@revealui/auth 0.2.0 → 0.3.0

package/dist/server/session.js

@@ -7,16 +7,61 @@
 import { logger } from '@revealui/core/observability/logger';
 import { getClient } from '@revealui/db/client';
 import { sessions, users } from '@revealui/db/schema';
-import { and, eq, gt } from 'drizzle-orm';
+import { and, eq, gt, isNull } from 'drizzle-orm';
 import { hashToken } from '../utils/token.js';
 import { DatabaseError, TokenError } from './errors.js';
+const DEFAULT_SESSION_BINDING = {
+    enforceUserAgent: true,
+    enforceIp: false,
+    warnOnIpChange: true,
+};
+let sessionBindingConfig = { ...DEFAULT_SESSION_BINDING };
+/** Override session binding behaviour (useful for tests or strict deployments). */
+export function configureSessionBinding(overrides) {
+    sessionBindingConfig = { ...DEFAULT_SESSION_BINDING, ...overrides };
+}
+/** Reset to defaults (for tests). */
+export function resetSessionBindingConfig() {
+    sessionBindingConfig = { ...DEFAULT_SESSION_BINDING };
+}
+/**
+ * Validate that the current request context matches the session's stored
+ * binding values (IP address, user-agent).
+ *
+ * @returns `null` when the session is valid, or a reason string when it should
+ *          be invalidated.
+ */
+export function validateSessionBinding(session, ctx) {
+    // User-agent enforcement
+    if (sessionBindingConfig.enforceUserAgent &&
+        ctx.userAgent &&
+        session.userAgent &&
+        ctx.userAgent !== session.userAgent) {
+        return 'user-agent mismatch';
+    }
+    // IP enforcement / warning
+    if (ctx.ipAddress && session.ipAddress && ctx.ipAddress !== session.ipAddress) {
+        if (sessionBindingConfig.enforceIp) {
+            return 'ip-address mismatch';
+        }
+        if (sessionBindingConfig.warnOnIpChange) {
+            logger.warn('Session IP changed', {
+                sessionId: session.id,
+                storedIp: session.ipAddress,
+                currentIp: ctx.ipAddress,
+            });
+        }
+    }
+    return null;
+}
 /**
  * Get session from request headers (cookie)
  *
  * @param headers - Request headers containing cookies
+ * @param requestContext - Optional IP / user-agent for session binding validation
  * @returns Session data with user, or null if invalid/expired
  */
-export async function getSession(headers) {
+export async function getSession(headers, requestContext) {
     try {
         const cookieHeader = headers.get('cookie');
         if (!cookieHeader) {
@@ -61,10 +106,32 @@ export async function getSession(headers) {
         if (!session) {
             return null;
         }
+        // Session binding validation (IP / user-agent)
+        if (requestContext) {
+            const bindingError = validateSessionBinding(session, requestContext);
+            if (bindingError) {
+                logger.warn('Session binding violation — invalidating session', {
+                    sessionId: session.id,
+                    reason: bindingError,
+                });
+                // Delete the compromised session
+                try {
+                    await db.delete(sessions).where(eq(sessions.id, session.id));
+                }
+                catch {
+                    logger.error('Failed to delete session after binding violation');
+                }
+                return null;
+            }
+        }
         // Get user data
         let user;
         try {
-            const result = await db.select().from(users).where(eq(users.id, session.userId)).limit(1);
+            const result = await db
+                .select()
+                .from(users)
+                .where(and(eq(users.id, session.userId), isNull(users.deletedAt)))
+                .limit(1);
             user = result[0];
         }
         catch (error) {
@@ -128,9 +195,11 @@ export async function createSession(userId, options) {
             logger.error('Error generating session token');
             throw new TokenError('Failed to generate session token');
         }
-        // Calculate expiration (7 days for persistent, 1 day for regular)
-        const expiresAt = new Date();
-        expiresAt.setDate(expiresAt.getDate() + (options?.persistent ? 7 : 1));
+        // Calculate expiration (custom override, 7 days for persistent, 1 day for regular)
+        const expiresAt = options?.expiresAt ?? new Date();
+        if (!options?.expiresAt) {
+            expiresAt.setDate(expiresAt.getDate() + (options?.persistent ? 7 : 1));
+        }
         // Create session in database
         let session;
         try {
@@ -145,6 +214,7 @@ export async function createSession(userId, options) {
                 userAgent: options?.userAgent,
                 ipAddress: options?.ipAddress,
                 lastActivityAt: new Date(),
+                metadata: options?.metadata ?? null,
             })
                 .returning();
             session = result[0];
@@ -171,6 +241,55 @@ export async function createSession(userId, options) {
         throw new DatabaseError('Unexpected error creating session', err);
     }
 }
+/**
+ * Rotate a user's session to prevent session fixation attacks.
+ *
+ * Deletes the old session (by token hash) or all sessions for the user,
+ * then creates a fresh session with a new token.
+ *
+ * @param userId - User ID to rotate sessions for
+ * @param options - Rotation options
+ * @returns New session token and session data
+ */
+export async function rotateSession(userId, options) {
+    try {
+        let db;
+        try {
+            db = getClient();
+        }
+        catch (error) {
+            logger.error('Error getting database client in rotateSession');
+            throw new DatabaseError('Database connection failed', error);
+        }
+        // Invalidate old session(s)
+        try {
+            if (options?.oldSessionToken) {
+                const oldTokenHash = hashToken(options.oldSessionToken);
+                await db.delete(sessions).where(eq(sessions.tokenHash, oldTokenHash));
+            }
+            else {
+                await db.delete(sessions).where(eq(sessions.userId, userId));
+            }
+        }
+        catch (error) {
+            logger.error('Error deleting old session(s) during rotation');
+            throw new DatabaseError('Failed to delete old session(s)', error);
+        }
+        // Create a fresh session
+        return await createSession(userId, {
+            persistent: options?.persistent,
+            userAgent: options?.userAgent,
+            ipAddress: options?.ipAddress,
+        });
+    }
+    catch (err) {
+        if (err instanceof DatabaseError || err instanceof TokenError) {
+            throw err;
+        }
+        logger.error('Unexpected error in rotateSession');
+        throw new DatabaseError('Unexpected error rotating session', err);
+    }
+}
 /**
  * Delete a session (sign out)
  *
@@ -235,7 +354,7 @@ function extractSessionToken(cookieHeader) {
     if (!sessionCookie) {
         return null;
     }
-    return sessionCookie.substring('revealui-session='.length);
+    return decodeURIComponent(sessionCookie.substring('revealui-session='.length));
 }
 /**
  * Generate a secure random session token

package/dist/server/signed-cookie.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Signed Cookie Utility
+ *
+ * Signs and verifies JSON payloads for stateless storage in httpOnly cookies.
+ * Used by MFA pre-auth flow and WebAuthn challenge flow.
+ *
+ * Format: base64url(JSON payload) + '.' + base64url(HMAC-SHA256 signature)
+ */
+/**
+ * Sign a payload for storage in an httpOnly cookie.
+ * Format: base64url(JSON payload) + '.' + base64url(HMAC-SHA256 signature)
+ *
+ * @param payload - Must include `expiresAt` (Unix ms timestamp)
+ * @param secret - HMAC signing key (e.g., REVEALUI_SECRET)
+ * @returns Signed string safe for cookie value
+ */
+export declare function signCookiePayload<T extends {
+    expiresAt: number;
+}>(payload: T, secret: string): string;
+/**
+ * Verify and decode a signed cookie payload.
+ * Returns null if: signature invalid, expired, or malformed.
+ * Uses timing-safe comparison to prevent timing attacks.
+ *
+ * @param signed - Signed cookie string from `signCookiePayload`
+ * @param secret - HMAC signing key (must match the one used to sign)
+ * @returns Decoded payload or null if invalid
+ */
+export declare function verifyCookiePayload<T extends {
+    expiresAt: number;
+}>(signed: string, secret: string): T | null;
+//# sourceMappingURL=signed-cookie.d.ts.map

package/dist/server/signed-cookie.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signed-cookie.d.ts","sourceRoot":"","sources":["../../src/server/signed-cookie.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAC/D,OAAO,EAAE,CAAC,EACV,MAAM,EAAE,MAAM,GACb,MAAM,CAQR;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EACjE,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,CAAC,GAAG,IAAI,CAyCV"}

package/dist/server/signed-cookie.js

@@ -0,0 +1,67 @@
+/**
+ * Signed Cookie Utility
+ *
+ * Signs and verifies JSON payloads for stateless storage in httpOnly cookies.
+ * Used by MFA pre-auth flow and WebAuthn challenge flow.
+ *
+ * Format: base64url(JSON payload) + '.' + base64url(HMAC-SHA256 signature)
+ */
+import crypto from 'node:crypto';
+/**
+ * Sign a payload for storage in an httpOnly cookie.
+ * Format: base64url(JSON payload) + '.' + base64url(HMAC-SHA256 signature)
+ *
+ * @param payload - Must include `expiresAt` (Unix ms timestamp)
+ * @param secret - HMAC signing key (e.g., REVEALUI_SECRET)
+ * @returns Signed string safe for cookie value
+ */
+export function signCookiePayload(payload, secret) {
+    const payloadJson = JSON.stringify(payload);
+    const payloadB64 = Buffer.from(payloadJson).toString('base64url');
+    const signature = crypto.createHmac('sha256', secret).update(payloadB64).digest();
+    const signatureB64 = signature.toString('base64url');
+    return `${payloadB64}.${signatureB64}`;
+}
+/**
+ * Verify and decode a signed cookie payload.
+ * Returns null if: signature invalid, expired, or malformed.
+ * Uses timing-safe comparison to prevent timing attacks.
+ *
+ * @param signed - Signed cookie string from `signCookiePayload`
+ * @param secret - HMAC signing key (must match the one used to sign)
+ * @returns Decoded payload or null if invalid
+ */
+export function verifyCookiePayload(signed, secret) {
+    try {
+        if (!signed) {
+            return null;
+        }
+        const parts = signed.split('.');
+        if (parts.length !== 2) {
+            return null;
+        }
+        const [payloadB64, signatureB64] = parts;
+        // Recompute the expected signature
+        const expectedSignature = crypto.createHmac('sha256', secret).update(payloadB64).digest();
+        const actualSignature = Buffer.from(signatureB64, 'base64url');
+        // Timing-safe comparison — buffers must be same length
+        if (expectedSignature.length !== actualSignature.length) {
+            return null;
+        }
+        if (!crypto.timingSafeEqual(expectedSignature, actualSignature)) {
+            return null;
+        }
+        // Signature valid — decode and parse the payload
+        const payloadJson = Buffer.from(payloadB64, 'base64url').toString('utf8');
+        const payload = JSON.parse(payloadJson);
+        // Check expiry
+        if (typeof payload.expiresAt !== 'number' || payload.expiresAt <= Date.now()) {
+            return null;
+        }
+        return payload;
+    }
+    catch {
+        // Malformed input (bad base64, bad JSON, etc.) → null
+        return null;
+    }
+}

package/dist/server/storage/database.d.ts

@@ -2,7 +2,7 @@
  * Database Storage
  *
  * Database backend using Drizzle ORM
- * Slower than Redis but uses existing database infrastructure
+ * Uses existing database infrastructure with no external cache dependency
  */
 import type { Storage } from './interface.js';
 export declare class DatabaseStorage implements Storage {
@@ -13,5 +13,14 @@ export declare class DatabaseStorage implements Storage {
     del(key: string): Promise<void>;
     incr(key: string): Promise<number>;
     exists(key: string): Promise<boolean>;
+    /**
+     * Atomically read and update a value using a database transaction.
+     * Falls back to non-atomic get-then-set if transactions are unavailable
+     * (e.g., Neon HTTP mode in environments that don't support advisory locks).
+     */
+    atomicUpdate(key: string, updater: (existing: string | null) => {
+        value: string;
+        ttlSeconds: number;
+    }): Promise<void>;
 }
 //# sourceMappingURL=database.d.ts.map

package/dist/server/storage/database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../src/server/storage/database.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AAE7C,qBAAa,eAAgB,YAAW,OAAO;IAC7C,OAAO,CAAC,EAAE,CAAU;gBAER,gBAAgB,CAAC,EAAE,MAAM;IAkB/B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAcxC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBnE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAI5C"}
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../src/server/storage/database.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE9C,qBAAa,eAAgB,YAAW,OAAO;IAC7C,OAAO,CAAC,EAAE,CAAW;gBAET,gBAAgB,CAAC,EAAE,MAAM;IAkB/B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAcxC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBnE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK3C;;;;OAIG;IACG,YAAY,CAChB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAC1E,OAAO,CAAC,IAAI,CAAC;CA6BjB"}

package/dist/server/storage/database.js

@@ -2,13 +2,14 @@
  * Database Storage
  *
  * Database backend using Drizzle ORM
- * Slower than Redis but uses existing database infrastructure
+ * Uses existing database infrastructure with no external cache dependency
  */
 // Import config module (ESM)
 // Config uses proxy for lazy loading, so import is safe - validation only happens on property access
 import configModule from '@revealui/config';
 import { createClient } from '@revealui/db/client';
-import { and, eq, gte, rateLimits } from '@revealui/db/schema';
+import { rateLimits } from '@revealui/db/schema';
+import { and, eq, gte } from 'drizzle-orm';
 export class DatabaseStorage {
     db;
     constructor(connectionString) {
@@ -60,13 +61,50 @@ export class DatabaseStorage {
         await this.db.delete(rateLimits).where(eq(rateLimits.key, key));
     }
     async incr(key) {
-        const current = await this.get(key);
-        const newValue = current ? parseInt(current, 10) + 1 : 1;
-        await this.set(key, String(newValue));
+        let newValue = 1;
+        await this.atomicUpdate(key, (existing) => {
+            newValue = existing ? parseInt(existing, 10) + 1 : 1;
+            return { value: String(newValue), ttlSeconds: 24 * 60 * 60 };
+        });
         return newValue;
     }
     async exists(key) {
         const result = await this.get(key);
         return result !== null;
     }
+    /**
+     * Atomically read and update a value using a database transaction.
+     * Falls back to non-atomic get-then-set if transactions are unavailable
+     * (e.g., Neon HTTP mode in environments that don't support advisory locks).
+     */
+    async atomicUpdate(key, updater) {
+        try {
+            await this.db.transaction(async (tx) => {
+                const now = new Date();
+                const result = await tx.query.rateLimits.findFirst({
+                    where: and(eq(rateLimits.key, key), gte(rateLimits.resetAt, now)),
+                });
+                const { value, ttlSeconds } = updater(result?.value ?? null);
+                const resetAt = new Date(Date.now() + ttlSeconds * 1000);
+                await tx
+                    .insert(rateLimits)
+                    .values({ key, value, resetAt })
+                    .onConflictDoUpdate({
+                    target: rateLimits.key,
+                    set: { value, resetAt, updatedAt: new Date() },
+                });
+            });
+        }
+        catch (error) {
+            // Only fall back for transaction-not-supported errors (e.g., Neon HTTP serverless).
+            // Re-throw real DB errors (connection failures, constraint violations, deadlocks).
+            const msg = error instanceof Error ? error.message : String(error);
+            if (!(msg.includes('transaction') || msg.includes('Transaction'))) {
+                throw error;
+            }
+            const existing = await this.get(key);
+            const { value, ttlSeconds } = updater(existing);
+            await this.set(key, value, ttlSeconds);
+        }
+    }
 }

package/dist/server/storage/in-memory.d.ts

@@ -12,6 +12,10 @@ export declare class InMemoryStorage implements Storage {
     del(key: string): Promise<void>;
     incr(key: string): Promise<number>;
     exists(key: string): Promise<boolean>;
+    atomicUpdate(key: string, updater: (existing: string | null) => {
+        value: string;
+        ttlSeconds: number;
+    }): Promise<void>;
     /**
      * Clean up expired entries (should be called periodically)
      */

package/dist/server/storage/in-memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"in-memory.d.ts","sourceRoot":"","sources":["../../../src/server/storage/in-memory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AAO7C,qBAAa,eAAgB,YAAW,OAAO;IAC7C,OAAO,CAAC,KAAK,CAAuC;IAG9C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAiBxC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUnE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgB3C;;OAEG;IACH,OAAO,IAAI,IAAI;IASf;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}
+{"version":3,"file":"in-memory.d.ts","sourceRoot":"","sources":["../../../src/server/storage/in-memory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAO9C,qBAAa,eAAgB,YAAW,OAAO;IAC7C,OAAO,CAAC,KAAK,CAAwC;IAE/C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAgBxC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASnE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAYlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBrC,YAAY,CAChB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAC1E,OAAO,CAAC,IAAI,CAAC;IAUhB;;OAEG;IACH,OAAO,IAAI,IAAI;IASf;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/server/storage/in-memory.js

@@ -6,7 +6,6 @@
  */
 export class InMemoryStorage {
     store = new Map();
-    // eslint-disable-next-line @typescript-eslint/require-await
     async get(key) {
         const entry = this.store.get(key);
         if (!entry) {
@@ -19,7 +18,6 @@ export class InMemoryStorage {
         }
         return entry.value;
     }
-    // eslint-disable-next-line @typescript-eslint/require-await
     async set(key, value, ttlSeconds) {
         const entry = {
             value,
@@ -27,17 +25,20 @@ export class InMemoryStorage {
         };
         this.store.set(key, entry);
     }
-    // eslint-disable-next-line @typescript-eslint/require-await
     async del(key) {
         this.store.delete(key);
     }
     async incr(key) {
-        const current = await this.get(key);
+        // Read and write synchronously on the Map to avoid yielding to the event loop
+        // between read and write (same approach as atomicUpdate).
+        const now = Date.now();
+        const entry = this.store.get(key);
+        const current = entry && (!entry.expiresAt || entry.expiresAt >= now) ? entry.value : null;
         const newValue = current ? parseInt(current, 10) + 1 : 1;
-        await this.set(key, String(newValue));
+        // Preserve the original TTL if the entry exists
+        this.store.set(key, { value: String(newValue), expiresAt: entry?.expiresAt });
         return newValue;
     }
-    // eslint-disable-next-line @typescript-eslint/require-await
     async exists(key) {
         const entry = this.store.get(key);
         if (!entry) {
@@ -50,6 +51,15 @@ export class InMemoryStorage {
         }
         return true;
     }
+    async atomicUpdate(key, updater) {
+        // Read synchronously from the Map to avoid yielding to the event loop between
+        // read and write (JavaScript is single-threaded; no I/O = no interleaving).
+        const now = Date.now();
+        const entry = this.store.get(key);
+        const existing = entry && (!entry.expiresAt || entry.expiresAt >= now) ? entry.value : null;
+        const { value, ttlSeconds } = updater(existing);
+        this.store.set(key, { value, expiresAt: now + ttlSeconds * 1000 });
+    }
     /**
      * Clean up expired entries (should be called periodically)
      */

package/dist/server/storage/index.d.ts

@@ -1,11 +1,19 @@
 /**
  * Storage Factory
  *
- * Selects storage backend based on configuration
+ * Selects storage backend based on configuration.
  * Priority: Database > In-Memory
  *
- * Note: Uses database storage for distributed rate limiting (works with ElectricSQL sync).
- * ElectricSQL handles client-side sync, database handles server-side storage.
+ * Architecture Decision (2026-03-11):
+ * Production deployments use DatabaseStorage backed by NeonDB (PostgreSQL).
+ * Neon's serverless driver uses HTTP (not persistent connections), so each
+ * rate limit check is a single HTTP round-trip (~30-50ms). State persists
+ * across Vercel cold starts because it lives in PostgreSQL, not process memory.
+ * This is acceptable for current scale. If sub-10ms latency becomes critical,
+ * add an ElectricSQL/PGlite adapter implementing the Storage interface.
+ *
+ * In-memory storage is ONLY used in development (throws in production if
+ * DATABASE_URL is missing).
  */
 import type { Storage } from './interface.js';
 /**

package/dist/server/storage/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/storage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AAI7C;;GAEG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAkCpC;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAevC;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAEnC;AAED,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAE/C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAChD,YAAY,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/storage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAI9C;;GAEG;AACH,wBAAgB,UAAU,IAAI,OAAO,CA6CpC;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAevC;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAEnC;AAED,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/server/storage/index.js

@@ -1,11 +1,19 @@
 /**
  * Storage Factory
  *
- * Selects storage backend based on configuration
+ * Selects storage backend based on configuration.
  * Priority: Database > In-Memory
  *
- * Note: Uses database storage for distributed rate limiting (works with ElectricSQL sync).
- * ElectricSQL handles client-side sync, database handles server-side storage.
+ * Architecture Decision (2026-03-11):
+ * Production deployments use DatabaseStorage backed by NeonDB (PostgreSQL).
+ * Neon's serverless driver uses HTTP (not persistent connections), so each
+ * rate limit check is a single HTTP round-trip (~30-50ms). State persists
+ * across Vercel cold starts because it lives in PostgreSQL, not process memory.
+ * This is acceptable for current scale. If sub-10ms latency becomes critical,
+ * add an ElectricSQL/PGlite adapter implementing the Storage interface.
+ *
+ * In-memory storage is ONLY used in development (throws in production if
+ * DATABASE_URL is missing).
  */
 import config from '@revealui/config';
 import { logger } from '@revealui/core/observability/logger';
@@ -40,12 +48,18 @@ export function getStorage() {
             return globalStorage;
         }
         catch (error) {
+            if (process.env.NODE_ENV === 'production') {
+                throw new Error(`Rate limiting requires database storage in production. DatabaseStorage failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
             logger.warn('Failed to create DatabaseStorage, falling back to InMemoryStorage', {
                 error: error instanceof Error ? error.message : String(error),
             });
         }
     }
-    // Fallback to in-memory (development without DATABASE_URL)
+    if (process.env.NODE_ENV === 'production') {
+        throw new Error('Rate limiting requires DATABASE_URL or POSTGRES_URL in production. In-memory storage is not safe for distributed deployments.');
+    }
+    // Fallback to in-memory (development only)
     globalStorage = new InMemoryStorage();
     return globalStorage;
 }

package/dist/server/storage/interface.d.ts

@@ -1,7 +1,7 @@
 /**
  * Storage Interface
  *
- * Abstract interface for storage backends (in-memory, Redis, database)
+ * Abstract interface for storage backends (in-memory, database)
  */
 export interface Storage {
     /**
@@ -32,5 +32,15 @@ export interface Storage {
      * Set multiple key-value pairs
      */
     mset?(pairs: Array<[string, string]>, ttlSeconds?: number): Promise<void>;
+    /**
+     * Atomically read and update a value.
+     * The updater receives the current value (or null) and returns the new value + TTL.
+     * Implementations that support DB transactions should do so; others fall back to
+     * a non-atomic get-then-set, which is safe for low-concurrency scenarios.
+     */
+    atomicUpdate?(key: string, updater: (existing: string | null) => {
+        value: string;
+        ttlSeconds: number;
+    }): Promise<void>;
 }
 //# sourceMappingURL=interface.d.ts.map

package/dist/server/storage/interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../../src/server/storage/interface.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAExC;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEnE;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE/B;;OAEG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAElC;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAErC;;OAEG;IACH,IAAI,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,CAAA;IAEjD;;OAEG;IACH,IAAI,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1E"}
+{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../../src/server/storage/interface.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEzC;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpE;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhC;;OAEG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnC;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtC;;OAEG;IACH,IAAI,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;IAElD;;OAEG;IACH,IAAI,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1E;;;;;OAKG;IACH,YAAY,CAAC,CACX,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAC1E,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB"}

package/dist/server/storage/interface.js

@@ -1,6 +1,6 @@
 /**
  * Storage Interface
  *
- * Abstract interface for storage backends (in-memory, Redis, database)
+ * Abstract interface for storage backends (in-memory, database)
  */
 export {};

package/dist/types.d.ts

@@ -2,8 +2,8 @@
  * Auth Types
  *
  * Type definitions for authentication system.
- * Uses concrete interfaces instead of z.infer<> aliases to ensure
- * ESLint type-checked rules can resolve all types.
+ * Uses concrete interfaces instead of z.infer<> aliases for
+ * clear type definitions and better IDE support.
  */
 /**
  * User row type matching the users table schema.
@@ -22,6 +22,11 @@ export interface User {
     agentModel: string | null;
     agentCapabilities: string[] | null;
     agentConfig: unknown;
+    emailVerified: boolean;
+    emailVerificationToken: string | null;
+    emailVerifiedAt: Date | null;
+    mfaEnabled: boolean;
+    mfaVerifiedAt: Date | null;
     preferences: unknown;
     createdAt: Date;
     updatedAt: Date;
@@ -43,17 +48,27 @@ export interface Session {
     lastActivityAt: Date;
     createdAt: Date;
     expiresAt: Date;
+    metadata: Record<string, unknown> | null;
 }
 export interface AuthSession {
     session: Session;
     user: User;
 }
-export interface SignInResult {
-    success: boolean;
-    user?: User;
-    sessionToken?: string;
-    error?: string;
-}
+/** Discriminated union for sign-in outcomes. Check `success` first, then `reason` for failure details. */
+export type SignInResult = {
+    success: true;
+    requiresMfa?: false;
+    user: User;
+    sessionToken: string;
+} | {
+    success: true;
+    requiresMfa: true;
+    mfaUserId: string;
+} | {
+    success: false;
+    reason: 'invalid_credentials' | 'account_locked' | 'rate_limited' | 'database_error' | 'session_error' | 'email_not_verified' | 'unexpected_error';
+    error: string;
+};
 export interface SignUpResult {
     success: boolean;
     user?: User;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;GAGG;AACH,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAA;IACV,aAAa,EAAE,MAAM,CAAA;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,iBAAiB,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;IAClC,WAAW,EAAE,OAAO,CAAA;IACpB,WAAW,EAAE,OAAO,CAAA;IACpB,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;IACf,YAAY,EAAE,IAAI,GAAG,IAAI,CAAA;IACzB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAA;IACV,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,UAAU,EAAE,OAAO,GAAG,IAAI,CAAA;IAC1B,cAAc,EAAE,IAAI,CAAA;IACpB,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,IAAI,CAAA;CACX;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE,IAAI,CAAA;IACX,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE,IAAI,CAAA;IACX,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;GAGG;AACH,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,iBAAiB,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACnC,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;IACvB,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,eAAe,EAAE,IAAI,GAAG,IAAI,CAAC;IAC7B,UAAU,EAAE,OAAO,CAAC;IACpB,aAAa,EAAE,IAAI,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;IAE1B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,OAAO,GAAG,IAAI,CAAC;IAC3B,cAAc,EAAE,IAAI,CAAC;IACrB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC1C;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,IAAI,CAAC;CACZ;AAED,0GAA0G;AAC1G,MAAM,MAAM,YAAY,GACpB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,WAAW,CAAC,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACxE;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACvD;IACE,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EACF,qBAAqB,GACrB,gBAAgB,GAChB,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,oBAAoB,GACpB,kBAAkB,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEN,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}