@coffre/cli 0.1.0 → 0.1.2

package/dist/setup-DPHVyr2N.js

@@ -0,0 +1,521 @@
+import { d as esm_default } from "./esm-Bts-esAl.js";
+import { n as generateKeys, t as KEYS_EXPLAINED } from "./keys-D9CG_wYV.js";
+import { r as postgresConnection, t as engineOfUrl } from "./connect-BONR52al.js";
+import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { createHash, createHmac, pbkdf2Sync, randomBytes } from "node:crypto";
+import { createInterface } from "node:readline/promises";
+import { Writable } from "node:stream";
+import { readFile } from "node:fs/promises";
+//#region ../db/dist/migrate.js
+/**
+* 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("./esm-B69mMLcR.js"),
+		import("./node-postgres-BlNvYfq_.js"),
+		import("./migrator-W1a-ooWi.js")
+	]);
+	const pool = new pg.Pool({
+		...postgresConnection(url),
+		application_name: "coffre-migrations",
+		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-BZdPYNbZ.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
+//#region src/setup.ts
+/** Where the administrator's connection string comes from, when not from a hidden prompt. */
+const URL_VARIABLE = "COFFRE_SETUP_DATABASE_URL";
+/** The two runtime roles, as the migration names them, and the Hyperdrive config each gets on Workers. */
+const ROLES = {
+	app: "coffre_runtime",
+	vault: "coffre_vault_runtime"
+};
+const HYPERDRIVE = {
+	app: "coffre",
+	vault: "coffre-vault"
+};
+var SetupError = class extends Error {};
+/**
+* The name a role logs in as. On PlanetScale Postgres, a login names its
+* branch: the administrator connects as `postgres.<branch id>`, and every
+* role on that branch as `<role>.<branch id>`. Elsewhere, the role's name.
+*/
+function loginFor(role, administrator) {
+	const dot = administrator.indexOf(".");
+	return dot === -1 ? role : `${role}${administrator.slice(dot)}`;
+}
+/** The administrator's URL, as `login` with `password`: same host, database and TLS settings. */
+function loginUrl(administrator, login, password) {
+	const url = new URL(administrator.href);
+	url.username = encodeURIComponent(login);
+	url.password = password;
+	return url.href;
+}
+/**
+* A login's URL for Hyperdrive, without its parameters: Hyperdrive always
+* connects over TLS, checking the certificate against public CAs, and takes
+* no `sslrootcert`.
+*/
+function hyperdriveUrl(url) {
+	const bare = new URL(url);
+	bare.search = "";
+	bare.hash = "";
+	return bare.href;
+}
+/**
+* What Postgres keeps for a password under SCRAM-SHA-256 (RFC 5802 and
+* 7677), made here, so that the password itself never reaches the server,
+* nor its logs.
+*/
+function scramVerifier(password, salt = randomBytes(16), iterations = 4096) {
+	const salted = pbkdf2Sync(password, salt, iterations, 32, "sha256");
+	const stored = createHash("sha256").update(createHmac("sha256", salted).update("Client Key").digest()).digest();
+	const server = createHmac("sha256", salted).update("Server Key").digest();
+	return `SCRAM-SHA-256$${iterations}:${salt.toString("base64")}$${stored.toString("base64")}:${server.toString("base64")}`;
+}
+/** 24 random bytes, URL-safe: nothing to encode in a connection string. */
+function newPassword() {
+	return randomBytes(24).toString("base64url");
+}
+async function setup(args) {
+	const secrets = [];
+	try {
+		const options = parseOptions(args);
+		const { text, interactive } = await readAdministrator();
+		secrets.push(text);
+		const administrator = administratorUrl(text);
+		if (administrator.password !== "") secrets.push(administrator.password, decodeURIComponent(administrator.password));
+		const result = await run(administrator, {
+			...options,
+			interactive
+		}, secrets);
+		process.stdout.write(options.json ? `${JSON.stringify(asJson(result))}\n` : formatSetup(result));
+	} catch (error) {
+		process.stderr.write(`coffre setup: ${redact(error instanceof Error ? error.message : String(error), secrets)}\n`);
+		process.exit(1);
+	}
+}
+function parseOptions(args) {
+	try {
+		const { values } = parseArgs({
+			args,
+			options: {
+				"reset-passwords": {
+					type: "boolean",
+					default: false
+				},
+				json: {
+					type: "boolean",
+					default: false
+				}
+			},
+			allowPositionals: false,
+			strict: true
+		});
+		return {
+			resetPasswords: values["reset-passwords"],
+			json: values.json
+		};
+	} catch {
+		const leaked = args.some((arg) => /postgres(ql)?:|@/i.test(arg));
+		throw new SetupError(`it takes only --reset-passwords and --json. It reads the administrator's connection string from a hidden prompt, ${URL_VARIABLE} or stdin, never from the command line, where the shell's history and other users can read it.` + (leaked ? " One of the arguments looks like one: change that password, which is in your shell history now." : ""));
+	}
+}
+/** The connection string: from the environment, from stdin when it is not a terminal, or typed at a hidden prompt. */
+async function readAdministrator() {
+	const terminal = process.stdin.isTTY === true;
+	const given = process.env[URL_VARIABLE];
+	delete process.env[URL_VARIABLE];
+	if (given !== void 0 && given.trim() !== "") return {
+		text: given.trim(),
+		interactive: terminal
+	};
+	if (!terminal) {
+		const line = readFileSync(0, "utf8").split("\n").find((candidate) => candidate.trim() !== "");
+		if (line === void 0) throw new SetupError(`no connection string: pipe it to stdin, or set ${URL_VARIABLE}`);
+		return {
+			text: line.trim(),
+			interactive: false
+		};
+	}
+	const text = await hidden("The database administrator's connection string (hidden): ");
+	if (text === "") throw new SetupError("no connection string given");
+	return {
+		text,
+		interactive: true
+	};
+}
+function administratorUrl(text) {
+	let url;
+	try {
+		url = new URL(text);
+	} catch {
+		throw new SetupError("that is not a connection string, such as postgresql://user:password@host:5432/database");
+	}
+	if (url.protocol !== "postgres:" && url.protocol !== "postgresql:") throw new SetupError("coffre setup needs a Postgres connection string, postgresql://…");
+	if (url.username === "" || url.hostname === "" || url.pathname.length <= 1) throw new SetupError("the connection string must name a user, a host and a database");
+	return url;
+}
+async function run(administrator, options, secrets) {
+	const user = decodeURIComponent(administrator.username);
+	const logins = await provision(administrator, user, options, secrets);
+	const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+	note(`migrating the database to coffre ${version}'s schema, as ${user}`);
+	await migrateDatabase(administrator.href);
+	note("checking the boundary, as each login");
+	return {
+		keys: !await withClient(administrator.href, async (client) => {
+			for (const component of ["app", "vault"]) {
+				const login = logins[component];
+				check(component, login, login.url === null ? await granted(client, login.role) : await probed(login.url));
+			}
+			return (await client.query("SELECT EXISTS (SELECT 1 FROM audit_log) AS used")).rows[0].used;
+		}) && (logins.app.url !== null || logins.vault.url !== null) ? generateKeys() : null,
+		...logins
+	};
+}
+/**
+* Each runtime login, created with a fresh password, or, if it exists, its
+* password set again when asked to; otherwise left as it is.
+*/
+async function provision(administrator, user, options, secrets) {
+	return withClient(administrator.href, async (client) => {
+		const [self] = (await client.query("SELECT rolsuper, rolcreaterole FROM pg_roles WHERE rolname = current_user")).rows;
+		if (!self?.rolsuper && !self?.rolcreaterole) throw new SetupError(`${user} cannot create roles: connect as the database's administrator, which has CREATEROLE`);
+		const existing = new Set((await client.query("SELECT rolname FROM pg_roles WHERE rolname = ANY($1)", [Object.values(ROLES)])).rows.map((row) => row.rolname));
+		let reset = options.resetPasswords;
+		if (existing.size > 0 && !reset) {
+			const [names, one] = [[...existing].join(" and "), existing.size === 1];
+			if (options.interactive) {
+				note(`${names} ${one ? "exists" : "exist"} already`);
+				reset = await confirm("Set new passwords? Each component then needs its new connection string [y/N] ");
+			} else note(`${names} ${one ? "exists" : "exist"} already, and ${one ? "keeps its password" : "keep their passwords"}: --reset-passwords sets new ones`);
+		}
+		const logins = {};
+		for (const component of ["app", "vault"]) {
+			const role = ROLES[component];
+			const login = loginFor(role, user);
+			const create = !existing.has(role);
+			if (!create && !reset) {
+				logins[component] = {
+					role,
+					login,
+					password: "kept",
+					url: null
+				};
+				continue;
+			}
+			const password = newPassword();
+			secrets.push(password);
+			const verifier = client.escapeLiteral(scramVerifier(password));
+			await client.query(create ? `CREATE ROLE ${client.escapeIdentifier(role)} LOGIN INHERIT NOCREATEDB NOCREATEROLE PASSWORD ${verifier}` : `ALTER ROLE ${client.escapeIdentifier(role)} LOGIN PASSWORD ${verifier}`);
+			note(`${create ? "created" : "set a new password for"} ${role}${login === role ? "" : `, which logs in as ${login}`}`);
+			logins[component] = {
+				role,
+				login,
+				password: create ? "created" : "reset",
+				url: loginUrl(administrator, login, password)
+			};
+		}
+		return logins;
+	});
+}
+/** What each login may do that matters, and what it must answer. */
+const BOUNDARY = [
+	{
+		what: "write members",
+		expected: {
+			app: false,
+			vault: true
+		},
+		sql: `INSERT INTO vault_members (principal, status, owner, generation, created_at, created_by, status_changed_at, status_changed_by, access_seq, mac)
+          VALUES ('user:coffre-setup@probe.invalid', 'active', false, 0, 0, 'system:coffre-setup', 0, 'system:coffre-setup', 0, decode(repeat('00', 32), 'hex'))`,
+		privilege: "has_table_privilege($1, 'public.vault_members', 'INSERT')"
+	},
+	{
+		what: "delete log entries",
+		expected: {
+			app: false,
+			vault: false
+		},
+		sql: "DELETE FROM audit_log",
+		privilege: "has_table_privilege($1, 'public.audit_log', 'DELETE')"
+	},
+	{
+		what: "create tables",
+		expected: {
+			app: false,
+			vault: false
+		},
+		sql: "CREATE TABLE coffre_setup_probe (probe integer)",
+		privilege: "has_schema_privilege($1, 'public', 'CREATE') OR has_database_privilege($1, current_database(), 'CREATE')"
+	}
+];
+/** Each probe, tried as the login in a transaction rolled back: allowed, or refused for want of a privilege. */
+async function probed(url) {
+	return withClient(url, async (client) => {
+		const allowed = [];
+		for (const { sql } of BOUNDARY) {
+			await client.query("BEGIN");
+			try {
+				await client.query(sql);
+				allowed.push(true);
+			} catch (error) {
+				if (error.code !== "42501") throw error;
+				allowed.push(false);
+			} finally {
+				await client.query("ROLLBACK");
+			}
+		}
+		return allowed;
+	});
+}
+/** The same, from the catalog, for a login whose password this run did not set: the administrator asks for it. */
+async function granted(client, role) {
+	const allowed = [];
+	for (const { privilege } of BOUNDARY) allowed.push((await client.query(`SELECT ${privilege} AS allowed`, [role])).rows[0].allowed);
+	return allowed;
+}
+function check(component, login, allowed) {
+	const wrong = BOUNDARY.flatMap(({ what, expected }, i) => allowed[i] === expected[component] ? [] : [`${allowed[i] ? "can" : "cannot"} ${what}`]);
+	if (wrong.length > 0) throw new SetupError(`${login.role} ${wrong.join(", and ")}: the database's privileges are not what coffre needs. Nothing is shown: fix them, then run coffre setup again with --reset-passwords.`);
+	const can = BOUNDARY.filter(({ expected }) => expected[component]).map(({ what }) => what);
+	const cannot = BOUNDARY.filter(({ expected }) => !expected[component]).map(({ what }) => what);
+	const how = login.url === null ? ", by the catalog: its password is unchanged" : "";
+	note(`  ${login.role.padEnd(20)} ${can.length > 0 ? `can ${listed(can, "and")}; ` : ""}cannot ${listed(cannot, "or")}${how}`);
+}
+/**
+* Every value, once, as a dotenv block for each component, then, as
+* comments, where each goes: Node's env files, or Workers' Hyperdrive
+* configs, vars and secrets.
+*/
+function formatSetup({ keys, app, vault }) {
+	const lines = [];
+	const say = (...text) => lines.push(...text);
+	if (keys === null && app.url === null && vault.url === null) return `# Nothing to save. The logins kept their passwords, and this database
+# holds a deployment's data already, whose keys are the ones it was set up
+# with. For new passwords: coffre setup --reset-passwords.
+`;
+	say("# SAVE THESE NOW, in your password manager. They are shown once: coffre", "# keeps no copy, and the database holds only the passwords' verifiers.");
+	if (keys === null) say("#", "# No keys: this database holds a deployment's data already, whose keys", "# are the ones it was set up with.");
+	const url = (login) => login.url === null ? `# DATABASE_URL: ${login.role} kept its password; coffre setup --reset-passwords sets a new one.` : `DATABASE_URL=${login.url}`;
+	say("", "# The app: server.env on Node; Worker secrets and Hyperdrive on Workers.");
+	if (keys !== null) say(`AUDIT_CHAIN_KEY=${keys.AUDIT_CHAIN_KEY}`);
+	say(url(app), "", "# The vault: vault.env on Node; a var, a secret and Hyperdrive on Workers.");
+	if (keys !== null) say(`KEK_ID=${keys.KEK_ID}`, `KEK=${keys.KEK}`);
+	say(url(vault), "");
+	say("# On Node, the app's block goes in server.env and the vault's in vault.env,", "# beside the settings their .example files list, each readable only by", "# its process's user (chmod 600).");
+	const set = [app, vault].filter((login) => login.url !== null);
+	if (set.length > 0) {
+		say("#", "# On Workers, from the deployment's directory: each login reaches the", "# database through a Hyperdrive config of its own, with caching off, so", "# that a revoked session or grant stops at once. Hyperdrive always", "# connects over TLS, checking the certificate against public CAs, so", "# these URLs leave the parameters out:", "#");
+		for (const [component, login] of [["app", app], ["vault", vault]]) {
+			if (login.url === null) continue;
+			say(`#   pnpm exec wrangler hyperdrive ${login.password === "created" ? `create ${HYPERDRIVE[component]} --caching-disabled` : `update <the ${component}'s config id>`} \\`, `#     --connection-string='${hyperdriveUrl(login.url)}'`);
+		}
+	}
+	const places = [...set.some((login) => login.password === "created") ? ["the ids they print under hyperdrive, in app/wrangler.jsonc and vault/wrangler.jsonc"] : [], ...keys === null ? [] : ["KEK_ID under vars in vault/wrangler.jsonc"]];
+	if (places.length > 0) say("#", ...comment(`Put ${places.join(", and ")}.${keys === null ? "" : " Then set the two secrets, each pasted at its prompt:"}`));
+	if (keys !== null) say("#", "#   pnpm exec wrangler secret put AUDIT_CHAIN_KEY -c app/wrangler.jsonc", "#   pnpm exec wrangler secret put KEK -c vault/wrangler.jsonc", "#", KEYS_EXPLAINED.trimEnd());
+	say("#", "# The database is migrated, and each login holds only its rights. Run", "# `pnpm migrate` in the deployment after every upgrade of coffre.");
+	return `${lines.join("\n")}\n`;
+}
+/** `text` as comment lines of at most 76 columns. */
+function comment(text) {
+	const lines = [];
+	let line = "#";
+	for (const word of text.split(" ")) {
+		if (line.length + 1 + word.length > 76) {
+			lines.push(line);
+			line = "#";
+		}
+		line += ` ${word}`;
+	}
+	return [...lines, line];
+}
+/** "a, b or c". */
+function listed(items, last) {
+	return items.length < 2 ? items.join("") : `${items.slice(0, -1).join(", ")} ${last} ${items.at(-1)}`;
+}
+/** The same values, for a script: each component's, and what happened to each login. */
+function asJson({ keys, app, vault }) {
+	const database = (login) => login.url === null ? {} : { DATABASE_URL: login.url };
+	return {
+		app: {
+			...keys === null ? {} : { AUDIT_CHAIN_KEY: keys.AUDIT_CHAIN_KEY },
+			...database(app)
+		},
+		vault: {
+			...keys === null ? {} : {
+				KEK_ID: keys.KEK_ID,
+				KEK: keys.KEK
+			},
+			...database(vault)
+		},
+		logins: Object.fromEntries([app, vault].map(({ role, login, password }) => [role, {
+			login,
+			password
+		}]))
+	};
+}
+async function withClient(url, use) {
+	const client = new esm_default.Client({
+		...postgresConnection(url),
+		application_name: "coffre-setup"
+	});
+	await client.connect();
+	try {
+		return await use(client);
+	} finally {
+		await client.end();
+	}
+}
+/** Progress, on stderr: stdout holds only what to save. */
+function note(text) {
+	process.stderr.write(`${text}\n`);
+}
+/** An error's text without any secret in it: a driver may quote what it was given. */
+function redact(text, secrets) {
+	return secrets.filter((secret) => secret.length >= 4).reduce((out, secret) => out.split(secret).join("…"), text);
+}
+async function hidden(question) {
+	const muted = new Writable({ write: (_chunk, _encoding, done) => done() });
+	const prompt = createInterface({
+		input: process.stdin,
+		output: muted,
+		terminal: true
+	});
+	prompt.on("SIGINT", () => {
+		process.stderr.write("\n");
+		process.exit(130);
+	});
+	process.stderr.write(question);
+	try {
+		return (await prompt.question("")).trim();
+	} finally {
+		prompt.close();
+		process.stderr.write("\n");
+	}
+}
+async function confirm(question) {
+	const prompt = createInterface({
+		input: process.stdin,
+		output: process.stderr
+	});
+	try {
+		return /^y(es)?$/i.test((await prompt.question(question)).trim());
+	} finally {
+		prompt.close();
+	}
+}
+//#endregion
+export { setup };

package/dist/templates/node/README.md

@@ -19,48 +19,53 @@ from this directory, on Node 24 or later.
 pnpm install
 cp server.env.example server.env
 cp vault.env.example vault.env
+chmod 600 server.env vault.env
 ```
 
-Fill both in: `PUBLIC_URL`, a GitHub OAuth app whose callback is
-`<PUBLIC_URL>/auth/callback/github`, `ROOT_ADMINS`, and three keys from
-`openssl rand -base64 32`. Escrow `KEK` and its `KEK_ID`, `SIGNING_KEY`, `AUDIT_CHAIN_KEY` and the OAuth
-client secret in a password manager. Without the KEK, stored values cannot
-be read; without the other keys, the existing log cannot be verified.
-
-## 2. The database
-
-Use one Postgres database with three logins: its owner for migrations,
-`coffre_runtime` for the server, and `coffre_vault_runtime` for the vault.
-As an administrator, connect to the database with `psql` and create the
-runtime logins. `\password` prompts for each password without putting it
-in a SQL statement or shell history:
-
-```sql
-CREATE ROLE coffre_runtime LOGIN INHERIT NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS;
-CREATE ROLE coffre_vault_runtime LOGIN INHERIT NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS;
-\password coffre_runtime
-\password coffre_vault_runtime
-```
+Fill in `PUBLIC_URL`, a GitHub OAuth app whose callback is
+`<PUBLIC_URL>/auth/callback/github`, and `ROOT_ADMINS`. Keep each env file
+readable only by its process's user.
+
+## 2. The database and keys
 
-Migrate as the owner, who must also be able to create and grant roles:
+Make a Postgres database, then:
 
 ```sh
-pnpm migrate "postgres://owner:…@db.example.com:5432/coffre"
+npx @coffre/cli setup
 ```
 
-The migration creates the `coffre_app` and `coffre_vault` group roles and
-grants each login only its group's rights. Only the vault writes members
-and grants; each login appends to the audit log only as itself. Run the
-migration again after every package upgrade, before starting either process.
-
-Fill `DATABASE_URL` in each env file with the same host and database, using
-`coffre_runtime` in `server.env` and `coffre_vault_runtime` in `vault.env`.
-URL-encode special characters in passwords. Neither process gets the owner's
-URL. Keep each env file readable only by its process's user (`chmod 600`).
+Run it with the CLI you ran `coffre init` with. It asks for the database
+administrator's connection string at a hidden prompt (a script can pipe it
+in, or set `COFFRE_SETUP_DATABASE_URL`; never pass it as an argument). It
+makes the two logins coffre runs as, `coffre_runtime` for the server and
+`coffre_vault_runtime` for the vault, migrates the database, checks that
+each login holds only its rights, and prints every value at once, as one
+block for each process. It keeps no copy and writes no file. Save its
+output in your password manager, with the OAuth client secret, before
+anything else. Then the app's block goes in `server.env` and the vault's in
+`vault.env`: one key for each process, so that the server, which faces the
+network, never holds what decrypts a value.
+
+- `KEK`, the vault's, decrypts every value, and the vault derives from it the
+  key it signs its records with. Lose it, and every value is lost.
+- `AUDIT_CHAIN_KEY`, the server's, signs the server's log entries, sessions
+  and tokens. Lose it, and everyone is signed out and the log stops
+  verifying.
+- Each `DATABASE_URL` is the same database through that process's own login.
+  Neither process gets the administrator's URL.
+
+With AWS KMS instead of a key of your own, the vault also needs a
+`SIGNING_KEY` ([keys](https://github.com/erwinkn/coffre/blob/main/docs/keys.md#aws-kms)).
+To do the same by hand, see
+[deploy.md](https://github.com/erwinkn/coffre/blob/main/docs/deploy.md#appendix-the-database-by-hand).
+
+Run `pnpm migrate`, with the administrator's URL in `DATABASE_URL`, after
+every package upgrade, before starting either process.
 
 For tests and local development only, both URLs may instead name the same
-absolute SQLite file, e.g. `file:/tmp/coffre-local.db`; migrate that URL once.
-SQLite has no database logins or separation of privileges.
+absolute SQLite file, e.g. `file:/tmp/coffre-local.db`; migrate that URL once
+with `pnpm migrate`, and make the keys with `npx @coffre/cli keys`. SQLite
+has no database logins or separation of privileges.
 
 ## 3. Run
 

package/dist/templates/node/package.json

@@ -13,11 +13,11 @@
     "conformance": "coffre-conformance node"
   },
   "dependencies": {
-    "@coffre/server": "0.1.0",
-    "@coffre/vault": "0.1.0"
+    "@coffre/server": "0.1.2",
+    "@coffre/vault": "0.1.2"
   },
   "devDependencies": {
-    "@coffre/conformance": "0.1.0",
+    "@coffre/conformance": "0.1.2",
     "@types/node": "26.1.1",
     "typescript": "5.9.3"
   }

package/dist/templates/node/server.env.example

@@ -4,7 +4,8 @@ PORT=3000
 # Where people reach coffre, through the proxy that terminates TLS in front
 # of it: an origin, no path.
 PUBLIC_URL=https://secrets.example.com
-# The vault uses this Postgres database through a different login.
+# From `coffre setup`: the database, as the server's own login. The vault
+# uses it through another.
 DATABASE_URL=postgres://coffre_runtime:CHANGE_ME@127.0.0.1:5432/coffre
 # The vault's socket, as in vault.env.
 VAULT_SOCKET=vault.sock
@@ -13,6 +14,6 @@ VAULT_SOCKET=vault.sock
 GITHUB_CLIENT_ID=
 GITHUB_CLIENT_SECRET=
 
-# 32 random bytes, base64 (`openssl rand -base64 32`): keys the audit log's
-# hash chain.
+# From `coffre setup`, saved in your password manager first: signs the
+# server's log entries, sessions and tokens.
 AUDIT_CHAIN_KEY=

package/dist/templates/node/src/server.ts

@@ -16,7 +16,7 @@ const server = await serve({
   database: env('DATABASE_URL'),
   vault: connectVault(env('VAULT_SOCKET')),
   // For tests or local SQLite development only, the vault in this process:
-  // vault: await localVault({ database: env('DATABASE_URL'), kek: …, rootAdmins: […], signingKey: … }),
+  // vault: await localVault({ database: env('DATABASE_URL'), kek: …, rootAdmins: […] }),
   auth: signin({
     providers: [
       github({

package/dist/templates/node/src/vault.ts

@@ -15,10 +15,12 @@ const vault = await serveVault({
   socket: env('VAULT_SOCKET'),
   database: env('DATABASE_URL'),
   kek: { id: env('KEK_ID'), key: env('KEK') },
-  // After a rotation, the KEKs before it, so the data keys they wrapped
-  // still open: previousKeks: [{ id: 'kek-1', key: env('KEK_1') }],
+  // After a rotation, the KEKs before it, so the data keys they wrapped still
+  // open and the records signed under them before it still verify:
+  // previousKeks: [{ id: 'kek-1', key: env('KEK_1') }],
   rootAdmins: env('ROOT_ADMINS').split(',').map((email) => email.trim()),
-  signingKey: env('SIGNING_KEY'),
+  // The vault derives its signing key from the KEK. With a KEK a key service
+  // holds, such as awsKms(…), it needs one of its own: signingKey: env('SIGNING_KEY').
 });
 console.log(`the vault is listening on ${vault.socket}`);