@jwilleke/ngdpbase-types 5.40.0 → 5.41.1

package/lib/src/utils/fileMigrationPlan.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The files migration dry run (#1859, epic #1851): what copying today's
+ * attachments into files WOULD do, worked out from the door's inventory
+ * (`FileManager.inventory`). Pure: it reads nothing and writes nothing.
+ *
+ * The rules are the decision log's
+ * (https://github.com/jwilleke/ngdpbase/issues/1851#issuecomment-6236003946):
+ * - two different files with the same name in one place get a numeric
+ *   suffix, `report.pdf` and `report-001.pdf`;
+ * - each page that shows a renamed file is rewritten to its new name, so it
+ *   keeps showing its own file;
+ * - an unknown or invalid uploader gets an owner from configuration.
+ */
+import type { FileInventory, FileRecord, VaultFileSummary } from '../types/File.js';
+/** The configured values the plan applies (`ngdpbase.files.migration.*`). */
+export interface FileMigrationOptions {
+    /** Recorded uploader → username, applied first (`owner-map`). */
+    ownerMap: Record<string, string>;
+    /** Owner for a file whose record names no user (`default-owner`). */
+    defaultOwner: string;
+    /** Width of the clash suffix: 3 gives `-001` (`clash-suffix-digits`). */
+    suffixDigits: number;
+}
+/** A file the migration would give a new name, and the pages it would rewrite to it. */
+export interface PlannedRename {
+    id: string;
+    from: string;
+    to: string;
+    pages: string[];
+}
+/** Who a group of public files would belong to after the migration. */
+export interface PlannedOwner {
+    /** The uploader the record names, or `null` when it names none. */
+    recorded: string | null;
+    owner: string;
+    /** `kept`: the record names a user; `mapped`: `owner-map`; `default`: `default-owner`. */
+    how: 'kept' | 'mapped' | 'default';
+    files: number;
+}
+export interface FileMigrationReport {
+    publicFiles: {
+        count: number;
+        bytes: number;
+        byType: Array<{
+            type: string;
+            files: number;
+        }>;
+    };
+    owners: PlannedOwner[];
+    /** Public files whose record names no user (before the owner mapping). */
+    noOwner: number;
+    /** Each clashing name, with the renames it would get. */
+    clashes: Array<{
+        name: string;
+        files: number;
+        renames: PlannedRename[];
+    }>;
+    /** Each page that would be rewritten, and to which names. */
+    pagesToRewrite: Array<{
+        page: string;
+        changes: Array<{
+            from: string;
+            to: string;
+        }>;
+    }>;
+    vaults: VaultFileSummary[];
+}
+/** The `-###` name a clash gets: before the extension, `route.png` → `route-001.png`. */
+export declare function suffixedName(name: string, n: number, digits: number): string;
+/**
+ * The new name of every file in one place that shares its name with another
+ * (id → new name). The oldest keeps the name (then the lowest id, so the
+ * answer is the same on every run); the rest are numbered from 1 in that
+ * order, skipping any name already used in the place. Names match exactly,
+ * as a link finds a file today.
+ */
+export declare function planClashRenames(files: ReadonlyArray<Pick<FileRecord, 'id' | 'filename' | 'dateCreated'>>, digits: number): Map<string, string>;
+/** What the migration would do with this inventory. */
+export declare function planFileMigration(inventory: FileInventory, opts: FileMigrationOptions): FileMigrationReport;
+/** The report as the operator reads it. */
+export declare function formatFileMigrationReport(r: FileMigrationReport, header?: string[]): string;

package/lib/src/utils/mediaFolderOverlap.d.ts

@@ -0,0 +1,50 @@
+/** One place private files are kept, and what to call it in a message. */
+export interface PrivateStorageRoot {
+    label: string;
+    path: string;
+}
+/** How a media folder overlaps a root: it is the root, holds it, or is inside it. */
+export type OverlapRelation = 'equals' | 'contains' | 'is inside';
+export interface MediaFolderOverlap {
+    folder: string;
+    /** 1-based position of the folder in `ngdpbase.media.folders`. */
+    position: number;
+    root: PrivateStorageRoot;
+    relation: OverlapRelation;
+}
+/** Minimal configuration surface, so tests need no live engine. */
+export interface StorageRootConfig {
+    getProperty(key: string, defaultValue: unknown): unknown;
+    getResolvedDataPath(key: string, defaultValue: string): string;
+}
+/**
+ * Where private files live: the vaults (shared folders' pages and files are
+ * the `shared-folders` container's vault, so they are in here), the legacy
+ * `private/` root a site may not have moved yet, the shared folders' key
+ * storage, and two places in attachment storage: the old private attachments
+ * the migration leaves behind and reads as a fallback, and the thumbnail cache,
+ * which holds thumbnails of vault images. Attachment paths are the ones
+ * BasicAttachmentProvider resolves.
+ */
+export declare function privateStorageRoots(config: StorageRootConfig): PrivateStorageRoot[];
+/**
+ * The real path of `p`, or of its nearest existing ancestor with the rest
+ * appended. `p` is not normalized first: `link/..` is the parent of where
+ * `link` points, not the directory holding `link` (#2195).
+ */
+export declare function realPathOf(p: string): string;
+/** Whether `child` is `parent` or under it; both already real paths. */
+export declare function isSameOrUnder(child: string, parent: string): boolean;
+/** How `folder` overlaps `root`, or null for no overlap. */
+export declare function overlapRelation(folder: string, root: string): OverlapRelation | null;
+/** The first private storage root `folder` overlaps, or null. */
+export declare function findMediaFolderOverlap(folder: string, roots: PrivateStorageRoot[], position?: number): MediaFolderOverlap | null;
+/** Each of `folders` that overlaps a root, with its position in the list. */
+export declare function findMediaFolderOverlaps(folders: string[], roots: PrivateStorageRoot[]): MediaFolderOverlap[];
+/**
+ * The message for a refused folder. It names the folder by its position and
+ * the kind of storage. It never echoes the folder: one inside a vault would
+ * name the vault's owner and id, and the message reaches admin notices and
+ * their email.
+ */
+export declare function describeMediaFolderOverlap(o: MediaFolderOverlap): string;

package/lib/src/utils/privateStoreAccess.d.ts

@@ -38,6 +38,16 @@ export interface VaultDecider {
         permit: boolean;
     }>;
 }
+/** The PDP surface {@link holdsInVault} needs. */
+export interface VaultHolder {
+    holds(subject: unknown, action: string, on: {
+        resource: {
+            type: string;
+            id: string;
+        };
+        attributes: Record<string, unknown>;
+    }): Promise<boolean>;
+}
 export declare function mayActInPrivateContainer(ctx: ActorContext, owner: string, opts?: {
     vault?: string;
 }): boolean;
@@ -59,3 +69,14 @@ export declare function permitsInVault(pdp: VaultDecider | null | undefined, ctx
     vault: string;
     resource: string;
 }): Promise<boolean>;
+/**
+ * Does `ctx` HOLD `action` inside `owner`'s vault (#2120)? {@link permitsInVault}
+ * without the step-up rule, for an affordance, and to tell a refusal for a
+ * stale sign-in (answered with the step-up prompt) from a plain one. Shared
+ * folders are not asked: `permitsInVault` decides them by permission alone.
+ */
+export declare function holdsInVault(pdp: VaultHolder | null | undefined, ctx: ActorContext, action: string, where: {
+    owner: string;
+    vault: string;
+    resource: string;
+}): Promise<boolean>;

package/lib/src/utils/privateStoreAccess.js

@@ -71,3 +71,14 @@ export async function permitsInVault(pdp, ctx, action, where) {
         return false;
     return (await pdp.decide(ctx, { action, resource: { type: 'page', id: where.resource }, attributes: { vault: where.vault } })).permit;
 }
+/**
+ * Does `ctx` HOLD `action` inside `owner`'s vault (#2120)? {@link permitsInVault}
+ * without the step-up rule, for an affordance, and to tell a refusal for a
+ * stale sign-in (answered with the step-up prompt) from a plain one. Shared
+ * folders are not asked: `permitsInVault` decides them by permission alone.
+ */
+export async function holdsInVault(pdp, ctx, action, where) {
+    if (isSharedFolderOwner(where.owner) || typeof pdp?.holds !== 'function' || !mayActInPrivateContainer(ctx, where.owner, { vault: where.vault }))
+        return false;
+    return pdp.holds(ctx, action, { resource: { type: 'page', id: where.resource }, attributes: { vault: where.vault } });
+}

package/lib/src/utils/privateStoreImport.d.ts

@@ -46,13 +46,3 @@ export type ParsedTakeout = {
 };
 /** What a takeout's entries hold. */
 export declare function readTakeout(entries: readonly ZipEntry[]): ParsedTakeout;
-/** `body` with every `/attachments/{old}` link pointed at its new id. */
-export declare function rewriteAttachmentLinks(body: string, ids: ReadonlyMap<string, string>): string;
-/** Whether `body` links to the file `id`. */
-export declare function linksToAttachment(body: string, id: string): boolean;
-/**
- * The first free title of `title`, `title (imported)`, `title (imported 2)` …
- * (operator, 2026-09-25): a DIFFERENT page already holding the title keeps it,
- * and the import lands beside it.
- */
-export declare function freeImportTitle(title: string, isTaken: (candidate: string) => Promise<boolean>): Promise<string>;

package/lib/src/utils/privateStorePath.d.ts

@@ -168,6 +168,18 @@ export declare function formatPrivatePageName(owner: string, store: string, titl
  * {@link SHARED_FOLDER_OWNER}'s; `vaults/shared-folders/…` is not a name.
  */
 export declare function parsePrivatePageName(name: unknown): PrivatePageName | null;
+/**
+ * A page's name for a log line (#1461, #2118, #2178): a private page's title
+ * stays out of logs, so it goes by its uuid, from its `metadata` — with its
+ * owner and store when its name holds them, and as "uuid unknown" before it
+ * has one. A private page saved under its bare title (#1520) is known only by
+ * its `metadata`. A public page goes by its name, and its uuid when known.
+ * The audit record is not a log line: it keeps the page's name.
+ */
+export declare function nameForLog(pageName: string, metadata?: {
+    private?: unknown;
+    uuid?: unknown;
+} | null): string;
 /**
  * The name a page an identifier opened is known by: its title — the
  * identifier may be a uuid or slug, and every downstream index is keyed by

package/lib/src/utils/privateStorePath.js

@@ -252,6 +252,24 @@ export function parsePrivatePageName(name) {
         return null;
     return { owner, store, title };
 }
+/**
+ * A page's name for a log line (#1461, #2118, #2178): a private page's title
+ * stays out of logs, so it goes by its uuid, from its `metadata` — with its
+ * owner and store when its name holds them, and as "uuid unknown" before it
+ * has one. A private page saved under its bare title (#1520) is known only by
+ * its `metadata`. A public page goes by its name, and its uuid when known.
+ * The audit record is not a log line: it keeps the page's name.
+ */
+export function nameForLog(pageName, metadata) {
+    const uuid = typeof metadata?.uuid === 'string' && metadata.uuid ? metadata.uuid : null;
+    const byUuid = `(uuid ${uuid ?? 'unknown'})`;
+    const vault = parsePrivatePageName(pageName);
+    if (vault)
+        return `a page in ${vault.owner}'s store '${vault.store}' ${byUuid}`;
+    if (metadata?.private === true)
+        return `a private page ${byUuid}`;
+    return uuid ? `'${pageName}' ${byUuid}` : `'${pageName}'`;
+}
 /**
  * The name a page an identifier opened is known by: its title — the
  * identifier may be a uuid or slug, and every downstream index is keyed by

package/lib/src/utils/recoveryWordsFile.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Recovery words to keep (#2144): the sheet an admin or a user downloads as a
+ * file or prints while their new words still wait to be confirmed, and the
+ * audit record of handing them out.
+ *
+ * One sheet for both sets of words: the shared folders' (SharedFolderManager)
+ * and a user's vault key (the store door, `privateStoreDoor.ts`). The words
+ * come only from the set still held for confirmation; once confirmed they are
+ * gone from the server and cannot be made again, so nothing here stores,
+ * caches or logs them. No key material is on the sheet.
+ */
+import { type ActorContext } from '../context/ActorContext.js';
+import { type AuditEventSink } from './auditEvents.js';
+/** Whose words: the organization's shared folders', or a user's vault key. */
+export type RecoveryWordsSet = 'shared-folders' | 'store';
+/** How they left the page: a plain text file, or the print view. */
+export type RecoveryWordsExport = 'download' | 'print';
+/** Everything the sheet shows, for the text file and the print view alike. */
+export interface RecoveryWordsSheet {
+    title: string;
+    siteName: string;
+    siteUrl: string;
+    /** When the words were made, in the server's local time with its offset. */
+    made: string;
+    words: readonly string[];
+    purpose: string;
+    notStored: string;
+}
+/** `date` in the server's local time: `2026-10-30 05:28 (UTC-04:00)`. */
+export declare function serverLocalTime(date: Date): string;
+/** The sheet for `words` of `set`, made at `madeAt`, on the site named `siteName` at `siteUrl`. */
+export declare function recoveryWordsSheet(args: {
+    set: RecoveryWordsSet;
+    siteName: string;
+    siteUrl: string;
+    words: readonly string[];
+    madeAt: Date;
+}): RecoveryWordsSheet;
+/** The sheet as a plain text file: the site, when made, the numbered words, what they are for. */
+export declare function recoveryWordsText(sheet: RecoveryWordsSheet): string;
+/** The file name: the site's name and whose words, safe for any file system. */
+export declare function recoveryWordsFilename(siteName: string, set: RecoveryWordsSet): string;
+/**
+ * Record that `ctx` downloaded or opened to print the set `wordsId` of `set`
+ * (`recovery-words-export`, on-failure refuse): called before the words are
+ * sent, so a record that cannot be written sends nothing. Who, which set and
+ * how; never the words.
+ */
+export declare function recordRecoveryWordsExport(sink: AuditEventSink | null | undefined, ctx: ActorContext, what: {
+    set: RecoveryWordsSet;
+    wordsId: string;
+    how: RecoveryWordsExport;
+    store?: string;
+}): Promise<void>;

package/lib/src/utils/sessionEnd.d.ts

@@ -2,6 +2,7 @@ export type SessionEndReason = 'logout' | 'idle-timeout' | 'max-age' | 'password
 export declare function endSession(engine: {
     getManager(name: string): unknown;
 }, session: {
+    id?: unknown;
     username?: unknown;
     privateStoreHandle?: unknown;
     pendingConnection?: unknown;

package/lib/src/utils/sessionEnd.js

@@ -10,6 +10,7 @@
  * - the end is recorded as `authentication-logout`, with who, from where and
  *   why (#1670). Until this, only the idle timeout was recorded.
  * - a choice to act for someone (`actingFor`, #1762) ends with it.
+ * - so do the form POSTs it kept for a fresh sign-in (#2176), by its `id`.
  *
  * An account deleted or turned off ends its sessions here too (#1937), with
  * the reason `account-deleted` / `account-disabled`: on the session's next
@@ -30,6 +31,9 @@ export function endSession(engine, session, reason, from) {
     // #1762 slice 4: nor does a choice to act for someone.
     if (session)
         delete session.actingFor;
+    // #2176: nor do the form POSTs it kept for a fresh sign-in.
+    if (typeof session?.id === 'string')
+        engine.getManager('AuthManager')?.dropStepUpReplays?.(session.id);
     const username = typeof session?.username === 'string' && session.username ? session.username : null;
     if (!username)
         return; // nobody was signed in: nothing ended

package/lib/src/utils/sessionIdle.d.ts

@@ -39,3 +39,7 @@ export declare function warnBeforeMs(timeoutMs: number): number;
 export declare function idleRemainingMs(lastActivity: unknown, now: number, timeoutMs: number): number | null;
 /** The status poll does not count as activity, or the warning would keep the session alive by itself. */
 export declare const IDLE_STATUS_PATH = "/api/session/idle-status";
+/** #2193: nor does a page's poll for its step-up prompt, or a page left waiting would keep its session alive. */
+export declare const STEP_UP_STATUS_PATH = "/auth/reauth/status";
+/** Whether a request to `path` counts as the person's activity: every one but the polls above. */
+export declare function countsAsActivity(path: string): boolean;

package/lib/src/utils/sessionIdle.js

@@ -64,3 +64,9 @@ export function idleRemainingMs(lastActivity, now, timeoutMs) {
 }
 /** The status poll does not count as activity, or the warning would keep the session alive by itself. */
 export const IDLE_STATUS_PATH = '/api/session/idle-status';
+/** #2193: nor does a page's poll for its step-up prompt, or a page left waiting would keep its session alive. */
+export const STEP_UP_STATUS_PATH = '/auth/reauth/status';
+/** Whether a request to `path` counts as the person's activity: every one but the polls above. */
+export function countsAsActivity(path) {
+    return path !== IDLE_STATUS_PATH && path !== STEP_UP_STATUS_PATH;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.40.0",
+  "version": "5.41.1",
   "description": "TypeScript types for ngdpbase add-ons, and a test kit of core's own values. A dev dependency, versioned with ngdpbase.",
   "license": "Apache-2.0",
   "author": "Jim Willeke",

package/lib/src/providers/mediaFilenameDate.d.ts

@@ -1,22 +0,0 @@
-/**
- * Conservative filename → capture-date parser (#809, slice C of #807).
- *
- * Last-resort fallback used by media providers when a file carries no usable
- * EXIF/QuickTime capture date. Many devices encode the capture time in the
- * filename (e.g. `PXL_20260113_123414708.jpg`, `2026-04-03-IMG_4654.jpg`,
- * `Feb_20_2026_19_25_04.jpg`); without this, those files index with
- * `dateTimeOriginal: null` and sort only by file `mtime`.
- *
- * Design constraints (from the issue):
- *   - **Conservative** — only a small set of high-confidence, anchored patterns
- *     are accepted. Anything ambiguous returns `null`, and the caller then
- *     falls back to `mtime` and surfaces the file to admins.
- *   - **Distinguishable provenance** — the caller records that the resulting
- *     date came from the filename (`captureDateSource: 'filename'`), so a
- *     parsed date never masquerades as authoritative EXIF metadata.
- *
- * Returns a `"YYYY-MM-DD HH:MM:SS"` string (the exact shape produced by the
- * EXIF extractor, so it flows through sort/filter identically), or `null`.
- * A date-only match yields a `00:00:00` time.
- */
-export declare function parseDateFromFilename(filename: string): string | null;