@payez/next-mvp 4.8.0 → 4.8.2

package/src/routes/auth/session.ts

@@ -1,262 +1,262 @@
-/**
- * Ready-to-Use Session Management Route
- *
- * Provides pre-configured session handlers for checking and updating session state.
- *
- * @example
- * ```typescript
- * // app/api/auth/session/route.ts
- * export { GET, POST } from '@payez/next-mvp/routes/auth/session';
- * ```
- *
- * @version 2.0.0
- * @since auth-ready-v2
- */
-
-import { NextRequest, NextResponse } from 'next/server';
-import { getSession as getBetterAuthSession } from '../../server/auth';
-import { getSession as getRedisSession, updateSession } from '../../lib/session-store';
-import { logExceptionWithCorrelation } from '../../lib/safe-error-response';
-import { tokenLogId } from '../../lib/token-log-id';
-
-/**
- * GET /api/auth/session - Check current session status
- *
- * Returns the current session information including:
- * - User details
- * - Token expiry status
- * - Session validity
- */
-export async function GET(req: NextRequest) {
-  try {
-    const authSession = await getBetterAuthSession(req);
-
-    if (!authSession) {
-      console.warn('[SESSION_ROUTE] Better Auth session not found');
-      // MUST return empty {} — useSession() treats any non-empty
-      // response object as "authenticated", causing redirect loops on login page.
-      return NextResponse.json({});
-    }
-
-    const redisSessionId = authSession.session?.token;
-
-    console.log('[SESSION_ROUTE] Session found:', {
-      userId: authSession.user?.id,
-      email: authSession.user?.email,
-      name: authSession.user?.name,
-      redisSessionId: redisSessionId ? tokenLogId(redisSessionId) : 'MISSING',
-    });
-
-    // Fetch full session data from Redis
-    const session = redisSessionId ? await getRedisSession(redisSessionId) : null;
-
-    console.log('[SESSION_ROUTE] Redis session:', {
-      found: !!session,
-      userId: session?.userId,
-      roles: session?.roles,
-      hasAccessToken: !!session?.idpAccessToken,
-    });
-
-    // A Better Auth cookie is NOT authorization. The Redis session is the
-    // authoritative record of what this user is allowed to do; without it we
-    // have no roles and no IDP access token, so there is nothing to authorize
-    // against. Returning a populated user here produces the worst failure mode
-    // available: a client that renders as signed-in and is not.
-    //
-    // MUST return empty {} for the same reason as line 34 — useSession() treats
-    // ANY non-empty response object as "authenticated".
-    //
-    // NOTE: an MFA-pending session IS present in Redis (it just has
-    // mfaVerified=false), so this gate does not break /verify-code. Gating on a
-    // missing accessToken instead WOULD break it.
-    if (!session) {
-      console.error('[SESSION_ROUTE] Redis session MISS — refusing to report authenticated', {
-        userId: authSession.user?.id,
-        redisSessionId: redisSessionId ? tokenLogId(redisSessionId) : 'MISSING',
-        reason: redisSessionId ? 'session expired or evicted' : 'no session token on auth session',
-      });
-      return NextResponse.json({});
-    }
-
-    // Return session format with Redis data
-    // useSession() expects: { user: {...}, expires: "..." }
-    // We enrich with all session data from Redis
-    return NextResponse.json({
-      user: {
-        id: session?.userId || authSession.user?.id,
-        email: session?.email || authSession.user?.email,
-        name: session?.name || authSession.user?.name,
-        image: authSession.user?.image || session?.image || null,
-        // Redis session data
-        roles: session?.roles || [],
-        twoFactorSessionVerified: session?.mfaVerified || false,
-        requiresTwoFactor: !session?.mfaVerified,
-        authenticationMethods: session?.authenticationMethods,
-        authenticationLevel: session?.authenticationLevel,
-        mfaCompletedAt: session?.mfaCompletedAt,
-        mfaExpiresAt: session?.mfaExpiresAt,
-        mfaValidityHours: session?.mfaValidityHours,
-        oauthProvider: session?.oauthProvider,
-        idpClientId: session?.idpClientId,
-        merchantId: session?.merchantId,
-      },
-      // PAY-1481 item 1: NO token material. This body is read by browser JS, so returning the session token and the
-      // IdP access/refresh tokens handed them to any script on the page (the refresh token outlives the session).
-      // Server routes read tokens from the session store; the UI only needs presence and expiry.
-      hasAccessToken: !!session?.idpAccessToken,
-      hasRefreshToken: !!session?.idpRefreshToken,
-      accessTokenExpires: session?.idpAccessTokenExpires,
-      expires: authSession.session?.expiresAt
-        ? new Date(authSession.session.expiresAt).toISOString()
-        : new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
-    });
-  } catch (error) {
-    // PAY-1438: pre-auth route - the exception text stays in the log, keyed by correlationId.
-    const correlationId = logExceptionWithCorrelation('[SESSION_ROUTE] Error checking session:', error);
-    return NextResponse.json({
-      error: 'Failed to check session',
-      code: 'INTERNAL_ERROR',
-      correlationId,
-    }, { status: 500 });
-  }
-}
-
-/**
- * The fields this route USED to accept from the request body and must never accept
- * again. Cards 308833 (critical) / 312092 (remediation spec) / 318272 / 311425.
- *
- * `twoFactorComplete` was written straight through to `mfaVerified`, so a caller
- * holding any session supplied its OWN second-factor verdict - no factor presented,
- * no comparison against `amr`, no server-side derivation. The caller can be PRE-2FA,
- * which makes this a 2FA bypass rather than a user rewriting a flag he had earned.
- *
- * The package already states the invariant in four places, in its own voice:
- *   api-handlers/mfa/totp-verify.ts   - "Enrolment must never set mfaVerified."
- *   api-handlers/auth/refresh.ts      - "mfaVerified is derived from amrClaims"
- *   auth/better-auth.ts               - "computed fresh ... re-derived fresh"
- *   (consumer) passkey-signin-plugin  - "mfaVerified is DERIVED from amr, never asserted."
- * Every other writer in the estate derives it. This one route took it from an HTTP body.
- *
- * PRESENCE, NOT TRUTHINESS, is what is refused - `twoFactorComplete: false` is rejected
- * exactly like `true`. A caller must not be able to drive this field in EITHER direction,
- * and per R486/R908 an absent signal is "cannot determine", never a negative assertion.
- *
- * REFUSED LOUDLY RATHER THAN IGNORED SILENTLY. Dropping the field would leave a caller
- * believing it had recorded a 2FA completion that never happened - the same failure shape
- * as the 4.1.14 -> 4.1.31 history below, where a write nobody read looked like it worked.
- *
- * *** DO NOT "FIX" A REGRESSION HERE BY REVERTING THE KEY NORMALIZATION (312092 s2). ***
- * 4.1.14 had this same unvalidated write but stored bare `accessToken`/`twoFactorComplete`,
- * keys no reader consulted, so the forgery landed where nothing looked. The 4.1.31
- * normalization did not introduce the bug - IT ARMED IT. Reverting re-hides the hole and
- * restores two real client-facing bugs. The write is authorized here instead.
- */
-const CALLER_ASSERTED_FIELDS: ReadonlyArray<{ field: string; why: string }> = [
-  { field: 'twoFactorComplete', why: 'the second-factor verdict is derived from the IDP token (amr), never asserted by the caller' },
-  { field: 'mfaVerified', why: 'the second-factor verdict is derived from the IDP token (amr), never asserted by the caller' },
-  { field: 'twoFactorMethod', why: 'the method is recorded by the server-side verification path that observed the factor' },
-  { field: 'access_token', why: 'tokens are issued by the IDP; use POST /api/auth/refresh' },
-  { field: 'refresh_token', why: 'tokens are issued by the IDP; use POST /api/auth/refresh' },
-  { field: 'idpAccessToken', why: 'tokens are issued by the IDP; use POST /api/auth/refresh' },
-  { field: 'idpRefreshToken', why: 'tokens are issued by the IDP; use POST /api/auth/refresh' },
-];
-
-/**
- * POST /api/auth/session - Update session METADATA
- *
- * Updates session metadata only. This route holds no authority over authentication
- * state: it cannot set the 2FA verdict and it cannot set tokens.
- *
- * Token refresh uses POST /api/auth/refresh. The 2FA verdict is written only by the
- * server-side verification path that actually observed the factor.
- *
- * Body:
- * - metadata: object - Custom metadata to store in session
- *
- * Any of CALLER_ASSERTED_FIELDS present in the body is a 400. The docstring above used
- * to promise "metadata (not tokens)" while the handler wrote idpAccessToken,
- * idpRefreshToken AND mfaVerified - that false parenthetical is the ONLY caution a
- * mounter reads, and it is how this route came to be mounted (318272). The promise is
- * now enforced by the code rather than asserted by the comment.
- */
-export async function POST(req: NextRequest) {
-  try {
-    const authSession = await getBetterAuthSession(req);
-
-    if (!authSession) {
-      return NextResponse.json({
-        error: 'No session found',
-        code: 'UNAUTHORIZED'
-      }, { status: 401 });
-    }
-
-    const sessionToken = authSession.session?.token;
-    if (!sessionToken) {
-      return NextResponse.json({
-        error: 'Invalid session',
-        code: 'INVALID_SESSION'
-      }, { status: 400 });
-    }
-
-    const body = await req.json();
-
-    // Refuse before reading the session: a caller must not learn whether its forged
-    // field would have landed, and nothing should be written on a rejected request.
-    const asserted = CALLER_ASSERTED_FIELDS.filter(
-      ({ field }) => body != null && Object.prototype.hasOwnProperty.call(body, field)
-    );
-    if (asserted.length > 0) {
-      console.warn('[SESSION_ROUTE] REFUSED caller-asserted authentication state', {
-        fields: asserted.map(({ field }) => field),
-        userId: authSession.user?.id,
-      });
-      return NextResponse.json({
-        error: 'This route updates session metadata only. It cannot set authentication state.',
-        code: 'CALLER_ASSERTED_AUTH_STATE',
-        fields: asserted.map(({ field, why }) => ({ field, why })),
-      }, { status: 400 });
-    }
-
-    const { metadata } = body;
-
-    // Get current session from Redis
-    const session = await getRedisSession(sessionToken);
-    if (!session) {
-      return NextResponse.json({
-        error: 'Session not found',
-        code: 'SESSION_NOT_FOUND'
-      }, { status: 404 });
-    }
-
-    // Update session with new data.
-    //
-    // METADATA ONLY. The token and 2FA-verdict writes that used to live here were
-    // removed, not merely guarded: see CALLER_ASSERTED_FIELDS above. Anything that
-    // needs to write authentication state must do so from a path that OBSERVED the
-    // fact - the IDP exchange for tokens, the verification path for the 2FA verdict.
-    const updatedSession = {
-      ...session,
-      ...(metadata ? {
-        metadata: {
-          ...(session.metadata || {}),
-          ...metadata,
-          updatedAt: new Date().toISOString()
-        }
-      } : {})
-    };
-
-    await updateSession(sessionToken, updatedSession);
-
-    return NextResponse.json({
-      success: true,
-      message: 'Session updated successfully'
-    });
-  } catch (error) {
-    const correlationId = logExceptionWithCorrelation('[SESSION_ROUTE] Error updating session:', error);
-    return NextResponse.json({
-      error: 'Failed to update session',
-      code: 'INTERNAL_ERROR',
-      correlationId,
-    }, { status: 500 });
-  }
+/**
+ * Ready-to-Use Session Management Route
+ *
+ * Provides pre-configured session handlers for checking and updating session state.
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/session/route.ts
+ * export { GET, POST } from '@payez/next-mvp/routes/auth/session';
+ * ```
+ *
+ * @version 2.0.0
+ * @since auth-ready-v2
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getSession as getBetterAuthSession } from '../../server/auth';
+import { getSession as getRedisSession, updateSession } from '../../lib/session-store';
+import { logExceptionWithCorrelation } from '../../lib/safe-error-response';
+import { tokenLogId } from '../../lib/token-log-id';
+
+/**
+ * GET /api/auth/session - Check current session status
+ *
+ * Returns the current session information including:
+ * - User details
+ * - Token expiry status
+ * - Session validity
+ */
+export async function GET(req: NextRequest) {
+  try {
+    const authSession = await getBetterAuthSession(req);
+
+    if (!authSession) {
+      console.warn('[SESSION_ROUTE] Better Auth session not found');
+      // MUST return empty {} — useSession() treats any non-empty
+      // response object as "authenticated", causing redirect loops on login page.
+      return NextResponse.json({});
+    }
+
+    const redisSessionId = authSession.session?.token;
+
+    console.log('[SESSION_ROUTE] Session found:', {
+      userId: authSession.user?.id,
+      email: authSession.user?.email,
+      name: authSession.user?.name,
+      redisSessionId: redisSessionId ? tokenLogId(redisSessionId) : 'MISSING',
+    });
+
+    // Fetch full session data from Redis
+    const session = redisSessionId ? await getRedisSession(redisSessionId) : null;
+
+    console.log('[SESSION_ROUTE] Redis session:', {
+      found: !!session,
+      userId: session?.userId,
+      roles: session?.roles,
+      hasAccessToken: !!session?.idpAccessToken,
+    });
+
+    // A Better Auth cookie is NOT authorization. The Redis session is the
+    // authoritative record of what this user is allowed to do; without it we
+    // have no roles and no IDP access token, so there is nothing to authorize
+    // against. Returning a populated user here produces the worst failure mode
+    // available: a client that renders as signed-in and is not.
+    //
+    // MUST return empty {} for the same reason as line 34 — useSession() treats
+    // ANY non-empty response object as "authenticated".
+    //
+    // NOTE: an MFA-pending session IS present in Redis (it just has
+    // mfaVerified=false), so this gate does not break /verify-code. Gating on a
+    // missing accessToken instead WOULD break it.
+    if (!session) {
+      console.error('[SESSION_ROUTE] Redis session MISS — refusing to report authenticated', {
+        userId: authSession.user?.id,
+        redisSessionId: redisSessionId ? tokenLogId(redisSessionId) : 'MISSING',
+        reason: redisSessionId ? 'session expired or evicted' : 'no session token on auth session',
+      });
+      return NextResponse.json({});
+    }
+
+    // Return session format with Redis data
+    // useSession() expects: { user: {...}, expires: "..." }
+    // We enrich with all session data from Redis
+    return NextResponse.json({
+      user: {
+        id: session?.userId || authSession.user?.id,
+        email: session?.email || authSession.user?.email,
+        name: session?.name || authSession.user?.name,
+        image: authSession.user?.image || session?.image || null,
+        // Redis session data
+        roles: session?.roles || [],
+        twoFactorSessionVerified: session?.mfaVerified || false,
+        requiresTwoFactor: !session?.mfaVerified,
+        authenticationMethods: session?.authenticationMethods,
+        authenticationLevel: session?.authenticationLevel,
+        mfaCompletedAt: session?.mfaCompletedAt,
+        mfaExpiresAt: session?.mfaExpiresAt,
+        mfaValidityHours: session?.mfaValidityHours,
+        oauthProvider: session?.oauthProvider,
+        idpClientId: session?.idpClientId,
+        merchantId: session?.merchantId,
+      },
+      // PAY-1481 item 1: NO token material. This body is read by browser JS, so returning the session token and the
+      // IdP access/refresh tokens handed them to any script on the page (the refresh token outlives the session).
+      // Server routes read tokens from the session store; the UI only needs presence and expiry.
+      hasAccessToken: !!session?.idpAccessToken,
+      hasRefreshToken: !!session?.idpRefreshToken,
+      accessTokenExpires: session?.idpAccessTokenExpires,
+      expires: authSession.session?.expiresAt
+        ? new Date(authSession.session.expiresAt).toISOString()
+        : new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+    });
+  } catch (error) {
+    // PAY-1438: pre-auth route - the exception text stays in the log, keyed by correlationId.
+    const correlationId = logExceptionWithCorrelation('[SESSION_ROUTE] Error checking session:', error);
+    return NextResponse.json({
+      error: 'Failed to check session',
+      code: 'INTERNAL_ERROR',
+      correlationId,
+    }, { status: 500 });
+  }
+}
+
+/**
+ * The fields this route USED to accept from the request body and must never accept
+ * again. Cards 308833 (critical) / 312092 (remediation spec) / 318272 / 311425.
+ *
+ * `twoFactorComplete` was written straight through to `mfaVerified`, so a caller
+ * holding any session supplied its OWN second-factor verdict - no factor presented,
+ * no comparison against `amr`, no server-side derivation. The caller can be PRE-2FA,
+ * which makes this a 2FA bypass rather than a user rewriting a flag he had earned.
+ *
+ * The package already states the invariant in four places, in its own voice:
+ *   api-handlers/mfa/totp-verify.ts   - "Enrolment must never set mfaVerified."
+ *   api-handlers/auth/refresh.ts      - "mfaVerified is derived from amrClaims"
+ *   auth/better-auth.ts               - "computed fresh ... re-derived fresh"
+ *   (consumer) passkey-signin-plugin  - "mfaVerified is DERIVED from amr, never asserted."
+ * Every other writer in the estate derives it. This one route took it from an HTTP body.
+ *
+ * PRESENCE, NOT TRUTHINESS, is what is refused - `twoFactorComplete: false` is rejected
+ * exactly like `true`. A caller must not be able to drive this field in EITHER direction,
+ * and per R486/R908 an absent signal is "cannot determine", never a negative assertion.
+ *
+ * REFUSED LOUDLY RATHER THAN IGNORED SILENTLY. Dropping the field would leave a caller
+ * believing it had recorded a 2FA completion that never happened - the same failure shape
+ * as the 4.1.14 -> 4.1.31 history below, where a write nobody read looked like it worked.
+ *
+ * *** DO NOT "FIX" A REGRESSION HERE BY REVERTING THE KEY NORMALIZATION (312092 s2). ***
+ * 4.1.14 had this same unvalidated write but stored bare `accessToken`/`twoFactorComplete`,
+ * keys no reader consulted, so the forgery landed where nothing looked. The 4.1.31
+ * normalization did not introduce the bug - IT ARMED IT. Reverting re-hides the hole and
+ * restores two real client-facing bugs. The write is authorized here instead.
+ */
+const CALLER_ASSERTED_FIELDS: ReadonlyArray<{ field: string; why: string }> = [
+  { field: 'twoFactorComplete', why: 'the second-factor verdict is derived from the IDP token (amr), never asserted by the caller' },
+  { field: 'mfaVerified', why: 'the second-factor verdict is derived from the IDP token (amr), never asserted by the caller' },
+  { field: 'twoFactorMethod', why: 'the method is recorded by the server-side verification path that observed the factor' },
+  { field: 'access_token', why: 'tokens are issued by the IDP; use POST /api/auth/refresh' },
+  { field: 'refresh_token', why: 'tokens are issued by the IDP; use POST /api/auth/refresh' },
+  { field: 'idpAccessToken', why: 'tokens are issued by the IDP; use POST /api/auth/refresh' },
+  { field: 'idpRefreshToken', why: 'tokens are issued by the IDP; use POST /api/auth/refresh' },
+];
+
+/**
+ * POST /api/auth/session - Update session METADATA
+ *
+ * Updates session metadata only. This route holds no authority over authentication
+ * state: it cannot set the 2FA verdict and it cannot set tokens.
+ *
+ * Token refresh uses POST /api/auth/refresh. The 2FA verdict is written only by the
+ * server-side verification path that actually observed the factor.
+ *
+ * Body:
+ * - metadata: object - Custom metadata to store in session
+ *
+ * Any of CALLER_ASSERTED_FIELDS present in the body is a 400. The docstring above used
+ * to promise "metadata (not tokens)" while the handler wrote idpAccessToken,
+ * idpRefreshToken AND mfaVerified - that false parenthetical is the ONLY caution a
+ * mounter reads, and it is how this route came to be mounted (318272). The promise is
+ * now enforced by the code rather than asserted by the comment.
+ */
+export async function POST(req: NextRequest) {
+  try {
+    const authSession = await getBetterAuthSession(req);
+
+    if (!authSession) {
+      return NextResponse.json({
+        error: 'No session found',
+        code: 'UNAUTHORIZED'
+      }, { status: 401 });
+    }
+
+    const sessionToken = authSession.session?.token;
+    if (!sessionToken) {
+      return NextResponse.json({
+        error: 'Invalid session',
+        code: 'INVALID_SESSION'
+      }, { status: 400 });
+    }
+
+    const body = await req.json();
+
+    // Refuse before reading the session: a caller must not learn whether its forged
+    // field would have landed, and nothing should be written on a rejected request.
+    const asserted = CALLER_ASSERTED_FIELDS.filter(
+      ({ field }) => body != null && Object.prototype.hasOwnProperty.call(body, field)
+    );
+    if (asserted.length > 0) {
+      console.warn('[SESSION_ROUTE] REFUSED caller-asserted authentication state', {
+        fields: asserted.map(({ field }) => field),
+        userId: authSession.user?.id,
+      });
+      return NextResponse.json({
+        error: 'This route updates session metadata only. It cannot set authentication state.',
+        code: 'CALLER_ASSERTED_AUTH_STATE',
+        fields: asserted.map(({ field, why }) => ({ field, why })),
+      }, { status: 400 });
+    }
+
+    const { metadata } = body;
+
+    // Get current session from Redis
+    const session = await getRedisSession(sessionToken);
+    if (!session) {
+      return NextResponse.json({
+        error: 'Session not found',
+        code: 'SESSION_NOT_FOUND'
+      }, { status: 404 });
+    }
+
+    // Update session with new data.
+    //
+    // METADATA ONLY. The token and 2FA-verdict writes that used to live here were
+    // removed, not merely guarded: see CALLER_ASSERTED_FIELDS above. Anything that
+    // needs to write authentication state must do so from a path that OBSERVED the
+    // fact - the IDP exchange for tokens, the verification path for the 2FA verdict.
+    const updatedSession = {
+      ...session,
+      ...(metadata ? {
+        metadata: {
+          ...(session.metadata || {}),
+          ...metadata,
+          updatedAt: new Date().toISOString()
+        }
+      } : {})
+    };
+
+    await updateSession(sessionToken, updatedSession);
+
+    return NextResponse.json({
+      success: true,
+      message: 'Session updated successfully'
+    });
+  } catch (error) {
+    const correlationId = logExceptionWithCorrelation('[SESSION_ROUTE] Error updating session:', error);
+    return NextResponse.json({
+      error: 'Failed to update session',
+      code: 'INTERNAL_ERROR',
+      correlationId,
+    }, { status: 500 });
+  }
 }