@jwilleke/ngdpbase-types 5.39.0 → 5.41.0

package/lib/src/types/guards.js

@@ -0,0 +1,366 @@
+/**
+ * Type guards for runtime type checking
+ *
+ * This module provides type guard functions that can be used to validate
+ * data structures at runtime and provide TypeScript type narrowing.
+ */
+/**
+ * Check if value is a valid PageFrontmatter object
+ */
+export function isPageFrontmatter(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const obj = value;
+    // Required fields
+    if (typeof obj.title !== 'string' || !obj.title) {
+        return false;
+    }
+    if (typeof obj.uuid !== 'string' || !obj.uuid) {
+        return false;
+    }
+    if (typeof obj.lastModified !== 'string' || !obj.lastModified) {
+        return false;
+    }
+    // Optional fields with type checks
+    if (obj['system-category'] !== undefined && typeof obj['system-category'] !== 'string') {
+        return false;
+    }
+    if (obj.category !== undefined && typeof obj.category !== 'string') {
+        return false;
+    }
+    if (obj['user-keywords'] !== undefined && !Array.isArray(obj['user-keywords'])) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Check if value is a valid WikiPage object
+ */
+export function isWikiPage(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const obj = value;
+    if (typeof obj.title !== 'string' || !obj.title) {
+        return false;
+    }
+    if (typeof obj.uuid !== 'string' || !obj.uuid) {
+        return false;
+    }
+    if (typeof obj.content !== 'string') {
+        return false;
+    }
+    if (!isPageFrontmatter(obj.metadata)) {
+        return false;
+    }
+    if (typeof obj.filePath !== 'string' || !obj.filePath) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Check if value is a valid PageInfo object
+ */
+export function isPageInfo(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const obj = value;
+    if (typeof obj.title !== 'string' || !obj.title) {
+        return false;
+    }
+    if (typeof obj.uuid !== 'string' || !obj.uuid) {
+        return false;
+    }
+    if (typeof obj.filePath !== 'string' || !obj.filePath) {
+        return false;
+    }
+    if (!isPageFrontmatter(obj.metadata)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Check if value is a valid VersionMetadata object
+ */
+export function isVersionMetadata(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const obj = value;
+    if (typeof obj.version !== 'number' || obj.version < 1) {
+        return false;
+    }
+    if (typeof obj.author !== 'string' || !obj.author) {
+        return false;
+    }
+    if (typeof obj.timestamp !== 'string' || !obj.timestamp) {
+        return false;
+    }
+    const validChangeTypes = ['create', 'update', 'minor', 'major'];
+    if (typeof obj.changeType !== 'string' || !validChangeTypes.includes(obj.changeType)) {
+        return false;
+    }
+    if (typeof obj.contentHash !== 'string' || !obj.contentHash) {
+        return false;
+    }
+    if (typeof obj.contentSize !== 'number' || obj.contentSize < 0) {
+        return false;
+    }
+    if (typeof obj.compressed !== 'boolean') {
+        return false;
+    }
+    if (typeof obj.isDelta !== 'boolean') {
+        return false;
+    }
+    return true;
+}
+/**
+ * Check if value is a valid VersionManifest object
+ */
+export function isVersionManifest(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const obj = value;
+    if (typeof obj.pageUuid !== 'string' || !obj.pageUuid) {
+        return false;
+    }
+    if (typeof obj.pageTitle !== 'string' || !obj.pageTitle) {
+        return false;
+    }
+    if (typeof obj.totalVersions !== 'number' || obj.totalVersions < 0) {
+        return false;
+    }
+    if (typeof obj.currentVersion !== 'number' || obj.currentVersion < 1) {
+        return false;
+    }
+    if (!Array.isArray(obj.versions)) {
+        return false;
+    }
+    // Validate each version metadata
+    for (const version of obj.versions) {
+        if (!isVersionMetadata(version)) {
+            return false;
+        }
+    }
+    if (typeof obj.createdAt !== 'string' || !obj.createdAt) {
+        return false;
+    }
+    if (typeof obj.updatedAt !== 'string' || !obj.updatedAt) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Check if value is a valid User object
+ */
+export function isUser(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const obj = value;
+    if (typeof obj.username !== 'string' || !obj.username) {
+        return false;
+    }
+    if (typeof obj.email !== 'string' || !obj.email) {
+        return false;
+    }
+    if (typeof obj.displayName !== 'string' || !obj.displayName) {
+        return false;
+    }
+    if (typeof obj.password !== 'string' || !obj.password) {
+        return false;
+    }
+    // `roles` is deprecated since #617 iteration 3b — RoleManager owns
+    // OrganizationRole records canonically. Accept users without the field;
+    // when present, accept any array shape (legacy files).
+    if (obj.roles !== undefined && !Array.isArray(obj.roles)) {
+        return false;
+    }
+    if (typeof obj.isActive !== 'boolean') {
+        return false;
+    }
+    if (typeof obj.isSystem !== 'boolean') {
+        return false;
+    }
+    if (typeof obj.isExternal !== 'boolean') {
+        return false;
+    }
+    if (typeof obj.createdAt !== 'string' || !obj.createdAt) {
+        return false;
+    }
+    if (typeof obj.loginCount !== 'number' || obj.loginCount < 0) {
+        return false;
+    }
+    if (!obj.preferences || typeof obj.preferences !== 'object') {
+        return false;
+    }
+    return true;
+}
+/**
+ * Check if value is a valid UserSession object
+ */
+export function isUserSession(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const obj = value;
+    if (typeof obj.sessionId !== 'string' || !obj.sessionId) {
+        return false;
+    }
+    if (typeof obj.username !== 'string' || !obj.username) {
+        return false;
+    }
+    if (typeof obj.userId !== 'string' || !obj.userId) {
+        return false;
+    }
+    if (typeof obj.createdAt !== 'string' || !obj.createdAt) {
+        return false;
+    }
+    if (typeof obj.expiresAt !== 'string' || !obj.expiresAt) {
+        return false;
+    }
+    if (typeof obj.lastActivity !== 'string' || !obj.lastActivity) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Check if value is a valid AttachmentMetadata object
+ */
+export function isAttachmentMetadata(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const obj = value;
+    if (typeof obj.id !== 'string' || !obj.id) {
+        return false;
+    }
+    if (typeof obj.filename !== 'string' || !obj.filename) {
+        return false;
+    }
+    if (typeof obj.pageUuid !== 'string' || !obj.pageUuid) {
+        return false;
+    }
+    if (typeof obj.mimeType !== 'string' || !obj.mimeType) {
+        return false;
+    }
+    if (typeof obj.size !== 'number' || obj.size < 0) {
+        return false;
+    }
+    if (typeof obj.uploadedAt !== 'string' || !obj.uploadedAt) {
+        return false;
+    }
+    if (typeof obj.uploadedBy !== 'string' || !obj.uploadedBy) {
+        return false;
+    }
+    if (typeof obj.filePath !== 'string' || !obj.filePath) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Check if value is a valid AuditEvent object
+ */
+export function isAuditEvent(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const obj = value;
+    if (typeof obj.id !== 'string' || !obj.id) {
+        return false;
+    }
+    if (typeof obj.type !== 'string' || !obj.type) {
+        return false;
+    }
+    if (typeof obj.actor !== 'string' || !obj.actor) {
+        return false;
+    }
+    if (typeof obj.target !== 'string' || !obj.target) {
+        return false;
+    }
+    if (typeof obj.action !== 'string' || !obj.action) {
+        return false;
+    }
+    if (typeof obj.timestamp !== 'string' || !obj.timestamp) {
+        return false;
+    }
+    const validResults = ['success', 'failure'];
+    if (typeof obj.result !== 'string' || !validResults.includes(obj.result)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Check if value is a valid UUID (v4 format)
+ */
+export function isUuid(value) {
+    if (typeof value !== 'string') {
+        return false;
+    }
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    return uuidRegex.test(value);
+}
+/**
+ * Check if value is a valid ISO 8601 timestamp
+ */
+export function isIsoTimestamp(value) {
+    if (typeof value !== 'string') {
+        return false;
+    }
+    try {
+        const date = new Date(value);
+        return date.toISOString() === value;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if value is a valid email address
+ */
+export function isEmail(value) {
+    if (typeof value !== 'string') {
+        return false;
+    }
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(value);
+}
+/**
+ * Validate and assert PageFrontmatter
+ * @throws {TypeError} if validation fails
+ */
+export function assertPageFrontmatter(value) {
+    if (!isPageFrontmatter(value)) {
+        throw new TypeError('Invalid PageFrontmatter object');
+    }
+}
+/**
+ * Validate and assert WikiPage
+ * @throws {TypeError} if validation fails
+ */
+export function assertWikiPage(value) {
+    if (!isWikiPage(value)) {
+        throw new TypeError('Invalid WikiPage object');
+    }
+}
+/**
+ * Validate and assert VersionMetadata
+ * @throws {TypeError} if validation fails
+ */
+export function assertVersionMetadata(value) {
+    if (!isVersionMetadata(value)) {
+        throw new TypeError('Invalid VersionMetadata object');
+    }
+}
+/**
+ * Validate and assert User
+ * @throws {TypeError} if validation fails
+ */
+export function assertUser(value) {
+    if (!isUser(value)) {
+        throw new TypeError('Invalid User object');
+    }
+}

package/lib/src/types/linkedom.d.ts

@@ -60,6 +60,8 @@ declare module 'linkedom' {
     getElementById(id: string): LinkedomElement | null;
     querySelector(selector: string): LinkedomElement | null;
     querySelectorAll(selector: string): LinkedomElement[];
+    /** The whole document as HTML, its doctype included. */
+    toString(): string;
   }
 
   function parseHTML(html: string): { document: LinkedomDocument };

package/lib/src/utils/atomicWrite.js

@@ -0,0 +1,129 @@
+/**
+ * atomicWrite — never leave a half-written file behind (#1062).
+ *
+ * `fs.writeFile` over a live path truncates it first, so a crash, container
+ * kill, OOM, disk-full, or power loss part-way through leaves the file
+ * truncated: not the old content, not the new content. The page index and the
+ * version manifest already guarded against this with temp-then-rename; page
+ * content and version snapshots did not.
+ *
+ * That gap mattered more than it looks. #1061's argument for refusing a stale
+ * save is that the losing edit survives in version history — which is only true
+ * while the history files themselves are intact. A truncated snapshot corrupts
+ * the recovery path that the rest of the durability story leans on.
+ *
+ * ## What this guarantees, and what it does not
+ *
+ * `rename(2)` within a filesystem is atomic: a reader sees either the whole old
+ * file or the whole new one, never a mixture. Writing to a sibling temp file
+ * first means the live path is never in a partial state.
+ *
+ * Deliberately stated rather than implied:
+ *
+ * - **Same directory, always.** A rename across filesystems is not atomic — it
+ *   degrades to copy-then-unlink. Putting the temp file beside the target keeps
+ *   it on the same device by construction, including when the pages directory
+ *   is a mount of its own.
+ * - **fsync is OFF by default, deliberately.** Measured on this repo's storage:
+ *   0.13 ms/write plain, 8.62 ms/write with fsync — 65x, or about +150 seconds
+ *   across a full 18,000-page index rebuild.
+ *
+ *   What that cost buys is narrow. The failure this issue is about is a
+ *   *process* death — deploy, OOM, node eviction — and there the kernel still
+ *   flushes the page cache, so temp-then-rename alone leaves the file whole.
+ *   fsync only adds protection against power loss, kernel panic, or a host
+ *   crash, which the storage layer under a PV normally handles.
+ *
+ *   Callers that genuinely need it pass `{ fsync: true }`. Defaulting it on
+ *   would have made every bulk operation dramatically slower to buy a
+ *   guarantee against a failure mode this deployment does not face.
+ * - **This is not a lock.** Two writers still race; the loser's content is
+ *   simply overwritten whole rather than interleaved. Concurrency is #1061's
+ *   problem, not this one.
+ */
+import fs from 'fs-extra';
+import { open } from 'fs/promises';
+import path from 'path';
+import logger from './logger.js';
+/** Counter making concurrent temp names unique within a process. */
+let sequence = 0;
+/**
+ * Write `data` to `filePath` so that the path is never observed partially
+ * written.
+ *
+ * The temp file carries the pid and a per-process counter so two writers — or
+ * two processes sharing a volume — cannot collide on it and corrupt each
+ * other's staging file.
+ *
+ * @param filePath - final destination
+ * @param data     - contents to write
+ * @param encoding - defaults to utf8
+ * @param options.fsync - also flush to the device. Off by default; see the file
+ *   header for why, and for the measured cost.
+ * @param options.mode - permission bits for the file, e.g. `0o600` for a file
+ *   holding secrets (#1524, #1560). Set on the temp file before any data is
+ *   written, so the secret is never on disk with wider permissions; the rename
+ *   keeps them. Absent: the process default, as before.
+ * @param options.exclusive - create only: refuse (EEXIST) when `filePath`
+ *   already exists, instead of replacing it (#1625). The finished temp file is
+ *   published with a hard link, which fails atomically if the name is taken,
+ *   so a crash mid-write never leaves a truncated file under the real name.
+ */
+export async function writeFileAtomic(filePath, data, encoding = 'utf8', options = {}) {
+    const dir = path.dirname(filePath);
+    const tempPath = path.join(dir, `.${path.basename(filePath)}.tmp.${process.pid}.${++sequence}`);
+    let handle;
+    try {
+        await fs.ensureDir(dir);
+        handle = await open(tempPath, 'w', options.mode);
+        // open()'s mode is filtered by the umask; chmod sets it exactly.
+        if (options.mode !== undefined)
+            await handle.chmod(options.mode);
+        await handle.write(typeof data === 'string' ? Buffer.from(data, encoding) : data);
+        if (options.fsync) {
+            // Only when the caller asks: see the cost note in the file header.
+            await handle.sync();
+        }
+        await handle.close();
+        handle = undefined;
+        if (options.exclusive) {
+            await fs.link(tempPath, filePath);
+            await fs.remove(tempPath);
+        }
+        else {
+            await fs.rename(tempPath, filePath);
+        }
+        if (options.fsync)
+            await fsyncDirectory(dir);
+    }
+    catch (err) {
+        if (handle) {
+            await handle.close().catch(() => { });
+        }
+        // Leaving the temp file behind would accumulate junk beside real pages and,
+        // being dot-prefixed, would be invisible in most listings.
+        await fs.remove(tempPath).catch(() => { });
+        throw err;
+    }
+}
+/**
+ * Flush the directory entry so the rename survives a power loss.
+ *
+ * Best-effort on purpose: not every platform or filesystem permits opening a
+ * directory for fsync, and a page save must not fail because of it. A failure
+ * here narrows the guarantee to "no partial file" without weakening it.
+ */
+async function fsyncDirectory(dir) {
+    let dirHandle;
+    try {
+        dirHandle = await open(dir, 'r');
+        await dirHandle.sync();
+    }
+    catch (err) {
+        logger.debug(`[atomicWrite] Directory fsync skipped for ${dir}: ${String(err)}`);
+    }
+    finally {
+        await dirHandle?.close().catch(() => { });
+    }
+}
+export default writeFileAtomic;

package/lib/src/utils/auditEventNames.generated.d.ts

@@ -34,6 +34,8 @@ export declare const AUDIT_EVENT: {
     readonly AUTHORIZATION_DENY: "authorization-deny";
     /** A full backup written; where it went and who asked */
     readonly BACKUP_CREATE: "backup-create";
+    /** An administrator downloaded the backup key file from the backup-key page (#2134): who, and the key's fingerprint, never the key. Recorded before the file is made, which cannot proceed without it */
+    readonly BACKUP_KEY_DOWNLOAD: "backup-key-download";
     /** A restore of a backup's databases started from Admin → Backup: which backup and who asked; recorded before the fresh backup and the staging, which cannot proceed without it (#1723) */
     readonly BACKUP_RESTORE: "backup-restore";
     /** A staged restore (site or databases-only) put in place at start: which backup, when it was taken, who started the restore and which parts were applied; written into the restored audit log, so the log itself says a restore happened (#1876) */
@@ -138,6 +140,8 @@ export declare const AUDIT_EVENT: {
     readonly REAUTH_PROMPT: "reauth-prompt";
     /** Step-up: the user re-authenticated, with the factor used */
     readonly REAUTH_SUCCESS: "reauth-success";
+    /** Recovery words still waiting to be confirmed were downloaded as a file or opened to print (#2144): who, which words (the shared folders' or a user's vault key), the set's id and how, never the words. Recorded before the words are sent, which cannot proceed without it */
+    readonly RECOVERY_WORDS_EXPORT: "recovery-words-export";
     /** A request was approved and the add-on's handler carried it out (#2072): who decided, its id, kind and handler; never the note, summary or details */
     readonly REVIEW_APPROVED: "review-approved";
     /** A request was approved but the add-on's handler did not carry it out, so it stays open (#2072): who approved it, its id, kind and handler */
@@ -166,12 +170,20 @@ export declare const AUDIT_EVENT: {
     readonly SHARE_EXTEND: "share-extend";
     /** Share link revoked; pairs with token-revoke */
     readonly SHARE_REVOKE: "share-revoke";
+    /** An administrator changed who may read and who may file in a shared folder on the Shared folders screen (#2126): which folder, who, and the roles before and after for each. Recorded once the folder's policies are written; a failed write is recorded as a failure, with the error, and a record that cannot be written puts the policies back */
+    readonly SHARED_FOLDER_ACCESS_CHANGE: "shared-folder-access-change";
+    /** An administrator created a shared folder (#2125): which folder and who. Recorded before the folder is made, which cannot proceed without it */
+    readonly SHARED_FOLDER_CREATE: "shared-folder-create";
     /** A shared folder's own key was made (#2124): which folder and who, never the key. Recorded before the key is saved, which cannot proceed without it */
     readonly SHARED_FOLDER_KEY_CREATE: "shared-folder-key-create";
+    /** A shared folder's page or file was opened (#2125): who, the folder and what. On by default: every read of a shared folder is recorded (#1775) */
+    readonly SHARED_FOLDER_READ: "shared-folder-read";
     /** The organization's 12 recovery words for shared folders were made and saved (#2124): the admin who was shown them, and which set (an id, never the words). Recorded before the words are saved, which cannot proceed without it */
     readonly SHARED_FOLDER_WORDS_CREATE: "shared-folder-words-create";
     /** An administrator discarded the organization's shared-folders recovery words before the admin shown them confirmed saving them (#2124): who, which set (an id) and who it was shown to. Recorded before the words are removed, which cannot proceed without it */
     readonly SHARED_FOLDER_WORDS_DISCARD: "shared-folder-words-discard";
+    /** An administrator, with a fresh sign-in, replaced the organization's shared-folders recovery words with a new set they typed back (#2144): who, the new set and the set it replaced (ids, never the words) and how many folder keys were sealed for the new set. The old words stop opening the folders. Recorded before the new set is saved, which cannot proceed without it */
+    readonly SHARED_FOLDER_WORDS_REPLACE: "shared-folder-words-replace";
     /** Sign-in approval: the browser that was waiting gave up the sign-in (#1532) */
     readonly SIGNINAPPROVAL_ABANDON: "signinapproval-abandon";
     /** Sign-in approval: the user pressed Approve (#1532) */

package/lib/src/utils/auditEventNames.generated.js

@@ -41,6 +41,8 @@ export const AUDIT_EVENT = {
     AUTHORIZATION_DENY: 'authorization-deny',
     /** A full backup written; where it went and who asked */
     BACKUP_CREATE: 'backup-create',
+    /** An administrator downloaded the backup key file from the backup-key page (#2134): who, and the key's fingerprint, never the key. Recorded before the file is made, which cannot proceed without it */
+    BACKUP_KEY_DOWNLOAD: 'backup-key-download',
     /** A restore of a backup's databases started from Admin → Backup: which backup and who asked; recorded before the fresh backup and the staging, which cannot proceed without it (#1723) */
     BACKUP_RESTORE: 'backup-restore',
     /** A staged restore (site or databases-only) put in place at start: which backup, when it was taken, who started the restore and which parts were applied; written into the restored audit log, so the log itself says a restore happened (#1876) */
@@ -145,6 +147,8 @@ export const AUDIT_EVENT = {
     REAUTH_PROMPT: 'reauth-prompt',
     /** Step-up: the user re-authenticated, with the factor used */
     REAUTH_SUCCESS: 'reauth-success',
+    /** Recovery words still waiting to be confirmed were downloaded as a file or opened to print (#2144): who, which words (the shared folders' or a user's vault key), the set's id and how, never the words. Recorded before the words are sent, which cannot proceed without it */
+    RECOVERY_WORDS_EXPORT: 'recovery-words-export',
     /** A request was approved and the add-on's handler carried it out (#2072): who decided, its id, kind and handler; never the note, summary or details */
     REVIEW_APPROVED: 'review-approved',
     /** A request was approved but the add-on's handler did not carry it out, so it stays open (#2072): who approved it, its id, kind and handler */
@@ -173,12 +177,20 @@ export const AUDIT_EVENT = {
     SHARE_EXTEND: 'share-extend',
     /** Share link revoked; pairs with token-revoke */
     SHARE_REVOKE: 'share-revoke',
+    /** An administrator changed who may read and who may file in a shared folder on the Shared folders screen (#2126): which folder, who, and the roles before and after for each. Recorded once the folder's policies are written; a failed write is recorded as a failure, with the error, and a record that cannot be written puts the policies back */
+    SHARED_FOLDER_ACCESS_CHANGE: 'shared-folder-access-change',
+    /** An administrator created a shared folder (#2125): which folder and who. Recorded before the folder is made, which cannot proceed without it */
+    SHARED_FOLDER_CREATE: 'shared-folder-create',
     /** A shared folder's own key was made (#2124): which folder and who, never the key. Recorded before the key is saved, which cannot proceed without it */
     SHARED_FOLDER_KEY_CREATE: 'shared-folder-key-create',
+    /** A shared folder's page or file was opened (#2125): who, the folder and what. On by default: every read of a shared folder is recorded (#1775) */
+    SHARED_FOLDER_READ: 'shared-folder-read',
     /** The organization's 12 recovery words for shared folders were made and saved (#2124): the admin who was shown them, and which set (an id, never the words). Recorded before the words are saved, which cannot proceed without it */
     SHARED_FOLDER_WORDS_CREATE: 'shared-folder-words-create',
     /** An administrator discarded the organization's shared-folders recovery words before the admin shown them confirmed saving them (#2124): who, which set (an id) and who it was shown to. Recorded before the words are removed, which cannot proceed without it */
     SHARED_FOLDER_WORDS_DISCARD: 'shared-folder-words-discard',
+    /** An administrator, with a fresh sign-in, replaced the organization's shared-folders recovery words with a new set they typed back (#2144): who, the new set and the set it replaced (ids, never the words) and how many folder keys were sealed for the new set. The old words stop opening the folders. Recorded before the new set is saved, which cannot proceed without it */
+    SHARED_FOLDER_WORDS_REPLACE: 'shared-folder-words-replace',
     /** Sign-in approval: the browser that was waiting gave up the sign-in (#1532) */
     SIGNINAPPROVAL_ABANDON: 'signinapproval-abandon',
     /** Sign-in approval: the user pressed Approve (#1532) */

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

@@ -121,6 +121,8 @@ export interface PageMutationInput extends CommonInput {
         from: string;
         to: string;
     } | null;
+    /** A `create` from an import whose user gave the page another title (#2130): the file's own name. */
+    importedFrom?: string | null;
 }
 export interface TokenInput extends CommonInput {
     op: TokenOp;
@@ -151,6 +153,18 @@ export type AttachmentDetail = {
     filename: string;
     pageName?: string | null;
     sizeBytes?: number | null;
+    /** An import's own file name, when the user gave the file another (#2130). */
+    importedFrom?: string | null;
+    /**
+     * `false` when the pool already held these bytes and nothing new was
+     * stored (#2130): `filename` and `heldAs` are then the name it is held
+     * under, and `offeredAs` the name the upload offered. Absent: stored.
+     */
+    stored?: false;
+    heldAs?: string;
+    offeredAs?: string;
+    /** What vetting removed before the file was kept (#2149): one note per kind, counts only, never content. */
+    cleaned?: string[];
 }
 /** A sealed store's file: `owner` is the store owner's identity @id in the record, `ownerUser` their username beside it (#2041). */
  | {
@@ -160,6 +174,7 @@ export type AttachmentDetail = {
         store: string;
         ownerUser?: string;
     };
+    cleaned?: string[];
 };
 export type AttachmentInput = CommonInput & {
     op: AttachmentOp;

package/lib/src/utils/auditEvents.js

@@ -79,7 +79,7 @@ function tokenMetadata(viaToken) {
  * nothing the file does not already say.
  */
 export function buildPageMutationAuditEvent(input) {
-    const { op, pageName, uuid, fromPageName, rewriteOf, viaToken } = input;
+    const { op, pageName, uuid, fromPageName, rewriteOf, importedFrom, viaToken } = input;
     const who = whoOf(input);
     const metadata = {
         pageName,
@@ -98,6 +98,10 @@ export function buildPageMutationAuditEvent(input) {
         metadata.rewriteFrom = rewriteOf.from;
         metadata.rewriteTo = rewriteOf.to;
     }
+    // #2130: the file an imported page came from, when the user named the page otherwise.
+    if (op === 'create' && importedFrom) {
+        metadata.importedFrom = importedFrom;
+    }
     return {
         eventType: PAGE_EVENT[op],
         ...who.fields,
@@ -155,7 +159,19 @@ export function buildAttachmentAuditEvent(input) {
             metadata.pageName = input.pageName;
         if (typeof input.sizeBytes === 'number')
             metadata.sizeBytes = input.sizeBytes;
+        if (input.importedFrom)
+            metadata.importedFrom = input.importedFrom;
+        if (input.stored === false) {
+            metadata.stored = false;
+            if (input.heldAs)
+                metadata.heldAs = input.heldAs;
+            if (input.offeredAs)
+                metadata.offeredAs = input.offeredAs;
+        }
     }
+    // #2149: what vetting removed, in either form: kinds and counts, nothing of the file.
+    if (input.cleaned && input.cleaned.length > 0)
+        metadata.cleaned = [...input.cleaned];
     const severity = op === 'delete'
         ? (viaToken ? 'high' : 'medium')
         : (viaToken ? 'medium' : 'low');