@payez/next-mvp 4.1.14 → 4.1.21

package/dist/api-handlers/mfa/totp-verify.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Verify TOTP 2FA Challenge Handler
+ *
+ * Verifies an authenticator-app code AT LOGIN and completes the 2FA flow,
+ * transitioning the session to MFA-verified.
+ *
+ * WHY THIS EXISTS (2026-08-02)
+ * The package shipped TOTP ENROLMENT (totp-enroll, totp-confirm, against
+ * /api/Account/mfa/totp/*) but no TOTP CHALLENGE. SMS and email both had one
+ * (verify-sms, verify-email, against /api/ExternalAuth/twofa/*), so TOTP could
+ * be enrolled and then never used to satisfy a login challenge — mfaVerified
+ * stayed false forever for authenticator-app users, even though the IDP
+ * advertises totp in allowed2FAMethods and exposes the endpoint.
+ *
+ * DO NOT "FIX" THIS BY MAKING totp-confirm TRANSITION THE SESSION. Three people
+ * proposed exactly that on the grounds that its SMS/email "siblings" do it. They
+ * are not siblings: totp-confirm is ENROLMENT. Flipping mfaVerified there would
+ * mean enrolling a factor counts as passing a challenge, letting a
+ * password-only session self-promote to MFA-verified by adding an
+ * authenticator. Enrolment must never set mfaVerified.
+ *
+ * FIELD NAME: the IDP expects { "code": ... } here
+ * (MfaTotpVerifyRequest, [JsonPropertyName("code")]), NOT the
+ * { "verification_code": ... } that the SMS endpoint takes. Copying verify-sms
+ * and changing only the URL produces a handler that reaches the IDP and is
+ * rejected, which reads as "wrong code" rather than "wrong shape".
+ *
+ * @package @payez/next-mvp
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = POST;
+const server_1 = require("next/server");
+const idp_fetch_1 = require("../../lib/idp-fetch");
+const env_1 = require("../../config/env");
+const test_aware_get_token_1 = require("../../lib/test-aware-get-token");
+const session_store_1 = require("../../lib/session-store");
+const jwt_decode_1 = require("../../lib/jwt-decode");
+async function POST(req) {
+    try {
+        const body = await req.json();
+        // Accept the same aliases the client might send; the IDP field is `code`.
+        const code = body.code || body.totpCode || body.verificationCode || body.verification_code;
+        if (!code) {
+            return server_1.NextResponse.json({
+                success: false,
+                error: 'Authenticator code is required',
+                code: 'INVALID_REQUEST',
+            }, { status: 400 });
+        }
+        // idpFetchJSON injects the caller's Bearer from the session store.
+        const result = await (0, idp_fetch_1.idpFetchJSON)(req, `${env_1.ENV_CONFIG.IDP_URL}/api/ExternalAuth/twofa/totp/verify`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ code }),
+        });
+        if (!result.ok) {
+            return server_1.NextResponse.json({
+                success: false,
+                error: result.json?.message || 'Verification failed',
+                code: result.json?.code || 'IDP_ERROR',
+                meta: { attemptedRefresh: result.attemptedRefresh },
+            }, { status: result.status });
+        }
+        // Unwrap IDP envelope { success, data }
+        const unwrappedData = result.json?.data || result.json;
+        // Only a successful challenge that returns fresh tokens may transition the
+        // session. No tokens => no transition: we must not mark 2FA complete on the
+        // strength of a 200 alone.
+        let sessionTransitioned = false;
+        if (unwrappedData.access_token && unwrappedData.refresh_token) {
+            const token = await (0, test_aware_get_token_1.getTokenTestAware)(req);
+            const sessionToken = (token?.sessionToken || token?.redisSessionId);
+            if (sessionToken) {
+                let accessTokenExpires = Date.now() + 15 * 60 * 1000;
+                try {
+                    const decoded = (0, jwt_decode_1.jwtDecode)(unwrappedData.access_token);
+                    if (decoded?.exp)
+                        accessTokenExpires = decoded.exp * 1000;
+                }
+                catch {
+                    console.warn('[VERIFY_TOTP] Could not decode access token, using default expiration');
+                }
+                let refreshTokenExpires = Date.now() + 3 * 24 * 60 * 60 * 1000;
+                try {
+                    const decoded = (0, jwt_decode_1.jwtDecode)(unwrappedData.refresh_token);
+                    if (decoded?.exp)
+                        refreshTokenExpires = decoded.exp * 1000;
+                }
+                catch {
+                    // Refresh token may carry no exp claim; default stands.
+                }
+                await (0, session_store_1.transitionTo2FASession)(sessionToken, {
+                    accessToken: unwrappedData.access_token,
+                    refreshToken: unwrappedData.refresh_token,
+                    accessTokenExpires,
+                    refreshTokenExpires,
+                }, 'totp' // 2FA method, used by the refresh-token flow
+                );
+                sessionTransitioned = true;
+                console.log('[VERIFY_TOTP] Session transitioned to 2FA-verified');
+            }
+            else {
+                console.warn('[VERIFY_TOTP] IDP verified the code but no session token was resolvable — session NOT transitioned');
+            }
+        }
+        else {
+            console.warn('[VERIFY_TOTP] IDP returned 2xx without tokens — session NOT transitioned');
+        }
+        // Do not expose tokens to the client.
+        //
+        // twoFactorSessionVerified REPORTS WHAT ACTUALLY HAPPENED. It is NOT a copy
+        // of `success`. The code can verify at the IDP while the session is not
+        // transitioned — no tokens returned, or no resolvable session token — and a
+        // client that trusted a hardcoded `true` would show the user as MFA-verified
+        // while the session still says otherwise. That divergence between the guard
+        // and the report is the defect this field exists to avoid.
+        // (verify-sms.ts hardcodes it true and has the same flaw — reported upstream.)
+        return server_1.NextResponse.json({
+            success: true,
+            verificationSuccessful: true,
+            twoFactorSessionVerified: sessionTransitioned,
+            message: unwrappedData.message || 'Authenticator code verified successfully',
+        }, { status: 200 });
+    }
+    catch (error) {
+        console.error('[VERIFY_TOTP] Error:', error);
+        return server_1.NextResponse.json({
+            success: false,
+            error: 'Failed to verify code',
+            code: 'INTERNAL_ERROR',
+        }, { status: 500 });
+    }
+}

package/dist/api-handlers/passkeys/list.d.ts

@@ -0,0 +1,7 @@
+import { NextRequest, NextResponse } from 'next/server';
+/**
+ * List the signed-in user's passkeys (GET /api/Passkeys, user JWT).
+ * Probe-verified live 2026-08-01 (anon -> 401 = routed).
+ * No session -> upstream 401, passed through, never invented locally.
+ */
+export declare function GET(req: NextRequest): Promise<NextResponse<any>>;

package/dist/api-handlers/passkeys/list.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GET = GET;
+const server_1 = require("next/server");
+const idp_fetch_1 = require("../../lib/idp-fetch");
+const env_1 = require("../../config/env");
+/**
+ * List the signed-in user's passkeys (GET /api/Passkeys, user JWT).
+ * Probe-verified live 2026-08-01 (anon -> 401 = routed).
+ * No session -> upstream 401, passed through, never invented locally.
+ */
+async function GET(req) {
+    const result = await (0, idp_fetch_1.idpFetchJSON)(req, `${env_1.ENV_CONFIG.IDP_URL}/api/Passkeys`, { method: 'GET' });
+    if (!result.ok) {
+        return server_1.NextResponse.json({
+            success: false,
+            message: 'Upstream error',
+            error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+            meta: { attemptedRefresh: result.attemptedRefresh },
+        }, { status: result.status });
+    }
+    const bodyJson = result.json;
+    if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
+        if (bodyJson.success === true)
+            return server_1.NextResponse.json(bodyJson.data, { status: 200 });
+        return server_1.NextResponse.json(bodyJson, { status: 200 });
+    }
+    return server_1.NextResponse.json(bodyJson ?? {}, { status: 200 });
+}

package/dist/api-handlers/passkeys/manage.d.ts

@@ -0,0 +1,3 @@
+import { NextRequest, NextResponse } from 'next/server';
+export declare function PATCH(req: NextRequest, id: string): Promise<NextResponse<any>>;
+export declare function DELETE(req: NextRequest, id: string): Promise<NextResponse<any>>;

package/dist/api-handlers/passkeys/manage.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PATCH = PATCH;
+exports.DELETE = DELETE;
+const server_1 = require("next/server");
+const idp_fetch_1 = require("../../lib/idp-fetch");
+const env_1 = require("../../config/env");
+/**
+ * Manage ONE passkey (PATCH rename / DELETE revoke, /api/Passkeys/{id},
+ * user JWT). The id arrives from the Next dynamic segment via the routes
+ * wrapper — it is never read from the body.
+ */
+function upstreamError(result) {
+    return server_1.NextResponse.json({
+        success: false,
+        message: 'Upstream error',
+        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+        meta: { attemptedRefresh: result.attemptedRefresh },
+    }, { status: result.status });
+}
+function passthrough(json) {
+    const bodyJson = json;
+    if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
+        if (bodyJson.success === true)
+            return server_1.NextResponse.json(bodyJson.data ?? { success: true }, { status: 200 });
+        return server_1.NextResponse.json(bodyJson, { status: 200 });
+    }
+    return server_1.NextResponse.json(bodyJson ?? { success: true }, { status: 200 });
+}
+async function PATCH(req, id) {
+    let body = '{}';
+    try {
+        const raw = await req.text();
+        if (raw && raw.trim().length > 0)
+            body = raw;
+    }
+    catch { }
+    const result = await (0, idp_fetch_1.idpFetchJSON)(req, `${env_1.ENV_CONFIG.IDP_URL}/api/Passkeys/${encodeURIComponent(id)}`, {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+    });
+    if (!result.ok)
+        return upstreamError(result);
+    return passthrough(result.json);
+}
+async function DELETE(req, id) {
+    const result = await (0, idp_fetch_1.idpFetchJSON)(req, `${env_1.ENV_CONFIG.IDP_URL}/api/Passkeys/${encodeURIComponent(id)}`, {
+        method: 'DELETE',
+    });
+    if (!result.ok)
+        return upstreamError(result);
+    return passthrough(result.json);
+}

package/dist/api-handlers/passkeys/register-options.d.ts

@@ -0,0 +1,8 @@
+import { NextRequest, NextResponse } from 'next/server';
+/**
+ * Begin the passkey REGISTRATION ceremony (POST /api/Passkeys/register/options,
+ * user JWT — a credential change; the IDP may demand step-up, surfaced as-is).
+ * Returns the WebAuthn PublicKeyCredentialCreationOptions (ride the envelope
+ * `data`, per the archived hand-roll contract).
+ */
+export declare function POST(req: NextRequest): Promise<NextResponse<any>>;

package/dist/api-handlers/passkeys/register-options.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = POST;
+const server_1 = require("next/server");
+const idp_fetch_1 = require("../../lib/idp-fetch");
+const env_1 = require("../../config/env");
+/**
+ * Begin the passkey REGISTRATION ceremony (POST /api/Passkeys/register/options,
+ * user JWT — a credential change; the IDP may demand step-up, surfaced as-is).
+ * Returns the WebAuthn PublicKeyCredentialCreationOptions (ride the envelope
+ * `data`, per the archived hand-roll contract).
+ */
+async function POST(req) {
+    let body = '{}';
+    try {
+        const raw = await req.text();
+        if (raw && raw.trim().length > 0)
+            body = raw;
+    }
+    catch { }
+    const result = await (0, idp_fetch_1.idpFetchJSON)(req, `${env_1.ENV_CONFIG.IDP_URL}/api/Passkeys/register/options`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+    });
+    if (!result.ok) {
+        return server_1.NextResponse.json({
+            success: false,
+            message: 'Upstream error',
+            error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+            meta: { attemptedRefresh: result.attemptedRefresh },
+        }, { status: result.status });
+    }
+    const bodyJson = result.json;
+    if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
+        if (bodyJson.success === true)
+            return server_1.NextResponse.json(bodyJson.data, { status: 200 });
+        return server_1.NextResponse.json(bodyJson, { status: 200 });
+    }
+    return server_1.NextResponse.json(bodyJson ?? {}, { status: 200 });
+}

package/dist/api-handlers/passkeys/register-verify.d.ts

@@ -0,0 +1,7 @@
+import { NextRequest, NextResponse } from 'next/server';
+/**
+ * Finish the passkey REGISTRATION ceremony (POST /api/Passkeys/register/verify,
+ * user JWT). Body forwarded VERBATIM — it carries the enrolment handle plus the
+ * authenticator attestation produced by navigator.credentials.create().
+ */
+export declare function POST(req: NextRequest): Promise<NextResponse<any>>;

package/dist/api-handlers/passkeys/register-verify.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POST = POST;
+const server_1 = require("next/server");
+const idp_fetch_1 = require("../../lib/idp-fetch");
+const env_1 = require("../../config/env");
+/**
+ * Finish the passkey REGISTRATION ceremony (POST /api/Passkeys/register/verify,
+ * user JWT). Body forwarded VERBATIM — it carries the enrolment handle plus the
+ * authenticator attestation produced by navigator.credentials.create().
+ */
+async function POST(req) {
+    let body = '{}';
+    try {
+        const raw = await req.text();
+        if (raw && raw.trim().length > 0)
+            body = raw;
+    }
+    catch { }
+    const result = await (0, idp_fetch_1.idpFetchJSON)(req, `${env_1.ENV_CONFIG.IDP_URL}/api/Passkeys/register/verify`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+    });
+    if (!result.ok) {
+        return server_1.NextResponse.json({
+            success: false,
+            message: 'Upstream error',
+            error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+            meta: { attemptedRefresh: result.attemptedRefresh },
+        }, { status: result.status });
+    }
+    const bodyJson = result.json;
+    if (bodyJson && typeof bodyJson === 'object' && 'success' in bodyJson && 'data' in bodyJson) {
+        if (bodyJson.success === true)
+            return server_1.NextResponse.json(bodyJson.data, { status: 200 });
+        return server_1.NextResponse.json(bodyJson, { status: 200 });
+    }
+    return server_1.NextResponse.json(bodyJson ?? {}, { status: 200 });
+}

package/dist/api-handlers/session/viability.js

@@ -103,6 +103,25 @@ async function GET(req) {
                     // 2FA fields - critical for middleware redirect logic
                     requires2FA, // From cached client config (client-wide setting)
                     twoFactorComplete: effectiveTwoFactorComplete, // From session, BUT respects MFA TTL
+                    // Cards 141688/141741 — the IDP's routing decision, relayed verbatim.
+                    //
+                    // THIS IS THE SECOND IMPLEMENTATION OF VIABILITY. The other is
+                    // routes/auth/viability.ts, which is what the admin graft mounts.
+                    // Both are publicly exported entry points, so both can be a consumer's
+                    // only source of this answer. Adding the relay to just one would leave
+                    // an app that mounts THIS one still blind to enroll_mfa — the exact
+                    // seam these cards are about, reopened one export over.
+                    //
+                    // 'enroll_mfa' = no USABLE method, the user cannot complete a
+                    // challenge. 'mfa_verify' = usable method exists. null = nothing due.
+                    // NOT a completion signal: twoFactorComplete still owns that.
+                    //
+                    // No `?? null`: undefined (never captured — every session minted
+                    // before this change) must stay distinguishable from null (the IDP
+                    // said nothing is outstanding). Defaulting to null would tell the
+                    // gate that every pre-existing session is fully authenticated,
+                    // including zero-method users who must be routed to enrol.
+                    nextStep: sessionData.nextStep,
                     // Token status for refresh decisions
                     accessTokenExpired,
                     hasRefreshToken: !!sessionData.idpRefreshToken

package/dist/auth/better-auth.d.ts

@@ -9,6 +9,7 @@
  * @see BETTER-AUTH-MIGRATION-SPEC.md
  */
 import 'server-only';
+import { betterAuth } from 'better-auth';
 import { type MagicLinkOptions } from 'better-auth/plugins/magic-link';
 import type { IDPClientConfig } from '../lib/idp-client-config';
 /**
@@ -34,6 +35,27 @@ export declare function buildBetterAuthProviders(config: IDPClientConfig): Recor
  */
 export interface CreateBetterAuthInstanceOptions {
     magicLink?: MagicLinkOptions;
+    /**
+     * Extra Better Auth plugins supplied by the consuming app.
+     *
+     * WHY THIS EXISTS — session minting is not delegable any other way. BA's
+     * `setSessionCookie` requires a `GenericEndpointContext`, which only BA's own
+     * endpoint machinery constructs, so an app that must mint a session for an
+     * identity established OUTSIDE BA's built-in providers (passkey sign-in being
+     * the first) cannot do it from a route handler. It needs a real BA endpoint,
+     * and endpoints only arrive via plugins.
+     *
+     * Deliberately GENERIC. The package gains "an app may supply plugins" rather
+     * than any knowledge of passkeys — the alternative was teaching this file
+     * about a specific auth method, which is how a package accumulates a consumer's
+     * feature list.
+     *
+     * The alternative to this option is an app hand-rolling the session cookie
+     * (`{token}.{base64(hmac)}`, standard padding, runtime `authSecret` from
+     * Redis). That fails as a session which DECODES BUT DOES NOT AUTHENTICATE —
+     * so this option exists specifically to make that shortcut unnecessary.
+     */
+    plugins?: Parameters<typeof betterAuth>[0]['plugins'];
 }
 /**
  * Create Better Auth instance from IDP config.
@@ -78,7 +100,7 @@ export declare function createBetterAuthInstance(idpConfig: IDPClientConfig, opt
                 handler: (inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<void>;
             }[];
         };
-    }, ...{
+    }, ...(import("better-auth").BetterAuthPlugin | {
         id: "magic-link";
         endpoints: {
             signInMagicLink: import("better-auth").StrictEndpoint<"/sign-in/magic-link", {
@@ -173,7 +195,7 @@ export declare function createBetterAuthInstance(idpConfig: IDPClientConfig, opt
             max: number;
         }[];
         options: MagicLinkOptions;
-    }[]];
+    })[]];
 }>;
 /**
  * Better Auth is always enabled (NextAuth removed in 4.0).
@@ -228,6 +250,50 @@ export declare function getBetterAuthHandler(): Promise<{
  * This replaces the old databaseHooks approach which doesn't fire in stateless mode.
  */
 export declare function exchangeOAuthForIdpTokens(sessionToken: string, provider?: string): Promise<boolean>;
+/**
+ * Write IDP tokens into an EXISTING Better Auth session. Storage only — this
+ * function never acquires tokens and never decides who the caller is.
+ *
+ * ── WHY THIS IS SPLIT OUT (BAPert ruling, 2026-08-04) ────────────────────────
+ *
+ * `exchangeOAuthForIdpTokens` above does TWO things: it ACQUIRES tokens by
+ * POSTing to `/api/ExternalAuth/oauth-callback`, and then it STORES them. Only
+ * the second half is reusable, and the first half is actively dangerous to
+ * reuse:
+ *
+ *   oauth-callback mints an IDP bearer from an ASSERTED EMAIL with no
+ *   cryptographic verification of any kind (card 138635).
+ *
+ * Passkey sign-in already holds something strictly better — a grant issued by
+ * `/api/ExternalAuth/passwordless/passkey/verify`, which checked a real
+ * signature against a registered credential. Routing that through
+ * oauth-callback to obtain a session would DOWNGRADE a cryptographically
+ * verified assertion into an unverified one, make passkey sign-in weaker than
+ * its own ceremony, and inherit 138635 wholesale.
+ *
+ * That is not hypothetical: "do what the OAuth path does" is the obvious
+ * implementation and it is the wrong one. Splitting acquisition from storage is
+ * what makes the wrong one hard to write by accident.
+ *
+ * ── WHAT CALLERS MUST HAVE DONE FIRST ───────────────────────────────────────
+ *
+ * A Better Auth session must ALREADY EXIST for `sessionToken`. This function
+ * enriches; it does not create. Better Auth owns session creation and cookie
+ * signing, and nothing in this package should replicate either — the cookie is
+ * `{token}.{base64(hmac)}` with standard padding, signed with the runtime
+ * `authSecret` from Redis, and hand-rolling that produces a session which
+ * decodes but does not authenticate.
+ *
+ * @param sessionToken  the Better Auth session token (from its Set-Cookie)
+ * @param idpTokenData  tokens + identity, already obtained by the CALLER'S OWN
+ *                      verified route. Built field-by-field by the caller so an
+ *                      unnamed field cannot ride along silently.
+ * @param authProvider  provenance label recorded on the canonical row. Written
+ *                      to the historical `oauthProvider` key, which predates
+ *                      non-OAuth callers; the NAME is legacy, the VALUE should
+ *                      state what actually authenticated ('passkey', 'google').
+ */
+export declare function storeIdpTokensInSession(sessionToken: string, idpTokenData: Record<string, unknown>, authProvider: string): Promise<boolean>;
 /**
  * Create a production-ready GET handler for the auth catch-all route.
  *