@willyim/drizzle-audit 0.5.0 → 0.6.0

package/README.md

@@ -179,6 +179,60 @@ withD1AuditedTransaction(db, "user_1", (tx) => { /* ... */ }, {
 })
 ```
 
+## Ambient Context (AsyncLocalStorage)
+
+The explicit `withAuditedTransaction(db, actorId, cb)` is the cross-runtime floor —
+it works everywhere and you pass the actor by hand. The opt-in
+`@willyim/drizzle-audit/context` export adds an *ambient* layer on top: establish
+"who is acting" **once** at an entry boundary (a request, a job, an engine tick),
+then open-or-reuse a single audited transaction anywhere below — the actor is read
+from the ambient store, never threaded through call signatures.
+
+```ts
+import {
+  runWithAuditContext,
+  ensureAuditedTx,
+  currentAudit,
+} from "@willyim/drizzle-audit/context"
+
+// 1. Boundary: set the ambient actor for the unit of work. Pass a thunk to
+//    resolve it LAZILY — it only runs if a write actually happens, so read-only
+//    requests never pay for it (e.g. resolving a session).
+app.use((req, next) =>
+  runWithAuditContext(
+    async () => ({
+      actorId: (await getSession(req)).userId,
+      context: { "app.workspace_id": req.workspaceId },
+    }),
+    next,
+  ),
+)
+
+// 2. Anywhere below: open-or-reuse ONE audited tx. Reads don't call this, so
+//    they never open a transaction. Reentrant — nested calls share the tx.
+async function archive(db, id) {
+  await ensureAuditedTx(db, async (tx) => {
+    await tx.update(items).set({ archived: true }).where(eq(items.id, id))
+  })
+}
+
+// 3. Read the actor for a domain column (inside the callback, where it's resolved).
+async function assign(db, id, to) {
+  await ensureAuditedTx(db, async (tx) => {
+    await tx.insert(assignments).values({ id, to, assignedBy: currentAudit().actorId })
+  })
+}
+```
+
+**Runtime support.** This uses *only* `AsyncLocalStorage` from `node:async_hooks`
+(not `createHook`/`executionAsyncId`/…), which is the subset Cloudflare Workers
+implements. Works on Node, Bun, and Workers — Workers needs the `nodejs_compat`
+flag and a recent compatibility date. If a target lacks ALS, the import throws
+loudly; fall back to the explicit `withAuditedTransaction`.
+
+**Guardrail.** `ensureAuditedTx` (and `currentAudit`) throw if there is no ambient
+context — a missed boundary becomes a loud failure instead of an unattributed write.
+
 ## CLI
 
 Generate a Drizzle migration with audit SQL appended:
@@ -221,6 +275,18 @@ export function createAuditSql() {
 | `setAuditContext(db, actorId, contextKey?, options?)` | Set actor context in current transaction |
 | `withAuditedTransaction(db, actorId, callback, contextKey?, options?)` | Transaction wrapper with actor context |
 
+### `@willyim/drizzle-audit/context`
+
+Opt-in ambient layer (AsyncLocalStorage). See [Ambient Context](#ambient-context-asynclocalstorage).
+
+| Export | Description |
+|---|---|
+| `runWithAuditContext(audit, fn)` | Set the ambient actor for `fn` (`audit` is an `AuditContext` or a lazy thunk) |
+| `ensureAuditedTx(db, run, contextKey?)` | Open-or-reuse one audited tx; actor read from the ambient context |
+| `currentAudit()` | The resolved ambient `AuditContext` (throws if absent/unresolved) |
+| `maybeCurrentAudit()` | The resolved ambient `AuditContext`, or `null` |
+| `hasAuditContext()` | Whether an ambient context is in scope |
+
 ### `@willyim/drizzle-audit`
 
 | Export | Description |

package/dist/src/context/index.d.ts

@@ -0,0 +1,42 @@
+import type { AuditSqlExecutor, AuditTransactionCapable } from "../postgres/types.js";
+/** Opaque to the library: an actor string + the GUC map written for the tx. */
+export type AuditContext = {
+    /** Value written to the actor GUC (default `app.user_id`). */
+    actorId: string;
+    /** Extra session GUCs (full GUC name → value), e.g. `app.workspace_id`. */
+    context?: Record<string, string>;
+};
+/**
+ * How the ambient actor is resolved. Pass a plain `AuditContext` to resolve it
+ * eagerly, or a thunk to resolve it LAZILY — the thunk runs only when the first
+ * audited write actually happens, so read-only units of work never pay for it
+ * (e.g. resolving a session on a request that only reads).
+ */
+export type AuditContextInput = AuditContext | (() => AuditContext | Promise<AuditContext>);
+/**
+ * Establish the ambient audit actor for the duration of `fn`. No transaction is
+ * opened here — `ensureAuditedTx` opens one lazily on the first write below.
+ */
+export declare function runWithAuditContext<T>(audit: AuditContextInput, fn: () => T): T;
+/** The ambient audit context if one is set AND already resolved, else null. */
+export declare function maybeCurrentAudit(): AuditContext | null;
+/**
+ * The ambient audit context. Throws if no context is set, or if it is set but
+ * not yet resolved (a lazy resolver that has not run). It is always resolved
+ * inside an `ensureAuditedTx` callback, which is the intended place to read it
+ * (e.g. to stamp a domain "createdBy" column from the actor).
+ */
+export declare function currentAudit(): AuditContext;
+/** True if an ambient audit context is in scope (resolved or not). */
+export declare function hasAuditContext(): boolean;
+/**
+ * THE primitive: ensure this unit of work runs inside ONE audited transaction,
+ * reusing an already-open one if present (reentrant). The actor is read from the
+ * ambient context (resolving it on first use). Reads should never call this, so
+ * they never open a transaction.
+ *
+ * Throws if called with no ambient audit context — the guardrail that turns a
+ * missed boundary into a loud failure instead of an unattributed write.
+ */
+export declare function ensureAuditedTx<TTransaction extends AuditSqlExecutor, TResult>(db: AuditTransactionCapable<TTransaction>, run: (tx: TTransaction) => Promise<TResult> | TResult, contextKey?: string): Promise<TResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/context/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,gBAAgB,EAChB,uBAAuB,EACxB,MAAM,sBAAsB,CAAA;AA+B7B,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GAAG;IACzB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAA;IACf,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB,YAAY,GACZ,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAA;AAYhD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,KAAK,EAAE,iBAAiB,EACxB,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAIH;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,IAAI,YAAY,GAAG,IAAI,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,YAAY,CAc3C;AAED,sEAAsE;AACtE,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,YAAY,SAAS,gBAAgB,EACrC,OAAO,EAEP,EAAE,EAAE,uBAAuB,CAAC,YAAY,CAAC,EACzC,GAAG,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,EACrD,UAAU,SAAgB,GACzB,OAAO,CAAC,OAAO,CAAC,CAyBlB"}

package/dist/src/context/index.js

@@ -0,0 +1,94 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { setAuditContext } from "../postgres/runtime.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Ambient audit context (opt-in).
+//
+// The explicit `withAuditedTransaction(db, actorId, cb)` from the main entry is
+// the cross-runtime floor: it works everywhere and takes the actor by hand. This
+// module adds an *ambient* layer on top of it, built on `AsyncLocalStorage`:
+//
+//   - establish "who is acting" ONCE at an entry boundary (a request, a job, an
+//     engine tick) with `runWithAuditContext`, then
+//   - open-or-reuse a single audited transaction anywhere below with
+//     `ensureAuditedTx` — the actor is read from the ambient store, never
+//     threaded through call signatures.
+//
+// Runtime support: this uses ONLY `AsyncLocalStorage` from `node:async_hooks`
+// (not `createHook`/`executionAsyncId`/…), which is the subset Cloudflare
+// Workers implements. It works on Node, Bun, and Workers (Workers needs the
+// `nodejs_compat` flag + a recent compatibility date). If a target lacks ALS,
+// fall back to the explicit `withAuditedTransaction` path.
+// ─────────────────────────────────────────────────────────────────────────────
+if (typeof AsyncLocalStorage === "undefined") {
+    throw new Error("@willyim/drizzle-audit/context requires AsyncLocalStorage from node:async_hooks. " +
+        "On Cloudflare Workers enable the `nodejs_compat` flag (with a recent compatibility " +
+        "date). On other runtimes use the explicit withAuditedTransaction(db, actorId, cb) " +
+        "from @willyim/drizzle-audit/postgres instead.");
+}
+const als = new AsyncLocalStorage();
+/**
+ * Establish the ambient audit actor for the duration of `fn`. No transaction is
+ * opened here — `ensureAuditedTx` opens one lazily on the first write below.
+ */
+export function runWithAuditContext(audit, fn) {
+    const resolve = typeof audit === "function" ? audit : () => audit;
+    const resolved = typeof audit === "function" ? null : audit;
+    return als.run({ resolve, resolved, tx: null }, fn);
+}
+/** The ambient audit context if one is set AND already resolved, else null. */
+export function maybeCurrentAudit() {
+    return als.getStore()?.resolved ?? null;
+}
+/**
+ * The ambient audit context. Throws if no context is set, or if it is set but
+ * not yet resolved (a lazy resolver that has not run). It is always resolved
+ * inside an `ensureAuditedTx` callback, which is the intended place to read it
+ * (e.g. to stamp a domain "createdBy" column from the actor).
+ */
+export function currentAudit() {
+    const cell = als.getStore();
+    if (!cell) {
+        throw new Error("no ambient audit context — wrap the unit of work in runWithAuditContext(...)");
+    }
+    if (!cell.resolved) {
+        throw new Error("ambient audit context not resolved yet — read currentAudit() inside an " +
+            "ensureAuditedTx callback, or pass an eager AuditContext to runWithAuditContext");
+    }
+    return cell.resolved;
+}
+/** True if an ambient audit context is in scope (resolved or not). */
+export function hasAuditContext() {
+    return als.getStore() !== undefined;
+}
+/**
+ * THE primitive: ensure this unit of work runs inside ONE audited transaction,
+ * reusing an already-open one if present (reentrant). The actor is read from the
+ * ambient context (resolving it on first use). Reads should never call this, so
+ * they never open a transaction.
+ *
+ * Throws if called with no ambient audit context — the guardrail that turns a
+ * missed boundary into a loud failure instead of an unattributed write.
+ */
+export async function ensureAuditedTx(db, run, contextKey = "app.user_id") {
+    const cell = als.getStore();
+    if (!cell) {
+        throw new Error("audited write outside an audit context — wrap the unit of work in " +
+            "runWithAuditContext(...) (or use the explicit withAuditedTransaction)");
+    }
+    // Reentrant: a tx is already open in this context — reuse it.
+    if (cell.tx)
+        return run(cell.tx);
+    const audit = cell.resolved ?? (cell.resolved = await cell.resolve());
+    return db.transaction(async (tx) => {
+        await setAuditContext(tx, audit.actorId, contextKey, {
+            context: audit.context,
+        });
+        cell.tx = tx;
+        try {
+            return await run(tx);
+        }
+        finally {
+            cell.tx = null;
+        }
+    });
+}

package/dist/test/context.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context.test.d.ts","sourceRoot":"","sources":["../../test/context.test.ts"],"names":[],"mappings":""}

package/dist/test/context.test.js

@@ -0,0 +1,98 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { currentAudit, ensureAuditedTx, hasAuditContext, maybeCurrentAudit, runWithAuditContext, } from "../src/context/index.js";
+function makeFakeDb() {
+    let txCount = 0;
+    const executed = [];
+    const tx = {
+        async execute(query) {
+            executed.push(query);
+            return undefined;
+        },
+    };
+    const db = {
+        async transaction(cb) {
+            txCount++;
+            return cb(tx);
+        },
+    };
+    return {
+        db,
+        tx,
+        executed,
+        get txCount() {
+            return txCount;
+        },
+    };
+}
+test("ensureAuditedTx opens one tx and writes the actor GUC", async () => {
+    const fake = makeFakeDb();
+    let inside;
+    await runWithAuditContext({ actorId: "user_1" }, () => ensureAuditedTx(fake.db, async (tx) => {
+        inside = tx;
+    }));
+    assert.equal(fake.txCount, 1);
+    assert.equal(inside, fake.tx);
+    // setAuditContext ran at least the actor set_config.
+    assert.ok(fake.executed.length >= 1);
+});
+test("nested ensureAuditedTx reuses the open tx (no second transaction)", async () => {
+    const fake = makeFakeDb();
+    const seen = [];
+    await runWithAuditContext({ actorId: "user_1" }, () => ensureAuditedTx(fake.db, async (tx) => {
+        seen.push(tx);
+        await ensureAuditedTx(fake.db, async (tx2) => {
+            seen.push(tx2);
+            await ensureAuditedTx(fake.db, async (tx3) => seen.push(tx3));
+        });
+    }));
+    assert.equal(fake.txCount, 1, "only one transaction is opened");
+    assert.equal(seen.length, 3);
+    assert.ok(seen.every((t) => t === fake.tx));
+});
+test("lazy resolver runs exactly once, on first write", async () => {
+    const fake = makeFakeDb();
+    let resolved = 0;
+    let seenActor;
+    await runWithAuditContext(() => {
+        resolved++;
+        return { actorId: "lazy" };
+    }, async () => {
+        assert.equal(resolved, 0, "not resolved before any write");
+        assert.equal(maybeCurrentAudit(), null);
+        await ensureAuditedTx(fake.db, async () => {
+            seenActor = currentAudit().actorId;
+            // reentrant — must not re-resolve
+            await ensureAuditedTx(fake.db, async () => { });
+        });
+        // resolved value is memoised on the cell
+        assert.equal(maybeCurrentAudit()?.actorId, "lazy");
+    });
+    assert.equal(resolved, 1);
+    assert.equal(seenActor, "lazy");
+});
+test("eager context resolves immediately (currentAudit before any write)", async () => {
+    await runWithAuditContext({ actorId: "eager", context: { "app.workspace_id": "ws_9" } }, async () => {
+        assert.equal(currentAudit().actorId, "eager");
+        assert.equal(currentAudit().context?.["app.workspace_id"], "ws_9");
+    });
+});
+test("guardrail: writes / reads outside a context fail loudly", async () => {
+    const fake = makeFakeDb();
+    assert.equal(hasAuditContext(), false);
+    assert.equal(maybeCurrentAudit(), null);
+    assert.throws(() => currentAudit(), /no ambient audit context/);
+    await assert.rejects(() => ensureAuditedTx(fake.db, async () => { }), /outside an audit context/);
+    assert.equal(fake.txCount, 0);
+});
+test("context is isolated per runWithAuditContext scope", async () => {
+    const a = runWithAuditContext({ actorId: "A" }, async () => {
+        await Promise.resolve();
+        return currentAudit().actorId;
+    });
+    const b = runWithAuditContext({ actorId: "B" }, async () => {
+        await Promise.resolve();
+        return currentAudit().actorId;
+    });
+    assert.deepEqual(await Promise.all([a, b]), ["A", "B"]);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willyim/drizzle-audit",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Lightweight audit logging for Drizzle ORM using database triggers (Postgres + D1/SQLite)",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -8,6 +8,7 @@
   "exports": {
     ".": "./dist/src/index.js",
     "./postgres": "./dist/src/postgres/index.js",
+    "./context": "./dist/src/context/index.js",
     "./d1": "./dist/src/d1/index.js",
     "./d1-runtime": "./dist/src/d1-runtime/index.js"
   },