Merge pull request #1 from Jambox11/feature/backend-auth-blacklist-tickets-soft-delete-queue-concurrency

Backend auth, ticket assignment, soft-delete, queue concurrency

Author: Jambox11

backend/docs/queue-concurrency.md

@@ -0,0 +1,36 @@
+# BullMQ Per-Queue Concurrency Configuration
+
+Each queue worker can be configured with a specific concurrency level to control how many jobs are processed in parallel.
+
+## Configuration
+
+Set `QUEUE_CONCURRENCY_MAP` as a comma-separated list of `queue-name=N` pairs:
+
+```
+QUEUE_CONCURRENCY_MAP=tx-submit=1,claim-events=5,claim-payouts=3
+```
+
+## Default Values
+
+| Queue | Default Concurrency | Rationale |
+|-------|---------------------|-----------|
+| `tx-submit` | 1 | Nonce-safe: serializes Stellar XDR submission to prevent nonce race conditions |
+| `claim-events` | 5 | Typical event indexing workload |
+| `claim-payouts` | 3 | Moderate payout processing capacity |
+
+## Observability
+
+Active worker count per queue is exposed as `bullmq_queue_active_workers` gauge in Prometheus:
+
+```
+bullmq_queue_active_workers{queue="tx-submit"} 1
+bullmq_queue_active_workers{queue="claim-events"} 4
+bullmq_queue_active_workers{queue="claim-payouts"} 2
+```
+
+## Tuning
+
+- **Increase concurrency** for I/O-bound jobs (database, RPC calls) that can safely parallelize
+- **Decrease concurrency** for CPU-bound jobs or to reduce resource contention
+- **Monitor active worker gauge** in Grafana to detect saturation or underutilization
+- **tx-submit must remain at 1** to prevent Soroban account nonce conflicts across transactions

backend/prisma/schema.prisma

@@ -284,12 +284,15 @@ model SupportTicket {
   /// One-way hash of submitter IP for spam detection (no raw IP stored).
   ipHash           String?
   status           TicketStatus @default(OPEN)
+  /// Staff member assigned to handle this ticket (null = unassigned).
+  assignedTo       String?      @map("assigned_to")
   /// Set once when the first staff status update is recorded.
   firstRespondedAt DateTime?    @map("first_responded_at")
   createdAt        DateTime     @default(now())
   updatedAt        DateTime     @updatedAt
 
   @@index([status])
+  @@index([assignedTo])
   @@index([createdAt])
   @@index([firstRespondedAt])
   @@map("support_tickets")

backend/src/admin/admin.controller.ts

@@ -43,6 +43,8 @@ import { AdminStatsService } from './admin-stats.service';
 import { AdminAnalyticsService } from './admin-analytics.service';
 import { PrismaService } from '../prisma/prisma.service';
 import { SorobanService } from '../rpc/soroban.service';
+import { TokenBlacklistService } from '../auth/token-blacklist.service';
+import { SupportService } from '../support/support.service';
 
 class BatchRegisterVotersDto {
   @IsArray()
@@ -76,6 +78,15 @@ class SetClaimSeverityDto {
   severity!: ClaimSeverity;
 }
 
+class RevokeTokenDto {
+  @IsString() jti!: string;
+  @IsInt() expiresAt!: number;
+}
+
+class AssignTicketDto {
+  @IsOptional() @IsString() assignee?: string | null;
+}
+
 type AdminRequest = Request & {
   user?: {
     walletAddress?: string;
@@ -111,6 +122,8 @@ export class AdminController {
     private readonly adminAnalyticsService: AdminAnalyticsService,
     private readonly prisma: PrismaService,
     private readonly sorobanService: SorobanService,
+    private readonly tokenBlacklist: TokenBlacklistService,
+    private readonly supportService: SupportService,
   ) {}
 
   // ── Governance: Voters ────────────────────────────────────────────
@@ -926,4 +939,68 @@ export class AdminController {
     });
     return result;
   }
+
+  // ── Auth: Token Management ─────────────────────────────────────────
+
+  /**
+   * POST /admin/auth/revoke
+   *
+   * Revoke a JWT token immediately by adding to Redis blacklist.
+   * Token remains blacklisted until its expiry time.
+   */
+  @Post('auth/revoke')
+  @HttpCode(HttpStatus.NO_CONTENT)
+  @ApiOperation({ summary: 'Revoke a JWT token' })
+  async revokeToken(@Body() dto: RevokeTokenDto, @Req() req: AdminRequest) {
+    if (!dto.jti || dto.jti.length === 0) {
+      throw new BadRequestException('jti must be a non-empty string');
+    }
+    if (!Number.isInteger(dto.expiresAt) || dto.expiresAt <= 0) {
+      throw new BadRequestException('expiresAt must be a positive integer (Unix timestamp)');
+    }
+
+    await this.tokenBlacklist.revokeToken(dto.jti, dto.expiresAt);
+
+    const actor = req.adminIdentity?.staffId || req.adminIdentity?.email || 'unknown';
+    await this.auditService.write({
+      actor,
+      action: 'auth_token_revoke',
+      payload: { jti: dto.jti },
+      ipAddress: req.ip,
+    });
+  }
+
+  // ── Support: Ticket Management ─────────────────────────────────────
+
+  /**
+   * GET /admin/support/tickets
+   *
+   * List all support tickets with optional filtering.
+   */
+  @Get('support/tickets')
+  @MinAdminRole('viewer')
+  @ApiOperation({ summary: 'List support tickets' })
+  async listSupportTickets(
+    @Query('limit', new ParseIntPipe({ optional: true })) limit?: number,
+    @Query('offset', new ParseIntPipe({ optional: true })) offset?: number,
+    @Query('assignedTo') assignedTo?: string,
+  ) {
+    return this.supportService.listTickets(limit || 50, offset || 0, assignedTo);
+  }
+
+  /**
+   * PATCH /admin/support/tickets/:id/assign
+   *
+   * Assign a support ticket to a staff member or unassign it.
+   */
+  @Patch('support/tickets/:id/assign')
+  @ApiOperation({ summary: 'Assign support ticket to staff member' })
+  async assignSupportTicket(
+    @Param('id') ticketId: string,
+    @Body() dto: AssignTicketDto,
+    @Req() req: AdminRequest,
+  ) {
+    const actor = req.adminIdentity?.staffId || req.adminIdentity?.email || 'unknown';
+    return this.supportService.assignTicket(ticketId, dto.assignee ?? null, actor, req.ip);
+  }
 }

backend/src/auth/auth.module.ts

@@ -8,6 +8,7 @@ import { NonceService } from './nonce.service';
 import { RefreshTokenService } from './refresh-token.service';
 import { AuthController } from './auth.controller';
 import { AuthIdentityService } from './auth-identity.service';
+import { TokenBlacklistService } from './token-blacklist.service';
 import { CacheModule } from '../cache/cache.module';
 
 @Module({
@@ -24,7 +25,7 @@ import { CacheModule } from '../cache/cache.module';
     }),
   ],
   controllers: [AuthController],
-  providers: [JwtStrategy, WalletAuthService, NonceService, RefreshTokenService, AuthIdentityService],
-  exports: [PassportModule, JwtModule, AuthIdentityService],
+  providers: [JwtStrategy, WalletAuthService, NonceService, RefreshTokenService, AuthIdentityService, TokenBlacklistService],
+  exports: [PassportModule, JwtModule, AuthIdentityService, TokenBlacklistService],
 })
 export class AuthModule {}

backend/src/auth/strategies/jwt.strategy.spec.ts

@@ -0,0 +1,95 @@
+import { UnauthorizedException } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { JwtStrategy, JwtPayload } from './jwt.strategy';
+import { TokenBlacklistService } from '../token-blacklist.service';
+
+describe('JwtStrategy', () => {
+  let strategy: JwtStrategy;
+  let mockConfigService: Partial<ConfigService>;
+  let mockBlacklistService: Partial<TokenBlacklistService>;
+
+  beforeEach(() => {
+    mockConfigService = {
+      get: jest.fn((key: string) => {
+        if (key === 'JWT_SECRET') return 'test-secret';
+        return undefined;
+      }),
+    };
+    mockBlacklistService = {
+      isBlacklisted: jest.fn().mockResolvedValue(false),
+    };
+    strategy = new JwtStrategy(
+      mockConfigService as ConfigService,
+      mockBlacklistService as TokenBlacklistService,
+    );
+  });
+
+  it('validate accepts valid payload without jti', async () => {
+    const payload: JwtPayload = {
+      sub: 'user123',
+      walletAddress: 'GXXX...',
+    };
+
+    const result = await strategy.validate(payload);
+
+    expect(result.walletAddress).toBe('GXXX...');
+    expect(mockBlacklistService.isBlacklisted).not.toHaveBeenCalled();
+  });
+
+  it('validate rejects payload without walletAddress', async () => {
+    const payload = { sub: 'user123' } as JwtPayload;
+
+    await expect(strategy.validate(payload)).rejects.toThrow(UnauthorizedException);
+  });
+
+  it('validate checks blacklist when jti is present', async () => {
+    const payload: JwtPayload = {
+      sub: 'user123',
+      walletAddress: 'GXXX...',
+      jti: 'token-id-123',
+    };
+
+    await strategy.validate(payload);
+
+    expect(mockBlacklistService.isBlacklisted).toHaveBeenCalledWith('token-id-123');
+  });
+
+  it('validate rejects blacklisted tokens', async () => {
+    (mockBlacklistService.isBlacklisted as jest.Mock).mockResolvedValueOnce(true);
+    const payload: JwtPayload = {
+      sub: 'user123',
+      walletAddress: 'GXXX...',
+      jti: 'blacklisted-token-id',
+    };
+
+    await expect(strategy.validate(payload)).rejects.toThrow(
+      new UnauthorizedException('Token has been revoked'),
+    );
+  });
+
+  it('validate accepts non-blacklisted tokens with jti', async () => {
+    (mockBlacklistService.isBlacklisted as jest.Mock).mockResolvedValueOnce(false);
+    const payload: JwtPayload = {
+      sub: 'user123',
+      walletAddress: 'GXXX...',
+      jti: 'valid-token-id',
+    };
+
+    const result = await strategy.validate(payload);
+
+    expect(result.walletAddress).toBe('GXXX...');
+  });
+
+  it('validate passes through iat and exp timestamps', async () => {
+    const payload: JwtPayload = {
+      sub: 'user123',
+      walletAddress: 'GXXX...',
+      iat: 1234567890,
+      exp: 1234567890 + 3600,
+    };
+
+    const result = await strategy.validate(payload);
+
+    expect(result.walletAddress).toBe('GXXX...');
+  });
+});

backend/src/auth/strategies/jwt.strategy.ts

@@ -2,17 +2,22 @@ import { Injectable, UnauthorizedException } from '@nestjs/common';
 import { PassportStrategy } from '@nestjs/passport';
 import { ExtractJwt, Strategy } from 'passport-jwt';
 import { ConfigService } from '@nestjs/config';
+import { TokenBlacklistService } from '../token-blacklist.service';
 
 export interface JwtPayload {
   sub: string; // Wallet address
   walletAddress: string;
+  jti?: string; // JWT ID for revocation
   iat?: number;
   exp?: number;
 }
 
 @Injectable()
 export class JwtStrategy extends PassportStrategy(Strategy) {
-  constructor(private readonly configService: ConfigService) {
+  constructor(
+    private readonly configService: ConfigService,
+    private readonly blacklist: TokenBlacklistService,
+  ) {
     const primary = configService.get<string>('JWT_SECRET') ?? ''
 
     super({
@@ -26,6 +31,14 @@ export class JwtStrategy extends PassportStrategy(Strategy) {
     if (!payload.walletAddress) {
       throw new UnauthorizedException('Invalid token payload');
     }
+
+    if (payload.jti) {
+      const isBlacklisted = await this.blacklist.isBlacklisted(payload.jti);
+      if (isBlacklisted) {
+        throw new UnauthorizedException('Token has been revoked');
+      }
+    }
+
     return { walletAddress: payload.walletAddress };
   }
 }

backend/src/auth/token-blacklist.service.spec.ts

@@ -0,0 +1,79 @@
+import { TokenBlacklistService } from './token-blacklist.service';
+import { RedisService } from '../cache/redis.service';
+
+describe('TokenBlacklistService', () => {
+  let service: TokenBlacklistService;
+  let redisService: Partial<RedisService>;
+  let mockRedisClient: Record<string, jest.Mock>;
+
+  beforeEach(() => {
+    mockRedisClient = {
+      setex: jest.fn().mockResolvedValue('OK'),
+      exists: jest.fn().mockResolvedValue(0),
+    };
+    redisService = {
+      client: mockRedisClient as any,
+    };
+    service = new TokenBlacklistService(redisService as RedisService);
+  });
+
+  it('blacklistToken sets key with TTL in Redis', async () => {
+    await service.blacklistToken('test-jti', 3600);
+
+    expect(mockRedisClient.setex).toHaveBeenCalledWith('token:blacklist:test-jti', 3600, '1');
+  });
+
+  it('blacklistToken ignores tokens with 0 or negative TTL', async () => {
+    await service.blacklistToken('expired-jti', 0);
+    await service.blacklistToken('very-expired-jti', -100);
+
+    expect(mockRedisClient.setex).not.toHaveBeenCalled();
+  });
+
+  it('isBlacklisted returns true when token exists in Redis', async () => {
+    mockRedisClient.exists.mockResolvedValueOnce(1);
+
+    const result = await service.isBlacklisted('blacklisted-jti');
+
+    expect(result).toBe(true);
+    expect(mockRedisClient.exists).toHaveBeenCalledWith('token:blacklist:blacklisted-jti');
+  });
+
+  it('isBlacklisted returns false when token not in Redis', async () => {
+    mockRedisClient.exists.mockResolvedValueOnce(0);
+
+    const result = await service.isBlacklisted('not-blacklisted-jti');
+
+    expect(result).toBe(false);
+  });
+
+  it('revokeToken calculates TTL from expiry timestamp', async () => {
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const expiresAt = nowSeconds + 7200; // expires in 2 hours
+    const expectedTtl = 7200;
+
+    await service.revokeToken('jti-to-revoke', expiresAt);
+
+    const calls = mockRedisClient.setex.mock.calls[0];
+    expect(calls[0]).toBe('token:blacklist:jti-to-revoke');
+    expect(calls[1]).toBe(expectedTtl);
+    expect(calls[2]).toBe('1');
+  });
+
+  it('revokeToken uses 0 TTL for already-expired tokens', async () => {
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const expiresAt = nowSeconds - 100; // expired 100 seconds ago
+
+    await service.revokeToken('already-expired-jti', expiresAt);
+
+    expect(mockRedisClient.setex).not.toHaveBeenCalled();
+  });
+
+  it('blacklistToken uses correct key prefix', async () => {
+    await service.blacklistToken('my-jti', 100);
+
+    const key = mockRedisClient.setex.mock.calls[0][0];
+    expect(key).toMatch(/^token:blacklist:/);
+    expect(key).toContain('my-jti');
+  });
+});