@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

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

@@ -0,0 +1,168 @@
+// GENERATED FILE — do not edit.
+// Source: config/app-default-config.json → ngdpbase.audit.events and ngdpbase.permissions.definitions.*.audit
+// Regenerate: npm run generate:permissions
+//
+// Every audit event core declares, as code (#1201, #1638). An emitter names
+// one as AUDIT_EVENT.KEY, so a typo is a compile error. Import from
+// ./auditEventNames.js, not from this file.
+/** The `{target}-{action}` convention: target first, hyphens only (#1201). */
+export const AUDIT_EVENT_NAME_PATTERN = /^[a-z]+(-[a-z]+)+$/;
+/** Every audit event core declares, keyed by the name upper-cased with underscores. */
+export 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) */
+    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) */
+    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) */
+    ADDON_VERIFY_FAILED: 'addon-verify-failed',
+    /** Admin dashboard read; not recorded, read volume */
+    ADMIN_READ: 'admin-read',
+    /** File deleted; destruction */
+    ASSET_DELETE: 'asset-delete',
+    /** Attachment metadata edited; EXIF/IPTC and catalog fields change provenance */
+    ASSET_EDIT: 'asset-edit',
+    /** Attachment read; not recorded, read volume */
+    ASSET_READ: 'asset-read',
+    /** File uploaded */
+    ASSET_UPLOAD: 'asset-upload',
+    /** Hash chain restarted, with the reason; the marker is the action and cannot half-complete */
+    AUDIT_CHAIN_RESTART: 'audit-chain-restart',
+    /** The audit trail exported to a file; who took a copy, in what format, with what filter */
+    AUDIT_EXPORT: 'audit-export',
+    /** Sign-in failed */
+    AUTHENTICATION_FAILED: 'authentication-failed',
+    /** User signed out */
+    AUTHENTICATION_LOGOUT: 'authentication-logout',
+    /** Sign-in succeeded */
+    AUTHENTICATION_SUCCESS: 'authentication-success',
+    /** Access granted; emitter exists, nothing in production calls it */
+    AUTHORIZATION_ALLOW: 'authorization-allow',
+    /** Access denied */
+    AUTHORIZATION_DENY: 'authorization-deny',
+    /** A full backup written; where it went and who asked */
+    BACKUP_CREATE: 'backup-create',
+    /** Comment added to a page — user content written on someone's behalf, the page-edit class (#1232) */
+    COMMENT_CREATE: 'comment-create',
+    /** Comment marked deleted; who removed it and whose it was (#1232) */
+    COMMENT_DELETE: 'comment-delete',
+    /** Configuration changed by an administrator; standard so a broken audit configuration can still be repaired from the UI */
+    CONFIG_CHANGE: 'config-change',
+    /** Every custom configuration value discarded; recorded before the reset, which cannot proceed without it */
+    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) */
+    FOOTNOTE_EDIT: 'footnote-edit',
+    /** A background job finished successfully */
+    JOB_COMPLETED: 'job-completed',
+    /** A background job failed */
+    JOB_FAILED: 'job-failed',
+    /** A scheduled run stopped by shutdown and handed to the next start, which resumes it */
+    JOB_INTERRUPTED: 'job-interrupted',
+    /** An administrator retried a scheduled run now instead of at its retry time */
+    JOB_RETRY: 'job-retry',
+    /** A scheduled job's rule changed; its slots are counted again from then */
+    JOB_SCHEDULE_CHANGE: 'job-schedule-change',
+    /** Scheduled slots a job passed over, by its catch-up or overlap rule */
+    JOB_SKIPPED: 'job-skipped',
+    /** A background job started, and who asked for it */
+    JOB_STARTED: 'job-started',
+    /** A manager changed state: degraded, disabled, failed or recovered */
+    MANAGER_STATE_CHANGE: 'manager-state-change',
+    /** OpenID Connect: an app's sign-in request was allowed and a code issued (#1575) */
+    OIDCAUTHORIZE_ALLOW: 'oidcauthorize-allow',
+    /** OpenID Connect: an app's sign-in request was refused (denied consent, sign-in required, bad request) */
+    OIDCAUTHORIZE_DENY: 'oidcauthorize-deny',
+    /** OpenID Connect: an app's grant and every token under it were revoked */
+    OIDCGRANT_REVOKE: 'oidcgrant-revoke',
+    /** OpenID Connect: the provider failed while handling a request */
+    OIDCSERVER_ERROR: 'oidcserver-error',
+    /** OpenID Connect: the token endpoint refused an app's request */
+    OIDCTOKEN_ERROR: 'oidctoken-error',
+    /** OpenID Connect: tokens issued to an app, with the grant type that earned them */
+    OIDCTOKEN_ISSUE: 'oidctoken-issue',
+    /** OpenID Connect: a used code or refresh token was presented again; its grant was revoked (possible replay) */
+    OIDCTOKEN_REUSE: 'oidctoken-reuse',
+    /** OpenID Connect: an access or refresh token was destroyed */
+    OIDCTOKEN_REVOKE: 'oidctoken-revoke',
+    /** OpenID Connect: UserInfo refused a request (bad, expired or revoked token, unknown account) */
+    OIDCUSERINFO_ERROR: 'oidcuserinfo-error',
+    /** Page created */
+    PAGE_CREATE: 'page-create',
+    /** Page deleted; destruction, so the record must outlive the page */
+    PAGE_DELETE: 'page-delete',
+    /** Page edited */
+    PAGE_EDIT: 'page-edit',
+    /** Page exported to a file; bulk extraction of content, gated on read until a bulk surface exists */
+    PAGE_EXPORT: 'page-export',
+    /** Inbound links rewritten after a rename */
+    PAGE_LINK_REWRITE: 'page-link-rewrite',
+    /** Page edited through the admin raw editor */
+    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) */
+    PAGE_READ: 'page-read',
+    /** Page renamed */
+    PAGE_RENAME: 'page-rename',
+    /** Security policy evaluated; emitter exists, nothing in production calls it */
+    POLICY_EVALUATE: 'policy-evaluate',
+    /** Security posture at startup, compared against the previous start */
+    POSTURE_RECORDED: 'posture-recorded',
+    /** Proxy grant made: someone may act for the person named in user; actor is who made it (#1762) */
+    PROXY_GRANT: 'proxy-grant',
+    /** Proxy grant ended: revoked, or the account closed; user is the person represented, actor who ended it (#1762) */
+    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) */
+    PROXY_SWITCH: 'proxy-switch',
+    /** Step-up: a re-authentication failed (wrong password, another person's passkey, throttled) */
+    REAUTH_FAILURE: 'reauth-failure',
+    /** Step-up: an action asked for a fresh sign-in (#1525) — or refused a delegated credential that cannot give one */
+    REAUTH_PROMPT: 'reauth-prompt',
+    /** Step-up: the person re-authenticated, with the factor used */
+    REAUTH_SUCCESS: 'reauth-success',
+    /** Page search; not recorded, read volume */
+    SEARCH_PAGE: 'search-page',
+    /** People searched for; enumerating people is disclosive in a way searching pages is not. Off by default as read volume */
+    SEARCH_USER: 'search-user',
+    /** A masked configuration value shown to an administrator; the key is recorded, never the value */
+    SECRET_REVEAL: 'secret-reveal',
+    /** Security violation detected; the kind is in metadata.securityEventType */
+    SECURITY_EVENT: 'security-event',
+    /** Anonymous sessions cleared */
+    SESSION_CLEAR_ANONYMOUS: 'session-clear-anonymous',
+    /** Session revoked by an administrator */
+    SESSION_REVOKE: 'session-revoke',
+    /** Share link used; batched counts for keyword links, one record per page or file opened through a vault link (#1388) */
+    SHARE_ACCESS: 'share-access',
+    /** Share link created; mints an anonymous-access credential, the same shape as token-mint */
+    SHARE_CREATE: 'share-create',
+    /** Share link's lifetime extended by its issuer, by up to 24 hours (#1388) */
+    SHARE_EXTEND: 'share-extend',
+    /** Share link revoked; pairs with token-revoke */
+    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 */
+    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 */
+    STORE_IMPORT: 'store-import',
+    /** A whole private store downloaded by its owner, DECRYPTED; who took it, which store, and how much left */
+    STORE_TAKEOUT: 'store-takeout',
+    /** Instance shut down cleanly; its absence before the next start is the signal */
+    SYSTEM_SHUTDOWN: 'system-shutdown',
+    /** Instance started; reports whether the previous run ended cleanly */
+    SYSTEM_START: 'system-start',
+    /** Agent token's expiry moved later by its owner; carries the old and new expiry (#1734) */
+    TOKEN_EXTEND: 'token-extend',
+    /** Agent token minted; a credential nobody knows exists is the worst case */
+    TOKEN_MINT: 'token-mint',
+    /** Agent token revoked */
+    TOKEN_REVOKE: 'token-revoke',
+    /** Account created; by an administrator, by self-registration, or provisioned by an identity provider */
+    USER_CREATE: 'user-create',
+    /** Account deleted; destruction of an identity and its attribution, recorded before the delete */
+    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 */
+    USER_EDIT: 'user-edit',
+    /** User profile read; not recorded, read volume */
+    USER_READ: 'user-read',
+    /** Not an action: read from a proxy grant at the vault door; the grant itself is recorded as proxy-grant */
+    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 */
+    VAULT_REPAIR: 'vault-repair'
+};

package/lib/src/utils/auditEventNames.js

@@ -0,0 +1,49 @@
+/**
+ * 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 } from './auditEventNames.generated.js';
+export { AUDIT_EVENT, AUDIT_EVENT_NAME_PATTERN };
+/** Every core name, sorted, for tests and tooling. */
+export function auditEventNames() {
+    return Object.values(AUDIT_EVENT).sort();
+}
+const CORE_NAMES = new Set(Object.values(AUDIT_EVENT));
+/** Is this one of the names core declares (and so one the generated union admits)? */
+export function isCoreAuditEventName(name) {
+    return CORE_NAMES.has(name);
+}
+/**
+ * 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 function addonAuditEventName(name) {
+    if (!AUDIT_EVENT_NAME_PATTERN.test(name)) {
+        throw new Error(`Audit event '${name}' is not a {target}-{action} name (hyphens only).`);
+    }
+    return name;
+}

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

@@ -0,0 +1,265 @@
+/**
+ * Audit event builders for content mutations (#1080).
+ *
+ * `AuditManager` was already mature — file provider with rotation, 90-day
+ * retention, search, stats, export, and an admin UI — but almost nothing
+ * called it. Outside the manager the only `logAuditEvent` call sites were
+ * `page-delete`, admin raw-edit, two session operations, and share
+ * issue/revoke. Ordinary page create, edit, and rename, and every attachment
+ * upload and delete, produced no audit record at all.
+ *
+ * That left "who changed this page, when, and through what?" answerable only
+ * from a version manifest: per-page, not queryable across pages, and present
+ * only when the deployment runs `versioningfileprovider` (the shipped default
+ * is `filesystemprovider`, which keeps no versions). There was no way to ask
+ * "everything this agent token wrote last Tuesday" — which is exactly the
+ * question agent tokens (#946) make worth asking, since a token writes
+ * unattended and the version manifest records only a username.
+ *
+ * These are pure builders so the event *shape* can be tested without an
+ * engine, a request, or a manager. The shape is the contract: `#1082` reads
+ * `page-rename`'s `fromPageName`/`pageName` pair to resolve a link that
+ * points at a page's former title, so those two fields are load-bearing
+ * rather than descriptive.
+ */
+import { type RecordableAuditEventName } from './auditEventNames.js';
+import type { ProxyClaim } from '../managers/UserManager.js';
+/** Agent-token identity attached to a request that authenticated with one. */
+export interface AuditViaToken {
+    id?: string;
+    name?: string;
+}
+/** The subset of `AuditManager` these helpers need. */
+export interface AuditEventSink {
+    logAuditEvent?: (event: Record<string, unknown>) => Promise<string>;
+    /**
+     * Force queued records to storage (#1121).
+     *
+     * Named for the method AuditManager actually has. An earlier draft called it
+     * `flush`, which nothing implements — so every critical event would have
+     * refused in production while the tests passed. Third time this exact
+     * mismatch has bitten in this issue chain.
+     *
+     * Optional because not every sink batches, but a sink WITHOUT it cannot
+     * promise durability, so a critical event refuses rather than reporting a
+     * guarantee the system does not have.
+     */
+    flushAuditQueue?: () => Promise<void>;
+}
+export type AuditSeverity = 'low' | 'medium' | 'high';
+/**
+ * The result vocabulary, as a runtime value (#1237).
+ *
+ * The type alone could not be offered as filter options, so the audit page
+ * hand-kept its own list — and it offered `allow`, `deny`, `error` while the
+ * log holds `success` (5,859), `deny` (896) and `failure` (79). Two of the
+ * three options matched zero records and the largest value was unfilterable.
+ * Exactly the #1115 failure, one field over.
+ */
+export declare const AUDIT_RESULTS: readonly ["success", "failure", "allow", "deny", "error", "logout"];
+export type AuditResult = typeof AUDIT_RESULTS[number];
+export interface AuditEvent {
+    /** A core name (`AUDIT_EVENT.KEY`), or an addon's name from `addonAuditEventName` (#1638). */
+    eventType: RecordableAuditEventName;
+    user: string;
+    /**
+     * Who actually did it, when that is not `user` (#1762): `user` is the
+     * account acted on — the person represented — and `actor` the person
+     * signed in. Absent on a row with no proxy claim, never a copy of `user`.
+     * Comes from `actorOf` / `proxyAttribution` (slice 3); the proxy-grant
+     * events also set it for the person who made or ended the grant (slice 1).
+     * The audit search filters on it (`?actor=`).
+     */
+    actor?: string;
+    ipAddress: string | undefined;
+    action: string;
+    /** How it went. Mutations record `success`; decisions record `allow` / `deny`; sign-in records `failure` / `logout`. */
+    result: AuditResult;
+    severity: AuditSeverity;
+    metadata: Record<string, unknown>;
+    /** What the action was about, where there is a single subject (a share id, a page). */
+    resource?: string;
+    resourceType?: string;
+    /** Why, for a decision or a refusal. */
+    reason?: string;
+    /** The session the action ran in, where one is known. */
+    sessionId?: string;
+}
+/**
+ * `link-rewrite` is a machine write, not a human one (#1094): when a page is
+ * renamed, the referring pages have their `[Old Title]` links rewritten. It is
+ * a distinct op so a reader of the history can tell why a page they did not
+ * edit changed, and so those writes can be excluded from "who is editing what"
+ * queries without having to guess from the content.
+ */
+export type PageMutationOp = 'create' | 'edit' | 'rename' | 'link-rewrite';
+export type AttachmentOp = 'upload' | 'delete';
+export type TokenOp = 'mint' | 'revoke' | 'extend';
+interface CommonInput {
+    username: string | undefined;
+    ipAddress: string | undefined;
+    viaToken?: AuditViaToken | null;
+    /**
+     * The proxy grant the request acted under (#1762 slice 3). Forwarded from the
+     * caller's context beside `viaToken`, never rebuilt: the row then names the
+     * represented person in `user` and the person who acted in `actor`.
+     */
+    viaProxy?: ProxyClaim | null;
+}
+export interface PageMutationInput extends CommonInput {
+    op: PageMutationOp;
+    pageName: string;
+    uuid: string | null | undefined;
+    /** Previous title. Only meaningful for `rename`; ignored otherwise. */
+    fromPageName?: string | null;
+    /**
+     * The rename that caused a `link-rewrite`. Ignored for every other op — the
+     * page being rewritten did not itself change title, so `fromPageName` would
+     * be the wrong field to carry it.
+     */
+    rewriteOf?: {
+        from: string;
+        to: string;
+    } | null;
+}
+export interface TokenInput extends CommonInput {
+    op: TokenOp;
+    /** Token id — the handle every later question about this credential uses. */
+    id: string;
+    /** Whose token it is, which is not always who acted: an admin may revoke. */
+    owner: string;
+    /** Operator-supplied label. Optional; a token need not be named. */
+    name?: string | null;
+    /** Only meaningful for `mint`; ignored otherwise. */
+    scopes?: readonly string[];
+    /** The expiry granted: meaningful for `mint` and `extend`; ignored otherwise. */
+    expiresAt?: string;
+    /** The expiry before an `extend` (#1734); ignored otherwise. */
+    previousExpiresAt?: string;
+    /** Only meaningful for `revoke`; ignored otherwise. */
+    revokedBy?: string;
+}
+export interface AttachmentInput extends CommonInput {
+    op: AttachmentOp;
+    attachmentId: string;
+    filename: string;
+    pageName?: string | null;
+    sizeBytes?: number | null;
+}
+/**
+ * Build the audit event for a page create, edit, rename, or link rewrite.
+ *
+ * `result` is always `success`: these are recorded *after* the write lands,
+ * unlike `page-delete`, which logs `attempted` before unlinking so that a
+ * crash mid-delete still leaves a trace. A create or edit has the page file
+ * and its version history as its own record, so recording the attempt buys
+ * nothing the file does not already say.
+ */
+export declare function buildPageMutationAuditEvent(input: PageMutationInput): AuditEvent;
+export interface PageViewInput extends CommonInput {
+    pageName: string;
+    uuid: string | null | undefined;
+}
+/**
+ * Build the audit event for a page view (#1129).
+ *
+ * Emission is a deployment posture: `page-read` ships `enabled: false` in
+ * `ngdpbase.audit.events` (#1203), and `recordAuditEvent` honours the switch.
+ * Off, a general-purpose deployment does not drown its log in reads; on, a
+ * records-style deployment gets the access accounting — who looked at what —
+ * that read auditing exists for.
+ */
+export declare function buildPageViewAuditEvent(input: PageViewInput): AuditEvent;
+/**
+ * Build the audit event for an attachment upload or delete.
+ *
+ * A delete outranks an upload because it is the one that loses data, and a
+ * token-driven delete matches `page-delete`'s `high` for the same reason:
+ * unattended destruction is the case someone reviewing the log is looking for.
+ */
+export declare function buildAttachmentAuditEvent(input: AttachmentInput): AuditEvent;
+/**
+ * Send an event to the audit sink, best-effort.
+ *
+ * Never throws and never rejects. By the time this runs the mutation it
+ * describes has already committed, so surfacing a logging failure would turn
+ * a successful save into an error response and invite a destructive retry.
+ * A missing or unconfigured `AuditManager` is a no-op for the same reason.
+ */
+/**
+ * Audit writes that were attempted and lost (#1109).
+ *
+ * Every audit write here is fire-and-forget with a caught error, deliberately:
+ * losing the log is bad, but refusing a page save or a token mint because the
+ * log failed is worse. The consequence is that a request can land its write and
+ * lose its audit entry — a page edited with no history, or a credential minted
+ * with no record it exists.
+ *
+ * That trade is defensible. What is not is leaving its only trace in a
+ * `logger.warn` nobody reads: an accepted risk nobody can see is
+ * indistinguishable from an unnoticed bug. So the drops are counted, the last
+ * one is described, and the count is surfaced where an operator already looks.
+ */
+export interface AuditDropStats {
+    /** Audit writes attempted and lost since boot. */
+    dropped: number;
+    /** `eventType` of the most recent loss, or null. */
+    lastEventType: string | null;
+    /** Message of the most recent failure, or null. */
+    lastError: string | null;
+    /** ISO timestamp of the most recent loss, or null. */
+    lastAt: string | null;
+}
+/** Audit writes lost since boot. Read-only snapshot. */
+export declare function getAuditDropStats(): AuditDropStats;
+/** Reset the counter. For tests; nothing in the running app calls this. */
+export declare function resetAuditDropStats(): void;
+/**
+ * Record an audit event, honouring its on-failure rule (#1121, #1218).
+ *
+ * __Standard__ events are fire-and-forget with a caught error, per the #1109
+ * decision: losing the log is bad, but refusing a page save because the log
+ * failed is worse.
+ *
+ * __Critical__ events reverse that. The record IS the evidence — a credential
+ * minted with nothing saying it exists is the case this exists for — so the
+ * write is flushed to storage and a failure REJECTS, letting the caller
+ * abandon the action. "Durable before the action completes" is not satisfied by
+ * a queue that flushes on a timer, because the process can die in between.
+ */
+/**
+ * What became of a record (#1205). Never silent: a caller can tell "recorded"
+ * from "switched off in configuration" from "no sink on this instance".
+ *
+ * - `recorded`    — the sink accepted it (and, for a refuse-on-failure event, flushed it)
+ * - `not-enabled` — `enabled: false` in `ngdpbase.audit.events`; a decision on the record
+ * - `no-sink`     — auditing is off or not yet initialised; visible through #1118's posture
+ * - `dropped`     — the sink failed on a continue-on-failure event; counted in the drop statistics
+ *
+ * An event declared on-failure: refuse that cannot be recorded does not
+ * return: it throws, so the caller abandons the action.
+ */
+export type AuditRecordOutcome = 'recorded' | 'not-enabled' | 'no-sink' | 'dropped';
+export declare function recordAuditEvent(sink: AuditEventSink | null | undefined, event: AuditEvent, onError?: (err: unknown) => void): Promise<AuditRecordOutcome>;
+/**
+ * Build the audit event for an agent token mint, extend or revoke (#1111, #1734).
+ *
+ * Before this, the token store was the only record that a credential had ever
+ * existed — and `purgeExpired()` claimed otherwise in a comment ("Audit is
+ * unaffected") while nothing emitted anything. That made `retention-days`
+ * load-bearing by accident: hash-bearing records were kept a month past
+ * usefulness purely so somebody could answer "what could this token do, and
+ * who stopped it?" With the lifecycle audited, the store can keep only what it
+ * needs to authenticate.
+ *
+ * Emitted from the manager rather than the route, unlike `page.*`. A page
+ * mutation logged at the HTTP layer misses an internal caller and that is
+ * survivable; an unaudited mint is a credential nobody knows exists.
+ *
+ * `scopes` appear on a mint only, `expiresAt` on a mint and an extend (with
+ * `previousExpiresAt` on an extend, #1734), and `revokedBy` on a revoke only —
+ * the same rule `page-rename` follows for `fromPageName`. A field present on
+ * every event is useless as a filter.
+ */
+export declare function buildTokenAuditEvent(input: TokenInput): AuditEvent;
+export {};