@wtfalch/audit 0.1.0

package/dist/tables.js

@@ -0,0 +1,46 @@
+import { sql } from 'drizzle-orm';
+import { bigint, boolean, index, jsonb, pgTable, smallint, text, timestamp, uuid, } from 'drizzle-orm/pg-core';
+/**
+ * The ledger, mirrored from `migrations/0001_audit.sql`, which is the source
+ * of truth: the SQL carries the CHECKs, the append-only triggers, the partial
+ * indexes and the erasure function that drizzle-kit does not generate. A host
+ * re-exports this from its own schema module so its drizzle instance and its
+ * types know it.
+ */
+export const auditEvents = pgTable('audit_events', {
+    id: bigint('id', { mode: 'number' }).generatedAlwaysAsIdentity().primaryKey(),
+    occurredAt: timestamp('occurred_at', { withTimezone: true }).notNull().default(sql `now()`),
+    tenantId: uuid('tenant_id'),
+    actorClass: text('actor_class').notNull(),
+    actorId: text('actor_id').notNull(),
+    actorDisplay: text('actor_display').notNull(),
+    action: text('action').notNull(),
+    targetType: text('target_type').notNull(),
+    targetId: text('target_id').notNull(),
+    outcome: text('outcome').notNull(),
+    context: text('context').notNull(),
+    sessionId: text('session_id'),
+    reason: text('reason'),
+    reference: text('reference'),
+    requestId: text('request_id'),
+    ip: text('ip'),
+    userAgent: text('user_agent'),
+    tenantVisible: boolean('tenant_visible').notNull(),
+    before: jsonb('before'),
+    after: jsonb('after'),
+    erasedAt: timestamp('erased_at', { withTimezone: true }),
+    schemaVersion: smallint('schema_version').notNull().default(1),
+    subjectClass: text('subject_class'),
+    subjectId: text('subject_id'),
+}, (t) => [
+    index('audit_events_tenant_time_idx').on(t.tenantId, t.occurredAt.desc(), t.id.desc()),
+    index('audit_events_actor_time_idx').on(t.actorId, t.occurredAt.desc()),
+    index('audit_events_action_time_idx').on(t.action, t.occurredAt.desc()),
+    index('audit_events_subject_time_idx')
+        .on(t.subjectClass, t.subjectId, t.occurredAt.desc(), t.id.desc())
+        .where(sql `${t.subjectId} is not null`),
+    index('audit_events_request_idx')
+        .on(t.requestId, t.occurredAt.desc())
+        .where(sql `${t.requestId} is not null`),
+]);
+export const tables = { events: auditEvents };

package/dist/vocabulary.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The closed sets a host admits into its ledger. The package enforces them
+ * in TypeScript at write time; the database CHECKs that enumerate the same
+ * sets are the host's own migration, when it has one.
+ *
+ * Built by a host from `@wtfalch/authz`'s `core` (the estate's shared audit
+ * words: the twenty-six authority events, four actor classes, three contexts,
+ * three outcomes, five break-glass reason codes) plus whatever events the
+ * host's own modules declare, through `ledgerVocabulary` below. This package
+ * does not import that package; it takes the words as data.
+ */
+export declare const EVENT_PATTERN: RegExp;
+export interface LedgerEventMeta {
+    /** Whether the tenant's own security log shows rows of this kind. Decided per event, never per write. */
+    readonly tenantVisible: boolean;
+    /** Free for the host: the permission its seam checks before signing this kind. Opaque here. */
+    readonly requires?: string;
+}
+export interface LedgerVocabulary {
+    readonly events: Readonly<Record<string, LedgerEventMeta>>;
+    readonly actorClasses: readonly string[];
+    readonly contexts: readonly string[];
+    readonly outcomes: readonly string[];
+    /** The context whose rows must carry a session, a reason from `breakGlassReasonCodes` and a reference. Omit for a host with no support sessions. */
+    readonly breakGlassContext?: string;
+    readonly breakGlassReasonCodes?: readonly string[];
+}
+export interface LedgerVocabularyInput {
+    readonly events: Readonly<Record<string, LedgerEventMeta>>;
+    readonly actorClasses: readonly string[];
+    readonly contexts: readonly string[];
+    readonly outcomes: readonly string[];
+    readonly breakGlassContext?: string;
+    readonly breakGlassReasonCodes?: readonly string[];
+}
+export declare class LedgerVocabularyError extends Error {
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+/**
+ * Validates and freezes. Every problem is named at once, so a fix is one
+ * edit rather than a loop.
+ */
+export declare function ledgerVocabulary(input: LedgerVocabularyInput): LedgerVocabulary;
+/** The shape of `@wtfalch/authz`'s `core`, as much of it as a ledger needs. Taken structurally. */
+export interface AuthzCoreLike {
+    readonly events: readonly string[];
+    readonly tenantVisible: readonly string[];
+    readonly actorClasses: readonly string[];
+    readonly contexts: readonly string[];
+    readonly outcomes: readonly string[];
+    readonly breakGlass: {
+        readonly reasonCodes: readonly string[];
+    };
+}
+/**
+ * The estate's usual construction: `@wtfalch/authz`'s core words plus the
+ * host's own events. An app's event may not sit in a namespace the core
+ * uses, so `tenant.invoice_paid` is refused while `invoice.paid` is not:
+ * the core's namespaces are the trusted base's, and a module claiming one
+ * would be writing rows a reader takes for authority changes.
+ */
+export declare function ledgerVocabularyFromCore(core: AuthzCoreLike, own?: Readonly<Record<string, LedgerEventMeta>>): LedgerVocabulary;

package/dist/vocabulary.js

@@ -0,0 +1,106 @@
+/**
+ * The closed sets a host admits into its ledger. The package enforces them
+ * in TypeScript at write time; the database CHECKs that enumerate the same
+ * sets are the host's own migration, when it has one.
+ *
+ * Built by a host from `@wtfalch/authz`'s `core` (the estate's shared audit
+ * words: the twenty-six authority events, four actor classes, three contexts,
+ * three outcomes, five break-glass reason codes) plus whatever events the
+ * host's own modules declare, through `ledgerVocabulary` below. This package
+ * does not import that package; it takes the words as data.
+ */
+export const EVENT_PATTERN = /^[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*$/;
+export class LedgerVocabularyError extends Error {
+    problems;
+    constructor(problems) {
+        super(`ledger vocabulary: ${problems.join('; ')}`);
+        this.name = 'LedgerVocabularyError';
+        this.problems = problems;
+    }
+}
+const distinct = (values) => new Set(values).size === values.length;
+/**
+ * Validates and freezes. Every problem is named at once, so a fix is one
+ * edit rather than a loop.
+ */
+export function ledgerVocabulary(input) {
+    const problems = [];
+    const names = Object.keys(input.events);
+    if (names.length === 0)
+        problems.push('at least one event is required');
+    for (const name of names) {
+        if (!EVENT_PATTERN.test(name))
+            problems.push(`event "${name}" is not namespace.name`);
+        if (typeof input.events[name]?.tenantVisible !== 'boolean')
+            problems.push(`event "${name}" needs tenantVisible`);
+    }
+    for (const [label, values] of [
+        ['actorClasses', input.actorClasses],
+        ['contexts', input.contexts],
+        ['outcomes', input.outcomes],
+    ]) {
+        if (values.length === 0)
+            problems.push(`${label} is empty`);
+        if (!distinct(values))
+            problems.push(`${label} repeats a value`);
+        for (const v of values) {
+            if (!/^[a-z][a-z0-9_]{0,63}$/.test(v))
+                problems.push(`${label} value "${v}" is not a lower-case word`);
+        }
+    }
+    if (input.breakGlassContext !== undefined) {
+        if (!input.contexts.includes(input.breakGlassContext))
+            problems.push(`breakGlassContext "${input.breakGlassContext}" is not one of the contexts`);
+        if (!input.breakGlassReasonCodes || input.breakGlassReasonCodes.length === 0)
+            problems.push('breakGlassContext needs breakGlassReasonCodes');
+    }
+    else if (input.breakGlassReasonCodes) {
+        problems.push('breakGlassReasonCodes without a breakGlassContext');
+    }
+    if (problems.length > 0)
+        throw new LedgerVocabularyError(problems);
+    return Object.freeze({
+        events: Object.freeze({ ...input.events }),
+        actorClasses: Object.freeze([...input.actorClasses]),
+        contexts: Object.freeze([...input.contexts]),
+        outcomes: Object.freeze([...input.outcomes]),
+        breakGlassContext: input.breakGlassContext,
+        breakGlassReasonCodes: input.breakGlassReasonCodes
+            ? Object.freeze([...input.breakGlassReasonCodes])
+            : undefined,
+    });
+}
+/**
+ * The estate's usual construction: `@wtfalch/authz`'s core words plus the
+ * host's own events. An app's event may not sit in a namespace the core
+ * uses, so `tenant.invoice_paid` is refused while `invoice.paid` is not:
+ * the core's namespaces are the trusted base's, and a module claiming one
+ * would be writing rows a reader takes for authority changes.
+ */
+export function ledgerVocabularyFromCore(core, own = {}) {
+    const visible = new Set(core.tenantVisible);
+    const reserved = new Set(core.events.map((e) => e.split('.')[0] ?? e));
+    const problems = [];
+    const events = {};
+    for (const name of core.events)
+        events[name] = { tenantVisible: visible.has(name) };
+    for (const [name, meta] of Object.entries(own)) {
+        const ns = name.split('.')[0] ?? name;
+        if (name in events)
+            problems.push(`event "${name}" is already the core's`);
+        else if (reserved.has(ns))
+            problems.push(`event "${name}" sits in the reserved namespace "${ns}"`);
+        else
+            events[name] = meta;
+    }
+    if (problems.length > 0)
+        throw new LedgerVocabularyError(problems);
+    return ledgerVocabulary({
+        events,
+        actorClasses: core.actorClasses,
+        contexts: core.contexts,
+        outcomes: core.outcomes,
+        breakGlassContext: 'break_glass',
+        breakGlassReasonCodes: core.breakGlass.reasonCodes,
+    });
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@wtfalch/audit",
+  "version": "0.1.0",
+  "description": "The estate's append-only audit ledger: the table's shape and walls, erasure, export and readers, with a signer a host builds once inside its trusted base and never exports. Per-app Postgres, a host-supplied vocabulary of closed sets, no framework.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wtfalch/audit",
+    "directory": "packages/audit"
+  },
+  "license": "MIT",
+  "type": "module",
+  "files": ["dist"],
+  "bin": {
+    "audit-migrations": "dist/bin/migrations.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./migrations/*.sql": "./dist/migrations/*.sql",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && mkdir -p dist/migrations && cp src/migrations/*.sql dist/migrations/",
+    "prepack": "pnpm build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "drizzle-orm": ">=0.39.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.5.8",
+    "@types/node": "^22",
+    "drizzle-orm": "^0.39.3",
+    "postgres": "^3.4.5",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.6",
+    "zod": "^4.5.4"
+  }
+}