@wtfalch/audit 0.1.0 → 0.2.0

package/README.md

@@ -70,6 +70,25 @@ 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 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. */
@@ -79,10 +85,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>;
@@ -93,6 +106,4 @@ export interface Ledger {
     /** 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[]>;
 }
-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,

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.2.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",