gazetta 0.7.0 → 0.8.0

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAsBxC;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,GAA8B;IAC5D,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,GAAG,CAAA;IAClC,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,MAAM,CAAC;QACZ,KAAK,WAAW;YACd,OAAO,GAAG,CAAC,MAAM,IAAI,IAAI,CAAA;QAC3B,KAAK,mBAAmB,CAAC,CAAC,CAAC;YACzB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAA;YAC5C,IAAI,IAAI;gBAAE,OAAO,IAAI,CAAA;YACrB,OAAO,GAAG,CAAC,MAAM,IAAI,IAAI,CAAA;QAC3B,CAAC;QACD,KAAK,gBAAgB,CAAC;QACtB,KAAK,iBAAiB,CAAC;QACvB,KAAK,aAAa,CAAC,CAAC,CAAC;YACnB,mDAAmD;YACnD,0DAA0D;YAC1D,0DAA0D;YAC1D,yDAAyD;YACzD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAA;YAC1C,IAAI,CAAC,GAAG;gBAAE,OAAO,GAAG,CAAC,MAAM,IAAI,IAAI,CAAA;YACnC,MAAM,OAAO,GAAG,GAAG;iBAChB,KAAK,CAAC,GAAG,CAAC;iBACV,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;iBAClB,MAAM,CAAC,OAAO,CAAC,CAAA;YAClB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,GAAG,CAAC,MAAM,IAAI,IAAI,CAAA;YACnD,MAAM,YAAY,GAAG,GAAG,CAAC,iBAAiB,IAAI,CAAC,CAAA;YAC/C,4DAA4D;YAC5D,oEAAoE;YACpE,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,YAAY,GAAG,CAAC,CAAA;YACnD,IAAI,SAAS,GAAG,CAAC;gBAAE,OAAO,GAAG,CAAC,MAAM,IAAI,IAAI,CAAA;YAC5C,OAAO,OAAO,CAAC,SAAS,CAAC,CAAA;QAC3B,CAAC;QACD;YACE,6DAA6D;YAC7D,0DAA0D;YAC1D,OAAO,GAAG,CAAC,MAAM,IAAI,IAAI,CAAA;IAC7B,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAoB,EAAE,IAAkB,EAAE,IAAa;IACrF,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,CAAA;IAChC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAE7C,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,KAAK,CAAA;IAChC,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CACb,yGAAyG,CAC1G,CAAA;QACH,CAAC;QACD,OAAO,UAAU,CAAC,QAAQ,CAAC;aACxB,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC;aACpB,MAAM,CAAC,KAAK,CAAC;aACb,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IACjB,CAAC;IACD,uBAAuB;IACvB,OAAO,UAAU,CAAC,KAAK,CAAC,CAAA;AAC1B,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAC,EAAU;IAC5B,6BAA6B;IAC7B,IAAI,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QAC3B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAA;QACnC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;YAChC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG;gBAAE,OAAO,IAAI,CAAA;QAC3D,CAAC;QACD,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,OAAO,CAAA;IACnD,CAAC;IACD,2DAA2D;IAC3D,IAAI,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,kCAAkC;QAClC,MAAM,MAAM,GAAG,gBAAgB,CAAC,EAAE,CAAC,CAAA;QACnC,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAA;QACxB,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAA;IAC/C,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAS,gBAAgB,CAAC,EAAU;IAClC,MAAM,WAAW,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IACpC,IAAI,MAAgB,CAAA;IACpB,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;QAChE,MAAM,KAAK,GAAG,EAAE;aACb,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC;aACtB,KAAK,CAAC,GAAG,CAAC;aACV,MAAM,CAAC,OAAO,CAAC,CAAA;QAClB,MAAM,SAAS,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAA;QAChD,IAAI,SAAS,GAAG,CAAC;YAAE,OAAO,IAAI,CAAA;QAC9B,MAAM,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,CAAC,CAAA;IACjE,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IACxB,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACpC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;QAChC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,MAAM;YAAE,OAAO,IAAI,CAAA;IAC9D,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC"}

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

package/dist/auth/capabilities.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Test whether a principal's capability set grants the required
+ * capability. Implements wildcard expansion:
+ *
+ *   - `*` (root wildcard) grants everything (including
+ *     wildcard-exempt capabilities — admin role retains the
+ *     escape hatch)
+ *   - `<prefix>:*` grants every capability under that prefix
+ *     EXCEPT capabilities in `WILDCARD_EXEMPT_CAPABILITIES`
+ *   - exact match grants exactly that capability
+ *
+ * Plugin-supplied capabilities use scoped prefixes
+ * (`@my-org/search:rebuild-index`) and follow the same rules:
+ * `@my-org/search:*` grants `@my-org/search:rebuild-index`.
+ */
+export declare function capabilityGrants(granted: ReadonlyArray<string>, required: string): boolean;
+/**
+ * Expand a role name to its capability set. Built-in roles
+ * (`admin`, `editor`, `viewer`) resolve from `BUILT_IN_ROLES`;
+ * custom roles must be supplied via the `customRoles` map at
+ * resolution time (per `design-auth-rbac.md`'s "hybrid built-in
+ * + custom" model).
+ *
+ * Returns null when the role isn't recognized — caller decides
+ * whether to fail-closed (deny access) or fail-open (assign default).
+ */
+export declare function expandRole(roleName: string, customRoles?: Readonly<Record<string, ReadonlyArray<string>>>): ReadonlyArray<string> | null;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/auth/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/auth/capabilities.ts"],"names":[],"mappings":"AAgDA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAe1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,GAC5D,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI,CAQ9B"}

package/dist/auth/capabilities.js

@@ -0,0 +1,101 @@
+/**
+ * Capability vocabulary helpers — the closed set of built-in
+ * capabilities and the matching logic for wildcard expansion.
+ *
+ * # Why these helpers live here
+ *
+ * Capabilities are strings, but the matching logic (does
+ * `read:*` grant `read:pages`? does `*` grant everything?) is
+ * load-bearing for every authorization check. Centralizing the
+ * matching logic in pure functions means:
+ *
+ *   - Middleware uses one function, not ad-hoc string compares
+ *   - Tests pin the wildcard semantics in one place
+ *   - Plugin-supplied capabilities (when plugin foundation ships)
+ *     extend via prefix conventions, not by changing matching code
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: matching only; doesn't read configs or extract principals.
+ *   - DIP: middleware depends on this helper, not on the BUILT_IN_ROLES
+ *     constant.
+ */
+import { BUILT_IN_ROLES } from './types.js';
+/**
+ * Privacy-sensitive capabilities that prefix wildcards do NOT
+ * grant. Per design-auth-rbac.md's "Audit-log read access is its
+ * own capability — viewers don't see audit by default", and the
+ * matching design-audit.md note that audit log is its own gate.
+ *
+ * These capabilities require either:
+ *   - explicit grant (the exact capability string in the granted
+ *     list), or
+ *   - root wildcard `*` (admin role)
+ *
+ * Prefix wildcards (`read:*`) DO NOT grant them. Built-in editor
+ * + viewer roles hold `read:*` — they get `read:pages`,
+ * `read:fragments`, `read:assets` but NOT `read:audit-log`.
+ * Operators wanting an "auditor" custom role declare
+ * `['read:*', 'read:audit-log']` explicitly.
+ *
+ * Plugin authors adding privacy-sensitive capabilities extend this
+ * set by exporting their own capability string in this set —
+ * future plugin foundation will likely move this to a registry.
+ * For v1 the set is closed to known built-ins.
+ */
+const WILDCARD_EXEMPT_CAPABILITIES = new Set(['read:audit-log']);
+/**
+ * Test whether a principal's capability set grants the required
+ * capability. Implements wildcard expansion:
+ *
+ *   - `*` (root wildcard) grants everything (including
+ *     wildcard-exempt capabilities — admin role retains the
+ *     escape hatch)
+ *   - `<prefix>:*` grants every capability under that prefix
+ *     EXCEPT capabilities in `WILDCARD_EXEMPT_CAPABILITIES`
+ *   - exact match grants exactly that capability
+ *
+ * Plugin-supplied capabilities use scoped prefixes
+ * (`@my-org/search:rebuild-index`) and follow the same rules:
+ * `@my-org/search:*` grants `@my-org/search:rebuild-index`.
+ */
+export function capabilityGrants(granted, required) {
+    if (required.length === 0)
+        return false;
+    const isExempt = WILDCARD_EXEMPT_CAPABILITIES.has(required);
+    for (const cap of granted) {
+        // Root wildcard always grants — admin retains the escape hatch
+        // even for wildcard-exempt capabilities.
+        if (cap === '*')
+            return true;
+        if (cap === required)
+            return true;
+        // Prefix wildcards skip wildcard-exempt capabilities.
+        if (!isExempt && cap.endsWith(':*')) {
+            const prefix = cap.slice(0, -1); // 'read:*' → 'read:'
+            if (required.startsWith(prefix))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Expand a role name to its capability set. Built-in roles
+ * (`admin`, `editor`, `viewer`) resolve from `BUILT_IN_ROLES`;
+ * custom roles must be supplied via the `customRoles` map at
+ * resolution time (per `design-auth-rbac.md`'s "hybrid built-in
+ * + custom" model).
+ *
+ * Returns null when the role isn't recognized — caller decides
+ * whether to fail-closed (deny access) or fail-open (assign default).
+ */
+export function expandRole(roleName, customRoles) {
+    if (customRoles && roleName in customRoles) {
+        return customRoles[roleName];
+    }
+    if (roleName in BUILT_IN_ROLES) {
+        return BUILT_IN_ROLES[roleName];
+    }
+    return null;
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/auth/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/auth/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,cAAc,EAA0B,MAAM,YAAY,CAAA;AAEnE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,4BAA4B,GAAwB,IAAI,GAAG,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAA;AAErF;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAA8B,EAAE,QAAgB;IAC/E,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IACvC,MAAM,QAAQ,GAAG,4BAA4B,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAC3D,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,+DAA+D;QAC/D,yCAAyC;QACzC,IAAI,GAAG,KAAK,GAAG;YAAE,OAAO,IAAI,CAAA;QAC5B,IAAI,GAAG,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAA;QACjC,sDAAsD;QACtD,IAAI,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACpC,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA,CAAC,qBAAqB;YACrD,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC;gBAAE,OAAO,IAAI,CAAA;QAC9C,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CACxB,QAAgB,EAChB,WAA6D;IAE7D,IAAI,WAAW,IAAI,QAAQ,IAAI,WAAW,EAAE,CAAC;QAC3C,OAAO,WAAW,CAAC,QAAQ,CAAC,CAAA;IAC9B,CAAC;IACD,IAAI,QAAQ,IAAI,cAAc,EAAE,CAAC;QAC/B,OAAO,cAAc,CAAC,QAAQ,CAAqC,CAAA;IACrE,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}