@payez/next-mvp 4.8.1 → 4.8.3

package/src/lib/lock-window.ts

@@ -1,49 +1,49 @@
-/**
- * PAY-1608: a 2FA lock's window, stated as the IdP enforces it. Never a hard-coded "15 minutes".
- *
- * Core answers every 2FA lock with 429 code "locked" plus Retry-After: MfaController.SecondFactorLocked sends the
- * full lockout (900), and VerifyTotp sends what is LEFT of the lock. The portal used to hard-code "locked for 15
- * minutes" in three places (verify-code-copy.ts, twofa-rejection.ts, and the next-mvp BFF), which was true only
- * while every lock was exactly 15 minutes and the user had just tripped it.
- *
- * The window arrives in one of two ways:
- *   - Door A (verify-code): next-mvp >= 4.5.2 relays it in the BFF body as `retryAfterSeconds` (a number).
- *   - Door B (admin-login): this route reads the IdP's Retry-After header itself.
- * With no window, the sentence states NO number rather than a guessed one.
- *
- * Dependency-free on purpose: the verify-code page (client) and the admin-login route (server) both use it, and
- * the chain gate executes it directly.
- */
-
-/** A positive whole number of seconds from the BFF body, or undefined. Anything else - a string, 0, NaN - is dropped. */
-export function lockSecondsFromBody(value: unknown): number | undefined {
-  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.ceil(value) : undefined;
-}
-
-/** A Retry-After header as whole seconds. ONE implementation: the package's lib/retry-after (the portal copy was the same rule). */
-export { parseRetryAfterSeconds } from './retry-after';
-
-/**
- * The window in words, rounded UP so the user is never told a shorter wait than the IdP enforces:
- * 900 -> "15 minutes", 61 -> "2 minutes", 60 -> "1 minute", 45 -> "45 seconds", 7200 -> "2 hours".
- */
-export function formatLockWindow(seconds: number | undefined): string | undefined {
-  if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds <= 0) return undefined;
-  const plural = (n: number, unit: string) => `${n} ${unit}${n === 1 ? '' : 's'}`;
-  if (seconds < 60) return plural(Math.ceil(seconds), 'second');
-  const minutes = Math.ceil(seconds / 60);
-  if (minutes < 120) return plural(minutes, 'minute');
-  return plural(Math.ceil(minutes / 60), 'hour');
-}
-
-/** The sentence for a lock whose window was NOT sent. It says even a correct code is refused, and states no number. */
-export const LOCKED_NO_WINDOW =
-  'Too many incorrect codes. Verification is locked for now - even a correct code is refused until the lock ends. Wait before entering another code.';
-
-/** The locked sentence: the IdP's real window when it sent one, otherwise LOCKED_NO_WINDOW. */
-export function lockedSentence(seconds?: number): string {
-  const window = formatLockWindow(seconds);
-  return window
-    ? `Too many incorrect codes. Verification is locked for ${window} - wait before entering another code.`
-    : LOCKED_NO_WINDOW;
-}
+/**
+ * PAY-1608: a 2FA lock's window, stated as the IdP enforces it. Never a hard-coded "15 minutes".
+ *
+ * Core answers every 2FA lock with 429 code "locked" plus Retry-After: MfaController.SecondFactorLocked sends the
+ * full lockout (900), and VerifyTotp sends what is LEFT of the lock. The portal used to hard-code "locked for 15
+ * minutes" in three places (verify-code-copy.ts, twofa-rejection.ts, and the next-mvp BFF), which was true only
+ * while every lock was exactly 15 minutes and the user had just tripped it.
+ *
+ * The window arrives in one of two ways:
+ *   - Door A (verify-code): next-mvp >= 4.5.2 relays it in the BFF body as `retryAfterSeconds` (a number).
+ *   - Door B (admin-login): this route reads the IdP's Retry-After header itself.
+ * With no window, the sentence states NO number rather than a guessed one.
+ *
+ * Dependency-free on purpose: the verify-code page (client) and the admin-login route (server) both use it, and
+ * the chain gate executes it directly.
+ */
+
+/** A positive whole number of seconds from the BFF body, or undefined. Anything else - a string, 0, NaN - is dropped. */
+export function lockSecondsFromBody(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.ceil(value) : undefined;
+}
+
+/** A Retry-After header as whole seconds. ONE implementation: the package's lib/retry-after (the portal copy was the same rule). */
+export { parseRetryAfterSeconds } from './retry-after';
+
+/**
+ * The window in words, rounded UP so the user is never told a shorter wait than the IdP enforces:
+ * 900 -> "15 minutes", 61 -> "2 minutes", 60 -> "1 minute", 45 -> "45 seconds", 7200 -> "2 hours".
+ */
+export function formatLockWindow(seconds: number | undefined): string | undefined {
+  if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds <= 0) return undefined;
+  const plural = (n: number, unit: string) => `${n} ${unit}${n === 1 ? '' : 's'}`;
+  if (seconds < 60) return plural(Math.ceil(seconds), 'second');
+  const minutes = Math.ceil(seconds / 60);
+  if (minutes < 120) return plural(minutes, 'minute');
+  return plural(Math.ceil(minutes / 60), 'hour');
+}
+
+/** The sentence for a lock whose window was NOT sent. It says even a correct code is refused, and states no number. */
+export const LOCKED_NO_WINDOW =
+  'Too many incorrect codes. Verification is locked for now - even a correct code is refused until the lock ends. Wait before entering another code.';
+
+/** The locked sentence: the IdP's real window when it sent one, otherwise LOCKED_NO_WINDOW. */
+export function lockedSentence(seconds?: number): string {
+  const window = formatLockWindow(seconds);
+  return window
+    ? `Too many incorrect codes. Verification is locked for ${window} - wait before entering another code.`
+    : LOCKED_NO_WINDOW;
+}

package/src/lib/login-error-message.ts

@@ -1,41 +1,41 @@
-/**
- * PAY-2319 (4.7.2): what the login page SAYS for an `?error=` / `?oauth_error=` code, as pure functions so a test can
- * execute them (the page is a client component and effects do not run in a static render).
- *
- * 4.7.1 mapped these codes in an effect that called setLoginError, but the page never RENDERED loginError (it only fed the
- * loading gate), so no sentence was ever shown (NightHawk's walk, 73801, W1). Now that the text is displayed, a raw code from
- * the URL must NOT be echoed: `/account-auth/login?error=<anything an attacker types>` would otherwise print attacker-chosen
- * text on the login page (content spoofing / phishing). Known codes get their sentence; anything else gets one generic
- * sentence; nothing from the URL is ever shown verbatim.
- */
-
-export const GENERIC_LOGIN_ERROR = 'We could not sign you in. Please try again.';
-
-const KNOWN: Record<string, string> = {
-  TwoFactorTimeout: 'Your verification step timed out before the code was confirmed. Please sign in again.',
-  AUTHORIZE_RESUME_REFUSED: 'That sign-in request could not be continued. Please sign in again.',
-  ServiceUnavailable: 'Authentication service is temporarily unavailable. Please try again in a few minutes.',
-  CredentialsSignin: 'Invalid email or password. Please try again.',
-};
-
-/**
- * The sentence for `?error=<code>`, or null when nothing should be shown.
- * SessionExpired is a normal event (not an error) and shows nothing; an absent/empty code shows nothing.
- */
-export function friendlyLoginError(code: string | null | undefined): string | null {
-  if (typeof code !== 'string' || code === '') return null;
-  if (code === 'SessionExpired') return null;
-  if (Object.prototype.hasOwnProperty.call(KNOWN, code)) return KNOWN[code];
-  // The old raw-JSON parse failures the middleware/proxy could bounce here:
-  if (code.startsWith('Unexpected token') || code.includes('not valid JSON')) {
-    return 'An authentication error occurred. Please try signing in again.';
-  }
-  return GENERIC_LOGIN_ERROR;
-}
-
-/** `?oauth_error=<provider>`: only a plain provider-like slug is echoed (capitalised); anything else is the generic sentence. */
-export function oauthFailureMessage(provider: string | null | undefined): string | null {
-  if (typeof provider !== 'string' || provider === '') return null;
-  if (!/^[a-z][a-z0-9_-]{0,31}$/i.test(provider)) return GENERIC_LOGIN_ERROR;
-  return `${provider.charAt(0).toUpperCase()}${provider.slice(1)} sign-in did not complete. Please try again.`;
-}
+/**
+ * PAY-2319 (4.7.2): what the login page SAYS for an `?error=` / `?oauth_error=` code, as pure functions so a test can
+ * execute them (the page is a client component and effects do not run in a static render).
+ *
+ * 4.7.1 mapped these codes in an effect that called setLoginError, but the page never RENDERED loginError (it only fed the
+ * loading gate), so no sentence was ever shown (NightHawk's walk, 73801, W1). Now that the text is displayed, a raw code from
+ * the URL must NOT be echoed: `/account-auth/login?error=<anything an attacker types>` would otherwise print attacker-chosen
+ * text on the login page (content spoofing / phishing). Known codes get their sentence; anything else gets one generic
+ * sentence; nothing from the URL is ever shown verbatim.
+ */
+
+export const GENERIC_LOGIN_ERROR = 'We could not sign you in. Please try again.';
+
+const KNOWN: Record<string, string> = {
+  TwoFactorTimeout: 'Your verification step timed out before the code was confirmed. Please sign in again.',
+  AUTHORIZE_RESUME_REFUSED: 'That sign-in request could not be continued. Please sign in again.',
+  ServiceUnavailable: 'Authentication service is temporarily unavailable. Please try again in a few minutes.',
+  CredentialsSignin: 'Invalid email or password. Please try again.',
+};
+
+/**
+ * The sentence for `?error=<code>`, or null when nothing should be shown.
+ * SessionExpired is a normal event (not an error) and shows nothing; an absent/empty code shows nothing.
+ */
+export function friendlyLoginError(code: string | null | undefined): string | null {
+  if (typeof code !== 'string' || code === '') return null;
+  if (code === 'SessionExpired') return null;
+  if (Object.prototype.hasOwnProperty.call(KNOWN, code)) return KNOWN[code];
+  // The old raw-JSON parse failures the middleware/proxy could bounce here:
+  if (code.startsWith('Unexpected token') || code.includes('not valid JSON')) {
+    return 'An authentication error occurred. Please try signing in again.';
+  }
+  return GENERIC_LOGIN_ERROR;
+}
+
+/** `?oauth_error=<provider>`: only a plain provider-like slug is echoed (capitalised); anything else is the generic sentence. */
+export function oauthFailureMessage(provider: string | null | undefined): string | null {
+  if (typeof provider !== 'string' || provider === '') return null;
+  if (!/^[a-z][a-z0-9_-]{0,31}$/i.test(provider)) return GENERIC_LOGIN_ERROR;
+  return `${provider.charAt(0).toUpperCase()}${provider.slice(1)} sign-in did not complete. Please try again.`;
+}

package/src/lib/never-in-response.ts

@@ -1,64 +1,64 @@
-/**
- * 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 const MIN_SECRET_LENGTH = 16;
-
-const registered = new Set<string>();
-
-/** Record a value that must never appear in a response body. Non-strings and short strings are ignored. */
-export function markNeverInResponse(value: unknown): void {
-    if (typeof value !== 'string' || value.length < 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);
-}
-
-export class SecretInResponseError extends Error {
-    constructor(where: string) {
-        // 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';
-    }
-}
-
-/** Throws SecretInResponseError if any registered secret appears in `body` once serialized. */
-export function assertNoServerSecret(body: unknown, where: string): void {
-    if (registered.size === 0 || body === undefined || body === null) return;
-    let text: string;
-    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. */
-export function secretSafeJson<T>(body: T, init: ResponseInit | undefined, where: string): NextResponse<T> {
-    assertNoServerSecret(body, where);
-    return NextResponse.json(body, init);
-}
+/**
+ * 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 const MIN_SECRET_LENGTH = 16;
+
+const registered = new Set<string>();
+
+/** Record a value that must never appear in a response body. Non-strings and short strings are ignored. */
+export function markNeverInResponse(value: unknown): void {
+    if (typeof value !== 'string' || value.length < 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);
+}
+
+export class SecretInResponseError extends Error {
+    constructor(where: string) {
+        // 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';
+    }
+}
+
+/** Throws SecretInResponseError if any registered secret appears in `body` once serialized. */
+export function assertNoServerSecret(body: unknown, where: string): void {
+    if (registered.size === 0 || body === undefined || body === null) return;
+    let text: string;
+    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. */
+export function secretSafeJson<T>(body: T, init: ResponseInit | undefined, where: string): NextResponse<T> {
+    assertNoServerSecret(body, where);
+    return NextResponse.json(body, init);
+}