@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

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

@@ -0,0 +1,1257 @@
+/**
+ * AuthManager — pluggable authentication provider chain.
+ *
+ * Registers one or more AuthProviders and delegates authenticate/initiate
+ * calls to the appropriate provider. Routes call only AuthManager — never
+ * individual providers directly.
+ *
+ * `ngdpbase.auth.factors` lists the methods offered (#1523): one entry per
+ * provider, with the `amr` / `aal` / `acr` it gives — lowered to what the
+ * provider's own code declares, never raised. What a sign-in must reach is set
+ * per role (`required-aal`), not here. Signing in still uses one factor; the
+ * 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):
+ *   - PasswordAuthProvider          (unless ngdpbase.auth.password.enabled is false)
+ *   - MagicLinkAuthProvider         (ngdpbase.auth.magic-link.enabled)
+ *   - OidcAuthProvider, one per entry (ngdpbase.auth.oidc.providers; the old
+ *     ngdpbase.auth.google-oidc.* keys are read as the `google` entry, #1743)
+ *   - CloudflareAccessAuthProvider  (ngdpbase.auth.cloudflare-access.enabled)
+ *   - 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.
+ *
+ * Future providers (see #421):
+ *   - TotpAuthProvider
+ *
+ * @see {@link https://github.com/jwilleke/ngdpbase/issues/396}
+ */
+import BaseManager from './BaseManager.js';
+import type { BackupData } from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { PermissionSubject } from './UserManager.js';
+import type { JobContext } from '../context/JobContext.js';
+import type { Aal, AuthProvider, AuthInitiateContext, AuthVerifyCredentials, PhishingResistance, ViaToken } from '../providers/BaseAuthProvider.js';
+import { type OutsideProviderIcon } from '../providers/OidcAuthProvider.js';
+import { type PasskeyRelyingParty } from '../providers/PasskeyAuthProvider.js';
+import { type CredentialKind, type CredentialRecord } from '../providers/BaseCredentialsProvider.js';
+import { type AuditEventName } from '../utils/auditEventNames.js';
+import { type ScopeDescription } from '../utils/permissionCatalog.js';
+import type { Request } from 'express';
+/** One entry of `ngdpbase.auth.factors`, as written in configuration (#1523). */
+export interface FactorEntry {
+    authproviderid: string;
+    primary?: boolean;
+    amr?: string[];
+    aal?: Aal;
+    acr?: PhishingResistance;
+    enabled?: boolean;
+}
+export interface Factor {
+    provider: string;
+    primary: boolean;
+    amr: string[];
+    aal: Aal;
+    acr?: PhishingResistance;
+}
+/** A factor a sign-in satisfied, and when — what step-up asks about (#1525). */
+export interface SatisfiedFactor extends Omit<Factor, 'primary'> {
+    at: string;
+}
+/** NIST SP 800-63 factor type. */
+export type FactorType = 'know' | 'have' | 'are';
+/** What a set of satisfied factors amounts to (#1523). */
+export interface Assurance {
+    /** The combined RFC 8176 `amr` array. */
+    amr: string[];
+    aal: Aal;
+    /** What we claim, strongest first: `phrh`, `phr`, then the AAL. Never overstated. */
+    acr: PhishingResistance | 'aal1' | 'aal2' | 'aal3';
+    /** Two or more distinct factor types — what MFA means here, not two providers. */
+    mfa: boolean;
+}
+/**
+ * An outside provider's report, as kept (#1633): only well-formed values,
+ * bounded, and whether the admin trusts this provider's own second factor.
+ * Recorded in the sign-in's audit record whether or not it counts.
+ */
+export interface ReportedValues {
+    amr: string[];
+    acr?: string;
+    trusted: boolean;
+}
+/** A credential as shown to a person: never its secret (#1524). */
+export type CredentialView = Omit<CredentialRecord, 'secret'>;
+/** What enrolling a credential supplies; id and times are the store's. */
+export interface CredentialInput {
+    kind: CredentialKind;
+    subject: string;
+    secret: string;
+    label: string;
+}
+/** The longest name a credential may carry. */
+export declare const CREDENTIAL_LABEL_MAX = 60;
+/**
+ * A credential's name, tidied: whitespace collapsed, at most 60 characters.
+ * Empty is refused — two passkeys both called "Passkey" cannot be told apart
+ * when one has to be removed (operator, 2026-10-04).
+ */
+export declare function credentialLabel(label: unknown): string;
+/**
+ * A sign-in waiting for its second factor (#1523): the first factor passed,
+ * no session exists yet. Held by AuthManager only — never a provider —
+ * bound to the requesting browser, single-use, and short-lived.
+ */
+export interface PendingSignIn {
+    handle: string;
+    username: string;
+    first: AuthenticateResult;
+    /** The requesting browser's binding value (an HTTP-only cookie); every step must present it. */
+    binding: string;
+    requestedAt: number;
+    expiresAt: number;
+    requestIp?: string;
+    requestUserAgent?: string;
+    /** Private-store keys unlocked by the password, held until the sign-in completes or is dropped. */
+    privateStoreHandle?: string;
+    /** The second factor, once satisfied. */
+    approved?: SatisfiedFactor;
+    /** Refused by the person ("this wasn't me"). */
+    denied?: boolean;
+    /** When the last approval message went out, for the resend limit. */
+    lastSentAt?: number;
+}
+/** A second factor a person has enrolled and can use now. */
+export interface AvailableSecondFactor {
+    id: 'email-link';
+    label: string;
+    /** Where it goes, masked for display (j***@example.com). */
+    target: string;
+}
+/** j***@example.com — enough to recognise, not enough to harvest. */
+export declare function maskEmail(address: string): string;
+/**
+ * Resolve an entry's `icon` (#1781). Accepted: an `https://` address, a site
+ * path (starts with one `/`, no `\`), or a Font Awesome name, normalised to
+ * its full class (`fa-users` → `fas fa-users`). Anything else — `http:`,
+ * `javascript:`, `data:`, a relative path — is refused with a warning naming
+ * the entry, and the default shown. Unset: the preset's icon, else generic.
+ */
+export declare function resolveOutsideProviderIcon(name: string, icon: unknown, preset: string | undefined, warn: (message: string) => void): OutsideProviderIcon;
+/** An outside sign-in provider as offered: on the login page, and to connect on the profile (#1743). */
+export interface OutsideProvider {
+    /** `oidc:<name>` */
+    id: string;
+    /** The `<name>` in its URLs. */
+    name: string;
+    displayName: string;
+    icon: OutsideProviderIcon;
+}
+/** An outside identity connected to an account, as shown to its owner (#1743). */
+export interface ConnectedIdentity {
+    /** The credential row's id — what Disconnect removes. */
+    id: string;
+    /** What the provider was called when it was connected. */
+    label: string;
+    /** The provider's verified email, '' when it gave none. */
+    email: string;
+    createdAt: string;
+    lastUsedAt?: string;
+    /** The provider it came from, while it is configured and enabled; null when it is not, and it cannot sign in. */
+    provider: OutsideProvider | null;
+}
+/** How connecting an outside identity ended (#1743). */
+export type ConnectOutcome = 'connected' | 'refused' | 'already-yours' | 'connected-elsewhere';
+/**
+ * A verified outside identity no account has connected, held in the session
+ * until the person signs in another way and confirms it (#1743 slice 3). One
+ * at a time; a new one replaces the old. `email` is the provider's verified
+ * email, or ''.
+ */
+export interface PendingConnection {
+    providerId: string;
+    /** `${iss}#${sub}` */
+    subject: string;
+    email: string;
+    /** The provider's name, for the notice. */
+    displayName: string;
+    /** Epoch ms. */
+    expiresAt: number;
+    /** Where the sign-in that follows was going; a declined connection goes there. */
+    returnTo?: string;
+}
+/** How an outside sign-in's callback ended (#1743), for the route to answer. */
+export type OutsideSignIn = 
+/** Signed in (`created`: an account was made for it first); `next` is where to go. */
+{
+    outcome: 'signed-in' | 'created';
+    next: string;
+}
+/** Held as a pending connection: the person signs in another way to connect it. `error` is what to say, if anything. */
+ | {
+    outcome: 'connect-first';
+    error?: string;
+}
+/** Refused; nothing says whether an account exists. */
+ | {
+    outcome: 'refused';
+}
+/** The state was already used: no second session. */
+ | {
+    outcome: 'replayed';
+};
+/** 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;
+}
+/**
+ * How a delegated credential is renewed (#1764): `fixed` ends on its date and
+ * someone makes a new one; `refreshable` is renewed automatically, with a new
+ * key each time. `extendable` (renewed by hand, same key) is #1734, not built.
+ */
+export type Renewal = 'fixed' | 'refreshable';
+/**
+ * One row of a person's "My tokens and devices" list (#1764): an agent token
+ * they made (`token`), or an app or device they approved through this site's
+ * own sign-in server (`app`). Never a secret.
+ */
+export interface Delegation {
+    kind: 'token' | 'app';
+    id: string;
+    name: string;
+    /** An app approved on a device by entering a code. */
+    device: boolean;
+    renewal: Renewal;
+    /** What it may do: permission names (and, for an app, its sign-in scopes). */
+    scopes: string[];
+    /** `scopes` in plain words, for a person to read (#1764): `describeScopes`. */
+    can: ScopeDescription[];
+    /** ISO 8601: made or approved. */
+    createdAt: string | null;
+    /** ISO 8601: when it stops working; null when it does not end by date. */
+    expiresAt: string | null;
+    /** ISO 8601: when a refreshable one was last renewed; null if not yet. */
+    renewedAt: string | null;
+    /** ISO 8601: an agent token's last use; null for an app, or never used. */
+    lastUsedAt: string | null;
+    /**
+     * #1762 slice 6: who approved it while acting for this person under a proxy
+     * grant; null when the person approved it themselves.
+     */
+    approvedBy: string | null;
+    /** The proxy grant it was approved under; ending that grant revokes it. Null when the person approved it. */
+    proxyGrantId: string | null;
+}
+export type DelegationKind = Delegation['kind'];
+/** The setting that turns proxy access on (#1762); false by default. */
+export declare const PROXY_ACCESS_ENABLED_KEY = "ngdpbase.auth.proxy-access.enabled";
+/** The permission to make a proxy grant on your own account (#1762); step-up. */
+export declare const PROXY_GRANT_PERMISSION = "proxy-grant";
+/**
+ * A proxy grant (#1762 slice 1): `owner` lets `proxy` act for them within
+ * `permissions`. Kept as a signed `proxy` row of the credentials store. Slice 1
+ * records it only: no request is affected by it yet.
+ */
+export interface ProxyGrant {
+    id: string;
+    /** The person represented. */
+    owner: string;
+    /** The person who may act for them. */
+    proxy: string;
+    /** Permission names; each one the owner held when the grant was made. */
+    permissions: string[];
+    /** Who made it: the owner, or an administrator acting for them. */
+    createdBy: string;
+    /** ISO 8601. */
+    createdAt: string;
+    /** ISO 8601: when it stops; null lasts until revoked. */
+    expiresAt: string | null;
+    /**
+     * Vault access (operator, 2026-10-12). `copy`: the owner made it with their
+     * store unlocked and `vault-proxy` in it, so it carries a copy of their
+     * vault key sealed to the proxy's public key (#1762 slice 5) — the copy
+     * itself is in the row, never on the grant. `none`: the owner made it with
+     * no copy (no `vault-proxy`, or no encrypted store to copy). `never`: an
+     * administrator made it, so it never carries one.
+     */
+    vault: 'none' | 'never' | 'copy';
+}
+/** A grant as listed: its terms, the permissions in plain words, and whether it lets the proxy give others access. */
+export interface ProxyGrantView extends ProxyGrant {
+    can: ScopeDescription[];
+    /** It includes `proxy-grant`: the proxy may make grants for the owner (the UI warns, #1762 slice 7). */
+    mayRedelegate: boolean;
+}
+/** What `grantProxy` takes. */
+export interface ProxyGrantInput {
+    owner: string;
+    proxy: string;
+    permissions: string[];
+    /** ISO 8601, in the future; omitted or null for none. */
+    expiresAt?: string | null;
+}
+/** Which side of the grants to list: the ones a person made (`asOwner`) or the ones naming them as proxy (`asProxy`). */
+export type ProxyGrantSide = {
+    asOwner: string;
+    asProxy?: undefined;
+} | {
+    asProxy: string;
+    asOwner?: undefined;
+};
+/** Where a signed-in person chooses whom to act for, and switches back (#1762 slice 4). */
+export declare const ACTING_FOR_PATH = "/account/acting-for";
+/**
+ * Why a session started or stopped acting for someone (#1762 slice 4), as the
+ * `proxy-switch` record's `reason` says it: the person chose a grant, chose
+ * themselves again, or the session was dropped back to them because the grant
+ * no longer allows it (ended, expired, either account inactive) or proxy
+ * access was turned off. `vault-opened` is not a switch: the grant's key copy
+ * was opened, so the represented person's encrypted vaults are open to the
+ * session that acts for them (#1762 slice 5).
+ */
+export type ActingForChange = 'chosen' | 'switched-back' | 'grant-ended' | 'proxy-access-off' | 'vault-opened';
+/** The choice a signed-in person has (#1762 slice 4): themselves, or someone a live grant lets them act for. */
+export interface ActingForChoices {
+    /** The person signed in on this session. */
+    self: string;
+    /** The grant this session acts under now, or null when the person acts as themselves. */
+    actingFor: string | null;
+    /** The live grants naming the person as proxy. */
+    grants: ProxyGrantView[];
+}
+/**
+ * How a session signed in (#1523): kept on the session so step-up (#1525) can
+ * ask "was a factor satisfied within N minutes", the audit record can say how,
+ * and UserInfo (#1529) can report `amr` / `acr` without overstating them.
+ */
+export interface SignInRecord extends Assurance {
+    provider: string;
+    factors: SatisfiedFactor[];
+    /** 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';
+/** The step-up answer (#1525, #1635), for the caller to send in its own form. */
+export interface FreshSignInAnswer {
+    /** The refused permission. */
+    permission: string;
+    /** An agent token or share link: it can never give a fresh sign-in, so there is no `reauth`. */
+    delegated: boolean;
+    /** What to tell the person. */
+    error: string;
+    /** Where to re-authenticate, returning to the page they were on. Absent for a delegated credential. */
+    reauth?: string;
+}
+/**
+ * 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.
+ */
+export declare function reauthReturnTo(req: Request, mode?: ReauthMode): string;
+/**
+ * Where an authentication attempt came from, and why (#1758). AuthManager is
+ * the one door for every check of a secret, and writes the audit record of a
+ * sign-in method's check itself; routes write none.
+ * - `sign-in` (default): a person signing in; a success counts on the account.
+ * - `re-check`: proving it again before a change (a password re-entered on the
+ *   profile, a store door); audited, never counted as a sign-in.
+ */
+export interface AuthAttempt {
+    ipAddress?: string;
+    userAgent?: string;
+    purpose?: 'sign-in' | 're-check';
+}
+export interface AuthenticateResult {
+    success: boolean;
+    username?: string;
+    /** The provider that verified this sign-in (#1523). */
+    provider?: string;
+    /** The factors satisfied, each with its time; empty for a delegated credential (#1523). */
+    factors?: SatisfiedFactor[];
+    /**
+     * #946 — set by token-based providers. Carries the delegating token's
+     * identity and scopes so the caller can enforce the scope ceiling and stamp
+     * page provenance.
+     *
+     * #1048: references the same `ViaToken` the provider contract declares,
+     * rather than repeating the shape. The two ends of one value used to be
+     * written out twice, which is how they drifted far enough apart to need a
+     * cast between them.
+     */
+    viaToken?: ViaToken;
+    /** #1576: the sign-in level a bearer credential carries; roles above it step down. */
+    aal?: Aal;
+    /** #1633: what an outside provider reported about its own sign-in, for the audit record. */
+    reported?: ReportedValues;
+}
+declare class AuthManager extends BaseManager {
+    private providers;
+    private factorEntries;
+    /** Built on first use and dropped on registration, since add-ons register late. */
+    private factorCache;
+    /** The credentials store (#1524); null when it could not be opened. */
+    private credentials;
+    constructor(engine: WikiEngine);
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * `ngdpbase.auth.factors`, or the retired flat `required-factors` list
+     * converted to entries when a site still sets only that (#1523).
+     */
+    private readFactorEntries;
+    /**
+     * The outside OpenID Connect providers (#1743): one `OidcAuthProvider` per
+     * enabled entry of `ngdpbase.auth.oidc.providers`, plus the old
+     * `ngdpbase.auth.google-oidc.*` keys as the `google` entry when the map has
+     * none. Connected identities live in the credentials store, so without it
+     * no outside sign-in can work and none is registered. An entry that cannot
+     * work (no issuer, no client id, a secret that is not an environment
+     * reference, nowhere to come back to) is refused with the reason.
+     */
+    private registerOidcProviders;
+    /** A secret from its environment reference (`$NAME`); never the secret written into configuration. */
+    private secretFromEnvironment;
+    /**
+     * Apple's client secret is signed by the site (#1743 slice 4b): the team id,
+     * the key's id, and the EC P-256 private key Apple issued (the `.p8` file's
+     * PEM, from an environment reference; `\n` escapes are accepted for a
+     * one-line variable). Null, with the reason refused, when any is missing or
+     * the key is not one Apple signs with.
+     */
+    private signingKeyFrom;
+    private outsideProvider;
+    /**
+     * Whether this enabled outside provider POSTs its callback (`form_post`,
+     * Apple) — the only callbacks the relay in front of the session and CSRF
+     * accepts as a POST (#1743 slice 4b).
+     */
+    callbackIsPosted(providerId: string): boolean;
+    /**
+     * Can a visitor with no account get one by an outside sign-in (#1743)?
+     * True when at least one enabled provider may create accounts, by the one
+     * rule the callback applies (`outsideMayCreateAccounts`). The header's
+     * Register button counts it as open sign-up. Read when asked.
+     */
+    outsideSignUpOpen(): boolean;
+    /** The outside sign-in providers configured and enabled now, in registration order (#1743). */
+    outsideProviders(): OutsideProvider[];
+    /** The enabled provider an identity row came from, by its issuer; null when none is. */
+    private providerOfIdentity;
+    /** Whether a credential row can start a sign-in now: an outside identity only while its provider is enabled. */
+    private isWayIn;
+    /**
+     * `username`'s connected outside identities (#1743), for its owner: each
+     * with the provider's email and whether that provider can sign in now.
+     */
+    connectedIdentities(ctx: PermissionSubject, username: string): Promise<ConnectedIdentity[]>;
+    /**
+     * Begin connecting an outside identity to the signed-in person's own
+     * account (#1743): an `account-security` change, so step-up applies.
+     * Returns the provider's URL to send the browser to.
+     */
+    startConnect(ctx: PermissionSubject, username: string, providerId: string, flow: {
+        redirect?: string;
+        deviceState: string;
+    }): Promise<string>;
+    /** The account a flow is connecting an identity to, or null for a sign-in (or an unknown flow) (#1743). */
+    flowConnectsFor(providerId: string, state: string): string | null;
+    /**
+     * Finish connecting an outside identity to `username` (#1743). The flow
+     * must be the one this person started to connect; the identity is the
+     * issuer plus subject, and belongs to exactly one account, so one already
+     * connected elsewhere is refused. Audited as a credential added.
+     */
+    connectIdentity(ctx: PermissionSubject, username: string, providerId: string, credentials: AuthVerifyCredentials, attempt?: AuthAttempt): Promise<ConnectOutcome>;
+    /**
+     * Add an outside identity to `username` — the one place a connection is
+     * made (#1743): from the profile, at the next sign-in after the email step,
+     * and when an account is created for it. The identity belongs to exactly
+     * one account, so one already connected elsewhere is refused. Audited as a
+     * credential added, saying how. The caller has decided the person may.
+     */
+    private attachIdentity;
+    /**
+     * Finish an outside sign-in's callback (#1743): the one decision about what
+     * a verified outside identity does here. Connected to an account: that
+     * account signs in. Connected to none: an account is created for it when
+     * the instance, the provider and the registration policy all allow it and
+     * the provider verified the email; otherwise (or when that email already
+     * belongs to an account) it is held in the session as a pending connection
+     * until the person signs in another way and confirms it. Email never signs
+     * anyone in.
+     */
+    finishOutsideSignIn(req: Request, providerId: string, credentials: AuthVerifyCredentials, attempt?: AuthAttempt): Promise<OutsideSignIn>;
+    /**
+     * May an outside sign-in create an account (#1743)? All three must allow
+     * it: the instance ceiling `ngdpbase.auth.oidc.auto-provision`, the
+     * provider's own `auto-provision` in `ngdpbase.auth.oidc.providers`, and
+     * `ngdpbase.application.registration`, the policy for whether any path may
+     * create an account. Read when asked, so a change applies at once.
+     * {@link outsideSignUpOpen} asks the same rule for every enabled provider.
+     */
+    private outsideMayCreateAccounts;
+    /**
+     * Does the admin trust this outside provider's own second factor (#1633)?
+     * Its entry's `trust-mfa` in `ngdpbase.auth.oidc.providers`, off unless set
+     * to true; read when asked, so a change applies at the next sign-in. The old
+     * `ngdpbase.auth.google-oidc.*` keys have no such switch: off.
+     */
+    private trustsOutsideMfa;
+    /** The provider's entry in `ngdpbase.auth.oidc.providers` as configured now, or null. */
+    private oidcEntry;
+    /**
+     * Create the account for an outside identity's verified email (#1743), by
+     * the path magic-link auto-provisioning takes: a derived username,
+     * `UserManager.createUser` with registration's default roles (the provider
+     * gives none), no password (`isExternal`), the system principal acting with
+     * the provider named as the reason. `createUser` records the creation. An
+     * email that already belongs to an account creates nothing: the safe
+     * registration message is returned instead.
+     */
+    private createAccountFor;
+    /** Delete an account created for an outside sign-in that could not be finished (#1743), through UserManager, which closes its access. */
+    private removeCreatedAccount;
+    /**
+     * The person's pending connection, for the sign-in page's notice and the
+     * confirmation page; an expired one is dropped (#1743).
+     */
+    pendingConnection(req: Request): {
+        displayName: string;
+        email: string;
+    } | null;
+    /** The person cancelled the pending connection (#1743). */
+    dropPendingConnection(req: Request): void;
+    /**
+     * Connect the pending identity to the signed-in person's own account, on
+     * their confirmation (#1743). Never automatic: on a shared browser the
+     * pending identity may be someone else's, and connecting it would let that
+     * person sign in here as this account. Checked again now: signed in, not
+     * expired, the provider enabled and allowed for the account, and the
+     * identity not connected elsewhere. Returns where to send the person, with
+     * what happened.
+     */
+    confirmPendingConnection(req: Request, ctx: PermissionSubject): Promise<string>;
+    /** The person declined the pending connection: drop it, and return where their sign-in was going (#1743). */
+    declinePendingConnection(req: Request): string;
+    /**
+     * Open the credentials store (#1524). Without the key nothing can be
+     * verified, so the store stays closed and the manager says so; boot itself
+     * never runs without the key, because bootstrap-env generates it.
+     */
+    private openCredentialsStore;
+    /**
+     * Passkeys (#448), registered only when they can work: the credentials store
+     * is open, `ngdpbase.auth.passkey.enabled` is not false, and base-url is set
+     * explicitly and is a secure context. The relying party is that host — never
+     * the request — so a passkey made here works only on that hostname.
+     */
+    private registerPasskeys;
+    private passkeyProvider;
+    /** The host passkeys are tied to, or null when passkeys are off (#448). */
+    passkeyRelyingParty(): PasskeyRelyingParty | null;
+    /** Options for `username` to enrol a passkey (#448); the caller keeps `challenge` for verify. */
+    /**
+     * May this account sign in with `providerId`? Its `allowedAuthMethods`, when
+     * set, list the providers it may use; absent or empty means any. The one
+     * answer for signing in and for enrolling (#1664): a method the account
+     * cannot sign in with is never offered or enrolled.
+     */
+    userMayUseProvider(username: string, providerId: string): Promise<boolean>;
+    passkeyRegistrationOptions(ctx: PermissionSubject, username: string, displayName: string): Promise<unknown>;
+    /**
+     * Verify an enrolment against the challenge the caller kept, and store the
+     * passkey (#448). Returns the credential id, or null when it does not verify.
+     */
+    passkeyRegister(ctx: PermissionSubject, username: string, response: unknown, expectedChallenge: string, label: string): Promise<string | null>;
+    /** Options for signing in with a passkey (#448); anyone may ask. */
+    passkeyAuthenticationOptions(): Promise<unknown>;
+    /**
+     * A row that does not verify was planted or damaged (#1524). It has already
+     * been dropped; this makes it impossible to miss: a critical security event,
+     * an escalating admin notification, and a degraded AuthManager until the
+     * store is put right.
+     */
+    private raiseRejectedCredentials;
+    /**
+     * Whether `ctx` may act on `username`'s credentials: their own under
+     * `profile-manage`, anyone else's under `user-edit` (#1524). No PDP, no answer,
+     * no access.
+     */
+    private mayManageCredentials;
+    /**
+     * Trust again the credential rows that failed verification (#1633): the
+     * operator's deliberate repair after the credentials key was lost or
+     * changed, so people keep their passkeys and verified addresses. Run from
+     * `scripts/retrust-credentials.ts`, never from a request — a web button
+     * that re-signs whatever is in the file would let anyone who can write the
+     * file plant a credential and have it blessed. Recorded as a security event
+     * naming every row and the reason.
+     */
+    retrustRejectedCredentials(reason: string, ctx: JobContext): Promise<{
+        trusted: number;
+        remaining: number;
+    }>;
+    private requireCredentialsStore;
+    /**
+     * `username`'s credentials, without their secrets (#1524). Reading the list
+     * is not a change, so it asks whether the person HOLDS the permission and
+     * leaves out the fresh-sign-in rule (#1738): a stale sign-in that was
+     * refused here showed its owner no passkeys at all, and they believed them
+     * lost. Adding, renaming and removing still ask for a fresh sign-in.
+     */
+    listCredentials(ctx: PermissionSubject, username: string): Promise<CredentialView[]>;
+    /** Enrol a credential for `username`; returns its id. Audited (#1524). */
+    addCredential(ctx: PermissionSubject, username: string, input: CredentialInput): Promise<string>;
+    /** Store and audit a credential the caller has already decided may be added; `how` says how it happened. */
+    private storeCredential;
+    /**
+     * Remove one of `username`'s credentials. Refused when it is their last way
+     * in: no password and no other credential that can start a sign-in (#1524).
+     */
+    removeCredential(ctx: PermissionSubject, username: string, id: string): Promise<boolean>;
+    /**
+     * The one deactivation step (#1765): "this account can no longer sign in".
+     * Disable and delete both come through here, from UserManager, so nothing
+     * an account holds is left reachable by one path and not the other.
+     *
+     * - Both: every session of the account ends.
+     * - Disable: its agent tokens, app grants and shares are suspended by the
+     *   live owner-is-active checks that refuse them, and its credentials stay,
+     *   so turning the account back on restores them.
+     * - Delete: its agent tokens, app grants and shares are revoked, and its
+     *   credentials-store rows (passkeys, verified addresses, devices) are
+     *   removed. A row names its account by username, so a row left behind
+     *   would sign in to a new account later created with the same name.
+     *
+     * The account change itself is audited by UserManager (user-delete, or the
+     * isActive change); each revocation is audited by its owner, and each removed
+     * credential here (`credential-remove`). Delete also ends every proxy grant
+     * the account is on, either side — the grants it made and the grants naming
+     * it as proxy (#1762), each recorded as `proxy-revoke` — whether or not
+     * proxy access is on. Disable leaves them, as it leaves tokens: acting under
+     * a grant must refuse it live while either account is inactive (#1762
+     * slice 2). The encrypted store is left to survivorship (#1545).
+     */
+    closeAccess(username: string, mode: 'disable' | 'delete', ctx: PermissionSubject): Promise<void>;
+    /**
+     * `username`'s agent tokens and the apps and devices they approved, as one
+     * list (#1764). Reading it is not a change, so, like `listCredentials`, it
+     * asks whether the caller holds the permission (their own:
+     * `account-security`; anyone else's: `user-edit`) without a fresh sign-in.
+     */
+    listDelegations(ctx: PermissionSubject, username: string): Promise<Delegation[]>;
+    /**
+     * Revoke one of `username`'s agent tokens or approved apps (#1764): the one
+     * door every Revoke goes through — the profile list, `DELETE /api/tokens/:id`,
+     * the admin user page — and `closeAccess`. Their own needs `account-security`
+     * (so a fresh sign-in); anyone else's `user-edit`. False when no such live
+     * item is theirs, so another person's is never revoked. Each is audited by
+     * its owner, by who revoked it: `token-revoke` / `oidcgrant-revoke`.
+     */
+    revokeDelegation(ctx: PermissionSubject, username: string, kind: DelegationKind, id: string): Promise<boolean>;
+    /**
+     * Scope and permission names in plain words (#1764): the permission
+     * catalog's `label` for each (`ngdpbase.permissions.definitions`, add-on
+     * permissions merged in), the sign-in scopes' own lines, and anything
+     * declared nowhere by its name. The one lookup: the "My tokens and devices"
+     * list and the app consent page both read it.
+     */
+    describeScopes(names: readonly string[]): ScopeDescription[];
+    /** One kind of `username`'s live delegated credentials, as list rows. */
+    private delegationsOf;
+    /**
+     * End one delegated credential the caller has already decided may be ended;
+     * only `username`'s own. Recorded by its owner as done by `ctx`: under a
+     * proxy grant, naming both people (#1762 slice 6).
+     */
+    private endDelegation;
+    /**
+     * End each of `username`'s live delegated credentials of one kind that
+     * `which` picks: the one loop for an account closed (all of them) and a
+     * proxy grant ended (those approved under it, #1762 slice 6).
+     */
+    private endDelegationsWhere;
+    /** Whether proxy access is on (`ngdpbase.auth.proxy-access.enabled`), read on every call. */
+    proxyAccessEnabled(): boolean;
+    private requireProxyAccess;
+    /**
+     * Whether `ctx` may make or end a grant on `owner`'s account (#1762): their
+     * own under `proxy-grant`, which asks for a fresh sign-in; anyone else's also
+     * under `user-edit`, so an administrator acting for someone is fresh too.
+     * `viewOnly` (a listing) asks whether the permission is held, without the
+     * fresh sign-in, as `mayManageCredentials` does.
+     */
+    private mayManageProxyGrants;
+    /**
+     * Let `proxy` act for `owner` within `permissions` (#1762 slice 1: recorded
+     * only; no request is affected yet). Refused while proxy access is off.
+     *
+     * - The owner makes it under `proxy-grant`; an administrator makes it for
+     *   them under `user-edit` too (see `mayManageProxyGrants`).
+     * - Delegate, not grant: every permission must be one the owner holds now,
+     *   the check agent tokens make (`lackingScopes`). Any permission they hold
+     *   may be included (operator, 2026-10-12), `proxy-grant` among them, which
+     *   lets the proxy give others access too (`mayRedelegate`).
+     * - An administrator's grant never carries vault access: no key copy
+     *   (`vault: 'never'`), and never `vault-proxy` (#1762 slice 7).
+     * - `expiresAt` is optional; without it the grant lasts until revoked.
+     *
+     * Recorded first, as `proxy-grant` (refuse on failure): `user` is the owner,
+     * `actor` who made it.
+     */
+    grantProxy(ctx: PermissionSubject, input: ProxyGrantInput): Promise<ProxyGrantView>;
+    /** Where private stores live; undefined when this site has no page directory. */
+    private pagesDirectory;
+    /**
+     * Why `ctx` cannot give access to their own vaults now, in plain words, or
+     * null when they can (#1762 slice 5). The give form shows it beside the
+     * "vaults" choice; grantProxy refuses with the same words.
+     *
+     * - Only the person themselves, signed in as themselves: not an
+     *   administrator, not a proxy re-delegating.
+     * - A person with an encrypted store must have it unlocked, so the grant
+     *   can seal a copy of its key. A person with none needs nothing unlocked:
+     *   the grant opens only their unencrypted vaults.
+     */
+    vaultGrantBlocked(ctx: PermissionSubject, owner: string): Promise<string | null>;
+    /**
+     * The copy of the owner's vault key a grant to `proxy` carries (#1762 slice
+     * 5), sealed to the proxy's public key while the owner's store is unlocked;
+     * null when the owner has no encrypted store (nothing to copy). Refused, in
+     * plain words, when the owner's store is locked or the proxy has no key
+     * pair yet — a grant never promises vault access it cannot give.
+     */
+    private sealVaultCopy;
+    /** The decision points and the represented person's live subject (`ctx` itself for one's own), as grantProxy and its form ask them. */
+    private proxyOwnerSubject;
+    /**
+     * What a grant on `owner`'s account may carry, in plain words (#1762 slice
+     * 7): every grantable catalog permission the owner holds now — the same
+     * `holds` question grantProxy asks — so the give form offers nothing
+     * grantProxy would refuse. An administrator's form for someone else, or a
+     * proxy's acting for them, never offers `vault-proxy`; the owner's own form
+     * offers it and says why it cannot be chosen now (`vaultGrantBlocked`).
+     * Asked like a listing (held, not fresh); refused
+     * while proxy access is off.
+     */
+    proxyGrantOptions(ctx: PermissionSubject, owner: string): Promise<ScopeDescription[]>;
+    /**
+     * End a proxy grant (#1762). The owner under `proxy-grant`; anyone else
+     * under `user-edit` too, so another person's grant is never ended by someone
+     * without both. False when there is no such grant. Recorded as
+     * `proxy-revoke`, first. Refused while proxy access is off.
+     */
+    revokeProxy(ctx: PermissionSubject, grantId: string): Promise<boolean>;
+    /**
+     * The live proxy grants on one side (#1762): those `asOwner` made, or those
+     * naming `asProxy`. One's own needs `proxy-grant` held; anyone else's
+     * `user-edit`, as `listDelegations`. A grant past its end date is left out.
+     * Refused while proxy access is off.
+     */
+    listProxyGrants(ctx: PermissionSubject, side: ProxyGrantSide): Promise<ProxyGrantView[]>;
+    /** The live grants on one side, unchecked: each caller has already decided who may see them. */
+    private liveGrantsOn;
+    /**
+     * The grant with this id if it is in force right now, else null (#1762
+     * slice 2): the PDP's live re-read on every decision under `viaProxy`.
+     * Null when proxy access is off, when there is no such row (revoked, or the
+     * account closed), when its terms do not read, or when its end date has
+     * passed — each fails closed. Not a door: it answers the decision point,
+     * never a person, so it asks no permission.
+     */
+    liveProxyGrant(grantId: string, now?: number): ProxyGrant | null;
+    /** The grant row with this id as it stands — live or not, whether proxy access is on or off — or null. */
+    private proxyGrantRecord;
+    /**
+     * The person signed in on this interactive session, or null. Never a
+     * bearer request: an agent token or an app can never act for anyone, so it
+     * can never choose to either. `session.username` stays the person who
+     * signed in while they act for someone; the subject changes, not the
+     * session.
+     */
+    private sessionPerson;
+    /**
+     * The request's subject when the session acts for someone (#1762 slice 4):
+     * the one place it is built, called from the session middleware in app.ts
+     * with the session's own subject (`self`). Returns `self` unchanged when the
+     * session acts for nobody.
+     *
+     * When `session.actingFor` names a grant, the grant is re-read live on this
+     * request: in force, proxy access on, naming the session's person as proxy,
+     * and the represented account active. The subject is then the represented
+     * person — their username and live roles — with `viaProxy` naming the
+     * actor, the grant and its permissions; the PDP bounds every decision by
+     * the grant and by what the actor holds. The sign-in is the actor's
+     * (`signIn`, `aalCap`): the represented person's roles are held at the
+     * level the actor signed in at, and step-up asks the actor's own fresh
+     * sign-in. It carries no private-store handle: the session's key bag is the
+     * actor's own.
+     *
+     * Anything else — a grant revoked or expired mid-session, an inactive
+     * account, proxy access turned off, a subject that came with a token or a
+     * share — drops the session back to the person themselves: `actingFor` is
+     * cleared and the drop recorded as `proxy-switch`. A request never acts on
+     * a dead grant.
+     */
+    subjectActingFor(req: Request, self: PermissionSubject): Promise<PermissionSubject>;
+    /**
+     * Open the grant's key copy into the actor's own bag (#1762 slice 5), once,
+     * when the grant carries `vault-proxy` and a copy and the actor's own store
+     * is unlocked; recorded as `proxy-switch` `vault-opened`, naming both
+     * people. Returns the handle the subject's claim carries to reach it, or
+     * undefined: no copy is held then, and a copy held for another grant is
+     * wiped. The copy is tried again when the actor unlocks their store later.
+     */
+    private openVaultCopy;
+    /**
+     * Whom the signed-in person may act for (#1762 slice 4): themselves, and
+     * each person a live grant names them proxy for. Null when proxy access is
+     * off or this is not an interactive signed-in session — the choice page
+     * does not exist then.
+     */
+    actingForChoices(req: Request): ActingForChoices | null;
+    /**
+     * Switch whom this session acts for (#1762 slice 4): a grant id, or null to
+     * act as yourself. The authority is the grant itself — live, naming the
+     * session's person as proxy, the represented account active — and the
+     * session's own sign-in; an agent token or an app never switches. Switching
+     * back is always allowed. Each change is recorded as `proxy-switch`. False
+     * when the switch is refused; the session is unchanged then.
+     */
+    switchActingFor(req: Request, grantId: string | null): Promise<boolean>;
+    /**
+     * A `proxy-switch` record (#1762 slice 4): `user` the person represented,
+     * `actor` the person signed in — the attribution every proxy row carries.
+     * When the grant's record is already gone (revoked), the represented person
+     * is not known and the row names the signed-in person alone.
+     */
+    private auditActingFor;
+    private proxyGrantView;
+    /**
+     * End a grant the caller has already decided may be ended: recorded first,
+     * then the tokens, apps and devices approved under it are revoked (#1762
+     * slice 6) — while the grant still stands, since a token under a grant no
+     * longer in force is no longer listed as live — and then it is removed.
+     */
+    private endProxyGrant;
+    /** A proxy-grant record (#1762): `user` the person represented, `actor` who acted. */
+    private auditProxy;
+    /** Rename one of `username`'s credentials. The name is required, as at enrolment. */
+    renameCredential(ctx: PermissionSubject, username: string, id: string, label: unknown): Promise<boolean>;
+    /** Whether the account signs in with a password — UserManager is the door that sees the hash (#1524). */
+    private hasPassword;
+    private auditCredentialChange;
+    /**
+     * The factors offered, in configuration order (#1523).
+     *
+     * An entry counts only when it is enabled and its provider is registered and
+     * declares itself a factor; listed but unavailable is never offered. Each
+     * value is the lower of the entry and the provider's code: an entry that
+     * overstates is lowered to the truth, with a warning naming the key.
+     */
+    getFactors(): Factor[];
+    private lowered;
+    /**
+     * What a set of satisfied factors amounts to (#1523), by NIST SP 800-63B.
+     *
+     * - `aal` is the strongest single factor's, lifted to AAL2 when the factors
+     *   cover two or more distinct types — email excepted: it never lifts a
+     *   sign-in above AAL1 (§5.1.3.1), though it still counts towards `mfa`.
+     * - `acr` is `phrh`, then `phr`, then the AAL — what we claim, never more.
+     * - `mfa` is two or more distinct types, which is what we require.
+     */
+    assess(factors: ReadonlyArray<Pick<Factor, 'amr' | 'aal' | 'acr'>>): Assurance;
+    /**
+     * Authenticate using the specified provider — the one door (#1758).
+     *
+     * A sign-in method (a provider listed in `ngdpbase.auth.factors`) has its
+     * failures and its re-checks audited here, with where they came from; a
+     * successful sign-in is recorded, and counted on the account, when it
+     * completes (`completeSignIn`), once with every factor it took. A request
+     * credential (agent token, app token, gateway header) is checked on every
+     * API request and is not audited per request.
+     */
+    authenticate(providerId: string, credentials: AuthVerifyCredentials, attempt?: AuthAttempt): Promise<AuthenticateResult>;
+    /**
+     * #1523: say how — the provider, and the factor it satisfied with its time.
+     * A delegated credential is never a factor, so it records none. An outside
+     * provider the admin trusts counts for what it reported (#1633,
+     * `outsideLevel`); step-up reads the same factor, so it uses the same level.
+     */
+    private satisfiedFactors;
+    /**
+     * What an outside provider's own sign-in counts for here (#1633) — the one
+     * mapping, for every outside provider, by NIST SP 800-63B and RFC 8176.
+     * Untrusted: AAL1 with no `amr`, whatever was reported. Trusted (operator,
+     * 2026-10-12): the report is taken as given, to whatever level it shows.
+     * The reported RFC 8176 `amr` values count:
+     *
+     * - AAL3, phishing-resistant on hardware (`phrh`): a hardware-bound key
+     *   (`hwk`) with a second factor or user verification — `mfa`, `user`, or a
+     *   second factor type by the same rule `assess` applies to this site's own
+     *   factors (`hwk` + `pin`, `hwk` + `fpt`, `hwk` + `pwd`; not `hwk` + `otp`).
+     *   This site's passkey is phishing-resistant the same way, through its
+     *   factor's `acr`, which `assess` carries to the sign-in.
+     * - AAL2: multi-factor — `mfa`, or two factor types by `assess`.
+     * - The `acr`, when it is an SP 800-63C identifier, raises the level to the
+     *   one it states (`…/aal/2`, `…/aal/3`); it is never phishing resistance.
+     * - 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. */
+    private auditCheck;
+    /** Each role's `required-aal`, and whether the operator set it, read through the catalogue's owner (#1523, #448). */
+    private requiredLevels;
+    /** The highest level the available factors reach together; 0 without a primary factor (#1523). */
+    reachableAal(): Aal;
+    /**
+     * A role's level as enforced (#448): its `required-aal`, except that a
+     * SHIPPED default no available factor reaches counts as what is reachable —
+     * an upgrade never locks an instance out. An operator's own level is never
+     * lowered; the boot refuses it instead (`checkRequiredAal`).
+     */
+    private effectiveLevels;
+    /**
+     * The highest level an account's own allowed sign-in methods reach, never
+     * below 1 (#1690). Operator rule (2026-10-08): whenever an account has no
+     * way to reach AAL2, AAL1 is what its roles require. The site-wide factors,
+     * narrowed to the account's `allowedAuthMethods` (none listed = all).
+     */
+    aalCapFor(username: string): Promise<Aal>;
+    /**
+     * What an account can reach now, and what it could reach once it enrols
+     * the factors it is allowed but has not set up (#1690). A factor that has
+     * to be enrolled — a passkey — counts toward `now` only when the account
+     * has one (operator, 2026-10-08: allowed but not enrolled is no way to
+     * AAL2 yet). Both are at least 1. The gap between them is what the account
+     * is told, on every page, to close.
+     */
+    aalReachFor(username: string): Promise<{
+        now: Aal;
+        ifEnrolled: Aal;
+    }>;
+    /**
+     * The roles an account holds at a lower level than they require only
+     * because it has not enrolled a factor it is allowed (#1690): it acts with
+     * them, and is told on every page to add the factor.
+     */
+    rolesAwaitingEnrolment(roles: readonly string[], reach: {
+        now: number;
+        ifEnrolled: number;
+    }): string[];
+    /** A role level, lowered to what the account can reach when its cap is known (#1690). */
+    private capped;
+    /**
+     * The level a sign-in must reach for someone holding `roles`: the highest
+     * effective level among them (#1523), never above the account's own cap
+     * when it is known (#1690).
+     */
+    requiredAalFor(roles: readonly string[], cap?: number): Aal;
+    /**
+     * Which of `roles` a session signed in at `signInAal` may act with (#448,
+     * decided 2026-10-03): a role whose effective level is above it steps down
+     * for this session — the person acts without it until they sign in strongly
+     * enough. Roles without a level are always kept, so a signed-in person keeps
+     * `profile-manage` and can reach their profile to enrol.
+     */
+    rolesAtSignIn(roles: readonly string[], signInAal: number, cap?: number): {
+        kept: string[];
+        steppedDown: string[];
+    };
+    /** Every role whose configured level the available factors cannot reach, described (#1523). */
+    unreachableRequiredAal(): string[];
+    /**
+     * 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
+     * set that no factor reaches. A shipped default that cannot be reached instead
+     * marks AuthManager degraded, naming what to do; those roles act at what is
+     * reachable meanwhile.
+     */
+    checkRequiredAal(): string[];
+    /** Whether `username` has enrolled a credential of `kind` — for the step-down banner (#448). */
+    hasCredential(username: string, kind: CredentialKind): boolean;
+    /**
+     * Step-up is AuthManager's (#1758, decided 2026-10-11): the freshness rule
+     * (`stepUpNeeded`), the answer to a refused request, re-authentication and
+     * its audit. The PDP stays the decider and asks `stepUpNeeded`.
+     *
+     * The answer for a person who holds `permission` but whose sign-in is not
+     * fresh enough, with the `reauth-prompt` recorded. A delegated credential is
+     * refused outright: it can never give a fresh factor.
+     */
+    askForFreshSignIn(req: Request, userContext: unknown, permission: string, mode: ReauthMode): Promise<FreshSignInAnswer>;
+    /** 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>;
+    /**
+     * 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
+     * outside provider — ends here, so none can forget a part.
+     *
+     * - A new session (#1043; a session already signed in on it ends, #1626),
+     *   with its sign-in time and a cookie as long as `ngdpbase.session.max-age`,
+     *   the cap from that time (#1767).
+     * - The person, `isAuthenticated`, how they signed in (`session.signIn`,
+     *   #1523) and the account's password-change generation (#1482).
+     * - Their private stores: a handle already unlocked (a two-step sign-in
+     *   unlocked at the password), or the password handed to the vault code
+     *   through the registered unlocker (#1594 adds a passkey's PRF output).
+     * - One audit record of the completed sign-in, naming how, and the count on
+     *   the account. `authenticate()` records failures and re-checks; a
+     *   successful sign-in is recorded here, once, when it is complete.
+     * - A pending outside identity (#1743): carried across the new session,
+     *   never connected here. The person is sent to confirm it (`next`,
+     *   `/login/connect/confirm`); ignored, it expires. An expired one is
+     *   dropped.
+     * - Whom to act for (#1762 slice 4): a person a live proxy grant names is
+     *   sent to choose (`next`, `ACTING_FOR_PATH`); they act as themselves
+     *   until they choose someone. The new session never carries a choice.
+     *
+     * The route saves the session and answers, going to `next` when it is set.
+     */
+    completeSignIn(req: Request, result: AuthenticateResult, how: {
+        method: string;
+        unlockWith?: {
+            password: string;
+        };
+        privateStoreHandle?: string;
+        returnTo?: string;
+    }): Promise<SignInCompleted>;
+    /**
+     * Start the signed-in session's lifetime (#1767), on the new session after
+     * regeneration: `signedInAt`, from which `ngdpbase.session.max-age` caps it
+     * (checked per request in app.ts, `checkSessionLimits`), and a cookie that
+     * lasts that long, so the cookie never ends the session before the cap.
+     * Only a sign-in writes it; a re-authentication (`completeReauth`) does not.
+     */
+    private startSessionLifetime;
+    /**
+     * Stamp the session with the account's password-change generation (#1482):
+     * at every sign-in, and on the session that changed the password, so that
+     * one stays signed in while every other session of the account ends.
+     */
+    stampSessionGeneration(req: Request, username: string): Promise<void>;
+    /**
+     * The vault code's unlocker (#1758, #1594): given who signed in and their
+     * password, unlock their private stores and return the session's handle.
+     * Registered by whoever owns the vault code (today the routes, #1382);
+     * sign-in completion and a two-step sign-in hand it the material, so no
+     * route unlocks stores itself.
+     */
+    setVaultUnlocker(unlock: (username: string, password: string) => Promise<string>): void;
+    /** Unlock `username`'s stores with their password through the registered unlocker, or none. */
+    unlockVaults(username: string, password: string): Promise<string | undefined>;
+    private vaultUnlocker;
+    private warnedNoUnlocker;
+    /** A fresh session for a sign-in (#1043); the one already on it ends first (#1626, #1670). */
+    private regenerate;
+    /**
+     * What a successful sign-in amounts to, for the session (#1523): its provider,
+     * the factors it satisfied with their times, and their assessment. Null for a
+     * failed result or a delegated credential, which never starts a session.
+     */
+    signInRecord(result: AuthenticateResult): SignInRecord | null;
+    /**
+     * Step-up (#1525): which permissions ask for a fresh factor, and how fresh.
+     * Which: every permission entry marked `step-up: true` in
+     * `ngdpbase.permissions.definitions` — the permission entry is the one
+     * declaration of its action (#1638). How fresh:
+     * `ngdpbase.auth.step-up.max-age-minutes`; missing, malformed or 0 means no
+     * step-up. A `permissions` list still set under `ngdpbase.auth.step-up` (the
+     * shape before #1638) is honoured as well, and said once.
+     */
+    stepUpPolicy(): {
+        maxAgeMs: number;
+        permissions: ReadonlySet<string>;
+    };
+    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
+     * never satisfies step-up.
+     */
+    stepUpNeeded(permission: string, signIn: SignInRecord | undefined, roles: readonly string[], delegated: boolean, now?: number, cap?: number): boolean;
+    /**
+     * 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
+     * time moves to now — this is a fresh authentication. The provider stays
+     * the one that started the session. Null when the result is no sign-in.
+     */
+    reauthenticated(signIn: SignInRecord | undefined, result: AuthenticateResult): SignInRecord | null;
+    private pendingSignIns;
+    private approvalTokens;
+    private enrolTokens;
+    /** Mail can carry an email-link factor: a mail transport and an explicit base-url for the link. */
+    private mailForLinks;
+    private linkBase;
+    /** 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.
+     */
+    secondFactorsFor(username: string): AvailableSecondFactor[];
+    /** Hold a sign-in whose first factor passed, until a second factor completes it. Returns its handle. */
+    beginTwoStep(first: AuthenticateResult, ctx: {
+        binding: string;
+        ip?: string;
+        userAgent?: string;
+        privateStoreHandle?: string;
+    }): string;
+    /** The pending sign-in, for the browser that started it; null when gone, expired, or another browser. */
+    pendingSignIn(handle: string | undefined, binding: string | undefined): PendingSignIn | null;
+    /**
+     * Email a one-time approval link for the pending sign-in (#1523, #1532).
+     * The link only opens the approval page; the button there approves, so a
+     * mail scanner opening links approves nothing. Limited to one per minute.
+     */
+    sendEmailApproval(handle: string, binding: string): Promise<'sent' | 'too-soon' | 'unavailable'>;
+    /** What the approval page shows about the waiting sign-in; null for an unknown or used link. */
+    approvalDetails(token: string): {
+        username: string;
+        requestedAt: number;
+        ip?: string;
+        userAgent?: string;
+    } | null;
+    /** Approve the waiting sign-in from its link (the button press). Single use; returns the username, or null. */
+    approveByToken(token: string): string | null;
+    /** Refuse the waiting sign-in from its link ("this wasn't me"). Returns the username, or null. */
+    denyByToken(token: string): string | null;
+    /**
+     * The finished sign-in, once its second factor is satisfied — both factors,
+     * assessed together. Single use: the pending entry is gone after this.
+     */
+    completeTwoStep(handle: string, binding: string): {
+        result: AuthenticateResult;
+        privateStoreHandle?: string;
+    } | null;
+    /** Drop a pending sign-in and lock any keys it held. */
+    dropPending(handle: string): void;
+    private sweepPending;
+    /**
+     * Start enrolling the account's email address as a second factor (#1523).
+     * The address must prove it receives mail first: a factor that cannot be
+     * satisfied would lock its owner out.
+     */
+    startEmailFactorEnrolment(ctx: PermissionSubject, username: string): Promise<'sent' | 'no-email' | 'unavailable' | 'already'>;
+    /** Finish enrolling from the emailed link, by the same signed-in person. Single use. */
+    confirmEmailFactorEnrolment(ctx: PermissionSubject, token: string): Promise<boolean>;
+    /**
+     * Initiate a challenge-based auth flow (magic link email, OAuth redirect).
+     */
+    initiate(providerId: string, context: AuthInitiateContext): Promise<void>;
+    /**
+     * Consume a single-use token, returning whether this caller consumed it.
+     *
+     * #1021: the return value is the single-use gate — a caller must not create
+     * a session when it is false, because that means another request consumed
+     * the token first. A provider with no `consumeToken` has no single-use
+     * semantics to enforce, so it reports true rather than blocking sign-in.
+     */
+    consumeToken(providerId: string, token: string): boolean;
+    /**
+     * 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
+     * whether a provider *should* be active, only that it is.
+     *
+     * ## Duplicate ids: first registration wins
+     *
+     * Deliberate, and the reason is security rather than tidiness. Last-wins
+     * would let an addon replace the built-in `password` provider with its own
+     * `verify()` — an auth bypass contributed by a config change. Throwing would
+     * be safe but lets one bad addon take the whole instance down at boot, and a
+     * refused provider is a smaller failure than a site that will not start. So:
+     * keep the incumbent, warn loudly, carry on.
+     *
+     * ## Late registration is allowed
+     *
+     * AuthManager initializes before AddonsManager (WikiEngine), so an addon
+     * registering during its own startup is registering late by definition. Such
+     * a provider is absent from `getFactors()` until it registers and cannot serve a request
+     * that arrives first. Both are acceptable; neither is silent.
+     *
+     * ## There is no unregisterProvider()
+     *
+     * Not an oversight. Withdrawing a provider would not invalidate the sessions
+     * already established through it, so "disabled" would mean "no new logins"
+     * while existing ones continued — which reads as revocation without being it.
+     * Honest session revocation is a larger feature than this seam, and pretending
+     * 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
+     */
+    registerProvider(provider: AuthProvider, source?: string): boolean;
+    /**
+     * Begin a redirect-based flow; returns the URL to send the browser to (#1049).
+     *
+     * Throws when the provider is absent or cannot start a flow, deliberately
+     * and unlike {@link getFlowRedirect} below. There is no sensible fallback for
+     * "where should the browser go" — returning `'/'` would bounce the user back
+     * to the page they just left with no error to explain it, which reads as the
+     * button being broken. Callers guard with `isEnabled()` first.
+     */
+    startFlow(providerId: string, context?: AuthInitiateContext): Promise<string>;
+    /**
+     * Where the user was headed before the flow began, keyed by the flow's own
+     * handle — a magic-link token, an OAuth state nonce (#1049).
+     *
+     * Must be called BEFORE `consumeToken()`, which deletes the entry.
+     *
+     * Falls back to `'/'` rather than throwing, deliberately and unlike
+     * {@link startFlow} above: losing the destination costs the user a redirect
+     * to the front page, while failing the sign-in over it would cost them the
+     * login itself.
+     */
+    getFlowRedirect(providerId: string, handle: string): string;
+    /**
+     * The device-state recorded when this flow was initiated (#1022), or null.
+     *
+     * Must be called BEFORE `consumeToken()`, which deletes the entry.
+     *
+     * Null means "nothing to compare against" — a provider that does not bind,
+     * or a handle issued before binding existed. It never means "did not match":
+     * that distinction is made in `evaluateDeviceBinding`, and collapsing the two
+     * here would make an unbindable flow look like an attack.
+     */
+    getDeviceState(providerId: string, handle: string): string | null;
+    /**
+     * Create the account behind a first-time credential (#1026, #1049).
+     *
+     * Must be called before `authenticate(providerId, …)` on the completing
+     * request, because the account has to exist before a session names it.
+     *
+     * Three outcomes, and the caller must tell them apart:
+     *   - `true`  — account created, or already existed
+     *   - `false` — the provider tried and could not; treat as a failed sign-in
+     *   - `undefined` — nothing to provision here, which is not a failure
+     *
+     * The previous `provisionMagicLinkUser` returned `false` for a missing
+     * provider, conflating "no such capability" with "tried and failed". The end
+     * state was the same only because `authenticate()` then failed anyway.
+     */
+    provisionIfNew(providerId: string, handle: string): Promise<boolean | undefined>;
+    /** Returns true if the provider is registered. */
+    isEnabled(providerId: string): boolean;
+    /** Returns all registered providers (for admin UI). */
+    getProviders(): AuthProvider[];
+    backup(): Promise<BackupData>;
+    restore(_backupData: BackupData): Promise<void>;
+}
+export default AuthManager;