gazetta 0.6.0 → 0.8.0

package/dist/audit/provider.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `AuditProvider` — the seam between Gazetta's recording sites
+ * (save/publish/delete/restore handlers, capability middleware,
+ * principal middleware) and the operator's chosen audit sink.
+ *
+ * # The contract
+ *
+ * Per `design-audit.md`'s "Surface-specific contract":
+ *
+ *   - `record(event)` — write an `AuditEvent` to the sink. MUST
+ *     NOT throw on transport errors; falls back to local-only
+ *     recording on failure (the dispatcher in Cut 3 catches +
+ *     logs via `AuditTransportError`).
+ *   - `query(filter)` — optional. Providers that own queryable
+ *     storage implement this; external-sink providers (webhook,
+ *     OTel) omit it.
+ *   - `queryUrl()` — optional. Returns a deep-link to the
+ *     operator's destination console (CloudWatch / Azure Monitor
+ *     URLs). Providers that own queryable storage typically omit.
+ *
+ * # Plugin promotion path
+ *
+ * Per ADR-0009 + `design-plugins.md`: external audit providers
+ * ship as npm packages exporting factory functions returning
+ * `AuditProvider`. Operators import + invoke at the audit config
+ * field (Pattern 3 — multi-provider fan-out via `auditChain([...])`
+ * when shipped). No runtime register method.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: each provider owns one sink's mechanics; no cross-cutting
+ *     concerns.
+ *   - LSP: every provider returns events shaped by `AuditEvent`;
+ *     consumers branch only on `outcome` / `action` for behavior.
+ *   - DIP: recorder + drawer depend on this interface, never on
+ *     concrete classes.
+ *   - ISP: interface stays narrow — record + optional query + optional
+ *     queryUrl. No capability-detection methods every provider must
+ *     stub out.
+ */
+import type { AuditEvent, AuditQuery } from './types.js';
+export interface AuditProvider {
+    /**
+     * Stable name. Used in failure log entries and in the audit
+     * drawer's "View in {name}" deep-link button. Convention:
+     * lowercase-kebab-case (`'history'`, `'cloudwatch'`,
+     * `'http-webhook'`).
+     */
+    readonly name: string;
+    /**
+     * Record an audit event. MUST NOT throw on transport errors;
+     * fall back to local recording on failure. Audit failures never
+     * block writes (fail-open default; strict mode opt-in via
+     * `admin.audit.strict: true` — handled by the recorder dispatcher
+     * in Cut 3).
+     */
+    record(event: AuditEvent): Promise<void>;
+    /**
+     * Optional — providers that own queryable storage implement this.
+     * External-sink providers that push events elsewhere (CloudWatch,
+     * webhook, OTel) omit it; the audit drawer falls back to a deep
+     * link from `queryUrl()` in those cases.
+     */
+    query?(filter: AuditQuery): Promise<AuditEvent[]>;
+    /**
+     * Optional — providers that push to an external destination
+     * return a deep-link to the operator's destination console.
+     * Returning `null` means "configured but no link available."
+     * Providers that own queryable storage typically omit this.
+     */
+    queryUrl?(): string | null;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/audit/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/audit/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAExD,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxC;;;;;OAKG;IACH,KAAK,CAAC,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;IACjD;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,MAAM,GAAG,IAAI,CAAA;CAC3B"}

package/dist/audit/provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=provider.js.map

package/dist/audit/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/audit/provider.ts"],"names":[],"mappings":""}

package/dist/audit/providers/history.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `HistoryAuditProvider` — v1 in-tree audit provider that stores
+ * events in the target's `.gazetta/audit/events.jsonl` file.
+ *
+ * # Why JSONL, not extending Revisions
+ *
+ * Per `design-audit.md`: "Audit and history are conceptually peer
+ * surfaces. v1 ships them unified in HistoryAuditProvider (writes a
+ * revision on success; writes an audit event on every outcome)."
+ *
+ * The simplest unified shape: history-recorder keeps writing
+ * Revisions for the success path (existing primitive, unchanged);
+ * audit events live in a parallel JSONL file under the same
+ * `.gazetta/` namespace. Failure outcomes (forbidden /
+ * validation-failed / unauthenticated) write only to the audit log
+ * (no content snapshot — there was no successful write to record).
+ * Success outcomes write to BOTH (revision in `.gazetta/history/`,
+ * audit event in `.gazetta/audit/events.jsonl`); the audit-event
+ * carries the actor + outcome + scope context the revision shape
+ * predates.
+ *
+ * The alternative — extending `Revision` with `actor` + `outcome` —
+ * forces the existing history machinery to handle audit-only
+ * revisions (no snapshot). Rather than complicate history-recorder
+ * with optional-snapshot revision flow, the audit log gets its own
+ * append-only file. v1 validation: simpler shape; same multi-instance
+ * guarantees.
+ *
+ * # Multi-instance correctness
+ *
+ * One file per instance. Each admin process writes to
+ * `events-{instance-id}.jsonl` so concurrent appends don't race.
+ * Reads aggregate via `readDir` + concat. Same pattern as
+ * design-audit.md "v2 reserved" notes for `FileAuditProvider`:
+ * "filesystem POSIX `O_APPEND` for small writes; R2/S3/Azure use
+ * per-instance file (`events.{instance-id}.jsonl`)".
+ *
+ * v1 is per-instance file unconditionally — no special-casing
+ * filesystem vs cloud storage. Filesystem operators pay one extra
+ * file per process (negligible); cloud-storage operators get the
+ * concurrency safety they need.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this provider only writes/reads JSONL. Recording dispatch,
+ *     pseudonymization, and source-IP extraction live elsewhere.
+ *   - LSP: implements `AuditProvider`; consumers don't know it's
+ *     filesystem-backed.
+ *   - DIP: takes a `StorageProvider` instance — works against
+ *     filesystem, R2, S3, Azure Blob uniformly.
+ */
+import type { StorageProvider } from '../../types.js';
+import type { AuditProvider } from '../provider.js';
+export interface HistoryAuditProviderOptions {
+    /** Storage provider for the target. Audit events live under `.gazetta/audit/`. */
+    storage: StorageProvider;
+    /**
+     * Per-process instance identifier. Disambiguates JSONL file
+     * names for multi-instance correctness. Production resolves
+     * this from K_REVISION (Cloud Run) → os.hostname() → random
+     * 8-char hex (per design-logging.md conventions).
+     */
+    instance: string;
+}
+export declare function createHistoryAuditProvider(opts: HistoryAuditProviderOptions): AuditProvider;
+//# sourceMappingURL=history.d.ts.map

package/dist/audit/providers/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../../src/audit/providers/history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD,MAAM,WAAW,2BAA2B;IAC1C,kFAAkF;IAClF,OAAO,EAAE,eAAe,CAAA;IACxB;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAA;CACjB;AAID,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,2BAA2B,GAAG,aAAa,CA0F3F"}

package/dist/audit/providers/history.js

@@ -0,0 +1,102 @@
+const AUDIT_DIR = '.gazetta/audit';
+export function createHistoryAuditProvider(opts) {
+    const { storage, instance } = opts;
+    const eventsPath = `${AUDIT_DIR}/events-${instance}.jsonl`;
+    async function appendEvent(event) {
+        // Read-modify-write per call. JSONL append-only on filesystem
+        // would be cheaper, but cloud StorageProvider (R2/S3/Azure)
+        // doesn't expose append — every write is whole-object replace.
+        // The per-instance file scoping makes RMW safe (no other
+        // instance writes to this file); the cost is one extra read
+        // per event. Acceptable for v1 latency budget (50-200ms).
+        let existing = '';
+        try {
+            existing = await storage.readFile(eventsPath);
+        }
+        catch {
+            // First write — file doesn't exist yet. Create the directory
+            // if the storage provider needs it (filesystem mkdir).
+            await storage.mkdir(AUDIT_DIR).catch(() => {
+                // Provider may not require mkdir (S3/R2 have no concept);
+                // swallow.
+            });
+        }
+        const line = JSON.stringify(event) + '\n';
+        await storage.writeFile(eventsPath, existing + line);
+    }
+    async function readAllEvents() {
+        // List all instance files + concat. readDir returns DirEntry
+        // shapes; we filter to the events-*.jsonl pattern so unrelated
+        // files (audit-index sidecars in the future) don't get parsed
+        // as events.
+        let entries;
+        try {
+            entries = await storage.readDir(AUDIT_DIR);
+        }
+        catch {
+            // No audit directory yet — nothing to read.
+            return [];
+        }
+        const events = [];
+        for (const entry of entries) {
+            if (entry.isDirectory)
+                continue;
+            if (!entry.name.startsWith('events-') || !entry.name.endsWith('.jsonl'))
+                continue;
+            const content = await storage.readFile(`${AUDIT_DIR}/${entry.name}`);
+            for (const line of content.split('\n')) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    events.push(JSON.parse(trimmed));
+                }
+                catch {
+                    // Malformed line — skip. A corrupt single line shouldn't
+                    // poison the whole query. Future: structured-log this.
+                }
+            }
+        }
+        return events;
+    }
+    function matchesFilter(event, filter) {
+        if (filter.action && event.action !== filter.action)
+            return false;
+        if (filter.outcome && event.outcome !== filter.outcome)
+            return false;
+        if (filter.scope?.kind && event.scope.kind !== filter.scope.kind)
+            return false;
+        if (filter.scope?.name && event.scope.name !== filter.scope.name)
+            return false;
+        if (filter.actor) {
+            const needle = filter.actor.toLowerCase();
+            const idMatch = event.actor.id.toLowerCase().includes(needle);
+            const emailMatch = event.actor.email?.toLowerCase().includes(needle) ?? false;
+            if (!idMatch && !emailMatch)
+                return false;
+        }
+        if (filter.since && event.timestamp < filter.since)
+            return false;
+        if (filter.until && event.timestamp >= filter.until)
+            return false;
+        return true;
+    }
+    return {
+        name: 'history',
+        async record(event) {
+            await appendEvent(event);
+        },
+        async query(filter) {
+            const all = await readAllEvents();
+            // Sort newest-first per audit-drawer convention. Stable sort
+            // by timestamp (string compare on ISO-8601 works correctly).
+            all.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+            const matched = all.filter(e => matchesFilter(e, filter));
+            const limit = filter.limit ?? 100;
+            return matched.slice(0, Math.min(limit, 1000));
+        },
+        // queryUrl intentionally omitted — HistoryAuditProvider has
+        // queryable storage; the drawer reads via query() directly.
+    };
+}
+//# sourceMappingURL=history.js.map

package/dist/audit/providers/history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.js","sourceRoot":"","sources":["../../../src/audit/providers/history.ts"],"names":[],"mappings":"AAmEA,MAAM,SAAS,GAAG,gBAAgB,CAAA;AAElC,MAAM,UAAU,0BAA0B,CAAC,IAAiC;IAC1E,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAA;IAClC,MAAM,UAAU,GAAG,GAAG,SAAS,WAAW,QAAQ,QAAQ,CAAA;IAE1D,KAAK,UAAU,WAAW,CAAC,KAAiB;QAC1C,8DAA8D;QAC9D,4DAA4D;QAC5D,+DAA+D;QAC/D,yDAAyD;QACzD,4DAA4D;QAC5D,0DAA0D;QAC1D,IAAI,QAAQ,GAAG,EAAE,CAAA;QACjB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAA;QAC/C,CAAC;QAAC,MAAM,CAAC;YACP,6DAA6D;YAC7D,uDAAuD;YACvD,MAAM,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;gBACxC,0DAA0D;gBAC1D,WAAW;YACb,CAAC,CAAC,CAAA;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAA;QACzC,MAAM,OAAO,CAAC,SAAS,CAAC,UAAU,EAAE,QAAQ,GAAG,IAAI,CAAC,CAAA;IACtD,CAAC;IAED,KAAK,UAAU,aAAa;QAC1B,6DAA6D;QAC7D,+DAA+D;QAC/D,8DAA8D;QAC9D,aAAa;QACb,IAAI,OAAwD,CAAA;QAC5D,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,4CAA4C;YAC5C,OAAO,EAAE,CAAA;QACX,CAAC;QACD,MAAM,MAAM,GAAiB,EAAE,CAAA;QAC/B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,KAAK,CAAC,WAAW;gBAAE,SAAQ;YAC/B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAAE,SAAQ;YACjF,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,GAAG,SAAS,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;YACpE,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;gBACvC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;gBAC3B,IAAI,CAAC,OAAO;oBAAE,SAAQ;gBACtB,IAAI,CAAC;oBACH,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAe,CAAC,CAAA;gBAChD,CAAC;gBAAC,MAAM,CAAC;oBACP,yDAAyD;oBACzD,uDAAuD;gBACzD,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAA;IACf,CAAC;IAED,SAAS,aAAa,CAAC,KAAiB,EAAE,MAAkB;QAC1D,IAAI,MAAM,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM;YAAE,OAAO,KAAK,CAAA;QACjE,IAAI,MAAM,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,KAAK,MAAM,CAAC,OAAO;YAAE,OAAO,KAAK,CAAA;QACpE,IAAI,MAAM,CAAC,KAAK,EAAE,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,KAAK,CAAC,IAAI;YAAE,OAAO,KAAK,CAAA;QAC9E,IAAI,MAAM,CAAC,KAAK,EAAE,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,KAAK,CAAC,IAAI;YAAE,OAAO,KAAK,CAAA;QAC9E,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE,CAAA;YACzC,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;YAC7D,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,KAAK,CAAA;YAC7E,IAAI,CAAC,OAAO,IAAI,CAAC,UAAU;gBAAE,OAAO,KAAK,CAAA;QAC3C,CAAC;QACD,IAAI,MAAM,CAAC,KAAK,IAAI,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC,KAAK;YAAE,OAAO,KAAK,CAAA;QAChE,IAAI,MAAM,CAAC,KAAK,IAAI,KAAK,CAAC,SAAS,IAAI,MAAM,CAAC,KAAK;YAAE,OAAO,KAAK,CAAA;QACjE,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO;QACL,IAAI,EAAE,SAAS;QACf,KAAK,CAAC,MAAM,CAAC,KAAiB;YAC5B,MAAM,WAAW,CAAC,KAAK,CAAC,CAAA;QAC1B,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,MAAkB;YAC5B,MAAM,GAAG,GAAG,MAAM,aAAa,EAAE,CAAA;YACjC,6DAA6D;YAC7D,6DAA6D;YAC7D,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAA;YAC1D,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA;YACzD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,GAAG,CAAA;YACjC,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAA;QAChD,CAAC;QACD,4DAA4D;QAC5D,4DAA4D;KAC7D,CAAA;AACH,CAAC"}

package/dist/audit/pseudonymize.d.ts

@@ -0,0 +1,26 @@
+import type { AuditActor } from './types.js';
+export type ActorPseudonymMode = 'none' | 'sha256';
+/**
+ * Apply the configured pseudonymization mode to an actor snapshot.
+ *
+ *   - `'none'` (default) — pass through unchanged.
+ *   - `'sha256'` — replace `id` with the salted hash prefix; drop
+ *     `email`.
+ *
+ * The original `actor` is never mutated; returns a new object.
+ *
+ * Throws when `mode === 'sha256'` and `salt` is empty/undefined —
+ * pseudonymization without a salt is a misconfiguration that would
+ * silently produce reversible-by-rainbow-table hashes. Caller (Cut
+ * 5's wiring) should catch this at boot via `AuditConfigurationError`
+ * when the env var is missing.
+ */
+export declare function pseudonymizeActor(actor: AuditActor, mode: ActorPseudonymMode, salt?: string): AuditActor;
+/**
+ * Compute the pseudonymized id for an actor — exposed for forensic
+ * queries: an operator who knows the upstream sub + salt can
+ * compute the pseudonymized id and search the audit log without
+ * the recorder being involved.
+ */
+export declare function computePseudonymizedId(rawSub: string, salt: string): string;
+//# sourceMappingURL=pseudonymize.d.ts.map

package/dist/audit/pseudonymize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pseudonymize.d.ts","sourceRoot":"","sources":["../../src/audit/pseudonymize.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,QAAQ,CAAA;AAElD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAkBxG;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAK3E"}

package/dist/audit/pseudonymize.js

@@ -0,0 +1,86 @@
+/**
+ * Actor pseudonymization — opt-in privacy hardening for audit events.
+ *
+ * Per `design-audit.md`'s "Pseudonymization" section: when
+ * `admin.audit.actorPseudonym: 'sha256'` is configured, the event's
+ * `actor.id` is replaced with `sha256(sub + GAZETTA_AUDIT_ACTOR_SALT)
+ * .slice(0, 16)`. The `actor.email` field is dropped (low-entropy
+ * email gives weak pseudonymization).
+ *
+ * # When to opt in
+ *
+ * - External-sink configurations where audit events leave Gazetta's
+ *   process boundary (CloudWatch, OTel, webhook) — limits PII
+ *   leakage if sink storage is compromised
+ * - Regulated contexts demanding pseudonymization-by-default (some
+ *   EU healthcare contexts, German telecommunications data
+ *   retention)
+ * - Multi-tenant SIEM correlation with shared salt across systems
+ *
+ * # Salt management
+ *
+ * - Salt is a credential. Stored in `GAZETTA_AUDIT_ACTOR_SALT` env
+ *   var per Universal Provider Requirement #3. Never in
+ *   `site.config.ts`.
+ * - 16+ random bytes recommended.
+ * - Salt rotation breaks historic correlation by design — rotate
+ *   per security policy (annually typical); document rotation
+ *   dates so forensic queries can scope by salt-era.
+ * - Multi-instance: every instance reads the same env → deterministic
+ *   hash across instances.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: pseudonymization only. Doesn't dispatch, doesn't extract
+ *     identity. Pure function over `(actor, mode)`.
+ *   - DIP: takes the salt as a string parameter (dependency-injected
+ *     by the caller); doesn't read `process.env` directly so tests
+ *     can pass deterministic salts.
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Apply the configured pseudonymization mode to an actor snapshot.
+ *
+ *   - `'none'` (default) — pass through unchanged.
+ *   - `'sha256'` — replace `id` with the salted hash prefix; drop
+ *     `email`.
+ *
+ * The original `actor` is never mutated; returns a new object.
+ *
+ * Throws when `mode === 'sha256'` and `salt` is empty/undefined —
+ * pseudonymization without a salt is a misconfiguration that would
+ * silently produce reversible-by-rainbow-table hashes. Caller (Cut
+ * 5's wiring) should catch this at boot via `AuditConfigurationError`
+ * when the env var is missing.
+ */
+export function pseudonymizeActor(actor, mode, salt) {
+    if (mode === 'none')
+        return actor;
+    // mode === 'sha256'
+    if (!salt || salt.length === 0) {
+        throw new Error('actorPseudonym: sha256 requires a non-empty salt (set GAZETTA_AUDIT_ACTOR_SALT environment variable)');
+    }
+    const hash = createHash('sha256')
+        .update(actor.id + salt)
+        .digest('hex')
+        .slice(0, 16);
+    return {
+        id: hash,
+        // email dropped — low-entropy email gives weak pseudonymization.
+        role: actor.role,
+        trustMode: actor.trustMode,
+    };
+}
+/**
+ * Compute the pseudonymized id for an actor — exposed for forensic
+ * queries: an operator who knows the upstream sub + salt can
+ * compute the pseudonymized id and search the audit log without
+ * the recorder being involved.
+ */
+export function computePseudonymizedId(rawSub, salt) {
+    return createHash('sha256')
+        .update(rawSub + salt)
+        .digest('hex')
+        .slice(0, 16);
+}
+//# sourceMappingURL=pseudonymize.js.map

package/dist/audit/pseudonymize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pseudonymize.js","sourceRoot":"","sources":["../../src/audit/pseudonymize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAKxC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAiB,EAAE,IAAwB,EAAE,IAAa;IAC1F,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,KAAK,CAAA;IACjC,oBAAoB;IACpB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,sGAAsG,CACvG,CAAA;IACH,CAAC;IACD,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC;SAC9B,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC;SACvB,MAAM,CAAC,KAAK,CAAC;SACb,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IACf,OAAO;QACL,EAAE,EAAE,IAAI;QACR,iEAAiE;QACjE,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,SAAS,EAAE,KAAK,CAAC,SAAS;KAC3B,CAAA;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAc,EAAE,IAAY;IACjE,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC;SACrB,MAAM,CAAC,KAAK,CAAC;SACb,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;AACjB,CAAC"}

package/dist/audit/recorder.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Audit-recording dispatcher. The fan-out + fail-open layer that
+ * separates recording sites (save/publish/delete/restore handlers)
+ * from individual `AuditProvider` implementations.
+ *
+ * # Locked design — synchronous fail-open, parallel fan-out
+ *
+ * Per `design-audit.md`'s "Recording timing":
+ *
+ *   - **Synchronous** — operation awaits the audit attempt. If the
+ *     user got a success response, the audit attempt was completed.
+ *     Async queuing would lose in-flight events on process restart.
+ *   - **Fail-open by default** — provider failures never block the
+ *     write. Operators in compliance contexts opt into `strict: true`
+ *     (any provider failure blocks the write).
+ *   - **Parallel fan-out** — `Promise.allSettled` so two providers'
+ *     latencies don't stack. Failures are independent.
+ *
+ * # Failure log — no payload
+ *
+ * Per Universal Provider Requirement #5: "When audit recording fails
+ * (fail-open), the failure log entry MUST NOT contain event payload."
+ * The recorder logs only `{ provider, eventId, category }` — never
+ * the actor, scope, or metadata. Prevents PII side-channels into
+ * application stderr / log shipping.
+ *
+ * # Strict mode
+ *
+ * For HIPAA / SOC 2 compliance contexts where "audit recording
+ * confirmed successful" is a hard prerequisite for the write to
+ * proceed. The recorder's caller (Cut 5's wired handlers) checks
+ * the `failed` flag in the result and aborts the write when strict
+ * mode is on.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: dispatch + failure-log only. Doesn't construct providers,
+ *     doesn't extract identity (Cut 4 handles privacy / source-IP
+ *     extraction).
+ *   - DIP: takes a `readonly AuditProvider[]` and an opaque logger
+ *     callback; no coupling to specific providers or to Hono.
+ */
+import type { AuditEvent } from './types.js';
+import type { AuditProvider } from './provider.js';
+export interface AuditFailureLog {
+    /** Provider name that failed. Per design: log identifies which sink dropped. */
+    provider: string;
+    /**
+     * Categorical reason — `transport` for network/HTTP failures,
+     * `serialize` for unparseable events, `quota` for sink full.
+     * Surface to log aggregators for filtering.
+     */
+    category: 'transport' | 'serialize' | 'quota';
+    /** Reason text for diagnostics. PII-free; never the event payload. */
+    reason: string;
+}
+/**
+ * Logger callback signature. Production wires to `pino` per
+ * `design-logging.md`; tests inject stubs to assert shape + count.
+ *
+ * Note: NEVER receives the event payload. The logger contract is
+ * narrow on purpose — operator's log-shipping pipeline can't
+ * accidentally surface PII via the audit failure path.
+ */
+export type AuditFailureLogger = (entry: AuditFailureLog) => void;
+export interface RecordToAllOptions {
+    /** Providers to fan out to. Order doesn't matter (parallel). */
+    providers: ReadonlyArray<AuditProvider>;
+    /**
+     * Strict mode flag. `true` → caller blocks the write on any
+     * provider failure (per design-audit.md "Strict mode opt-in").
+     * `false` (default) → fail-open; operations always proceed.
+     */
+    strict?: boolean;
+    /**
+     * Failure logger. Production wires `pino`. Tests inject `vi.fn()`.
+     * When undefined, failures pass silently — useful for tests that
+     * don't care about log output, but production should always wire
+     * a real logger for diagnosability.
+     */
+    logFailure?: AuditFailureLogger;
+}
+export interface RecordResult {
+    /** Number of providers that successfully recorded. */
+    succeeded: number;
+    /**
+     * Number of providers that failed. Always 0 when no providers are
+     * configured. Caller uses this in strict mode to abort the write.
+     */
+    failed: number;
+    /** Per-provider failure entries — for diagnostic surfaces. */
+    failures: ReadonlyArray<AuditFailureLog>;
+}
+/**
+ * Fan-out an event to every configured provider in parallel.
+ * Returns counts + per-failure entries; never throws (per Universal
+ * Provider Requirement #5). Strict-mode behavior is the caller's
+ * concern — the recorder does the dispatch + log; the caller branches
+ * on `result.failed > 0` to abort the write.
+ */
+export declare function recordToAll(event: AuditEvent, opts: RecordToAllOptions): Promise<RecordResult>;
+//# sourceMappingURL=recorder.d.ts.map

package/dist/audit/recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../../src/audit/recorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAElD,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,QAAQ,EAAE,WAAW,GAAG,WAAW,GAAG,OAAO,CAAA;IAC7C,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAA;AAEjE,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,SAAS,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;IACvC;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAA;CAChC;AAED,MAAM,WAAW,YAAY;IAC3B,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,8DAA8D;IAC9D,QAAQ,EAAE,aAAa,CAAC,eAAe,CAAC,CAAA;CACzC;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAuBpG"}

package/dist/audit/recorder.js

@@ -0,0 +1,55 @@
+/**
+ * Fan-out an event to every configured provider in parallel.
+ * Returns counts + per-failure entries; never throws (per Universal
+ * Provider Requirement #5). Strict-mode behavior is the caller's
+ * concern — the recorder does the dispatch + log; the caller branches
+ * on `result.failed > 0` to abort the write.
+ */
+export async function recordToAll(event, opts) {
+    const { providers, logFailure } = opts;
+    if (providers.length === 0)
+        return { succeeded: 0, failed: 0, failures: [] };
+    const results = await Promise.allSettled(providers.map(p => p.record(event)));
+    const failures = [];
+    let succeeded = 0;
+    for (let i = 0; i < results.length; i++) {
+        const result = results[i];
+        const provider = providers[i];
+        if (result.status === 'fulfilled') {
+            succeeded++;
+            continue;
+        }
+        const entry = {
+            provider: provider.name,
+            category: categorizeFailure(result.reason),
+            reason: extractReason(result.reason),
+        };
+        failures.push(entry);
+        logFailure?.(entry);
+    }
+    return { succeeded, failed: failures.length, failures };
+}
+/**
+ * Categorize a thrown reason into the closed-enum category. Maps
+ * `AuditTransportError.category` directly when present; falls back
+ * to `'transport'` for unknown errors (most common — provider
+ * SDKs rarely throw structured failure types).
+ */
+function categorizeFailure(reason) {
+    if (reason instanceof Error) {
+        // AuditTransportError carries category as a typed field.
+        const maybeCategory = reason.category;
+        if (maybeCategory === 'transport' || maybeCategory === 'serialize' || maybeCategory === 'quota') {
+            return maybeCategory;
+        }
+    }
+    return 'transport';
+}
+function extractReason(reason) {
+    if (reason instanceof Error)
+        return reason.message;
+    if (typeof reason === 'string')
+        return reason;
+    return 'unknown failure';
+}
+//# sourceMappingURL=recorder.js.map

package/dist/audit/recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.js","sourceRoot":"","sources":["../../src/audit/recorder.ts"],"names":[],"mappings":"AAkGA;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,KAAiB,EAAE,IAAwB;IAC3E,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,IAAI,CAAA;IACtC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAA;IAE5E,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IAC7E,MAAM,QAAQ,GAAsB,EAAE,CAAA;IACtC,IAAI,SAAS,GAAG,CAAC,CAAA;IACjB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;QACzB,MAAM,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,CAAA;QAC7B,IAAI,MAAM,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;YAClC,SAAS,EAAE,CAAA;YACX,SAAQ;QACV,CAAC;QACD,MAAM,KAAK,GAAoB;YAC7B,QAAQ,EAAE,QAAQ,CAAC,IAAI;YACvB,QAAQ,EAAE,iBAAiB,CAAC,MAAM,CAAC,MAAM,CAAC;YAC1C,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC;SACrC,CAAA;QACD,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACpB,UAAU,EAAE,CAAC,KAAK,CAAC,CAAA;IACrB,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAA;AACzD,CAAC;AAED;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,MAAe;IACxC,IAAI,MAAM,YAAY,KAAK,EAAE,CAAC;QAC5B,yDAAyD;QACzD,MAAM,aAAa,GAAI,MAAiC,CAAC,QAAQ,CAAA;QACjE,IAAI,aAAa,KAAK,WAAW,IAAI,aAAa,KAAK,WAAW,IAAI,aAAa,KAAK,OAAO,EAAE,CAAC;YAChG,OAAO,aAAa,CAAA;QACtB,CAAC;IACH,CAAC;IACD,OAAO,WAAW,CAAA;AACpB,CAAC;AAED,SAAS,aAAa,CAAC,MAAe;IACpC,IAAI,MAAM,YAAY,KAAK;QAAE,OAAO,MAAM,CAAC,OAAO,CAAA;IAClD,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAA;IAC7C,OAAO,iBAAiB,CAAA;AAC1B,CAAC"}

package/dist/audit/retention.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Audit retention pruner.
+ *
+ * Per design-audit.md "Retention": audit retention is configurable
+ * independently from content history retention. Two dimensions:
+ *
+ *   - `events` — max event count kept across all per-instance JSONL
+ *     files. When exceeded, oldest events evicted (timestamp-sort
+ *     ascending; drop from the head).
+ *   - `maxAgeMonths` — max age in months. Events older than the
+ *     cutoff evicted regardless of count.
+ *
+ * Operator sets one or both. When neither set, the pruner is a no-op
+ * (audit accumulates indefinitely until storage budget exhausted —
+ * operator's choice; documented).
+ *
+ * # JSONL storage shape
+ *
+ * Per `HistoryAuditProvider`, events live in
+ * `.gazetta/audit/events-{instance-id}.jsonl` — one file per admin
+ * instance. The pruner walks every events file, parses lines into
+ * AuditEvent objects, applies retention, and rewrites each file with
+ * the surviving lines. Per-file rewrite preserves the per-instance
+ * scoping (no cross-instance interleaving).
+ *
+ * # Multi-instance correctness
+ *
+ * Per-revision file granularity (each instance's file is independent)
+ * means concurrent pruners on the same target converge. If instance A
+ * is rewriting events-A.jsonl while instance B is rewriting
+ * events-B.jsonl, no race. If two pruners on different hosts try to
+ * rewrite the SAME events-A.jsonl simultaneously (two instances with
+ * the same hostname / K_REVISION), the storage provider's atomic
+ * write-then-rename keeps the file consistent — last-write-wins is
+ * fine because both pruners compute the same surviving set from the
+ * same input bytes.
+ *
+ * # Why JSONL-line pruning, not whole-file deletion
+ *
+ * The pruner has to handle events file-by-file because:
+ *   - Different instances have different event mixes; deleting an
+ *     entire instance's file would lose events newer than the cutoff
+ *   - Events within one instance's file span time; some pruned, some
+ *     kept — selective line removal is the right granularity
+ *
+ * # Returns: PruneResult
+ *
+ * Diagnostic info for the caller's log + metrics. `eventsKept` and
+ * `eventsEvicted` together = total events pre-prune.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: retention only; doesn't construct providers, doesn't
+ *     audit pruner-events itself (would create recursion).
+ *   - DIP: takes a StorageProvider — works against filesystem, R2,
+ *     S3, Azure Blob uniformly.
+ */
+import type { StorageProvider } from '../types.js';
+export interface AuditRetentionConfig {
+    /** Max event count kept. When exceeded, oldest evicted. */
+    events?: number;
+    /** Max age in months. Events older than the cutoff evicted. */
+    maxAgeMonths?: number | null;
+}
+export interface PruneResult {
+    /** Number of events present before pruning. */
+    eventsBefore: number;
+    /** Number of events surviving. */
+    eventsKept: number;
+    /** Number of events evicted. */
+    eventsEvicted: number;
+    /** Files rewritten (only files with at least one eviction). */
+    filesRewritten: number;
+    /** Files inspected (every events file under .gazetta/audit/). */
+    filesInspected: number;
+}
+/**
+ * Walk the audit JSONL files, evict events that violate retention,
+ * rewrite each affected file. No-op when retention config has neither
+ * `events` nor `maxAgeMonths` set.
+ */
+export declare function pruneAuditEvents(storage: StorageProvider, config: AuditRetentionConfig): Promise<PruneResult>;
+//# sourceMappingURL=retention.d.ts.map

package/dist/audit/retention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.d.ts","sourceRoot":"","sources":["../../src/audit/retention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAGlD,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAA;IACpB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAA;IAClB,gCAAgC;IAChC,aAAa,EAAE,MAAM,CAAA;IACrB,+DAA+D;IAC/D,cAAc,EAAE,MAAM,CAAA;IACtB,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAA;CACvB;AAID;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC,CA0HnH"}