@jwilleke/ngdpbase-types 5.40.0 → 5.41.0

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

@@ -6,12 +6,14 @@ import { type ActorContext } from '../context/ActorContext.js';
  * failed" (#1183). A caller refusing a destructive action needs to say which.
  */
 export declare const AUDIT_WRITE_FAILED = "EAUDITWRITE";
+import type { AttachmentDetail } from '../utils/auditEvents.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { CatalogSource, CatalogQuery, CatalogPage, CreativeWork, SchemaType, RebuildOpts } from '../types/Schema.js';
 import type { User } from '../providers/BaseAttachmentProvider.js';
 import { type AssetQuery, type AssetRecord } from '../types/Asset.js';
 import type { StoreFileEntry, StoreFileInput, StoreFileLocation } from '../types/Provider.js';
 import type { OriginalKeep } from '../ice/types.js';
+import type { FilePlace } from '../types/File.js';
 /**
  * Base attachment provider interface
  */
@@ -82,23 +84,24 @@ export interface FileInfo {
     mimeType: string;
     size: number;
 }
+/** A file handed to the write door (#2148): its bytes, and what the uploader said about them. */
+export interface PutFile {
+    bytes: Buffer;
+    info: FileInfo;
+}
 /**
- * Upload options interface
+ * What else a write carries (#2148). None of it decides where the file goes:
+ * that is the place the caller passed to `FileManager.put`.
  */
-export interface UploadOptions {
+export interface PutOptions {
+    /**
+     * The page that shows the file, recorded as a mention (and on the audit
+     * record of an unsealed place). Never the place: a page only links to a file.
+     */
     pageName?: string;
     description?: string;
     /** WikiContext for the current request — audit IP fallback */
     wikiContext?: import('../context/WikiContext.js').default;
-    /**
-     * Private-store destination (#1396): the upload dialog's checkbox. Decides
-     * only when `pageName` is not a private page — an upload onto a private page
-     * is always private, in that page's author's store (#1398). Absent or false
-     * otherwise keeps the public attachments pool.
-     */
-    private?: boolean;
-    /** Store id when private with no private page; default from ConfigurationManager defaultstoreid */
-    store?: string;
     /**
      * An import's keep at upload (#2061): the `OriginalKeep` the engine handed
      * the receiver's `keepOriginal`, passed on unchanged. Honoured only while
@@ -115,6 +118,31 @@ export interface UploadOptions {
      */
     importedFrom?: string;
 }
+/**
+ * The page-tied upload's options (#1396, #1398): today's callers name the page
+ * they upload onto and the dialog's Private tick, and FileManager turns that
+ * into a place (`placeForPageUpload`) until #2149/#2150 move them to a place
+ * the user chose.
+ */
+/**
+ * What storage hands back to FileManager (#2149): the stored file's metadata,
+ * and what the upload's audit record says about it, which FileManager records.
+ */
+export interface StoredInPlace {
+    metadata: AttachmentMetadata;
+    record: AttachmentDetail;
+}
+export interface UploadOptions extends PutOptions {
+    /**
+     * Private-store destination (#1396): the upload dialog's checkbox. Decides
+     * only when `pageName` is not a private page — an upload onto a private page
+     * is always private, in that page's author's store (#1398). Absent or false
+     * otherwise keeps the public attachments pool.
+     */
+    private?: boolean;
+    /** Store id when private with no private page; default from ConfigurationManager defaultstoreid */
+    store?: string;
+}
 /**
  * Mention object (WebPage reference)
  */
@@ -304,19 +332,39 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
      */
     private writeAttachments;
     /**
-     * Upload an attachment
+     * Upload a file onto a page: the page-tied path its current callers use
+     * (the editor's upload route, imports, NCM image localization, thumbnails).
+     *
+     * #2148: this decides nothing. Where the file goes is FileManager's
+     * (`placeForPageUpload`, kept until #2149/#2150 move these callers to a
+     * place the user chose), and the write is FileManager's one door, `put`,
+     * which asks the permission for that place and then has this manager store
+     * it ({@link storeInPlace}). One write path, not two.
      *
-     * @param {Buffer} fileBuffer - File data
-     * @param {FileInfo} fileInfo - { originalName, mimeType, size }
-     * @param {UploadOptions} options - Upload options
-     * @param {string} options.pageName - Page uploaded onto (optional). A private page forces the upload private, into its author's store (#1398)
-     * @param {string} options.description - File description
-     * @param {boolean} options.private - Private-store destination for an upload with no private page (#1396)
-     * @param {string} options.store - Store id when private with no private page; else ConfigurationManager defaultstoreid
+     * @param fileBuffer - File data
+     * @param fileInfo - { originalName, mimeType, size }
      * @param ctx - Who is uploading (#1179): the request's subject, or a JobContext for an in-engine caller. Mandatory and positional.
-     * @returns {Promise<AttachmentMetadata>} Attachment metadata
+     * @param options - The page it is uploaded onto, the private tick and store, description, keep, importedFrom
+     * @returns Attachment metadata
      */
     uploadAttachment(fileBuffer: Buffer, fileInfo: FileInfo, ctx: ActorContext, options?: UploadOptions): Promise<AttachmentMetadata>;
+    /** The owner of files (#2148, #2149): every upload goes through its door, and it writes every upload and delete record. */
+    private fileManager;
+    /**
+     * Store a file in `place` (#2148): the storage underneath FileManager's
+     * door. Only `FileManager.put` calls this, after it has asked the
+     * permission for the place; nothing here decides where a file goes or who
+     * may put it there.
+     *
+     * What it does, as the place requires: the type read from the bytes
+     * (#1624); the uploader recorded by identity @id, and nobody uploads
+     * anonymously (#1926, #2097); a vault or shared folder keeps the file in its
+     * own store, sealed when the store is (#1460, #1394); and an import's kept
+     * original honoured only in its user's own vault (#2061). It records
+     * nothing (#2149): it returns what the upload's audit record says (a sealed
+     * store's file by id only, #2048), and FileManager, the owner, records it.
+     */
+    storeInPlace(ctx: ActorContext, place: FilePlace, file: PutFile, options?: PutOptions): Promise<StoredInPlace>;
     /**
      * The username an upload is recorded under (#1926): the person the context
      * names. Asked after policy has allowed the upload and before anything is
@@ -354,8 +402,12 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
      */
     private userReference;
     private static uploaderOf;
-    /** A file is added to a private page only by someone who may edit it: the page's own decision (#1398). */
-    private assertMayEditPage;
+    /**
+     * A file is added to a private page only by someone who may edit it: the
+     * page's own decision (#1398). Asked here by `attachToPage`, and by
+     * FileManager's page-tied upload (#2148).
+     */
+    assertMayEditPage(ctx: ActorContext, pageName: string): Promise<void>;
     /**
      * One vault as a provider location, opened through `ctx` (#1842). Throws as
      * `storeFileIO` does: a locked vault, or a sealed kind's vault not yet opened.
@@ -428,9 +480,10 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
     /**
      * May `ctx` do `permission` to `what` in `owner`'s vault `store` (#1539)?
      * The container rule, then the capability asked with the vault, so
-     * `vault-owner` decides — the same rule as a vault page.
+     * `vault-owner` decides — the same rule as a vault page. FileManager's
+     * write door asks it for a vault (#2148), so the rule has one home.
      */
-    private mayInVault;
+    mayInVault(ctx: ActorContext, permission: string, owner: string, store: string, what: string): Promise<boolean>;
     /** The requester's own store file and its entry, before the capability is asked — see {@link findOwnStoreFile}. */
     private locateOwnStoreFile;
     /**
@@ -487,6 +540,15 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
      * differently without reading it twice (#1460).
      */
     isOwnPrivateStoreFile(attachmentId: string, ctx: ActorContext): Promise<boolean>;
+    /**
+     * The files the requester's own store `store` holds, as fingerprint → id,
+     * or null when this context cannot open it (#2171). The store's own
+     * duplicate check (its index's fingerprints), read without storing or
+     * recording anything: a takeout import reads it once per run and asks it
+     * before putting a file again, so a file deleted since comes back and one
+     * still held writes no second upload record. Only that store is opened.
+     */
+    ownStoreFingerprints(ctx: ActorContext, store: string): Promise<Map<string, string> | null>;
     /** The requester's own private-store files uploaded onto `pageName`. */
     getPrivateStoreAttachmentsForPage(pageName: string, ctx: ActorContext): Promise<AttachmentMetadata[]>;
     /**
@@ -839,18 +901,6 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
             ip?: string;
         } | null;
     }): Promise<boolean>;
-    /**
-     * Emit an attachment audit event from the manager that owns the resource.
-     *
-     * `docs/audit-posture.md` states the rule this implements: an action is
-     * "emitted through `recordAuditEvent` (or the manager door that calls it)".
-     * The door is here. Placing it at a route means every future caller has to
-     * remember, which is the thing #1120 exists to end — being audited must not
-     * depend on a producer recalling a method.
-     *
-     * `critical` decides whether a failure to record stops the action.
-     */
-    private recordAttachmentEvent;
     /** #1204: an attachment's metadata changed; field NAMES only, at the door both edit paths pass through. */
     private recordAssetEdit;
     /**

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

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