@jwilleke/ngdpbase-types 5.41.0 → 5.42.0

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

@@ -12,7 +12,8 @@
  * multi-factor flow, the per-role check and the boot refusal follow under #1523.
  *
  * Built-in providers, each gated on its own config key and all registered
- * through the public {@link AuthManager.registerProvider} (#1050):
+ * through registerCoreProvider(), which shares the checks of the public
+ * {@link AuthManager.registerProvider} (#1050):
  *   - PasswordAuthProvider          (unless ngdpbase.auth.password.enabled is false)
  *   - MagicLinkAuthProvider         (ngdpbase.auth.magic-link.enabled)
  *   - OidcAuthProvider, one per entry (ngdpbase.auth.oidc.providers; the old
@@ -21,8 +22,9 @@
  *   - AuthentikBearerAuthProvider   (ngdpbase.auth.authentik-bearer.enabled)
  *   - AgentTokenAuthProvider        (ngdpbase.auth.agent-token.enabled)
  *
- * Addons register through the same method, so the contributed path is the one
- * exercised on every boot rather than a second, less-travelled one.
+ * Addons register through registerProvider(), so the contributed path is the one
+ * exercised on every boot rather than a second, less-travelled one. Core's ids
+ * and the `oidc:` prefix are reserved for core there (#2223).
  *
  * Future providers (see #421):
  *   - TotpAuthProvider
@@ -36,6 +38,7 @@ import type { PermissionSubject } from './UserManager.js';
 import type { JobContext } from '../context/JobContext.js';
 import type { Aal, AuthProvider, AuthInitiateContext, AuthVerifyCredentials, PhishingResistance, ReportedAssurance, ViaToken } from '../providers/BaseAuthProvider.js';
 import { type OutsideProviderIcon } from '../providers/OidcAuthProvider.js';
+import { type BrowserIdentity } from '../utils/browserDescription.js';
 import { type PasskeyRelyingParty } from '../providers/PasskeyAuthProvider.js';
 import { type CredentialKind, type CredentialRecord } from '../providers/BaseCredentialsProvider.js';
 import { type ActorContext } from '../context/ActorContext.js';
@@ -140,7 +143,44 @@ export interface PendingSignIn {
     denied?: boolean;
     /** When the last approval message went out, for the resend limit. */
     lastSentAt?: number;
+    /**
+     * #1523 slice 1c: the highest `required-aal` among the person's roles, not
+     * capped by what the account can reach: the bar a remembered browser's skip
+     * must clear.
+     */
+    rolesAal?: Aal;
+    /** #1523 slice 1c: "Remember this browser" was ticked, with the version of its page the person was shown. */
+    remember?: {
+        version: string;
+    };
+    /** #1523 slice 1c: the one-time challenge a remembered browser signs; taken by its first use. */
+    deviceChallenge?: string;
+    /** #1523 slice 1c: the remembered device that proved itself, so the prompt is skipped. Not a factor. */
+    knownDevice?: string;
+}
+/** #1523 slice 1c: a remembered browser's `device` row secret: its public key and what it was issued to. */
+export interface DeviceSecret extends BrowserIdentity {
+    /** The ECDSA P-256 public key, SPKI DER, base64url. Never a private key. */
+    publicKey: string;
+    /** The `amr` of the sign-in that remembered it. */
+    amr: string[];
+    /** RFC 3339: after this it no longer skips the prompt. */
+    expiresAt: string;
+    /**
+     * The account's password-change generation when it was remembered (#1482):
+     * a later password change retires it.
+     */
+    generation?: number;
+    /**
+     * The id of the audit record of the sign-in that remembered it (#1523,
+     * operator 2026-10-31), and how that sign-in was made, as the record says.
+     * A browser remembered before this has neither.
+     */
+    auditId?: string;
+    signInMethod?: string;
 }
+/** What a remembered browser signs: this, then the challenge. Separates the signature from any other use of the key. */
+export declare const KNOWN_DEVICE_SIGNED_PREFIX = "ngdpbase known device v1\n";
 /**
  * What an approval request says about a waiting sign-in (#1532): one source
  * for the message and the page.
@@ -297,6 +337,8 @@ export type OutsideSignIn =
 /** What the one completion step leaves for the route (#1743): where to go instead, when a pending identity waits to be confirmed. */
 export interface SignInCompleted {
     next?: string;
+    /** The id of the sign-in's audit record, when it was recorded (#1523: a remembered browser's row names it). */
+    auditId?: string;
 }
 /**
  * How a delegated credential is renewed (#1764): `fixed` ends on its date and
@@ -447,6 +489,8 @@ export interface ActingForChoices {
 export interface SignInRecord extends Assurance {
     provider: string;
     factors: SatisfiedFactor[];
+    /** #1523 slice 1c: the second-factor prompt was skipped on a remembered browser. It raises nothing. */
+    knownDevice?: true;
     /** When the sign-in completed, RFC 3339. */
     at: string;
 }
@@ -556,6 +600,11 @@ export interface AuthenticateResult {
     aal?: Aal;
     /** #1633: what an outside provider reported about its own sign-in, for the audit record. */
     reported?: ReportedValues;
+    /**
+     * #1523 slice 1c: the second-factor prompt was skipped because this browser
+     * is remembered. Not a factor: `factors` holds only what was entered.
+     */
+    knownDevice?: boolean;
 }
 declare class AuthManager extends BaseManager {
     private providers;
@@ -564,6 +613,12 @@ declare class AuthManager extends BaseManager {
     private factorCache;
     /** The credentials store (#1524); null when it could not be opened. */
     private credentials;
+    /**
+     * #421: TOTP, built for enrolment only. Not registered as a sign-in
+     * provider until the second-factor step can ask for it (slice 2b): offering
+     * it earlier would raise admins to AAL2 before they could use it.
+     */
+    private totp;
     /** `ngdpbase.auth.credentials.file`, resolved at start: what a backup copies (#1876). */
     private credentialsFile;
     constructor(engine: WikiEngine);
@@ -742,6 +797,32 @@ declare class AuthManager extends BaseManager {
      * the request — so a passkey made here works only on that hostname.
      */
     private registerPasskeys;
+    /** TOTP enrolment (#421), available whenever the credentials store is open. */
+    private openTotp;
+    /** Whether an authenticator app can be enrolled here (#421). */
+    totpAvailable(): boolean;
+    /**
+     * A new seed for `username` to add to an authenticator app (#421): the
+     * manual key, the `otpauth://` URI and that URI as an SVG QR code. Nothing
+     * is stored. `pending` is the seed sealed for this account: the caller keeps
+     * that, never the seed, (in the session) until a code confirms it. Refused
+     * while the account already has one.
+     */
+    totpEnrolmentStart(ctx: PermissionSubject, username: string): Promise<{
+        seed: string;
+        pending: string;
+        uri: string;
+        qrSvg: string;
+    }>;
+    /**
+     * Confirm an enrolment with a code from the app and store the seed,
+     * encrypted (#421). Returns the credential id, or null when the code does
+     * not match, or when `pending` is not a seed `totpEnrolmentStart` sealed
+     * for this account. The confirming code is spent: it cannot also sign
+     * anyone in.
+     */
+    totpEnrolmentConfirm(ctx: PermissionSubject, username: string, pending: string, code: string, label: string): Promise<string | null>;
+    private totpEnrolGate;
     private passkeyProvider;
     /** The host passkeys are tied to, or null when passkeys are off (#448). */
     passkeyRelyingParty(): PasskeyRelyingParty | null;
@@ -1096,7 +1177,10 @@ declare class AuthManager extends BaseManager {
      * - AAL1 otherwise.
      */
     outsideLevel(reported: ReportedValues | undefined): Pick<Factor, 'amr' | 'aal' | 'acr'>;
-    /** The audit record of one sign-in method's check (#1758): written here, never by a route. */
+    /**
+     * The audit record of one sign-in method's check (#1758): written here, never
+     * by a route. Returns the record's id when it was recorded (#1523).
+     */
     private auditCheck;
     /** Each role's `required-aal`, and whether the operator set it, read through the catalogue's owner (#1523, #448). */
     private requiredLevels;
@@ -1158,6 +1242,26 @@ declare class AuthManager extends BaseManager {
     };
     /** Every role whose configured level the available factors cannot reach, described (#1523). */
     unreachableRequiredAal(): string[];
+    /**
+     * The start-up check of the `ngdpbase.auth.factors` ids, once add-ons have
+     * registered their providers (#1523 Q1, operator 2026-10-31). An id no
+     * provider could ever register, such as a typo, refuses the boot when its
+     * entry is on, and only warns when it is `enabled: false`. Returns the
+     * problems that must refuse the boot.
+     */
+    checkFactorIds(): string[];
+    /**
+     * The same check for a value the configuration screen is about to save as
+     * `ngdpbase.auth.factors` (#1523), so a typo is refused there rather than
+     * at the next restart, which would refuse to start. `refused` names each
+     * enabled unknown id; `ignored` each one whose entry is `enabled: false`.
+     */
+    checkFactorEntries(value: unknown): {
+        refused: string[];
+        ignored: string[];
+    };
+    /** The entries whose id no provider could ever register, split by whether the entry is on. */
+    private unknownFactorIds;
     /**
      * The start-up check, once add-ons have registered their providers (#1523,
      * #448). Returns the problems that must refuse the boot: a level the operator
@@ -1335,9 +1439,9 @@ declare class AuthManager extends BaseManager {
     private warnedLegacyStepUp;
     /**
      * Whether `permission` needs a fresher factor than `signIn` holds (#1525).
-     * Fresh: a factor satisfied within the step-up window that reaches the
-     * level the person's roles require (at least 1 — a known device, aal 0,
-     * never counts). A delegated credential has no sign-in of its own, so it
+     * Fresh: the factors satisfied within the step-up window together reach
+     * the level the person's roles require (at least 1 — a known device, aal 0,
+     * never counts); a password and an authenticator code reach AAL2 (#421). A delegated credential has no sign-in of its own, so it
      * never satisfies step-up.
      */
     stepUpNeeded(permission: string, signIn: SignInRecord | undefined, roles: readonly string[], delegated: boolean, now?: number, cap?: number): boolean;
@@ -1463,9 +1567,9 @@ declare class AuthManager extends BaseManager {
     /**
      * 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.
+     * by `preference`. Only what the second step can run is offered — the
+     * email link and an authenticator app (#421) — 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, signIn?: Pick<PendingSignIn, 'first' | 'requiredAal'>): AvailableSecondFactor[];
     /**
@@ -1546,6 +1650,30 @@ declare class AuthManager extends BaseManager {
     private approvalContext;
     /** Approve the waiting sign-in from its link (the button press). Single use; returns the username, or null. */
     approveByToken(token: string, presser?: ApprovalVisitor): Promise<string | null>;
+    /**
+     * The authenticator app's code for the waiting sign-in (#421 slice 2b). Its
+     * check goes through `authenticate`, which records a wrong code as a failed
+     * sign-in; a right one approves the pending sign-in, which `completeTwoStep`
+     * then finishes with both factors. `unavailable` when the sign-in is gone,
+     * already decided, or the account has no authenticator app offered here.
+     * The caller throttles wrong codes as it does wrong passwords.
+     */
+    approveByTotp(handle: string, binding: string, code: string, from?: ApprovalVisitor): Promise<'approved' | 'wrong' | 'unavailable'>;
+    /**
+     * Whether step-up offers `username` the authenticator app's code (#421
+     * slice 2c): as at the second step, an app enrolled and its
+     * `ngdpbase.auth.factors` entry enabled.
+     */
+    stepUpTotpOffered(username: string): boolean;
+    /**
+     * Step-up with the authenticator app (#421 slice 2c). The code is checked
+     * through `authenticate`, as at the second step of sign-in, so a wrong one
+     * is recorded as a failed re-check. With `password` (a role that needs
+     * AAL2), the password is checked first, and the result carries both
+     * factors, which together reach AAL2. `unavailable` when the app is not
+     * offered here. The caller throttles wrong answers as it does wrong passwords.
+     */
+    reauthenticateByTotp(username: string, code: string, password: string | null, attempt?: AuthAttempt): Promise<AuthenticateResult | 'unavailable'>;
     /** Refuse the waiting sign-in from its link (Deny). Returns the username, or null. */
     denyByToken(token: string, presser?: ApprovalVisitor): Promise<string | null>;
     /**
@@ -1555,7 +1683,102 @@ declare class AuthManager extends BaseManager {
     completeTwoStep(handle: string, binding: string): {
         result: AuthenticateResult;
         privateStoreHandle?: string;
+        remember?: {
+            version: string;
+        };
     } | null;
+    /** How many days a remembered browser stays remembered: `ngdpbase.auth.known-device.remember-days`; 0 turns remembering off. */
+    rememberDays(): number;
+    /**
+     * Whether a remembered browser may skip this sign-in's second step: the
+     * factors entered already reach the highest `required-aal` among the
+     * person's roles (operator, 2026-11-01). A person whose roles need AAL2 is
+     * always asked.
+     */
+    knownDeviceMaySkip(p: Pick<PendingSignIn, 'first' | 'rolesAal'>): boolean;
+    /** Whether "Remember this browser" is offered at this second step: only where it could ever skip one. */
+    rememberOffered(p: Pick<PendingSignIn, 'first' | 'rolesAal'>): boolean;
+    /** "Remember this browser" was ticked at the second step, having been shown `version` of its page. */
+    noteRemember(handle: string, binding: string, version: string): void;
+    /**
+     * When a remembered browser stops skipping the prompt: its stored expiry,
+     * or its creation plus the current `remember-days`, whichever is sooner,
+     * so lowering the setting shortens browsers already remembered.
+     */
+    private deviceExpiry;
+    /**
+     * `username`'s remembered browsers that have not expired. With the
+     * account's password-change `generation`, also only those remembered
+     * since the last password change (#1482).
+     */
+    rememberedDevices(username: string, now?: number, generation?: number): Array<{
+        row: CredentialRecord;
+        device: DeviceSecret;
+    }>;
+    private accountGeneration;
+    /**
+     * Drop `username`'s remembered browsers that no longer count: expired,
+     * unreadable, or remembered before the last password change. Each is
+     * recorded as `credential-remove` and its consent withdrawn. Returns the
+     * ones that still count.
+     */
+    pruneRememberedDevices(username: string, now?: number): Promise<Array<{
+        row: CredentialRecord;
+        device: DeviceSecret;
+    }>>;
+    /** Withdraw the "remember this browser" consent bound to `deviceId`; a failure is logged, the browser stays removed. */
+    private withdrawRememberConsent;
+    /**
+     * A one-time challenge for a remembered browser to sign, or null when the
+     * skip cannot apply (the roles need more, or no browser is remembered).
+     * A new challenge replaces the last.
+     */
+    knownDeviceChallenge(handle: string, binding: string): string | null;
+    /**
+     * A remembered browser's answer to the challenge (#1523 slice 1c). It
+     * counts only when the device is this person's, has not expired, the
+     * signature over the challenge verifies with its public key, and the
+     * browser and system still match what it was issued to, and the audit
+     * record its row names says the same as the row (#1523, operator
+     * 2026-10-31). Any failure is recorded and the prompt stays. A row whose
+     * audit record is missing or disagrees is also a security event; a row
+     * remembered before rows named their record is removed, so the browser is
+     * asked once and may be remembered again. The challenge is spent either way.
+     */
+    proveKnownDevice(handle: string, binding: string, deviceId: string, signature: string, from: {
+        ip?: string;
+        userAgent?: string;
+        platformHint?: string;
+    }): Promise<boolean>;
+    /**
+     * How a remembered browser's row disagrees with the audit record it names
+     * (#1523), or null when they agree: the record is the account's sign-in,
+     * made the way the row says, with the same factors. `'no record named'` for
+     * a row remembered before rows named one.
+     */
+    private deviceRecordDisagreement;
+    /**
+     * Remember this browser for `ctx`'s person (#1523 slice 1c, Q5): the
+     * consent record first, bound to the device id, then the `device` row with
+     * the public key, the browser and system, and when it expires. Refused
+     * when the key is not an ECDSA P-256 public key, the browser cannot be
+     * told, the page changed since it was shown, or consent cannot be recorded.
+     * The row names the audit record of the sign-in (`auditId`, from
+     * `completeSignIn`), which must be readable and be this person's sign-in
+     * with these factors; otherwise nothing is remembered (#1523).
+     */
+    rememberBrowser(ctx: {
+        username: string;
+    } & Record<string, unknown>, input: {
+        publicKey: string;
+        version: string;
+        userAgent?: string;
+        platformHint?: string;
+        amr: string[];
+        auditId?: string;
+    }): Promise<{
+        deviceId: string;
+    } | null>;
     /**
      * The waiting browser gave up the sign-in (Cancel, #1532): dropped, its
      * keys locked, and recorded as `signinapproval-abandon`.
@@ -1636,9 +1859,11 @@ declare class AuthManager extends BaseManager {
     /**
      * Register an authentication provider (#1050).
      *
-     * The built-ins call this during `initialize()`, so the path an addon uses is
-     * the path exercised on every boot rather than a second, less-travelled one.
-     * Config gating stays with the caller: this method decides nothing about
+     * The built-ins register during `initialize()` through registerCoreProvider(),
+     * which shares every check below except the reserved ids, so the path an addon
+     * uses is the path exercised on every boot rather than a second, less-travelled
+     * one. Core ids and the `oidc:` prefix are reserved: an addon registering one is
+     * refused, whether or not core registered it on this site (#2223). Config gating stays with the caller: this method decides nothing about
      * whether a provider *should* be active, only that it is.
      *
      * ## Duplicate ids: first registration wins
@@ -1666,10 +1891,17 @@ declare class AuthManager extends BaseManager {
      * otherwise here would be worse than the gap.
      *
      * @param provider the provider to register
-     * @param source   attribution for logs — an addon name, or 'built-in'
-     * @returns true if registered; false if rejected as malformed or duplicate
+     * @param source   attribution for logs: the add-on's name
+     * @returns true if registered; false if rejected as reserved, malformed or duplicate
      */
     registerProvider(provider: AuthProvider, source?: string): boolean;
+    /**
+     * Core's own registrations (#2223): the one way a reserved id gets in. Called
+     * only from initialize() and the helpers it runs; add-ons get the AuthManager
+     * through the engine and call registerProvider(), which refuses these ids.
+     */
+    private registerCoreProvider;
+    private addProvider;
     /**
      * Begin a redirect-based flow; returns the URL to send the browser to (#1049).
      *