Merge pull request #622 from talatu4sambo-cmyk/feature/510-rotate-refresh-tokens-on-use-staging

feat(auth): implement refresh token rotation on use

Author: Jambox11

prisma/schema.prisma

@@ -130,6 +130,9 @@ model User {
   /// Relation to user's spending limits
   spendingLimits SpendingLimit[]
 
+  /// Relation to user's refresh tokens
+  refreshTokens RefreshToken[]
+
   @@index([authId])
   @@index([authProvider])
   @@index([deletedAt])
@@ -736,6 +739,58 @@ model KeyRotationAuditLog {
   @@index([expiresAt])
 }
 
+/// Refresh token status lifecycle
+enum RefreshTokenStatus {
+  ACTIVE
+  ROTATED
+  REVOKED
+  EXPIRED
+}
+
+/// Refresh token management with automatic rotation on use
+model RefreshToken {
+  id String @id @default(uuid())
+
+  /// User reference
+  userId String
+  user   User   @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  /// Refresh token hash (never store plaintext)
+  tokenHash String @unique
+
+  /// Rotation chain - previous token in rotation sequence
+  previousTokenId String?
+  previousToken   RefreshToken?  @relation("TokenRotation", fields: [previousTokenId], references: [id])
+  nextToken       RefreshToken[] @relation("TokenRotation")
+
+  /// Token status
+  status RefreshTokenStatus @default(ACTIVE)
+
+  /// Expiration timestamp
+  expiresAt DateTime
+
+  /// Usage tracking
+  lastUsedAt DateTime?
+  usageCount Int @default(0)
+
+  /// Rotation tracking
+  rotatedAt DateTime?
+  rotatedReason String?
+
+  /// Revocation details
+  revokedAt DateTime?
+  revokeReason String?
+
+  /// Metadata
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  @@index([userId, status])
+  @@index([tokenHash])
+  @@index([expiresAt])
+  @@index([previousTokenId])
+}
+
 /// Transaction lifecycle states
 enum TransactionStatus {
   PENDING    // Transaction created but not yet submitted to network

src/auth/auth-orchestrator.controller.ts

@@ -41,7 +41,10 @@ import {
 @FeatureFlag('auth_api')
 @UseGuards(FeatureFlagGuard)
 export class AuthOrchestratorController {
-  constructor(private readonly authOrchestrator: AuthOrchestrator) {}
+  constructor(
+    private readonly authOrchestrator: AuthOrchestrator,
+    private readonly refreshTokenService: RefreshTokenService,
+  ) {}
 
   /**
    * Main authentication endpoint - handles both first-time and returning users.

src/auth/auth.module.ts

@@ -18,6 +18,7 @@ import { FeatureFlagGuard } from '../common/feature-flags/feature-flag.guard';
   controllers: [AuthOrchestratorController, AuthMetricsController],
   providers: [
     AuthOrchestrator,
+    RefreshTokenService,
     IdempotencyService,
     AuthRateLimitService,
     AuthRateLimitGuard,
@@ -27,6 +28,7 @@ import { FeatureFlagGuard } from '../common/feature-flags/feature-flag.guard';
   ],
   exports: [
     AuthOrchestrator,
+    RefreshTokenService,
     IdempotencyService,
     AuthRateLimitService,
     AuthRateLimitGuard,

src/auth/refresh-token.service.spec.ts

@@ -0,0 +1,141 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { RefreshTokenService } from './refresh-token.service';
+import { PrismaService } from '../common/prisma/prisma.service';
+import { RefreshTokenStatus } from '../generated/prisma';
+
+describe('RefreshTokenService', () => {
+  let service: RefreshTokenService;
+  let prismaMock: any;
+
+  beforeEach(async () => {
+    prismaMock = {
+      refreshToken: {
+        create: jest.fn(),
+        update: jest.fn(),
+        updateMany: jest.fn(),
+        findUnique: jest.fn(),
+        findMany: jest.fn(),
+      },
+    };
+
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        RefreshTokenService,
+        { provide: PrismaService, useValue: prismaMock },
+      ],
+    }).compile();
+
+    service = module.get<RefreshTokenService>(RefreshTokenService);
+  });
+
+  describe('createRefreshToken', () => {
+    it('should create a new refresh token', async () => {
+      const request = {
+        userId: 'user-1',
+        tokenHash: 'hash-1',
+        expiresAt: new Date(Date.now() + 7200000),
+      };
+
+      prismaMock.refreshToken.create.mockResolvedValue({
+        ...request,
+        status: RefreshTokenStatus.ACTIVE,
+        id: 'token-1',
+      });
+
+      const result = await service.createRefreshToken(request);
+      expect(result.status).toBe(RefreshTokenStatus.ACTIVE);
+      expect(prismaMock.refreshToken.create).toHaveBeenCalled();
+    });
+  });
+
+  describe('rotateRefreshToken', () => {
+    it('should rotate token and create new one', async () => {
+      const currentToken = {
+        id: 'token-1',
+        userId: 'user-1',
+        tokenHash: 'hash-1',
+        status: RefreshTokenStatus.ACTIVE,
+        expiresAt: new Date(Date.now() + 7200000),
+      };
+
+      prismaMock.refreshToken.findUnique.mockResolvedValue(currentToken);
+      prismaMock.refreshToken.update.mockResolvedValue({
+        ...currentToken,
+        status: RefreshTokenStatus.ROTATED,
+      });
+      prismaMock.refreshToken.create.mockResolvedValue({
+        id: 'token-2',
+        userId: 'user-1',
+        tokenHash: 'hash-2',
+        previousTokenId: 'token-1',
+        status: RefreshTokenStatus.ACTIVE,
+      });
+
+      const result = await service.rotateRefreshToken({
+        currentTokenHash: 'hash-1',
+        newTokenHash: 'hash-2',
+        expiresAt: new Date(Date.now() + 7200000),
+      });
+
+      expect(result.status).toBe(RefreshTokenStatus.ACTIVE);
+      expect(prismaMock.refreshToken.update).toHaveBeenCalled();
+      expect(prismaMock.refreshToken.create).toHaveBeenCalled();
+    });
+
+    it('should throw when current token is expired', async () => {
+      const expiredToken = {
+        id: 'token-1',
+        userId: 'user-1',
+        status: RefreshTokenStatus.ACTIVE,
+        expiresAt: new Date(Date.now() - 1000),
+      };
+
+      prismaMock.refreshToken.findUnique.mockResolvedValue(expiredToken);
+
+      await expect(
+        service.rotateRefreshToken({
+          currentTokenHash: 'hash-1',
+          newTokenHash: 'hash-2',
+          expiresAt: new Date(Date.now() + 7200000),
+        }),
+      ).rejects.toThrow('Current refresh token has expired');
+    });
+  });
+
+  describe('revokeRefreshToken', () => {
+    it('should revoke a refresh token', async () => {
+      const tokenHash = 'hash-1';
+      const revokedAt = new Date();
+
+      prismaMock.refreshToken.update.mockResolvedValue({
+        tokenHash,
+        status: RefreshTokenStatus.REVOKED,
+        revokedAt,
+      });
+
+      const result = await service.revokeRefreshToken({ tokenHash });
+      expect(result.status).toBe(RefreshTokenStatus.REVOKED);
+    });
+  });
+
+  describe('validateRefreshToken', () => {
+    it('should return null for invalid token', async () => {
+      prismaMock.refreshToken.findUnique.mockResolvedValue(null);
+      const result = await service.validateRefreshToken('invalid-hash');
+      expect(result).toBeNull();
+    });
+
+    it('should return valid token', async () => {
+      const token = {
+        id: 'token-1',
+        tokenHash: 'hash-1',
+        status: RefreshTokenStatus.ACTIVE,
+        expiresAt: new Date(Date.now() + 7200000),
+      };
+
+      prismaMock.refreshToken.findUnique.mockResolvedValue(token);
+      const result = await service.validateRefreshToken('hash-1');
+      expect(result).toEqual(token);
+    });
+  });
+});