@payez/next-mvp 4.4.5 → 4.4.7

package/dist/lib/idp-client-config.js

@@ -74,12 +74,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.providerSecretEnvVar = providerSecretEnvVar;
 exports.getIDPClientConfig = getIDPClientConfig;
 exports.clearConfigCache = clearConfigCache;
 exports.clearConfigRedisCache = clearConfigRedisCache;
 exports.getEnabledProviders = getEnabledProviders;
 require("server-only");
 const crypto_1 = require("crypto");
+const never_in_response_1 = require("./never-in-response");
 // REDIS IS IMPORTED LAZILY, AND THAT IS LOAD-BEARING.
 // A module-scope `import redis from './redis'` drags ioredis into EVERY bundle that
 // touches this file - including instrumentation.ts. Next compiles the instrumentation
@@ -124,6 +126,55 @@ async function getRedis() {
 const OPERATOR_AUTH_SECRET = process.env.BETTER_AUTH_SECRET;
 const OPERATOR_NEXTAUTH_SECRET = process.env.NEXTAUTH_SECRET;
 let operatorOverrideLogged = false;
+function providerSecretEnvVar(provider) {
+    return `${String(provider).trim().toUpperCase().replace(/[^A-Z0-9]+/g, '_')}_CLIENT_SECRET`;
+}
+const loggedSecretSources = new Map();
+function logSecretSource(what, source) {
+    if (loggedSecretSources.get(what) === source)
+        return;
+    loggedSecretSources.set(what, source);
+    console.log(`[IDP_CONFIG] ${what} source: ${source}`);
+}
+function resolveAuthSecret(fromConfig) {
+    if (OPERATOR_AUTH_SECRET)
+        return { value: OPERATOR_AUTH_SECRET, source: 'env:BETTER_AUTH_SECRET' };
+    if (OPERATOR_NEXTAUTH_SECRET)
+        return { value: OPERATOR_NEXTAUTH_SECRET, source: 'env:NEXTAUTH_SECRET' };
+    if (fromConfig)
+        return { value: fromConfig, source: 'idp-config' };
+    return { value: '', source: 'none' };
+}
+/** A copy of `config` with every secret resolved env-first. Never mutates (the argument may be cached). */
+function applyEnvSecrets(config) {
+    const auth = resolveAuthSecret(config.authSecret);
+    logSecretSource('authSecret', auth.source);
+    // PAY-1529: every secret this module resolves is registered as never-in-response HERE, the one place
+    // both fetch paths and the Redis read pass through, so the runtime backstop knows the value whichever
+    // handler later tries to serialize it.
+    (0, never_in_response_1.markNeverInResponse)(auth.value);
+    return {
+        ...config,
+        authSecret: auth.value,
+        oauthProviders: (config.oauthProviders ?? []).map((p) => {
+            const envVar = providerSecretEnvVar(p.provider);
+            const fromEnv = process.env[envVar];
+            const source = fromEnv ? `env:${envVar}` : p.clientSecret ? 'idp-config' : 'none';
+            logSecretSource(`${p.provider} clientSecret`, source);
+            const clientSecret = fromEnv || p.clientSecret;
+            (0, never_in_response_1.markNeverInResponse)(clientSecret);
+            return { ...p, clientSecret };
+        }),
+    };
+}
+/** What may be persisted to Redis: env-sourced secrets are blanked (the environment re-supplies them on read). */
+function stripEnvSecrets(config) {
+    return {
+        ...config,
+        authSecret: OPERATOR_AUTH_SECRET || OPERATOR_NEXTAUTH_SECRET ? '' : config.authSecret,
+        oauthProviders: (config.oauthProviders ?? []).map((p) => process.env[providerSecretEnvVar(p.provider)] ? { ...p, clientSecret: '' } : p),
+    };
+}
 /** Publish the resolved auth secret WITHOUT ever overwriting an operator-set value. */
 function publishAuthSecret(value, source) {
     if (OPERATOR_AUTH_SECRET) {
@@ -234,7 +285,8 @@ async function setConfigInRedis(config) {
         const key = getRedisConfigKey();
         const ttlSeconds = config.configCacheTtlSeconds || 300;
         const data = {
-            config,
+            // PAY-1460: never persist a secret the environment supplied.
+            config: stripEnvSecrets(config),
             expiresAt: Date.now() + (ttlSeconds * 1000)
         };
         // Store with TTL slightly longer than the logical expiry to allow for clock skew
@@ -289,7 +341,10 @@ async function getIDPClientConfig(forceRefresh = false) {
     }
     // Layer 2: Check Redis cache (skip if forceRefresh - startup should always get fresh data)
     if (!forceRefresh) {
-        const redisConfig = await getConfigFromRedis();
+        // PAY-1460: a cached entry never carries env-sourced secrets (stripEnvSecrets), so the
+        // environment is re-applied on read, BEFORE the emptiness test below.
+        const cachedRaw = await getConfigFromRedis();
+        const redisConfig = cachedRaw ? applyEnvSecrets(cachedRaw) : null;
         // A cached entry is only USABLE if it carries a secret — see the note
         // below. `redisConfig && !authSecret` must behave like a cache MISS, so
         // the emptiness test belongs here, in the condition that gates the
@@ -433,7 +488,7 @@ async function getIDPClientConfig(forceRefresh = false) {
             // This throw is what stops that. It is also what turned the
             // 2026-08-05 nextauth_secret spelling bug into a loud FATAL instead
             // of a silently forgeable app.
-            throw new Error('[IDP_CONFIG] FATAL: IDP did not return authSecret');
+            throw new Error('[IDP_CONFIG] FATAL: IDP did not return authSecret and neither BETTER_AUTH_SECRET nor NEXTAUTH_SECRET is set');
         }
         // Validated above — only now is it safe to cache or publish.
         publishAuthSecret(config.authSecret, 'freshly-fetched IDP config');
@@ -503,7 +558,7 @@ async function fetchConfigFromInternalIDP(internalIdpUrl, clientIdStr) {
     });
     if (!resp.ok) {
         const txt = await resp.text().catch(() => 'Unknown error');
-        throw new Error(`[IDP_CONFIG] FATAL: Internal IDP returned ${resp.status} - ${txt}`);
+        throw new Error(`[IDP_CONFIG] FATAL: Internal IDP returned ${resp.status} (body ${txt.length} chars)`); // PAY-1427
     }
     const body = await resp.json().catch(() => null);
     if (!body) {
@@ -514,7 +569,7 @@ async function fetchConfigFromInternalIDP(internalIdpUrl, clientIdStr) {
     if (rawClientId === undefined || rawClientId === null) {
         throw new Error(`[IDP_CONFIG] FATAL: Internal IDP response missing clientId. Got: ${JSON.stringify(Object.keys(configData))}`);
     }
-    const config = {
+    const config = applyEnvSecrets({
         clientId: String(rawClientId),
         clientSlug: configData.clientSlug ?? configData.client_slug ?? configData.slug ?? '',
         // Wire compatibility: accept new authSecret first, fall back to legacy
@@ -575,12 +630,12 @@ async function fetchConfigFromInternalIDP(internalIdpUrl, clientIdStr) {
             logoUrl: configData.branding?.logoUrl ?? configData.branding?.logo_url
         },
         baseClientUrl: configData.baseClientUrl ?? configData.base_client_url ?? configData.BaseClientUrl
-    };
+    });
     if (!config.authSecret) {
         // LOAD-BEARING — see the note on the external path's equivalent throw.
         // An empty secret reaching betterAuth() becomes the PUBLIC default, not an
         // error. Never replace this with a fallback.
-        throw new Error('[IDP_CONFIG] FATAL: Internal IDP did not return authSecret');
+        throw new Error('[IDP_CONFIG] FATAL: Internal IDP did not return authSecret and neither BETTER_AUTH_SECRET nor NEXTAUTH_SECRET is set');
     }
     console.log(`[IDP_CONFIG] Internal IDP config loaded for ${clientIdStr}`);
     consecutiveFailures = 0;
@@ -649,7 +704,8 @@ async function fetchConfigFromIDP(idpUrl, clientIdStr) {
         });
         if (!signingResp.ok) {
             const txt = await signingResp.text().catch(() => 'Unknown error');
-            throw new Error(`[IDP_CONFIG] FATAL: Failed to sign client assertion: ${signingResp.status} - ${txt}`);
+            // PAY-1427: the thrown message is logged by callers - body length only, never the upstream text.
+            throw new Error(`[IDP_CONFIG] FATAL: Failed to sign client assertion: ${signingResp.status} (body ${txt.length} chars)`);
         }
         const signingBody = await signingResp.json().catch(() => null);
         if (!signingBody) {
@@ -660,7 +716,8 @@ async function fetchConfigFromIDP(idpUrl, clientIdStr) {
         const client_assertion = (signingBody?.data?.client_assertion ??
             signingBody?.data?.clientAssertion);
         if (!client_assertion) {
-            console.error('[IDP_CONFIG] FATAL: Full response body:', JSON.stringify(signingBody, null, 2));
+            // PAY-1427: never the full sign-client-assertion body (assertion material). Key names only.
+            console.error('[IDP_CONFIG] FATAL: sign-client-assertion response shape:', { keys: Object.keys(signingBody || {}), dataKeys: Object.keys(signingBody?.data || {}) });
             throw new Error(`[IDP_CONFIG] FATAL: IDP response missing client_assertion. Got keys: ${JSON.stringify(Object.keys(signingBody?.data || signingBody || {}))}`);
         }
         // Step 2: Fetch client config using the assertion
@@ -673,42 +730,12 @@ async function fetchConfigFromIDP(idpUrl, clientIdStr) {
                 'X-Client-Id': clientIdStr,
                 'X-Correlation-Id': (0, crypto_1.randomUUID)().replace(/-/g, ''),
             },
-            // 217917 PHASE 1: explicit opt-in for provider secrets.
-            //
-            // This broker is the ONLY consumer of oauth_providers[].client_secret
-            // (DotNetPert enumerated it: this file feeds auth/providers/oauth.ts,
-            // which performs the server-side code exchange). Every OTHER caller of
-            // ExternalAuth/client-config - notably every fielded acp-desktop - is
-            // pushed the same secrets today and reads none of them: the desktop is
-            // PKCE and dropped clientSecret from OAuthProviderConfig entirely.
-            //
-            // The IDP IGNORES this field today, so shipping it is a no-op and needs
-            // no coordination window. Phase 2 (DotNetPert, IDP side) makes
-            // client-config emit the secrets ONLY when the opt-in is present and
-            // redact otherwise - which is why phase 1 MUST be live first, or the
-            // broker loses the field and tenant OAuth sign-in dies.
-            //
-            // SCOPE, deliberately narrow - do NOT read this as a partial migration:
-            // the sibling path fetchConfigFromInternalIDP() hits a DIFFERENT
-            // endpoint (InternalClientConfig/{id}, GET) that is already
-            // authenticated with CONTAINERS_KEY, is not reachable by a desktop, and
-            // is therefore not part of 217917's exposure. It deliberately sends no
-            // opt-in. If phase 2's redaction is implemented in shared config-
-            // assembly code rather than in ExternalAuthController.GetClientConfig,
-            // it will ALSO strip the internal route and break this broker's other
-            // path with no opt-in to save it. Phase 2 must gate on the request.
-            //
-            // NOT A FIX ON ITS OWN: an attacker can set this flag too. Phase 2 ends
-            // the AUTOMATIC delivery of every tenant's provider secrets to every
-            // user laptop; it does not close disclosure to a determined caller.
-            // That residual is card 175047 (unauthenticated mint, global partner
-            // key) and 217917 does not close until 175047 lands or Jon accepts it.
-            body: JSON.stringify({ client_assertion, include_provider_secrets: true }),
+            body: JSON.stringify({ client_assertion }),
             cache: 'no-store'
         });
         if (!configResp.ok) {
             const txt = await configResp.text().catch(() => 'Unknown error');
-            throw new Error(`[IDP_CONFIG] FATAL: Failed to fetch client config: ${configResp.status} - ${txt}`);
+            throw new Error(`[IDP_CONFIG] FATAL: Failed to fetch client config: ${configResp.status} (body ${txt.length} chars)`);
         }
         const configBody = await configResp.json().catch(() => null);
         if (!configBody) {
@@ -717,7 +744,8 @@ async function fetchConfigFromIDP(idpUrl, clientIdStr) {
         // Per PayEz API standard: response is wrapped in { success, data: {...} }
         const configData = configBody?.data;
         if (!configData || typeof configData !== 'object') {
-            console.error('[IDP_CONFIG] FATAL: Full config response body:', JSON.stringify(configBody, null, 2));
+            // PAY-1427: never the full client-config body (client configuration / provider secrets). Key names only.
+            console.error('[IDP_CONFIG] FATAL: client-config response shape:', { keys: Object.keys(configBody || {}) });
             throw new Error('[IDP_CONFIG] FATAL: IDP client-config response missing data envelope');
         }
         // Validate required fields - handle both number and string client_id
@@ -728,7 +756,7 @@ async function fetchConfigFromIDP(idpUrl, clientIdStr) {
         // Map response to our interface (IDP returns camelCase or snake_case).
         // Wire compatibility: accept new authSecret first, fall back to legacy
         // nextAuthSecret/next_auth_secret while IDP rename rolls out.
-        const config = {
+        const config = applyEnvSecrets({
             clientId: String(rawClientId),
             clientSlug: configData.clientSlug ?? configData.client_slug ?? configData.slug ?? '',
             authSecret: configData.authSecret ??
@@ -798,7 +826,7 @@ async function fetchConfigFromIDP(idpUrl, clientIdStr) {
                 logoUrl: configData.branding?.logoUrl ?? configData.branding?.logo_url
             },
             baseClientUrl: configData.baseClientUrl ?? configData.base_client_url ?? configData.BaseClientUrl
-        };
+        });
         // Debug: log what we got for baseClientUrl
         console.log(`[IDP_CONFIG] Parsed baseClientUrl:`, config.baseClientUrl, `| raw keys:`, Object.keys(configData).filter(k => k.toLowerCase().includes('client')));
         // Validate we got what we need
@@ -808,7 +836,7 @@ async function fetchConfigFromIDP(idpUrl, clientIdStr) {
         if (!config.authSecret) {
             // LOAD-BEARING — empty must fail here, never downstream. betterAuth()
             // silently substitutes a public constant for an empty secret.
-            throw new Error('[IDP_CONFIG] FATAL: authSecret is empty after parsing');
+            throw new Error('[IDP_CONFIG] FATAL: authSecret is empty after parsing and neither BETTER_AUTH_SECRET nor NEXTAUTH_SECRET is set');
         }
         // Success - reset failure tracking
         consecutiveFailures = 0;

package/dist/lib/idp-fetch.js

@@ -77,7 +77,7 @@ async function ensureFreshAccessToken(req) {
     const sessionToken = (token?.sessionToken || token?.redisSessionId);
     console.log('[IDP_FETCH] ensureFreshAccessToken:', {
         hasToken: !!token,
-        sessionToken: sessionToken?.substring(0, 20) + '...',
+        hasSessionToken: !!sessionToken, // PAY-1427 / BAPert 58829: no token material in logs, not even a stub (was a 20-char prefix)
         pathname: req.nextUrl.pathname
     });
     if (!sessionToken) {

package/dist/lib/never-in-response.d.ts

@@ -0,0 +1,30 @@
+/**
+ * PAY-1529 runtime backstop: the signing secret and the OAuth provider client secrets must never be
+ * serialized into an HTTP response body.
+ *
+ * The build-time guard (test/secrets-never-in-response-source-guard.test.cjs) follows values through the
+ * source it can see. This is the layer for what it cannot see — a value that crosses a module boundary,
+ * a structuredClone / Object.assign copy, a helper in a consumer app. It tracks the secret by VALUE:
+ * the loader registers every resolved secret here at the moment it resolves it (applyEnvSecrets), and a
+ * response built with `secretSafeJson` / checked with `assertNoServerSecret` FAILS CLOSED — it throws,
+ * and the route answers 500 — if any registered value appears anywhere in the serialized body, under any
+ * key, at any depth, whatever the code that built it called it.
+ *
+ * Bounds, stated rather than implied:
+ *  - Values shorter than MIN_SECRET_LENGTH are not registered. A short string matches innocent bodies and
+ *    would turn this into an outage generator; real signing and provider secrets are far longer.
+ *  - It protects responses that go through it. Adoption is per handler; the build-time guard is what
+ *    covers the handlers that do not.
+ *  - Nothing here ever logs, returns or throws a secret value.
+ */
+import { NextResponse } from 'next/server';
+export declare const MIN_SECRET_LENGTH = 16;
+/** Record a value that must never appear in a response body. Non-strings and short strings are ignored. */
+export declare function markNeverInResponse(value: unknown): void;
+export declare class SecretInResponseError extends Error {
+    constructor(where: string);
+}
+/** Throws SecretInResponseError if any registered secret appears in `body` once serialized. */
+export declare function assertNoServerSecret(body: unknown, where: string): void;
+/** NextResponse.json, refusing any body that carries a registered secret. */
+export declare function secretSafeJson<T>(body: T, init: ResponseInit | undefined, where: string): NextResponse<T>;

package/dist/lib/never-in-response.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecretInResponseError = exports.MIN_SECRET_LENGTH = void 0;
+exports.markNeverInResponse = markNeverInResponse;
+exports.assertNoServerSecret = assertNoServerSecret;
+exports.secretSafeJson = secretSafeJson;
+/**
+ * PAY-1529 runtime backstop: the signing secret and the OAuth provider client secrets must never be
+ * serialized into an HTTP response body.
+ *
+ * The build-time guard (test/secrets-never-in-response-source-guard.test.cjs) follows values through the
+ * source it can see. This is the layer for what it cannot see — a value that crosses a module boundary,
+ * a structuredClone / Object.assign copy, a helper in a consumer app. It tracks the secret by VALUE:
+ * the loader registers every resolved secret here at the moment it resolves it (applyEnvSecrets), and a
+ * response built with `secretSafeJson` / checked with `assertNoServerSecret` FAILS CLOSED — it throws,
+ * and the route answers 500 — if any registered value appears anywhere in the serialized body, under any
+ * key, at any depth, whatever the code that built it called it.
+ *
+ * Bounds, stated rather than implied:
+ *  - Values shorter than MIN_SECRET_LENGTH are not registered. A short string matches innocent bodies and
+ *    would turn this into an outage generator; real signing and provider secrets are far longer.
+ *  - It protects responses that go through it. Adoption is per handler; the build-time guard is what
+ *    covers the handlers that do not.
+ *  - Nothing here ever logs, returns or throws a secret value.
+ */
+const server_1 = require("next/server");
+exports.MIN_SECRET_LENGTH = 16;
+const registered = new Set();
+/** Record a value that must never appear in a response body. Non-strings and short strings are ignored. */
+function markNeverInResponse(value) {
+    if (typeof value !== 'string' || value.length < exports.MIN_SECRET_LENGTH)
+        return;
+    registered.add(value);
+    // JSON escapes some characters, so the serialized form of a secret containing `"` or `\` differs from
+    // the raw value. Register that form too, or such a secret would pass through a JSON body unseen.
+    const escaped = JSON.stringify(value).slice(1, -1);
+    if (escaped !== value)
+        registered.add(escaped);
+}
+class SecretInResponseError extends Error {
+    constructor(where) {
+        // The message names the route, never the value.
+        super(`[PAY-1529] Refused to serialize a server secret into the response of ${where}`);
+        this.name = 'SecretInResponseError';
+    }
+}
+exports.SecretInResponseError = SecretInResponseError;
+/** Throws SecretInResponseError if any registered secret appears in `body` once serialized. */
+function assertNoServerSecret(body, where) {
+    if (registered.size === 0 || body === undefined || body === null)
+        return;
+    let text;
+    try {
+        text = typeof body === 'string' ? body : JSON.stringify(body);
+    }
+    catch {
+        // Unserializable: NextResponse.json would throw on it anyway. Fail closed rather than guess.
+        throw new SecretInResponseError(where);
+    }
+    if (!text)
+        return;
+    for (const secret of registered) {
+        if (text.includes(secret))
+            throw new SecretInResponseError(where);
+    }
+}
+/** NextResponse.json, refusing any body that carries a registered secret. */
+function secretSafeJson(body, init, where) {
+    assertNoServerSecret(body, where);
+    return server_1.NextResponse.json(body, init);
+}

package/dist/lib/password-rules.d.ts

@@ -0,0 +1,22 @@
+/**
+ * PAY-1591: the one sentence that states the password rules on the recovery set-password step.
+ *
+ * Built ONLY from the policy the IdP reported (usePasswordValidation.policy). A rule that is off is not stated, and with
+ * no policy at all we state no number: telling a user "at least 8 characters" when the client is configured for 12 is
+ * the same defect as saying nothing, one step later.
+ */
+export interface PasswordPolicyLike {
+    min_length?: number;
+    require_uppercase?: boolean;
+    require_lowercase?: boolean;
+    require_digit?: boolean;
+    require_special?: boolean;
+}
+export declare function passwordRulesText(policy: PasswordPolicyLike | undefined | null): string;
+/**
+ * PAY-1591: the IdP's reset refusal names WHICH rules failed as codes (error.details.rules). This is the closed set the
+ * portal accepts and the one plain sentence for each. Anything outside it is dropped, never displayed or forwarded.
+ */
+export declare const PASSWORD_RULE_SENTENCES: Readonly<Record<string, string>>;
+export declare function knownPasswordRules(rules: unknown): string[];
+export declare function passwordRuleSentences(rules: string[]): string;

package/dist/lib/password-rules.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PASSWORD_RULE_SENTENCES = void 0;
+exports.passwordRulesText = passwordRulesText;
+exports.knownPasswordRules = knownPasswordRules;
+exports.passwordRuleSentences = passwordRuleSentences;
+function passwordRulesText(policy) {
+    if (!policy || typeof policy.min_length !== 'number') {
+        return "Use a password that meets this site's rules. We'll show what is missing as you type.";
+    }
+    const parts = [`at least ${policy.min_length} characters`];
+    if (policy.require_uppercase)
+        parts.push('an upper-case letter');
+    if (policy.require_lowercase)
+        parts.push('a lower-case letter');
+    if (policy.require_digit)
+        parts.push('a number');
+    if (policy.require_special)
+        parts.push('a symbol');
+    const [first, ...rest] = parts;
+    return rest.length ? `Your password needs ${first}, with ${rest.join(', ')}.` : `Your password needs ${first}.`;
+}
+/**
+ * PAY-1591: the IdP's reset refusal names WHICH rules failed as codes (error.details.rules). This is the closed set the
+ * portal accepts and the one plain sentence for each. Anything outside it is dropped, never displayed or forwarded.
+ */
+exports.PASSWORD_RULE_SENTENCES = {
+    min_length: 'Use a longer password.',
+    uppercase: 'Add an upper-case letter.',
+    lowercase: 'Add a lower-case letter.',
+    digit: 'Add a number.',
+    special: 'Add a symbol.',
+    unique_chars: 'Use more different characters.',
+    recent_password: "Choose a password you haven't used recently.",
+};
+function knownPasswordRules(rules) {
+    if (!Array.isArray(rules))
+        return [];
+    return rules.filter((r) => typeof r === 'string' && Object.prototype.hasOwnProperty.call(exports.PASSWORD_RULE_SENTENCES, r));
+}
+function passwordRuleSentences(rules) {
+    return rules.map((r) => exports.PASSWORD_RULE_SENTENCES[r]).join(' ');
+}

package/dist/lib/safe-error-response.d.ts

@@ -0,0 +1,67 @@
+/**
+ * PAY-1438: what a USER-FACING handler may put in an error response.
+ *
+ * Several of these routes are reachable before authentication (session check, viability probe,
+ * logout, auth status, refresh-viability), so whatever lands in the body reaches an anonymous caller.
+ *
+ * Class A - an EXCEPTION: its text (ioredis `connect ECONNREFUSED host:port`, undici `fetch failed`,
+ * JSON parse errors quoting payload bytes) stays server-side. The response carries a fixed message,
+ * a code and a correlationId; the log line carries the exception and the same id.
+ *
+ * Class B - an IDP ERROR ENVELOPE ({ success, message, error: { code, message, details, support } }):
+ * never passed through whole. Only the display contract is projected: code, message, resolution,
+ * request_id - each only when it is a string. `details` (free-form, may carry validation internals
+ * or exception data) is dropped, except for the password-policy messages change-password's UI reads.
+ */
+export interface IdpErrorProjection {
+    code?: string;
+    message?: string;
+    resolution?: string;
+    request_id?: string;
+}
+/** Log an exception with a fresh correlationId and return the id for the response body. */
+export declare function logExceptionWithCorrelation(tag: string, err: unknown): string;
+/** Whitelisted projection of an IDP error envelope: code / message / resolution / request_id only. */
+export declare function projectIdpError(json: unknown): IdpErrorProjection;
+/**
+ * change-password's `details`: the security pages show `details.value[0].message` (else
+ * `details.message`) as the password-policy error (QAPert census on PAY-1438). Keep exactly those
+ * strings; drop everything else.
+ */
+export declare function projectPasswordPolicyDetails(details: unknown): {
+    message?: string;
+    value?: Array<{
+        message: string;
+    }>;
+} | undefined;
+/**
+ * For proxies that used to pass the IDP response through WHOLE on every status (account recovery,
+ * reset-password, passkey sign-in - all anonymous): on a non-OK status, return the same envelope
+ * SHAPE callers already read (`message`, `error.code`, `error.message`) built only from the
+ * whitelisted projection. The success path keeps its passthrough.
+ */
+export declare function idpErrorEnvelope(json: unknown, fallbackMessage?: string): {
+    success: false;
+    message: string;
+    error: {
+        code?: string;
+        message: string;
+        resolution?: string;
+    };
+    request_id?: string;
+};
+/**
+ * True only when the IdP EXPLICITLY says the recovery token itself is unusable: details.code token_expired / token_used, or an
+ * ASP.NET Identity `InvalidToken` error in details.value (what the served IdP sends when ResetPasswordAsync refuses a used or
+ * expired token, AccountController.ResetPassword line ~699 at b5c56e6c0). Only this boolean crosses the anonymous route, never the
+ * Identity error text. Anything else is NOT a dead-link signal (rigpert 60822): an older IdP sends a weak-password refusal with
+ * no code at all, and calling that 'link expired' loops the user.
+ */
+export declare function projectResetTokenInvalid(json: unknown): boolean;
+/**
+ * PAY-1591: the IdP refuses a reset password with error.details = { code: 'password_policy', rules: [codes], requirements:
+ * [English] }. This route is anonymous, so only the CODES cross, and only the known ones: never `requirements`, never an
+ * unknown string. Returns undefined when this is NOT a password-policy refusal, and [] when it is one but names no rule we know
+ * (the caller must be able to tell a refused password from a dead recovery session).
+ */
+export declare function projectPasswordPolicyRules(json: unknown): string[] | undefined;

package/dist/lib/safe-error-response.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * PAY-1438: what a USER-FACING handler may put in an error response.
+ *
+ * Several of these routes are reachable before authentication (session check, viability probe,
+ * logout, auth status, refresh-viability), so whatever lands in the body reaches an anonymous caller.
+ *
+ * Class A - an EXCEPTION: its text (ioredis `connect ECONNREFUSED host:port`, undici `fetch failed`,
+ * JSON parse errors quoting payload bytes) stays server-side. The response carries a fixed message,
+ * a code and a correlationId; the log line carries the exception and the same id.
+ *
+ * Class B - an IDP ERROR ENVELOPE ({ success, message, error: { code, message, details, support } }):
+ * never passed through whole. Only the display contract is projected: code, message, resolution,
+ * request_id - each only when it is a string. `details` (free-form, may carry validation internals
+ * or exception data) is dropped, except for the password-policy messages change-password's UI reads.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logExceptionWithCorrelation = logExceptionWithCorrelation;
+exports.projectIdpError = projectIdpError;
+exports.projectPasswordPolicyDetails = projectPasswordPolicyDetails;
+exports.idpErrorEnvelope = idpErrorEnvelope;
+exports.projectResetTokenInvalid = projectResetTokenInvalid;
+exports.projectPasswordPolicyRules = projectPasswordPolicyRules;
+const password_rules_1 = require("./password-rules");
+const str = (v) => (typeof v === 'string' ? v : undefined);
+/** Log an exception with a fresh correlationId and return the id for the response body. */
+function logExceptionWithCorrelation(tag, err) {
+    const correlationId = globalThis.crypto.randomUUID();
+    console.error(tag, { correlationId, error: err });
+    return correlationId;
+}
+/** Whitelisted projection of an IDP error envelope: code / message / resolution / request_id only. */
+function projectIdpError(json) {
+    if (!json || typeof json !== 'object')
+        return {};
+    const top = json;
+    const err = top.error && typeof top.error === 'object' ? top.error : {};
+    const support = err.support && typeof err.support === 'object' ? err.support : {};
+    const out = {};
+    const code = str(err.code) ?? str(top.code) ?? str(top.error_code);
+    const message = str(err.message) ?? str(top.message);
+    const resolution = str(err.resolution) ?? str(top.resolution);
+    const requestId = str(support.request_id) ?? str(top.request_id);
+    if (code !== undefined)
+        out.code = code;
+    if (message !== undefined)
+        out.message = message;
+    if (resolution !== undefined)
+        out.resolution = resolution;
+    if (requestId !== undefined)
+        out.request_id = requestId;
+    return out;
+}
+/**
+ * change-password's `details`: the security pages show `details.value[0].message` (else
+ * `details.message`) as the password-policy error (QAPert census on PAY-1438). Keep exactly those
+ * strings; drop everything else.
+ */
+function projectPasswordPolicyDetails(details) {
+    if (!details || typeof details !== 'object')
+        return undefined;
+    const d = details;
+    const out = {};
+    if (Array.isArray(d.value)) {
+        const value = d.value
+            .map((v) => (v && typeof v === 'object' ? str(v.message) : undefined))
+            .filter((m) => m !== undefined)
+            .map((message) => ({ message }));
+        if (value.length)
+            out.value = value;
+    }
+    const message = str(d.message);
+    if (message !== undefined)
+        out.message = message;
+    return out.value || out.message !== undefined ? out : undefined;
+}
+/**
+ * For proxies that used to pass the IDP response through WHOLE on every status (account recovery,
+ * reset-password, passkey sign-in - all anonymous): on a non-OK status, return the same envelope
+ * SHAPE callers already read (`message`, `error.code`, `error.message`) built only from the
+ * whitelisted projection. The success path keeps its passthrough.
+ */
+function idpErrorEnvelope(json, fallbackMessage = 'Request failed') {
+    const p = projectIdpError(json);
+    const message = p.message ?? fallbackMessage;
+    const error = { message };
+    if (p.code !== undefined)
+        error.code = p.code;
+    if (p.resolution !== undefined)
+        error.resolution = p.resolution;
+    const out = { success: false, message, error };
+    if (p.request_id !== undefined)
+        out.request_id = p.request_id;
+    return out;
+}
+/**
+ * True only when the IdP EXPLICITLY says the recovery token itself is unusable: details.code token_expired / token_used, or an
+ * ASP.NET Identity `InvalidToken` error in details.value (what the served IdP sends when ResetPasswordAsync refuses a used or
+ * expired token, AccountController.ResetPassword line ~699 at b5c56e6c0). Only this boolean crosses the anonymous route, never the
+ * Identity error text. Anything else is NOT a dead-link signal (rigpert 60822): an older IdP sends a weak-password refusal with
+ * no code at all, and calling that 'link expired' loops the user.
+ */
+function projectResetTokenInvalid(json) {
+    if (!json || typeof json !== 'object')
+        return false;
+    const top = json;
+    const err = top.error && typeof top.error === 'object' ? top.error : {};
+    const details = (err.details && typeof err.details === 'object' ? err.details : top.details && typeof top.details === 'object' ? top.details : null);
+    if (!details)
+        return false;
+    if (details.code === 'token_expired' || details.code === 'token_used')
+        return true;
+    return Array.isArray(details.value) && details.value.some((v) => !!v && typeof v === 'object' && v.code === 'InvalidToken');
+}
+/**
+ * PAY-1591: the IdP refuses a reset password with error.details = { code: 'password_policy', rules: [codes], requirements:
+ * [English] }. This route is anonymous, so only the CODES cross, and only the known ones: never `requirements`, never an
+ * unknown string. Returns undefined when this is NOT a password-policy refusal, and [] when it is one but names no rule we know
+ * (the caller must be able to tell a refused password from a dead recovery session).
+ */
+function projectPasswordPolicyRules(json) {
+    if (!json || typeof json !== 'object')
+        return undefined;
+    const top = json;
+    const err = top.error && typeof top.error === 'object' ? top.error : {};
+    const details = (err.details && typeof err.details === 'object' ? err.details : top.details && typeof top.details === 'object' ? top.details : null);
+    if (!details || details.code !== 'password_policy')
+        return undefined;
+    return (0, password_rules_1.knownPasswordRules)(details.rules);
+}