@payez/next-mvp 4.8.0 → 4.8.2

package/src/api-handlers/auth/update-session.ts

@@ -1,144 +1,144 @@
-/**
- * Authentication Update Session API Handler
- *
- * *** THIS HANDLER DOES NOT PERSIST ANYTHING. IT IS AN ECHO. ***
- *
- * It authenticates the caller, reads `twoFactorSessionVerified` from the REQUEST
- * BODY, and echoes that caller-asserted value straight back. There is no redis
- * write, no cookie write, no JWT mint and no session-store call anywhere in this
- * module - the only `.set(` calls are the security headers below. The 2FA state
- * does NOT survive the request.
- *
- * Do not wire this expecting it to record a second factor. It is kept because
- * live callers POST to it on the 2FA completion path and a 404/501 would break
- * that flow; it is deliberately inert, NOT a session writer. Callers can detect
- * this programmatically via `persisted: false` in the response.
- *
- * Card 391621 measured the consequence: because nothing is stored, downstream
- * 2FA gates read no verified state and FAIL CLOSED. That is why this is an
- * honesty/diagnosability defect rather than an auth bypass - but a future
- * consumer that trusts `success: true` here would be trusting nothing.
- *
- * If you need to actually record 2FA completion, write to the session store
- * (see `../../server/session-store`); do not extend this handler in place.
- *
- * @version 2.1
- * @requires Authentication (authenticated endpoint)
- */
-
-import { NextRequest, NextResponse } from 'next/server';
-import { getSession } from '../../server/auth';
-
-// Add protection headers to all responses
-function addSecurityHeaders(response: NextResponse) {
-  response.headers.set('Content-Security-Policy', "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self'; connect-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'self';");
-  response.headers.set('X-Frame-Options', 'DENY');
-  response.headers.set('X-Content-Type-Options', 'nosniff');
-  response.headers.set('X-XSS-Protection', '1; mode=block');
-  response.headers.set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains; preload');
-  response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
-  response.headers.set('Permissions-Policy', 'geolocation=(), microphone=(), camera=(), payment=(), usb=(), magnetometer=(), gyroscope=(), accelerometer=()');
-  response.headers.set('Cache-Control', 'no-store, no-cache, must-revalidate, proxy-revalidate');
-  response.headers.set('Pragma', 'no-cache');
-  response.headers.set('Expires', '0');
-  return response;
-}
-
-interface UpdateSessionRequest {
-  twoFactorSessionVerified?: boolean;
-  twoFactorMethod?: string;
-}
-
-interface UpdateSessionResponse {
-  success: boolean;
-  twoFactorSessionVerified: boolean;
-  twoFactorMethod?: string;
-  /**
-   * ALWAYS `false`. This handler stores nothing, so the echoed
-   * `twoFactorSessionVerified` above reflects the REQUEST BODY and not any
-   * recorded state. Present so a consumer can detect the no-op without having
-   * to read this file. Additive: no pre-existing field changed meaning.
-   */
-  persisted: false;
-}
-
-/**
- * Creates an update-session handler for Next.js API routes.
- *
- * *** NO-OP: this handler PERSISTS NOTHING. *** It requires a valid session,
- * then echoes the caller-asserted `twoFactorSessionVerified` back with
- * `persisted: false`. See the module header before wiring it.
- *
- * Better Auth resolves its session from cookies, so this handler takes no
- * configuration. Use the default `POST` export below for typical usage.
- *
- * @example
- * ```typescript
- * // In your app's /app/api/auth/update-session/route.ts
- * export { POST } from '@payez/next-mvp/api-handlers/auth/update-session';
- * ```
- */
-export function createUpdateSessionHandler() {
-  return async function POST(req: NextRequest) {
-    try {
-      let body: UpdateSessionRequest;
-
-      try {
-        body = await req.json();
-      } catch (parseError) {
-        return addSecurityHeaders(NextResponse.json(
-          { error: 'Invalid JSON format' },
-          { status: 400 }
-        ));
-      }
-
-      const { twoFactorSessionVerified, twoFactorMethod } = body;
-
-      // Get the current session from Better Auth
-      const session = await getSession(req);
-      if (!session) {
-        return addSecurityHeaders(NextResponse.json(
-          { error: 'No session token available' },
-          { status: 401 }
-        ));
-      }
-
-      // NOT a session update. This object is local, is never written anywhere,
-      // and is discarded when the request ends. Named for what it is so the
-      // next reader cannot mistake it for persisted state.
-      const echoedRequest = {
-        twoFactorSessionVerified: !!twoFactorSessionVerified,
-        twoFactorMethod: twoFactorMethod || (session as any).twoFactorMethod
-      };
-
-      // Previously logged "Session updated successfully", which asserted a write
-      // that never happened and made the no-op invisible in production logs.
-      console.warn('[UPDATE-SESSION] NO-OP: nothing persisted; echoing caller-asserted 2FA state', {
-        userId: session.user?.id,
-        twoFactorSessionVerified: echoedRequest.twoFactorSessionVerified,
-        twoFactorMethod: echoedRequest.twoFactorMethod,
-        persisted: false
-      });
-
-      const responseData: UpdateSessionResponse = {
-        success: true,
-        twoFactorSessionVerified: echoedRequest.twoFactorSessionVerified as boolean,
-        twoFactorMethod: echoedRequest.twoFactorMethod as string | undefined,
-        persisted: false
-      };
-
-      return addSecurityHeaders(NextResponse.json(responseData));
-    } catch (error) {
-      console.error('[UPDATE-SESSION] Error updating session', { error });
-      return addSecurityHeaders(NextResponse.json(
-        { error: 'Failed to update session' },
-        { status: 500 }
-      ));
-    }
-  };
-}
-
-/**
- * Default POST export — drop-in for `app/api/auth/update-session/route.ts`.
- */
-export const POST = createUpdateSessionHandler();
+/**
+ * Authentication Update Session API Handler
+ *
+ * *** THIS HANDLER DOES NOT PERSIST ANYTHING. IT IS AN ECHO. ***
+ *
+ * It authenticates the caller, reads `twoFactorSessionVerified` from the REQUEST
+ * BODY, and echoes that caller-asserted value straight back. There is no redis
+ * write, no cookie write, no JWT mint and no session-store call anywhere in this
+ * module - the only `.set(` calls are the security headers below. The 2FA state
+ * does NOT survive the request.
+ *
+ * Do not wire this expecting it to record a second factor. It is kept because
+ * live callers POST to it on the 2FA completion path and a 404/501 would break
+ * that flow; it is deliberately inert, NOT a session writer. Callers can detect
+ * this programmatically via `persisted: false` in the response.
+ *
+ * Card 391621 measured the consequence: because nothing is stored, downstream
+ * 2FA gates read no verified state and FAIL CLOSED. That is why this is an
+ * honesty/diagnosability defect rather than an auth bypass - but a future
+ * consumer that trusts `success: true` here would be trusting nothing.
+ *
+ * If you need to actually record 2FA completion, write to the session store
+ * (see `../../server/session-store`); do not extend this handler in place.
+ *
+ * @version 2.1
+ * @requires Authentication (authenticated endpoint)
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getSession } from '../../server/auth';
+
+// Add protection headers to all responses
+function addSecurityHeaders(response: NextResponse) {
+  response.headers.set('Content-Security-Policy', "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self'; connect-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'self';");
+  response.headers.set('X-Frame-Options', 'DENY');
+  response.headers.set('X-Content-Type-Options', 'nosniff');
+  response.headers.set('X-XSS-Protection', '1; mode=block');
+  response.headers.set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains; preload');
+  response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
+  response.headers.set('Permissions-Policy', 'geolocation=(), microphone=(), camera=(), payment=(), usb=(), magnetometer=(), gyroscope=(), accelerometer=()');
+  response.headers.set('Cache-Control', 'no-store, no-cache, must-revalidate, proxy-revalidate');
+  response.headers.set('Pragma', 'no-cache');
+  response.headers.set('Expires', '0');
+  return response;
+}
+
+interface UpdateSessionRequest {
+  twoFactorSessionVerified?: boolean;
+  twoFactorMethod?: string;
+}
+
+interface UpdateSessionResponse {
+  success: boolean;
+  twoFactorSessionVerified: boolean;
+  twoFactorMethod?: string;
+  /**
+   * ALWAYS `false`. This handler stores nothing, so the echoed
+   * `twoFactorSessionVerified` above reflects the REQUEST BODY and not any
+   * recorded state. Present so a consumer can detect the no-op without having
+   * to read this file. Additive: no pre-existing field changed meaning.
+   */
+  persisted: false;
+}
+
+/**
+ * Creates an update-session handler for Next.js API routes.
+ *
+ * *** NO-OP: this handler PERSISTS NOTHING. *** It requires a valid session,
+ * then echoes the caller-asserted `twoFactorSessionVerified` back with
+ * `persisted: false`. See the module header before wiring it.
+ *
+ * Better Auth resolves its session from cookies, so this handler takes no
+ * configuration. Use the default `POST` export below for typical usage.
+ *
+ * @example
+ * ```typescript
+ * // In your app's /app/api/auth/update-session/route.ts
+ * export { POST } from '@payez/next-mvp/api-handlers/auth/update-session';
+ * ```
+ */
+export function createUpdateSessionHandler() {
+  return async function POST(req: NextRequest) {
+    try {
+      let body: UpdateSessionRequest;
+
+      try {
+        body = await req.json();
+      } catch (parseError) {
+        return addSecurityHeaders(NextResponse.json(
+          { error: 'Invalid JSON format' },
+          { status: 400 }
+        ));
+      }
+
+      const { twoFactorSessionVerified, twoFactorMethod } = body;
+
+      // Get the current session from Better Auth
+      const session = await getSession(req);
+      if (!session) {
+        return addSecurityHeaders(NextResponse.json(
+          { error: 'No session token available' },
+          { status: 401 }
+        ));
+      }
+
+      // NOT a session update. This object is local, is never written anywhere,
+      // and is discarded when the request ends. Named for what it is so the
+      // next reader cannot mistake it for persisted state.
+      const echoedRequest = {
+        twoFactorSessionVerified: !!twoFactorSessionVerified,
+        twoFactorMethod: twoFactorMethod || (session as any).twoFactorMethod
+      };
+
+      // Previously logged "Session updated successfully", which asserted a write
+      // that never happened and made the no-op invisible in production logs.
+      console.warn('[UPDATE-SESSION] NO-OP: nothing persisted; echoing caller-asserted 2FA state', {
+        userId: session.user?.id,
+        twoFactorSessionVerified: echoedRequest.twoFactorSessionVerified,
+        twoFactorMethod: echoedRequest.twoFactorMethod,
+        persisted: false
+      });
+
+      const responseData: UpdateSessionResponse = {
+        success: true,
+        twoFactorSessionVerified: echoedRequest.twoFactorSessionVerified as boolean,
+        twoFactorMethod: echoedRequest.twoFactorMethod as string | undefined,
+        persisted: false
+      };
+
+      return addSecurityHeaders(NextResponse.json(responseData));
+    } catch (error) {
+      console.error('[UPDATE-SESSION] Error updating session', { error });
+      return addSecurityHeaders(NextResponse.json(
+        { error: 'Failed to update session' },
+        { status: 500 }
+      ));
+    }
+  };
+}
+
+/**
+ * Default POST export — drop-in for `app/api/auth/update-session/route.ts`.
+ */
+export const POST = createUpdateSessionHandler();

package/src/api-handlers/auth/validate.ts

@@ -1,46 +1,46 @@
-import { NextRequest, NextResponse } from 'next/server';
-import { idpFetchJSON } from '../../lib/idp-fetch';
-import { ENV_CONFIG, API_ENDPOINTS } from '../../config/env';
-import { getTokenTestAware } from '../../lib/test-aware-get-token';
-import { getSession } from '../../lib/session-store';
-import { logExceptionWithCorrelation, projectIdpError } from '../../lib/safe-error-response';
-
-/**
- * Validates current access token with the IDP and returns normalized info.
- * Sources access token from Authorization header or Redis session via cookie.
- */
-export async function GET(req: NextRequest) {
-  try {
-    // 1) Prefer Authorization header if present
-    let bearer: string | undefined = undefined;
-    const authHeader = req.headers.get('authorization') || req.headers.get('Authorization');
-    if (authHeader && /^Bearer\s+/i.test(authHeader)) bearer = authHeader.replace(/^Bearer\s+/i, '').trim();
-
-    // 2) If not, resolve from session
-    if (!bearer) {
-      const tok = await getTokenTestAware(req);
-      const sessionToken = tok?.sessionToken as string | undefined;
-      if (sessionToken) {
-        const sess = await getSession(sessionToken);
-        bearer = sess?.accessToken;
-      }
-    }
-
-    if (!bearer) {
-      return NextResponse.json({ success: false, error: { code: 'UNAUTHORIZED', message: 'No access token available' } }, { status: 401 });
-    }
-
-    const url = `${ENV_CONFIG.IDP_URL}${API_ENDPOINTS.externalAuth.validate}`;
-    const result = await idpFetchJSON(req, url, { method: 'GET', headers: { Authorization: `Bearer ${bearer}` } });
-
-    if (!result.ok) {
-      return NextResponse.json({ success: false, error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: projectIdpError(result.json) } }, { status: result.status });
-    }
-
-    // Passthrough normalized
-    return NextResponse.json(result.json ?? { success: true }, { status: 200 });
-  } catch (e: any) {
-    const correlationId = logExceptionWithCorrelation('[AUTH_VALIDATE] Error:', e);
-    return NextResponse.json({ success: false, error: { code: 'INTERNAL_SERVER_ERROR', message: 'validate error', correlationId } }, { status: 500 });
-  }
+import { NextRequest, NextResponse } from 'next/server';
+import { idpFetchJSON } from '../../lib/idp-fetch';
+import { ENV_CONFIG, API_ENDPOINTS } from '../../config/env';
+import { getTokenTestAware } from '../../lib/test-aware-get-token';
+import { getSession } from '../../lib/session-store';
+import { logExceptionWithCorrelation, projectIdpError } from '../../lib/safe-error-response';
+
+/**
+ * Validates current access token with the IDP and returns normalized info.
+ * Sources access token from Authorization header or Redis session via cookie.
+ */
+export async function GET(req: NextRequest) {
+  try {
+    // 1) Prefer Authorization header if present
+    let bearer: string | undefined = undefined;
+    const authHeader = req.headers.get('authorization') || req.headers.get('Authorization');
+    if (authHeader && /^Bearer\s+/i.test(authHeader)) bearer = authHeader.replace(/^Bearer\s+/i, '').trim();
+
+    // 2) If not, resolve from session
+    if (!bearer) {
+      const tok = await getTokenTestAware(req);
+      const sessionToken = tok?.sessionToken as string | undefined;
+      if (sessionToken) {
+        const sess = await getSession(sessionToken);
+        bearer = sess?.accessToken;
+      }
+    }
+
+    if (!bearer) {
+      return NextResponse.json({ success: false, error: { code: 'UNAUTHORIZED', message: 'No access token available' } }, { status: 401 });
+    }
+
+    const url = `${ENV_CONFIG.IDP_URL}${API_ENDPOINTS.externalAuth.validate}`;
+    const result = await idpFetchJSON(req, url, { method: 'GET', headers: { Authorization: `Bearer ${bearer}` } });
+
+    if (!result.ok) {
+      return NextResponse.json({ success: false, error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: projectIdpError(result.json) } }, { status: result.status });
+    }
+
+    // Passthrough normalized
+    return NextResponse.json(result.json ?? { success: true }, { status: 200 });
+  } catch (e: any) {
+    const correlationId = logExceptionWithCorrelation('[AUTH_VALIDATE] Error:', e);
+    return NextResponse.json({ success: false, error: { code: 'INTERNAL_SERVER_ERROR', message: 'validate error', correlationId } }, { status: 500 });
+  }
 }

package/src/api-handlers/auth/verify-code.ts

@@ -1,116 +1,116 @@
-/**
- * Authentication Verify Code / Complete 2FA API Handler
- *
- * Handles 2FA verification and token updates after successful verification.
- * This handler is designed to be imported and used by Next.js applications
- * using the @payez/next-mvp package.
- *
- * @version 2.0
- * @requires Authentication (authenticated endpoint)
- */
-
-import { NextRequest, NextResponse } from 'next/server';
-import { getSession } from '../../server/auth';
-import { updateTokens, mark2FAComplete } from '../../lib/session-store';
-import { tokenLogId } from '../../lib/token-log-id';
-
-interface VerifyCodeRequest {
-  accessToken: string;
-  refreshToken: string;
-  accessTokenExpires: number;
-  refreshTokenExpires?: number;
-}
-
-/**
- * Creates a verify-code/complete-2FA handler for Next.js API routes.
- *
- * Better Auth resolves its session from cookies, so this handler takes no
- * configuration. Use the default `POST` export below for typical usage.
- *
- * @example
- * ```typescript
- * // In your app's /app/api/auth/verify-code/route.ts
- * export { POST } from '@payez/next-mvp/api-handlers/auth/verify-code';
- * ```
- */
-export function createVerifyCodeHandler() {
-  return async function POST(req: NextRequest) {
-    try {
-      let body: VerifyCodeRequest;
-
-      try {
-        body = await req.json();
-      } catch (parseError) {
-        return NextResponse.json(
-          { success: false, message: 'Invalid JSON format' },
-          { status: 400 }
-        );
-      }
-
-      const { accessToken, refreshToken, accessTokenExpires, refreshTokenExpires } = body;
-
-      // Get current session from Better Auth
-      const betterAuthSession = await getSession(req);
-
-      const sessionToken = betterAuthSession?.session?.token as string;
-
-      if (!sessionToken) {
-        console.error('[VERIFY-CODE] No session token found', {
-          hasSession: !!betterAuthSession,
-        });
-        return NextResponse.json(
-          { success: false, message: 'No session found' },
-          { status: 401 }
-        );
-      }
-
-      console.info('[VERIFY-CODE] Updating session with new tokens after 2FA', {
-        sessionToken: tokenLogId(sessionToken),
-        userId: betterAuthSession?.user?.id,
-        hasAccessToken: !!accessToken,
-        hasRefreshToken: !!refreshToken,
-        accessTokenLength: accessToken?.length,
-        refreshTokenLength: refreshToken?.length
-      });
-
-      // Update tokens in Redis
-      await updateTokens(
-        sessionToken,
-        accessToken,
-        refreshToken,
-        accessTokenExpires,
-        refreshTokenExpires
-      );
-
-      // Mark 2FA as complete.
-      // 339563: pass the stepped-up access token so the session gets an
-      // mfaExpiresAt alongside mfaVerified. Without it the gate's `> 0` guard
-      // treats the missing expiry as "never expires".
-      await mark2FAComplete(sessionToken, accessToken);
-
-      console.info('[VERIFY-CODE] 2FA completion successful', {
-        sessionToken: tokenLogId(sessionToken),
-        userId: betterAuthSession?.user?.id
-      });
-
-      return NextResponse.json({
-        success: true,
-        message: '2FA verification complete'
-      });
-    } catch (error) {
-      console.error('[VERIFY-CODE] Failed to complete 2FA', {
-        error: error instanceof Error ? error.message : String(error)
-      });
-
-      return NextResponse.json(
-        { success: false, message: 'Failed to complete 2FA' },
-        { status: 500 }
-      );
-    }
-  };
-}
-
-/**
- * Default POST export — drop-in for `app/api/auth/verify-code/route.ts`.
- */
-export const POST = createVerifyCodeHandler();
+/**
+ * Authentication Verify Code / Complete 2FA API Handler
+ *
+ * Handles 2FA verification and token updates after successful verification.
+ * This handler is designed to be imported and used by Next.js applications
+ * using the @payez/next-mvp package.
+ *
+ * @version 2.0
+ * @requires Authentication (authenticated endpoint)
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getSession } from '../../server/auth';
+import { updateTokens, mark2FAComplete } from '../../lib/session-store';
+import { tokenLogId } from '../../lib/token-log-id';
+
+interface VerifyCodeRequest {
+  accessToken: string;
+  refreshToken: string;
+  accessTokenExpires: number;
+  refreshTokenExpires?: number;
+}
+
+/**
+ * Creates a verify-code/complete-2FA handler for Next.js API routes.
+ *
+ * Better Auth resolves its session from cookies, so this handler takes no
+ * configuration. Use the default `POST` export below for typical usage.
+ *
+ * @example
+ * ```typescript
+ * // In your app's /app/api/auth/verify-code/route.ts
+ * export { POST } from '@payez/next-mvp/api-handlers/auth/verify-code';
+ * ```
+ */
+export function createVerifyCodeHandler() {
+  return async function POST(req: NextRequest) {
+    try {
+      let body: VerifyCodeRequest;
+
+      try {
+        body = await req.json();
+      } catch (parseError) {
+        return NextResponse.json(
+          { success: false, message: 'Invalid JSON format' },
+          { status: 400 }
+        );
+      }
+
+      const { accessToken, refreshToken, accessTokenExpires, refreshTokenExpires } = body;
+
+      // Get current session from Better Auth
+      const betterAuthSession = await getSession(req);
+
+      const sessionToken = betterAuthSession?.session?.token as string;
+
+      if (!sessionToken) {
+        console.error('[VERIFY-CODE] No session token found', {
+          hasSession: !!betterAuthSession,
+        });
+        return NextResponse.json(
+          { success: false, message: 'No session found' },
+          { status: 401 }
+        );
+      }
+
+      console.info('[VERIFY-CODE] Updating session with new tokens after 2FA', {
+        sessionToken: tokenLogId(sessionToken),
+        userId: betterAuthSession?.user?.id,
+        hasAccessToken: !!accessToken,
+        hasRefreshToken: !!refreshToken,
+        accessTokenLength: accessToken?.length,
+        refreshTokenLength: refreshToken?.length
+      });
+
+      // Update tokens in Redis
+      await updateTokens(
+        sessionToken,
+        accessToken,
+        refreshToken,
+        accessTokenExpires,
+        refreshTokenExpires
+      );
+
+      // Mark 2FA as complete.
+      // 339563: pass the stepped-up access token so the session gets an
+      // mfaExpiresAt alongside mfaVerified. Without it the gate's `> 0` guard
+      // treats the missing expiry as "never expires".
+      await mark2FAComplete(sessionToken, accessToken);
+
+      console.info('[VERIFY-CODE] 2FA completion successful', {
+        sessionToken: tokenLogId(sessionToken),
+        userId: betterAuthSession?.user?.id
+      });
+
+      return NextResponse.json({
+        success: true,
+        message: '2FA verification complete'
+      });
+    } catch (error) {
+      console.error('[VERIFY-CODE] Failed to complete 2FA', {
+        error: error instanceof Error ? error.message : String(error)
+      });
+
+      return NextResponse.json(
+        { success: false, message: 'Failed to complete 2FA' },
+        { status: 500 }
+      );
+    }
+  };
+}
+
+/**
+ * Default POST export — drop-in for `app/api/auth/verify-code/route.ts`.
+ */
+export const POST = createVerifyCodeHandler();