Merge branch 'main' into security/118-domain-bound-signatures

Author: Marvelg256

context/progress-tracker.md

@@ -6,53 +6,33 @@ pure chore/docs commits). Direct pushes to main must also be logged here.
 
 ---
 
-## 2026-08-27
-
-- Closed the audit gaps on the #118 PR (#124): the legacy raw-nonce migration
-  window is now enforced at runtime, not just documented.
-  - Added `AUTH_LEGACY_SIGNATURES_SUNSET` (default `2026-10-31`): after the
-    cutoff, `verifyLegacyRawSignature()` rejects legacy raw-nonce signatures
-    with `AUTH_LEGACY_SIGNATURE_DISABLED` even while
-    `AUTH_ALLOW_LEGACY_RAW_SIGNATURES` is still true, so the replayable
-    scheme closes automatically on the sunset date — no manual ops action
-    required. Malformed sunset values fall back to the default rather than
-    silently disabling the cutoff.
-  - Strengthened the unit suite: the legacy-disabled regression test now
-    proves rejection happens before any signature verification (mock verify
-    returns true, assert it is never called), and new tests cover the
-    sunset cutoff (past sunset + flag true → rejected; future sunset +
-    flag true → accepted). Expired-envelope rejection unit test retained.
-  - Resolved the unresolved conflict markers (leftover wrong-repo
-    StepFi-Contracts content) that had been committed into
-    `context/progress-tracker.md`, which the PR audit flagged as merge
-    conflicts with the base branch.
-
-## 2026-08-25
-
-- Fixed cross-service signature replay (#118): `verifySignature()` now accepts
-  exactly one scheme per request and every accepted signature provably signs a
-  StepFi-bound challenge.
-  - `generateNonce()` issues a canonical challenge envelope (domain, address,
-    statement, uri, version, nonce, issuedAt, expirationTime,
-    networkPassphrase) and stores a SHA-256 digest of the exact message on the
-    nonce row (`issued_at`, `message_hash` columns via migration
-    `20260825000000_add_nonce_message_binding.sql`).
-  - Verification runs only against a message whose digest matches the stored
-    challenge hash (`AUTH_CHALLENGE_MISMATCH` otherwise), with strict
-    domain/URI/network/expiry checks (`AUTH_CHALLENGE_DOMAIN_MISMATCH`,
-    `AUTH_CHALLENGE_URI_MISMATCH`, `AUTH_CHALLENGE_NETWORK_MISMATCH`,
-    `AUTH_NONCE_EXPIRED`). The old "try raw, then 'Stellar Signing Key: '"
-    fallback is gone — the weakest format no longer defines the security floor.
-  - Browser wallets verify per SEP-53 (SHA-256 of
-    "Stellar Signed Message:\n" + envelope, `signatureType: 'sep0043'`);
-    native clients sign the envelope with raw Ed25519
-    (`signatureType: 'envelope'`).
-  - The legacy raw-nonce scheme is deprecated behind
-    `AUTH_ALLOW_LEGACY_RAW_SIGNATURES` (default true for mobile-client
-    compatibility) with a documented sunset date of **2026-10-31**; when
-    disabled, legacy requests fail with `AUTH_LEGACY_SIGNATURE_DISABLED`.
-  - Added `AUTH_CHALLENGE_DOMAIN` env (defaults to `API_URL` host); envelope
-    `uri` is derived from `API_URL` + `API_PREFIX`.
+## 2026-08-24
+
+- **Session families + refresh-token replay detection** (`sessions.family_id`
+  migration, `fam` claim in refresh JWTs). Replaying an already-rotated
+  refresh token now revokes every session in the family and writes a
+  `auth.refresh_token_reuse` audit log entry — previously the first
+  presenter of a stolen token won silently. Legacy tokens without a `fam`
+  claim keep the old `AUTH_SESSION_NOT_FOUND` response.
+- **Blocked-user enforcement on every request**: new
+  `UserStatusService` (in-memory TTL cache) consulted by `JwtStrategy`.
+  Documented staleness bound: **30 seconds** — a blocked wallet loses API
+  access within ~30s of being blocked instead of retaining access until its
+  access token expires (up to 15 minutes). Cache is per-instance and fails
+  open on DB errors to avoid locking out all users during a DB blip.
+- **Session cleanup cron** (`src/jobs/session-cleanup/`, hourly,
+  mirrors nonce-cleanup): deletes only rows with `expires_at` older than
+  1 hour; sessions no longer accumulate forever.
+- Tests: refresh-family rotation, replay → family-wide revocation + audit
+  event, blocked-user denial within TTL bound, cache expiry re-query,
+  cleanup job deletes-only-expired.
+
+## 2026-08-26
+
+- Fixed registration race conditions in `AuthService.register()` by eliminating application-side pre-checks (`findByWallet`, `checkUsernameExists`) and relying directly on DB-level UNIQUE constraints (`users.wallet_address`, `users.username`).
+- Added idempotent migration `20260826130000_ensure_users_unique_constraints.sql` to ensure unique indexes exist on `users.wallet_address` and `users.username`.
+- Updated `UsersRepository.createProfile()` to catch PostgreSQL unique constraint violation error `23505` and map to structured 409 `ConflictException` (`AUTH_WALLET_EXISTS`, `AUTH_USERNAME_TAKEN`).
+- Added cleanup handlers (`deleteAvatar`, `deleteUserById`) in `AuthService.register()` and `UsersRepository` to ensure failed registrations do not leave orphaned avatar files or partial user records.
 
 ## 2026-07-23
 

src/app.module.ts

@@ -21,6 +21,7 @@ import { IndexerModule } from './indexer/indexer.module';
 import { LoanPaymentReminderModule } from './jobs/loan-payment-reminder/loan-payment-reminder.module';
 import { TransactionStatusCheckerModule } from './jobs/transaction-status-checker/transaction-status-checker.module';
 import { NonceCleanupModule } from './jobs/nonce-cleanup/nonce-cleanup.module';
+import { SessionCleanupModule } from './jobs/session-cleanup/session-cleanup.module';
 import { SupabaseKeepAliveModule } from './jobs/supabase-keepalive/supabase-keepalive.module';
 import { StellarModule } from './stellar/stellar.module';
 import { LoggerModule } from './common/logger/logger.module';
@@ -62,6 +63,7 @@ import { AuditInterceptor } from './common/interceptors/audit.interceptor';
     LoanPaymentReminderModule,
     TransactionStatusCheckerModule,
     NonceCleanupModule,
+    SessionCleanupModule,
     SupabaseKeepAliveModule,
     StateReconciliationModule,
     CreditScoringModule,

src/auth/guards/roles.guard.ts

@@ -4,8 +4,10 @@ import {
   ExecutionContext,
   ForbiddenException,
   SetMetadata,
+  Optional,
 } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
+import { UserStatusService } from '../../modules/auth/user-status.service';
 
 export const ROLES_KEY = 'roles';
 
@@ -19,18 +21,22 @@ export const ROLES_KEY = 'roles';
 export const Roles = (...roles: string[]) => SetMetadata(ROLES_KEY, roles);
 
 /**
- * Enforces the role claim carried in the JWT (set by JwtStrategy.validate).
+ * Enforces user role authorization based on server truth in the datastore
+ * (resolved via short-TTL cached UserStatusService).
  *
  * - Routes without @Roles metadata are unaffected.
- * - Tokens without a role claim (role not chosen yet, or token issued
- *   before the role was set) are rejected with 403; the client must call
- *   POST /auth/refresh after setting a role to obtain the claim.
+ * - The JWT role claim is treated as a hint only; live datastore role is enforced.
+ * - Roles revoked or changed server-side take effect within USER_STATUS_CACHE_TTL_MS (30s)
+ *   or immediately upon cache invalidation.
  */
 @Injectable()
 export class RolesGuard implements CanActivate {
-  constructor(private readonly reflector: Reflector) {}
+  constructor(
+    private readonly reflector: Reflector,
+    @Optional() private readonly userStatusService?: UserStatusService,
+  ) {}
 
-  canActivate(context: ExecutionContext): boolean {
+  async canActivate(context: ExecutionContext): Promise<boolean> {
     const requiredRoles = this.reflector.getAllAndOverride<string[]>(ROLES_KEY, [
       context.getHandler(),
       context.getClass(),
@@ -41,7 +47,21 @@ export class RolesGuard implements CanActivate {
       .switchToHttp()
       .getRequest<{ user?: { wallet: string; role?: string | null } }>();
 
-    if (!user?.role || !requiredRoles.includes(user.role)) {
+    if (!user) {
+      throw new ForbiddenException({
+        code: 'AUTH_ROLE_FORBIDDEN',
+        message: `This action requires one of the following roles: ${requiredRoles.join(', ')}.`,
+      });
+    }
+
+    let currentRole: string | null = null;
+    if (this.userStatusService && user.wallet) {
+      currentRole = await this.userStatusService.getRole(user.wallet);
+    } else {
+      currentRole = user.role ?? null;
+    }
+
+    if (!currentRole || !requiredRoles.includes(currentRole)) {
       throw new ForbiddenException({
         code: 'AUTH_ROLE_FORBIDDEN',
         message: `This action requires one of the following roles: ${requiredRoles.join(', ')}. If you just selected your role, refresh your access token.`,
@@ -50,3 +70,5 @@ export class RolesGuard implements CanActivate {
     return true;
   }
 }
+
+

src/database/repositories/users.repository.ts

@@ -1,4 +1,4 @@
-import { Injectable, InternalServerErrorException } from '@nestjs/common';
+import { Injectable, InternalServerErrorException, ConflictException } from '@nestjs/common';
 import { SupabaseService } from '../supabase.client';
 import { UpdateUserDto } from '../../modules/users/dto/update-user.dto';
 
@@ -226,6 +226,31 @@ export class UsersRepository {
         return (data as { wallet_address: string; role: UserRole } | null) ?? null;
     }
 
+    /**
+     * Admin override: sets or resets the user's role regardless of whether a role was set previously.
+     * Returns the updated user row, or null if the user does not exist.
+     */
+    async forceSetRole(
+        wallet: string,
+        role: UserRole | null,
+    ): Promise<{ wallet_address: string; role: UserRole | null } | null> {
+        const { data, error } = await this.supabaseService
+            .getServiceRoleClient()
+            .from('users')
+            .update({ role })
+            .eq('wallet_address', wallet)
+            .select('wallet_address, role')
+            .maybeSingle();
+
+        if (error) {
+            throw new InternalServerErrorException({
+                code: 'DATABASE_ROLE_UPDATE_FAILED',
+                message: 'Failed to update user role.',
+            });
+        }
+        return (data as { wallet_address: string; role: UserRole | null } | null) ?? null;
+    }
+
     // --- REGISTRATION METHODS ---
 
     async checkUsernameExists(username: string): Promise<boolean> {
@@ -260,6 +285,19 @@ export class UsersRepository {
             .single();
 
         if (error) {
+            const combinedErr = `${error.code || ''} ${error.message || ''} ${error.details || ''} ${error.hint || ''}`;
+            if (error.code === '23505' || combinedErr.includes('duplicate key') || combinedErr.includes('unique constraint')) {
+                if (combinedErr.includes('username')) {
+                    throw new ConflictException({
+                        code: 'AUTH_USERNAME_TAKEN',
+                        message: 'Username is already taken.',
+                    });
+                }
+                throw new ConflictException({
+                    code: 'AUTH_WALLET_EXISTS',
+                    message: 'Wallet address is already registered.',
+                });
+            }
             throw new InternalServerErrorException({
                 code: 'DATABASE_INSERT_ERROR',
                 message: `Failed to create user profile: ${error.message}`,
@@ -292,4 +330,25 @@ export class UsersRepository {
         const { data } = client.storage.from('avatars').getPublicUrl(fileName);
         return data.publicUrl;
     }
+
+    async deleteAvatar(avatarUrl: string): Promise<void> {
+        try {
+            const fileName = avatarUrl.substring(avatarUrl.lastIndexOf('/') + 1);
+            if (!fileName) return;
+            const client = this.supabaseService.getServiceRoleClient();
+            await client.storage.from('avatars').remove([fileName]);
+        } catch {
+            // Ignore cleanup failures
+        }
+    }
+
+    async deleteUserById(id: string): Promise<void> {
+        try {
+            const client = this.supabaseService.getServiceRoleClient();
+            await client.from('users').delete().eq('id', id);
+        } catch {
+            // Ignore cleanup failures
+        }
+    }
 }
+

src/jobs/session-cleanup/session-cleanup.module.ts

@@ -0,0 +1,8 @@
+import { Module } from '@nestjs/common';
+import { SessionCleanupService } from './session-cleanup.service';
+import { SupabaseService } from '../../database/supabase.client';
+
+@Module({
+  providers: [SessionCleanupService, SupabaseService],
+})
+export class SessionCleanupModule {}

src/jobs/session-cleanup/session-cleanup.service.ts

@@ -0,0 +1,37 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Cron, CronExpression } from '@nestjs/schedule';
+import { SupabaseService } from '../../database/supabase.client';
+
+@Injectable()
+export class SessionCleanupService {
+  private readonly logger = new Logger(SessionCleanupService.name);
+
+  constructor(private readonly supabaseService: SupabaseService) {}
+
+  @Cron(CronExpression.EVERY_HOUR)
+  async cleanupExpiredSessions(): Promise<void> {
+    try {
+      const client = this.supabaseService.getServiceRoleClient();
+
+      // Delete only rows already past their expiry; the 1h grace window
+      // mirrors the nonce-cleanup pattern and keeps rows around long enough
+      // that an "expired" response (instead of "not found") is still
+      // possible for borderline requests.
+      const cutoff = new Date(Date.now() - 60 * 60 * 1000).toISOString();
+
+      const { error, count } = await client
+        .from('sessions')
+        .delete({ count: 'exact' })
+        .lt('expires_at', cutoff);
+
+      if (error) {
+        this.logger.error(`Failed to delete expired sessions: ${error.message}`);
+        throw error;
+      }
+
+      this.logger.log(`Deleted ${count ?? 0} expired sessions`);
+    } catch (error) {
+      this.logger.error('Session cleanup failed', error);
+    }
+  }
+}

src/modules/admin/admin-roles.controller.ts

@@ -0,0 +1,71 @@
+import {
+  Controller,
+  Post,
+  Param,
+  Body,
+  NotFoundException,
+  UseGuards,
+  UseInterceptors,
+  HttpCode,
+  HttpStatus,
+} from '@nestjs/common';
+import { ApiTags, ApiOperation, ApiResponse, ApiBearerAuth, ApiParam } from '@nestjs/swagger';
+import { JwtAuthGuard } from '../../common/guards/jwt-auth.guard';
+import { AdminGuard } from '../../auth/guards/admin.guard';
+import { AuditInterceptor } from '../../common/interceptors/audit.interceptor';
+import { AuditAction } from '../../common/decorators/audit-action.decorator';
+import { UsersRepository } from '../../database/repositories/users.repository';
+import { UserStatusService } from '../auth/user-status.service';
+import { AdminResetRoleDto } from './dto/admin-reset-role.dto';
+
+@ApiTags('admin')
+@Controller('admin')
+@UseGuards(JwtAuthGuard, AdminGuard)
+@ApiBearerAuth()
+@UseInterceptors(AuditInterceptor)
+export class AdminRolesController {
+  constructor(
+    private readonly usersRepository: UsersRepository,
+    private readonly userStatusService: UserStatusService,
+  ) {}
+
+  @Post('users/:wallet/role/reset')
+  @HttpCode(HttpStatus.OK)
+  @AuditAction('admin_users', 'RESET_USER_ROLE')
+  @ApiOperation({
+    summary: 'Reset or override user role (Admin only)',
+    description:
+      'Allows admins to reset a user\'s permanent role back to null or override it with a specific role. ' +
+      'Immediately invalidates the user\'s server-side status cache and logs an audit event.',
+  })
+  @ApiParam({ name: 'wallet', description: 'Target user wallet address' })
+  @ApiResponse({ status: 200, description: 'Role reset/updated successfully' })
+  @ApiResponse({ status: 401, description: 'Unauthorized — missing or invalid JWT' })
+  @ApiResponse({ status: 403, description: 'Forbidden — wallet is not in ADMIN_WALLETS' })
+  @ApiResponse({ status: 404, description: 'User not found' })
+  async resetUserRole(
+    @Param('wallet') wallet: string,
+    @Body() dto?: AdminResetRoleDto,
+  ) {
+    const targetRole = dto?.role ?? null;
+    const updated = await this.usersRepository.forceSetRole(wallet, targetRole);
+
+    if (!updated) {
+      throw new NotFoundException({
+        code: 'USERS_NOT_FOUND',
+        message: 'User not found.',
+      });
+    }
+
+    this.userStatusService.invalidate(wallet);
+
+    return {
+      success: true,
+      data: {
+        wallet: updated.wallet_address,
+        role: updated.role,
+      },
+      message: 'User role updated successfully.',
+    };
+  }
+}

src/modules/admin/admin.module.ts

@@ -1,11 +1,15 @@
 import { Module } from '@nestjs/common';
 import { AuditController } from './audit.controller';
 import { AuditService } from './audit.service';
+import { AdminRolesController } from './admin-roles.controller';
 import { SupabaseService } from '../../database/supabase.client';
+import { UsersRepository } from '../../database/repositories/users.repository';
+import { UserStatusService } from '../auth/user-status.service';
+import { AdminGuard } from '../../auth/guards/admin.guard';
 
 @Module({
-  controllers: [AuditController],
-  providers: [AuditService, SupabaseService],
-  exports: [AuditService],
+  controllers: [AuditController, AdminRolesController],
+  providers: [AuditService, SupabaseService, UsersRepository, UserStatusService, AdminGuard],
+  exports: [AuditService, UserStatusService],
 })
 export class AdminModule {}