@jwilleke/ngdpbase-types 5.40.0 → 5.41.0

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.0",
   "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",