@payez/next-mvp 4.4.7 → 4.4.8

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

@@ -536,8 +536,14 @@ export declare function getBetterAuthHandler(): Promise<{
  * header of the response to find the BA Redis key.
  *
  * This replaces the old databaseHooks approach which doesn't fire in stateless mode.
+ *
+ * RETURNS the IdP's own error code on an IDP refusal, or null otherwise
+ * (PAY-2005 scenario (b), BAPert ruling 67897). It used to return a bare
+ * boolean, so `REGISTRATION_NOT_ALLOWED` was indistinguishable from a network
+ * blip and every cause collapsed to one generic login-page code — a NEW user
+ * refused registration bounced silently, which is the failure Jon named.
  */
-export declare function exchangeOAuthForIdpTokens(sessionToken: string, provider?: string): Promise<boolean>;
+export declare function exchangeOAuthForIdpTokens(sessionToken: string, provider?: string): Promise<boolean | string>;
 /**
  * Write IDP tokens into an EXISTING Better Auth session. Storage only — this
  * function never acquires tokens and never decides who the caller is.
@@ -588,6 +594,17 @@ export declare function storeIdpTokensInSession(sessionToken: string, idpTokenDa
  * Try again or use another method." The cause stays in the server log, never on the page.
  */
 export declare const OAUTH_SIGN_IN_FAILED_ERROR = "OAUTH_SIGN_IN_FAILED";
+/**
+ * The ONLY IdP refusal codes the package forwards to the login page (PAY-2005 (b), BAPert 67897).
+ *
+ * Default stays PAY-1733's ONE neutral code: the cause of an ordinary failed exchange lives in the server
+ * log, never on the page. A code is forwarded ONLY when it earns a distinct user-facing message — today just
+ * the registration refusal, so a NEW Google user with registration OFF sees a clear "not open to sign-up"
+ * line instead of a silent bounce. Adding a code here REQUIRES a matching entry in the host allowlist
+ * (portal: src/lib/auth/magic-link-outcome.ts); an unlisted code renders nothing, which is a silent bounce
+ * wearing a different number. Add them together, never one alone.
+ */
+export declare const IDP_ERROR_CODES_TO_FORWARD: ReadonlySet<string>;
 /**
  * Re-emit each cookie the callback response SET as an immediate expiry, keeping the attributes that decide
  * WHICH cookie the browser overwrites (Path, Domain, Secure, SameSite, HttpOnly - a `__Secure-` name is only

package/dist/auth/better-auth.js

@@ -43,7 +43,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OAUTH_SIGN_IN_FAILED_ERROR = void 0;
+exports.IDP_ERROR_CODES_TO_FORWARD = exports.OAUTH_SIGN_IN_FAILED_ERROR = void 0;
 exports.secretFingerprint = secretFingerprint;
 exports.buildIdpOAuthProviderConfig = buildIdpOAuthProviderConfig;
 exports.buildBetterAuthProviders = buildBetterAuthProviders;
@@ -286,19 +286,42 @@ function buildBetterAuthProviders(config) {
             clientSecret: oauth.clientSecret,
             scope: wireScopes.length > 0 ? wireScopes : undefined,
             /**
-             * 260419 — CLOSE THE SECOND SELF-SERVE PROVISIONING DOOR. 259805 gated
-             * the signup BFF on allow_public_registration, but the social lane never
-             * touches that code: better-auth creates the user through its own
-             * internalAdapter at the OAuth callback, and its ONLY guard is this flag.
+             * PAY-2005 — DISABLE-SIGN-UP IS REMOVED, DELIBERATELY. DO NOT RE-ADD IT.
              *
-             * Wired from the tenant's own policy, explicit-true-opens: the IDP config
-             * keeps allowPublicRegistration UNDEFINED when the tenant never answered
-             * (idp-client-config.ts, the no-fabricated-default rule), and an
-             * unanswered policy question must not provision accounts. That matches
-             * the FE's silent-default-is-decline posture for the "Create account"
-             * affordance. A tenant that wants Google self-serve says so.
+             * 260419 wired this from `config.authSettings?.allowPublicRegistration` to
+             * close a client-side self-serve provisioning door. It cannot do that job
+             * correctly, and it BREAKS SIGN-IN:
+             *
+             *   - This app runs better-auth in STATELESS mode (no DB adapter — see the
+             *     file header). better-auth therefore has NO user store, so at the OAuth
+             *     callback it cannot tell an EXISTING user from a NEW one. Its
+             *     handleOAuthUserInfo consults `disableSignUp` for BOTH, so
+             *     `disableSignUp: true` refuses a returning user exactly like a
+             *     stranger. Measured live 2026-09-30 (PAY-2005): portal.keelauth.com
+             *     Google sign-in bounced to /sign-in with Better Auth `signup_disabled`
+             *     once client 12's allow_public_registration reported false.
+             *
+             *   - The REAL registration gate already exists and is correct, at the IDP:
+             *     PayEz.External.Id.Api ExternalAuthController.oauth-callback looks the
+             *     user up by verified email (:799); an existing user logs in UNTOUCHED
+             *     (:811); only the isNewUser branch (:853) calls INewUserRegistrar,
+             *     which refuses fail-closed when the client forbids public registration
+             *     (NewUserRegistrar.cs:65, `SecurityFlags.AllowPublicRegistration != true`).
+             *     Its own comment states the contract: "existing federated users ...
+             *     log in untouched, so gating here never blocks login."
+             *
+             * So this flag was a DUPLICATE gate that could only ever misfire — it cannot
+             * distinguish new from existing, and the IDP already refuses new identities.
+             * Removing it restores sign-in for existing users WITHOUT reopening
+             * self-serve: a NEW identity that completes the better-auth leg still gets
+             * REFUSED at the IDP exchange and never receives IDP tokens, which is the
+             * portal's actual authorization gate.
+             *
+             * WHERE "no self-serve sign-up" IS ENFORCED NOW: the IDP's NewUserRegistrar
+             * (above) as the backstop, and each app's own front-door sign-up gate
+             * (e.g. the portal's signup-gate.ts / SignUpCard) for the UI affordance.
+             * Both are correct and neither is this flag.
              */
-            disableSignUp: config.authSettings?.allowPublicRegistration !== true,
             // Google is overly eager to reuse the last account unless we
             // explicitly ask for account selection on each social login.
             prompt: typeof rawPrompt === 'string'
@@ -874,6 +897,12 @@ async function getBetterAuthHandler() {
  * header of the response to find the BA Redis key.
  *
  * This replaces the old databaseHooks approach which doesn't fire in stateless mode.
+ *
+ * RETURNS the IdP's own error code on an IDP refusal, or null otherwise
+ * (PAY-2005 scenario (b), BAPert ruling 67897). It used to return a bare
+ * boolean, so `REGISTRATION_NOT_ALLOWED` was indistinguishable from a network
+ * blip and every cause collapsed to one generic login-page code — a NEW user
+ * refused registration bounced silently, which is the failure Jon named.
  */
 async function exchangeOAuthForIdpTokens(sessionToken, provider = 'google') {
     try {
@@ -959,6 +988,36 @@ async function exchangeOAuthForIdpTokens(sessionToken, provider = 'google') {
         console.log('[BETTER_AUTH] IDP oauth-callback response:', { status: oauthRes.status, bodyLength: oauthResText.length });
         if (!oauthRes.ok) {
             console.error('[BETTER_AUTH] IDP oauth-callback failed:', oauthRes.status);
+            /**
+             * PAY-2005 scenario (b) — RETURN THE IDP'S ERROR CODE (BAPert ruling 67897).
+             *
+             * Every refusal used to return a bare `false`, so the abort collapsed ALL
+             * causes to one generic `OAUTH_SIGN_IN_FAILED`: a NEW user refused
+             * registration (`REGISTRATION_NOT_ALLOWED`, ExternalAuthController.cs:908)
+             * bounced silently, indistinguishable from a network blip. Jon named the
+             * clear message explicitly (67856): "(b) a brand-new Google user with
+             * registration OFF is refused by the IDP with a clear message, not a
+             * silent bounce."
+             *
+             * The envelope is `{ error: { code, message } }` (PayEzControllerBase.Error).
+             * We read ONLY `error.code` and return it VERBATIM — the abort puts it in
+             * the `?error=` param, and the HOST's allowlist decides whether to render
+             * it. The package does NOT interpret the code and does NOT add a message
+             * (that would be a second allowlist). No code in the body -> null (the
+             * generic host code), exactly as before.
+             */
+            let idpErrorCode = null;
+            try {
+                const parsed = JSON.parse(oauthResText);
+                // FORWARD ONLY AN ALLOWLISTED CODE. Every other refusal keeps PAY-1733's single neutral code — an
+                // unlisted code would render nothing on the host page, which is the silent bounce this exists to end.
+                if (typeof parsed?.error?.code === 'string' && exports.IDP_ERROR_CODES_TO_FORWARD.has(parsed.error.code)) {
+                    idpErrorCode = parsed.error.code;
+                }
+            }
+            catch {
+                /* non-JSON refusal body -> no code (generic abort) */
+            }
             /**
              * WHY THIS LOGS ONLY ON FAILURE, AND WHY IT LOGS THESE FIELDS.
              *
@@ -1007,7 +1066,7 @@ async function exchangeOAuthForIdpTokens(sessionToken, provider = 'google') {
                 sent_client_id: (0, client_key_1.resolveClientKey)(config, 'auth/better-auth:oauth-callback').key ?? null,
                 idp_url: idpUrl,
             });
-            return false;
+            return idpErrorCode ?? false;
         }
         let idpData;
         try {
@@ -1127,6 +1186,7 @@ async function exchangeOAuthForIdpTokens(sessionToken, provider = 'google') {
         const stored = await storeIdpTokensInSession(sessionToken, idpTokenData, provider);
         if (stored)
             console.log('[BETTER_AUTH] IDP tokens stored in session for', email);
+        // true = success (tokens stored). false = a non-IdP failure with no specific code (generic abort).
         return stored;
     }
     catch (err) {
@@ -1222,6 +1282,17 @@ async function storeIdpTokensInSession(sessionToken, idpTokenData, authProvider)
  * Try again or use another method." The cause stays in the server log, never on the page.
  */
 exports.OAUTH_SIGN_IN_FAILED_ERROR = 'OAUTH_SIGN_IN_FAILED';
+/**
+ * The ONLY IdP refusal codes the package forwards to the login page (PAY-2005 (b), BAPert 67897).
+ *
+ * Default stays PAY-1733's ONE neutral code: the cause of an ordinary failed exchange lives in the server
+ * log, never on the page. A code is forwarded ONLY when it earns a distinct user-facing message — today just
+ * the registration refusal, so a NEW Google user with registration OFF sees a clear "not open to sign-up"
+ * line instead of a silent bounce. Adding a code here REQUIRES a matching entry in the host allowlist
+ * (portal: src/lib/auth/magic-link-outcome.ts); an unlisted code renders nothing, which is a silent bounce
+ * wearing a different number. Add them together, never one alone.
+ */
+exports.IDP_ERROR_CODES_TO_FORWARD = new Set(['REGISTRATION_NOT_ALLOWED']);
 /**
  * Re-emit each cookie the callback response SET as an immediate expiry, keeping the attributes that decide
  * WHICH cookie the browser overwrites (Path, Domain, Secure, SameSite, HttpOnly - a `__Secure-` name is only
@@ -1253,7 +1324,7 @@ function expireSetCookies(setCookies) {
  * expired, and the user goes to the login page with OAUTH_SIGN_IN_FAILED. Relative Location, as for the state-error
  * branch above (328439: an absolute URL built from request.url is a dead tab in a container).
  */
-async function abortOAuthSignIn(callbackResponse, sessionToken, cookieHeader, loginPath) {
+async function abortOAuthSignIn(callbackResponse, sessionToken, cookieHeader, loginPath, errorCode = exports.OAUTH_SIGN_IN_FAILED_ERROR) {
     const headers = new Headers();
     if (sessionToken) {
         try {
@@ -1275,8 +1346,8 @@ async function abortOAuthSignIn(callbackResponse, sessionToken, cookieHeader, lo
     }
     for (const sc of expireSetCookies(callbackResponse.headers.getSetCookie?.() ?? []))
         headers.append('set-cookie', sc);
-    headers.set('location', `${loginPath}${loginPath.includes('?') ? '&' : '?'}error=${exports.OAUTH_SIGN_IN_FAILED_ERROR}`);
-    console.warn('[BETTER_AUTH] OAuth sign-in ABORTED: the IdP exchange stored no tokens, so no session is kept (PAY-1733)', sessionToken ? (0, token_log_id_1.tokenLogId)(sessionToken) : '(no session)');
+    headers.set('location', `${loginPath}${loginPath.includes('?') ? '&' : '?'}error=${errorCode}`);
+    console.warn('[BETTER_AUTH] OAuth sign-in ABORTED: the IdP exchange stored no tokens, so no session is kept (PAY-1733)', sessionToken ? (0, token_log_id_1.tokenLogId)(sessionToken) : '(no session)', 'code=' + errorCode);
     return new Response(null, { status: 302, headers });
 }
 /**
@@ -1364,7 +1435,9 @@ function createAuthGetHandler(loginPath = '/account-auth/login') {
                     .map((c) => c.split(';')[0])
                     .join('; ');
                 let sessionToken = null;
-                let exchanged = false;
+                // true = tokens stored; false = no specific IdP code (generic abort); a string = the IdP's own refusal code
+                // (PAY-2005 (b): REGISTRATION_NOT_ALLOWED, etc.), forwarded so the host can show a clear message.
+                let exchange = false;
                 try {
                     const auth = await getBetterAuthInstance();
                     if (auth?.api?.getSession) {
@@ -1374,7 +1447,7 @@ function createAuthGetHandler(loginPath = '/account-auth/login') {
                         if (session?.session?.token) {
                             sessionToken = session.session.token;
                             console.log('[BETTER_AUTH] Got session token from callback:', (0, token_log_id_1.tokenLogId)(session.session.token), '| email:', session.user?.email);
-                            exchanged = await exchangeOAuthForIdpTokens(session.session.token);
+                            exchange = await exchangeOAuthForIdpTokens(session.session.token);
                         }
                         else {
                             console.warn('[BETTER_AUTH] Could not get session after OAuth callback');
@@ -1384,8 +1457,11 @@ function createAuthGetHandler(loginPath = '/account-auth/login') {
                 catch (err) {
                     console.error('[BETTER_AUTH] IDP token exchange failed:', err.message);
                 }
-                if (!exchanged)
-                    return abortOAuthSignIn(response, sessionToken, cookieHeader, loginPath);
+                if (exchange !== true) {
+                    // A specific IdP error code goes on the URL; otherwise the generic OAUTH_SIGN_IN_FAILED.
+                    const errorCode = typeof exchange === 'string' ? exchange : exports.OAUTH_SIGN_IN_FAILED_ERROR;
+                    return abortOAuthSignIn(response, sessionToken, cookieHeader, loginPath, errorCode);
+                }
             }
             return response;
         });

package/dist/lib/nextauth-secret.d.ts

@@ -0,0 +1,51 @@
+/**
+ * resolveNextAuthSecret - COMPATIBILITY SHIM (restored 2026-09-30, PAY-2005 / N7).
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS, AND WHY IT IS A SHIM RATHER THAN A FEATURE
+ * ---------------------------------------------------------------------------
+ * The NextAuth-era broker secret resolver was DELETED in
+ *     4d3d29e6  "feat!: Better Auth 4.0.0 — NextAuth fully removed"
+ * and it is intentionally NOT coming back as first-class API: this package is
+ * Better Auth now, and new apps must not resolve a NextAuth secret at all.
+ *
+ * It is restored here ONLY because ONE consumer is still mid-migration and cannot
+ * take the 4.4.x bump without it:
+ *
+ *   CONSUMER THAT NEEDS THIS: the customer portal
+ *   (`payez_idp_admin_web` / VibeID-Customer-Portal). It is pinned at
+ *   @payez/next-mvp 4.0.46 and still runs BOTH next-auth@4.24 and better-auth; its
+ *   `src/lib/server-session.ts` and `src/lib/session-token.ts` (and 5 route files)
+ *   import `resolveNextAuthSecret` from here. Without this export, bumping the
+ *   portal to 4.4.x breaks its build. BAPert ruled (68003) to ship this scoped
+ *   shim rather than force the portal's full NextAuth->BetterAuth migration
+ *   tonight. That migration is tracked as its own card; WHEN IT LANDS, DELETE
+ *   THIS FILE.
+ *
+ * DO NOT add new consumers. If you are starting an app, use Better Auth's own
+ * secret handling; you do not need this.
+ *
+ * ---------------------------------------------------------------------------
+ * BEHAVIOUR (faithful to the 4.0.46 implementation, with one deliberate change)
+ * ---------------------------------------------------------------------------
+ * Priority: (1) process.env.NEXTAUTH_SECRET if set; (2) fetch from the IDP via a
+ * signed client assertion; (3) cache in-memory 5 min and stamp NEXTAUTH_SECRET.
+ *
+ * DELIBERATE CHANGE, 4.0.46 -> here: 4.0.46 validated the fetched secret with
+ * `validateNextAuthSecret`, which this package's 4.4.x no longer exports (it was
+ * renamed to `validateAuthSecret` with an IDENTICAL body). The shim calls
+ * `validateAuthSecret` - same predicate, current name - so there is no second
+ * copy of the rule. The validation semantics are unchanged.
+ *
+ * SERVER-ONLY: the IDP handshake and NEXTAUTH_SECRET are server concerns.
+ */
+import 'server-only';
+/**
+ * Resolve the NextAuth secret (server-only).
+ *
+ * Priority:
+ * 1) Use process.env.NEXTAUTH_SECRET if present (allows overrides/production)
+ * 2) Fetch from the IDP broker endpoint - the IDP handles all Key Vault/signing
+ * 3) Cache result in-memory and set process.env.NEXTAUTH_SECRET for later calls
+ */
+export declare function resolveNextAuthSecret(): Promise<string>;

package/dist/lib/nextauth-secret.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveNextAuthSecret = resolveNextAuthSecret;
+/**
+ * resolveNextAuthSecret - COMPATIBILITY SHIM (restored 2026-09-30, PAY-2005 / N7).
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS, AND WHY IT IS A SHIM RATHER THAN A FEATURE
+ * ---------------------------------------------------------------------------
+ * The NextAuth-era broker secret resolver was DELETED in
+ *     4d3d29e6  "feat!: Better Auth 4.0.0 — NextAuth fully removed"
+ * and it is intentionally NOT coming back as first-class API: this package is
+ * Better Auth now, and new apps must not resolve a NextAuth secret at all.
+ *
+ * It is restored here ONLY because ONE consumer is still mid-migration and cannot
+ * take the 4.4.x bump without it:
+ *
+ *   CONSUMER THAT NEEDS THIS: the customer portal
+ *   (`payez_idp_admin_web` / VibeID-Customer-Portal). It is pinned at
+ *   @payez/next-mvp 4.0.46 and still runs BOTH next-auth@4.24 and better-auth; its
+ *   `src/lib/server-session.ts` and `src/lib/session-token.ts` (and 5 route files)
+ *   import `resolveNextAuthSecret` from here. Without this export, bumping the
+ *   portal to 4.4.x breaks its build. BAPert ruled (68003) to ship this scoped
+ *   shim rather than force the portal's full NextAuth->BetterAuth migration
+ *   tonight. That migration is tracked as its own card; WHEN IT LANDS, DELETE
+ *   THIS FILE.
+ *
+ * DO NOT add new consumers. If you are starting an app, use Better Auth's own
+ * secret handling; you do not need this.
+ *
+ * ---------------------------------------------------------------------------
+ * BEHAVIOUR (faithful to the 4.0.46 implementation, with one deliberate change)
+ * ---------------------------------------------------------------------------
+ * Priority: (1) process.env.NEXTAUTH_SECRET if set; (2) fetch from the IDP via a
+ * signed client assertion; (3) cache in-memory 5 min and stamp NEXTAUTH_SECRET.
+ *
+ * DELIBERATE CHANGE, 4.0.46 -> here: 4.0.46 validated the fetched secret with
+ * `validateNextAuthSecret`, which this package's 4.4.x no longer exports (it was
+ * renamed to `validateAuthSecret` with an IDENTICAL body). The shim calls
+ * `validateAuthSecret` - same predicate, current name - so there is no second
+ * copy of the rule. The validation semantics are unchanged.
+ *
+ * SERVER-ONLY: the IDP handshake and NEXTAUTH_SECRET are server concerns.
+ */
+require("server-only");
+const node_crypto_1 = require("node:crypto");
+const secret_validation_1 = require("./secret-validation");
+let cachedSecret = null;
+let lastFetchedAt = 0;
+const CACHE_TTL_MS = 5 * 60 * 1000;
+/**
+ * Resolve the NextAuth secret (server-only).
+ *
+ * Priority:
+ * 1) Use process.env.NEXTAUTH_SECRET if present (allows overrides/production)
+ * 2) Fetch from the IDP broker endpoint - the IDP handles all Key Vault/signing
+ * 3) Cache result in-memory and set process.env.NEXTAUTH_SECRET for later calls
+ */
+async function resolveNextAuthSecret() {
+    // Check if already in environment
+    if (process.env.NEXTAUTH_SECRET && process.env.NEXTAUTH_SECRET.trim() !== '') {
+        return process.env.NEXTAUTH_SECRET;
+    }
+    // Check if cached and fresh (within 5 minutes)
+    if (cachedSecret && Date.now() - lastFetchedAt < CACHE_TTL_MS) {
+        return cachedSecret;
+    }
+    // Broker mode: fetch from the IDP (the IDP handles all Key Vault/signing)
+    const base = process.env.IDP_URL;
+    if (!base)
+        throw new Error('IDP_URL environment variable is required');
+    const clientIdStr = process.env.CLIENT_ID;
+    if (!clientIdStr || clientIdStr.trim() === '') {
+        throw new Error('CLIENT_ID is required (e.g., "ideal_resume_website")');
+    }
+    // Step 1: ask the IDP to sign a client assertion (the IDP holds the keys, not us)
+    const signingUrl = `${base.replace(/\/$/, '')}/api/ExternalAuth/sign-client-assertion`;
+    const signingResp = await fetch(signingUrl, {
+        method: 'POST',
+        headers: {
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+            'X-Client-Id': clientIdStr,
+            'X-Correlation-Id': (0, node_crypto_1.randomUUID)().replace(/-/g, ''),
+        },
+        body: JSON.stringify({
+            issuer: clientIdStr,
+            subject: clientIdStr,
+            audience: 'urn:payez:externalauth:nextauthsecret',
+            expires_in: 60,
+        }),
+        cache: 'no-store',
+    });
+    if (!signingResp.ok) {
+        const txt = await signingResp.text().catch(() => 'Unknown error');
+        throw new Error(`Failed to sign client assertion: ${signingResp.status} ${signingResp.statusText} - ${txt}`);
+    }
+    const signingBody = (await signingResp.json().catch(() => ({})));
+    const clientAssertion = signingBody?.data?.client_assertion ??
+        signingBody?.data?.clientAssertion ??
+        signingBody?.client_assertion ??
+        signingBody?.clientAssertion ??
+        signingBody?.data?.ClientAssertion ??
+        signingBody?.ClientAssertion;
+    if (!clientAssertion || typeof clientAssertion !== 'string') {
+        throw new Error('IDP did not return a valid signed client assertion');
+    }
+    // Step 2: use the signed assertion to fetch the NextAuth secret
+    const proxyUrl = `${base.replace(/\/$/, '')}/api/ExternalAuth/next-auth/secret`;
+    const proxyResp = await fetch(proxyUrl, {
+        method: 'POST',
+        headers: {
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+            'X-Client-Id': clientIdStr,
+            'X-Correlation-Id': (0, node_crypto_1.randomUUID)().replace(/-/g, ''),
+        },
+        body: JSON.stringify({ client_assertion: clientAssertion }),
+        cache: 'no-store',
+    });
+    if (!proxyResp.ok) {
+        const txt = await proxyResp.text().catch(() => 'Unknown error');
+        throw new Error(`Proxy error: ${proxyResp.status} ${proxyResp.statusText} - ${txt}`);
+    }
+    const proxyBody = (await proxyResp.json().catch(() => ({})));
+    const secret = proxyBody?.data?.secret ?? proxyBody?.secret;
+    // `configuration` is available from the IDP but deliberately not logged.
+    if (!secret || typeof secret !== 'string') {
+        throw new Error('Proxy did not return a valid NextAuth secret');
+    }
+    // Same predicate as 4.0.46's validateNextAuthSecret, under its current name.
+    const validation = (0, secret_validation_1.validateAuthSecret)(secret);
+    if (!validation.valid) {
+        throw new Error(`Fetched NextAuth secret failed validation: ${validation.reason}`);
+    }
+    cachedSecret = secret;
+    lastFetchedAt = Date.now();
+    process.env.NEXTAUTH_SECRET = secret;
+    console.log('[NEXTAUTH-SECRET] Resolved from IDP (length:', secret.length + ')');
+    return secret;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.4.7",
+  "version": "4.4.8",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -129,6 +129,11 @@
       "require": "./dist/lib/session-store.js",
       "default": "./dist/lib/session-store.js"
     },
+    "./lib/nextauth-secret": {
+      "types": "./dist/lib/nextauth-secret.d.ts",
+      "require": "./dist/lib/nextauth-secret.js",
+      "default": "./dist/lib/nextauth-secret.js"
+    },
     "./lib/ensure-fresh-access-token": {
       "types": "./dist/lib/ensure-fresh-access-token.d.ts",
       "require": "./dist/lib/ensure-fresh-access-token.js",

package/src/auth/better-auth.ts

@@ -281,19 +281,42 @@ export function buildBetterAuthProviders(
       clientSecret: oauth.clientSecret,
       scope: wireScopes.length > 0 ? wireScopes : undefined,
       /**
-       * 260419 — CLOSE THE SECOND SELF-SERVE PROVISIONING DOOR. 259805 gated
-       * the signup BFF on allow_public_registration, but the social lane never
-       * touches that code: better-auth creates the user through its own
-       * internalAdapter at the OAuth callback, and its ONLY guard is this flag.
+       * PAY-2005 — DISABLE-SIGN-UP IS REMOVED, DELIBERATELY. DO NOT RE-ADD IT.
        *
-       * Wired from the tenant's own policy, explicit-true-opens: the IDP config
-       * keeps allowPublicRegistration UNDEFINED when the tenant never answered
-       * (idp-client-config.ts, the no-fabricated-default rule), and an
-       * unanswered policy question must not provision accounts. That matches
-       * the FE's silent-default-is-decline posture for the "Create account"
-       * affordance. A tenant that wants Google self-serve says so.
+       * 260419 wired this from `config.authSettings?.allowPublicRegistration` to
+       * close a client-side self-serve provisioning door. It cannot do that job
+       * correctly, and it BREAKS SIGN-IN:
+       *
+       *   - This app runs better-auth in STATELESS mode (no DB adapter — see the
+       *     file header). better-auth therefore has NO user store, so at the OAuth
+       *     callback it cannot tell an EXISTING user from a NEW one. Its
+       *     handleOAuthUserInfo consults `disableSignUp` for BOTH, so
+       *     `disableSignUp: true` refuses a returning user exactly like a
+       *     stranger. Measured live 2026-09-30 (PAY-2005): portal.keelauth.com
+       *     Google sign-in bounced to /sign-in with Better Auth `signup_disabled`
+       *     once client 12's allow_public_registration reported false.
+       *
+       *   - The REAL registration gate already exists and is correct, at the IDP:
+       *     PayEz.External.Id.Api ExternalAuthController.oauth-callback looks the
+       *     user up by verified email (:799); an existing user logs in UNTOUCHED
+       *     (:811); only the isNewUser branch (:853) calls INewUserRegistrar,
+       *     which refuses fail-closed when the client forbids public registration
+       *     (NewUserRegistrar.cs:65, `SecurityFlags.AllowPublicRegistration != true`).
+       *     Its own comment states the contract: "existing federated users ...
+       *     log in untouched, so gating here never blocks login."
+       *
+       * So this flag was a DUPLICATE gate that could only ever misfire — it cannot
+       * distinguish new from existing, and the IDP already refuses new identities.
+       * Removing it restores sign-in for existing users WITHOUT reopening
+       * self-serve: a NEW identity that completes the better-auth leg still gets
+       * REFUSED at the IDP exchange and never receives IDP tokens, which is the
+       * portal's actual authorization gate.
+       *
+       * WHERE "no self-serve sign-up" IS ENFORCED NOW: the IDP's NewUserRegistrar
+       * (above) as the backstop, and each app's own front-door sign-up gate
+       * (e.g. the portal's signup-gate.ts / SignUpCard) for the UI affordance.
+       * Both are correct and neither is this flag.
        */
-      disableSignUp: config.authSettings?.allowPublicRegistration !== true,
       // Google is overly eager to reuse the last account unless we
       // explicitly ask for account selection on each social login.
       prompt: typeof rawPrompt === 'string'
@@ -984,11 +1007,17 @@ export async function getBetterAuthHandler(): Promise<{ GET: (req: Request) => P
  * header of the response to find the BA Redis key.
  *
  * This replaces the old databaseHooks approach which doesn't fire in stateless mode.
+ *
+ * RETURNS the IdP's own error code on an IDP refusal, or null otherwise
+ * (PAY-2005 scenario (b), BAPert ruling 67897). It used to return a bare
+ * boolean, so `REGISTRATION_NOT_ALLOWED` was indistinguishable from a network
+ * blip and every cause collapsed to one generic login-page code — a NEW user
+ * refused registration bounced silently, which is the failure Jon named.
  */
 export async function exchangeOAuthForIdpTokens(
   sessionToken: string,
   provider: string = 'google'
-): Promise<boolean> {
+): Promise<boolean | string> {
   try {
     const config = await getIDPClientConfig();
     const appSlug = config.clientSlug || getAppSlug();
@@ -1081,6 +1110,36 @@ export async function exchangeOAuthForIdpTokens(
     if (!oauthRes.ok) {
       console.error('[BETTER_AUTH] IDP oauth-callback failed:', oauthRes.status);
 
+      /**
+       * PAY-2005 scenario (b) — RETURN THE IDP'S ERROR CODE (BAPert ruling 67897).
+       *
+       * Every refusal used to return a bare `false`, so the abort collapsed ALL
+       * causes to one generic `OAUTH_SIGN_IN_FAILED`: a NEW user refused
+       * registration (`REGISTRATION_NOT_ALLOWED`, ExternalAuthController.cs:908)
+       * bounced silently, indistinguishable from a network blip. Jon named the
+       * clear message explicitly (67856): "(b) a brand-new Google user with
+       * registration OFF is refused by the IDP with a clear message, not a
+       * silent bounce."
+       *
+       * The envelope is `{ error: { code, message } }` (PayEzControllerBase.Error).
+       * We read ONLY `error.code` and return it VERBATIM — the abort puts it in
+       * the `?error=` param, and the HOST's allowlist decides whether to render
+       * it. The package does NOT interpret the code and does NOT add a message
+       * (that would be a second allowlist). No code in the body -> null (the
+       * generic host code), exactly as before.
+       */
+      let idpErrorCode: string | null = null;
+      try {
+        const parsed = JSON.parse(oauthResText);
+        // FORWARD ONLY AN ALLOWLISTED CODE. Every other refusal keeps PAY-1733's single neutral code — an
+        // unlisted code would render nothing on the host page, which is the silent bounce this exists to end.
+        if (typeof parsed?.error?.code === 'string' && IDP_ERROR_CODES_TO_FORWARD.has(parsed.error.code)) {
+          idpErrorCode = parsed.error.code;
+        }
+      } catch {
+        /* non-JSON refusal body -> no code (generic abort) */
+      }
+
       /**
        * WHY THIS LOGS ONLY ON FAILURE, AND WHY IT LOGS THESE FIELDS.
        *
@@ -1128,7 +1187,7 @@ export async function exchangeOAuthForIdpTokens(
         sent_client_id: resolveClientKey(config, 'auth/better-auth:oauth-callback').key ?? null,
         idp_url: idpUrl,
       });
-      return false;
+      return idpErrorCode ?? false;
     }
 
     let idpData: any;
@@ -1138,6 +1197,7 @@ export async function exchangeOAuthForIdpTokens(
     if (!result?.access_token) {
       console.warn('[BETTER_AUTH] IDP oauth-callback returned no access_token. Keys:', Object.keys(result || {}));
       return false;
+
     }
 
     // Build IDP token data
@@ -1248,6 +1308,7 @@ export async function exchangeOAuthForIdpTokens(
     // Storage is shared with the passkey sign-in path — see storeIdpTokensInSession.
     const stored = await storeIdpTokensInSession(sessionToken, idpTokenData, provider);
     if (stored) console.log('[BETTER_AUTH] IDP tokens stored in session for', email);
+    // true = success (tokens stored). false = a non-IdP failure with no specific code (generic abort).
     return stored;
   } catch (err) {
     console.error('[BETTER_AUTH] IDP token exchange failed:', err instanceof Error ? err.message : String(err));
@@ -1255,6 +1316,7 @@ export async function exchangeOAuthForIdpTokens(
   }
 }
 
+
 /**
  * Write IDP tokens into an EXISTING Better Auth session. Storage only — this
  * function never acquires tokens and never decides who the caller is.
@@ -1351,6 +1413,19 @@ export async function storeIdpTokensInSession(
  */
 export const OAUTH_SIGN_IN_FAILED_ERROR = 'OAUTH_SIGN_IN_FAILED';
 
+/**
+ * The ONLY IdP refusal codes the package forwards to the login page (PAY-2005 (b), BAPert 67897).
+ *
+ * Default stays PAY-1733's ONE neutral code: the cause of an ordinary failed exchange lives in the server
+ * log, never on the page. A code is forwarded ONLY when it earns a distinct user-facing message — today just
+ * the registration refusal, so a NEW Google user with registration OFF sees a clear "not open to sign-up"
+ * line instead of a silent bounce. Adding a code here REQUIRES a matching entry in the host allowlist
+ * (portal: src/lib/auth/magic-link-outcome.ts); an unlisted code renders nothing, which is a silent bounce
+ * wearing a different number. Add them together, never one alone.
+ */
+export const IDP_ERROR_CODES_TO_FORWARD: ReadonlySet<string> = new Set(['REGISTRATION_NOT_ALLOWED']);
+
+
 /**
  * Re-emit each cookie the callback response SET as an immediate expiry, keeping the attributes that decide
  * WHICH cookie the browser overwrites (Path, Domain, Secure, SameSite, HttpOnly - a `__Secure-` name is only
@@ -1387,6 +1462,7 @@ async function abortOAuthSignIn(
   sessionToken: string | null,
   cookieHeader: string,
   loginPath: string,
+  errorCode: string = OAUTH_SIGN_IN_FAILED_ERROR,
 ): Promise<Response> {
   const headers = new Headers();
   if (sessionToken) {
@@ -1405,8 +1481,8 @@ async function abortOAuthSignIn(
     }
   }
   for (const sc of expireSetCookies(callbackResponse.headers.getSetCookie?.() ?? [])) headers.append('set-cookie', sc);
-  headers.set('location', `${loginPath}${loginPath.includes('?') ? '&' : '?'}error=${OAUTH_SIGN_IN_FAILED_ERROR}`);
-  console.warn('[BETTER_AUTH] OAuth sign-in ABORTED: the IdP exchange stored no tokens, so no session is kept (PAY-1733)', sessionToken ? tokenLogId(sessionToken) : '(no session)');
+  headers.set('location', `${loginPath}${loginPath.includes('?') ? '&' : '?'}error=${errorCode}`);
+  console.warn('[BETTER_AUTH] OAuth sign-in ABORTED: the IdP exchange stored no tokens, so no session is kept (PAY-1733)', sessionToken ? tokenLogId(sessionToken) : '(no session)', 'code=' + errorCode);
   return new Response(null, { status: 302, headers });
 }
 
@@ -1498,7 +1574,9 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
         .map((c: string) => c.split(';')[0])
         .join('; ');
       let sessionToken: string | null = null;
-      let exchanged = false;
+      // true = tokens stored; false = no specific IdP code (generic abort); a string = the IdP's own refusal code
+      // (PAY-2005 (b): REGISTRATION_NOT_ALLOWED, etc.), forwarded so the host can show a clear message.
+      let exchange: boolean | string = false;
       try {
         const auth = await getBetterAuthInstance();
         if (auth?.api?.getSession) {
@@ -1509,7 +1587,7 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
           if (session?.session?.token) {
             sessionToken = session.session.token;
             console.log('[BETTER_AUTH] Got session token from callback:', tokenLogId(session.session.token), '| email:', session.user?.email);
-            exchanged = await exchangeOAuthForIdpTokens(session.session.token);
+            exchange = await exchangeOAuthForIdpTokens(session.session.token);
           } else {
             console.warn('[BETTER_AUTH] Could not get session after OAuth callback');
           }
@@ -1517,7 +1595,11 @@ export function createAuthGetHandler(loginPath: string = '/account-auth/login')
       } catch (err: any) {
         console.error('[BETTER_AUTH] IDP token exchange failed:', err.message);
       }
-      if (!exchanged) return abortOAuthSignIn(response, sessionToken, cookieHeader, loginPath);
+      if (exchange !== true) {
+        // A specific IdP error code goes on the URL; otherwise the generic OAUTH_SIGN_IN_FAILED.
+        const errorCode = typeof exchange === 'string' ? exchange : OAUTH_SIGN_IN_FAILED_ERROR;
+        return abortOAuthSignIn(response, sessionToken, cookieHeader, loginPath, errorCode);
+      }
     }
 
     return response;

package/src/lib/nextauth-secret.ts

@@ -0,0 +1,168 @@
+/**
+ * resolveNextAuthSecret - COMPATIBILITY SHIM (restored 2026-09-30, PAY-2005 / N7).
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS, AND WHY IT IS A SHIM RATHER THAN A FEATURE
+ * ---------------------------------------------------------------------------
+ * The NextAuth-era broker secret resolver was DELETED in
+ *     4d3d29e6  "feat!: Better Auth 4.0.0 — NextAuth fully removed"
+ * and it is intentionally NOT coming back as first-class API: this package is
+ * Better Auth now, and new apps must not resolve a NextAuth secret at all.
+ *
+ * It is restored here ONLY because ONE consumer is still mid-migration and cannot
+ * take the 4.4.x bump without it:
+ *
+ *   CONSUMER THAT NEEDS THIS: the customer portal
+ *   (`payez_idp_admin_web` / VibeID-Customer-Portal). It is pinned at
+ *   @payez/next-mvp 4.0.46 and still runs BOTH next-auth@4.24 and better-auth; its
+ *   `src/lib/server-session.ts` and `src/lib/session-token.ts` (and 5 route files)
+ *   import `resolveNextAuthSecret` from here. Without this export, bumping the
+ *   portal to 4.4.x breaks its build. BAPert ruled (68003) to ship this scoped
+ *   shim rather than force the portal's full NextAuth->BetterAuth migration
+ *   tonight. That migration is tracked as its own card; WHEN IT LANDS, DELETE
+ *   THIS FILE.
+ *
+ * DO NOT add new consumers. If you are starting an app, use Better Auth's own
+ * secret handling; you do not need this.
+ *
+ * ---------------------------------------------------------------------------
+ * BEHAVIOUR (faithful to the 4.0.46 implementation, with one deliberate change)
+ * ---------------------------------------------------------------------------
+ * Priority: (1) process.env.NEXTAUTH_SECRET if set; (2) fetch from the IDP via a
+ * signed client assertion; (3) cache in-memory 5 min and stamp NEXTAUTH_SECRET.
+ *
+ * DELIBERATE CHANGE, 4.0.46 -> here: 4.0.46 validated the fetched secret with
+ * `validateNextAuthSecret`, which this package's 4.4.x no longer exports (it was
+ * renamed to `validateAuthSecret` with an IDENTICAL body). The shim calls
+ * `validateAuthSecret` - same predicate, current name - so there is no second
+ * copy of the rule. The validation semantics are unchanged.
+ *
+ * SERVER-ONLY: the IDP handshake and NEXTAUTH_SECRET are server concerns.
+ */
+import 'server-only';
+import { randomUUID } from 'node:crypto';
+import { validateAuthSecret } from './secret-validation';
+
+let cachedSecret: string | null = null;
+let lastFetchedAt = 0;
+
+const CACHE_TTL_MS = 5 * 60 * 1000;
+
+interface SigningResponse {
+  data?: { client_assertion?: string; clientAssertion?: string; ClientAssertion?: string };
+  client_assertion?: string;
+  clientAssertion?: string;
+  ClientAssertion?: string;
+}
+
+interface SecretResponse {
+  data?: { secret?: string; configuration?: unknown };
+  secret?: string;
+  configuration?: unknown;
+}
+
+/**
+ * Resolve the NextAuth secret (server-only).
+ *
+ * Priority:
+ * 1) Use process.env.NEXTAUTH_SECRET if present (allows overrides/production)
+ * 2) Fetch from the IDP broker endpoint - the IDP handles all Key Vault/signing
+ * 3) Cache result in-memory and set process.env.NEXTAUTH_SECRET for later calls
+ */
+export async function resolveNextAuthSecret(): Promise<string> {
+  // Check if already in environment
+  if (process.env.NEXTAUTH_SECRET && process.env.NEXTAUTH_SECRET.trim() !== '') {
+    return process.env.NEXTAUTH_SECRET;
+  }
+
+  // Check if cached and fresh (within 5 minutes)
+  if (cachedSecret && Date.now() - lastFetchedAt < CACHE_TTL_MS) {
+    return cachedSecret;
+  }
+
+  // Broker mode: fetch from the IDP (the IDP handles all Key Vault/signing)
+  const base = process.env.IDP_URL;
+  if (!base) throw new Error('IDP_URL environment variable is required');
+
+  const clientIdStr = process.env.CLIENT_ID;
+  if (!clientIdStr || clientIdStr.trim() === '') {
+    throw new Error('CLIENT_ID is required (e.g., "ideal_resume_website")');
+  }
+
+  // Step 1: ask the IDP to sign a client assertion (the IDP holds the keys, not us)
+  const signingUrl = `${base.replace(/\/$/, '')}/api/ExternalAuth/sign-client-assertion`;
+  const signingResp = await fetch(signingUrl, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      'X-Client-Id': clientIdStr,
+      'X-Correlation-Id': randomUUID().replace(/-/g, ''),
+    },
+    body: JSON.stringify({
+      issuer: clientIdStr,
+      subject: clientIdStr,
+      audience: 'urn:payez:externalauth:nextauthsecret',
+      expires_in: 60,
+    }),
+    cache: 'no-store',
+  });
+
+  if (!signingResp.ok) {
+    const txt = await signingResp.text().catch(() => 'Unknown error');
+    throw new Error(`Failed to sign client assertion: ${signingResp.status} ${signingResp.statusText} - ${txt}`);
+  }
+
+  const signingBody = (await signingResp.json().catch(() => ({}))) as SigningResponse;
+  const clientAssertion =
+    signingBody?.data?.client_assertion ??
+    signingBody?.data?.clientAssertion ??
+    signingBody?.client_assertion ??
+    signingBody?.clientAssertion ??
+    signingBody?.data?.ClientAssertion ??
+    signingBody?.ClientAssertion;
+
+  if (!clientAssertion || typeof clientAssertion !== 'string') {
+    throw new Error('IDP did not return a valid signed client assertion');
+  }
+
+  // Step 2: use the signed assertion to fetch the NextAuth secret
+  const proxyUrl = `${base.replace(/\/$/, '')}/api/ExternalAuth/next-auth/secret`;
+  const proxyResp = await fetch(proxyUrl, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      'X-Client-Id': clientIdStr,
+      'X-Correlation-Id': randomUUID().replace(/-/g, ''),
+    },
+    body: JSON.stringify({ client_assertion: clientAssertion }),
+    cache: 'no-store',
+  });
+
+  if (!proxyResp.ok) {
+    const txt = await proxyResp.text().catch(() => 'Unknown error');
+    throw new Error(`Proxy error: ${proxyResp.status} ${proxyResp.statusText} - ${txt}`);
+  }
+
+  const proxyBody = (await proxyResp.json().catch(() => ({}))) as SecretResponse;
+  const secret = proxyBody?.data?.secret ?? proxyBody?.secret;
+  // `configuration` is available from the IDP but deliberately not logged.
+
+  if (!secret || typeof secret !== 'string') {
+    throw new Error('Proxy did not return a valid NextAuth secret');
+  }
+
+  // Same predicate as 4.0.46's validateNextAuthSecret, under its current name.
+  const validation = validateAuthSecret(secret);
+  if (!validation.valid) {
+    throw new Error(`Fetched NextAuth secret failed validation: ${validation.reason}`);
+  }
+
+  cachedSecret = secret;
+  lastFetchedAt = Date.now();
+  process.env.NEXTAUTH_SECRET = secret;
+
+  console.log('[NEXTAUTH-SECRET] Resolved from IDP (length:', secret.length + ')');
+  return secret;
+}

package/src/vibe/document-unwrap.ts

@@ -1,103 +1,103 @@
-/**
- * Vibe document wrapper + unwrapping.
- *
- * PAY-1767: extracted from generic.ts into its own module so the typed client (client.ts) can unwrap
- * reads WITHOUT importing generic.ts - generic.ts imports client.ts, so a shared helper there would be
- * a cycle. This module imports nothing from the vibe client.
- *
- * Vibe stores a row's own fields as a JSON STRING under the wrapper's `data` field, alongside storage
- * columns (document_id, owner, timestamps). A caller that renders `response.data` directly sees the
- * wrapper, so `row.name` is undefined. unwrapVibeDocument flattens the row out and keeps the storage
- * document_id as `_vibe_doc_id` for update/delete paths.
- */
-
-/** Vibe document wrapper structure. Vibe stores actual table data as a JSON string in the 'data' field. */
-export interface VibeDocumentWrapper {
-  document_id: number;
-  client_id?: number;
-  user_id?: number;
-  collection?: string;
-  table_name?: string;
-  data: string | Record<string, unknown>;
-  collection_schema_id?: number;
-  created_at?: string;
-  created_by?: number;
-  updated_at?: string | null;
-  updated_by?: number | null;
-  deleted_at?: string | null;
-}
-
-/**
- * Unwrap a Vibe document response.
- *
- * @param doc - Raw Vibe document (wrapper format)
- * @returns Unwrapped document with schema fields only; storage document_id preserved as `_vibe_doc_id`
- *          for update/delete paths. See PayEz-Core/docs/vibe-primary-key-standard.md
- *
- * @example
- * const raw = { document_id: 123, data: '{"user_id":15,"name":"John"}' };
- * unwrapVibeDocument(raw); // => { user_id: 15, name: 'John', _vibe_doc_id: 123 }
- */
-export function unwrapVibeDocument<T extends object = Record<string, unknown>>(
-  doc: VibeDocumentWrapper | Record<string, unknown> | null | undefined
-): (T & { _vibe_doc_id?: number }) | null {
-  if (!doc) return null;
-
-  // Handle case where doc is already unwrapped (has schema fields directly)
-  if (!('document_id' in doc) && !('data' in doc)) {
-    return doc as T & { _vibe_doc_id?: number };
-  }
-
-  const wrapper = doc as VibeDocumentWrapper;
-  let parsedData: Record<string, unknown> = {};
-
-  if (typeof wrapper.data === 'string') {
-    try {
-      parsedData = JSON.parse(wrapper.data);
-    } catch {
-      console.warn('[vibe-document] Failed to parse document data JSON:', wrapper.data);
-      parsedData = {};
-    }
-  } else if (typeof wrapper.data === 'object' && wrapper.data !== null) {
-    parsedData = wrapper.data;
-  }
-
-  // Preserve document_id as _vibe_doc_id for Vibe API update/delete paths only
-  const documentId = wrapper.document_id ?? (doc as { document_id?: number }).document_id;
-  if (documentId != null) {
-    parsedData._vibe_doc_id = documentId;
-  }
-
-  return parsedData as T & { _vibe_doc_id?: number };
-}
-
-/**
- * Extract and unwrap an array of documents from a Vibe response.
- *
- * @param responseData - Raw Vibe API response ({ data: [...] }, { items: [...] }, { documents: [...] } or a bare array)
- * @returns Array of unwrapped documents
- */
-export function extractVibeDocuments<T extends Record<string, unknown> = Record<string, unknown>>(
-  responseData: unknown
-): Array<T & { _vibe_doc_id?: number }> {
-  if (!responseData || typeof responseData !== 'object') {
-    return [];
-  }
-
-  const data = responseData as Record<string, unknown>;
-
-  // Try common response shapes
-  const docs =
-    data.data ??
-    data.items ??
-    data.documents ??
-    (Array.isArray(responseData) ? responseData : null);
-
-  if (!Array.isArray(docs)) {
-    return [];
-  }
-
-  return docs
-    .map((doc) => unwrapVibeDocument<T>(doc))
-    .filter((d): d is T & { _vibe_doc_id?: number } => d !== null);
-}
+/**
+ * Vibe document wrapper + unwrapping.
+ *
+ * PAY-1767: extracted from generic.ts into its own module so the typed client (client.ts) can unwrap
+ * reads WITHOUT importing generic.ts - generic.ts imports client.ts, so a shared helper there would be
+ * a cycle. This module imports nothing from the vibe client.
+ *
+ * Vibe stores a row's own fields as a JSON STRING under the wrapper's `data` field, alongside storage
+ * columns (document_id, owner, timestamps). A caller that renders `response.data` directly sees the
+ * wrapper, so `row.name` is undefined. unwrapVibeDocument flattens the row out and keeps the storage
+ * document_id as `_vibe_doc_id` for update/delete paths.
+ */
+
+/** Vibe document wrapper structure. Vibe stores actual table data as a JSON string in the 'data' field. */
+export interface VibeDocumentWrapper {
+  document_id: number;
+  client_id?: number;
+  user_id?: number;
+  collection?: string;
+  table_name?: string;
+  data: string | Record<string, unknown>;
+  collection_schema_id?: number;
+  created_at?: string;
+  created_by?: number;
+  updated_at?: string | null;
+  updated_by?: number | null;
+  deleted_at?: string | null;
+}
+
+/**
+ * Unwrap a Vibe document response.
+ *
+ * @param doc - Raw Vibe document (wrapper format)
+ * @returns Unwrapped document with schema fields only; storage document_id preserved as `_vibe_doc_id`
+ *          for update/delete paths. See PayEz-Core/docs/vibe-primary-key-standard.md
+ *
+ * @example
+ * const raw = { document_id: 123, data: '{"user_id":15,"name":"John"}' };
+ * unwrapVibeDocument(raw); // => { user_id: 15, name: 'John', _vibe_doc_id: 123 }
+ */
+export function unwrapVibeDocument<T extends object = Record<string, unknown>>(
+  doc: VibeDocumentWrapper | Record<string, unknown> | null | undefined
+): (T & { _vibe_doc_id?: number }) | null {
+  if (!doc) return null;
+
+  // Handle case where doc is already unwrapped (has schema fields directly)
+  if (!('document_id' in doc) && !('data' in doc)) {
+    return doc as T & { _vibe_doc_id?: number };
+  }
+
+  const wrapper = doc as VibeDocumentWrapper;
+  let parsedData: Record<string, unknown> = {};
+
+  if (typeof wrapper.data === 'string') {
+    try {
+      parsedData = JSON.parse(wrapper.data);
+    } catch {
+      console.warn('[vibe-document] Failed to parse document data JSON:', wrapper.data);
+      parsedData = {};
+    }
+  } else if (typeof wrapper.data === 'object' && wrapper.data !== null) {
+    parsedData = wrapper.data;
+  }
+
+  // Preserve document_id as _vibe_doc_id for Vibe API update/delete paths only
+  const documentId = wrapper.document_id ?? (doc as { document_id?: number }).document_id;
+  if (documentId != null) {
+    parsedData._vibe_doc_id = documentId;
+  }
+
+  return parsedData as T & { _vibe_doc_id?: number };
+}
+
+/**
+ * Extract and unwrap an array of documents from a Vibe response.
+ *
+ * @param responseData - Raw Vibe API response ({ data: [...] }, { items: [...] }, { documents: [...] } or a bare array)
+ * @returns Array of unwrapped documents
+ */
+export function extractVibeDocuments<T extends Record<string, unknown> = Record<string, unknown>>(
+  responseData: unknown
+): Array<T & { _vibe_doc_id?: number }> {
+  if (!responseData || typeof responseData !== 'object') {
+    return [];
+  }
+
+  const data = responseData as Record<string, unknown>;
+
+  // Try common response shapes
+  const docs =
+    data.data ??
+    data.items ??
+    data.documents ??
+    (Array.isArray(responseData) ? responseData : null);
+
+  if (!Array.isArray(docs)) {
+    return [];
+  }
+
+  return docs
+    .map((doc) => unwrapVibeDocument<T>(doc))
+    .filter((d): d is T & { _vibe_doc_id?: number } => d !== null);
+}