@coffre/db 0.0.0-stage → 0.1.0

package/dist/log.d.ts

@@ -0,0 +1,72 @@
+import { i as Transaction } from "./database-CWpo5aF0.js";
+import { LogKey } from "@coffre/core/audit";
+//#region src/log.d.ts
+/**
+ * Appending to the audit log, the one table both the app and the vault
+ * write, each under its own key (@coffre/core/audit says what an entry's MAC
+ * and hash cover).
+ *
+ * Every append locks the log's head first, `audit_chain_head`, so entries
+ * from any process take their numbers in one order. It then reads the
+ * database clock, after the lock, and the log's last entry, which the head
+ * must name: a head that does not was moved, or entries were deleted behind
+ * it, and the append refuses.
+ *
+ * This is deliberately not a queue and not best-effort: the entries go in
+ * the caller's transaction, so if the append fails, what it records does
+ * not happen either.
+ */
+/** An entry to append: what it says. The append numbers, dates, signs and chains it. */
+export type NewEntry = {
+  actor: string;
+  action: string;
+  decision: 'allow' | 'deny';
+  code?: string | null;
+  subjectPrincipal?: string | null;
+  projectId?: string | null;
+  environmentId?: string | null;
+  secretId?: string | null;
+  secretVersionId?: string | null;
+  operationId?: string | null;
+  requestId?: string | null;
+  sourceIp?: string | null;
+  relatedSeq?: bigint | null;
+  /** JSON text. */
+  metadata?: string;
+};
+export type Appended = {
+  /** The first entry's number, and the next number after the last. */
+  seqStart: bigint;
+  nextSeq: bigint;
+  headHash: Buffer;
+  /** Milliseconds since the epoch, the database's, shared by the batch. */
+  occurredAt: number;
+};
+/** The log's head does not name its last entry: something moved it, or cut the log behind it. */
+export declare class LogHeadMismatch extends Error {
+  constructor(message: string);
+}
+/**
+ * The log's head is behind one this process wrote: the database was rolled
+ * back, or entries were cut off its end. That cannot be told from a restore,
+ * so the append refuses and someone has to look.
+ */
+export declare class LogRewound extends Error {
+  constructor(message: string);
+}
+/**
+ * Forget every head written so far. For tests that empty the database
+ * between cases, which is exactly what the check above refuses.
+ */
+export declare function forgetLogHeads(): void;
+/**
+ * Lock the log's head, and read it. A transaction that appends takes this
+ * before any other row, so the lock order is the same everywhere; taking it
+ * again in the same transaction is free.
+ */
+export declare function lockLogHead(tx: Transaction): Promise<{
+  nextSeq: bigint;
+  headHash: Buffer;
+}>;
+export declare function appendEntries(tx: Transaction, key: LogKey, entries: readonly NewEntry[]): Promise<Appended>;
+//#endregion

package/dist/log.js

@@ -0,0 +1,133 @@
+import { t as afterCommit } from "./commits-BuW-NL3n.js";
+import { tablesOf } from "./index.js";
+import { clockMillis, forUpdate } from "./dialect.js";
+import { desc, eq } from "drizzle-orm";
+import { GENESIS_HASH, sealEntry } from "@coffre/core/audit";
+//#region src/log.ts
+/** The log's head does not name its last entry: something moved it, or cut the log behind it. */
+var LogHeadMismatch = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "LogHeadMismatch";
+	}
+};
+/**
+* The log's head is behind one this process wrote: the database was rolled
+* back, or entries were cut off its end. That cannot be told from a restore,
+* so the append refuses and someone has to look.
+*/
+var LogRewound = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "LogRewound";
+	}
+};
+/**
+* The newest head each writer has written, under each of its keys, while
+* the process lives. A head is remembered only once the transaction that
+* wrote it has committed, all the way out (commits.ts): one that rolls back
+* never puts it ahead of the database, and the last batch committed is
+* covered too. When commits race, the furthest head stays.
+*/
+const remembered = /* @__PURE__ */ new WeakMap();
+let epoch = 0;
+function remember(key, head) {
+	const before = remembered.get(key);
+	if (before !== void 0 && before.epoch === epoch && before.nextSeq >= head.nextSeq) return;
+	remembered.set(key, {
+		epoch,
+		...head
+	});
+}
+/**
+* Forget every head written so far. For tests that empty the database
+* between cases, which is exactly what the check above refuses.
+*/
+function forgetLogHeads() {
+	epoch += 1;
+}
+/**
+* Lock the log's head, and read it. A transaction that appends takes this
+* before any other row, so the lock order is the same everywhere; taking it
+* again in the same transaction is free.
+*/
+async function lockLogHead(tx) {
+	const { auditChainHead } = tablesOf(tx);
+	const [head] = await forUpdate(tx, tx.select({
+		nextSeq: auditChainHead.nextSeq,
+		headHash: auditChainHead.headHash
+	}).from(auditChainHead).where(eq(auditChainHead.onlyRow, true)));
+	if (head === void 0) throw new Error("audit_chain_head is missing; refusing to write an unchained entry");
+	return head;
+}
+async function appendEntries(tx, key, entries) {
+	if (entries.length === 0) throw new Error("appendEntries called with no entries");
+	const { auditChainHead, auditLog } = tablesOf(tx);
+	const head = await lockLogHead(tx);
+	const [{ now }] = await tx.select({ now: clockMillis(tx) }).from(auditChainHead);
+	const [last] = await tx.select({
+		seq: auditLog.seq,
+		hash: auditLog.hash
+	}).from(auditLog).orderBy(desc(auditLog.seq)).limit(1);
+	const expected = last === void 0 ? {
+		nextSeq: 0n,
+		headHash: GENESIS_HASH
+	} : {
+		nextSeq: last.seq + 1n,
+		headHash: last.hash
+	};
+	if (head.nextSeq !== expected.nextSeq || !head.headHash.equals(expected.headHash)) throw new LogHeadMismatch(`the log's head says entry ${head.nextSeq} comes next, but the log ends ${last === void 0 ? "empty" : `at entry ${last.seq}`}, or with another hash`);
+	const before = remembered.get(key);
+	if (before !== void 0 && before.epoch === epoch && (head.nextSeq < before.nextSeq || head.nextSeq === before.nextSeq && !head.headHash.equals(before.headHash))) throw new LogRewound(`the log ends before entry ${before.nextSeq}, which this process wrote: it was rolled back`);
+	let seq = head.nextSeq;
+	let prevHash = head.headHash;
+	const rows = [];
+	for (const entry of entries) {
+		const fields = {
+			seq,
+			author: key.author,
+			keyId: key.keyId,
+			occurredAt: now,
+			actor: entry.actor,
+			action: entry.action,
+			decision: entry.decision,
+			code: entry.code ?? null,
+			subjectPrincipal: entry.subjectPrincipal ?? null,
+			projectId: entry.projectId ?? null,
+			environmentId: entry.environmentId ?? null,
+			secretId: entry.secretId ?? null,
+			secretVersionId: entry.secretVersionId ?? null,
+			operationId: entry.operationId ?? null,
+			requestId: entry.requestId ?? null,
+			sourceIp: entry.sourceIp ?? null,
+			relatedSeq: entry.relatedSeq ?? null,
+			metadata: entry.metadata ?? "{}"
+		};
+		const { mac, hash } = sealEntry(key, prevHash, fields);
+		rows.push({
+			...fields,
+			prevHash,
+			mac,
+			hash
+		});
+		prevHash = hash;
+		seq += 1n;
+	}
+	await tx.insert(auditLog).values(rows);
+	await tx.update(auditChainHead).set({
+		nextSeq: seq,
+		headHash: prevHash
+	}).where(eq(auditChainHead.onlyRow, true));
+	const written = {
+		nextSeq: seq,
+		headHash: prevHash
+	};
+	afterCommit(tx, () => remember(key, written));
+	return {
+		seqStart: head.nextSeq,
+		...written,
+		occurredAt: now
+	};
+}
+//#endregion
+export { LogHeadMismatch, LogRewound, appendEntries, forgetLogHeads, lockLogHead };

package/dist/migrate.d.ts

@@ -0,0 +1,10 @@
+import { Engine } from "./dialect.js";
+//#region src/migrate.d.ts
+/**
+ * Beside this module: src/migrations in the workspace, and dist/migrations
+ * in the built package, where the build copies them.
+ */
+export declare function migrationsFolder(engine: Engine): string;
+/** Apply missing migrations, check their history and reassert database privileges. */
+export declare function migrateDatabase(url: string): Promise<void>;
+//#endregion

package/dist/migrate.js

@@ -0,0 +1,129 @@
+import { engineOfUrl } from "./connect.js";
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+//#region src/migrate.ts
+/**
+* Bring a database up to date with its engine's migration tree:
+* migrations/postgres or migrations/sqlite. Both trees
+* describe one schema; see schema-parity.test.ts.
+*
+* Applied history must be a prefix of the local journal, byte for byte,
+* before and after. Only one migrator runs at a time: Postgres takes an
+* advisory lock, and SQLite's own write lock covers the
+* whole run. Restricted runtime roles are Postgres-only (baseline/postgres.sql).
+*/
+const MIGRATION_LOCK_KEY = "7165058122361679213";
+/**
+* Beside this module: src/migrations in the workspace, and dist/migrations
+* in the built package, where the build copies them.
+*/
+function migrationsFolder(engine) {
+	return fileURLToPath(new URL(`./migrations/${engine}`, import.meta.url));
+}
+async function expectedMigrations(engine) {
+	const folder = migrationsFolder(engine);
+	const journal = JSON.parse(await readFile(`${folder}/meta/_journal.json`, "utf8"));
+	if (!Array.isArray(journal.entries)) throw new Error("invalid Drizzle migration journal");
+	const expected = await Promise.all(journal.entries.map(async (entry, position) => {
+		if (entry.idx !== position || !Number.isSafeInteger(entry.when) || typeof entry.tag !== "string" || !/^[a-zA-Z0-9_-]+$/.test(entry.tag)) throw new Error(`invalid Drizzle migration journal entry at index ${position}`);
+		const sqlText = await readFile(`${folder}/${entry.tag}.sql`, "utf8");
+		return {
+			createdAt: String(entry.when),
+			hash: createHash("sha256").update(sqlText).digest("hex"),
+			tag: entry.tag
+		};
+	}));
+	for (let index = 1; index < expected.length; index += 1) if (BigInt(expected[index - 1].createdAt) >= BigInt(expected[index].createdAt)) throw new Error("Drizzle migration journal timestamps must be strictly increasing");
+	return expected;
+}
+function verifyHistory(expected, applied, requireComplete) {
+	const rows = applied ?? [];
+	if (rows.length > expected.length) throw new Error("database contains migrations that are absent from this image");
+	if (requireComplete && rows.length !== expected.length) throw new Error(`migration history is incomplete: expected ${expected.length}, found ${rows.length}`);
+	rows.forEach((row, index) => {
+		const local = expected[index];
+		if (row.created_at !== local.createdAt || row.hash !== local.hash) throw new Error(`migration history diverged at ${local.tag}; applied migrations must never be edited`);
+	});
+}
+async function postgresMigrator(url) {
+	const [{ default: pg }, { drizzle }, { migrate }] = await Promise.all([
+		import("pg"),
+		import("drizzle-orm/node-postgres"),
+		import("drizzle-orm/node-postgres/migrator")
+	]);
+	const pool = new pg.Pool({
+		application_name: "coffre-migrations",
+		connectionString: url,
+		max: 1
+	});
+	const client = await pool.connect();
+	return {
+		async applied() {
+			if (!(await client.query("SELECT to_regclass('drizzle.__drizzle_migrations')::text AS relation")).rows[0]?.relation) return null;
+			return (await client.query("SELECT hash, created_at::text FROM drizzle.__drizzle_migrations ORDER BY created_at, id")).rows;
+		},
+		async lock() {
+			await client.query("SET lock_timeout = '5min'");
+			await client.query("SELECT pg_advisory_lock($1::bigint)", [MIGRATION_LOCK_KEY]);
+		},
+		async unlock() {
+			await client.query("SELECT pg_advisory_unlock($1::bigint)", [MIGRATION_LOCK_KEY]);
+		},
+		migrate: (migrationsFolder) => migrate(drizzle(client), { migrationsFolder }),
+		async restrict() {
+			await client.query(`DO $$ BEGIN
+        EXECUTE format(
+          'REVOKE CREATE, TEMPORARY ON DATABASE %I FROM PUBLIC, coffre_app, coffre_runtime, coffre_vault, coffre_vault_runtime',
+          current_database()
+        );
+      END $$`);
+		},
+		async close() {
+			client.release();
+			await pool.end();
+		}
+	};
+}
+async function sqliteMigrator(url) {
+	const [{ openDatabase }, { migrate }] = await Promise.all([import("./connect.js"), import("drizzle-orm/libsql/migrator")]);
+	const { db, close } = await openDatabase(url);
+	const sqlite = db;
+	return {
+		async applied() {
+			if ((await sqlite.all("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = '__drizzle_migrations'")).length === 0) return null;
+			return sqlite.all("SELECT hash, CAST(created_at AS TEXT) AS created_at FROM __drizzle_migrations ORDER BY created_at, id");
+		},
+		async lock() {},
+		async unlock() {},
+		migrate: (migrationsFolder) => migrate(sqlite, { migrationsFolder }),
+		async restrict() {},
+		close
+	};
+}
+/** Apply missing migrations, check their history and reassert database privileges. */
+async function migrateDatabase(url) {
+	const engine = engineOfUrl(url);
+	const expected = await expectedMigrations(engine);
+	const migrator = await {
+		postgres: postgresMigrator,
+		sqlite: sqliteMigrator
+	}[engine](url);
+	let locked = false;
+	try {
+		await migrator.lock();
+		locked = true;
+		verifyHistory(expected, await migrator.applied(), false);
+		await migrator.migrate(migrationsFolder(engine));
+		verifyHistory(expected, await migrator.applied(), true);
+		await migrator.restrict();
+	} finally {
+		try {
+			if (locked) await migrator.unlock();
+		} finally {
+			await migrator.close();
+		}
+	}
+}
+//#endregion
+export { migrateDatabase, migrationsFolder };