@jwilleke/ngdpbase-types 5.39.0 → 5.41.0

package/lib/src/managers/AuthManager.d.ts

@@ -50,6 +50,12 @@ export interface FactorEntry {
     aal?: Aal;
     acr?: PhishingResistance;
     enabled?: boolean;
+    /**
+     * Where it comes among the second factors offered, lower first; none comes
+     * last (#1523, operator 2026-10-11). A number, because the configuration
+     * merge does not keep a custom entry's place in the list.
+     */
+    preference?: number;
 }
 export interface Factor {
     provider: string;
@@ -126,6 +132,8 @@ export interface PendingSignIn {
     requestLocation?: string | null;
     /** Private-store keys unlocked by the password, held until the sign-in completes or is dropped. */
     privateStoreHandle?: string;
+    /** The level this account's roles require (`requiredAalFor`), so the second factors that reach it are offered first (#1523 Q2). */
+    requiredAal?: Aal;
     /** The second factor, once satisfied. */
     approved?: SatisfiedFactor;
     /** Refused by the person (Deny). */
@@ -172,7 +180,8 @@ export interface ApprovalVisitor {
 }
 /** A second factor a person has enrolled and can use now. */
 export interface AvailableSecondFactor {
-    id: 'email-link';
+    /** The second step's method: `email-link` for the email link (its entry is `magic-link`), else the provider id. */
+    id: string;
     label: string;
     /** Where it goes, masked for display (j***@example.com). */
     target: string;
@@ -441,8 +450,59 @@ export interface SignInRecord extends Assurance {
     /** When the sign-in completed, RFC 3339. */
     at: string;
 }
-/** How a refused request wants its answer: a page to redirect, JSON, or plain text (#1745). */
-export type ReauthMode = 'json' | 'page' | 'text';
+/**
+ * How a refused request wants its answer: a page to redirect, JSON, or plain
+ * text (#1745). `download` is a GET that answers with a file: refused like a
+ * page, but returned to the page that linked it, since going back to the file
+ * itself saves it and leaves the browser on the prompt (#2145).
+ */
+export type ReauthMode = 'json' | 'page' | 'text' | 'download';
+/** Whether a refusal in `mode` is answered by sending the browser to a page: a page, or a file a page links to (#2145). */
+export declare function answeredWithPage(mode: ReauthMode): boolean;
+/**
+ * A step-up asked for and not yet given, kept on the session (#2145): which
+ * permission it was for, where the prompt returns, and whether going there
+ * does the action again (a page GET, or a form POST kept to be redone, #2154)
+ * or only brings the person back to it.
+ */
+export interface PendingStepUp {
+    permission: string;
+    next: string;
+    replays: boolean;
+    /** The kept form POST the confirmation releases (#2154). */
+    replay?: string;
+}
+/**
+ * Where a script's own prompt is (#2193): a page that sent a request by
+ * `fetch` and was refused waits on the prompt its refusal named, and sends
+ * again only when that prompt, not another tab's, is confirmed.
+ */
+export type StepUpPromptState = 'waiting' | 'confirmed' | 'cancelled';
+/** A script's prompt as the session keeps it (#2193): its id and where it is. */
+export interface StepUpPrompt {
+    id: string;
+    state: StepUpPromptState;
+}
+/** A prompt id as minted (#2193), or null for anything else. */
+export declare function stepUpPromptId(value: unknown): string | null;
+/** Where a fresh sign-in sends the browser to redo a form POST (#2154). */
+export declare const STEP_UP_CONTINUE_PATH = "/auth/reauth/continue";
+/** What the continue page does (#2154): post `fields` to `action` (`back` is the page it came from), or go `back` with nothing redone. */
+export type StepUpReplayAnswer = {
+    action: string;
+    fields: Array<[string, string]>;
+    back: string;
+} | {
+    back: string;
+};
+/**
+ * A form POST's fields as they can be posted again to give the same body
+ * (#2154), or null when they cannot: a file upload, a nested field, a name
+ * with brackets. A list goes back as `name[]`, which parses to a list even
+ * of one. `_csrf` is left out: the replay carries the session's token. A
+ * secret (`SECRET_FIELD`) is never kept, so such a form is null too.
+ */
+export declare function replayableFields(req: Request): Array<[string, string]> | null;
 /** The step-up answer (#1525, #1635), for the caller to send in its own form. */
 export interface FreshSignInAnswer {
     /** The refused permission. */
@@ -457,8 +517,8 @@ export interface FreshSignInAnswer {
 /**
  * Where to return after re-authenticating: this page for a page GET, and the
  * page the person was on for anything else — a POST (the form is filled in
- * again; a POST body is not replayed) or a script's request for data (#1738).
- * Always a path on this site.
+ * again; a POST body is not replayed), a script's request for data (#1738) or
+ * a file download (#2145). Always a path on this site.
  */
 export declare function reauthReturnTo(req: Request, mode?: ReauthMode): string;
 /**
@@ -513,6 +573,12 @@ declare class AuthManager extends BaseManager {
      * converted to entries when a site still sets only that (#1523).
      */
     private readFactorEntries;
+    /**
+     * #1523: with the `magic-link` entry off or not listed, an enrolled email
+     * second factor is no longer asked for. The operator may mean that, but it
+     * must not happen silently.
+     */
+    private warnIfEmailSecondFactorsDropped;
     /**
      * The outside OpenID Connect providers (#1743): one `OidcAuthProvider` per
      * enabled entry of `ngdpbase.auth.oidc.providers`, plus the old
@@ -1112,14 +1178,63 @@ declare class AuthManager extends BaseManager {
      * refused outright: it can never give a fresh factor.
      */
     askForFreshSignIn(req: Request, userContext: unknown, permission: string, mode: ReauthMode): Promise<FreshSignInAnswer>;
+    /**
+     * Where this session's prompt `id` is (#2193): waiting, confirmed or
+     * cancelled, or unknown (another session's, dropped, or not an id). Reads
+     * only, so asking it often changes nothing in the session.
+     */
+    stepUpPromptState(req: Request, id: unknown): StepUpPromptState | 'unknown';
+    /** The prompt's Cancel (#2193): a waiting prompt of this session is cancelled, so its page stops waiting. */
+    cancelStepUpPrompt(req: Request, id: unknown): void;
     /** Record a step-up event: a prompt, a success or a failure (#1525). */
     recordReauth(req: Request, eventType: AuditEventName, result: 'success' | 'failure', permission: string, detail: string): Promise<void>;
     /**
      * A re-authentication completes (#1525, #1758): the session's sign-in record
      * gains the fresh factor, and the success is recorded. The route saves the
-     * session and answers.
-     */
-    completeReauth(req: Request, result: AuthenticateResult, method: string): Promise<SignInRecord | null>;
+     * session and answers, sending the browser to `next`.
+     *
+     * #2145: when `next` is where the pending prompt returns, the success is
+     * recorded against the permission it was for (otherwise, a prompt opened
+     * directly, against the method), and when going there does not redo the
+     * action (a form POST, a script's request, a download) the page there says
+     * it can be done now (`takeStepUpNotice`).
+     *
+     * #2193: `prompt`, the id a script's refusal named, is confirmed when it is
+     * this session's and still waiting; no other prompt is.
+     */
+    completeReauth(req: Request, result: AuthenticateResult, method: string, next: string, prompt?: unknown): Promise<SignInRecord | null>;
+    /**
+     * Whether this request's page says "Confirmed — you can do it now" (#2145):
+     * the first page the browser opens after a re-authentication that could not
+     * redo the action, when it is the page the prompt returned to. Any page
+     * opened clears it, so it is said once.
+     */
+    takeStepUpNotice(req: Request): boolean;
+    /** #2154: form POSTs kept for their fresh sign-in, by a random id. In memory: a restart drops them. */
+    private stepUpReplays;
+    /**
+     * Keep a form POST answered with the prompt, to be redone after it
+     * (#2154); its id, or null when it cannot be redone exactly. Only a page's
+     * POST by a signed-in person, to an address on this site. Each prompt keeps
+     * its own, so the same button pressed in two tabs loses neither (#2176); a
+     * session keeps at most `STEP_UP_REPLAYS_PER_SESSION`, an account
+     * `STEP_UP_REPLAYS_PER_ACCOUNT` and the site `STEP_UP_REPLAYS_TOTAL`, a new
+     * prompt dropping the oldest past that, unconfirmed first, and any past its
+     * time. It waits `STEP_UP_REPLAY_WAIT_MS` for the confirmation, which
+     * restarts its clock. A session's end drops its own (`dropStepUpReplays`).
+     */
+    private keepStepUpReplay;
+    /** A session ended (#2176): the form POSTs it kept go with it (`endSession`). */
+    dropStepUpReplays(sessionId: string): void;
+    /**
+     * Take the kept form POST `id` for the continue page (#2154). Single-use:
+     * taken, it is gone, whatever the answer. Another session's or person's is
+     * refused (null); one not confirmed (the prompt's Cancel) or past its time
+     * only goes back, a confirmed one with the note (#2145). Otherwise the page
+     * posts the fields to the same address. A refusal or one past its time is
+     * recorded as a `reauth-failure`; any other past its time is dropped.
+     */
+    takeStepUpReplay(req: Request, id: unknown): Promise<StepUpReplayAnswer | null>;
     /**
      * The one sign-in completion step (#1758): every way a person finishes
      * signing in — a password, a passkey, a second factor, an email link, an
@@ -1226,6 +1341,14 @@ declare class AuthManager extends BaseManager {
      * never satisfies step-up.
      */
     stepUpNeeded(permission: string, signIn: SignInRecord | undefined, roles: readonly string[], delegated: boolean, now?: number, cap?: number): boolean;
+    /**
+     * Whether `signIn` is fresh enough for every step-up permission (#2193): the
+     * window and the level are one for all of them, so a page waiting on its
+     * prompt asks this without naming the permission. With step-up off, every
+     * sign-in is.
+     */
+    signInFresh(signIn: SignInRecord | undefined, roles: readonly string[], delegated: boolean, now?: number, cap?: number): boolean;
+    private freshUnder;
     /**
      * A session's sign-in after a re-authentication (#1525): the new factors
      * join the old, the assessment is redone over all of them, and the sign-in
@@ -1323,11 +1446,28 @@ declare class AuthManager extends BaseManager {
     /** Whether an email link can be a second factor on this site now (#1523): mail and an explicit base-url. */
     emailLinksAvailable(): boolean;
     /**
-     * The second factors `username` has enrolled and can use now (#1523). Any
-     * enrolled factor works; one that is not truly available (no mail transport)
-     * is not offered. Empty means the sign-in is one step, as before.
+     * Whether the email link can be a second factor now (#1523): its entry in
+     * `ngdpbase.auth.factors` (`magic-link`, or its alias `email-link`) listed
+     * and enabled, mail, and an explicit base-url.
+     */
+    emailSecondFactorAvailable(): boolean;
+    /**
+     * The second factors that may follow `first`, in the order they are offered
+     * (#1523; Q2, operator 2026-10-31): every enabled entry of
+     * `ngdpbase.auth.factors` other than the one the sign-in started with, whose
+     * level is known (its provider registered, or the email link). Those that,
+     * with the first step, reach `requiredAal` come first; then by `preference`,
+     * lower first, an entry with none last. Entry ids.
+     */
+    secondFactorOrder(first: Pick<AuthenticateResult, 'provider' | 'factors'>, requiredAal: number): string[];
+    /**
+     * The second factors `username` has enrolled and can use now (#1523), in
+     * `secondFactorOrder` after the pending sign-in's first step; without one,
+     * by `preference`. Only what the second step can run is offered — today the
+     * email link — and one that is not truly available (no mail transport) is
+     * not. Empty means the sign-in is one step, as before.
      */
-    secondFactorsFor(username: string): AvailableSecondFactor[];
+    secondFactorsFor(username: string, signIn?: Pick<PendingSignIn, 'first' | 'requiredAal'>): AvailableSecondFactor[];
     /**
      * Whether a successful first step needs a second (#1532, operator
      * 2026-10-22): everyone who arrives with only a password behind them — a