@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

package/lib/src/utils/addonsPathResolver.js

@@ -0,0 +1,129 @@
+/**
+ * Shared parsing/discovery for the `ngdpbase.managers.addons-manager.addons-path`
+ * config value.
+ *
+ * #924: `AddonsManager` (real runtime discovery) and `ConfigurationManager`
+ * (the #672 boot-time "does this enabled addon exist" safety check) used to
+ * each carry their own copy of this logic. They drifted: `AddonsManager` was
+ * updated for #673's `node_modules:<glob>` packaged-addon syntax, but the
+ * validator's copy was not, so it resolved a `node_modules:` entry as a
+ * literal (non-existent) directory and treated every packaged addon as
+ * "unknown" — crashing boot the moment one was enabled. Consolidating the
+ * parsing/matching into one module removes the class of bug, not just this
+ * instance of it.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { minimatch } from 'minimatch';
+/** Prefix marking an addons-path entry as an npm-package glob rather than a directory. */
+export const NPM_ADDON_PREFIX = 'node_modules:';
+/**
+ * Coerce the raw config value (string or string[]) and split it into
+ * filesystem directory entries vs. `node_modules:<glob>` npm patterns.
+ */
+export function splitAddonsPath(raw) {
+    const entries = Array.isArray(raw) ? raw.map(String) : [String(raw)];
+    return {
+        directories: entries.filter(p => !p.startsWith(NPM_ADDON_PREFIX)),
+        npmPatterns: entries
+            .filter(p => p.startsWith(NPM_ADDON_PREFIX))
+            .map(p => p.slice(NPM_ADDON_PREFIX.length).trim())
+            .filter(Boolean)
+    };
+}
+/** The config key naming the add-ons to install (#1830). */
+export const ADDONS_INSTALL_KEY = 'ngdpbase.addons.install';
+/**
+ * Where installed add-ons live (#1830): `<data>/addons`, one folder per slug.
+ * Only a folder the lock file names, for a slug still in the install map, is
+ * an add-on (see `addonLock.ts`); anything else there is never loaded.
+ */
+export function installedAddonsDir(dataFolder, cwd = process.cwd()) {
+    return path.resolve(cwd, dataFolder, 'addons');
+}
+/** The slugs `ngdpbase.addons.install` names, from a merged or shipped+custom view. */
+export function configuredInstallSlugs(config) {
+    const map = config[ADDONS_INSTALL_KEY];
+    return map && typeof map === 'object' && !Array.isArray(map) ? Object.keys(map) : [];
+}
+/** Locate the `node_modules` directory to search for packaged addons (resolved from cwd). */
+export function findNodeModulesDir(cwd = process.cwd()) {
+    const nm = path.resolve(cwd, 'node_modules');
+    return fs.existsSync(nm) && fs.statSync(nm).isDirectory() ? nm : null;
+}
+/**
+ * Expand a `@scope/glob` (or bare `glob`) npm pattern to matching package
+ * directories under `nmRoot`.
+ */
+export function matchNpmPackageDirs(nmRoot, pattern) {
+    let baseDir = nmRoot;
+    let nameGlob = pattern;
+    if (pattern.startsWith('@')) {
+        const slash = pattern.indexOf('/');
+        const scope = slash > 0 ? pattern.slice(0, slash) : pattern;
+        nameGlob = slash > 0 ? pattern.slice(slash + 1) : '*';
+        baseDir = path.join(nmRoot, scope);
+    }
+    if (!fs.existsSync(baseDir))
+        return [];
+    const out = [];
+    for (const entry of fs.readdirSync(baseDir, { withFileTypes: true })) {
+        if (entry.isDirectory() && !entry.name.startsWith('.') && minimatch(entry.name, nameGlob)) {
+            out.push(path.join(baseDir, entry.name));
+        }
+    }
+    return out;
+}
+/**
+ * Best-effort addon identity for a packaged (npm) addon directory, derived
+ * from its package-directory name alone — no module import, matching the
+ * same boot-time-speed, no-module-loading design already accepted for the
+ * directory-scan case (see `ConfigurationManager.assertConfiguredAddonsExist`).
+ *
+ * Follows the documented packaged-addon naming convention
+ * (`@scope/<slug>-addon`, see docs/platform/deployment/addon-packaged.md):
+ * strips a trailing `-addon` suffix if present, else returns the folder name
+ * as-is.
+ *
+ * Caveat (same class as the existing directory-name heuristic): the addon's
+ * *real* identity is whatever its module exports as `name` at runtime. A
+ * package that doesn't follow the `-addon` naming convention, or whose
+ * module exports a different `name`, won't be matched precisely here — this
+ * is a validation-time approximation, not the source of truth.
+ */
+export function deriveAddonSlugFromPackageDirName(dirName) {
+    const suffix = '-addon';
+    return dirName.endsWith(suffix) ? dirName.slice(0, -suffix.length) : dirName;
+}
+/**
+ * Canonical identity for an addon directory (#927), resolved the SAME
+ * import-free way in every layer (discovery, `isEnabled`, the boot-time
+ * validator) so the four historical identities (folder name, module `name`,
+ * config key, manifest slug) can no longer drift:
+ *
+ *   canonicalId = package.json `ngdpbase.slug`  ??  deriveAddonSlugFromPackageDirName(folder)
+ *
+ * Reads `package.json` statically — never imports the module — which is what
+ * lets the boot validator compute the exact id the runtime will register
+ * under, instead of guessing. The module's exported `name` is a display
+ * label validated against this at load time, not a source of identity.
+ */
+export function resolveAddonSlug(addonDir, source) {
+    const dirName = path.basename(addonDir);
+    const pkgPath = path.join(addonDir, 'package.json');
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        const slug = pkg?.ngdpbase?.slug;
+        if (typeof slug === 'string' && slug.trim())
+            return slug.trim();
+    }
+    catch {
+        /* no/invalid package.json — fall back to the folder-derived id */
+    }
+    // Fallback when no slug is declared. npm packages follow the
+    // `@scope/<slug>-addon` publishing convention, so strip the conventional
+    // trailing `-addon`. A plain directory (bundled/drop-in) addon's folder
+    // name IS its identity verbatim — an addon may legitimately be named
+    // `something-addon` on disk — so never strip there.
+    return source === 'npm' ? deriveAddonSlugFromPackageDirName(dirName) : dirName;
+}

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

@@ -0,0 +1,66 @@
+/**
+ * @file assetMetadataTags.ts
+ * @description Shared ExifTool tag mapping for asset metadata edits (#866, #999).
+ *
+ * Extracted from `BaseMediaProvider` so attachments (#999) and media items use
+ * one implementation rather than two that drift. The mapping encodes decisions
+ * made in #866 that are easy to get subtly wrong a second time:
+ *
+ *  - **Keywords only.** ExifTool's MWG logic already mirrors `Keywords` to
+ *    XMP-dc `Subject`; writing both doubles every entry in the list.
+ *  - **Description twice, deliberately.** The read path resolves
+ *    `Description ?? ImageDescription`, so both are written to keep a round-trip
+ *    stable regardless of which one a given file already carries.
+ *  - **Date tag depends on container.** Images take `DateTimeOriginal`; video
+ *    and audio take QuickTime `CreateDate` (#750). Writing the wrong one
+ *    silently fails to change the capture date the reader displays.
+ *
+ * Pure — no I/O — so the mapping is unit-testable without ExifTool present.
+ */
+import type { AssetMetadataPatch } from '../types/Asset.js';
+/**
+ * Normalize a user-supplied timestamp to ExifTool's `YYYY:MM:DD HH:MM:SS`
+ * write format.
+ *
+ * Accepts `YYYY-MM-DD HH:MM[:SS]` and ISO-8601 `YYYY-MM-DDTHH:MM[:SS]`; a
+ * date-only value gets `00:00:00`.
+ *
+ * Rejects out-of-range parts rather than letting `Date` roll them over — a
+ * typo'd `2026-02-31` would otherwise be silently written as 3 March, which is
+ * worse than an error because the user believes the date they typed.
+ *
+ * @param input - User-supplied timestamp
+ * @returns ExifTool-format timestamp
+ * @throws Error on any other shape, or on out-of-range date parts
+ */
+export declare function normalizeExifDate(input: string): string;
+/**
+ * Map an `AssetMetadataPatch` onto the ExifTool tags to write for a file of the
+ * given MIME type.
+ *
+ * Only fields present on the patch produce tags, so a partial edit never
+ * clears a field the caller did not mention. An explicit `null` DOES clear —
+ * that is how a user removes a value, and it is distinct from omission.
+ *
+ * @param patch - Fields the caller wants changed
+ * @param mimeType - The file's MIME type, which selects the date tag
+ * @returns ExifTool tag object, empty when the patch changes nothing
+ * @throws Error if `dateTimeOriginal` is present, non-null and unparseable
+ */
+export declare function buildMetadataWriteTags(patch: AssetMetadataPatch, mimeType: string): Record<string, unknown>;
+/**
+ * Whether a MIME type can carry embedded metadata ExifTool can write (#999).
+ *
+ * Attachments are not curated media — a page can carry a `.zip`, a `.csv`, a
+ * `.json`. Writing EXIF to those either fails or corrupts them, so the caller
+ * must know when to persist the edit as sidecar metadata only rather than
+ * attempting a file write.
+ *
+ * Conservative allowlist rather than a denylist: an unrecognised type is
+ * treated as unwritable. Getting that wrong the safe way costs a sidecar-only
+ * edit; getting it wrong the other way damages a user's file.
+ *
+ * @param mimeType - The attachment's MIME type
+ * @returns Whether an embedded write should be attempted
+ */
+export declare function supportsEmbeddedMetadata(mimeType: string): boolean;

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

@@ -0,0 +1,28 @@
+/**
+ * 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 declare function writeFileAtomic(filePath: string, data: string | Buffer, encoding?: BufferEncoding, options?: {
+    fsync?: boolean;
+    mode?: number;
+    exclusive?: boolean;
+}): Promise<void>;
+export default writeFileAtomic;

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

@@ -0,0 +1,57 @@
+/**
+ * Administrative configuration changes as audit events (#1150).
+ *
+ * `auditRegistry` marked `admin-system` as `exempt: 'not-implemented'`, so no
+ * configuration change was audited anywhere. An administrator could change any
+ * setting on the instance — whether HTML is sanitised, the login throttle
+ * thresholds, the outbound egress ranges, the session cookie flags, whether
+ * auditing runs at all — and the log held no record, while faithfully
+ * recording that somebody viewed a page.
+ *
+ * See D19 of docs/security-posture.md, which needs this: the security posture
+ * is edited from a web form, so a change to it must leave a trace.
+ */
+import type { AuditEvent } from './auditEvents.js';
+import type { ActorAttribution } from '../context/ActorContext.js';
+/**
+ * Is this key one the operator has declared secret?
+ *
+ * The list is `ngdpbase.config.sensitive-values` (its `secret` entries), the same one that masks values on
+ * `/admin/configuration` and drives log redaction. It is operator-editable
+ * configuration, so it can contain anything: non-string entries are ignored
+ * rather than throwing, because a malformed list must not stop a config change
+ * from being recorded.
+ */
+export declare function isSecretKey(key: string, secretKeys: unknown): boolean;
+/**
+ * Render a configuration value for the record.
+ *
+ * Primitives are kept as they are, so a reader filtering on `after: true` gets
+ * what they expect. Anything else becomes JSON, truncated past
+ * {@link MAX_VALUE_CHARS} with an explicit marker — a truncated value that does
+ * not say it was truncated is worse than no value at all.
+ */
+export declare function describeConfigValue(value: unknown): unknown;
+export interface ConfigChangeInput {
+    key: string;
+    before: unknown;
+    after: unknown;
+    /** Who made the change — from the context the write was handed (#1179), never guessed. */
+    actor: ActorAttribution;
+    /** Whether the key is named in `ngdpbase.config.sensitive-values` (its `secret` entries). */
+    secret: boolean;
+}
+/**
+ * Build the audit event for a configuration change.
+ *
+ * A secret key records __that it changed and neither value__. An entry naming
+ * a key alongside its before and after values would reintroduce the disclosure
+ * `ngdpbase.config.sensitive-values` (its `secret` entries) exists to prevent, by a different route and
+ * into a file with a longer retention than the logs it already guards.
+ *
+ * Severity is uniform. Grading a security-relevant key higher would need a
+ * list of which keys those are, and inventing one here — ahead of the posture
+ * ingredient list in D15 — would be a second, drifting definition of the same
+ * thing.
+ */
+export declare function buildConfigChangeAuditEvent(input: ConfigChangeInput): AuditEvent;

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

@@ -0,0 +1,50 @@
+/**
+ * Every audit event name, in code (#1201, #1638, epic #1208).
+ *
+ * Configuration declares the names (`ngdpbase.audit.events`). Core's names are
+ * generated from `config/app-default-config.json` into
+ * `auditEventNames.generated.ts` by `npm run generate:permissions`, and
+ * `npm run lint:permissions` fails when that file is stale, so there is one
+ * declaration and no hand-kept list. `AuditEvent.eventType` is typed, so a
+ * core emitter cannot compile with a name configuration does not declare; a
+ * rename is one edit in configuration plus a regeneration, and the compiler
+ * finds every call site.
+ *
+ * An addon declares its own events in its `config/default-config.json`; they
+ * reach the registry through the configuration merge while the addon is
+ * enabled (addonConfigLayer.ts). The generated union cannot name them, and
+ * widening it to `string` would let a core typo compile again. So an addon
+ * names its event through {@link addonAuditEventName}, which brands a checked
+ * string, and `recordAuditEvent` refuses — throws — a branded name the merged
+ * registry does not declare. Core typing stays exactly as strict as before.
+ *
+ * Convention: `{target}-{action}`, hyphens only, URL-safe, sharing the slug of
+ * the permission whose action it records (`page-read` authorizes; `page-read`
+ * records). The containing map says which is meant.
+ */
+import { AUDIT_EVENT, AUDIT_EVENT_NAME_PATTERN, type AuditEventName } from './auditEventNames.generated.js';
+export { AUDIT_EVENT, AUDIT_EVENT_NAME_PATTERN, type AuditEventName };
+/** Every core name, sorted, for tests and tooling. */
+export declare function auditEventNames(): AuditEventName[];
+/** Is this one of the names core declares (and so one the generated union admits)? */
+export declare function isCoreAuditEventName(name: string): name is AuditEventName;
+declare const addonAuditEventBrand: unique symbol;
+/**
+ * An audit event name an addon declares (#1638). A string literal is not one:
+ * the only way to get one is {@link addonAuditEventName}, so the brand marks a
+ * name that went through the check, and a core typo still fails to compile.
+ */
+export type AddonAuditEventName = string & {
+    readonly [addonAuditEventBrand]: true;
+};
+/** What `recordAuditEvent` accepts: a core name, or an addon's checked name. */
+export type RecordableAuditEventName = AuditEventName | AddonAuditEventName;
+/**
+ * Name an addon's audit event. Throws on a name outside `{target}-{action}`.
+ *
+ * Whether the name is declared is checked when the event is recorded, not
+ * here: the registry is bound when AuditManager initialises, which may be
+ * after the addon module loads. `lint:audit` reads the literal passed here as
+ * the addon's emitter, so pass a string literal.
+ */
+export declare function addonAuditEventName(name: string): AddonAuditEventName;

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

@@ -0,0 +1,169 @@
+/** The `{target}-{action}` convention: target first, hyphens only (#1201). */
+export declare const AUDIT_EVENT_NAME_PATTERN: RegExp;
+/** Every audit event core declares, keyed by the name upper-cased with underscores. */
+export declare const AUDIT_EVENT: {
+    /** An add-on named in ngdpbase.addons.install installed into the data folder: package, version, sha512 and the repository its provenance names; recorded before it is written, which cannot proceed without it (#1830) */
+    readonly ADDON_INSTALL: "addon-install";
+    /** An installed add-on moved to another version by an administrator's Update: who, and from which version to which (#1830; the Update action is not built yet) */
+    readonly ADDON_UPDATE: "addon-update";
+    /** An add-on refused or set aside by a check: its sha512, provenance, tarball contents, package.json, the lock file, or a changed installed folder (#1830) */
+    readonly ADDON_VERIFY_FAILED: "addon-verify-failed";
+    /** Admin dashboard read; not recorded, read volume */
+    readonly ADMIN_READ: "admin-read";
+    /** File deleted; destruction */
+    readonly ASSET_DELETE: "asset-delete";
+    /** Attachment metadata edited; EXIF/IPTC and catalog fields change provenance */
+    readonly ASSET_EDIT: "asset-edit";
+    /** Attachment read; not recorded, read volume */
+    readonly ASSET_READ: "asset-read";
+    /** File uploaded */
+    readonly ASSET_UPLOAD: "asset-upload";
+    /** Hash chain restarted, with the reason; the marker is the action and cannot half-complete */
+    readonly AUDIT_CHAIN_RESTART: "audit-chain-restart";
+    /** The audit trail exported to a file; who took a copy, in what format, with what filter */
+    readonly AUDIT_EXPORT: "audit-export";
+    /** Sign-in failed */
+    readonly AUTHENTICATION_FAILED: "authentication-failed";
+    /** User signed out */
+    readonly AUTHENTICATION_LOGOUT: "authentication-logout";
+    /** Sign-in succeeded */
+    readonly AUTHENTICATION_SUCCESS: "authentication-success";
+    /** Access granted; emitter exists, nothing in production calls it */
+    readonly AUTHORIZATION_ALLOW: "authorization-allow";
+    /** Access denied */
+    readonly AUTHORIZATION_DENY: "authorization-deny";
+    /** A full backup written; where it went and who asked */
+    readonly BACKUP_CREATE: "backup-create";
+    /** 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 database restore cancelled before the restart applied it: which backup, who staged it and who cancelled; recorded first, which cannot proceed without it (#1723) */
+    readonly BACKUP_RESTORE_CANCEL: "backup-restore-cancel";
+    /** A staged database restore replaced by another before the restart applied it: which backup replaced which, and who asked; recorded first, which cannot proceed without it (#1723) */
+    readonly BACKUP_RESTORE_REPLACE: "backup-restore-replace";
+    /** Comment added to a page — user content written on someone's behalf, the page-edit class (#1232) */
+    readonly COMMENT_CREATE: "comment-create";
+    /** Comment marked deleted; who removed it and whose it was (#1232) */
+    readonly COMMENT_DELETE: "comment-delete";
+    /** Configuration changed by an administrator; standard so a broken audit configuration can still be repaired from the UI */
+    readonly CONFIG_CHANGE: "config-change";
+    /** Every custom configuration value discarded; recorded before the reset, which cannot proceed without it */
+    readonly CONFIG_RESET: "config-reset";
+    /** A page's footnote list changed — action add, import, transfer, update or delete; page content written on someone's behalf (#1233) */
+    readonly FOOTNOTE_EDIT: "footnote-edit";
+    /** A background job finished successfully */
+    readonly JOB_COMPLETED: "job-completed";
+    /** A background job failed */
+    readonly JOB_FAILED: "job-failed";
+    /** A scheduled run stopped by shutdown and handed to the next start, which resumes it */
+    readonly JOB_INTERRUPTED: "job-interrupted";
+    /** An administrator retried a scheduled run now instead of at its retry time */
+    readonly JOB_RETRY: "job-retry";
+    /** A scheduled job's rule changed; its slots are counted again from then */
+    readonly JOB_SCHEDULE_CHANGE: "job-schedule-change";
+    /** Scheduled slots a job passed over, by its catch-up or overlap rule */
+    readonly JOB_SKIPPED: "job-skipped";
+    /** A background job started, and who asked for it */
+    readonly JOB_STARTED: "job-started";
+    /** A manager changed state: degraded, disabled, failed or recovered */
+    readonly MANAGER_STATE_CHANGE: "manager-state-change";
+    /** OpenID Connect: an app's sign-in request was allowed and a code issued (#1575) */
+    readonly OIDCAUTHORIZE_ALLOW: "oidcauthorize-allow";
+    /** OpenID Connect: an app's sign-in request was refused (denied consent, sign-in required, bad request) */
+    readonly OIDCAUTHORIZE_DENY: "oidcauthorize-deny";
+    /** OpenID Connect: an app's grant and every token under it were revoked */
+    readonly OIDCGRANT_REVOKE: "oidcgrant-revoke";
+    /** OpenID Connect: the provider failed while handling a request */
+    readonly OIDCSERVER_ERROR: "oidcserver-error";
+    /** OpenID Connect: the token endpoint refused an app's request */
+    readonly OIDCTOKEN_ERROR: "oidctoken-error";
+    /** OpenID Connect: tokens issued to an app, with the grant type that earned them */
+    readonly OIDCTOKEN_ISSUE: "oidctoken-issue";
+    /** OpenID Connect: a used code or refresh token was presented again; its grant was revoked (possible replay) */
+    readonly OIDCTOKEN_REUSE: "oidctoken-reuse";
+    /** OpenID Connect: an access or refresh token was destroyed */
+    readonly OIDCTOKEN_REVOKE: "oidctoken-revoke";
+    /** OpenID Connect: UserInfo refused a request (bad, expired or revoked token, unknown account) */
+    readonly OIDCUSERINFO_ERROR: "oidcuserinfo-error";
+    /** Page created */
+    readonly PAGE_CREATE: "page-create";
+    /** Page deleted; destruction, so the record must outlive the page */
+    readonly PAGE_DELETE: "page-delete";
+    /** Page edited */
+    readonly PAGE_EDIT: "page-edit";
+    /** Page exported to a file; bulk extraction of content, gated on read until a bulk surface exists */
+    readonly PAGE_EXPORT: "page-export";
+    /** Inbound links rewritten after a rename */
+    readonly PAGE_LINK_REWRITE: "page-link-rewrite";
+    /** Page edited through the admin raw editor */
+    readonly PAGE_RAW_EDIT: "page-raw-edit";
+    /** Page read; off by default so a general-purpose deployment does not drown its log in reads. On, a records-style deployment gets who looked at what (#1129) */
+    readonly PAGE_READ: "page-read";
+    /** Page renamed */
+    readonly PAGE_RENAME: "page-rename";
+    /** Security policy evaluated; emitter exists, nothing in production calls it */
+    readonly POLICY_EVALUATE: "policy-evaluate";
+    /** Security posture at startup, compared against the previous start */
+    readonly POSTURE_RECORDED: "posture-recorded";
+    /** Proxy grant made: someone may act for the person named in user; actor is who made it (#1762) */
+    readonly PROXY_GRANT: "proxy-grant";
+    /** Proxy grant ended: revoked, or the account closed; user is the person represented, actor who ended it (#1762) */
+    readonly PROXY_REVOKE: "proxy-revoke";
+    /** A signed-in session started or stopped acting for someone under a proxy grant, or opens their private store: chosen, switched-back, ended because the grant no longer allows it (grant-ended, proxy-access-off), or vault-opened; user is the person represented, actor the person signed in (#1762) */
+    readonly PROXY_SWITCH: "proxy-switch";
+    /** Step-up: a re-authentication failed (wrong password, another person's passkey, throttled) */
+    readonly REAUTH_FAILURE: "reauth-failure";
+    /** Step-up: an action asked for a fresh sign-in (#1525) — or refused a delegated credential that cannot give one */
+    readonly REAUTH_PROMPT: "reauth-prompt";
+    /** Step-up: the person re-authenticated, with the factor used */
+    readonly REAUTH_SUCCESS: "reauth-success";
+    /** Page search; not recorded, read volume */
+    readonly SEARCH_PAGE: "search-page";
+    /** People searched for; enumerating people is disclosive in a way searching pages is not. Off by default as read volume */
+    readonly SEARCH_USER: "search-user";
+    /** A masked configuration value shown to an administrator; the key is recorded, never the value */
+    readonly SECRET_REVEAL: "secret-reveal";
+    /** Security violation detected; the kind is in metadata.securityEventType */
+    readonly SECURITY_EVENT: "security-event";
+    /** Anonymous sessions cleared */
+    readonly SESSION_CLEAR_ANONYMOUS: "session-clear-anonymous";
+    /** Session revoked by an administrator */
+    readonly SESSION_REVOKE: "session-revoke";
+    /** Share link used; batched counts for keyword links, one record per page or file opened through a vault link (#1388) */
+    readonly SHARE_ACCESS: "share-access";
+    /** Share link created; mints an anonymous-access credential, the same shape as token-mint */
+    readonly SHARE_CREATE: "share-create";
+    /** Share link's lifetime extended by its issuer, by up to 24 hours (#1388) */
+    readonly SHARE_EXTEND: "share-extend";
+    /** Share link revoked; pairs with token-revoke */
+    readonly SHARE_REVOKE: "share-revoke";
+    /** A user's private store copy created at its door (#1414) — with key material when sealed; never the words or a key in the record */
+    readonly STORE_CREATE: "store-create";
+    /** A takeout imported into its owner's private store; a bulk write — who, which store, pages and files written or skipped */
+    readonly STORE_IMPORT: "store-import";
+    /** A whole private store downloaded by its owner, DECRYPTED; who took it, which store, and how much left */
+    readonly STORE_TAKEOUT: "store-takeout";
+    /** Instance shut down cleanly; its absence before the next start is the signal */
+    readonly SYSTEM_SHUTDOWN: "system-shutdown";
+    /** Instance started; reports whether the previous run ended cleanly */
+    readonly SYSTEM_START: "system-start";
+    /** Agent token's expiry moved later by its owner; carries the old and new expiry (#1734) */
+    readonly TOKEN_EXTEND: "token-extend";
+    /** Agent token minted; a credential nobody knows exists is the worst case */
+    readonly TOKEN_MINT: "token-mint";
+    /** Agent token revoked */
+    readonly TOKEN_REVOKE: "token-revoke";
+    /** Account created; by an administrator, by self-registration, or provisioned by an identity provider */
+    readonly USER_CREATE: "user-create";
+    /** Account deleted; destruction of an identity and its attribution, recorded before the delete */
+    readonly USER_DELETE: "user-delete";
+    /** Account changed in a way that alters what it may do or who holds it: roles, password, active, external, email, profile lock. Preference edits are not recorded */
+    readonly USER_EDIT: "user-edit";
+    /** User profile read; not recorded, read volume */
+    readonly USER_READ: "user-read";
+    /** Not an action: read from a proxy grant at the vault door; the grant itself is recorded as proxy-grant */
+    readonly VAULT_PROXY: "vault-proxy";
+    /** A vault page's leftovers moved into its vault (#1842): its shared-pool files (moved, or copied where other public pages use them) and its footnotes and comments from the public folders. Names the owner, vault and page uuid and the counts, never a title or file name. Run by the vault's owner, or for a vault that isn't sealed by someone holding admin-system */
+    readonly VAULT_REPAIR: "vault-repair";
+};
+/** A name core code may emit. */
+export type AuditEventName = (typeof AUDIT_EVENT)[keyof typeof AUDIT_EVENT];