@payez/next-mvp 4.8.0 → 4.8.2

package/src/routes/auth/logout.ts

@@ -1,112 +1,112 @@
-/**
- * Ready-to-Use Logout Route
- *
- * Provides a pre-configured logout handler that properly cleans up
- * sessions and revokes tokens.
- *
- * @example
- * ```typescript
- * // app/api/auth/logout/route.ts
- * export { POST } from '@payez/next-mvp/routes/auth/logout';
- * ```
- *
- * @version 2.0.0
- * @since auth-ready-v2
- */
-
-import { NextRequest, NextResponse } from 'next/server';
-import { getSession } from '../../server/auth';
-import { deleteSessionEverywhere } from '../../lib/session-store';
-import {
-  getSessionCookieName,
-  getSecureSessionCookieName,
-  getCsrfCookieName,
-  getSecureCsrfCookieName,
-  getCallbackUrlCookieName,
-} from '../../lib/app-slug';
-import { siteEvents, getClientIp } from '../../lib/site-logger';
-import { logExceptionWithCorrelation } from '../../lib/safe-error-response';
-
-/**
- * POST /api/auth/logout - Sign out and clean up session
- *
- * Performs complete logout:
- * 1. Revokes tokens at IDP (if refresh token available)
- * 2. Deletes session from store
- * 3. Clears session cookies
- */
-export async function POST(req: NextRequest) {
-  try {
-    const session = await getSession(req);
-
-    if (!session) {
-      // Already logged out
-      return NextResponse.json({
-        success: true,
-        message: 'No active session'
-      });
-    }
-
-    const sessionId = session.session?.token;
-
-    // Delete session from EVERY store — canonical + BA secondary (181922).
-    // Canonical-only deletion let the ba: record resurrect the session.
-    if (sessionId) {
-      try {
-        await deleteSessionEverywhere(sessionId);
-        console.info('[LOGOUT_ROUTE] Session deleted from store');
-      } catch (error) {
-        console.warn('[LOGOUT_ROUTE] Failed to delete session:', error);
-      }
-    }
-
-    // Log logout event (fire-and-forget)
-    const userId = session.user?.id;
-    if (userId) {
-      siteEvents.logout({
-        user_id: userId,
-        session_id: sessionId,
-        trigger: 'user',
-        url: '/api/auth/logout',
-        user_agent: req.headers.get('user-agent') || undefined,
-        ip_address: getClientIp(req.headers) || undefined,
-      });
-    }
-
-    // Build response that clears session cookies
-    const response = NextResponse.json({
-      success: true,
-      message: 'Logged out successfully'
-    });
-
-    // Clear NextAuth session cookies (using app-slug prefixed names)
-    const cookieNames = [
-      getSessionCookieName(),
-      getSecureSessionCookieName(),
-      getCsrfCookieName(),
-      getSecureCsrfCookieName(),
-      getCallbackUrlCookieName(),
-      `__Secure-${getCallbackUrlCookieName()}`,
-    ];
-
-    // Clear each cookie by setting it with maxAge 0
-    cookieNames.forEach(name => {
-      response.cookies.set(name, '', {
-        maxAge: 0,
-        path: '/',
-        httpOnly: true,
-        secure: process.env.NODE_ENV === 'production',
-        sameSite: 'lax'
-      });
-    });
-
-    return response;
-  } catch (error) {
-    const correlationId = logExceptionWithCorrelation('[LOGOUT_ROUTE] Error during logout:', error);
-    return NextResponse.json({
-      error: 'Failed to logout',
-      code: 'INTERNAL_ERROR',
-      correlationId,
-    }, { status: 500 });
-  }
+/**
+ * Ready-to-Use Logout Route
+ *
+ * Provides a pre-configured logout handler that properly cleans up
+ * sessions and revokes tokens.
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/logout/route.ts
+ * export { POST } from '@payez/next-mvp/routes/auth/logout';
+ * ```
+ *
+ * @version 2.0.0
+ * @since auth-ready-v2
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { getSession } from '../../server/auth';
+import { deleteSessionEverywhere } from '../../lib/session-store';
+import {
+  getSessionCookieName,
+  getSecureSessionCookieName,
+  getCsrfCookieName,
+  getSecureCsrfCookieName,
+  getCallbackUrlCookieName,
+} from '../../lib/app-slug';
+import { siteEvents, getClientIp } from '../../lib/site-logger';
+import { logExceptionWithCorrelation } from '../../lib/safe-error-response';
+
+/**
+ * POST /api/auth/logout - Sign out and clean up session
+ *
+ * Performs complete logout:
+ * 1. Revokes tokens at IDP (if refresh token available)
+ * 2. Deletes session from store
+ * 3. Clears session cookies
+ */
+export async function POST(req: NextRequest) {
+  try {
+    const session = await getSession(req);
+
+    if (!session) {
+      // Already logged out
+      return NextResponse.json({
+        success: true,
+        message: 'No active session'
+      });
+    }
+
+    const sessionId = session.session?.token;
+
+    // Delete session from EVERY store — canonical + BA secondary (181922).
+    // Canonical-only deletion let the ba: record resurrect the session.
+    if (sessionId) {
+      try {
+        await deleteSessionEverywhere(sessionId);
+        console.info('[LOGOUT_ROUTE] Session deleted from store');
+      } catch (error) {
+        console.warn('[LOGOUT_ROUTE] Failed to delete session:', error);
+      }
+    }
+
+    // Log logout event (fire-and-forget)
+    const userId = session.user?.id;
+    if (userId) {
+      siteEvents.logout({
+        user_id: userId,
+        session_id: sessionId,
+        trigger: 'user',
+        url: '/api/auth/logout',
+        user_agent: req.headers.get('user-agent') || undefined,
+        ip_address: getClientIp(req.headers) || undefined,
+      });
+    }
+
+    // Build response that clears session cookies
+    const response = NextResponse.json({
+      success: true,
+      message: 'Logged out successfully'
+    });
+
+    // Clear NextAuth session cookies (using app-slug prefixed names)
+    const cookieNames = [
+      getSessionCookieName(),
+      getSecureSessionCookieName(),
+      getCsrfCookieName(),
+      getSecureCsrfCookieName(),
+      getCallbackUrlCookieName(),
+      `__Secure-${getCallbackUrlCookieName()}`,
+    ];
+
+    // Clear each cookie by setting it with maxAge 0
+    cookieNames.forEach(name => {
+      response.cookies.set(name, '', {
+        maxAge: 0,
+        path: '/',
+        httpOnly: true,
+        secure: process.env.NODE_ENV === 'production',
+        sameSite: 'lax'
+      });
+    });
+
+    return response;
+  } catch (error) {
+    const correlationId = logExceptionWithCorrelation('[LOGOUT_ROUTE] Error during logout:', error);
+    return NextResponse.json({
+      error: 'Failed to logout',
+      code: 'INTERNAL_ERROR',
+      correlationId,
+    }, { status: 500 });
+  }
 }

package/src/routes/auth/nextauth.ts

@@ -1,45 +1,45 @@
-/**
- * Ready-to-Use Auth Route Handler (Better Auth)
- *
- * Provides a pre-configured Better Auth handler that uses dynamic OAuth providers
- * loaded from IDP at startup.
- *
- * Replaces the former NextAuth handler. The file name is kept as nextauth.ts
- * to avoid breaking re-exports in routes/auth/index.ts.
- *
- * @version 4.0.0 - Better Auth migration
- * @since better-auth-4.0
- */
-
-import { getBetterAuthHandler } from '../../auth/better-auth';
-import { NextResponse } from 'next/server';
-
-/**
- * GET handler for auth routes
- * Delegates to Better Auth instance.
- */
-export async function GET(request: Request) {
-  const handler = await getBetterAuthHandler();
-  if (!handler) {
-    return NextResponse.json(
-      { error: 'Auth handler not available' },
-      { status: 503 }
-    );
-  }
-  return handler.GET(request);
-}
-
-/**
- * POST handler for auth routes
- * Delegates to Better Auth instance.
- */
-export async function POST(request: Request) {
-  const handler = await getBetterAuthHandler();
-  if (!handler) {
-    return NextResponse.json(
-      { error: 'Auth handler not available' },
-      { status: 503 }
-    );
-  }
-  return handler.POST(request);
-}
+/**
+ * Ready-to-Use Auth Route Handler (Better Auth)
+ *
+ * Provides a pre-configured Better Auth handler that uses dynamic OAuth providers
+ * loaded from IDP at startup.
+ *
+ * Replaces the former NextAuth handler. The file name is kept as nextauth.ts
+ * to avoid breaking re-exports in routes/auth/index.ts.
+ *
+ * @version 4.0.0 - Better Auth migration
+ * @since better-auth-4.0
+ */
+
+import { getBetterAuthHandler } from '../../auth/better-auth';
+import { NextResponse } from 'next/server';
+
+/**
+ * GET handler for auth routes
+ * Delegates to Better Auth instance.
+ */
+export async function GET(request: Request) {
+  const handler = await getBetterAuthHandler();
+  if (!handler) {
+    return NextResponse.json(
+      { error: 'Auth handler not available' },
+      { status: 503 }
+    );
+  }
+  return handler.GET(request);
+}
+
+/**
+ * POST handler for auth routes
+ * Delegates to Better Auth instance.
+ */
+export async function POST(request: Request) {
+  const handler = await getBetterAuthHandler();
+  if (!handler) {
+    return NextResponse.json(
+      { error: 'Auth handler not available' },
+      { status: 503 }
+    );
+  }
+  return handler.POST(request);
+}

package/src/routes/auth/passkey-signin.ts

@@ -1,13 +1,13 @@
-/**
- * Ready-to-Use Passkey Sign-In Route (ANONYMOUS ceremony)
- *
- * @example
- * ```typescript
- * // app/api/passkey/sign-in/options/route.ts
- * export { POST } from '@payez/next-mvp/routes/auth/passkey-signin';
- * // (optionsPOST is exported as POST; mount verify at its own path:)
- * // app/api/passkey/sign-in/verify/route.ts
- * export { verifyPOST as POST } from '@payez/next-mvp/routes/auth/passkey-signin';
- * ```
- */
-export { optionsPOST, verifyPOST } from '../../api-handlers/auth/passkey-signin';
+/**
+ * Ready-to-Use Passkey Sign-In Route (ANONYMOUS ceremony)
+ *
+ * @example
+ * ```typescript
+ * // app/api/passkey/sign-in/options/route.ts
+ * export { POST } from '@payez/next-mvp/routes/auth/passkey-signin';
+ * // (optionsPOST is exported as POST; mount verify at its own path:)
+ * // app/api/passkey/sign-in/verify/route.ts
+ * export { verifyPOST as POST } from '@payez/next-mvp/routes/auth/passkey-signin';
+ * ```
+ */
+export { optionsPOST, verifyPOST } from '../../api-handlers/auth/passkey-signin';

package/src/routes/auth/refresh.ts

@@ -1,78 +1,78 @@
-/**
- * Ready-to-Use Refresh Token Route
- *
- * Provides a pre-configured refresh handler that can be imported directly
- * into your app's API routes with zero configuration.
- *
- * @example
- * ```typescript
- * // app/api/auth/refresh/route.ts
- * export { POST } from '@payez/next-mvp/routes/auth/refresh';
- * ```
- *
- * @version 2.0.0
- * @since auth-ready-v2
- */
-
-import { createRefreshHandler } from '../../api-handlers/auth/refresh';
-
-/**
- * Resolve the client id from environment variables.
- *
- * Was: `process.env.CLIENT_ID || process.env.NEXT_PUBLIC_IDP_CLIENT_ID || ''`
- * That fallback to empty string made "we do not know the client" indistinguishable from
- * "the client id is blank". Callers cannot tell absence from a known-empty value.
- *
- * Card 221076 / 223542: absence is now `null`, which is representable and still falsy,
- * so existing `if (!clientId)` guards behave exactly as before.
- * (Ported verbatim from qapert-nighthawk/221076, where this fix already existed;
- * the qa/222363 line carried viability's half but never got refresh's.)
- */
-function resolveClientId(): string | null {
-  const clientId = process.env.CLIENT_ID || process.env.NEXT_PUBLIC_IDP_CLIENT_ID;
-  if (clientId) {
-    return clientId;
-  }
-  return null;
-}
-
-// Configuration is read at runtime from environment.
-function getConfig() {
-  const idpBaseUrl = process.env.IDP_URL;
-  if (!idpBaseUrl) {
-    throw new Error('[IDP_URL] FATAL: IDP_URL environment variable is REQUIRED.');
-  }
-  const clientId = resolveClientId();
-  if (!clientId) {
-    // Card 221076 / 223542: absence must be detectable, not collapsed to a default.
-    console.warn(
-      '[REFRESH_ROUTE] No CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID configured. ' +
-        'Token refresh will be attempted, but the server cannot identify which client ' +
-        'initiated the request. This may fail if the IDP requires a client ID.'
-    );
-  }
-  return {
-    idpBaseUrl,
-    clientId: clientId || 'payez_default_client', // Handler-safe fallback
-    refreshEndpoint: process.env.REFRESH_ENDPOINT || '/api/ExternalAuth/refresh',
-  };
-}
-
-/**
- * Pre-configured POST handler for token refresh
- *
- * Environment variables used:
- * - IDP_URL (REQUIRED)
- * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
- * - REFRESH_ENDPOINT (default: /api/ExternalAuth/refresh)
- */
-let _handler: ReturnType<typeof createRefreshHandler> | null = null;
-
-import { NextRequest } from 'next/server';
-
-export async function POST(req: NextRequest) {
-  if (!_handler) {
-    _handler = createRefreshHandler(getConfig());
-  }
-  return _handler(req);
+/**
+ * Ready-to-Use Refresh Token Route
+ *
+ * Provides a pre-configured refresh handler that can be imported directly
+ * into your app's API routes with zero configuration.
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/refresh/route.ts
+ * export { POST } from '@payez/next-mvp/routes/auth/refresh';
+ * ```
+ *
+ * @version 2.0.0
+ * @since auth-ready-v2
+ */
+
+import { createRefreshHandler } from '../../api-handlers/auth/refresh';
+
+/**
+ * Resolve the client id from environment variables.
+ *
+ * Was: `process.env.CLIENT_ID || process.env.NEXT_PUBLIC_IDP_CLIENT_ID || ''`
+ * That fallback to empty string made "we do not know the client" indistinguishable from
+ * "the client id is blank". Callers cannot tell absence from a known-empty value.
+ *
+ * Card 221076 / 223542: absence is now `null`, which is representable and still falsy,
+ * so existing `if (!clientId)` guards behave exactly as before.
+ * (Ported verbatim from qapert-nighthawk/221076, where this fix already existed;
+ * the qa/222363 line carried viability's half but never got refresh's.)
+ */
+function resolveClientId(): string | null {
+  const clientId = process.env.CLIENT_ID || process.env.NEXT_PUBLIC_IDP_CLIENT_ID;
+  if (clientId) {
+    return clientId;
+  }
+  return null;
+}
+
+// Configuration is read at runtime from environment.
+function getConfig() {
+  const idpBaseUrl = process.env.IDP_URL;
+  if (!idpBaseUrl) {
+    throw new Error('[IDP_URL] FATAL: IDP_URL environment variable is REQUIRED.');
+  }
+  const clientId = resolveClientId();
+  if (!clientId) {
+    // Card 221076 / 223542: absence must be detectable, not collapsed to a default.
+    console.warn(
+      '[REFRESH_ROUTE] No CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID configured. ' +
+        'Token refresh will be attempted, but the server cannot identify which client ' +
+        'initiated the request. This may fail if the IDP requires a client ID.'
+    );
+  }
+  return {
+    idpBaseUrl,
+    clientId: clientId || 'payez_default_client', // Handler-safe fallback
+    refreshEndpoint: process.env.REFRESH_ENDPOINT || '/api/ExternalAuth/refresh',
+  };
+}
+
+/**
+ * Pre-configured POST handler for token refresh
+ *
+ * Environment variables used:
+ * - IDP_URL (REQUIRED)
+ * - CLIENT_ID or NEXT_PUBLIC_IDP_CLIENT_ID (required)
+ * - REFRESH_ENDPOINT (default: /api/ExternalAuth/refresh)
+ */
+let _handler: ReturnType<typeof createRefreshHandler> | null = null;
+
+import { NextRequest } from 'next/server';
+
+export async function POST(req: NextRequest) {
+  if (!_handler) {
+    _handler = createRefreshHandler(getConfig());
+  }
+  return _handler(req);
 }

package/src/routes/auth/session-reset.ts

@@ -1,37 +1,37 @@
-/**
- * PAY-2218 PR 2: the session-reset route. Mount it at app/api/auth/session-reset/route.ts:
- *
- *     export { GET } from '@payez/next-mvp/routes/auth/session-reset';
- *
- * and turn it on with createMvpMiddleware({ sessionResetRoute: true }). The middleware then sends a page's
- * session-ending redirect (stale session, force-invalidated, pre-2FA timeout, refresh 401/403) here instead of
- * clearing the cookies itself. See src/auth/session-reset-link.ts for the measurements behind each rule.
- *
- *  - Router PREFETCH (the route sees `next-router-prefetch`, which Next strips before middleware): 204 + no-store,
- *    no redirect, no Set-Cookie. A redirect here would be cached by the 15.5.x router and reused by the click, so
- *    the real navigation would never come back to clear.
- *  - Real navigation with a valid signed hand-off: expire the session cookies and 307 to the login page.
- *  - Anything unsigned, tampered, expired, or bound to a DIFFERENT session than this request's cookie: 307 to the
- *    login page and touch NO cookie (nobody can link a signed-in user here to log them out; a second use is a no-op).
- *
- * The login URL is always rebuilt from allowlisted parts; the route never redirects to a URL it was given.
- */
-import { NextRequest, NextResponse } from 'next/server';
-import { isPrefetchRequest } from '../../middleware/create-middleware';
-import { expireSessionCookies } from '../../auth/session-cookie-clear';
-import { getSessionCookieName, getSecureSessionCookieName } from '../../lib/app-slug';
-import { boundSessionCookie, loginLocation, readResetRequest, resetSecret } from '../../auth/session-reset-link';
-
-export const dynamic = 'force-dynamic';
-
-export async function GET(request: NextRequest): Promise<NextResponse> {
-  if (isPrefetchRequest(request)) {
-    return new NextResponse(null, { status: 204, headers: { 'cache-control': 'no-store' } });
-  }
-  const bound = boundSessionCookie((n) => request.cookies.get(n)?.value, getSessionCookieName(), getSecureSessionCookieName());
-  const { params, signed } = await readResetRequest(request.nextUrl.searchParams, resetSecret(), bound);
-  const response = NextResponse.redirect(new URL(loginLocation(params), request.url), 307);
-  response.headers.set('cache-control', 'no-store');
-  if (signed) expireSessionCookies(response, Array.from(request.cookies, ([name]) => name));
-  return response;
-}
+/**
+ * PAY-2218 PR 2: the session-reset route. Mount it at app/api/auth/session-reset/route.ts:
+ *
+ *     export { GET } from '@payez/next-mvp/routes/auth/session-reset';
+ *
+ * and turn it on with createMvpMiddleware({ sessionResetRoute: true }). The middleware then sends a page's
+ * session-ending redirect (stale session, force-invalidated, pre-2FA timeout, refresh 401/403) here instead of
+ * clearing the cookies itself. See src/auth/session-reset-link.ts for the measurements behind each rule.
+ *
+ *  - Router PREFETCH (the route sees `next-router-prefetch`, which Next strips before middleware): 204 + no-store,
+ *    no redirect, no Set-Cookie. A redirect here would be cached by the 15.5.x router and reused by the click, so
+ *    the real navigation would never come back to clear.
+ *  - Real navigation with a valid signed hand-off: expire the session cookies and 307 to the login page.
+ *  - Anything unsigned, tampered, expired, or bound to a DIFFERENT session than this request's cookie: 307 to the
+ *    login page and touch NO cookie (nobody can link a signed-in user here to log them out; a second use is a no-op).
+ *
+ * The login URL is always rebuilt from allowlisted parts; the route never redirects to a URL it was given.
+ */
+import { NextRequest, NextResponse } from 'next/server';
+import { isPrefetchRequest } from '../../middleware/create-middleware';
+import { expireSessionCookies } from '../../auth/session-cookie-clear';
+import { getSessionCookieName, getSecureSessionCookieName } from '../../lib/app-slug';
+import { boundSessionCookie, loginLocation, readResetRequest, resetSecret } from '../../auth/session-reset-link';
+
+export const dynamic = 'force-dynamic';
+
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  if (isPrefetchRequest(request)) {
+    return new NextResponse(null, { status: 204, headers: { 'cache-control': 'no-store' } });
+  }
+  const bound = boundSessionCookie((n) => request.cookies.get(n)?.value, getSessionCookieName(), getSecureSessionCookieName());
+  const { params, signed } = await readResetRequest(request.nextUrl.searchParams, resetSecret(), bound);
+  const response = NextResponse.redirect(new URL(loginLocation(params), request.url), 307);
+  response.headers.set('cache-control', 'no-store');
+  if (signed) expireSessionCookies(response, Array.from(request.cookies, ([name]) => name));
+  return response;
+}