gazetta 0.7.0 → 0.8.0

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"}

package/dist/audit/retention.js

@@ -0,0 +1,142 @@
+const AUDIT_DIR = '.gazetta/audit';
+/**
+ * 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 async function pruneAuditEvents(storage, config) {
+    // No retention configured → no-op. Operator opted out or never opted in.
+    const hasEventsCap = config.events !== undefined && config.events !== null;
+    const hasAgeCap = config.maxAgeMonths !== undefined && config.maxAgeMonths !== null && config.maxAgeMonths > 0;
+    if (!hasEventsCap && !hasAgeCap) {
+        return { eventsBefore: 0, eventsKept: 0, eventsEvicted: 0, filesRewritten: 0, filesInspected: 0 };
+    }
+    // Compute the age cutoff once so all files use the same boundary.
+    // `maxAgeMonths` is a real-month subtraction (Date.setMonth handles
+    // leap years + variable month length); ISO-8601 string compare works
+    // on the resulting timestamp.
+    const ageCutoff = hasAgeCap ? computeAgeCutoff(config.maxAgeMonths) : null;
+    // Walk the events directory. Missing dir = no events to prune.
+    let entries;
+    try {
+        entries = await storage.readDir(AUDIT_DIR);
+    }
+    catch {
+        return { eventsBefore: 0, eventsKept: 0, eventsEvicted: 0, filesRewritten: 0, filesInspected: 0 };
+    }
+    // Read every events file into memory with its source path. We need
+    // the global event count for `events` cap enforcement (oldest-across-
+    // files evicted, not per-file), so we collect all events first.
+    const filesInspected = [];
+    for (const entry of entries) {
+        if (entry.isDirectory)
+            continue;
+        if (!entry.name.startsWith('events-') || !entry.name.endsWith('.jsonl'))
+            continue;
+        const path = `${AUDIT_DIR}/${entry.name}`;
+        const content = await storage.readFile(path);
+        const lines = content.split('\n');
+        const events = [];
+        let rawLineCount = 0;
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            rawLineCount++;
+            try {
+                events.push(JSON.parse(trimmed));
+            }
+            catch {
+                // Malformed line — skip + count as raw line so the rewrite
+                // doesn't accidentally include it. Same posture as the reader
+                // in HistoryAuditProvider.
+            }
+        }
+        filesInspected.push({ path, events, rawLineCount });
+    }
+    const eventsBefore = filesInspected.reduce((sum, f) => sum + f.events.length, 0);
+    if (eventsBefore === 0) {
+        return {
+            eventsBefore: 0,
+            eventsKept: 0,
+            eventsEvicted: 0,
+            filesRewritten: 0,
+            filesInspected: filesInspected.length,
+        };
+    }
+    // Phase 1: age cutoff (per-file evaluation; events older than the
+    // cutoff are evicted regardless of where they sit in the global
+    // ordering).
+    for (const file of filesInspected) {
+        if (ageCutoff !== null) {
+            file.events = file.events.filter(e => e.timestamp >= ageCutoff);
+        }
+    }
+    // Phase 2: count cap (global). Build the global ordering once:
+    // sort all surviving events by timestamp (oldest first), evict
+    // from the head until we're under the cap. The eviction set is
+    // matched back to its source file by reference identity.
+    let evictedFromCap = new Set();
+    if (hasEventsCap) {
+        const allSurviving = [];
+        for (const file of filesInspected) {
+            for (const event of file.events) {
+                allSurviving.push({ file, event });
+            }
+        }
+        allSurviving.sort((a, b) => a.event.timestamp.localeCompare(b.event.timestamp));
+        const overflow = allSurviving.length - config.events;
+        if (overflow > 0) {
+            evictedFromCap = new Set(allSurviving.slice(0, overflow).map(x => x.event));
+        }
+    }
+    // Phase 3: rewrite each file whose surviving set differs from the
+    // pre-prune set. Reasons a file rewrites:
+    //   - age-cutoff already mutated `file.events`
+    //   - count-cap is going to evict additional events
+    //   - malformed JSONL lines on disk (rawLineCount > parsed events) —
+    //     incidental hygiene; the line never made it through parse and
+    //     wouldn't survive a re-read either, so we drop it during the
+    //     rewrite. Doesn't count toward `eventsEvicted` (the metric
+    //     reports parsed-event deltas only).
+    let filesRewritten = 0;
+    let eventsKeptTotal = 0;
+    for (const file of filesInspected) {
+        const surviving = evictedFromCap.size > 0 ? file.events.filter(e => !evictedFromCap.has(e)) : file.events;
+        eventsKeptTotal += surviving.length;
+        const parsedDelta = file.events.length - surviving.length;
+        const malformedLines = file.rawLineCount - file.events.length;
+        if (parsedDelta === 0 && malformedLines === 0)
+            continue;
+        // Rewrite. JSONL convention: one event per line + trailing newline.
+        // Empty file (all events pruned) → write an empty string so the
+        // file remains as a marker (deleting would force concurrent
+        // appenders to mkdir; safer to keep the file with a zero-line body).
+        const rewritten = surviving.map(e => JSON.stringify(e)).join('\n');
+        const final = rewritten ? rewritten + '\n' : '';
+        await storage.writeFile(file.path, final);
+        filesRewritten++;
+    }
+    return {
+        eventsBefore,
+        eventsKept: eventsKeptTotal,
+        eventsEvicted: eventsBefore - eventsKeptTotal,
+        filesRewritten,
+        filesInspected: filesInspected.length,
+    };
+}
+/**
+ * Subtract `months` calendar months from `now` and return the ISO
+ * timestamp boundary. Events with `timestamp >= cutoff` are kept;
+ * older events evicted.
+ *
+ * Uses Date.setMonth so leap years and variable-length months are
+ * handled correctly (3 months back from 2026-05-31 is 2026-02-28,
+ * not 2026-02-31).
+ */
+function computeAgeCutoff(months) {
+    const cutoff = new Date();
+    cutoff.setMonth(cutoff.getMonth() - months);
+    return cutoff.toISOString();
+}
+//# sourceMappingURL=retention.js.map

package/dist/audit/retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.js","sourceRoot":"","sources":["../../src/audit/retention.ts"],"names":[],"mappings":"AAgFA,MAAM,SAAS,GAAG,gBAAgB,CAAA;AAElC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAAwB,EAAE,MAA4B;IAC3F,yEAAyE;IACzE,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,CAAA;IAC1E,MAAM,SAAS,GAAG,MAAM,CAAC,YAAY,KAAK,SAAS,IAAI,MAAM,CAAC,YAAY,KAAK,IAAI,IAAI,MAAM,CAAC,YAAY,GAAG,CAAC,CAAA;IAC9G,IAAI,CAAC,YAAY,IAAI,CAAC,SAAS,EAAE,CAAC;QAChC,OAAO,EAAE,YAAY,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,CAAA;IACnG,CAAC;IAED,kEAAkE;IAClE,oEAAoE;IACpE,qEAAqE;IACrE,8BAA8B;IAC9B,MAAM,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,YAAa,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAE3E,+DAA+D;IAC/D,IAAI,OAAwD,CAAA;IAC5D,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,YAAY,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,CAAA;IACnG,CAAC;IAED,mEAAmE;IACnE,sEAAsE;IACtE,gEAAgE;IAChE,MAAM,cAAc,GAAmE,EAAE,CAAA;IACzF,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,WAAW;YAAE,SAAQ;QAC/B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAAE,SAAQ;QACjF,MAAM,IAAI,GAAG,GAAG,SAAS,IAAI,KAAK,CAAC,IAAI,EAAE,CAAA;QACzC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;QAC5C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QACjC,MAAM,MAAM,GAAiB,EAAE,CAAA;QAC/B,IAAI,YAAY,GAAG,CAAC,CAAA;QACpB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;YAC3B,IAAI,CAAC,OAAO;gBAAE,SAAQ;YACtB,YAAY,EAAE,CAAA;YACd,IAAI,CAAC;gBACH,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAe,CAAC,CAAA;YAChD,CAAC;YAAC,MAAM,CAAC;gBACP,2DAA2D;gBAC3D,8DAA8D;gBAC9D,2BAA2B;YAC7B,CAAC;QACH,CAAC;QACD,cAAc,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAA;IACrD,CAAC;IAED,MAAM,YAAY,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;IAChF,IAAI,YAAY,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO;YACL,YAAY,EAAE,CAAC;YACf,UAAU,EAAE,CAAC;YACb,aAAa,EAAE,CAAC;YAChB,cAAc,EAAE,CAAC;YACjB,cAAc,EAAE,cAAc,CAAC,MAAM;SACtC,CAAA;IACH,CAAC;IAED,kEAAkE;IAClE,gEAAgE;IAChE,aAAa;IACb,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;QAClC,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACvB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,IAAI,SAAS,CAAC,CAAA;QACjE,CAAC;IACH,CAAC;IAED,+DAA+D;IAC/D,+DAA+D;IAC/D,+DAA+D;IAC/D,yDAAyD;IACzD,IAAI,cAAc,GAAG,IAAI,GAAG,EAAc,CAAA;IAC1C,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,YAAY,GAAmE,EAAE,CAAA;QACvF,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;YAClC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChC,YAAY,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;YACpC,CAAC;QACH,CAAC;QACD,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAA;QAC/E,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,GAAG,MAAM,CAAC,MAAO,CAAA;QACrD,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;YACjB,cAAc,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;QAC7E,CAAC;IACH,CAAC;IAED,kEAAkE;IAClE,0CAA0C;IAC1C,+CAA+C;IAC/C,oDAAoD;IACpD,qEAAqE;IACrE,mEAAmE;IACnE,kEAAkE;IAClE,gEAAgE;IAChE,yCAAyC;IACzC,IAAI,cAAc,GAAG,CAAC,CAAA;IACtB,IAAI,eAAe,GAAG,CAAC,CAAA;IACvB,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;QAClC,MAAM,SAAS,GAAG,cAAc,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAA;QACzG,eAAe,IAAI,SAAS,CAAC,MAAM,CAAA;QACnC,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,SAAS,CAAC,MAAM,CAAA;QACzD,MAAM,cAAc,GAAG,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAA;QAC7D,IAAI,WAAW,KAAK,CAAC,IAAI,cAAc,KAAK,CAAC;YAAE,SAAQ;QACvD,oEAAoE;QACpE,gEAAgE;QAChE,4DAA4D;QAC5D,qEAAqE;QACrE,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAClE,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;QAC/C,MAAM,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QACzC,cAAc,EAAE,CAAA;IAClB,CAAC;IAED,OAAO;QACL,YAAY;QACZ,UAAU,EAAE,eAAe;QAC3B,aAAa,EAAE,YAAY,GAAG,eAAe;QAC7C,cAAc;QACd,cAAc,EAAE,cAAc,CAAC,MAAM;KACtC,CAAA;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,gBAAgB,CAAC,MAAc;IACtC,MAAM,MAAM,GAAG,IAAI,IAAI,EAAE,CAAA;IACzB,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,MAAM,CAAC,CAAA;IAC3C,OAAO,MAAM,CAAC,WAAW,EAAE,CAAA;AAC7B,CAAC"}

package/dist/audit/source-ip.d.ts

@@ -0,0 +1,32 @@
+export type SourceIpMode = 'none' | 'raw' | 'hashed' | 'truncated';
+export interface SourceIpExtractionContext {
+    /** Trust mode determines which header carries the client IP. */
+    trustMode: string;
+    /** TCP peer IP (when available — Hono's c.req.raw.headers may not expose). */
+    peerIp?: string;
+    /** All request headers (for X-Forwarded-For / Cf-Connecting-IP / X-Real-IP lookup). */
+    headers: ReadonlyMap<string, string>;
+    /**
+     * For trust modes that read X-Forwarded-For, how many trusted
+     * proxies are between Gazetta and the client. Counts back from
+     * the rightmost; everything to the right is trusted, the
+     * resulting leftmost-of-trusted is the client.
+     *
+     * Defaults to 1 (single proxy in front of Gazetta — most common).
+     */
+    trustedProxyCount?: number;
+}
+/**
+ * Extract the client IP per the trust mode's header convention.
+ * Returns null when the configured header is missing — the caller
+ * should omit the `sourceIp` field from the event (per design:
+ * "Explicitly absent is more honest" than fake values).
+ */
+export declare function extractSourceIp(ctx: SourceIpExtractionContext): string | null;
+/**
+ * Apply the configured source-IP mode. Returns null when the mode
+ * is `'none'` OR when the extracted IP is null/empty/malformed —
+ * the caller omits the field.
+ */
+export declare function processSourceIp(rawIp: string | null, mode: SourceIpMode, salt?: string): string | null;
+//# sourceMappingURL=source-ip.d.ts.map

package/dist/audit/source-ip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-ip.d.ts","sourceRoot":"","sources":["../../src/audit/source-ip.ts"],"names":[],"mappings":"AAsCA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,WAAW,CAAA;AAElE,MAAM,WAAW,yBAAyB;IACxC,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAA;IACjB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,uFAAuF;IACvF,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACpC;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,yBAAyB,GAAG,MAAM,GAAG,IAAI,CAqC7E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkBtG"}