@everystack/auth 0.1.0 → 0.2.0

package/src/refresh.ts

@@ -1,20 +1,38 @@
 /**
- * Database-backed refresh token rotation using auth.sessions.
+ * Database-backed refresh token rotation using auth.refresh_tokens.
  *
  * Tokens are random strings (not JWTs). Only SHA-256 hashes are stored.
- * Each token is one-time use — on refresh, the old token is deleted and a new one created.
- * Tokens are grouped by `familyId` (stored in data JSONB) for theft detection.
+ * Each token is one-time use — on refresh, the old token is marked 'consumed'
+ * and a new one is created in the same family.
  *
- * Refresh tokens are stored as sessions with domain='auth', type='refresh'.
+ * Reuse detection (RFC 6819): if a consumed token is presented, the entire
+ * rotation family is revoked. This detects token theft after the fact.
  *
- * Usage: Pass a `sessions` table reference to `createAuthHandlers()`.
+ * Per-user ceiling: max 10 active families per user. Oldest revoked on overflow.
+ *
+ * Usage: Pass a `refreshTokens` table reference to `createAuthHandlers()`.
  * If not provided, the existing JWT-based refresh behavior is preserved.
+ *
+ * Known limitation: The JS path cannot do SELECT FOR UPDATE through Drizzle.
+ * The consumed-token reuse detection mitigates race conditions. For production
+ * deployments needing full atomicity, use the PostgreSQL path (mode: 'postgres').
  */
 
-import { and, eq, lt, sql } from 'drizzle-orm';
+import { and, eq, lt, sql, asc, inArray } from 'drizzle-orm';
 
 const REFRESH_TOKEN_BYTES = 32;
-const REFRESH_TOKEN_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+const REFRESH_TOKEN_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+const MAX_FAMILIES_PER_USER = 10;
+
+/**
+ * Options for creating a refresh token with session metadata.
+ */
+export interface RefreshTokenOptions {
+  repositoryId?: string;
+  ipAddress?: string;
+  userAgent?: string;
+  deviceId?: string;
+}
 
 /**
  * Generate a cryptographically random token string.
@@ -40,13 +58,17 @@ export async function hashToken(token: string): Promise<string> {
 }
 
 /**
- * Create a new refresh token, store its hash in the sessions table,
+ * Create a new refresh token, store its hash in the refresh_tokens table,
  * and return the raw token to send to the client.
  *
+ * Enforces a per-user ceiling of MAX_FAMILIES_PER_USER active families.
+ * When exceeded, the oldest family is revoked to make room.
+ *
  * @param db - Drizzle database instance
- * @param table - The sessions table reference
+ * @param table - The refresh_tokens table reference
  * @param userId - The user ID to associate with this token
  * @param familyId - Optional family ID (inherits on rotation, new UUID if omitted)
+ * @param options - Optional session metadata (IP, user agent, device)
  * @returns Raw token string and family ID
  */
 export async function createRefreshToken(
@@ -54,30 +76,56 @@ export async function createRefreshToken(
   table: any,
   userId: string,
   familyId?: string,
+  options?: RefreshTokenOptions,
 ): Promise<{ token: string; familyId: string }> {
-  // Clean up expired refresh sessions for this user (prevents accumulation)
+  const repoId = options?.repositoryId ?? null;
+
+  // Build scoping conditions: always (userId), optionally (repositoryId)
+  const scopeConditions = repoId
+    ? and(eq(table.userId, userId), eq(table.repositoryId, repoId))
+    : eq(table.userId, userId);
+
+  // Clean up expired tokens for this user (prevents accumulation)
   await db.delete(table).where(
-    and(
-      eq(table.userId, userId),
-      eq(table.domain, 'auth'),
-      eq(table.type, 'refresh'),
-      lt(table.expiresAt, new Date()),
-    ),
+    and(scopeConditions, lt(table.expiresAt, new Date())),
   );
 
+  // Enforce per-user family ceiling (only when creating a new family, not rotating)
+  if (!familyId) {
+    const activeFamilies = await db
+      .selectDistinct({ familyId: table.familyId, createdAt: sql`MIN(${table.createdAt})` })
+      .from(table)
+      .where(and(scopeConditions, eq(table.status, 'active')))
+      .groupBy(table.familyId)
+      .orderBy(asc(sql`MIN(${table.createdAt})`));
+
+    if (activeFamilies.length >= MAX_FAMILIES_PER_USER) {
+      // Revoke the oldest families to make room
+      const excessCount = activeFamilies.length - MAX_FAMILIES_PER_USER + 1;
+      const familyIdsToRevoke = activeFamilies
+        .slice(0, excessCount)
+        .map((f: any) => f.familyId);
+      await db.delete(table).where(
+        and(scopeConditions, inArray(table.familyId, familyIdsToRevoke)),
+      );
+    }
+  }
+
   const token = generateToken();
   const tokenHash = await hashToken(token);
   const family = familyId ?? crypto.randomUUID();
   const expiresAt = new Date(Date.now() + REFRESH_TOKEN_TTL_MS);
 
   await db.insert(table).values({
-    domain: 'auth',
-    type: 'refresh',
-    status: 'active',
+    repositoryId: repoId,
     userId,
     tokenHash,
+    familyId: family,
+    status: 'active',
+    ipAddress: options?.ipAddress ?? null,
+    userAgent: options?.userAgent ?? null,
+    deviceId: options?.deviceId ?? null,
     expiresAt,
-    data: { familyId: family },
   });
 
   return { token, familyId: family };
@@ -85,75 +133,99 @@ export async function createRefreshToken(
 
 /**
  * Validate a refresh token and rotate it.
- * Deletes the old token and creates a new one in the same family.
+ * Marks the old token as consumed and creates a new one in the same family.
  *
  * @throws {TokenError} If token is invalid, expired, or already used
- * @returns User ID, new raw token, and family ID
+ * @returns User ID, new raw token, family ID, and device ID
  */
 export async function rotateRefreshToken(
   db: any,
   table: any,
   rawToken: string,
-): Promise<{ userId: string; token: string; familyId: string }> {
+  options?: {
+    /** Verify user is still valid. Return false to reject refresh. */
+    checkUser?: (userId: string) => Promise<boolean>;
+    /** IP address for the new token row. */
+    ipAddress?: string;
+    /** User agent for the new token row. */
+    userAgent?: string;
+  },
+): Promise<{ userId: string; token: string; familyId: string; deviceId?: string }> {
   const tokenHash = await hashToken(rawToken);
 
   const [existing] = await db
     .select()
     .from(table)
-    .where(and(
-      eq(table.tokenHash, tokenHash),
-      eq(table.domain, 'auth'),
-      eq(table.type, 'refresh'),
-    ))
+    .where(eq(table.tokenHash, tokenHash))
     .limit(1);
 
   if (!existing) {
     throw new TokenError('invalid_token', 'Refresh token not found');
   }
 
+  // Reuse detection: if token was already consumed, this is potential theft
+  if (existing.status === 'consumed') {
+    await revokeTokenFamily(db, table, existing.familyId);
+    // Also delete the consumed token itself (it may not match the family query if already cleaned)
+    await db.delete(table).where(eq(table.id, existing.id));
+    throw new TokenError('token_reused', 'Refresh token reuse detected — family revoked');
+  }
+
   // Check expiry
   if (new Date(existing.expiresAt) < new Date()) {
     await db.delete(table).where(eq(table.id, existing.id));
     throw new TokenError('token_expired', 'Refresh token has expired');
   }
 
-  // Delete old token (one-time use)
-  await db.delete(table).where(eq(table.id, existing.id));
+  // Check user state if callback provided
+  if (options?.checkUser) {
+    const userValid = await options.checkUser(existing.userId);
+    if (!userValid) {
+      await revokeAllRefreshTokens(db, table, existing.userId);
+      throw new TokenError('invalid_token', 'User account is disabled or deleted');
+    }
+  }
 
-  // Read familyId from data JSONB
-  const existingFamilyId = (existing.data as Record<string, unknown>)?.familyId as string | undefined;
+  // Mark old token as consumed (instead of deleting) for reuse detection
+  await db.update(table).set({ status: 'consumed' }).where(eq(table.id, existing.id));
 
-  // Issue new token in the same family
+  // Issue new token in the same family (inherit repositoryId from original)
   const result = await createRefreshToken(
     db,
     table,
     existing.userId,
-    existingFamilyId,
+    existing.familyId,
+    {
+      repositoryId: existing.repositoryId ?? undefined,
+      ipAddress: options?.ipAddress,
+      userAgent: options?.userAgent,
+      deviceId: existing.deviceId ?? undefined,
+    },
   );
 
   return {
     userId: existing.userId,
     token: result.token,
     familyId: result.familyId,
+    deviceId: existing.deviceId ?? undefined,
   };
 }
 
 /**
  * Revoke all refresh tokens for a user.
+ * When repositoryId is provided, only tokens for that repository are revoked.
  * Use on: logout everywhere, password change, account compromise.
  */
 export async function revokeAllRefreshTokens(
   db: any,
   table: any,
   userId: string,
+  repositoryId?: string,
 ): Promise<void> {
-  await db.delete(table).where(
-    and(
-      eq(table.userId, userId),
-      eq(table.domain, 'auth'),
-      eq(table.type, 'refresh'),
-    ),
-  );
+  const conditions = repositoryId
+    ? and(eq(table.userId, userId), eq(table.repositoryId, repositoryId))
+    : eq(table.userId, userId);
+  await db.delete(table).where(conditions);
 }
 
 /**
@@ -165,29 +237,21 @@ export async function revokeTokenFamily(
   table: any,
   familyId: string,
 ): Promise<void> {
-  await db.delete(table).where(
-    and(
-      eq(table.domain, 'auth'),
-      eq(table.type, 'refresh'),
-      sql`${table.data}->>'familyId' = ${familyId}`,
-    ),
-  );
+  await db.delete(table).where(eq(table.familyId, familyId));
 }
 
 /**
- * Delete all expired refresh sessions. Call periodically (e.g., daily cron).
+ * Delete all expired and stale consumed tokens.
+ * Call periodically (e.g., daily cron via pg_cron).
+ *
+ * Consumed tokens are kept for reuse detection but only need to persist
+ * for a reasonable window (default: until their original expiry).
  */
 export async function cleanupExpiredTokens(
   db: any,
   table: any,
 ): Promise<void> {
-  await db.delete(table).where(
-    and(
-      eq(table.domain, 'auth'),
-      eq(table.type, 'refresh'),
-      lt(table.expiresAt, new Date()),
-    ),
-  );
+  await db.delete(table).where(lt(table.expiresAt, new Date()));
 }
 
 /**
@@ -195,7 +259,7 @@ export async function cleanupExpiredTokens(
  */
 export class TokenError extends Error {
   constructor(
-    public readonly code: 'invalid_token' | 'token_expired',
+    public readonly code: 'invalid_token' | 'token_expired' | 'token_reused',
     message: string,
   ) {
     super(message);