gazetta 0.6.0 → 0.8.0

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

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

package/dist/audit/source-ip.js

@@ -0,0 +1,164 @@
+/**
+ * Source-IP recording — opt-in per design-audit.md "Source IP
+ * recording" section. Trust-mode-driven extraction with optional
+ * pseudonymization / truncation.
+ *
+ * # Modes
+ *
+ *   - `'none'` (default) — IP not recorded; field absent from event
+ *   - `'raw'` — full IP. GDPR-personal-data; operator declares
+ *     processing
+ *   - `'hashed'` — `sha256(ip + GAZETTA_AUDIT_SOURCEIP_SALT).slice(0, 16)`
+ *     for "same source across events?" correlation without
+ *     identification. Different salt from actor (so rotating one
+ *     doesn't break the other)
+ *   - `'truncated'` — `/24` for IPv4, `/48` for IPv6. Geographic /
+ *     network-segment forensics without device identification
+ *
+ * # Trust-mode-driven extraction
+ *
+ * Per design's "Trust-mode-driven header extraction" — leftmost-XFF
+ * naive read is an OWASP Trust Boundary Violation. The IP source
+ * differs per trust mode:
+ *
+ *   - `none`              — TCP peer (no proxy assumed)
+ *   - `forwarded-user`    — X-Forwarded-For with trustedProxyCount
+ *   - `cloudflare-access` — Cf-Connecting-IP (signed/trusted)
+ *   - `azure-easy-auth`   — X-Forwarded-For (Azure appends one entry)
+ *   - `aws-cognito`       — X-Forwarded-For (ALB appends one entry)
+ *   - `tailscale`         — TCP peer (serves direct)
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: extraction + truncation/hashing only. Doesn't dispatch,
+ *     doesn't extract actor identity. Pure functions over
+ *     `(headers, mode, salt?)`.
+ */
+import { createHash } from 'node:crypto';
+/**
+ * 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 function extractSourceIp(ctx) {
+    const { trustMode, headers } = ctx;
+    switch (trustMode) {
+        case 'none':
+        case 'tailscale':
+            return ctx.peerIp ?? null;
+        case 'cloudflare-access': {
+            const cfIp = headers.get('cf-connecting-ip');
+            if (cfIp)
+                return cfIp;
+            return ctx.peerIp ?? null;
+        }
+        case 'forwarded-user':
+        case 'azure-easy-auth':
+        case 'aws-cognito': {
+            // X-Forwarded-For shape: "client, proxy1, proxy2".
+            // trustedProxyCount = N → take the (N+1)th from the RIGHT
+            // (1-indexed). For N=1 (one trusted proxy), client is the
+            // leftmost; for N=2, client is leftmost-of-leftmost-two.
+            const xff = headers.get('x-forwarded-for');
+            if (!xff)
+                return ctx.peerIp ?? null;
+            const entries = xff
+                .split(',')
+                .map(s => s.trim())
+                .filter(Boolean);
+            if (entries.length === 0)
+                return ctx.peerIp ?? null;
+            const trustedCount = ctx.trustedProxyCount ?? 1;
+            // Client position from the right: N entries trusted; client
+            // is the (N+1)th-from-right, i.e., entries[entries.length - N - 1].
+            const clientIdx = entries.length - trustedCount - 1;
+            if (clientIdx < 0)
+                return ctx.peerIp ?? null;
+            return entries[clientIdx];
+        }
+        default:
+            // Unknown trust mode (plugin-supplied future) — fall back to
+            // peer IP. Plugin authors override via custom extraction.
+            return ctx.peerIp ?? 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 function processSourceIp(rawIp, mode, salt) {
+    if (mode === 'none')
+        return null;
+    if (!rawIp || rawIp.length === 0)
+        return null;
+    if (mode === 'raw')
+        return rawIp;
+    if (mode === 'hashed') {
+        if (!salt || salt.length === 0) {
+            throw new Error('recordSourceIp: hashed requires a non-empty salt (set GAZETTA_AUDIT_SOURCEIP_SALT environment variable)');
+        }
+        return createHash('sha256')
+            .update(rawIp + salt)
+            .digest('hex')
+            .slice(0, 16);
+    }
+    // mode === 'truncated'
+    return truncateIp(rawIp);
+}
+/**
+ * Truncate an IP to /24 (IPv4) or /48 (IPv6). Returns null for
+ * malformed input — the caller treats this as "missing" and omits
+ * the field.
+ */
+function truncateIp(ip) {
+    // IPv4: 1.2.3.4 → 1.2.3.0/24
+    if (ip.includes('.') && !ip.includes(':')) {
+        const parts = ip.split('.');
+        if (parts.length !== 4)
+            return null;
+        for (const p of parts) {
+            const n = Number.parseInt(p, 10);
+            if (!Number.isInteger(n) || n < 0 || n > 255)
+                return null;
+        }
+        return `${parts[0]}.${parts[1]}.${parts[2]}.0/24`;
+    }
+    // IPv6: fe80::1234 → fe80::/48 (first 3 groups of 16 bits)
+    if (ip.includes(':')) {
+        // Expand :: shorthand if present.
+        const groups = expandIpv6Groups(ip);
+        if (!groups)
+            return null;
+        return `${groups.slice(0, 3).join(':')}::/48`;
+    }
+    return null;
+}
+function expandIpv6Groups(ip) {
+    const doubleColon = ip.indexOf('::');
+    let groups;
+    if (doubleColon >= 0) {
+        const left = ip.slice(0, doubleColon).split(':').filter(Boolean);
+        const right = ip
+            .slice(doubleColon + 2)
+            .split(':')
+            .filter(Boolean);
+        const fillCount = 8 - left.length - right.length;
+        if (fillCount < 0)
+            return null;
+        groups = [...left, ...new Array(fillCount).fill('0'), ...right];
+    }
+    else {
+        groups = ip.split(':');
+    }
+    if (groups.length !== 8)
+        return null;
+    for (const g of groups) {
+        const n = Number.parseInt(g, 16);
+        if (!Number.isInteger(n) || n < 0 || n > 0xffff)
+            return null;
+    }
+    return groups;
+}
+//# sourceMappingURL=source-ip.js.map

package/dist/audit/source-ip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-ip.js","sourceRoot":"","sources":["../../src/audit/source-ip.ts"],"names":[],"mappings":"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"}

package/dist/audit/types.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Audit types — the durable forensic record shape consumed by every
+ * `AuditProvider` implementation.
+ *
+ * # Why these types live here
+ *
+ * Per `design-audit.md`'s "history-recorder is the foundation"
+ * invariant, the audit log extends the existing `Revision` shape
+ * with `actor` + `outcome` fields. The types here are the wire
+ * shape every provider speaks; in-tree `HistoryAuditProvider`
+ * (Cut 2) and external-sink providers (v2 webhook, file, OTel,
+ * CloudWatch, Azure Monitor, syslog) all consume `AuditEvent`.
+ *
+ * # Outcome is required
+ *
+ * Per the locked invariant: "no implicit 'default to success' —
+ * recording sites supply outcome explicitly. Cuts a class of 'I
+ * forgot to record the failure' bugs." The closed enum stays
+ * closed (future additions like `'rate-limited'`, `'session-expired'`
+ * extend the enum, not the wire shape).
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns the event vocabulary. Doesn't read
+ *     storage; pure data shapes.
+ *   - DIP: providers, recorder, drawer all depend on these types
+ *     — never on which specific provider produced an event.
+ *   - LSP: every `AuditProvider` returns events shaped by these
+ *     types; consumers branch only on `outcome` / `action` for
+ *     behavior, never on which provider produced the data.
+ */
+/**
+ * Closed enum of action verbs Gazetta records. Per `design-audit.md`
+ * "Recording scope (v1)": save / publish / delete / restore at the
+ * content level + configure-roles for role-mapping changes in
+ * site.config.ts. `hook-fired` extends per design-hooks.md Cut 7.
+ *
+ * Soft-delete (per design-soft-delete.md Q8) extends with
+ * `archive` / `unarchive` / `purge` / `rename` — each maps to one
+ * user action; `rename` is recorded as a single composite event with
+ * `metadata.fromName` for forensic reconstruction (per Q8 M4 lock).
+ */
+export type AuditAction = 'save' | 'publish' | 'delete' | 'restore' | 'configure-roles' | 'hook-fired' | 'archive' | 'unarchive' | 'purge' | 'rename' | 'review-withdraw' | 'ai-suggest-alt';
+/**
+ * Closed enum of outcomes. Locked: every recording site supplies
+ * outcome explicitly. The four listed cover write attempts;
+ * v2 ambient-log expansion ('read', 'hook-cancelled') stays
+ * closed-enum.
+ */
+export type AuditOutcome = 'success' | 'forbidden' | 'validation-failed' | 'unauthenticated' | 'hook-cancelled' | 'timeout';
+/**
+ * Snapshot of the principal at decision time — never a live
+ * reference. Subsequent role changes don't rewrite history.
+ */
+export interface AuditActor {
+    /**
+     * Upstream stable subject (OIDC `sub`, Cloudflare Access
+     * `identity_nonce`, etc.) — NOT email. Email rotates; sub is
+     * stable. When `admin.audit.actorPseudonym: 'sha256'` is
+     * configured (Cut 4), this field is the salted hash prefix.
+     * `'unknown'` for pre-RBAC revisions or `none`-mode deployments.
+     */
+    id: string;
+    /**
+     * Optional human-readable identifier. Redacted to undefined when
+     * pseudonymization is enabled (low-entropy email gives weak
+     * pseudonymization).
+     */
+    email?: string;
+    /** Resolved Gazetta role at decision time. */
+    role: string;
+    /**
+     * Trust mode that produced this principal. Open string (not the
+     * `TrustMode` enum) so plugin-supplied modes can carry their own
+     * names without widening this type.
+     */
+    trustMode: string;
+}
+/**
+ * What was acted on. Keeps the audit query layer simple — consumers
+ * filter by `kind` + optional `name`.
+ */
+export interface AuditScope {
+    kind: 'page' | 'fragment' | 'asset' | 'site';
+    /** Item name when applicable (page name, fragment name, etc.). */
+    name?: string;
+}
+/**
+ * The wire shape every provider speaks. Every event records actor
+ * identity + action + outcome + scope; optional sourceIp / userAgent
+ * are operator-opt-in per Cut 4's privacy posture.
+ */
+export interface AuditEvent {
+    /** ISO 8601 with Z suffix. Matches the existing history-recorder convention. */
+    timestamp: string;
+    /** Snapshot of the actor at decision time. */
+    actor: AuditActor;
+    /** Closed-enum action verb. */
+    action: AuditAction;
+    /** Closed-enum outcome. Required — no implicit default. */
+    outcome: AuditOutcome;
+    /** What was acted on. */
+    scope: AuditScope;
+    /**
+     * Source IP when `admin.audit.recordSourceIp` is configured.
+     * Truncation / pseudonymization happens at recording time per
+     * the operator's mode setting (Cut 4).
+     */
+    sourceIp?: string;
+    /**
+     * User agent when `admin.audit.recordUserAgent` is configured.
+     * Cut 4 supports raw / truncated modes; default is none.
+     */
+    userAgent?: string;
+    /**
+     * Provider-specific extras. Examples: publish source target +
+     * destination, restore revision id, `missingCapabilities` for
+     * forbidden outcomes, `comment` for failure-mode events.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Filter shape consumed by `AuditProvider.query()`. Open enums
+ * because filter values come from URL query params; the server
+ * validates each field against the audit-event closed enums.
+ */
+export interface AuditQuery {
+    /** Match against `actor.id` or `actor.email` (case-insensitive substring). */
+    actor?: string;
+    action?: AuditAction;
+    outcome?: AuditOutcome;
+    scope?: {
+        kind?: AuditScope['kind'];
+        name?: string;
+    };
+    /** ISO 8601 timestamp lower bound (inclusive). */
+    since?: string;
+    /** ISO 8601 timestamp upper bound (exclusive). */
+    until?: string;
+    /** Max events returned. Default 100; provider may cap further. */
+    limit?: number;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/audit/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,SAAS,GACT,QAAQ,GACR,SAAS,GACT,iBAAiB,GACjB,YAAY,GACZ,SAAS,GACT,WAAW,GACX,OAAO,GACP,QAAQ,GACR,iBAAiB,GACjB,gBAAgB,CAAA;AAEpB;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GACpB,SAAS,GACT,WAAW,GACX,mBAAmB,GACnB,iBAAiB,GACjB,gBAAgB,GAChB,SAAS,CAAA;AAEb;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,EAAE,EAAE,MAAM,CAAA;IACV;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,CAAA;IAC5C,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAA;IACjB,8CAA8C;IAC9C,KAAK,EAAE,UAAU,CAAA;IACjB,+BAA+B;IAC/B,MAAM,EAAE,WAAW,CAAA;IACnB,2DAA2D;IAC3D,OAAO,EAAE,YAAY,CAAA;IACrB,yBAAyB;IACzB,KAAK,EAAE,UAAU,CAAA;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACpD,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf"}

package/dist/audit/types.js

@@ -0,0 +1,33 @@
+/**
+ * Audit types — the durable forensic record shape consumed by every
+ * `AuditProvider` implementation.
+ *
+ * # Why these types live here
+ *
+ * Per `design-audit.md`'s "history-recorder is the foundation"
+ * invariant, the audit log extends the existing `Revision` shape
+ * with `actor` + `outcome` fields. The types here are the wire
+ * shape every provider speaks; in-tree `HistoryAuditProvider`
+ * (Cut 2) and external-sink providers (v2 webhook, file, OTel,
+ * CloudWatch, Azure Monitor, syslog) all consume `AuditEvent`.
+ *
+ * # Outcome is required
+ *
+ * Per the locked invariant: "no implicit 'default to success' —
+ * recording sites supply outcome explicitly. Cuts a class of 'I
+ * forgot to record the failure' bugs." The closed enum stays
+ * closed (future additions like `'rate-limited'`, `'session-expired'`
+ * extend the enum, not the wire shape).
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns the event vocabulary. Doesn't read
+ *     storage; pure data shapes.
+ *   - DIP: providers, recorder, drawer all depend on these types
+ *     — never on which specific provider produced an event.
+ *   - LSP: every `AuditProvider` returns events shaped by these
+ *     types; consumers branch only on `outcome` / `action` for
+ *     behavior, never on which provider produced the data.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/audit/types.js.map

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

package/dist/audit/user-agent.d.ts

@@ -0,0 +1,28 @@
+/**
+ * User-agent recording — opt-in per design-audit.md "User agent
+ * recording" section. Lower priority than source-IP; most operators
+ * don't enable.
+ *
+ * # Modes
+ *
+ *   - `'none'` (default) — UA not recorded; field absent
+ *   - `'raw'` — full UA string. Useful for fingerprint forensics
+ *   - `'truncated'` — browser family + major version. Drops
+ *     fingerprinting detail; example outputs: `'Chrome/119'`,
+ *     `'Firefox/120'`, `'Safari/17'`, `'Other'`
+ *
+ * No `'hashed'` mode — UA has too little entropy for hashing to be
+ * a meaningful privacy hardening; if you want privacy, use
+ * `truncated` or `none`.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: UA processing only.
+ */
+export type UserAgentMode = 'none' | 'raw' | 'truncated';
+/**
+ * Apply the configured UA mode. Returns null for `'none'` or when
+ * input is empty/missing.
+ */
+export declare function processUserAgent(rawUa: string | undefined, mode: UserAgentMode): string | null;
+//# sourceMappingURL=user-agent.d.ts.map

package/dist/audit/user-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-agent.d.ts","sourceRoot":"","sources":["../../src/audit/user-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,KAAK,GAAG,WAAW,CAAA;AAExD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAM9F"}

package/dist/audit/user-agent.js

@@ -0,0 +1,63 @@
+/**
+ * User-agent recording — opt-in per design-audit.md "User agent
+ * recording" section. Lower priority than source-IP; most operators
+ * don't enable.
+ *
+ * # Modes
+ *
+ *   - `'none'` (default) — UA not recorded; field absent
+ *   - `'raw'` — full UA string. Useful for fingerprint forensics
+ *   - `'truncated'` — browser family + major version. Drops
+ *     fingerprinting detail; example outputs: `'Chrome/119'`,
+ *     `'Firefox/120'`, `'Safari/17'`, `'Other'`
+ *
+ * No `'hashed'` mode — UA has too little entropy for hashing to be
+ * a meaningful privacy hardening; if you want privacy, use
+ * `truncated` or `none`.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: UA processing only.
+ */
+/**
+ * Apply the configured UA mode. Returns null for `'none'` or when
+ * input is empty/missing.
+ */
+export function processUserAgent(rawUa, mode) {
+    if (mode === 'none')
+        return null;
+    if (!rawUa || rawUa.length === 0)
+        return null;
+    if (mode === 'raw')
+        return rawUa;
+    // mode === 'truncated' — extract browser family + major version.
+    return truncateUserAgent(rawUa);
+}
+/**
+ * Heuristic browser-family detection. Order matters: Edge before
+ * Chrome (Edge UA contains Chrome); Opera before Chrome (same).
+ * Returns 'Other' when no known family matches — better than
+ * leaking the raw string under truncated mode.
+ */
+function truncateUserAgent(ua) {
+    // Patterns ordered by specificity: more-specific first.
+    const patterns = [
+        { name: 'Edge', regex: /Edg(e|A|iOS)?\/(\d+)/i },
+        { name: 'Opera', regex: /OPR\/(\d+)/i },
+        { name: 'Chrome', regex: /Chrome\/(\d+)/i },
+        { name: 'Firefox', regex: /Firefox\/(\d+)/i },
+        { name: 'Safari', regex: /Version\/(\d+).*Safari/i },
+    ];
+    for (const { name, regex } of patterns) {
+        const match = ua.match(regex);
+        if (match) {
+            // Match group 1 is sometimes a sub-product name (Edg vs Edge),
+            // group 2 is the version. Pick the last numeric group.
+            const numericGroups = match.filter(g => /^\d+$/.test(g ?? ''));
+            const version = numericGroups[numericGroups.length - 1];
+            return `${name}/${version}`;
+        }
+    }
+    return 'Other';
+}
+//# sourceMappingURL=user-agent.js.map

package/dist/audit/user-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-agent.js","sourceRoot":"","sources":["../../src/audit/user-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAyB,EAAE,IAAmB;IAC7E,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,CAAA;IAChC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAC7C,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,KAAK,CAAA;IAChC,iEAAiE;IACjE,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAA;AACjC,CAAC;AAED;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,EAAU;IACnC,wDAAwD;IACxD,MAAM,QAAQ,GAA2C;QACvD,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,uBAAuB,EAAE;QAChD,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE;QACvC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,gBAAgB,EAAE;QAC3C,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,iBAAiB,EAAE;QAC7C,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,yBAAyB,EAAE;KACrD,CAAA;IACD,KAAK,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,QAAQ,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QAC7B,IAAI,KAAK,EAAE,CAAC;YACV,+DAA+D;YAC/D,uDAAuD;YACvD,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAA;YAC9D,MAAM,OAAO,GAAG,aAAa,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;YACvD,OAAO,GAAG,IAAI,IAAI,OAAO,EAAE,CAAA;QAC7B,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC"}