@wtfalch/audit 0.1.0 → 0.3.0

package/README.md

@@ -70,6 +70,40 @@ const touched = await ledger.erase(tx, { subject: personId, pseudonym, email });
 uses: `tenant.invoice_paid` is out, `invoice.paid` is in. The core's
 namespaces are the trusted base's.
 
+## A writer for an embedding service
+
+A service that wants a trail (a forum's moderation, a mail admin's writes) gets
+a writer, never the signer. The host binds one per namespace:
+
+```ts
+export const forumAudit = ledger.writer({ namespace: 'thread', handle: db });
+createThreads({ db, gates, audit: forumAudit });
+```
+
+The writer signs `thread.*` and refuses everything else; the actor is whoever
+the service resolved; context, actor class and tenant default to what the
+host bound. A caller passes its transaction as the second argument when the
+row must commit with the change it records.
+
+## A host's own columns
+
+A host that needs a column beside the ledger's (a team, a region) declares
+its table over the package's builders and hands it to the ledger:
+
+```ts
+import { AUDIT_COLUMNS, auditIndexes, createLedger } from '@wtfalch/audit';
+
+export const auditEvents = pgTable('audit_events', { ...AUDIT_COLUMNS, teamId: uuid('team_id') }, (t) =>
+  auditIndexes(t),
+);
+const ledger = createLedger({ vocabulary, table: auditEvents, schemaVersion: core.version });
+await ledger.sign(tx, { ...input, extra: { teamId } });
+```
+
+`extra` takes host columns only: a ledger column there is refused, and so is a
+key the table does not declare. The host's own migration adds the column; the
+package's migration never learns of it.
+
 ## Tests
 
 ```sh

package/dist/ledger.d.ts

@@ -1,5 +1,5 @@
 import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
-import { type AuditEventRow, auditEvents } from './tables.js';
+import { type AuditEventRow, type AuditTable } from './tables.js';
 import type { LedgerVocabulary } from './vocabulary.js';
 /**
  * The host's drizzle handle or a transaction open on it. postgres-js in the
@@ -42,6 +42,12 @@ export interface SignInput {
         readonly id: string;
     } | null;
     readonly occurredAt?: Date;
+    /**
+     * Values for the host's own columns, by the drizzle key the host's table
+     * declares them under (`{ teamId }`), written beside the ledger's. Never a
+     * ledger column: those are validated above and refused here.
+     */
+    readonly extra?: Readonly<Record<string, unknown>>;
 }
 export interface PageOptions {
     /** One tenant's rows; `null` for rows with no tenant; omit for every tenant. */
@@ -65,6 +71,55 @@ export interface Page {
         readonly id: number;
     } | null;
 }
+/**
+ * What an embedding service hands a bound writer for one row. The namespace
+ * is fixed when the host binds the writer, so `action` must sit in it; the
+ * actor is whoever the service resolved (a forum's `who`, a mail admin's
+ * principal), never chosen by the ledger. Everything else is optional and
+ * defaults as `SignInput` does.
+ */
+export interface WriterEvent {
+    readonly action: string;
+    readonly actor: {
+        readonly id: string;
+        readonly display: string;
+        readonly class?: string;
+    };
+    readonly target: {
+        readonly type: string;
+        readonly id: string;
+    };
+    readonly tenantId?: string | null;
+    readonly outcome?: string;
+    readonly reason?: string | null;
+    readonly reference?: string | null;
+    readonly before?: unknown;
+    readonly after?: unknown;
+    readonly subject?: {
+        readonly class: string;
+        readonly id: string;
+    } | null;
+    readonly request?: SignInput['request'];
+    readonly extra?: SignInput['extra'];
+}
+/**
+ * A writer the host bound to one namespace. `handle` is the caller's
+ * transaction when the row must commit with the change it records;
+ * otherwise the handle the host bound.
+ */
+export type AuditWriter = (event: WriterEvent, handle?: Handle) => Promise<void>;
+export interface WriterOptions {
+    /** The namespace the writer may sign in: `thread` admits `thread.pinned` and refuses `tenant.created`. */
+    readonly namespace: string;
+    /** The handle used when the caller passes none. */
+    readonly handle: Handle;
+    /** The context every row carries. Defaults to the vocabulary's first context. */
+    readonly context?: string;
+    /** The actor class when the event names none. Defaults to the vocabulary's first actor class. */
+    readonly actorClass?: string;
+    /** The tenant when the event names none. Defaults to null: a row on the estate log. */
+    readonly tenantId?: string | null;
+}
 export interface EraseInput {
     readonly subject: string;
     readonly pseudonym: string;
@@ -79,10 +134,17 @@ export interface EraseInput {
  * or reads a session: the guarantee that a row's actor is real is the host's,
  * and it holds only while the signer stays private.
  */
+export interface LedgerOptions {
+    readonly vocabulary: LedgerVocabulary;
+    /** The host's own table over `AUDIT_COLUMNS`, when it has columns beside the ledger's. Defaults to the package's `auditEvents`. */
+    readonly table?: AuditTable;
+    /** What `schema_version` every row carries. Defaults to 1; a host whose shared audit words are versioned passes theirs. */
+    readonly schemaVersion?: number;
+}
 export interface Ledger {
     readonly vocabulary: LedgerVocabulary;
     readonly tables: {
-        readonly events: typeof auditEvents;
+        readonly events: AuditTable;
     };
     /** Validates against the vocabulary and inserts, on the handle given: a transaction when the row must commit with the change it records. */
     sign(handle: Handle, input: SignInput): Promise<void>;
@@ -92,7 +154,11 @@ export interface Ledger {
     erase(handle: Handle, input: EraseInput): Promise<number>;
     /** One tenant's rows, oldest first, for a tenant's export. Deterministic order; no secrets are in this table to omit. */
     exportRows(handle: Handle, tenantId: string): Promise<readonly AuditEventRow[]>;
+    /**
+     * A writer for one embedding service, bound to one namespace. This is what
+     * a host hands to `createThreads({ audit })` or a postmaster: it can write
+     * that namespace's events and nothing else, and it never sees `sign`.
+     */
+    writer(options: WriterOptions): AuditWriter;
 }
-export declare function createLedger(options: {
-    vocabulary: LedgerVocabulary;
-}): Ledger;
+export declare function createLedger(options: LedgerOptions): Ledger;

package/dist/ledger.js

@@ -1,9 +1,10 @@
 import { and, asc, desc, eq, lt, or, sql } from 'drizzle-orm';
 import { rowSchema } from './schema.js';
-import { auditEvents } from './tables.js';
+import { auditEvents as auditEvents_ } from './tables.js';
+const LEDGER_KEYS = new Set(Object.keys(auditEvents_));
 export function createLedger(options) {
-    const { vocabulary } = options;
-    const schema = rowSchema(vocabulary);
+    const { vocabulary, table: auditEvents = auditEvents_, schemaVersion = 1 } = options;
+    const schema = rowSchema(vocabulary, { schemaVersion });
     async function sign(handle, input) {
         const meta = vocabulary.events[input.action];
         if (!meta) {
@@ -31,11 +32,19 @@ export function createLedger(options) {
             before: input.before ?? null,
             after: input.after ?? null,
             erased_at: null,
-            schema_version: 1,
+            schema_version: schemaVersion,
             subject_class: input.subject?.class ?? null,
             subject_id: input.subject?.id ?? null,
         });
+        const extra = input.extra ?? {};
+        for (const key of Object.keys(extra)) {
+            if (LEDGER_KEYS.has(key))
+                throw new Error(`audit: "${key}" is a ledger column, not a host column`);
+            if (!(key in auditEvents))
+                throw new Error(`audit: the ledger's table has no column "${key}"`);
+        }
         await handle.insert(auditEvents).values({
+            ...extra,
             occurredAt,
             tenantId: row.tenant_id,
             actorClass: row.actor_class,
@@ -110,5 +119,40 @@ export function createLedger(options) {
             .where(eq(auditEvents.tenantId, tenantId))
             .orderBy(asc(auditEvents.occurredAt), asc(auditEvents.id));
     }
-    return { vocabulary, tables: { events: auditEvents }, sign, page, erase, exportRows };
+    function writer(options) {
+        const { namespace } = options;
+        if (!/^[a-z][a-z0-9_]*$/.test(namespace)) {
+            throw new Error(`audit: "${namespace}" is not a namespace`);
+        }
+        const context = options.context ?? vocabulary.contexts[0];
+        const actorClass = options.actorClass ?? vocabulary.actorClasses[0];
+        if (context === undefined || actorClass === undefined) {
+            throw new Error('audit: the vocabulary has no context or actor class to default to');
+        }
+        return async (event, handle) => {
+            if (!event.action.startsWith(`${namespace}.`)) {
+                throw new Error(`audit: "${event.action}" is outside the namespace "${namespace}" this writer is bound to`);
+            }
+            await sign(handle ?? options.handle, {
+                action: event.action,
+                tenantId: event.tenantId === undefined ? (options.tenantId ?? null) : event.tenantId,
+                actor: {
+                    class: event.actor.class ?? actorClass,
+                    id: event.actor.id,
+                    display: event.actor.display,
+                },
+                context,
+                target: event.target,
+                outcome: event.outcome,
+                reason: event.reason,
+                reference: event.reference,
+                before: event.before,
+                after: event.after,
+                subject: event.subject,
+                request: event.request,
+                extra: event.extra,
+            });
+        };
+    }
+    return { vocabulary, tables: { events: auditEvents }, sign, page, erase, exportRows, writer };
 }

package/dist/schema.d.ts

@@ -20,7 +20,9 @@ export declare function isJsonValue(value: unknown, seen?: WeakSet<object>): boo
  * the break-glass context must carry the session, a reason from the closed
  * code set and a reference; every other row's reason is free text.
  */
-export declare function rowSchema(vocabulary: LedgerVocabulary): z.ZodObject<{
+export declare function rowSchema(vocabulary: LedgerVocabulary, options?: {
+    schemaVersion?: number;
+}): z.ZodObject<{
     occurred_at: z.ZodISODateTime;
     tenant_id: z.ZodNullable<z.ZodString>;
     actor_class: z.ZodEnum<{
@@ -49,7 +51,7 @@ export declare function rowSchema(vocabulary: LedgerVocabulary): z.ZodObject<{
     before: z.ZodNullable<z.ZodUnknown>;
     after: z.ZodNullable<z.ZodUnknown>;
     erased_at: z.ZodNullable<z.ZodISODateTime>;
-    schema_version: z.ZodLiteral<1>;
+    schema_version: z.ZodLiteral<number>;
     subject_class: z.ZodNullable<z.ZodEnum<{
         [x: string]: string;
     }>>;

package/dist/schema.js

@@ -60,7 +60,8 @@ const enumOf = (values) => z.enum([...values]);
  * the break-glass context must carry the session, a reason from the closed
  * code set and a reference; every other row's reason is free text.
  */
-export function rowSchema(vocabulary) {
+export function rowSchema(vocabulary, options = {}) {
+    const schemaVersion = options.schemaVersion ?? 1;
     const eventNames = Object.keys(vocabulary.events);
     const reasonCodes = new Set(vocabulary.breakGlassReasonCodes ?? []);
     return z
@@ -85,7 +86,7 @@ export function rowSchema(vocabulary) {
         before: jsonColumn.nullable(),
         after: jsonColumn.nullable(),
         erased_at: z.iso.datetime({ offset: true }).nullable(),
-        schema_version: z.literal(1),
+        schema_version: z.literal(schemaVersion),
         subject_class: enumOf(vocabulary.actorClasses).nullable(),
         subject_id: identifier(AUDIT_LIMITS.id).nullable(),
     })

package/dist/tables.d.ts

@@ -1,3 +1,4 @@
+import { type ExtraConfigColumn } 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
@@ -5,6 +6,162 @@
  * re-exports this from its own schema module so its drizzle instance and its
  * types know it.
  */
+/**
+ * The ledger's columns, as drizzle builders, so a host that needs a column
+ * of its own beside them (a team, a region) declares
+ * `pgTable('audit_events', { ...AUDIT_COLUMNS, teamId: uuid('team_id') }, …)`
+ * and hands that table to `createLedger`. The package's own `auditEvents`
+ * is the same call with nothing added.
+ */
+export declare const AUDIT_COLUMNS: {
+    id: import("drizzle-orm").IsPrimaryKey<import("drizzle-orm").NotNull<import("drizzle-orm").IsIdentity<import("drizzle-orm/pg-core").PgBigInt53BuilderInitial<"id">, "always">>>;
+    occurredAt: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTimestampBuilderInitial<"occurred_at">>>;
+    tenantId: import("drizzle-orm/pg-core").PgUUIDBuilderInitial<"tenant_id">;
+    actorClass: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilder<{
+        name: "actor_class";
+        dataType: "string";
+        columnType: "PgText";
+        data: string;
+        enumValues: [string, ...string[]];
+        driverParam: string;
+    }>>;
+    actorId: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilder<{
+        name: "actor_id";
+        dataType: "string";
+        columnType: "PgText";
+        data: string;
+        enumValues: [string, ...string[]];
+        driverParam: string;
+    }>>;
+    actorDisplay: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilder<{
+        name: "actor_display";
+        dataType: "string";
+        columnType: "PgText";
+        data: string;
+        enumValues: [string, ...string[]];
+        driverParam: string;
+    }>>;
+    action: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilder<{
+        name: "action";
+        dataType: "string";
+        columnType: "PgText";
+        data: string;
+        enumValues: [string, ...string[]];
+        driverParam: string;
+    }>>;
+    targetType: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilder<{
+        name: "target_type";
+        dataType: "string";
+        columnType: "PgText";
+        data: string;
+        enumValues: [string, ...string[]];
+        driverParam: string;
+    }>>;
+    targetId: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilder<{
+        name: "target_id";
+        dataType: "string";
+        columnType: "PgText";
+        data: string;
+        enumValues: [string, ...string[]];
+        driverParam: string;
+    }>>;
+    outcome: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilder<{
+        name: "outcome";
+        dataType: "string";
+        columnType: "PgText";
+        data: string;
+        enumValues: [string, ...string[]];
+        driverParam: string;
+    }>>;
+    context: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilder<{
+        name: "context";
+        dataType: "string";
+        columnType: "PgText";
+        data: string;
+        enumValues: [string, ...string[]];
+        driverParam: string;
+    }>>;
+    sessionId: import("drizzle-orm/pg-core").PgTextBuilder<{
+        name: "session_id";
+        dataType: "string";
+        columnType: "PgText";
+        data: string;
+        enumValues: [string, ...string[]];
+        driverParam: string;
+    }>;
+    reason: import("drizzle-orm/pg-core").PgTextBuilder<{
+        name: "reason";
+        dataType: "string";
+        columnType: "PgText";
+        data: string;
+        enumValues: [string, ...string[]];
+        driverParam: string;
+    }>;
+    reference: import("drizzle-orm/pg-core").PgTextBuilder<{
+        name: "reference";
+        dataType: "string";
+        columnType: "PgText";
+        data: string;
+        enumValues: [string, ...string[]];
+        driverParam: string;
+    }>;
+    requestId: import("drizzle-orm/pg-core").PgTextBuilder<{
+        name: "request_id";
+        dataType: "string";
+        columnType: "PgText";
+        data: string;
+        enumValues: [string, ...string[]];
+        driverParam: string;
+    }>;
+    ip: import("drizzle-orm/pg-core").PgTextBuilder<{
+        name: "ip";
+        dataType: "string";
+        columnType: "PgText";
+        data: string;
+        enumValues: [string, ...string[]];
+        driverParam: string;
+    }>;
+    userAgent: import("drizzle-orm/pg-core").PgTextBuilder<{
+        name: "user_agent";
+        dataType: "string";
+        columnType: "PgText";
+        data: string;
+        enumValues: [string, ...string[]];
+        driverParam: string;
+    }>;
+    tenantVisible: import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgBooleanBuilderInitial<"tenant_visible">>;
+    before: import("drizzle-orm/pg-core").PgJsonbBuilderInitial<"before">;
+    after: import("drizzle-orm/pg-core").PgJsonbBuilderInitial<"after">;
+    erasedAt: import("drizzle-orm/pg-core").PgTimestampBuilderInitial<"erased_at">;
+    schemaVersion: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgSmallIntBuilderInitial<"schema_version">>>;
+    subjectClass: import("drizzle-orm/pg-core").PgTextBuilder<{
+        name: "subject_class";
+        dataType: "string";
+        columnType: "PgText";
+        data: string;
+        enumValues: [string, ...string[]];
+        driverParam: string;
+    }>;
+    subjectId: import("drizzle-orm/pg-core").PgTextBuilder<{
+        name: "subject_id";
+        dataType: "string";
+        columnType: "PgText";
+        data: string;
+        enumValues: [string, ...string[]];
+        driverParam: string;
+    }>;
+};
+/** The indexes every ledger table carries, for a host declaring its own table over `AUDIT_COLUMNS`. */
+export declare function auditIndexes(t: {
+    [K in keyof typeof AUDIT_COLUMNS]: ExtraConfigColumn;
+}): import("drizzle-orm/pg-core").IndexBuilder[];
+/**
+ * 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, or declares a wider table over `AUDIT_COLUMNS`.
+ */
 export declare const auditEvents: import("drizzle-orm/pg-core").PgTableWithColumns<{
     name: "audit_events";
     schema: undefined;
@@ -420,6 +577,8 @@ export declare const auditEvents: import("drizzle-orm/pg-core").PgTableWithColum
     };
     dialect: "pg";
 }>;
+/** The package's table, or a host's declared over `AUDIT_COLUMNS` with more columns; structurally either. */
+export type AuditTable = typeof auditEvents;
 export type AuditEventRow = typeof auditEvents.$inferSelect;
 export type AuditEventInsert = typeof auditEvents.$inferInsert;
 export declare const tables: {

package/dist/tables.js

@@ -7,7 +7,14 @@ import { bigint, boolean, index, jsonb, pgTable, smallint, text, timestamp, uuid
  * re-exports this from its own schema module so its drizzle instance and its
  * types know it.
  */
-export const auditEvents = pgTable('audit_events', {
+/**
+ * The ledger's columns, as drizzle builders, so a host that needs a column
+ * of its own beside them (a team, a region) declares
+ * `pgTable('audit_events', { ...AUDIT_COLUMNS, teamId: uuid('team_id') }, …)`
+ * and hands that table to `createLedger`. The package's own `auditEvents`
+ * is the same call with nothing added.
+ */
+export const AUDIT_COLUMNS = {
     id: bigint('id', { mode: 'number' }).generatedAlwaysAsIdentity().primaryKey(),
     occurredAt: timestamp('occurred_at', { withTimezone: true }).notNull().default(sql `now()`),
     tenantId: uuid('tenant_id'),
@@ -32,15 +39,27 @@ export const auditEvents = pgTable('audit_events', {
     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`),
-]);
+};
+/** The indexes every ledger table carries, for a host declaring its own table over `AUDIT_COLUMNS`. */
+export function auditIndexes(t) {
+    return [
+        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`),
+    ];
+}
+/**
+ * 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, or declares a wider table over `AUDIT_COLUMNS`.
+ */
+export const auditEvents = pgTable('audit_events', AUDIT_COLUMNS, (t) => auditIndexes(t));
 export const tables = { events: auditEvents };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/audit",
-  "version": "0.1.0",
+  "version": "0.3.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",