@payez/next-mvp 3.0.0

package/dist/lib/session-store.js

@@ -0,0 +1,537 @@
+"use strict";
+/**
+ * Session Store for `@payez/next-mvp` using ioredis
+ *
+ * This module provides a Redis-backed session store that is compatible with the
+ * `ioredis` client. It handles the creation, retrieval, and deletion of
+ * session data, which is the single source of truth for authentication.
+ *
+ * Includes advanced distributed refresh coordination with version control.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSessionToken = generateSessionToken;
+exports.createSession = createSession;
+exports.getSession = getSession;
+exports.getSessionWithVersion = getSessionWithVersion;
+exports.isAccessTokenFresh = isAccessTokenFresh;
+exports.deleteSession = deleteSession;
+exports.setSession = setSession;
+exports.updateSession = updateSession;
+exports.transitionTo2FASession = transitionTo2FASession;
+exports.updateTokens = updateTokens;
+exports.mark2FAComplete = mark2FAComplete;
+exports.is2FAComplete = is2FAComplete;
+exports.getTokens = getTokens;
+exports.refreshJWTSession = refreshJWTSession;
+exports.clearAllSessions = clearAllSessions;
+exports.listAllSessions = listAllSessions;
+exports.acquireRefreshLock = acquireRefreshLock;
+exports.releaseRefreshLock = releaseRefreshLock;
+exports.checkRefreshLock = checkRefreshLock;
+exports.isRefreshInProgress = isRefreshInProgress;
+exports.cleanupRefreshLocks = cleanupRefreshLocks;
+const redis_1 = __importDefault(require("./redis"));
+const crypto_1 = require("crypto");
+const app_slug_1 = require("./app-slug");
+const token_utils_1 = require("../auth/utils/token-utils");
+// Use app-slug prefixes for multi-app isolation
+const getSessionKey = (token) => `${(0, app_slug_1.getSessionPrefix)()}${token}`;
+const getRefreshLockKey = (token) => `${(0, app_slug_1.getRefreshLockPrefix)()}${token}`;
+const getSessionVersionKey = (token) => `${(0, app_slug_1.getSessionPrefix)()}ver:${token}`;
+const REFRESH_LOCK_TTL = 60; // 60 seconds
+const SESSION_TTL = 3 * 24 * 60 * 60; // 3 days in seconds (matches refresh token lifetime)
+/**
+ * Generates a new session token.
+ * @returns A new session token string.
+ */
+function generateSessionToken() {
+    return (0, crypto_1.randomBytes)(32).toString('hex');
+}
+/**
+ * Creates a new session in Redis.
+ *
+ * @param data The session data to store.
+ * @returns The generated session token (redisSessionId).
+ */
+async function createSession(data) {
+    const sessionToken = (0, crypto_1.randomBytes)(32).toString('hex');
+    const key = getSessionKey(sessionToken);
+    const versionKey = getSessionVersionKey(sessionToken);
+    try {
+        await redis_1.default.multi()
+            .setex(key, SESSION_TTL, JSON.stringify(data))
+            .setex(versionKey, SESSION_TTL, '1')
+            .exec();
+    }
+    catch (error) {
+        console.error('[SESSION-STORE] Failed to create session:', error);
+        throw error;
+    }
+    return sessionToken;
+}
+/**
+ * Retrieves a session from Redis.
+ *
+ * @param sessionToken The session token (redisSessionId) to look up.
+ * @returns The session data, or null if not found.
+ */
+async function getSession(sessionToken) {
+    if (!sessionToken) {
+        return null;
+    }
+    const key = getSessionKey(sessionToken);
+    const json = await redis_1.default.get(key);
+    if (!json) {
+        return null;
+    }
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        console.error('[SESSION-STORE] Failed to parse session data');
+        return null;
+    }
+}
+/**
+ * Retrieves a session along with a version identifier for optimistic locking.
+ * @param sessionToken The session token to look up.
+ * @returns An object with session and version, or null if not found.
+ */
+async function getSessionWithVersion(sessionToken) {
+    const session = await getSession(sessionToken);
+    if (!session) {
+        return null;
+    }
+    const versionKey = getSessionVersionKey(sessionToken);
+    const version = await redis_1.default.get(versionKey);
+    if (!version) {
+        // Session exists but version key missing - use idpAccessTokenExpires as fallback
+        const fallbackVersion = String(session.idpAccessTokenExpires || Date.now());
+        return { session, version: fallbackVersion };
+    }
+    return { session, version };
+}
+/**
+ * Checks if the access token in a session is still fresh (not expired).
+ * @param sessionToken The session token to check.
+ * @param currentAccessToken The current access token to compare.
+ * @param currentVersion Optional version to check for changes.
+ * @returns Object with freshness status and latest token info.
+ */
+async function isAccessTokenFresh(sessionToken, currentAccessToken, currentVersion) {
+    const sessionWithVersion = await getSessionWithVersion(sessionToken);
+    if (!sessionWithVersion) {
+        return { isFresh: false, versionChanged: true };
+    }
+    const { session, version } = sessionWithVersion;
+    const versionChanged = currentVersion ? version !== currentVersion : false;
+    // If version changed, the token might be stale
+    // Use normalized field name (idpAccessToken)
+    const isFresh = !versionChanged && session.idpAccessToken === currentAccessToken;
+    return {
+        isFresh,
+        latestAccessToken: session.idpAccessToken || undefined,
+        latestVersion: version,
+        versionChanged
+    };
+}
+/**
+ * Deletes a session from Redis.
+ * @param sessionToken The session token to delete.
+ */
+async function deleteSession(sessionToken) {
+    if (!sessionToken) {
+        return;
+    }
+    const key = getSessionKey(sessionToken);
+    const versionKey = getSessionVersionKey(sessionToken);
+    await redis_1.default.del(key, versionKey);
+}
+/**
+ * Sets a session directly (for testing or migrations).
+ * @param sessionToken The session token.
+ * @param data The session data.
+ */
+async function setSession(sessionToken, data) {
+    const key = getSessionKey(sessionToken);
+    const versionKey = getSessionVersionKey(sessionToken);
+    await redis_1.default.multi()
+        .setex(key, SESSION_TTL, JSON.stringify(data))
+        .incr(versionKey)
+        .expire(versionKey, SESSION_TTL)
+        .exec();
+}
+/**
+ * Updates tokens within an existing session.
+ * @param sessionToken The session token to update.
+ * @param updates Partial session data to update.
+ * @returns The updated session data, or null if the session was not found.
+ */
+async function updateSession(sessionToken, updates) {
+    const key = getSessionKey(sessionToken);
+    const versionKey = getSessionVersionKey(sessionToken);
+    // Get current session to merge with updates
+    const currentSession = await getSession(sessionToken);
+    if (!currentSession) {
+        return null;
+    }
+    // CRITICAL: Track any refresh token changes (check both old and new field names)
+    const hadRefreshToken = !!(currentSession.idpRefreshToken || currentSession.refreshToken);
+    const willHaveRefreshToken = updates.idpRefreshToken !== undefined
+        ? !!updates.idpRefreshToken
+        : updates.refreshToken !== undefined
+            ? !!updates.refreshToken
+            : hadRefreshToken;
+    if (hadRefreshToken && !willHaveRefreshToken) {
+        console.error('[SESSION-STORE] ⚠️ REFRESH_TOKEN_BEING_CLEARED', {
+            sessionToken: sessionToken.substring(0, 8) + '...',
+            userId: currentSession.userId,
+            updateKeys: Object.keys(updates),
+            refreshTokenInUpdate: updates.idpRefreshToken || updates.refreshToken,
+            refreshTokenClearedReason: updates.refreshTokenClearedReason || 'UNKNOWN',
+            stack: new Error().stack
+        });
+    }
+    // Merge current session with updates
+    const updatedSession = { ...currentSession, ...updates };
+    // Write the entire updated session back to Redis with version increment
+    await redis_1.default.multi()
+        .setex(key, SESSION_TTL, JSON.stringify(updatedSession))
+        .incr(versionKey)
+        .expire(versionKey, SESSION_TTL)
+        .exec();
+    return updatedSession;
+}
+/**
+ * Transitions a session to a MFA-completed state.
+ * @param sessionToken The session token to update.
+ * @param tokens The new tokens received after MFA completion.
+ * @param mfaMethod The MFA method used (email, sms, totp) - required for token refresh.
+ * @returns The updated session data.
+ */
+async function transitionTo2FASession(sessionToken, tokens, mfaMethod) {
+    const newAccessToken = tokens.idpAccessToken || tokens.accessToken;
+    console.log('[transitionTo2FASession] Called with:', {
+        sessionToken: sessionToken?.substring(0, 8) + '...',
+        mfaMethod,
+        hasAccessToken: !!newAccessToken,
+        hasRefreshToken: !!(tokens.idpRefreshToken || tokens.refreshToken),
+    });
+    // Extract bearerKeyId from the new access token (IDP may use different key after 2FA)
+    let bearerKeyId;
+    if (newAccessToken) {
+        bearerKeyId = (0, token_utils_1.extractKidFromToken)(newAccessToken);
+        if (bearerKeyId) {
+            console.log('[transitionTo2FASession] Extracted bearerKeyId (kid) from new JWT header:', bearerKeyId);
+        }
+    }
+    // Support both old and new field names in input
+    // CRITICAL: Set BOTH mfaVerified (new) AND twoFactorComplete (legacy) for compatibility
+    // auth.ts session callback reads twoFactorComplete, so we must set it here
+    const updates = {
+        idpAccessToken: newAccessToken,
+        idpRefreshToken: tokens.idpRefreshToken || tokens.refreshToken,
+        idpAccessTokenExpires: tokens.idpAccessTokenExpires || tokens.accessTokenExpires,
+        mfaVerified: true,
+        twoFactorComplete: true, // Legacy field - required by auth.ts session callback
+        mfaMethod: mfaMethod,
+        // Update bearerKeyId if extracted from new token
+        ...(bearerKeyId && { bearerKeyId }),
+    };
+    const refreshExpires = tokens.idpRefreshTokenExpires || tokens.refreshTokenExpires;
+    if (refreshExpires !== undefined) {
+        updates.idpRefreshTokenExpires = refreshExpires;
+    }
+    console.log('[transitionTo2FASession] Updates to apply:', {
+        mfaVerified: updates.mfaVerified,
+        twoFactorComplete: updates.twoFactorComplete,
+        mfaMethod: updates.mfaMethod,
+        hasIdpAccessToken: !!updates.idpAccessToken,
+    });
+    const result = await updateSession(sessionToken, updates);
+    console.log('[transitionTo2FASession] Result:', {
+        success: !!result,
+        resultMfaVerified: result?.mfaVerified,
+    });
+    return result;
+}
+/**
+ * Updates IDP tokens and their expiries in an existing session.
+ * @param sessionToken The session token to update.
+ * @param idpAccessToken The new IDP access token.
+ * @param idpRefreshToken The new IDP refresh token.
+ * @param idpAccessTokenExpires The access token expiry timestamp.
+ * @param idpRefreshTokenExpires The refresh token expiry timestamp (optional).
+ * @returns The updated session data.
+ */
+async function updateTokens(sessionToken, idpAccessToken, idpRefreshToken, idpAccessTokenExpires, idpRefreshTokenExpires) {
+    return updateSession(sessionToken, {
+        idpAccessToken,
+        idpRefreshToken,
+        idpAccessTokenExpires,
+        idpRefreshTokenExpires,
+    });
+}
+/**
+ * Marks a session as having completed MFA.
+ * @param sessionToken The session token to update.
+ * @returns The updated session data.
+ */
+async function mark2FAComplete(sessionToken) {
+    return updateSession(sessionToken, {
+        mfaVerified: true,
+    });
+}
+/**
+ * Checks if MFA is complete for a session.
+ * @param sessionToken The session token.
+ * @returns True if MFA is complete.
+ */
+async function is2FAComplete(sessionToken) {
+    const session = await getSession(sessionToken);
+    return session?.mfaVerified === true;
+}
+/**
+ * Gets IDP tokens from a session.
+ * @param sessionToken The session token.
+ * @returns The tokens or null if session not found.
+ */
+async function getTokens(sessionToken) {
+    const session = await getSession(sessionToken);
+    if (!session || !session.idpAccessToken || !session.idpRefreshToken) {
+        return null;
+    }
+    return {
+        // Legacy names for backward compatibility
+        accessToken: session.idpAccessToken,
+        refreshToken: session.idpRefreshToken,
+        // New normalized names
+        idpAccessToken: session.idpAccessToken,
+        idpRefreshToken: session.idpRefreshToken,
+    };
+}
+/**
+ * Refreshes a JWT session (placeholder for compatibility).
+ * @param sessionToken The session token.
+ * @returns The session data or null.
+ */
+async function refreshJWTSession(sessionToken) {
+    return getSession(sessionToken);
+}
+/**
+ * Clears all sessions (for testing only).
+ */
+async function clearAllSessions() {
+    console.warn('[SESSION-STORE] clearAllSessions called - this should only be used in testing');
+}
+/**
+ * Lists all sessions (for testing/debugging only).
+ * @returns An empty array (placeholder).
+ */
+async function listAllSessions() {
+    console.warn('[SESSION-STORE] listAllSessions called - this should only be used in testing');
+    return [];
+}
+// ===============================
+// DISTRIBUTED REFRESH COORDINATION
+// ===============================
+/**
+ * Attempt to acquire a refresh lock for a session
+ * Uses Redis SET with NX (Not eXists) for atomic lock acquisition
+ */
+async function acquireRefreshLock(sessionToken, requestId, maxWaitMs = 5000) {
+    const lockKey = getRefreshLockKey(sessionToken);
+    const acquiredAt = Date.now();
+    const lockVersion = Math.floor(Math.random() * 1000000);
+    const lockInfo = {
+        sessionToken,
+        acquiredAt,
+        acquiredBy: requestId,
+        lockVersion
+    };
+    try {
+        // Try to acquire the lock atomically
+        const result = await redis_1.default.set(lockKey, JSON.stringify(lockInfo), 'PX', REFRESH_LOCK_TTL * 1000, 'NX');
+        if (result === 'OK') {
+            console.log('[SESSION-STORE] Refresh lock acquired', {
+                sessionToken: sessionToken.substring(0, 8) + '...',
+                requestId,
+                lockVersion
+            });
+            return { acquired: true, lockInfo };
+        }
+        else {
+            // Lock already exists, check if we should wait
+            if (maxWaitMs > 0) {
+                console.log('[SESSION-STORE] Refresh lock already exists, waiting for release', {
+                    sessionToken: sessionToken.substring(0, 8) + '...',
+                    requestId,
+                    maxWaitMs
+                });
+                return await waitForRefreshLockRelease(sessionToken, requestId, maxWaitMs);
+            }
+            console.warn('[SESSION-STORE] Refresh lock already exists, not waiting', {
+                sessionToken: sessionToken.substring(0, 8) + '...',
+                requestId
+            });
+            return { acquired: false };
+        }
+    }
+    catch (error) {
+        console.error('[SESSION-STORE] Failed to acquire refresh lock', {
+            sessionToken: sessionToken.substring(0, 8) + '...',
+            requestId,
+            error: error instanceof Error ? error.message : String(error)
+        });
+        return { acquired: false };
+    }
+}
+/**
+ * Wait for a refresh lock to be released
+ */
+async function waitForRefreshLockRelease(sessionToken, requestId, maxWaitMs) {
+    const lockKey = getRefreshLockKey(sessionToken);
+    const startTime = Date.now();
+    const pollInterval = 100;
+    while (Date.now() - startTime < maxWaitMs) {
+        try {
+            const lockExists = await redis_1.default.exists(lockKey);
+            if (!lockExists) {
+                // Lock released - do not reacquire here to avoid double refresh
+                return { acquired: false };
+            }
+            // Wait before next check
+            await new Promise(resolve => setTimeout(resolve, pollInterval));
+        }
+        catch (error) {
+            console.error('[SESSION-STORE] Error while waiting for refresh lock release', {
+                sessionToken: sessionToken.substring(0, 8) + '...',
+                requestId,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            break;
+        }
+    }
+    console.warn('[SESSION-STORE] Timeout waiting for refresh lock release', {
+        sessionToken: sessionToken.substring(0, 8) + '...',
+        requestId,
+        waitedMs: Date.now() - startTime
+    });
+    return { acquired: false };
+}
+/**
+ * Release a refresh lock
+ * Uses Lua script to ensure atomic validation and release
+ */
+async function releaseRefreshLock(sessionToken, requestId, lockVersion) {
+    const lockKey = getRefreshLockKey(sessionToken);
+    try {
+        // Lua script for atomic lock validation and release
+        const luaScript = `
+      local lockKey = KEYS[1]
+      local expectedRequestId = ARGV[1]
+      local expectedVersion = ARGV[2]
+
+      local lockData = redis.call('GET', lockKey)
+      if not lockData then
+        return 0  -- Lock doesn't exist
+      end
+
+      local lockInfo = cjson.decode(lockData)
+      if lockInfo.acquiredBy == expectedRequestId then
+        if not expectedVersion or expectedVersion == '' or tostring(lockInfo.lockVersion) == expectedVersion then
+          redis.call('DEL', lockKey)
+          return 1  -- Successfully released
+        else
+          return -2  -- Version mismatch
+        end
+      else
+        return -1  -- Wrong owner
+      end
+    `;
+        const result = await redis_1.default.eval(luaScript, 1, lockKey, requestId, lockVersion ? lockVersion.toString() : '');
+        if (result === 1) {
+            console.log('[SESSION-STORE] Refresh lock released successfully', {
+                sessionToken: sessionToken.substring(0, 8) + '...',
+                requestId,
+                lockVersion
+            });
+            return true;
+        }
+        else if (result === 0) {
+            console.warn('[SESSION-STORE] Attempted to release non-existent refresh lock', {
+                sessionToken: sessionToken.substring(0, 8) + '...',
+                requestId
+            });
+            return false;
+        }
+        else if (result === -1) {
+            console.error('[SESSION-STORE] Attempted to release refresh lock owned by another request', {
+                sessionToken: sessionToken.substring(0, 8) + '...',
+                requestId
+            });
+            return false;
+        }
+        else if (result === -2) {
+            console.error('[SESSION-STORE] Lock version mismatch during release', {
+                sessionToken: sessionToken.substring(0, 8) + '...',
+                requestId,
+                lockVersion
+            });
+            return false;
+        }
+        else {
+            console.error('[SESSION-STORE] Unexpected result from lock release script', {
+                sessionToken: sessionToken.substring(0, 8) + '...',
+                requestId,
+                result
+            });
+            return false;
+        }
+    }
+    catch (error) {
+        console.error('[SESSION-STORE] Failed to release refresh lock', {
+            sessionToken: sessionToken.substring(0, 8) + '...',
+            requestId,
+            error: error instanceof Error ? error.message : String(error)
+        });
+        return false;
+    }
+}
+/**
+ * Check if a refresh lock exists for a session
+ */
+async function checkRefreshLock(sessionToken) {
+    const lockKey = getRefreshLockKey(sessionToken);
+    try {
+        const lockData = await redis_1.default.get(lockKey);
+        if (!lockData) {
+            return null;
+        }
+        return JSON.parse(lockData);
+    }
+    catch (error) {
+        console.error('[SESSION-STORE] Failed to check refresh lock', {
+            sessionToken: sessionToken.substring(0, 8) + '...',
+            error: error instanceof Error ? error.message : String(error)
+        });
+        return null;
+    }
+}
+/**
+ * Simple check if a refresh is currently in progress for a session
+ */
+async function isRefreshInProgress(sessionToken) {
+    const lock = await checkRefreshLock(sessionToken);
+    return lock !== null;
+}
+/**
+ * Force cleanup of expired or orphaned refresh locks
+ */
+async function cleanupRefreshLocks() {
+    console.warn('[SESSION-STORE] cleanupRefreshLocks called - scanning for expired locks');
+    return 0;
+}

package/dist/lib/session.d.ts

@@ -0,0 +1,21 @@
+export type MinimalSession = {
+    user?: {
+        id?: string | null;
+        email?: string | null;
+    } | null;
+    accessToken?: string | null;
+    expires?: string;
+    [k: string]: any;
+};
+export type AppSession = MinimalSession;
+/**
+ * Strict session validation for client-side guards.
+ * A session is considered valid when:
+ * - a user object exists with non-empty id and email
+ * - an accessToken string exists
+ */
+export declare function isValidSession(session: MinimalSession | null | undefined): boolean;
+/**
+ * Sanitize session data - returns null if session is invalid
+ */
+export declare function sanitizeSession(session: MinimalSession | null | undefined): MinimalSession | null;

package/dist/lib/session.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidSession = isValidSession;
+exports.sanitizeSession = sanitizeSession;
+/**
+ * Strict session validation for client-side guards.
+ * A session is considered valid when:
+ * - a user object exists with non-empty id and email
+ * - an accessToken string exists
+ */
+function isValidSession(session) {
+    if (!session)
+        return false;
+    const u = session.user;
+    const hasUser = !!u && typeof u.id === 'string' && u.id.length > 0 && typeof u.email === 'string' && u.email.length > 0;
+    const hasAccessToken = typeof session.accessToken === 'string' && session.accessToken.length > 0;
+    return hasUser && hasAccessToken;
+}
+/**
+ * Sanitize session data - returns null if session is invalid
+ */
+function sanitizeSession(session) {
+    if (!isValidSession(session))
+        return null;
+    return session;
+}