better-supabase 0.13.0 → 0.15.0

package/dist/blocks/audit/index.js

@@ -1,14 +1,870 @@
-import { n as dbError } from "../../errors-D7u24ZJH.js";
+import { t as DbException } from "../../db-exception-Lngc1W49.js";
+import { n as dbError } from "../../errors-BVFgt8BZ.js";
+import { n as isRecord } from "../../guards-6F2bCtQR.js";
 import { s as nowInstant } from "../../temporal-DLZlWbOi.js";
-import { t as AsyncResult } from "../../result-DIT_qp4G.js";
+import { t as temporal } from "../../temporal-required-Dy0GGD8E.js";
+import { a as ok, r as err, t as AsyncResult } from "../../result-ntFBW2p2.js";
 import { t as base64ToText } from "../../base64-B9Wlsdj7.js";
+import { t as SPEC_PINS } from "../../spec-pins-C1Vm8OBl.js";
+import { i as sqlIdent } from "../../template-Drgg3v2J.js";
+import { t as MAX_BATCH } from "../../batch-limit-DKVQDz4o.js";
 import { t as auditSqlOptions } from "../../options-CljDnQt2.js";
+import { n as whileSignedIn, t as defineController } from "../../controller-BEliOBOv.js";
+import { B as dbTransport, C as optionalText, D as recordOf, F as stringsOf, H as rpcTransport, I as textOf, M as seconds, R as toInstant, S as optionalInstant, U as sqlTransport, c as chunksOf, i as batchResultsOf, j as run, k as recordsOf, m as instantArg, n as applyTemporal, o as blockCall, w as pageOf } from "../../block-helpers-CtBdjgO4.js";
+import { r as withBlockHooks } from "../../block-hooks-BfxX3682.js";
+import { r as toCsv } from "../../csv-2rXGPNtP.js";
 import { n as event, t as defineEvents } from "../../event-map-CtPFhcOp.js";
-import { i as sqlTransport, r as rpcTransport, t as dbTransport } from "../../block-transport-Ds0C2mUf.js";
-import { C as optionalText, D as recordOf, I as textOf, R as toInstant, k as recordsOf, n as applyTemporal, o as blockCall } from "../../block-helpers-DwE32_gT.js";
-import { n as defineBlock } from "../../define-block-B6Gjs57G.js";
-import { a as exportAuditLog, c as toOcsf, i as auditListQuery, n as auditEventOf, o as purgeAuditLog, r as auditSink, s as setAuditRetention, t as createAudit } from "../../audit-log-5aTnl7W2.js";
-import { t as createAuditLogController } from "../../client-DkI0oyR7.js";
+import { n as defineBlock } from "../../define-block-BGqOO8B3.js";
+import { i as undoToken } from "../../undo-BjCChCmH.js";
+import { n as defineListQuery } from "../../list-query-BKy2zBaT.js";
+//#region src/blocks/audit/audit.ts
+function sqlPurgeCalls(sql) {
+	return {
+		async purge(olderThan, batch, tenant) {
+			const [row] = await sql.queryRaw(tenant === void 0 ? "select better_supabase.purge_audit_log($1::interval, $2) as n" : "select better_supabase.purge_audit_log($1::interval, $2, $3, true) as n", tenant === void 0 ? [olderThan, batch] : [
+				olderThan,
+				batch,
+				tenant
+			]);
+			return Number(row?.n ?? 0);
+		},
+		async tenants() {
+			return (await sql.queryRaw("select tenant::text from better_supabase.audit_events_tenants($1::interval) as tenant", ["1 day"])).map((row) => row.tenant);
+		}
+	};
+}
+function transportPurgeCalls(transport, schema) {
+	const call = blockCall(transport, schema);
+	return {
+		purge: (olderThan, batch, tenant) => call("purge_audit_log", {
+			older_than: olderThan,
+			batch,
+			tenant,
+			for_tenant: tenant === void 0 ? void 0 : true
+		}, (value) => Number(value ?? 0)).orThrow(),
+		tenants: () => call("audit_events_tenants", { older_than: "1 day" }, (value) => {
+			if (value === null || value === void 0) return [];
+			if (!Array.isArray(value)) throw new TypeError("audit_events_tenants returned one value, not rows: pass a SqlClient instead of sqlTransport");
+			return value.map((tenant) => tenant === null || tenant === void 0 ? null : String(tenant));
+		}).orThrow()
+	};
+}
+const RETENTION_MANY = /* @__PURE__ */ new WeakMap();
+/**
+* Deletes audit entries past their retention and returns how many. Without
+* `retention` it is one `purge_audit_log` call (which honours an
+* `audit_retention` SQL hook); with it, each tenant is purged with its own
+* interval. Run it from a schedule until it returns 0.
+*/
+function purgeAuditLog(source, options = {}) {
+	applyTemporal(options);
+	const olderThan = seconds(options.olderThan ?? "1 year");
+	const batch = options.batch ?? 1e4;
+	const calls = "call" in source ? transportPurgeCalls(source, options.schema ?? "better_supabase") : sqlPurgeCalls(source);
+	const { retention } = options;
+	if (!retention) return run(() => calls.purge(olderThan, batch));
+	return run(async () => {
+		const tenants = await calls.tenants();
+		const many = RETENTION_MANY.get(retention);
+		const ids = tenants.flatMap((tenant) => tenant === null ? [] : [tenant]);
+		const known = many && ids.length > 0 ? await many(ids) : void 0;
+		let purged = 0;
+		for (const tenant of tenants) {
+			const days = known ? tenant === null ? void 0 : known.get(tenant) : await retention(tenant);
+			const keep = days === void 0 ? olderThan : `${days} days`;
+			purged += await calls.purge(keep, batch, tenant);
+		}
+		return purged;
+	});
+}
+/**
+* A `retention` callback for `purgeAuditLog` that reads each tenant's days from
+* a column (a plan's `audit_retention_days`, say). `purgeAuditLog` reads every
+* tenant's days in one query; a direct call reads one tenant.
+*/
+function setAuditRetention(sql, source) {
+	const [schema, name] = source.table.includes(".") ? source.table.split(".", 2) : ["public", source.table];
+	const key = sqlIdent(source.key ?? "id");
+	const from = `${sqlIdent(source.column)}::integer as days from ${sqlIdent(schema)}.${sqlIdent(name)}`;
+	const kept = (days) => typeof days === "number" && days > 0 ? days : void 0;
+	const retention = async (tenant) => {
+		if (tenant === null) return;
+		const [row] = await sql.queryRaw(`select ${from} where ${key}::text = $1`, [tenant]);
+		return kept(row?.days);
+	};
+	RETENTION_MANY.set(retention, async (tenants) => {
+		const rows = await sql.queryRaw(`select ${key}::text as tenant, ${from} where ${key}::text = any($1::text[])`, [tenants]);
+		const days = /* @__PURE__ */ new Map();
+		for (const row of rows) {
+			const value = kept(row.days);
+			if (value !== void 0) days.set(row.tenant, value);
+		}
+		return days;
+	});
+	return retention;
+}
+const COLUMNS = [
+	"id",
+	"occurred_at",
+	"op",
+	"table_name",
+	"record_id",
+	"changed",
+	"actor_id",
+	"actor_role",
+	"organization_id",
+	"event_type",
+	"category",
+	"outcome",
+	"source",
+	"target_type",
+	"metadata"
+];
+function entryOf$1(row) {
+	const text = (key) => optionalText(row[key]);
+	const pick = (key, value) => value === void 0 ? {} : { [key]: value };
+	const metadata = row["metadata"];
+	return {
+		id: textOf(row["id"]),
+		occurredAt: optionalInstant(row["occurred_at"]) ?? temporal().Instant.fromEpochMilliseconds(0),
+		op: textOf(row["op"]),
+		...pick("table", text("table_name")),
+		...pick("record", text("record_id")),
+		...pick("changed", row["changed"] === null || row["changed"] === void 0 ? void 0 : stringsOf(row["changed"])),
+		...pick("actor", text("actor_id")),
+		...pick("actorRole", text("actor_role")),
+		...pick("organizationId", text("organization_id")),
+		...pick("eventType", text("event_type")),
+		...pick("category", text("category")),
+		...pick("outcome", text("outcome")),
+		...pick("source", text("source")),
+		...pick("targetType", text("target_type")),
+		...pick("metadata", typeof metadata === "object" && metadata !== null && !Array.isArray(metadata) ? metadata : void 0)
+	};
+}
+const ENTITY_ACTIVITY = {
+	insert: [1, "Create"],
+	update: [3, "Update"],
+	delete: [4, "Delete"]
+};
+const API_ACTIVITY = [
+	[
+		/(^|[._])(create|created|add|added|insert|inserted)$/,
+		1,
+		"Create"
+	],
+	[
+		/(^|[._])(read|viewed|view|get|list|exported|export)$/,
+		2,
+		"Read"
+	],
+	[
+		/(^|[._])(update|updated|change|changed|rename|renamed)$/,
+		3,
+		"Update"
+	],
+	[
+		/(^|[._])(delete|deleted|remove|removed|revoke|revoked)$/,
+		4,
+		"Delete"
+	]
+];
+function status(outcome) {
+	switch (outcome) {
+		case void 0:
+		case "success":
+		case "succeeded": return {
+			status_id: 1,
+			status: "Success"
+		};
+		case "failure":
+		case "failed":
+		case "denied": return {
+			status_id: 2,
+			status: "Failure"
+		};
+		default: return {
+			status_id: 99,
+			status: outcome
+		};
+	}
+}
+/**
+* One entry as an OCSF event (`SPEC_PINS.ocsf`). Row changes are Entity
+* Management (3004); semantic events are API Activity (6003), with the activity
+* read from the event type's last segment (`deal.created` is Create).
+*/
+function toOcsf(entry, product) {
+	const metadata = {
+		version: SPEC_PINS.ocsf,
+		product,
+		uid: entry.id,
+		log_name: "audit_events",
+		...entry.organizationId ? { tenant_uid: entry.organizationId } : {}
+	};
+	const actor = { user: {
+		uid: entry.actor ?? "system",
+		...entry.actorRole ? { type: entry.actorRole } : {}
+	} };
+	const base = {
+		severity_id: 1,
+		severity: "Informational",
+		time: entry.occurredAt.epochMilliseconds,
+		...status(entry.outcome),
+		metadata,
+		actor
+	};
+	const known = ENTITY_ACTIVITY[entry.op];
+	if (entry.op !== "event" && known) {
+		const [activity, name] = known;
+		return {
+			class_uid: 3004,
+			class_name: "Entity Management",
+			category_uid: 3,
+			category_name: "Identity & Access Management",
+			activity_id: activity,
+			activity_name: name,
+			type_uid: 300400 + activity,
+			...base,
+			entity: {
+				uid: entry.record ?? "",
+				type: entry.table ?? "row"
+			},
+			...entry.changed ? { unmapped: { changed: entry.changed } } : {}
+		};
+	}
+	const operation = entry.eventType ?? entry.op;
+	const match = API_ACTIVITY.find(([pattern]) => pattern.test(operation));
+	const [activity, name] = match ? [match[1], match[2]] : [99, operation];
+	return {
+		class_uid: 6003,
+		class_name: "API Activity",
+		category_uid: 6,
+		category_name: "Application Activity",
+		activity_id: activity,
+		activity_name: name,
+		type_uid: 600300 + activity,
+		...base,
+		api: { operation },
+		src_endpoint: { name: entry.source ?? "database" },
+		...entry.record || entry.targetType ? { resources: [{
+			uid: entry.record ?? "",
+			type: entry.targetType ?? entry.table ?? "resource"
+		}] } : {},
+		...entry.metadata || entry.category ? { unmapped: {
+			...entry.category ? { category: entry.category } : {},
+			...entry.metadata ? { metadata: entry.metadata } : {}
+		} } : {}
+	};
+}
+/**
+* Streams one tenant's audit entries as newline-delimited JSON, in id order,
+* one keyset query per batch. Run it with a member's claims (the `readPolicy`
+* filters) or as the service role. It reads the managed module's column names;
+* for an adopted log, the version 3 columns or CSV, use
+* `createAudit().export()`, which reads `list_audit_events`.
+*/
+function exportAuditLog(sql, options) {
+	applyTemporal(options);
+	const format = options.format ?? "ndjson";
+	if (format === "ocsf" && !options.product) throw new TypeError("exportAuditLog: the ocsf format needs product");
+	const batch = options.batch ?? 1e3;
+	const [schema, name] = (options.table ?? "better_supabase.audit_events").split(".", 2);
+	const text = `select ${COLUMNS.map((column) => sqlIdent(column)).join(", ")}
+from ${sqlIdent(schema)}.${sqlIdent(name)}
+where organization_id::text = $1
+  and ($2::timestamptz is null or occurred_at >= $2)
+  and ($3::timestamptz is null or occurred_at < $3)
+  and id > $4
+order by id
+limit $5`;
+	const encoder = new TextEncoder();
+	let after = "0";
+	let done = false;
+	return new ReadableStream({ async pull(controller) {
+		if (done) return;
+		const rows = await sql.queryRaw(text, [
+			options.organizationId,
+			instantArg(options.from) ?? null,
+			instantArg(options.to) ?? null,
+			after,
+			batch
+		]);
+		const lines = rows.map((row) => {
+			const entry = entryOf$1(row);
+			return JSON.stringify(format === "ocsf" ? toOcsf(entry, options.product) : entry);
+		});
+		if (lines.length > 0) {
+			controller.enqueue(encoder.encode(`${lines.join("\n")}\n`));
+			after = textOf(rows.at(-1)["id"]);
+		}
+		if (rows.length < batch) {
+			done = true;
+			controller.close();
+		}
+	} });
+}
+const FACETS = [
+	[
+		"table",
+		"table_name",
+		"tableName"
+	],
+	[
+		"record",
+		"record_id",
+		"recordId"
+	],
+	[
+		"op",
+		"op",
+		"op"
+	],
+	[
+		"actor",
+		"actor_id",
+		"actorId"
+	],
+	[
+		"event",
+		"event_type",
+		"eventType"
+	],
+	[
+		"category",
+		"category",
+		"category"
+	],
+	[
+		"outcome",
+		"outcome",
+		"outcome"
+	],
+	[
+		"target",
+		"target_type",
+		"targetType"
+	]
+];
+/**
+* A cursor-paged list over the audit table through the Data API or `ctx.sql`
+* (generate types for the module's schema to get it in your models; facets
+* follow the managed column names). `createAudit().list()` reads
+* `list_audit_events` instead, with an adopted log's columns mapped. Filtered
+* by actor, table, record, event type, category, outcome and target, newest
+* first. The `readPolicy` and the `restricted` table decide what a member
+* sees.
+*/
+function auditListQuery(betterSupabase, table, options = {}) {
+	const meta = betterSupabase.meta.tables[table];
+	if (!meta) throw new TypeError(`auditListQuery: unknown table "${table}"`);
+	const camel = meta.columns["occurredAt"] !== void 0;
+	const col = (snake, camelName) => camel ? camelName : snake;
+	const facets = Object.fromEntries(FACETS.map(([key, snake, camelName]) => [key, col(snake, camelName)]).filter(([, column]) => meta.columns[column] !== void 0));
+	const occurredAt = col("occurred_at", "occurredAt");
+	const config = {
+		facets,
+		sorts: {
+			newest: [{ [occurredAt]: "desc" }, { id: "desc" }],
+			oldest: [{ [occurredAt]: "asc" }, { id: "asc" }]
+		},
+		defaultSort: "newest",
+		pagination: "cursor",
+		...options.pageSize === void 0 ? {} : { pageSize: options.pageSize },
+		...options.maxPageSize === void 0 ? {} : { maxPageSize: options.maxPageSize }
+	};
+	const list = defineListQuery(betterSupabase, table, config);
+	return Object.assign(list, { between(from, to) {
+		const range = {
+			...from ? { gte: from.toString() } : {},
+			...to ? { lt: to.toString() } : {}
+		};
+		return Object.keys(range).length === 0 ? {} : { [occurredAt]: range };
+	} });
+}
+//#endregion
+//#region src/blocks/audit/csv.ts
+const DEFAULT_COLUMNS = [
+	"id",
+	"occurredAt",
+	"op",
+	"eventType",
+	"category",
+	"outcome",
+	"actorId",
+	"actorLabel",
+	"actorRole",
+	"actorKind",
+	"tenant",
+	"tenantLabel",
+	"table",
+	"record",
+	"targetType",
+	"targetLabel",
+	"summary",
+	"changed",
+	"source",
+	"requestId",
+	"correlationId",
+	"impersonatedBy",
+	"metadata"
+];
+const keyOf = (column) => typeof column === "string" ? column : column.key;
+/** Whether the columns read restricted details. */
+const revealsDetails = (columns) => (columns ?? []).some((column) => keyOf(column).startsWith("restricted."));
+function defaultRow(record, keys, details) {
+	const row = {
+		...record,
+		occurredAt: record.occurredAt.toString(),
+		changed: record.changed?.join(" ")
+	};
+	for (const key of keys) {
+		const [scope, ...rest] = key.split(".");
+		const name = rest.join(".");
+		if (scope === "columns" && name !== "") row[key] = record.columns?.[name];
+		if (scope === "restricted" && name !== "") row[key] = new Map(Object.entries(details ?? {})).get(name);
+	}
+	return row;
+}
+/** One cell per line, escaped like the rows. */
+const lines = (values) => values.map((value) => {
+	const csv = toCsv([{ value }], { columns: ["value"] });
+	return csv.slice(csv.indexOf("\r\n") + 2);
+}).join("");
+/** A page of CSV, with the preamble and header row on the first. */
+function csvPage(entries, options, details, first) {
+	const columns = options.columns ?? DEFAULT_COLUMNS;
+	const keys = columns.map(keyOf);
+	const rows = entries.map((record) => {
+		const found = details?.get(record.id);
+		const row = defaultRow(record, keys, found);
+		return options.formatRow ? options.formatRow(row, record, found) : row;
+	});
+	const csv = toCsv(rows, { columns: keys });
+	const body = csv.slice(csv.indexOf("\r\n") + 2);
+	if (!first) return body;
+	const header = toCsv([], { columns: columns.map((column) => typeof column === "string" ? column : column.label) });
+	return `${lines(options.preamble ?? [])}${header}${body}`;
+}
+//#endregion
+//#region src/blocks/audit/sink.ts
+const textIn = (value) => typeof value === "string" && value !== "" ? value : void 0;
+const defaultCategory = (eventType) => eventType.startsWith("account.") || eventType.startsWith("support.") ? "security" : void 0;
+/**
+* The impersonation fields of a `support.*` event: its session, admin and
+* reason.
+*/
+function supportFields(eventType, data) {
+	if (!eventType.startsWith("support.") || data === void 0) return {};
+	const sessionId = textIn(data["sessionId"]);
+	const adminId = textIn(data["adminId"]);
+	const reason = textIn(data["reason"]);
+	return {
+		...sessionId === void 0 ? {} : { supportSessionId: sessionId },
+		...adminId === void 0 ? {} : { impersonatedBy: adminId },
+		...reason === void 0 ? {} : { impersonationReason: reason }
+	};
+}
+/**
+* The audit entry for one CloudEvent: its type without the prefix, its subject
+* as the record, the tenant from the `tenant` or `partitionkey` extension (or
+* `data.organizationId`), and the data as metadata. The idempotency key is the
+* event's source and id, so a redelivery records once. A `support.*` event also
+* fills the impersonation columns from its `sessionId`, `adminId` and
+* `reason`.
+*/
+function auditEventOf(event, options = {}) {
+	const prefix = `${options.typePrefix ?? "dev.better-supabase"}.`;
+	const data = isRecord(event.data) ? event.data : void 0;
+	const organizationId = textIn(event["tenant"]) ?? textIn(event["partitionkey"]) ?? textIn(data?.["organizationId"]);
+	const actorId = textIn(data?.["actorId"]);
+	const metadata = data ?? (event.data === void 0 ? void 0 : { data: event.data });
+	const eventType = event.type.startsWith(prefix) ? event.type.slice(prefix.length) : event.type;
+	const category = (options.category ?? defaultCategory)(eventType);
+	return {
+		eventType,
+		idempotencyKey: `${event.source}#${event.id}`,
+		...category === void 0 ? {} : { category },
+		...event.subject === void 0 ? {} : { record: event.subject },
+		...organizationId === void 0 ? {} : { organizationId },
+		...actorId === void 0 ? {} : { actorId },
+		...metadata === void 0 ? {} : { metadata },
+		...supportFields(eventType, data)
+	};
+}
+/**
+* An `EventSink` that records CloudEvents in the audit log, one `recordMany`
+* call per chunk of at most `MAX_BATCH` events. `send` throws the first failure
+* once every chunk ran, so an outbox relay retries the batch; the idempotency
+* key keeps the entries already written from repeating.
+*/
+function auditSink(recordMany, options = {}) {
+	return { async send(events) {
+		let failure;
+		for (const chunk of chunksOf(events, MAX_BATCH)) {
+			const results = await recordMany(chunk.map((event) => auditEventOf(event, options)));
+			if (!results.ok) {
+				failure ??= new DbException(results.error);
+				continue;
+			}
+			for (const result of results.data) if (!result.ok) failure ??= new DbException(result.error);
+		}
+		if (failure !== void 0) throw failure;
+	} };
+}
+//#endregion
+//#region src/blocks/audit/audit-log.ts
+function revertedOf(value) {
+	const record = isRecord(value) ? value : {};
+	const entries = Array.isArray(record["entries"]) ? record["entries"].filter((entry) => typeof entry === "string") : [];
+	return {
+		reverted: typeof record["reverted"] === "number" ? record["reverted"] : 0,
+		undo: entries.length > 0 ? undoToken([{
+			fn: "revert_audit_entries",
+			args: { entries }
+		}]) : null
+	};
+}
+const TEXT_KEYS = [
+	"op",
+	"table",
+	"record",
+	"actorId",
+	"actorRole",
+	"actorKind",
+	"actorLabel",
+	"tenant",
+	"tenantLabel",
+	"impersonatedBy",
+	"impersonationReason",
+	"supportSession",
+	"eventType",
+	"category",
+	"outcome",
+	"source",
+	"targetType",
+	"targetLabel",
+	"summary",
+	"requestId",
+	"correlationId",
+	"scope"
+];
+function recordOfEntry(value) {
+	const row = isRecord(value) ? value : {};
+	const text = {};
+	for (const key of TEXT_KEYS) {
+		const found = optionalText(row[key]);
+		if (found !== void 0) text[key] = found;
+	}
+	const json = (key) => {
+		const found = row[key];
+		return isRecord(found) ? found : void 0;
+	};
+	const old = json("old");
+	const next = json("new");
+	const metadata = json("metadata");
+	const columns = json("columns");
+	return {
+		id: textOf(row["id"]),
+		occurredAt: optionalInstant(row["occurredAt"]) ?? temporal().Instant.fromEpochMilliseconds(0),
+		...text,
+		...Array.isArray(row["changed"]) ? { changed: stringsOf(row["changed"]) } : {},
+		...old === void 0 ? {} : { old },
+		...next === void 0 ? {} : { new: next },
+		...metadata === void 0 ? {} : { metadata },
+		...columns === void 0 ? {} : { columns }
+	};
+}
+/** The record in `exportAuditLog`'s `AuditEntry` shape, for `toOcsf`. */
+function entryOf(record) {
+	return {
+		id: record.id,
+		occurredAt: record.occurredAt,
+		op: record.op ?? "event",
+		...record.table === void 0 ? {} : { table: record.table },
+		...record.record === void 0 ? {} : { record: record.record },
+		...record.changed === void 0 ? {} : { changed: record.changed },
+		...record.actorId === void 0 ? {} : { actor: record.actorId },
+		...record.actorRole === void 0 ? {} : { actorRole: record.actorRole },
+		...record.tenant === void 0 ? {} : { organizationId: record.tenant },
+		...record.eventType === void 0 ? {} : { eventType: record.eventType },
+		...record.category === void 0 ? {} : { category: record.category },
+		...record.outcome === void 0 ? {} : { outcome: record.outcome },
+		...record.source === void 0 ? {} : { source: record.source },
+		...record.targetType === void 0 ? {} : { targetType: record.targetType },
+		...record.metadata === void 0 ? {} : { metadata: record.metadata }
+	};
+}
+const many = (value) => value === void 0 ? void 0 : typeof value === "string" ? [value] : value;
+/** `reveal_audit_entry`'s details, or one of `reveal_audit_entries`'. */
+function detailsOf(value, entryId) {
+	const row = isRecord(value) ? value : {};
+	const json = (key) => {
+		const found = row[key];
+		return isRecord(found) ? { [key]: found } : {};
+	};
+	const text = (key) => {
+		const found = optionalText(row[key]);
+		return found === void 0 ? {} : { [key]: found };
+	};
+	return {
+		entry: textOf(row["entry"] ?? entryId),
+		...json("old"),
+		...json("new"),
+		...json("metadata"),
+		...text("ip"),
+		...text("userAgent"),
+		...text("sessionId"),
+		...row["changes"] === void 0 || row["changes"] === null ? {} : { changes: row["changes"] }
+	};
+}
+/** `audit_event`'s named arguments for one event. */
+function eventArgs(event) {
+	return {
+		event_type: event.eventType,
+		category: event.category,
+		outcome: event.outcome,
+		source: event.source,
+		target_type: event.targetType,
+		record_id: event.record,
+		tenant: event.organizationId,
+		metadata: event.metadata,
+		idempotency_key: event.idempotencyKey,
+		restricted: event.restricted,
+		actor_id: event.actorId,
+		summary: event.summary,
+		target_label: event.targetLabel,
+		correlation_id: event.correlationId,
+		actor_kind: event.actorKind,
+		actor_label: event.actorLabel,
+		ip: event.ip,
+		user_agent: event.userAgent,
+		session_id: event.sessionId,
+		request_id: event.requestId,
+		scope: event.scope,
+		support_session: event.supportSessionId,
+		impersonated_by: event.impersonatedBy,
+		impersonation_reason: event.impersonationReason
+	};
+}
+/**
+* The audit log over the `audit` module's functions, as the caller: the read
+* policy decides what `list` and `export` return, and column mappings of an
+* adopted log are already applied.
+*/
+function createAudit(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	const list = (list = {}) => {
+		const limit = list.limit ?? 50;
+		const filters = {
+			for_tenants: many(list.organizationId),
+			for_event_types: many(list.eventType),
+			for_actors: many(list.actorId),
+			for_target_types: many(list.targetType),
+			for_records: many(list.record),
+			for_categories: many(list.category),
+			for_outcomes: many(list.outcome),
+			for_sources: many(list.source),
+			for_actor_kinds: many(list.actorKind),
+			for_correlation_ids: many(list.correlationId),
+			search: list.search,
+			since: instantArg(list.since),
+			until: instantArg(list.until)
+		};
+		const { cursor } = pageOf(list);
+		const page = call("list_audit_events", {
+			...filters,
+			cursor_at: instantArg(cursor?.occurredAt),
+			cursor_id: cursor?.id,
+			max_items: limit,
+			ascending: list.order === "asc",
+			skip: list.offset
+		}, (value) => {
+			const entries = (Array.isArray(value) ? value : []).map((entry) => recordOfEntry(entry));
+			const last = entries.at(-1);
+			return {
+				entries,
+				next: last === void 0 || entries.length < Math.min(limit, 1e3) ? void 0 : {
+					occurredAt: last.occurredAt,
+					id: last.id
+				}
+			};
+		});
+		if (list.count !== true) return page;
+		return page.andThen((data) => call("count_audit_events", filters, (value) => ({
+			...data,
+			total: Number(value)
+		})));
+	};
+	const revealPage = (entries) => call("reveal_audit_entries", { entries: entries.map((entry) => entry.id) }, (value) => new Map((Array.isArray(value) ? value : []).map((row) => {
+		const details = detailsOf(row, "");
+		return [details.entry, details];
+	})));
+	const exportStream = (exporting = {}) => {
+		const format = exporting.format ?? "ndjson";
+		const product = exporting.product;
+		if (format === "ocsf" && !product) throw new TypeError("createAudit().export: the ocsf format needs product");
+		const encoder = new TextEncoder();
+		let before;
+		const { offset: start, columns, preamble, formatRow, ...filters } = exporting;
+		const csv = {
+			...columns === void 0 ? {} : { columns },
+			...preamble === void 0 ? {} : { preamble },
+			...formatRow === void 0 ? {} : { formatRow }
+		};
+		const reveals = format === "csv" && revealsDetails(columns);
+		let offset = start;
+		let header = format === "csv";
+		let done = false;
+		return new ReadableStream({ async pull(controller) {
+			if (done) return;
+			const page = await list({
+				...filters,
+				...before ? { cursor: before } : {},
+				...offset === void 0 ? {} : { offset },
+				limit: exporting.batch ?? 500
+			});
+			offset = void 0;
+			if (!page.ok) {
+				done = true;
+				controller.error(new Error(page.error.message));
+				return;
+			}
+			const { entries, next } = page.data;
+			let text = "";
+			if (format === "csv") {
+				let details;
+				if (reveals && entries.length > 0) {
+					const revealed = await revealPage(entries);
+					if (!revealed.ok) {
+						done = true;
+						controller.error(new Error(revealed.error.message));
+						return;
+					}
+					details = revealed.data;
+				}
+				text = csvPage(entries, csv, details, header);
+				header = false;
+			} else if (entries.length > 0) text = `${entries.map((entry) => JSON.stringify(format === "ocsf" && product ? toOcsf(entryOf(entry), product) : entry)).join("\n")}\n`;
+			if (text.length > 0) controller.enqueue(encoder.encode(text));
+			before = next;
+			if (next === void 0) {
+				done = true;
+				controller.close();
+			}
+		} });
+	};
+	const record = (event) => call("audit_event", eventArgs(event), textOf);
+	const recordMany = (events) => events.length === 0 ? AsyncResult.ok([]) : call("audit_event_many", { events: events.map(eventArgs) }, (value) => batchResultsOf(value, events.length, "id", textOf, options.mappers));
+	return withBlockHooks({
+		record,
+		recordMany,
+		sink: (sinkOptions) => auditSink(recordMany, sinkOptions),
+		list,
+		reveal: (entryId) => call("reveal_audit_entry", { entry: entryId }, (value) => detailsOf(value, entryId)),
+		revert: (entryIds) => call("revert_audit_entries", { entries: [...entryIds] }, revertedOf),
+		export: exportStream,
+		exportToStorage: (target) => AsyncResult.from(async () => {
+			const contentType = (target.format ?? "ndjson") === "csv" ? "text/csv" : "application/x-ndjson";
+			let body;
+			try {
+				body = new Blob([await new Response(exportStream(target)).arrayBuffer()], { type: contentType });
+			} catch (cause) {
+				return err(dbError("raised", cause instanceof Error ? cause.message : String(cause), { hint: "AUDIT_EXPORT_FAILED" }));
+			}
+			const bucket = target.storage.from(target.bucket);
+			if ((await bucket.upload(target.path, body, {
+				contentType,
+				upsert: true
+			})).error) return err(dbError("raised", "The export could not be stored", { hint: "AUDIT_EXPORT_FAILED" }));
+			let url;
+			if (target.signedUrlTtl !== void 0 && bucket.createSignedUrl) url = (await bucket.createSignedUrl(target.path, target.signedUrlTtl, { download: true })).data?.signedUrl;
+			return ok({
+				path: target.path,
+				url
+			});
+		})
+	}, options.hooks, {
+		block: "audit",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+//#endregion
+//#region src/blocks/audit/client.ts
+function listOptions(organizationId, filters, limit, cursor) {
+	const { actorId, eventType, search } = filters;
+	return {
+		organizationId,
+		order: "desc",
+		...actorId ? { actorId } : {},
+		...eventType ? { eventType } : {},
+		...search?.trim() ? { search: search.trim() } : {},
+		...limit === void 0 ? {} : { limit },
+		...cursor === void 0 ? {} : { cursor }
+	};
+}
+/**
+* One organization's audit trail for an audit table: the newest page as the
+* caller may read it, `setFilters` to narrow it by actor, action or text, and
+* `loadMore` for older pages.
+*/
+function createAuditLogController(options) {
+	const { client, organizationId, limit } = options;
+	return defineController({
+		entries: void 0,
+		filters: options.filters ?? {},
+		loading: false,
+		hasMore: false,
+		error: void 0
+	}, (state) => {
+		let ticket = 0;
+		let next;
+		const load = async (more) => {
+			if (organizationId === null) return;
+			if (more && next === void 0) return;
+			ticket += 1;
+			const request = ticket;
+			state.set({ loading: true });
+			const result = await client.list(listOptions(organizationId, state.get().filters, limit, more ? next : void 0));
+			if (request !== ticket) return;
+			if (!result.ok) {
+				state.set({
+					loading: false,
+					error: result.error
+				});
+				return;
+			}
+			next = result.data.next;
+			state.set((current) => ({
+				loading: false,
+				error: void 0,
+				hasMore: next !== void 0,
+				entries: more ? [...current.entries ?? [], ...result.data.entries] : result.data.entries
+			}));
+		};
+		const refresh = () => load(false);
+		return {
+			actions: {
+				refresh,
+				loadMore: () => load(true),
+				setFilters: (filters) => {
+					next = void 0;
+					state.set({
+						filters,
+						entries: void 0,
+						hasMore: false
+					});
+					return refresh();
+				}
+			},
+			start: () => organizationId === null ? void 0 : whileSignedIn(options.auth, () => {
+				refresh();
+			})
+		};
+	});
+}
+//#endregion
 //#region src/blocks/audit/events.ts
 /** The `audit` block's event types, for its manifest and `onBlockEvent`. */
 const auditEvents = defineEvents({ "audit.revealed": event() });