@jwilleke/ngdpbase-types 5.24.0 → 5.26.0

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

@@ -30,7 +30,7 @@
  * @see {@link https://github.com/jwilleke/ngdpbase/issues/396}
  */
 import BaseManager from './BaseManager.js';
-import type { BackupData, ManagerBackupOptions, ManagerRestoreOptions } from './BaseManager.js';
+import type { BackupData, BackupFolder } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { PermissionSubject } from './UserManager.js';
 import type { JobContext } from '../context/JobContext.js';
@@ -107,6 +107,12 @@ export declare function credentialLabel(label: unknown): string;
  */
 export interface PendingSignIn {
     handle: string;
+    /**
+     * The id every audit record of this sign-in's approval carries (#1532), so
+     * the steps read as one trail. Random and separate from the handle and the
+     * link token, which are secrets.
+     */
+    id: string;
     username: string;
     first: AuthenticateResult;
     /** The requesting browser's binding value (an HTTP-only cookie); every step must present it. */
@@ -115,15 +121,54 @@ export interface PendingSignIn {
     expiresAt: number;
     requestIp?: string;
     requestUserAgent?: string;
+    /** Roughly where the request came from ("Columbus, United States"), or null when no source says (#1532). */
+    requestLocation?: string | null;
     /** 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"). */
+    /** Refused by the person (Deny). */
     denied?: boolean;
     /** When the last approval message went out, for the resend limit. */
     lastSentAt?: number;
 }
+/**
+ * What an approval request says about a waiting sign-in (#1532): one source
+ * for the message and the page.
+ */
+export interface ApprovalAbout {
+    /** The site's name (`ngdpbase.application-name`). */
+    site: string;
+    /** When it was asked, in the account holder's own time zone. */
+    when: string;
+    /** "Chrome on Windows", or null when the browser could not be named. */
+    device: string | null;
+    /** The IP address it came from (Express's `req.ip`, so `trust-proxy` applies). */
+    ip?: string;
+    /** Roughly where ("Columbus, United States"), or null when no source says. */
+    location: string | null;
+}
+/** What the approval page shows about a waiting sign-in (#1532). */
+export interface ApprovalDetails extends ApprovalAbout {
+    username: string;
+    requestedAt: number;
+    userAgent?: string;
+    /** The sentence the message says, as HTML with every value escaped. */
+    sentenceHtml: string;
+}
+/**
+ * The approval sentence (#1532, decided wording plus the IP and place):
+ * "A sign-in request for Willeke Family was sent at 2 Oct 2026, 14:02 EDT
+ * from Chrome on Windows at IP address 81.2.69.160, near Columbus, United
+ * States." `strong` marks the site and time, `text` every other value; for
+ * HTML both escape.
+ */
+export declare function approvalSentence(about: ApprovalAbout, strong?: (v: string) => string, text?: (v: string) => string): string;
+/** Who opened the approval page or pressed its button (#1532): recorded, never trusted for anything. */
+export interface ApprovalVisitor {
+    ip?: string;
+    userAgent?: string;
+}
 /** A second factor a person has enrolled and can use now. */
 export interface AvailableSecondFactor {
     id: 'email-link';
@@ -202,6 +247,18 @@ export type OutsideSignIn =
 /** The state was already used: no second session. */
  | {
     outcome: 'replayed';
+}
+/**
+ * #1532: the provider's sign-in reached only AAL1 and the account has a
+ * second factor: held as a pending sign-in, as after a password. The route
+ * binds the browser (`binding`), keeps `handle` in the session and sends the
+ * person to the second-factor page; `next` is where they were going.
+ */
+ | {
+    outcome: 'second-step';
+    handle: string;
+    binding: string;
+    next: string;
 };
 /** 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 {
@@ -1030,6 +1087,12 @@ declare class AuthManager extends BaseManager {
         privateStoreHandle?: string;
         returnTo?: string;
     }): Promise<SignInCompleted>;
+    /**
+     * Whether `username` has core documents to accept (#1603), asked of
+     * ConsentManager. A store that cannot be read asks nothing, loudly: a
+     * broken consent folder must not lock everyone out.
+     */
+    private termsPendingFor;
     /**
      * Start the signed-in session's lifetime (#1767), on the new session after
      * regeneration: `signedInAt`, from which `ngdpbase.session.max-age` caps it
@@ -1117,32 +1180,79 @@ declare class AuthManager extends BaseManager {
      * is not offered. Empty means the sign-in is one step, as before.
      */
     secondFactorsFor(username: string): AvailableSecondFactor[];
+    /**
+     * Whether a successful first step needs a second (#1532, operator
+     * 2026-10-22): everyone who arrives with only a password behind them — a
+     * password typed here, or an outside provider's sign-in at AAL1 — when the
+     * account has a second factor it can use now. Never after an email link
+     * (the second factor would go to the same inbox), and never after a sign-in
+     * already at AAL2 or above (a passkey, a provider whose second factor the
+     * admin trusts).
+     */
+    needsSecondStep(result: AuthenticateResult): boolean;
+    /**
+     * Roughly where `req` came from, for the approval message (#1532):
+     * Cloudflare's location headers when `ngdpbase.server.behind-cloudflare`,
+     * else the GeoLite2 City file at `ngdpbase.server.geolite2-city-file`, else
+     * null. Read when asked, so a change applies at the next sign-in. The IP is
+     * Express's `req.ip`, which honours `ngdpbase.server.trust-proxy`.
+     */
+    approximateLocation(req: Pick<Request, 'ip'> & {
+        get?: (name: string) => string | undefined;
+    }): Promise<string | null>;
     /** 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;
+        location?: string | null;
         privateStoreHandle?: string;
     }): Promise<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;
+    /**
+     * Record one step of a sign-in's approval (#1532): every record carries the
+     * pending sign-in's `id` (never its handle or the link token), the account
+     * it is for, and who took the step — the IP and browser of the request, the
+     * opener or the presser. `user` is the account signing in: there is no
+     * session yet, so no proxy (whom to act for is chosen after sign-in).
+     */
+    private recordApproval;
+    /**
+     * HTML escaping for the approval message and page (#1532): PluginManager's
+     * formatter (#1820), the one escapeHtml. Its absence is a wiring fault, not
+     * a reason to send a value unescaped.
+     */
+    private escapeHtml;
+    /** Where the sign-in asked from, as the request, send and expiry records say it. */
+    private static askedFrom;
     /**
      * 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.
+     * Each outcome is recorded: sent (`signinapproval-request`), too soon
+     * (`-throttle`), or not sent (`-sendfail`).
      */
     sendEmailApproval(handle: string, binding: string): Promise<'sent' | 'too-soon' | 'unavailable' | 'failed'>;
-    /** 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;
+    /**
+     * What the approval page shows about the waiting sign-in; null for an
+     * unknown or used link. Opening the page changes nothing, but it is
+     * recorded (`signinapproval-open`) with who opened it (#1532): a mail
+     * scanner opens links too.
+     */
+    approvalDetails(token: string, opener?: ApprovalVisitor): Promise<ApprovalDetails | null>;
+    /**
+     * What an approval request says about a waiting sign-in (#1532), one source
+     * for the message and the page: the site's name, when it was asked in the
+     * account holder's own time zone (their preference, else the site default),
+     * the browser and device it came from (null when the header names
+     * neither), its IP address, and roughly where (null when no source says).
+     */
+    private approvalContext;
     /** 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;
+    approveByToken(token: string, presser?: ApprovalVisitor): Promise<string | null>;
+    /** Refuse the waiting sign-in from its link (Deny). Returns the username, or null. */
+    denyByToken(token: string, presser?: ApprovalVisitor): Promise<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.
@@ -1151,8 +1261,15 @@ declare class AuthManager extends BaseManager {
         result: AuthenticateResult;
         privateStoreHandle?: string;
     } | null;
+    /**
+     * The waiting browser gave up the sign-in (Cancel, #1532): dropped, its
+     * keys locked, and recorded as `signinapproval-abandon`.
+     */
+    abandonTwoStep(handle: string, binding: string, from?: ApprovalVisitor): Promise<void>;
     /** Drop a pending sign-in and lock any keys it held. */
     dropPending(handle: string): void;
+    /** A pending sign-in past its time: dropped, and recorded once as `signinapproval-expire` (#1532). */
+    private expirePending;
     private sweepPending;
     /**
      * Start enrolling the account's email address as a second factor (#1523).
@@ -1265,25 +1382,26 @@ declare class AuthManager extends BaseManager {
     isEnabled(providerId: string): boolean;
     /** Returns all registered providers (for admin UI). */
     getProviders(): AuthProvider[];
-    /**
-     * The provider list, and the credentials store (#1876): passkeys, TOTP,
-     * verified email and phone, devices, linked identities and proxy grants,
-     * as its own file beside the document, __always encrypted under
-     * `NGDPBASE_BACKUP_KEY`__ (`<stem>.credentials.tar.enc`). Without the key the
-     * store is left out and the backup is reported incomplete; it is never in a
-     * backup unencrypted. The rows stay signed with `NGDPBASE_CREDENTIALS_KEY`,
-     * which is not in the backup: a site restored under another credentials key
-     * holds them in quarantine (#1633).
-     */
-    backup(options?: ManagerBackupOptions): Promise<BackupData>;
-    /**
-     * Stage the credentials store from a backup for the next start, with the
-     * rest of a site restore (#1876). A backup that left it out (no backup key
-     * when it was taken) stages nothing: the store on the site stays, and the
-     * restore's notification names it as not restored.
-     */
-    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
-    /** Staged for the next start with the rest of a site restore (#1876). */
-    restoreIsStaged(): boolean;
+    /** `ngdpbase.auth.credentials.file`, resolved: the credentials store. */
+    private configuredCredentialsFile;
+    /**
+     * The provider list. The credentials store (#1876) — passkeys, TOTP,
+     * verified email and phone, devices, linked identities and proxy grants —
+     * is a declared file (`backupFolders`), which BackupManager writes beside
+     * the document as `data.credentials`.
+     */
+    backup(): Promise<BackupData>;
+    /**
+     * The credentials store, as its own file beside the backup document,
+     * __always encrypted under `NGDPBASE_BACKUP_KEY`__
+     * (`<stem>.credentials.tar.enc`; #1876, declared since #1985). Without the
+     * key it is left out and the backup is reported incomplete; it is never in
+     * a backup unencrypted. A backup that left it out stages nothing: the store
+     * on the site stays, and the restore's notification names it as not
+     * restored. The rows stay signed with `NGDPBASE_CREDENTIALS_KEY`, which is
+     * not in the backup: a site restored under another credentials key holds
+     * them in quarantine (#1633).
+     */
+    backupFolders(): BackupFolder[];
 }
 export default AuthManager;

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

@@ -1,4 +1,4 @@
-import BaseManager, { type BackupData, type ManagerBackupOptions, type ManagerRestoreOptions } from './BaseManager.js';
+import BaseManager, { type BackupData, type BackupFolder } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import { type JobContext } from '../context/JobContext.js';
 import { type ScheduleInput } from '../utils/schedule.js';
@@ -432,21 +432,31 @@ declare class BackgroundJobManager extends BaseManager {
      */
     private settleAfterRestore;
     /**
-     * Job state in a backup (#1876). Files (`ngdpbase.jobs.state.dir`): the
-     * state, run history and checkpoints as `<stem>.jobs.tar` beside the
-     * document, without the slot locks, which belong to the server that holds
-     * them. In the database: nothing here — it is in the database backup.
+     * Where job state is kept in files, before this manager has started
+     * (#1985): null when it is in the database, held for an unavailable
+     * database, or a test's own provider. After the start, `stateDir`.
      */
-    backup(options?: ManagerBackupOptions): Promise<BackupData>;
-    /** File job state is staged for the next start with the rest of a site restore (#1876). Database job state comes back with the database. */
-    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+    private configuredFileStateDir;
+    /**
+     * File job state (`ngdpbase.jobs.state.dir`) is a declared folder (#1876,
+     * #1985): the state, run history and checkpoints as `<stem>.jobs.tar`
+     * beside the document, without the slot locks, which belong to the server
+     * that holds them. A backup without it (its job state was in the database)
+     * stages nothing for it. Job state in the database is in the database
+     * backup, and comes back with it.
+     */
+    backupFolders(): BackupFolder[];
+    /** Where job state is when it is not a declared folder: the database, or nowhere while held (#1876). */
+    backup(): Promise<BackupData>;
+    /** Database job state comes back with the database; file job state is a declared folder BackupManager stages (#1876, #1985). */
     restoreIsStaged(): boolean;
     /**
-     * Put staged file job state in place, at start, before it is opened
-     * (#1876). The runs in the live state since the backup was taken are read
-     * first, before it is replaced, for the restore's notification.
+     * Whether file job state was put back from a backup at this start (#1876):
+     * BaseManager applied it before this manager opened it (#1985). The runs
+     * in the state it replaced, started since the backup, are read from where
+     * it was kept, for the restore's notification.
      */
-    private applyRestoreAtStart;
+    private noteRestoreAtStart;
     /**
      * The job runs the live application database held, since the backup, when
      * this start's restore replaced it (#1876): read from the copy DatabaseManager