gazetta 0.7.0 → 0.8.0

package/dist/audit/context.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Audit context — the per-request helper handlers call to record
+ * events. Constructed once per `createAdminApp` boot from the
+ * resolved `admin.audit` config; injected into Hono's request
+ * context as `c.var.audit` by middleware.
+ *
+ * # Why a context object, not a free function
+ *
+ * Recording an event takes the principal (per-request), the
+ * configured providers (per-app), the privacy modes (per-app),
+ * and the source-IP / userAgent (per-request). A free function
+ * would force every handler to thread the per-app config alongside
+ * the per-request data — boilerplate every handler repeats.
+ *
+ * The context wraps both: `c.var.audit.record({ action, outcome,
+ * scope, metadata? })` is all the handler writes. The middleware
+ * pre-binds the per-app config + per-request principal/headers.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: this module owns the recording-site-facing helper. The
+ *     recorder dispatcher (Cut 3), pseudonymization (Cut 4), and
+ *     individual providers (Cut 2) are independent concerns.
+ *   - DIP: handlers depend on the `AuditContext` interface, not on
+ *     `recordToAll` or specific providers.
+ */
+import type { AuditAction, AuditOutcome, AuditProvider, AuditScope } from './index.js';
+import type { ActorPseudonymMode } from './pseudonymize.js';
+import type { SourceIpMode } from './source-ip.js';
+import type { UserAgentMode } from './user-agent.js';
+import type { AuditFailureLogger, RecordResult } from './recorder.js';
+import type { Principal } from '../auth/index.js';
+/**
+ * What the handler supplies. Everything else (actor, sourceIp,
+ * userAgent, timestamp) the context derives from per-request +
+ * per-app data.
+ */
+export interface RecordEventInput {
+    action: AuditAction;
+    outcome: AuditOutcome;
+    scope: AuditScope;
+    /** Provider-specific extras: missingCapabilities, source target, restoredFrom, etc. */
+    metadata?: Record<string, unknown>;
+}
+export interface AuditContext {
+    /**
+     * Record an event. Returns the recorder result so strict-mode
+     * callers can branch on `result.failed > 0` (per design-audit.md
+     * "Strict mode opt-in"). Non-strict callers ignore the return.
+     *
+     * Never throws (per Universal Provider Requirement #5). Failures
+     * surface in the result + structured log.
+     */
+    record(input: RecordEventInput): Promise<RecordResult>;
+    /**
+     * True when the operator has opted into strict mode. Handlers
+     * check this to decide whether to abort the write on failed
+     * recording.
+     */
+    readonly strict: boolean;
+}
+export interface AuditContextOptions {
+    /** Configured providers (in fan-out order). */
+    providers: ReadonlyArray<AuditProvider>;
+    /** Strict mode flag from `admin.audit.strict`. */
+    strict: boolean;
+    /** Pseudonymization mode for actor.id. */
+    actorPseudonym: ActorPseudonymMode;
+    /** Pseudonymization salt — required when actorPseudonym is sha256. */
+    actorSalt?: string;
+    /** Source-IP recording mode. */
+    recordSourceIp: SourceIpMode;
+    /** Source-IP hash salt — required when recordSourceIp is hashed. */
+    sourceIpSalt?: string;
+    /** Trusted proxy count for X-Forwarded-For mode dispatch. */
+    trustedProxyCount?: number;
+    /** User-agent recording mode. */
+    recordUserAgent: UserAgentMode;
+    /**
+     * Per-request data. Bound by the middleware before each route
+     * runs.
+     */
+    principal: Principal;
+    /** Per-request headers (lowercase keys). */
+    headers: ReadonlyMap<string, string>;
+    /** Per-request peer IP (when available). */
+    peerIp?: string;
+    /** Failure logger. */
+    logFailure?: AuditFailureLogger;
+}
+/**
+ * Build a context for one request. Production wiring: middleware
+ * runs after `principalMiddleware` (so c.var.principal is populated)
+ * + before route handlers; constructs the context with the request's
+ * principal + headers and stores it on `c.var.audit`.
+ */
+export declare function createAuditContext(opts: AuditContextOptions): AuditContext;
+//# sourceMappingURL=context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/audit/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAc,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAClG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,KAAK,EAA6B,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAMjD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,WAAW,CAAA;IACnB,OAAO,EAAE,YAAY,CAAA;IACrB,KAAK,EAAE,UAAU,CAAA;IACjB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IACtD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,+CAA+C;IAC/C,SAAS,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;IACvC,kDAAkD;IAClD,MAAM,EAAE,OAAO,CAAA;IACf,0CAA0C;IAC1C,cAAc,EAAE,kBAAkB,CAAA;IAClC,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gCAAgC;IAChC,cAAc,EAAE,YAAY,CAAA;IAC5B,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,6DAA6D;IAC7D,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,iCAAiC;IACjC,eAAe,EAAE,aAAa,CAAA;IAC9B;;;OAGG;IACH,SAAS,EAAE,SAAS,CAAA;IACpB,4CAA4C;IAC5C,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACpC,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sBAAsB;IACtB,UAAU,CAAC,EAAE,kBAAkB,CAAA;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB,GAAG,YAAY,CA2C1E"}

package/dist/audit/context.js

@@ -0,0 +1,51 @@
+import { recordToAll } from './recorder.js';
+import { pseudonymizeActor } from './pseudonymize.js';
+import { extractSourceIp, processSourceIp } from './source-ip.js';
+import { processUserAgent } from './user-agent.js';
+/**
+ * Build a context for one request. Production wiring: middleware
+ * runs after `principalMiddleware` (so c.var.principal is populated)
+ * + before route handlers; constructs the context with the request's
+ * principal + headers and stores it on `c.var.audit`.
+ */
+export function createAuditContext(opts) {
+    return {
+        strict: opts.strict,
+        async record(input) {
+            // Apply pseudonymization to the actor BEFORE constructing
+            // the event. Cuts a class of bugs where the pre-pseudonym
+            // actor leaks via metadata or per-provider serialization.
+            const actor = pseudonymizeActor(opts.principal, opts.actorPseudonym, opts.actorSalt);
+            // Source IP — extract per trust mode, then process per
+            // operator's mode. Both are pure functions; either step
+            // returns null → omit the field.
+            const sourceIpCtx = {
+                trustMode: opts.principal.trustMode,
+                headers: opts.headers,
+                peerIp: opts.peerIp,
+                trustedProxyCount: opts.trustedProxyCount,
+            };
+            const rawIp = extractSourceIp(sourceIpCtx);
+            const sourceIp = processSourceIp(rawIp, opts.recordSourceIp, opts.sourceIpSalt) ?? undefined;
+            // User agent — same dispatch.
+            const rawUa = opts.headers.get('user-agent');
+            const userAgent = processUserAgent(rawUa, opts.recordUserAgent) ?? undefined;
+            const event = {
+                timestamp: new Date().toISOString(),
+                actor,
+                action: input.action,
+                outcome: input.outcome,
+                scope: input.scope,
+                ...(sourceIp !== undefined ? { sourceIp } : {}),
+                ...(userAgent !== undefined ? { userAgent } : {}),
+                ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+            };
+            return recordToAll(event, {
+                providers: opts.providers,
+                strict: opts.strict,
+                logFailure: opts.logFailure,
+            });
+        },
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/audit/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/audit/context.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AA+DlD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAyB;IAC1D,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,KAAK,CAAC,MAAM,CAAC,KAAuB;YAClC,0DAA0D;YAC1D,0DAA0D;YAC1D,0DAA0D;YAC1D,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;YAEpF,uDAAuD;YACvD,wDAAwD;YACxD,iCAAiC;YACjC,MAAM,WAAW,GAA8B;gBAC7C,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS;gBACnC,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;aAC1C,CAAA;YACD,MAAM,KAAK,GAAG,eAAe,CAAC,WAAW,CAAC,CAAA;YAC1C,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,YAAY,CAAC,IAAI,SAAS,CAAA;YAE5F,8BAA8B;YAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;YAC5C,MAAM,SAAS,GAAG,gBAAgB,CAAC,KAAK,EAAE,IAAI,CAAC,eAAe,CAAC,IAAI,SAAS,CAAA;YAE5E,MAAM,KAAK,GAAe;gBACxB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,KAAK;gBACL,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC/C,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACjD,GAAG,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACtE,CAAA;YAED,OAAO,WAAW,CAAC,KAAK,EAAE;gBACxB,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,UAAU,EAAE,IAAI,CAAC,UAAU;aAC5B,CAAC,CAAA;QACJ,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/audit/errors.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Audit error taxonomy. Per `design-plugins.md`'s Universal Provider
+ * Requirements, every provider surface gets its own error classes
+ * so consumers can branch on the failure category.
+ *
+ * # Error taxonomy
+ *
+ *   - `AuditError`     — base class for all audit failures
+ *   - `AuditConfigurationError` — invalid `admin.audit` config
+ *     (unknown provider name, missing required field). Surfaces
+ *     at admin boot; admin won't start.
+ *   - `AuditTransportError` — provider couldn't reach its sink
+ *     (network blip, 5xx from CloudWatch, etc.). Per Universal
+ *     Provider Requirement #5: NEVER thrown — providers log and
+ *     fall back to local-only recording. The class exists so
+ *     transport-failure structured-log entries can carry a typed
+ *     reason field.
+ *
+ * # Why no `AuditAuthorizationError`
+ *
+ * Audit READS gate on `read:audit-log` capability via the standard
+ * capability middleware (`requireCapability` from auth/RBAC) — the
+ * 403 surfaces as `AuthorizationError` from the existing taxonomy,
+ * not a new audit-specific error class.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: error classes own only error identity; route handlers
+ *     map to JSON via the existing error-response infrastructure.
+ *   - LSP: subclasses extend `AuditError` so consumers can
+ *     `instanceof AuditError` for catch-all handling.
+ */
+/** Base class for all audit-related errors. */
+export declare class AuditError extends Error {
+    readonly name: string;
+    /** HTTP status the route should return when this error reaches one. */
+    readonly httpStatus: number;
+    constructor(message: string);
+}
+/**
+ * Thrown at config-load time when `admin.audit` is malformed
+ * (unknown provider, missing required field, invalid retention).
+ * Admin won't start — operator sees the failure before any request
+ * is served.
+ */
+export declare class AuditConfigurationError extends AuditError {
+    readonly name = "AuditConfigurationError";
+    readonly httpStatus = 500;
+}
+/**
+ * Tagged transport failure. Per Universal Provider Requirement #5,
+ * audit providers never throw on transport errors — they catch
+ * internally and log via this category. The class exists so the
+ * structured-log entries the recorder emits can carry a typed
+ * reason field; route handlers never see this.
+ */
+export declare class AuditTransportError extends AuditError {
+    readonly name = "AuditTransportError";
+    readonly httpStatus = 500;
+    /**
+     * Categorical failure type for log-aggregator filtering.
+     *
+     *   - `transport` — network / HTTP failure on a provider with an
+     *     external sink (CloudWatch outage, webhook timeout)
+     *   - `serialize` — event couldn't be serialized to the provider's
+     *     wire format
+     *   - `quota`     — provider's storage tier rejected the write
+     *     (CloudWatch log group full, file-cache disk full)
+     */
+    readonly category: 'transport' | 'serialize' | 'quota';
+    constructor(message: string, category: 'transport' | 'serialize' | 'quota');
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/audit/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,+CAA+C;AAC/C,qBAAa,UAAW,SAAQ,KAAK;IACnC,SAAkB,IAAI,EAAE,MAAM,CAAe;IAC7C,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAM;gBACrB,OAAO,EAAE,MAAM;CAG5B;AAED;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,UAAU;IACrD,SAAkB,IAAI,6BAA4B;IAClD,SAAkB,UAAU,OAAM;CACnC;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,UAAU;IACjD,SAAkB,IAAI,yBAAwB;IAC9C,SAAkB,UAAU,OAAM;IAClC;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,WAAW,GAAG,OAAO,CAAA;gBAC1C,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,WAAW,GAAG,OAAO;CAI3E"}

package/dist/audit/errors.js

@@ -0,0 +1,78 @@
+/**
+ * Audit error taxonomy. Per `design-plugins.md`'s Universal Provider
+ * Requirements, every provider surface gets its own error classes
+ * so consumers can branch on the failure category.
+ *
+ * # Error taxonomy
+ *
+ *   - `AuditError`     — base class for all audit failures
+ *   - `AuditConfigurationError` — invalid `admin.audit` config
+ *     (unknown provider name, missing required field). Surfaces
+ *     at admin boot; admin won't start.
+ *   - `AuditTransportError` — provider couldn't reach its sink
+ *     (network blip, 5xx from CloudWatch, etc.). Per Universal
+ *     Provider Requirement #5: NEVER thrown — providers log and
+ *     fall back to local-only recording. The class exists so
+ *     transport-failure structured-log entries can carry a typed
+ *     reason field.
+ *
+ * # Why no `AuditAuthorizationError`
+ *
+ * Audit READS gate on `read:audit-log` capability via the standard
+ * capability middleware (`requireCapability` from auth/RBAC) — the
+ * 403 surfaces as `AuthorizationError` from the existing taxonomy,
+ * not a new audit-specific error class.
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: error classes own only error identity; route handlers
+ *     map to JSON via the existing error-response infrastructure.
+ *   - LSP: subclasses extend `AuditError` so consumers can
+ *     `instanceof AuditError` for catch-all handling.
+ */
+/** Base class for all audit-related errors. */
+export class AuditError extends Error {
+    name = 'AuditError';
+    /** HTTP status the route should return when this error reaches one. */
+    httpStatus = 500;
+    constructor(message) {
+        super(message);
+    }
+}
+/**
+ * Thrown at config-load time when `admin.audit` is malformed
+ * (unknown provider, missing required field, invalid retention).
+ * Admin won't start — operator sees the failure before any request
+ * is served.
+ */
+export class AuditConfigurationError extends AuditError {
+    name = 'AuditConfigurationError';
+    httpStatus = 500;
+}
+/**
+ * Tagged transport failure. Per Universal Provider Requirement #5,
+ * audit providers never throw on transport errors — they catch
+ * internally and log via this category. The class exists so the
+ * structured-log entries the recorder emits can carry a typed
+ * reason field; route handlers never see this.
+ */
+export class AuditTransportError extends AuditError {
+    name = 'AuditTransportError';
+    httpStatus = 500;
+    /**
+     * Categorical failure type for log-aggregator filtering.
+     *
+     *   - `transport` — network / HTTP failure on a provider with an
+     *     external sink (CloudWatch outage, webhook timeout)
+     *   - `serialize` — event couldn't be serialized to the provider's
+     *     wire format
+     *   - `quota`     — provider's storage tier rejected the write
+     *     (CloudWatch log group full, file-cache disk full)
+     */
+    category;
+    constructor(message, category) {
+        super(message);
+        this.category = category;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/audit/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/audit/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,+CAA+C;AAC/C,MAAM,OAAO,UAAW,SAAQ,KAAK;IACjB,IAAI,GAAW,YAAY,CAAA;IAC7C,uEAAuE;IAC9D,UAAU,GAAW,GAAG,CAAA;IACjC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;IAChB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,uBAAwB,SAAQ,UAAU;IACnC,IAAI,GAAG,yBAAyB,CAAA;IAChC,UAAU,GAAG,GAAG,CAAA;CACnC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,mBAAoB,SAAQ,UAAU;IAC/B,IAAI,GAAG,qBAAqB,CAAA;IAC5B,UAAU,GAAG,GAAG,CAAA;IAClC;;;;;;;;;OASG;IACM,QAAQ,CAAqC;IACtD,YAAY,OAAe,EAAE,QAA6C;QACxE,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;IAC1B,CAAC;CACF"}

package/dist/audit/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Audit barrel export. Cuts 2-9 add to this surface (`AuditProvider`
+ * interface, `HistoryAuditProvider`, recorder, query route).
+ */
+export type { AuditAction, AuditActor, AuditEvent, AuditOutcome, AuditQuery, AuditScope } from './types.js';
+export { AuditError, AuditConfigurationError, AuditTransportError } from './errors.js';
+export { AuditConfigSchema, DEFAULT_AUDIT_CONFIG, type AuditConfig } from './config.js';
+export type { AuditProvider } from './provider.js';
+export { createHistoryAuditProvider, type HistoryAuditProviderOptions } from './providers/history.js';
+export { recordToAll, type AuditFailureLog, type AuditFailureLogger, type RecordResult, type RecordToAllOptions, } from './recorder.js';
+export { computePseudonymizedId, pseudonymizeActor, type ActorPseudonymMode } from './pseudonymize.js';
+export { extractSourceIp, processSourceIp, type SourceIpExtractionContext, type SourceIpMode, } from './source-ip.js';
+export { processUserAgent, type UserAgentMode } from './user-agent.js';
+export { pruneAuditEvents, type AuditRetentionConfig, type PruneResult } from './retention.js';
+export { createAuditContext, type AuditContext, type AuditContextOptions, type RecordEventInput, } from './context.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC3G,OAAO,EAAE,UAAU,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACtF,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAA;AACvF,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAClD,OAAO,EAAE,0BAA0B,EAAE,KAAK,2BAA2B,EAAE,MAAM,wBAAwB,CAAA;AACrG,OAAO,EACL,WAAW,EACX,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,kBAAkB,GACxB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACtG,OAAO,EACL,eAAe,EACf,eAAe,EACf,KAAK,yBAAyB,EAC9B,KAAK,YAAY,GAClB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACtE,OAAO,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC9F,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,cAAc,CAAA"}

package/dist/audit/index.js

@@ -0,0 +1,10 @@
+export { AuditError, AuditConfigurationError, AuditTransportError } from './errors.js';
+export { AuditConfigSchema, DEFAULT_AUDIT_CONFIG } from './config.js';
+export { createHistoryAuditProvider } from './providers/history.js';
+export { recordToAll, } from './recorder.js';
+export { computePseudonymizedId, pseudonymizeActor } from './pseudonymize.js';
+export { extractSourceIp, processSourceIp, } from './source-ip.js';
+export { processUserAgent } from './user-agent.js';
+export { pruneAuditEvents } from './retention.js';
+export { createAuditContext, } from './context.js';
+//# sourceMappingURL=index.js.map

package/dist/audit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,UAAU,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACtF,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAoB,MAAM,aAAa,CAAA;AAEvF,OAAO,EAAE,0BAA0B,EAAoC,MAAM,wBAAwB,CAAA;AACrG,OAAO,EACL,WAAW,GAKZ,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAA2B,MAAM,mBAAmB,CAAA;AACtG,OAAO,EACL,eAAe,EACf,eAAe,GAGhB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,gBAAgB,EAAsB,MAAM,iBAAiB,CAAA;AACtE,OAAO,EAAE,gBAAgB,EAA+C,MAAM,gBAAgB,CAAA;AAC9F,OAAO,EACL,kBAAkB,GAInB,MAAM,cAAc,CAAA"}

package/dist/audit/provider.d.ts

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

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

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

package/dist/audit/provider.js

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

package/dist/audit/provider.js.map

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

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

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

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

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

package/dist/audit/providers/history.js

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

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

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

package/dist/audit/pseudonymize.d.ts

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