@payez/next-mvp 4.10.0 → 4.12.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog — @payez/next-mvp
 
+## 4.12.0 (to be published under dist-tag `next` only, after 4.11.0; `latest` stays 4.8.9 until Jon says otherwise)
+
+A minor: PII-in-logs groups 1, 2, 3a and 3b, the GOV-023 signout BREAKING change, the logout-401 FIX (PAY-2396), and the BREAKING site-logger signatures (3b: callers of `siteEvents.loginFailed` / `siteEvents.error` must change).
+
+
+- **BREAKING: `siteEvents.loginFailed` and `siteEvents.error` (`lib/site-logger`) lose their free-text parameters (PII-in-logs group 3b, BAPert 76553 Q2).** `loginFailed({ reason, url?, user_agent?, ip_address? })` no longer takes `email`; the `reason` is stored only if it is a closed UPPER_SNAKE code, anything else is stored as `UNSPECIFIED`. `error({ code, user_id?, url?, user_agent?, ip_address? })` takes a closed `code` instead of `message`, `error` and `stack`; the stored message is the fixed sentence `Application error` and the code goes in `context.code`. The parameters are removed from the TYPE, so a TypeScript caller that still passes `email`, `message`, `error` or `stack` fails to compile, which is the point. **Migration:** replace `loginFailed({ reason: 'bad password', email })` with `loginFailed({ reason: 'BAD_PASSWORD' })` (look the user up by `user_id` elsewhere if support needs it), and `error({ message: err.message, stack: err.stack })` with `error({ code: 'YOUR_CLOSED_CODE' })`. Callers found: the package itself calls only `siteEvents.logout`; VibeID-Customer-Portal 0; idealvibe.online 0 `siteEvents.*` (it has its own copy of `lib/site-logger.ts`, which keeps the old shapes until its own caller PR); UMI-Website 0 (not verified against its repo). Row: `test/next-mvp-pii-logs-group3b.test.cjs`.
+
+- **BREAKING: `api-handlers/auth/signout` now ends the IdP grant, not only the local session (GOV-023, BAPert 76687).** It used to delete the local record only and make no IdP call, so an app that mounted it left the IdP refresh token live until it expired (`routes/auth/logout` already revoked first). It now runs the same IdP-first path: `revokeSessionAtIdp`, then the local delete, then the cookies. If the IdP revoke fails, or cannot resolve the session while a refresh token is held, or the local delete fails, it answers **HTTP 500** `{ success: false, code: 'SESSION_NOT_ENDED', cause: 'idp_unconfirmed' | 'local_delete_failed', message }` (the same code, causes and sentences as `routes/auth/logout`; both failing: the local cause) instead of `success: true`; the local delete and the cookie clearing still happen. A caller that treated every signout answer as success must now read `success` / `cause`. Ships in the release after 4.11.0 (with the site-logger signature change). Rows: `test/next-mvp-gov023-signout-ends-idp-grant.test.cjs`.
+- **CHANGE: a caught error is logged by its NAME and a closed code/status, never its message (PII-in-logs group 1, BAPert 76553).** New `lib/log-safe` (`errForLog`, `closedCodeForLog`, internal, not in the exports map): `error=<Name> [status=<100-599>] [code=<CLOSED_TOKEN>]`; `message`, `stack`, `cause` and `details` never appear, and a name, status or code that is not a closed shape is dropped. Applied to the shared sites with the widest reach: `logExceptionWithCorrelation` (14 handlers; the line keeps the `correlationId`, the logged `error` is now the string above instead of the raw error object), the four catches in `auth/utils/idp-client` (login, refresh, verify-2FA, send-2FA-code), `api-handlers/session/refresh-viability`'s catch (it logged the exception message next to the correlation id; found by the Mac run of `user-facing-error-not-returned`), and `server/auth`'s `SESSION_READ_SWALLOWED` line (it used to log a redacted, 80-character-truncated message; it now logs `error=<Name>` only). Operators lose the exception text in these log lines on purpose; the correlation id still ties a response to its line. Rows: `test/next-mvp-pii-logs-group1.test.cjs`; `test/pay-2136-no-session-origin.test.cjs` and `test/user-facing-error-not-returned.test.cjs` now assert the opposite of what they did (the message must NOT be in the log).
+- **CHANGE: more caught errors are logged by NAME and closed code/status, not by message (PII-in-logs group 2, BAPert 76767).** The catches in `api-handlers/account/*` (send-code, update-phone, validate-password, verify-email, verify-sms, reset-password, recovery initiate and forward), `api-handlers/mfa/*` (backup-code-verify, totp-verify), `auth/utils/token-utils` (three sites) and `lib/session-store` now log `errForLog(err)` instead of the error object. The response bodies do not change. Row: `test/next-mvp-pii-logs-group2.test.cjs` (a source scan of those 12 files, plus a real-dist token-decode failure whose canary must not reach a log line).
+- **CHANGE: the rest of the server-side caught-error logs use `errForLog` (PII-in-logs group 3a, BAPert 76955).** `api-handlers` (anon preferences, credential-login and its email-code lane, refresh, session viability), `auth` (better-auth, idp-oauth), `lib` (ensure-fresh-access-token, idp-client-config, jwt-decode, redis, site-logger, standardized-client-api, token-lifecycle), `config` (logger, logging-config, vibe-log-transport), `routes/auth` (logout, settings), `server` (auth-guard, decode-session, with-auth) and `middleware` now log the error's name and a closed status/code, not `err`, `err.message` or `String(err)`. `lib/geolocation` no longer logs the IP or the upstream's `data.message` (Q1). The `payez-idp access token refused` line now reads `error=Error code=RESPONSE_ADDRESS_MASKED` or `code=NO_USABLE_EMAIL` (a closed code on the two refusals thrown in `auth/idp-oauth`, BAPert 76998) instead of the reason sentence, so an operator still sees WHY and no message text is logged. Response bodies do not change. Browser code (client, components, hooks, stores) is untouched. Row: `test/next-mvp-pii-logs-group3a.test.cjs`.
+- **FIX: a sign-out whose logout answers 401 now forces one REAL refresh, so a dead grant is no longer reported as "could not confirm the sign-out" (BAPert 77013, QAPert 77012).** After a password change, an admin revoke or a sign-out elsewhere, Core has invalidated the access token while the stored copy still looks fresh. `POST /api/Account/logout` then answered 401, the refresh the 401 triggers answered "already fresh" without asking the IdP, so no discard marker was written and `revokeSessionAtIdp` threw: the route answered `SESSION_NOT_ENDED` / `idp_unconfirmed` and logged "the IdP refresh token is STILL LIVE" for a grant that was already dead. Now `revokeSessionAtIdp` makes the refresh `idpFetchJSON` runs after a 401 a FORCED one, done in-process (`refreshOnAuthFailure` calls `ensureFreshAccessToken` with a window that cannot be "fresh", config from `IDP_URL` / `CLIENT_ID` as `oauth/resume` reads it). Nothing changes on the public `POST /api/auth/refresh`: no header can force a refresh (NightHawk 77021, BAPert 77022). The IdP's answer decides: a refresh 401 with the discard marker is `grant-already-dead` (a successful sign-out); a refresh that succeeds while the logout is still refused means the grant is live and stays `idp_unconfirmed`. The failure is a typed `IdpLogoutUnconfirmedError` (`code` `IDP_LOGOUT_UNCONFIRMED`, `grantLive`); `routes/auth/logout` and `api-handlers/auth/signout` print "STILL LIVE" only when `grantLive` is true and otherwise say the revoke could not be confirmed. `api-handlers/auth/signout` also logs its revoke and session-cleanup errors through `errForLog` now (they passed the raw error). Rows: `test/next-mvp-logout-401-forces-refresh.test.cjs`. A real, unstubbed row (a real password change must land on `notice=password-changed`) is QAPert's walk.
+
+## 4.11.0 (to be published under dist-tag `next` only, after 4.10.0; `latest` stays 4.8.9 until Jon says otherwise)
+
+Carries PRs 1443, 1444, 1445, 1446, 1451, 1452, 1460 and 1461 (and the 1450 design doc): the refresh consolidation (the refresh route is now a thin wrapper over `ensureFreshAccessToken`), the one freshness window, the fetch timeout with the in-doubt marker, and the trace-id cleanup. A minor, because response codes and bodies that callers may match on changed (BREAKING below).
+
+- **BREAKING (for callers that match on refresh error codes, wording or bodies; BAPert 76495 item 4).** Each is detailed in the entries below: (1) a Better-Auth-only session answers 401 `NO_CANONICAL_SESSION` (terminal) where it answered `NO_REFRESH_TOKEN`; (2) a pending-2FA row answers 401 `NO_TOKEN_PENDING_2FA` and is no longer refreshed; (3) new answers `504 UPSTREAM_TIMEOUT` and `401 REFRESH_OUTCOME_UNKNOWN` (a refresh whose outcome is unknown is never replayed); (4) a non-envelope IdP answer on the refresh route is `502 Non-compliant IDP envelope` (was `Upstream non-compliance`); the route's `IDP service unavailable` and `Invalid response from IDP` wording is unchanged (only `ensureFreshAccessToken`'s own result messages changed, see its entry below); (5) the `409 CONFLICT` body gains `retryable: true`; (6) **a bare 401 whose body is not an IdP envelope no longer discards the token** (only the IdP's own verdict does: a typed error with `discard_token`, or the `IDP_DISCARD_TOKEN` path; a bare 401 comes from a proxy or gateway, and DotNetPert 76454 shows every Core refresh 401 is an envelope). Also, a refresh whose result could not be stored answers the terminal `SESSION_PERSIST_FAILED` where the route used to answer a generic 500. A caller that matched the old strings or codes must be updated.
+
+- **FIX: the caller's trace id is cleaned before it is logged (PAY-2376).** `ensureFreshAccessToken` logged `options.requestId` and the refresh route passed the `x-request-id` header into it: attacker-chosen text in the log sink (a newline forges a line, a huge value floods it). New `lib/safe-trace-id` `sanitizeTraceId` removes control characters (C0, DEL, C1, U+2028/U+2029), caps the length at 64 and turns anything that is not a non-empty string into `undefined`; both the route and E use it. Log correlation only: it was never the lock identity. Rows: `test/next-mvp-4910-trace-id-sanitize.test.cjs`.
+- **CHANGE: the last 5-minute freshness literals are on the one refresh window (PAY-2374).** `lib/api-handler.ts` (three sites), `lib/token-lifecycle.ts` (`REFRESH_THRESHOLD_MS`), `auth/utils/token-utils.ts` (`tokenNeedsRefresh`'s default `bufferMs`) and `stores/authStore.ts` (post-rehydration freshness check) and `lib/refresh-token-validator.ts` (`checkRefreshViability`'s buffer, in seconds) now use `REFRESH_WINDOW_MS` from `lib/refresh-window`, the value the refresh route, `ensureFreshAccessToken` and `idp-fetch` already use. No value changes today (all were 5 minutes); the point is that they can no longer drift apart. Cache TTLs and the circuit breaker are not freshness and are left alone. Rows: `test/next-mvp-4910-refresh-window-literals.test.cjs`.
+- **CHANGE: `POST /api/auth/refresh` (`api-handlers/auth/refresh`) is now a thin wrapper over `ensureFreshAccessToken` (BAPert 76449, R-over-E PR 2).** One implementation talks to the IdP, holds the refresh lock and writes the tokens; the route keeps what only an HTTP request has: resolving the session from the Better Auth cookie, the `x-session-token` ownership rejection, the `x-request-id` trace id, and the mapping of E's typed result onto the route's existing JSON bodies and status codes. Success bodies are unchanged (`{ refreshed, [reason: 'already_fresh' | 'completed_by_concurrent_request'], accessTokenExpires, hasRefreshToken }`; the access token is never in a body), as are the bodies for `UNAUTHORIZED`, `NO_REFRESH_TOKEN`, `CONFLICT` and the upstream failures. **What changes for a caller of the route:**
+  - A **Better-Auth-only session** (no canonical row) now answers 401 `NO_CANONICAL_SESSION` (terminal) instead of `NO_REFRESH_TOKEN`; and a session whose row vanished while the request waited for the lock answers 401 `UNAUTHORIZED` (no session).
+  - A row with a refresh token but **no access token** is refreshed only when it is not 2FA-pending; a **pending-2FA** row now answers `NO_TOKEN_PENDING_2FA` instead of being refreshed (refresh is never a way around 2FA).
+  - The IdP envelope rule is E's (no `meta` requirement): a response that is not an envelope is a 502 `Non-compliant IDP envelope` (was `Upstream non-compliance`), and a **bare 401 whose body is not an envelope no longer discards the token**.
+  - The `409 CONFLICT` body gains `retryable: true`; the lock identity prefix is `ensure_fresh_` (not observable). The window (5 min), the fetch timeout, the in-doubt marker, the dropped-persist answer and the `success:false` meaning are the ones already released, now in one place.
+  - Tests: the rows that broke the route's source now break `ensureFreshAccessToken`'s (the same defects, loaded through the real route); new `test/next-mvp-4910-refresh-route-wrapper.test.cjs` pins the wrapper's own mapping, the ownership rejection and the refresh-token requirement. The mutants are loaded through a per-process module hook (`test/lib/swap-dist.cjs`), never written over shipped `dist` files (the test files run in parallel processes).
+
+- **FIX + CHANGE: `ensureFreshAccessToken` brought to what the refresh route does, so the route can become a thin wrapper over it (BAPert 76449, R-over-E PR 1; E only).**
+  - **FIX (twin of the route's 1432 fix): the write-back could put a SPENT refresh token back.** E SENT the post-lock token but its write-back fallbacks (`idpRefreshToken` when the IdP answer carries no new refresh token, `idpRefreshTokenExpires`, `bearerKeyId`, `authenticationMethods`/`authenticationLevel` and the MFA timing fields) read the PRE-lock session, and it spread the whole pre-lock row over the canonical row. If a concurrent request rotated the token while this one waited for the lock and the IdP omitted `refresh_token`, the rotated token was overwritten by the spent one (a dead stored credential), and a concurrent writer's change to any other field was overwritten too. The fallbacks now read the post-lock canonical row, the stored token is the one that was SENT, and only the refreshed fields are written (`updateSession` merges).
+  - **CHANGE: the result carries a `reason`** (`'already_fresh' | 'refreshed' | 'completed_by_concurrent_request'`), additive. `refreshed` is unchanged (it is `true` for both the last two). The route's response bodies, and `lib/token-lifecycle`'s `reason === 'already_fresh'`, are built from it.
+  - **CHANGE: a row with a refresh token but NO access token is refreshed when it is not 2FA-pending** (as the route always did); it used to answer `NO_TOKEN`. A pending-2FA row keeps `NO_TOKEN_PENDING_2FA` even with a refresh token (refresh is never a way around 2FA); no refresh token is `NO_TOKEN` as before.
+  - **CHANGE: `persisted` means the canonical row.** A token served from the Better Auth fallback record is `persisted: false` (it used to say `true`). Nothing in this package reads it.
+  - **CHANGE: `ensureFreshAccessToken`'s result messages now use the route's wording (the route's own wording did not change).** A transport failure answers `'IDP service unavailable'` (it returned the raw error text, which can carry host names and socket details) and an unparseable non-2xx answer `'Invalid response from IDP'` (it answered `'Invalid JSON from IDP'`). Callers of `ensureFreshAccessToken` that matched the old `message` text must be updated; the `code`s are unchanged.
+  - **CHANGE: the IdP envelope rule (BAPert 76455 (B)): no `meta` requirement.** `success` must be a boolean; `success:true` needs `data.access_token` (a string); `success:false` needs `error.code` (a string); `meta`, `request_id` and `time_stamp` are optional; anything else (including `success:true` on a non-2xx, or a non-2xx body that is not an envelope) is a 502 `Non-compliant IDP envelope`, retryable, and DISCARDS NOTHING. Core's four hint-carrying error returns on `POST /api/ExternalAuth/refresh` carry no `meta` (they are the answers that carry `discard_token` / `retryable`), so they are mapped by their code and flags as before. A non-2xx whose body is not an envelope used to be treated by its status alone (a bare 401 discarded the token); it no longer is. Only Core's own verdict (a typed error with `discard_token`, or the `IDP_DISCARD_TOKEN` code path) proves the grant is dead; a bare 401 comes from a proxy or gateway, not from Core's refresh decision (DotNetPert 76454: every Core refresh 401 is an envelope), so it answers the 502 with the token kept and is not in doubt (BAPert 76480).
+  - Rows: `test/next-mvp-4910-ensure-fresh-r-parity.test.cjs` (a mutant per change).
+
+- **FIX: the IdP refresh fetch has a timeout, and a timed-out refresh is never replayed (BAPert 76397 decision 3, corrected by 76403).** Neither the refresh route nor `ensureFreshAccessToken` had a fetch timeout. Core consumes a refresh token with one atomic update and has no reuse grace, and a replay revokes EVERY newer refresh token the user holds, on every device. So a refresh whose answer never arrived is outcome-UNKNOWN: Core may have consumed the token and minted a replacement we never saw, and the store still holds the token we sent. Now: the fetch carries `AbortSignal.timeout(10 s)` (`REFRESH_FETCH_TIMEOUT_MS`, covering the body read too); a timeout answers **504 `UPSTREAM_TIMEOUT`** (`outcomeUnknown: true`, `retryable: false`, `discardToken: false`; `ensureFreshAccessToken` returns the same code with `status: 504`) and writes onto the session row `refreshInDoubtTokenHash`, a SHA-256 of the token that was sent (never the token), and `refreshInDoubtAt`. Any later attempt that would send that same token **refuses without calling the IdP**: terminal 401 **`REFRESH_OUTCOME_UNKNOWN`** (`resolution: 'REAUTHENTICATE'`, `retryable: false`, `discardToken: false`) from both implementations. One login on one session instead of a user-wide revocation. The marker is dropped by the same `updateSession`/`setSession` write that stores a DIFFERENT refresh token; a write that stores the same token keeps it. Nothing tries to resolve the doubt without a login. This also closes the old replay: a hung fetch used to hold the lock for its 60 s TTL and then the next request re-sent the same token. **What changes for you:** a refresh that used to hang now answers 504 after 10 s; consumers that switch on `code` see `UPSTREAM_TIMEOUT` and, afterwards, `REFRESH_OUTCOME_UNKNOWN` (both new). **Any transport failure is outcome-unknown too** (BAPert 76433): a connection reset after the request was written looks the same as a timeout from here. It takes the same path (504 `UPSTREAM_TIMEOUT` plus the marker) UNLESS its cause code proves the request never left: the allowlist is exactly `ECONNREFUSED`, `ENOTFOUND`, `EAI_AGAIN` (read from the error, its `cause` and an AggregateError's members; EVERY code must be on the list). Those stay 503 `UPSTREAM_SERVICE_UNAVAILABLE`, retryable, with no marker. `ECONNRESET`, `UND_ERR_SOCKET`, an error with no code and a mixed list are in doubt; a failure while reading the response body (not a JSON syntax error) is in doubt as well, and so is a **2xx whose body is empty or does not parse** (BAPert 76441: a 2xx means Core processed the grant and consumed the token, so the replacement is lost). A **non-2xx** whose body is not JSON (a gateway HTML 502/503) did not mint and stays a completed failure: 502 `UPSTREAM_SERVICE_ERROR`, no marker. A false in-doubt costs one re-login; a missed one costs a user-wide revocation. Do not add a code to the list without proof it can only occur before the request is sent. The `SessionData` type gains `refreshInDoubtTokenHash` and `refreshInDoubtAt`. Rows: `test/next-mvp-4910-refresh-timeout-in-doubt.test.cjs` (no marker write -> the replay is sent; marker never cleared -> RED; signal removed -> RED).
+
+- **CHANGE: one freshness window, 5 minutes, for the refresh route, `ensureFreshAccessToken` and `lib/idp-fetch` (BAPert 76397 decision 1).** They disagreed: the route and `idp-fetch` used 5 minutes, `ensureFreshAccessToken` used 60 seconds, so a session could be stale to one and fresh to another and two callers rotated a token the other had just rotated. They now share `REFRESH_WINDOW_MS` (`lib/refresh-window`). Core's access-token lifetime is a fixed 15 minutes, so 5 minutes is the ruled value (lifetime / 3 if it were shorter). **What changes for you:** callers of `ensureFreshAccessToken` (`getIdpToken` in `server/auth.ts`, the OAuth resume handler) now refresh up to 4 minutes earlier than before, so slightly more IdP refreshes per token lifetime and never a staler token; the `safetyWindowMs` option still exists and still wins when passed. The route's and `idp-fetch`'s behaviour is unchanged. Row: `test/next-mvp-4910-one-refresh-window.test.cjs` (each path probed at 6 and 4 minutes left, a mutant per path).
+- **FIX: `ensureFreshAccessToken` no longer spends a refresh token it cannot store (BAPert 76397 Finding 1).** It READ a session through the Better Auth fallback but PERSISTED only into the canonical session row (`updateSession` returns `null` when that row is absent). For a session that lives only under the Better Auth key it therefore called the IdP, which rotated and spent the refresh token, could not store the answer, and returned `SESSION_PERSIST_FAILED` with the replacement token lost. It now requires the canonical row BEFORE the IdP call: no row -> no IdP call and a typed terminal answer, 401 `NO_CANONICAL_SESSION` (`terminal`, `discardToken: false`, `retryable: false`, `resolution: 'REAUTHENTICATE'`; the Better Auth record is left alone). `server/auth.ts` forwards `result.code`, so a consumer that switches on codes sees the new one for these sessions, where it saw `SESSION_PERSIST_FAILED` after a spent token. `SESSION_PERSIST_FAILED` remains for a row that disappears after the check. Row: `test/next-mvp-4910-ensure-fresh-canonical-row.test.cjs` (with the check removed it goes RED and the token is lost); the 320072 file now makes the row vanish during the IdP call.
+
+- **FIX: `POST /api/auth/refresh` no longer ignores a dropped persist (BAPert 76392 item 2).** `updateSession` returns `null` when the canonical session row is gone. The refresh route ignored that, so after the IdP exchange had already spent the old refresh token it answered a generic 500 'No access token after refresh'. It now answers 401 `SESSION_PERSIST_FAILED` (`discardToken: true`, `retryable: false`, `resolution: 'REAUTHENTICATE'`), the same code and meaning `ensureFreshAccessToken` has answered since 320072, and logs the drop. Row: `test/next-mvp-4910-refresh-persist-failed.test.cjs` (with the check removed the row goes RED).
+
 ## 4.10.0 (to be published under dist-tag `next` only, after 4.9.0; `latest` stays 4.8.9 until Jon says otherwise)
 
 Carries PRs 1432, 1435 and 1438. A minor, not a patch, because a removed export breaks importers (BREAKING below).

package/dist/api-handlers/account/recovery/forward.js

@@ -7,6 +7,7 @@ const env_1 = require("../../../config/env");
 const idp_client_config_1 = require("../../../lib/idp-client-config");
 const client_key_1 = require("../../../lib/client-key");
 const safe_error_response_1 = require("../../../lib/safe-error-response");
+const log_safe_1 = require("../../../lib/log-safe");
 /**
  * Account recovery - the ONE forwarder behind /recovery/send-code and /recovery/verify-code (PAY-1588).
  *
@@ -61,7 +62,7 @@ async function recoveryClientKey(where) {
         return (0, client_key_1.resolveClientKey)(config, where).key;
     }
     catch (e) {
-        console.error(`[${where}] could not resolve IDP client config for client_id:`, e);
+        console.error(`[${where}] could not resolve IDP client config for client_id:`, (0, log_safe_1.errForLog)(e));
         return null;
     }
 }

package/dist/api-handlers/account/recovery/initiate.js

@@ -5,6 +5,7 @@ const server_1 = require("next/server");
 const idp_client_config_1 = require("../../../lib/idp-client-config");
 const client_key_1 = require("../../../lib/client-key");
 const safe_error_response_1 = require("../../../lib/safe-error-response");
+const log_safe_1 = require("../../../lib/log-safe");
 function getIdpUrl() {
     const url = process.env.IDP_URL;
     if (!url)
@@ -37,7 +38,7 @@ async function recoveryClientKey() {
         return (0, client_key_1.resolveClientKey)(config, 'account/recovery/initiate').key;
     }
     catch (e) {
-        console.error('[account/recovery/initiate] could not resolve IDP client config for client_id:', e);
+        console.error('[account/recovery/initiate] could not resolve IDP client config for client_id:', (0, log_safe_1.errForLog)(e));
         return null;
     }
 }

package/dist/api-handlers/account/reset-password.js

@@ -5,6 +5,7 @@ const server_1 = require("next/server");
 const idp_client_config_1 = require("../../lib/idp-client-config");
 const client_key_1 = require("../../lib/client-key");
 const safe_error_response_1 = require("../../lib/safe-error-response");
+const log_safe_1 = require("../../lib/log-safe");
 function getIdpUrl() {
     const url = process.env.IDP_URL;
     if (!url)
@@ -37,7 +38,7 @@ async function recoveryClientKey() {
         return (0, client_key_1.resolveClientKey)(config, 'account/reset-password').key;
     }
     catch (e) {
-        console.error('[account/reset-password] could not resolve IDP client config for client_id:', e);
+        console.error('[account/reset-password] could not resolve IDP client config for client_id:', (0, log_safe_1.errForLog)(e));
         return null;
     }
 }

package/dist/api-handlers/account/send-code.js

@@ -13,6 +13,7 @@ const server_1 = require("next/server");
 const idp_fetch_1 = require("../../lib/idp-fetch");
 const env_1 = require("../../config/env");
 const two_factor_verify_failure_1 = require("../../lib/two-factor-verify-failure");
+const log_safe_1 = require("../../lib/log-safe");
 async function POST(req) {
     try {
         // Parse request body
@@ -47,7 +48,7 @@ async function POST(req) {
         }, { status: 200 });
     }
     catch (error) {
-        console.error('[SEND_CODE] Error:', error);
+        console.error('[SEND_CODE] Error:', (0, log_safe_1.errForLog)(error));
         return server_1.NextResponse.json({
             success: false,
             error: 'Failed to send verification code',

package/dist/api-handlers/account/update-phone.js

@@ -4,6 +4,7 @@ exports.POST = POST;
 const server_1 = require("next/server");
 const idp_fetch_1 = require("../../lib/idp-fetch");
 const env_1 = require("../../config/env");
+const log_safe_1 = require("../../lib/log-safe");
 /**
  * Update Phone Number API Handler
  *
@@ -63,7 +64,7 @@ async function POST(req) {
         });
     }
     catch (error) {
-        console.error('[UPDATE_PHONE] Error:', error);
+        console.error('[UPDATE_PHONE] Error:', (0, log_safe_1.errForLog)(error));
         return server_1.NextResponse.json({ success: false, error: { code: 'INTERNAL_ERROR', message: 'Failed to update phone number' } }, { status: 500 });
     }
 }

package/dist/api-handlers/account/validate-password.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.POST = POST;
 const server_1 = require("next/server");
+const log_safe_1 = require("../../lib/log-safe");
 async function POST(req) {
     try {
         const body = await req.json();
@@ -88,7 +89,7 @@ async function POST(req) {
         });
     }
     catch (error) {
-        console.error('[VALIDATE_PASSWORD] Error:', error);
+        console.error('[VALIDATE_PASSWORD] Error:', (0, log_safe_1.errForLog)(error));
         return server_1.NextResponse.json({
             is_valid: false,
             score: 0,

package/dist/api-handlers/account/verify-email.js

@@ -16,6 +16,7 @@ const test_aware_get_token_1 = require("../../lib/test-aware-get-token");
 const session_store_1 = require("../../lib/session-store");
 const jwt_decode_1 = require("../../lib/jwt-decode");
 const two_factor_verify_failure_1 = require("../../lib/two-factor-verify-failure");
+const log_safe_1 = require("../../lib/log-safe");
 async function POST(req) {
     try {
         // Parse request body
@@ -108,7 +109,7 @@ async function POST(req) {
         }, { status: 200 });
     }
     catch (error) {
-        console.error('[VERIFY_EMAIL] Error:', error);
+        console.error('[VERIFY_EMAIL] Error:', (0, log_safe_1.errForLog)(error));
         return server_1.NextResponse.json({
             success: false,
             error: 'Failed to verify code',

package/dist/api-handlers/account/verify-sms.js

@@ -16,6 +16,7 @@ const test_aware_get_token_1 = require("../../lib/test-aware-get-token");
 const session_store_1 = require("../../lib/session-store");
 const jwt_decode_1 = require("../../lib/jwt-decode");
 const two_factor_verify_failure_1 = require("../../lib/two-factor-verify-failure");
+const log_safe_1 = require("../../lib/log-safe");
 async function POST(req) {
     try {
         // Parse request body
@@ -108,7 +109,7 @@ async function POST(req) {
         }, { status: 200 });
     }
     catch (error) {
-        console.error('[VERIFY_SMS] Error:', error);
+        console.error('[VERIFY_SMS] Error:', (0, log_safe_1.errForLog)(error));
         return server_1.NextResponse.json({
             success: false,
             error: 'Failed to verify code',

package/dist/api-handlers/anon/preferences.js

@@ -13,6 +13,7 @@ exports.POST = POST;
 const server_1 = require("next/server");
 const headers_1 = require("next/headers");
 const anon_session_1 = require("../../lib/anon-session");
+const log_safe_1 = require("../../lib/log-safe");
 const COOKIE_MAX_AGE = 90 * 24 * 60 * 60; // 90 days in seconds
 /**
  * GET handler - retrieves anonymous session preferences
@@ -45,7 +46,7 @@ async function GET(request) {
         return response;
     }
     catch (error) {
-        console.error('[ANON-PREFERENCES] GET error:', error);
+        console.error('[ANON-PREFERENCES] GET error:', (0, log_safe_1.errForLog)(error));
         return server_1.NextResponse.json({ success: false, error: 'Failed to get preferences' }, { status: 500 });
     }
 }
@@ -90,7 +91,7 @@ async function POST(request) {
         return response;
     }
     catch (error) {
-        console.error('[ANON-PREFERENCES] POST error:', error);
+        console.error('[ANON-PREFERENCES] POST error:', (0, log_safe_1.errForLog)(error));
         return server_1.NextResponse.json({ success: false, error: 'Failed to update preferences' }, { status: 500 });
     }
 }

package/dist/api-handlers/auth/credential-login-email-code.js

@@ -5,6 +5,7 @@ const server_1 = require("next/server");
 const idp_client_config_1 = require("../../lib/idp-client-config");
 const client_key_1 = require("../../lib/client-key");
 const bearer_fetch_1 = require("../../lib/bearer-fetch");
+const log_safe_1 = require("../../lib/log-safe");
 // `export const runtime = 'nodejs'` must be written LITERALLY in the app's route file (Next ignores a re-exported segment config).
 /** One email-code request per this many seconds per browser (the IdP rate-limits too; this stops a double click and a loop). */
 const EMAIL_CODE_COOLDOWN_S = 30;
@@ -39,7 +40,7 @@ async function POST(req) {
         clientKey = (0, client_key_1.resolveClientKey)(config, 'graft/admin-login/email-code').key ?? '';
     }
     catch (err) {
-        console.error('[ADMIN_LOGIN_EMAIL_CODE] IDP client config unavailable:', err instanceof Error ? err.message : String(err));
+        console.error('[ADMIN_LOGIN_EMAIL_CODE] IDP client config unavailable:', (0, log_safe_1.errForLog)(err));
         return server_1.NextResponse.json({ success: false, error: 'Sign-in is temporarily unavailable. This is a problem on our side. Please try again shortly.' }, { status: 503 });
     }
     let sendOk = false;
@@ -70,7 +71,7 @@ async function POST(req) {
         }
     }
     catch (err) {
-        console.error('[ADMIN_LOGIN_EMAIL_CODE] twofa/email/send fetch failed:', err instanceof Error ? err.message : String(err));
+        console.error('[ADMIN_LOGIN_EMAIL_CODE] twofa/email/send fetch failed:', (0, log_safe_1.errForLog)(err));
     }
     if (!sendOk) {
         return server_1.NextResponse.json({ success: false, error: 'We could not ask for an email code just now - this is a problem on our side. Try again shortly.' }, { status: 502 });

package/dist/api-handlers/auth/credential-login.js

@@ -50,6 +50,7 @@ const crypto_1 = require("crypto");
 const device_id_1 = require("../../lib/device-id");
 const twofa_rejection_1 = require("../../lib/twofa-rejection");
 const bearer_fetch_1 = require("../../lib/bearer-fetch");
+const log_safe_1 = require("../../lib/log-safe");
 // `export const runtime = 'nodejs'` must be written LITERALLY in the app's route file (Next ignores a re-exported segment config).
 /**
  * The device id to forward to the IDP for THIS caller — card 240566.
@@ -171,7 +172,7 @@ async function POST(req) {
         config = await (0, idp_client_config_1.getIDPClientConfig)();
     }
     catch (err) {
-        console.error('[ADMIN_LOGIN] IDP client config unavailable — returning 503:', err);
+        console.error('[ADMIN_LOGIN] IDP client config unavailable — returning 503:', (0, log_safe_1.errForLog)(err));
         return server_1.NextResponse.json({
             success: false,
             error: 'Sign-in is temporarily unavailable. This is a problem on our side, not with your details. Please try again shortly.',
@@ -265,7 +266,7 @@ async function POST(req) {
             }
         }
         catch (error) {
-            console.error('[ADMIN-LOGIN] twofa verify fetch failed:', error instanceof Error ? error.message : String(error));
+            console.error('[ADMIN-LOGIN] twofa verify fetch failed:', (0, log_safe_1.errForLog)(error));
             return server_1.NextResponse.json({ success: false, error: 'Unable to reach the authentication service' }, { status: 503 });
         }
         if (!idpResponse.ok) {
@@ -350,7 +351,7 @@ async function POST(req) {
         });
     }
     catch (error) {
-        console.error('[ADMIN-LOGIN] IDP fetch failed:', error instanceof Error ? error.message : String(error));
+        console.error('[ADMIN-LOGIN] IDP fetch failed:', (0, log_safe_1.errForLog)(error));
         return server_1.NextResponse.json({ success: false, error: 'Unable to reach the authentication service' }, { status: 503 });
     }
     const rawText = await idpResponse.text();
@@ -446,7 +447,7 @@ async function POST(req) {
                 }
             }
             catch (err) {
-                console.warn('[ADMIN-LOGIN] mfa/methods fetch failed, defaulting to email lane:', err instanceof Error ? err.message : String(err));
+                console.warn('[ADMIN-LOGIN] mfa/methods fetch failed, defaulting to email lane:', (0, log_safe_1.errForLog)(err));
             }
         }
         // PAY-2314: advertise what this user can actually use, derived from the SAME usableFactors that chose the lane
@@ -523,7 +524,7 @@ async function POST(req) {
                 }
             }
             catch (err) {
-                console.error(`[ADMIN-LOGIN] twofa/${sendLane}/send fetch failed:`, err instanceof Error ? err.message : String(err));
+                console.error(`[ADMIN-LOGIN] twofa/${sendLane}/send fetch failed:`, (0, log_safe_1.errForLog)(err));
             }
         }
         // 267479: `method:'email'` WAS A HARDCODED LITERAL HERE, and it was a lie for

package/dist/api-handlers/auth/refresh.d.ts

@@ -1,37 +1,24 @@
 /**
- * CRITICAL REFRESH TOKEN API HANDLER
+ * REFRESH TOKEN API HANDLER - a thin HTTP wrapper over `ensureFreshAccessToken` (R-over-E, BAPert 76449; design: docs/refresh-r-over-e-delta.md)
  *
- * ASK BEFORE EDITING - TESTED AND WORKING SYSTEM
+ * ASK BEFORE EDITING - this is the route every browser, middleware and `internalRefresh` caller reaches.
  *
- * This handler manages the server-side refresh token cycle with:
- * - Better Auth session extraction (the ONLY way a session is established here)
- * - PayEz IDP refresh token exchange
- * - Session state updates with new tokens
- * - Proper error handling and logging
- * - Single-use semantics enforcement
+ * `lib/ensure-fresh-access-token` is the ONE implementation that talks to the IdP, holds the refresh lock and writes the tokens (post-lock
+ * token, in-doubt marker, fetch timeout, envelope rule, dropped-persist and canonical-row handling all live there). This file keeps what only
+ * an HTTP request has:
+ *  - resolving the session from the request's own Better Auth cookie,
+ *  - the `x-session-token` ownership rejection (below),
+ *  - the `x-request-id` trace id (log correlation only; it is never the lock identity),
+ *  - mapping E's typed result onto this route's existing JSON bodies and status codes.
+ * The bodies did not change except where E's rules did (see CHANGELOG): the browser, `middleware/create-middleware`, `lib/token-lifecycle`
+ * (which reads `reason === 'already_fresh'`) and `lib/idp-fetch` / `lib/api-handler` (via `internalRefresh`) depend on them.
  *
  * ── 246007: THE `x-session-token` FALLBACK IS GONE. IT NOW HARD-DENIES. ────
- * This list previously advertised an x-session-token fallback for internal
- * callers as a current capability. That behaviour has been REMOVED: a request presenting `x-session-token` with
- * no cookie-resolved session of its own is rejected 401 UNAUTHORIZED, because
- * there is no session to establish ownership of the token it names. Accepting
- * it let a caller refresh a session they did not own.
+ * A request presenting `x-session-token` with no cookie-resolved session of its own is rejected 401 UNAUTHORIZED, because there is no
+ * session to establish ownership of the token it names. Accepting it let a caller refresh a session they did not own. This docstring
+ * ships (it is compiled into dist and the .d.ts), so it describes what the code does.
  *
- * The line is corrected here rather than merely deleted, and it is called out
- * rather than quietly dropped, because THIS DOCSTRING SHIPS. It is compiled
- * into dist and into the .d.ts, so it reaches every consumer's editor as hover
- * text. QAPert-NightHawk caught that the fixed build was still describing the
- * removed capability as a current feature (34973) — her verifier tests code
- * properties and reads no comments, so a correct build could have published
- * documentation asserting the opposite of what the code does.
- *
- * That matters twice over: an internal caller relying on the fallback gets a
- * silent behavioural break while the docs promise it still works, and a
- * published package that misdescribes its own auth behaviour is the same
- * amplifier that put other defects onto three surfaces — shipped code carrying
- * instructions for using it wrongly.
- *
- * @version 2.1
+ * @version 3.0
  */
 import { NextRequest, NextResponse } from 'next/server';
 interface RefreshConfig {
@@ -57,38 +44,10 @@ interface RefreshConfig {
  * });
  * ```
  */
-export declare function createRefreshHandler(config: RefreshConfig): (req: NextRequest) => Promise<NextResponse<{
-    error: string;
-    code: string;
-}> | NextResponse<{
-    error: any;
-    code: any;
-    discardToken: boolean;
-    retryable: boolean;
-    resolution: any;
-    status: number;
-}> | NextResponse<{
-    refreshed: boolean;
-    accessTokenExpires: number;
-    hasRefreshToken: boolean;
-}>>;
+export declare function createRefreshHandler(config: RefreshConfig): (req: NextRequest) => Promise<NextResponse<unknown>>;
 /**
  * Default POST export — drop-in for `app/api/auth/refresh/route.ts`.
  * Requires environment variables: IDP_URL, CLIENT_ID
  */
-export declare const POST: (req: NextRequest) => Promise<NextResponse<{
-    error: string;
-    code: string;
-}> | NextResponse<{
-    error: any;
-    code: any;
-    discardToken: boolean;
-    retryable: boolean;
-    resolution: any;
-    status: number;
-}> | NextResponse<{
-    refreshed: boolean;
-    accessTokenExpires: number;
-    hasRefreshToken: boolean;
-}>>;
+export declare const POST: (req: NextRequest) => Promise<NextResponse<unknown>>;
 export {};