@payez/next-mvp 4.1.21 → 4.4.1

package/dist/api-handlers/test/force-expire.js

@@ -5,30 +5,125 @@ const server_1 = require("next/server");
 const auth_1 = require("../../server/auth");
 const session_store_1 = require("../../lib/session-store");
 /**
- * Force-expire access token for testing refresh flow.
+ * ⚠️ DESTRUCTIVE TEST-ONLY HANDLER — DO NOT MOUNT IN PRODUCTION. ⚠️
  *
- * Sets the access token expiry to 2 minutes in the past,
- * which will trigger a refresh on the next API call.
+ * Force-expire access token for testing refresh flow. Sets the access token
+ * expiry to 2 minutes in the past, which will trigger a refresh on the next
+ * API call.
+ *
+ * THIS MUTATES SESSION STATE. It is a test affordance, not a product feature.
+ *
+ * ── WHY THIS WARNING EXISTS (QAPert 34983) ────────────────────────────────
+ * The usage block below is not decoration: THIS DOCSTRING IS THE SPREAD
+ * MECHANISM. It ships compiled into dist and into the .d.ts, so it reaches
+ * every consumer's editor as hover text, and it is a one-line copy-paste that
+ * mounts a destructive endpoint. Every one of the three surfaces this route
+ * ended up on followed exactly these instructions.
+ *
+ * The handler itself was fixed (244877: default-deny behind ENABLE_TEST_ROUTES,
+ * plus the caller-supplied-token IDOR removed). But a fixed handler shipped
+ * with unqualified mounting instructions still spreads: the guidance was never
+ * corrected alongside the code, and a package that documents a dangerous route
+ * as a plain convenience is instructing the weaker configuration.
+ *
+ * ── IF YOU MOUNT IT, MOUNT IT LIKE THIS ───────────────────────────────────
+ * Required: set ENABLE_TEST_ROUTES=true IN THAT ENVIRONMENT ONLY. Absent, empty
+ * or any other value default-DENIES (404). Never set it in production.
  *
- * Usage in consuming app:
  * ```typescript
- * // app/api/test/force-expire/route.ts
+ * // app/api/test/force-expire/route.ts   — TEST/DEV ENVIRONMENTS ONLY
+ * // Requires ENABLE_TEST_ROUTES=true in that environment; 404s otherwise.
  * export { POST } from '@payez/next-mvp/api-handlers/test/force-expire';
  * ```
+ *
+ * If you do not need to exercise the refresh flow, DO NOT MOUNT THIS AT ALL.
+ * The safest configuration is the absence of the route.
  */
 const POST = async (req) => {
+    // 244877 (package-level): DEFAULT DENY behind ENABLE_TEST_ROUTES.
+    //
+    // This handler MUTATES session state — it rewrites idpAccessTokenExpires two
+    // minutes into the past — and was gated on nothing but "any signed-in
+    // session": no role check, no env kill-switch. Because consuming apps mount
+    // it with a one-line re-export, EVERY consumer inherited that, including
+    // deployments on production hosts.
+    //
+    // The card was raised against one app's local copy. Sweeping the pattern
+    // rather than the instance found the same route in three places — a local
+    // copy in the graft, a local copy in idealvibe.online, and idealresume.online
+    // re-exporting THIS handler — so the fix belongs here, at the source all
+    // three ultimately derive from, not only in whichever copy was noticed first.
+    //
+    // The gate is the FIRST statement, before any session decode, so a disabled
+    // build does not reveal that the route is live. Absent, empty, or any value
+    // other than 'true' disables it. Distinguishable body on purpose: a bare 404
+    // reads as "route missing / build broken" and sends someone debugging
+    // deployment instead of reading a flag.
+    //
+    // A consumer that genuinely needs this in a test environment sets
+    // ENABLE_TEST_ROUTES=true there, which is the same posture the token
+    // inspector already uses for a strictly LESS dangerous, read-only route.
+    if (process.env.ENABLE_TEST_ROUTES !== 'true') {
+        // DISCLOSURE IS CONDITIONAL ON ENVIRONMENT (QAPert-NightHawk 34539, after
+        // QAPert caught that my first version shipped the very leak we had just
+        // criticised elsewhere).
+        //
+        // My original body named the flag: "Set ENABLE_TEST_ROUTES=true...". That
+        // is the same class of disclosure as TOKEN_INSPECTOR_DISABLED — it confirms
+        // the route exists, names the capability, and hands a prober the exact
+        // switch that turns it on. Having argued against that pattern one directory
+        // over, shipping it here would have been incoherent.
+        //
+        // Deleting the message outright is also wrong: it is what stops a developer
+        // losing an hour deciding whether their build is broken. The tension
+        // resolves by AUDIENCE, not by picking a side:
+        //   production      -> 404, EMPTY body. Nothing about the capability, the
+        //                      flag, or even that a handler is here.
+        //   non-production  -> 404 + the helpful message naming the flag.
+        //
+        // The operator affordance survives in production too, via the log line
+        // below: logs are visible to operators and not to probers, which is exactly
+        // the split the response body cannot make.
+        console.warn('[FORCE-EXPIRE] blocked: ENABLE_TEST_ROUTES is not "true" (test routes default-deny).');
+        if (process.env.NODE_ENV === 'production') {
+            return new server_1.NextResponse(null, { status: 404 });
+        }
+        return server_1.NextResponse.json({
+            error: 'TEST_ROUTES_DISABLED',
+            message: 'Test routes are disabled in this build. Set ENABLE_TEST_ROUTES=true to enable them (development only).',
+        }, { status: 404 });
+    }
     try {
         const betterAuthSession = await (0, auth_1.getSession)(req);
-        let sessionToken = betterAuthSession?.session?.token;
+        // ACCESS CONTROL (QAPert 34553). This handler previously fell back to a
+        // CALLER-SUPPLIED `X-Session-Token` header when the request carried no
+        // session of its own, and then force-expired whatever token that header
+        // named — with NO check that the token belonged to the caller. The 401
+        // fired only when a caller supplied NEITHER a session NOR the header. So
+        // an UNAUTHENTICATED caller who presented any valid session token could
+        // expire ANOTHER USER'S session: an unauthenticated cross-session write.
+        //
+        // The fallback is removed rather than ownership-checked, because an
+        // ownership check would make it exactly equivalent to reading the caller's
+        // own session — the header could then never name anything else, so it
+        // would be a parameter that cannot legally vary. The session to expire is
+        // now ALWAYS the caller's own, which is also what the graft's local copy
+        // has always done.
+        //
+        // This is defence in depth, not the only control: the ENABLE_TEST_ROUTES
+        // gate above already 404s this handler by default. But the gate is
+        // switched ON in test environments, and "unauthenticated users can expire
+        // each other's sessions" is not acceptable there either — a control that
+        // only holds while a feature is switched off is not an access control.
+        //
+        // Corrects NextPert's own scope claim on card 244877 ("a caller could only
+        // ever expire their OWN session"): that was read off the graft's LOCAL
+        // copy, which derives the token from the caller's JWT. It was never true
+        // of THIS handler, which is the one consumers actually mount.
+        const sessionToken = betterAuthSession?.session?.token;
         if (!sessionToken) {
-            const headerSessionToken = req.headers.get('x-session-token') || req.headers.get('X-Session-Token');
-            if (headerSessionToken) {
-                sessionToken = headerSessionToken;
-            }
-            else {
-                console.warn('[TEST_EXPIRE] No session token or X-Session-Token header');
-                return server_1.NextResponse.json({ success: false, error: 'No session token' }, { status: 401 });
-            }
+            console.warn('[TEST_EXPIRE] No session on the request');
+            return server_1.NextResponse.json({ success: false, error: 'No session token' }, { status: 401 });
         }
         const session = await (0, session_store_1.getSession)(sessionToken);
         if (!session) {

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

@@ -12,6 +12,12 @@ 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';
+/**
+ * 185121: short sha256 fingerprint for secrets/tokens in log lines — enough
+ * to tell "same" from "divergent", never enough to reconstruct. 12 hex chars
+ * = 48 bits; collision-tellable across a deployment, useless as a credential.
+ */
+export declare function secretFingerprint(value: string): string;
 /**
  * Better Auth social provider config shape.
  */
@@ -22,7 +28,52 @@ export interface BetterAuthSocialProvider {
     prompt?: string;
     accessType?: 'offline' | 'online';
     hd?: string;
+    /**
+     * 260419: better-auth's ONLY guard against OAuth auto-provisioning
+     * (oauth2/link-account.mjs handleOAuthUserInfo: `if (disableSignUp) return
+     * {error:"signup disabled"}`). Unset means ANY unknown Google identity gets a
+     * local account created at callback. We wire it from the tenant's own policy.
+     */
+    disableSignUp?: boolean;
 }
+/**
+ * EXCHANGE-MOVE (175047): route OAuth through OUR IDP instead of holding
+ * provider credentials in the app.
+ *
+ * ARCHITECTURE LOCKED (BAPert 21318): genericOAuth pointed at the IDP - NOT at
+ * Google - which is simultaneously pkce + no-secret AND route-through-IDP, and
+ * is uniform with the ratified desktop leg. The IDP holds the provider secret
+ * and performs the provider exchange server-side.
+ *
+ * ── CUSTOM SHAPE, NEVER A PROVIDER PRESET ───────────────────────────────────
+ * QAPert-NightHawk 21304: better-auth's provider-PRESET shape makes
+ * clientSecret REQUIRED again. Same plugin, two config shapes, opposite answers
+ * on whether we need a secret. This builds the generic/custom shape
+ * deliberately; reaching for a preset because it looks tidier would silently
+ * kill keyless-on-web and nobody would connect the two changes.
+ *
+ * ── OPT-IN, AND NOT A FALLBACK ──────────────────────────────────────────────
+ * Returns null unless the IDP's OAuth endpoints are explicitly configured. That
+ * makes this ADDITIVE: the existing socialProviders path keeps working until an
+ * operator turns this on. It is NOT a runtime failover - nothing silently
+ * chooses between them, because a silent chooser is how a migration ends up
+ * half-applied and undetectable.
+ *
+ * ⚠ WHAT MUST MOVE TO THE IDP WITH THIS (flagged in 21317, not solvable here):
+ * the app stops talking to Google, so it can no longer capture the raw
+ * id_token that oauth-callback verifies today, and the per-provider settings
+ * below stop being ours to set - profile scope, prompt=select_account,
+ * accessType, and hd (hosted-domain, a SECURITY control). The IDP's own
+ * exchange must verify signature/iss/aud/exp itself and preserve those four, or
+ * they are lost silently.
+ */
+export declare function buildIdpOAuthProviderConfig(): {
+    providerId: string;
+    discoveryUrl: string;
+    clientId: string;
+    pkce: true;
+    scopes: string[];
+} | null;
 export declare function buildBetterAuthProviders(config: IDPClientConfig): Record<string, BetterAuthSocialProvider>;
 /**
  * Optional configuration for `createBetterAuthInstance`.
@@ -69,7 +120,58 @@ export declare function createBetterAuthInstance(idpConfig: IDPClientConfig, opt
     socialProviders: Record<string, BetterAuthSocialProvider>;
     trustedOrigins: string[];
     secondaryStorage: {
+        /**
+         * 170033 (QAPert 22654, load-bearing precondition for 183483): DO NOT
+         * swallow a Redis failure into `null` here.
+         *
+         * `null` from `get` is Better Auth's OWN signal for "no session at this
+         * key" (see node_modules/better-auth db/internal-adapter.mjs
+         * `findSession`: `if (!sessionStringified ...) return null`). Catching
+         * a Redis error and returning `null` therefore told better-auth "this
+         * session does not exist" when the true state was "the store could not
+         * be asked" — indistinguishable from a genuine sign-out. With
+         * `cookieCache` disabled (session.cookieCache.enabled above), EVERY
+         * `getSession()` call hits this path for real, so a Redis blip
+         * manufactured a `200 { session: null }` for every live session at
+         * once — the exact channel 183483's client-side guard (verify-code
+         * page's session-liveness check) was built to survive, and the one it
+         * could not survive while this swallow stood: a fabricated "no
+         * session" 200 is not distinguishable from a real one by any client.
+         *
+         * Letting the error propagate is safe: better-auth's own router
+         * (better-call/dist/router.mjs) wraps every endpoint handler in a
+         * top-level try/catch and converts an uncaught throw to a genuine
+         * `500`, not a crash. A `500` IS the "inconclusive" signal 183483's
+         * corrected client guard already knows how to hold a session through —
+         * so a Redis outage now surfaces as "couldn't check" instead of
+         * silently lying "confirmed logged out".
+         */
         get: (key: string) => Promise<string | null>;
+        /**
+         * 170033 fix 1 — DO NOT SWALLOW A FAILED WRITE. A SESSION THAT WAS NOT
+         * PERSISTED IS NOT A SESSION.
+         *
+         * This previously caught every Redis error and returned normally, so
+         * better-auth was told the session had been stored when nothing had been
+         * written. The user got a successful login, a session cookie, and a
+         * rendered signed-in shell on top of a store that holds no session — and
+         * the very next `getSession()` reads `null` and signs them straight back
+         * out. Nothing logged, nothing thrown, no banner: a login that "worked"
+         * and a sign-out nobody can explain.
+         *
+         * Letting it propagate is the same contract `get` above already relies on:
+         * better-auth's router (better-call/dist/router.mjs) wraps every endpoint
+         * handler and converts an uncaught throw into a genuine 500. A 500 on the
+         * login write is honest — "we could not store your session" — and it is
+         * distinguishable by any client from a successful login, which a swallowed
+         * failure is not.
+         *
+         * THE COMMENT THIS REPLACES SAID "Redis unavailable — cookie cache still
+         * works". It does not: `session.cookieCache.enabled` is FALSE (see below).
+         * The comment described a safety net that had been removed, which is why
+         * this swallow looked survivable to every reader who trusted it (170033
+         * fix 3).
+         */
         set: (key: string, value: string, ttl?: number) => Promise<void>;
         delete: (key: string) => Promise<void>;
     };
@@ -195,18 +297,173 @@ export declare function createBetterAuthInstance(idpConfig: IDPClientConfig, opt
             max: number;
         }[];
         options: MagicLinkOptions;
+    } | {
+        id: "generic-oauth";
+        init: (ctx: import("better-auth").AuthContext) => {
+            context: {
+                socialProviders: import("better-auth").OAuthProvider<Record<string, any>, Partial<import("better-auth").ProviderOptions<any>>>[];
+            };
+        };
+        endpoints: {
+            signInWithOAuth2: import("better-auth").StrictEndpoint<"/sign-in/oauth2", {
+                method: "POST";
+                body: import("better-auth").ZodObject<{
+                    providerId: import("better-auth").ZodString;
+                    callbackURL: import("better-auth").ZodOptional<import("better-auth").ZodString>;
+                    errorCallbackURL: import("better-auth").ZodOptional<import("better-auth").ZodString>;
+                    newUserCallbackURL: import("better-auth").ZodOptional<import("better-auth").ZodString>;
+                    disableRedirect: import("better-auth").ZodOptional<import("better-auth").ZodBoolean>;
+                    scopes: import("better-auth").ZodOptional<import("better-auth").ZodArray<import("better-auth").ZodString>>;
+                    requestSignUp: import("better-auth").ZodOptional<import("better-auth").ZodBoolean>;
+                    additionalData: import("better-auth").ZodOptional<import("better-auth").ZodRecord<import("better-auth").ZodString, import("better-auth").ZodAny>>;
+                }, import("better-auth").$strip>;
+                metadata: {
+                    openapi: {
+                        description: string;
+                        responses: {
+                            200: {
+                                description: string;
+                                content: {
+                                    "application/json": {
+                                        schema: {
+                                            type: "object";
+                                            properties: {
+                                                url: {
+                                                    type: string;
+                                                };
+                                                redirect: {
+                                                    type: string;
+                                                };
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            }, {
+                url: string;
+                redirect: boolean;
+            }>;
+            oAuth2Callback: import("better-auth").StrictEndpoint<"/oauth2/callback/:providerId", {
+                method: "GET";
+                query: import("better-auth").ZodObject<{
+                    code: import("better-auth").ZodOptional<import("better-auth").ZodString>;
+                    error: import("better-auth").ZodOptional<import("better-auth").ZodString>;
+                    error_description: import("better-auth").ZodOptional<import("better-auth").ZodString>;
+                    state: import("better-auth").ZodOptional<import("better-auth").ZodString>;
+                    iss: import("better-auth").ZodOptional<import("better-auth").ZodString>;
+                }, import("better-auth").$strip>;
+                metadata: {
+                    allowedMediaTypes: string[];
+                    openapi: {
+                        description: string;
+                        responses: {
+                            200: {
+                                description: string;
+                                content: {
+                                    "application/json": {
+                                        schema: {
+                                            type: "object";
+                                            properties: {
+                                                url: {
+                                                    type: string;
+                                                };
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                    scope: "server";
+                };
+            }, void>;
+            oAuth2LinkAccount: import("better-auth").StrictEndpoint<"/oauth2/link", {
+                method: "POST";
+                body: import("better-auth").ZodObject<{
+                    providerId: import("better-auth").ZodString;
+                    callbackURL: import("better-auth").ZodString;
+                    scopes: import("better-auth").ZodOptional<import("better-auth").ZodArray<import("better-auth").ZodString>>;
+                    errorCallbackURL: import("better-auth").ZodOptional<import("better-auth").ZodString>;
+                }, import("better-auth").$strip>;
+                use: ((inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<{
+                    session: {
+                        session: Record<string, any> & {
+                            id: string;
+                            createdAt: Date;
+                            updatedAt: Date;
+                            userId: string;
+                            expiresAt: Date;
+                            token: string;
+                            ipAddress?: string | null | undefined;
+                            userAgent?: string | null | undefined;
+                        };
+                        user: Record<string, any> & {
+                            id: string;
+                            createdAt: Date;
+                            updatedAt: Date;
+                            email: string;
+                            emailVerified: boolean;
+                            name: string;
+                            image?: string | null | undefined;
+                        };
+                    };
+                }>)[];
+                metadata: {
+                    openapi: {
+                        description: string;
+                        responses: {
+                            "200": {
+                                description: string;
+                                content: {
+                                    "application/json": {
+                                        schema: {
+                                            type: "object";
+                                            properties: {
+                                                url: {
+                                                    type: string;
+                                                    format: string;
+                                                    description: string;
+                                                };
+                                                redirect: {
+                                                    type: string;
+                                                    description: string;
+                                                    enum: boolean[];
+                                                };
+                                            };
+                                            required: string[];
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            }, {
+                url: string;
+                redirect: boolean;
+            }>;
+        };
+        options: import("better-auth/plugins/generic-oauth").GenericOAuthOptions;
+        $ERROR_CODES: {
+            INVALID_OAUTH_CONFIGURATION: import("better-auth").RawError<"INVALID_OAUTH_CONFIGURATION">;
+            TOKEN_URL_NOT_FOUND: import("better-auth").RawError<"TOKEN_URL_NOT_FOUND">;
+            PROVIDER_CONFIG_NOT_FOUND: import("better-auth").RawError<"PROVIDER_CONFIG_NOT_FOUND">;
+            PROVIDER_ID_REQUIRED: import("better-auth").RawError<"PROVIDER_ID_REQUIRED">;
+            INVALID_OAUTH_CONFIG: import("better-auth").RawError<"INVALID_OAUTH_CONFIG">;
+            SESSION_REQUIRED: import("better-auth").RawError<"SESSION_REQUIRED">;
+            ISSUER_MISMATCH: import("better-auth").RawError<"ISSUER_MISMATCH">;
+            ISSUER_MISSING: import("better-auth").RawError<"ISSUER_MISSING">;
+        };
     })[]];
 }>;
 /**
  * Better Auth is always enabled (NextAuth removed in 4.0).
  */
 export declare function isBetterAuthEnabled(): boolean;
-/**
- * Get Better Auth Next.js route handlers (GET, POST).
- * Initializes Better Auth from IDP config on first call, caches the instance.
- */
-declare let cachedInstance: any;
-export { cachedInstance as __betterAuthInstance };
+export declare function __getBetterAuthInstance(): unknown;
 /**
  * Configure Better Auth instance options for this process.
  *