gazetta 0.6.0 → 0.8.0

package/dist/assets/variants.js

@@ -0,0 +1,74 @@
+/**
+ * Responsive-variant generation for image assets.
+ *
+ * Single responsibility: given the original bytes of an image, produce
+ * resized variants at the v1 target widths. No storage, no manifest, no
+ * naming policy — callers (ingest pipeline) compose this with byte
+ * persistence and manifest writing.
+ *
+ * v1 target widths: 400 / 800 / 1200 / 1600. Variants wider than the
+ * source image are skipped (no upscaling — the browser's srcset picker
+ * is happy with fewer candidates, and upscaled variants would be worse
+ * than the original). Same format as input (JPEG → JPEG, PNG → PNG).
+ *
+ * Format conversion (WebP/AVIF emission) is a separate capability and
+ * lives out of scope for this module.
+ */
+import sharp from 'sharp';
+/** The v1 srcset ladder. Ordered ascending — callers rely on this. */
+export const VARIANT_WIDTHS = [400, 800, 1200, 1600];
+/**
+ * Generate responsive variants from a source image buffer. Produces one
+ * variant per `VARIANT_WIDTHS` entry that is ≤ the source image's width.
+ *
+ * Same output format as the input (JPEG stays JPEG, PNG stays PNG) —
+ * re-compression is implicit via sharp's encoder, which applies its
+ * quality defaults. Explicit quality/compression tuning is deferred to
+ * a future image-pipeline config module.
+ *
+ * Throws whatever sharp throws on unreadable input — the caller is
+ * responsible for treating that as a hard ingest failure (per v1
+ * contract: rollback + fail the upload).
+ */
+export async function generateVariants(source) {
+    // Decode once, reuse for every target width — avoids re-parsing the
+    // source for each resize.
+    const base = sharp(source);
+    const meta = await base.metadata();
+    const sourceWidth = meta.width ?? 0;
+    const sourceFormat = meta.format;
+    if (!sourceFormat) {
+        throw new Error('Image format could not be determined for variant generation');
+    }
+    const picked = VARIANT_WIDTHS.filter(w => w <= sourceWidth);
+    const out = [];
+    for (const width of picked) {
+        // Re-construct per iteration; sharp pipelines are single-use once
+        // `.toBuffer()` has run.
+        const pipeline = sharp(source).resize({ width });
+        const bytes = await toSourceFormat(pipeline, sourceFormat).toBuffer();
+        out.push({ width, bytes: new Uint8Array(bytes) });
+    }
+    return out;
+}
+/**
+ * Route a sharp pipeline to the encoder matching the source format.
+ * sharp auto-detects on `.toBuffer()` when the input had an explicit
+ * format, but being explicit here keeps behavior deterministic and
+ * makes future per-format quality tuning a one-line change.
+ */
+function toSourceFormat(pipeline, format) {
+    switch (format) {
+        case 'jpeg':
+        case 'jpg':
+            return pipeline.jpeg();
+        case 'png':
+            return pipeline.png();
+        default:
+            // Should not be reached in v1 (ingest allowlist is JPEG + PNG).
+            // If it does (future MIME expansion), the caller's rollback path
+            // will fire on the thrown error — safer than silently defaulting.
+            throw new Error(`Unsupported source format for variant generation: ${format}`);
+    }
+}
+//# sourceMappingURL=variants.js.map

package/dist/assets/variants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variants.js","sourceRoot":"","sources":["../../src/assets/variants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,MAAM,OAAO,CAAA;AAEzB,sEAAsE;AACtE,MAAM,CAAC,MAAM,cAAc,GAAsB,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;AASvE;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAkB;IACvD,oEAAoE;IACpE,0BAA0B;IAC1B,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAA;IAC1B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAA;IAClC,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAA;IACnC,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAA;IAChC,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAA;IAChF,CAAC;IAED,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,WAAW,CAAC,CAAA;IAE3D,MAAM,GAAG,GAAuB,EAAE,CAAA;IAClC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,kEAAkE;QAClE,yBAAyB;QACzB,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,CAAA;QAChD,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,QAAQ,EAAE,CAAA;QACrE,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IACnD,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;;GAKG;AACH,SAAS,cAAc,CAAC,QAAqB,EAAE,MAA8B;IAC3E,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,MAAM,CAAC;QACZ,KAAK,KAAK;YACR,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAA;QACxB,KAAK,KAAK;YACR,OAAO,QAAQ,CAAC,GAAG,EAAE,CAAA;QACvB;YACE,gEAAgE;YAChE,iEAAiE;YACjE,kEAAkE;YAClE,MAAM,IAAI,KAAK,CAAC,qDAAqD,MAAM,EAAE,CAAC,CAAA;IAClF,CAAC;AACH,CAAC"}

package/dist/audit/config.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Zod schema for the `admin.audit` block in `site.config.ts`. Cut 1
+ * ships only the v1 in-tree provider configuration shapes (none /
+ * history); v2 external-sink providers (webhook, file, OTel,
+ * CloudWatch, Azure Monitor, syslog) extend the union when they
+ * land — the discriminator field stays `provider`.
+ *
+ * # Why `provider` is a string discriminator (not Path X factory)
+ *
+ * Per `design-audit.md`'s "Configuration" section:
+ *
+ *     admin: { audit: { provider: 'history' } }
+ *
+ * The string-discriminator predates Path X (factory-call config) per
+ * the "Path X migration note" in design-audit.md. When the audit
+ * foundation moves to Path X, the operator-facing shape becomes:
+ *
+ *     audit: auditChain([historyAudit(), cloudwatchAudit({...})], { strict: false })
+ *
+ * Cut 1 ships the pre-Path-X shape because:
+ *   1. The Path X migration touches every Pattern-3 surface; doing
+ *      it audit-only fragments the cutover
+ *   2. The string-discriminator works correctly today; operators
+ *      can use it without regret. The Path X migration is a future
+ *      additive change (fan-out factory wraps single-provider for
+ *      backwards compat at config-eval time)
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: schema validation only. Doesn't construct providers.
+ *   - OCP: adding a v2 provider extends the discriminated union;
+ *     existing variants unchanged.
+ */
+import { z } from 'zod';
+/**
+ * Top-level audit config. v1 ships only the `history` variant;
+ * the discriminated-union shape leaves room for v2 external-sink
+ * providers without touching the consumer code path.
+ */
+export declare const AuditConfigSchema: z.ZodObject<{
+    provider: z.ZodLiteral<"history">;
+    retention: z.ZodOptional<z.ZodObject<{
+        events: z.ZodOptional<z.ZodNumber>;
+        maxAgeMonths: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strict>>;
+    strict: z.ZodOptional<z.ZodBoolean>;
+    actorPseudonym: z.ZodOptional<z.ZodEnum<{
+        sha256: "sha256";
+        none: "none";
+    }>>;
+    recordSourceIp: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        raw: "raw";
+        hashed: "hashed";
+        truncated: "truncated";
+    }>>;
+    trustedProxyHeader: z.ZodOptional<z.ZodString>;
+    trustedProxyCount: z.ZodOptional<z.ZodNumber>;
+    recordUserAgent: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        raw: "raw";
+        truncated: "truncated";
+    }>>;
+}, z.core.$strict>;
+export type AuditConfig = z.infer<typeof AuditConfigSchema>;
+/**
+ * Defaults per design-audit.md "Configuration":
+ *   - `provider: 'history'` is implicit when admin.audit absent
+ *   - `strict: false` (fail-open)
+ *   - `actorPseudonym: 'none'` (raw subject)
+ *   - `recordSourceIp: 'none'` (off)
+ *   - `recordUserAgent: 'none'` (off)
+ */
+export declare const DEFAULT_AUDIT_CONFIG: AuditConfig;
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/audit/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAuCvB;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;kBAAqB,CAAA;AAEnD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAE3D;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAMlC,CAAA"}

package/dist/audit/config.js

@@ -0,0 +1,91 @@
+/**
+ * Zod schema for the `admin.audit` block in `site.config.ts`. Cut 1
+ * ships only the v1 in-tree provider configuration shapes (none /
+ * history); v2 external-sink providers (webhook, file, OTel,
+ * CloudWatch, Azure Monitor, syslog) extend the union when they
+ * land — the discriminator field stays `provider`.
+ *
+ * # Why `provider` is a string discriminator (not Path X factory)
+ *
+ * Per `design-audit.md`'s "Configuration" section:
+ *
+ *     admin: { audit: { provider: 'history' } }
+ *
+ * The string-discriminator predates Path X (factory-call config) per
+ * the "Path X migration note" in design-audit.md. When the audit
+ * foundation moves to Path X, the operator-facing shape becomes:
+ *
+ *     audit: auditChain([historyAudit(), cloudwatchAudit({...})], { strict: false })
+ *
+ * Cut 1 ships the pre-Path-X shape because:
+ *   1. The Path X migration touches every Pattern-3 surface; doing
+ *      it audit-only fragments the cutover
+ *   2. The string-discriminator works correctly today; operators
+ *      can use it without regret. The Path X migration is a future
+ *      additive change (fan-out factory wraps single-provider for
+ *      backwards compat at config-eval time)
+ *
+ * # SOLID lenses
+ *
+ *   - SRP: schema validation only. Doesn't construct providers.
+ *   - OCP: adding a v2 provider extends the discriminated union;
+ *     existing variants unchanged.
+ */
+import { z } from 'zod';
+/**
+ * Retention shape — separate from history retention per locked
+ * invariant: compliance regimes specify retention windows that
+ * differ from content-history budgets.
+ */
+const retentionSchema = z
+    .object({
+    /** Max audit events kept (per provider with own storage). */
+    events: z.number().int().positive().optional(),
+    /** Max age in months. `null` = no time limit. */
+    maxAgeMonths: z.number().int().positive().nullable().optional(),
+})
+    .strict();
+/**
+ * `history` provider — extends the existing `Revision` shape with
+ * audit fields. v1 default; zero-config when audit isn't explicitly
+ * configured.
+ */
+const historyAuditSchema = z
+    .object({
+    provider: z.literal('history'),
+    retention: retentionSchema.optional(),
+    /** `true` blocks writes when audit recording fails. Default false. */
+    strict: z.boolean().optional(),
+    /** Pseudonymization mode for actor.id. Default 'none'. */
+    actorPseudonym: z.enum(['none', 'sha256']).optional(),
+    /** Source IP recording mode (default off; see Cut 4). */
+    recordSourceIp: z.enum(['none', 'raw', 'hashed', 'truncated']).optional(),
+    /** Trusted proxy header for source IP extraction. */
+    trustedProxyHeader: z.string().optional(),
+    trustedProxyCount: z.number().int().nonnegative().optional(),
+    /** User agent recording mode. */
+    recordUserAgent: z.enum(['none', 'raw', 'truncated']).optional(),
+})
+    .strict();
+/**
+ * Top-level audit config. v1 ships only the `history` variant;
+ * the discriminated-union shape leaves room for v2 external-sink
+ * providers without touching the consumer code path.
+ */
+export const AuditConfigSchema = historyAuditSchema;
+/**
+ * Defaults per design-audit.md "Configuration":
+ *   - `provider: 'history'` is implicit when admin.audit absent
+ *   - `strict: false` (fail-open)
+ *   - `actorPseudonym: 'none'` (raw subject)
+ *   - `recordSourceIp: 'none'` (off)
+ *   - `recordUserAgent: 'none'` (off)
+ */
+export const DEFAULT_AUDIT_CONFIG = {
+    provider: 'history',
+    strict: false,
+    actorPseudonym: 'none',
+    recordSourceIp: 'none',
+    recordUserAgent: 'none',
+};
+//# sourceMappingURL=config.js.map

package/dist/audit/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/audit/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;GAIG;AACH,MAAM,eAAe,GAAG,CAAC;KACtB,MAAM,CAAC;IACN,6DAA6D;IAC7D,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC9C,iDAAiD;IACjD,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAChE,CAAC;KACD,MAAM,EAAE,CAAA;AAEX;;;;GAIG;AACH,MAAM,kBAAkB,GAAG,CAAC;KACzB,MAAM,CAAC;IACN,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IAC9B,SAAS,EAAE,eAAe,CAAC,QAAQ,EAAE;IACrC,sEAAsE;IACtE,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC9B,0DAA0D;IAC1D,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE;IACrD,yDAAyD;IACzD,cAAc,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,QAAQ,EAAE;IACzE,qDAAqD;IACrD,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACzC,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;IAC5D,iCAAiC;IACjC,eAAe,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,QAAQ,EAAE;CACjE,CAAC;KACD,MAAM,EAAE,CAAA;AAEX;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,kBAAkB,CAAA;AAInD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAgB;IAC/C,QAAQ,EAAE,SAAS;IACnB,MAAM,EAAE,KAAK;IACb,cAAc,EAAE,MAAM;IACtB,cAAc,EAAE,MAAM;IACtB,eAAe,EAAE,MAAM;CACxB,CAAA"}

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