@payez/next-mvp 4.13.1 → 4.14.0

package/src/lib/first-enrol.ts

@@ -0,0 +1,180 @@
+/**
+ * AUTH-045 first-enrolment carry (PAY-2938, BAPert 100969): the server logic of the two enrolment calls a generated app makes for a user the IdP told
+ * to ENROL a factor on this client. Ported from VibeID-Customer-Portal PAY-2798 part 2 (src/lib/auth/enrol-core.ts + enrol-required.ts at a9ab685c);
+ * the pattern is not redesigned.
+ *
+ * WHY IT EXISTS. The credential door (api-handlers/auth/credential-login) answers an enrolment-scoped token (access, NO refresh) with the enrolment
+ * answer and mints NO session, so the package's session-gated MFA routes cannot serve this user. The door parks that token in an httpOnly cookie
+ * (ENROL_COOKIE); the two routes built on this module read ONLY that cookie, and ONLY for these two operations. No other route reads it.
+ *
+ * Rules held here (each has a row in test/first-enrol-core.test.cjs): the scoped token and the full pair a confirm answers NEVER appear in a returned
+ * body; the IdP's prose is never relayed; nothing is logged; the confirm body is a whitelist; the recovery codes are fetched with the confirm's full
+ * pair SERVER-SIDE ONLY and that pair is then dropped (this module mints no session: what follows is the sign-in the person already knows).
+ *
+ * No framework imports: a test runs it with a stubbed fetch.
+ */
+
+export const ENROL_COOKIE = 'payez_enrol';
+export const ENROL_COOKIE_MAX_AGE = 600;
+export type EnrolStep = 'enroll' | 'confirm';
+export const ENROL_STEPS: readonly EnrolStep[] = ['enroll', 'confirm'];
+
+export type Fetcher = (url: string, init: RequestInit & { headers: Record<string, string> }) => Promise<Response>;
+export type CoreDeps = { fetchImpl: Fetcher; idp: string; clientKey: string };
+/** `cookie`: what the route does with the enrolment cookie. */
+export type CoreResult = { status: number; body: Record<string, unknown>; cookie: 'clear' | 'keep' };
+
+const SENTENCE_UNAVAILABLE = 'We could not reach the sign-in service. Nothing was changed. Try again in a moment.';
+
+export function enrolIdpPath(step: EnrolStep): string {
+  return step === 'enroll' ? '/api/Account/mfa/totp/enroll' : '/api/Account/mfa/totp/confirm';
+}
+
+/** The body each step may carry: enroll { friendly_name? }, confirm { enrollment_id, code }. null = nothing is sent. */
+export function enrolBodyFor(step: EnrolStep, raw: unknown): Record<string, unknown> | null {
+  const src = raw && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, unknown>) : {};
+  if (step === 'enroll') {
+    const n = src.friendly_name;
+    return typeof n === 'string' && n.trim() !== '' && n.length <= 64 ? { friendly_name: n.trim() } : {};
+  }
+  const id = src.enrollment_id;
+  const code = src.code;
+  if (typeof id !== 'number' || !Number.isInteger(id) || id <= 0) return null;
+  if (typeof code !== 'string' || !/^\d{6}$/.test(code)) return null;
+  return { enrollment_id: id, code };
+}
+
+const unwrap = (b: unknown): Record<string, unknown> | null => {
+  if (!b || typeof b !== 'object' || Array.isArray(b)) return null;
+  const o = b as Record<string, unknown>;
+  return o.data && typeof o.data === 'object' && !Array.isArray(o.data) ? (o.data as Record<string, unknown>) : o;
+};
+const str = (v: unknown) => (typeof v === 'string' && v !== '' ? v : null);
+
+export function parseEnrol(body: unknown): { secret: string; otpauthUri: string; enrollmentId: number } | null {
+  const d = unwrap(body);
+  const secret = str(d?.secret);
+  const uri = str(d?.otpauth_uri);
+  const id = d?.enrollment_id;
+  if (!d || !secret || !uri || !uri.startsWith('otpauth://totp/') || typeof id !== 'number' || !Number.isInteger(id)) return null;
+  return { secret, otpauthUri: uri, enrollmentId: id };
+}
+
+export function parseConfirmed(body: unknown): boolean {
+  return unwrap(body)?.confirmed === true;
+}
+
+export function parseCodes(body: unknown): string[] | null {
+  const d = unwrap(body);
+  const codes = d?.codes;
+  if (!Array.isArray(codes) || codes.length === 0 || !codes.every((c) => typeof c === 'string' && c !== '')) return null;
+  return codes as string[];
+}
+
+export function codesForDisplay(codes: readonly string[]): string[] {
+  return codes.map((c) => c.trim()).filter((c) => c !== '');
+}
+
+/** What a person reads for a failed enrol / confirm call (never the server's text). 'sign-in' = 401/403: the page goes to sign-in, never a message box. */
+export function enrolRefusal(step: EnrolStep, status: number, body: unknown): { status: number; code: string; text: string } | 'sign-in' {
+  if (status === 401 || status === 403) return 'sign-in';
+  const c = (() => {
+    const b = body as { code?: unknown; error?: { code?: unknown } | string } | null;
+    if (b && typeof b.code === 'string') return b.code;
+    if (b && typeof b.error === 'object' && b.error && typeof (b.error as { code?: unknown }).code === 'string') return (b.error as { code: string }).code;
+    return null;
+  })();
+  if (status === 429) return { status: 429, code: 'TOO_MANY', text: 'Too many attempts. Wait a few minutes and try again.' };
+  if (step === 'confirm' && status >= 400 && status < 500) {
+    if (c === 'enrollment_not_found') return { status: 400, code: 'ENROLMENT_RESTART', text: 'This setup timed out. Reload the page to get a new code to scan.' };
+    return { status: 400, code: 'CODE_INVALID', text: 'That code did not work. Check the 6 digits in your authenticator app and try again.' };
+  }
+  return { status: 502, code: 'UNAVAILABLE', text: SENTENCE_UNAVAILABLE };
+}
+
+const headers = (token: string, clientKey: string): Record<string, string> => ({
+  'Content-Type': 'application/json',
+  Accept: 'application/json',
+  Authorization: `Bearer ${token}`,
+  'X-Client-Id': clientKey,
+});
+const asJson = async (res: Response) => res.json().catch(() => null);
+
+export async function runEnrolStep(deps: CoreDeps, input: { step: EnrolStep; token: string; body: unknown }): Promise<CoreResult> {
+  const body = enrolBodyFor(input.step, input.body);
+  if (body === null) return { status: 400, body: { success: false, code: 'INVALID_REQUEST' }, cookie: 'keep' };
+
+  let res: Response;
+  try {
+    res = await deps.fetchImpl(`${deps.idp}${enrolIdpPath(input.step)}`, {
+      method: 'POST',
+      headers: headers(input.token, deps.clientKey),
+      body: JSON.stringify(body),
+      cache: 'no-store',
+    });
+  } catch {
+    return { status: 502, body: { success: false, code: 'UNAVAILABLE', error: SENTENCE_UNAVAILABLE }, cookie: 'keep' };
+  }
+  const answer = await asJson(res);
+
+  if (res.status < 200 || res.status >= 300) {
+    const refusal = enrolRefusal(input.step, res.status, answer);
+    if (refusal === 'sign-in') return { status: 401, body: { success: false, code: 'SIGN_IN_AGAIN' }, cookie: 'clear' };
+    // A mistyped code must not cost a whole sign-in (the attempt limit bounds it); every other refusal ends this enrolment.
+    return { status: refusal.status, body: { success: false, code: refusal.code, error: refusal.text }, cookie: refusal.code === 'CODE_INVALID' ? 'keep' : 'clear' };
+  }
+
+  if (input.step === 'enroll') {
+    const e = parseEnrol(answer);
+    if (!e) return { status: 502, body: { success: false, code: 'UNAVAILABLE', error: 'We could not read the setup details. Nothing was changed. Reload the page.' }, cookie: 'clear' };
+    return { status: 200, body: { success: true, data: { secret: e.secret, otpauth_uri: e.otpauthUri, enrollment_id: e.enrollmentId } }, cookie: 'keep' };
+  }
+
+  // confirm: the factor is confirmed; the answer carries the FULL pair, used here ONLY to fetch the recovery codes, then dropped.
+  if (!parseConfirmed(answer)) return { status: 502, body: { success: false, code: 'UNAVAILABLE', error: 'We could not confirm that. Try the code again.' }, cookie: 'keep' };
+  const d = unwrap(answer);
+  const full = str(d?.access_token);
+  let codes: string[] | null = null;
+  if (full) {
+    try {
+      const c = await deps.fetchImpl(`${deps.idp}/api/Account/mfa/backup-codes`, { method: 'POST', headers: headers(full, deps.clientKey), body: '{}', cache: 'no-store' });
+      const list = c.ok ? parseCodes(await asJson(c)) : null;
+      codes = list ? codesForDisplay(list) : null;
+    } catch {
+      codes = null;
+    }
+  }
+  return { status: 200, body: { success: true, confirmed: true, codes }, cookie: 'clear' };
+}
+
+// ── attempt limit: per enrolment cookie (in-memory, per instance), hard-capped ──
+const WINDOW_MS = ENROL_COOKIE_MAX_AGE * 1000;
+export const LIMIT_PER_COOKIE = 5;
+const hits = new Map<string, number[]>();
+/**
+ * HARD CAP (portal PAY-2913, BAPert 90048): the map never holds more than this many keys; past it the OLDEST-TOUCHED key is evicted.
+ * KNOWN TRADE: a flood of forged cookies can push a real caller's counter out and reset its budget; bounded by this cap and by the IdP's own throttle.
+ * Not ported from the portal: the per-IP limit (it needs the trusted-proxy setting, PORTAL_TRUSTED_PROXY_HOPS, which a generated app does not have).
+ */
+export const MAX_TRACKED_KEYS = 5000;
+
+/** True when this key may attempt now; records the attempt. Keys are never the raw cookie (the route passes a digest). */
+export function attemptAllowed(key: string, limit: number, now: number = Date.now()): boolean {
+  const recent = (hits.get(key) ?? []).filter((t) => now - t < WINDOW_MS);
+  const allowed = recent.length < limit;
+  if (allowed) recent.push(now);
+  hits.delete(key); // re-insert at the end: Map order is last-touched order
+  hits.set(key, recent);
+  while (hits.size > MAX_TRACKED_KEYS) {
+    const oldest = hits.keys().next().value;
+    if (oldest === undefined) break;
+    hits.delete(oldest);
+  }
+  return allowed;
+}
+export function _resetAttempts(): void {
+  hits.clear();
+}
+export function _trackedKeys(): number {
+  return hits.size;
+}

package/src/pages/first-enroll/page.tsx

@@ -0,0 +1,19 @@
+'use client';
+
+import React from 'react';
+import { FirstEnrolPanel } from '../../components/mfa/FirstEnrolPanel';
+
+/**
+ * AUTH-045 (PAY-2938): /account-auth/first-enroll in a generated app, the page a person is sent to when the IdP says they must enrol an authenticator
+ * on this app and they have NO session yet. The page SHELL is public (every /account-auth/* path is public by default); the two routes behind it read
+ * ONLY the httpOnly enrolment cookie the credential door parked, and answer 401 without it (the panel then sends the person to sign-in).
+ * Not the signed-in enrolment page (/account-auth/enroll), which needs a session.
+ */
+export default function FirstEnrollPage() {
+  return (
+    <main style={{ maxWidth: 480, margin: '48px auto', padding: '0 16px' }}>
+      <h1>Secure your account</h1>
+      <FirstEnrolPanel />
+    </main>
+  );
+}

package/src/routes/mfa/first-enrol-confirm.ts

@@ -0,0 +1,10 @@
+/**
+ * AUTH-045 first-enrolment: confirm the first authenticator code, clear the enrolment cookie, return the recovery codes. Mints no session.
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/first-enrol/confirm/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/first-enrol-confirm';
+ * ```
+ */
+export { POST_CONFIRM as POST } from '../../api-handlers/mfa/first-enrol';

package/src/routes/mfa/first-enrol-enroll.ts

@@ -0,0 +1,10 @@
+/**
+ * AUTH-045 first-enrolment: begin TOTP enrolment for a user the IdP told to enrol (uses ONLY the httpOnly enrolment cookie the credential door parked).
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/first-enrol/enroll/route.ts
+ * export { POST } from '@payez/next-mvp/routes/mfa/first-enrol-enroll';
+ * ```
+ */
+export { POST_ENROLL as POST } from '../../api-handlers/mfa/first-enrol';