@coffre/db 0.14.1 → 0.14.3

package/dist/dialect.d.ts

@@ -28,10 +28,11 @@ export declare function engineOf(db: Queryable): Engine;
  *
  * `no key update` is for rows others reference by foreign key: it keeps out
  * every other writer of the row, but not an insert that points at it.
+ * `share` keeps out every writer, but not another `share`.
  */
 export declare function forUpdate<Query extends {
-  for: (strength: 'update' | 'no key update') => unknown;
-}>(db: Queryable, query: Query, strength?: 'update' | 'no key update'): ReturnType<Query['for']>;
+  for: (strength: 'update' | 'no key update' | 'share') => unknown;
+}>(db: Queryable, query: Query, strength?: 'update' | 'no key update' | 'share'): ReturnType<Query['for']>;
 /**
  * The rows a hand-written query answers, as the driver gives them: what
  * Postgres's `execute` and SQLite's `all` each call a result. Column names

package/dist/dialect.js

@@ -15,6 +15,7 @@ function engineOf(db) {
 *
 * `no key update` is for rows others reference by foreign key: it keeps out
 * every other writer of the row, but not an insert that points at it.
+* `share` keeps out every writer, but not another `share`.
 */
 function forUpdate(db, query, strength = "update") {
 	if (engineOf(db) === "sqlite") return query;

package/dist/migrate.d.ts

@@ -3,6 +3,16 @@ import { PoolClient } from "pg";
 //#region src/migrate.d.ts
 /** Reassert database privileges that pg_dump and CREATE DATABASE TEMPLATE do not carry. */
 export declare function restrictDatabase(client: Pick<PoolClient, 'query'>): Promise<void>;
+/** Why `login` cannot be the backup login, before anything runs, or null when it may. */
+export declare function backupLoginProblem(login: string): string | null;
+/**
+ * The migrations are applied, by this run or an earlier one, and their
+ * ledger checked, but reasserting the privileges after them failed: unlike
+ * a migration's failure, this one may have changed the database.
+ */
+export declare class AfterMigrations extends Error {
+  constructor(error: unknown);
+}
 /** An owner of coffre's objects whose privileges the login lacks: not a member of it, or one that does not inherit them. */
 export type ForeignOwner = {
   name: string;
@@ -80,11 +90,17 @@ export declare function migrationStatus(url: string): Promise<{
   notOwner: NotOwner | null;
 }>;
 /**
- * Apply missing migrations, check their history and reassert database
- * privileges, as a login that can change coffre's objects: another is
- * refused, NotOwner, before anything changes. `onPlan` hears what there is to apply before it is, under
+ * Apply missing migrations, check their history, and reassert database
+ * privileges, on every run, even with nothing to apply, as a login that can
+ * change coffre's objects: another is refused, NotOwner, before anything
+ * changes. `onPlan` hears what there is to apply before it is, under
  * the migration lock, and may stop the run by throwing: all of it then goes
- * in one call, with no word of each.
+ * in one call, with no word of each. `backupLogin` names an existing role to
+ * grant the backup group, `coffre_backup`, on Postgres; it is never made, and
+ * never revoked when a later run names none.
  */
-export declare function migrateDatabase(url: string, onPlan?: (plan: MigrationPlan) => void | Promise<void>): Promise<void>;
+export declare function migrateDatabase(url: string, { onPlan, backupLogin }?: {
+  onPlan?: (plan: MigrationPlan) => void | Promise<void>;
+  backupLogin?: string;
+}): Promise<void>;
 //#endregion

package/dist/migrate.js

@@ -19,11 +19,34 @@ const MIGRATION_LOCK_KEY = "7165058122361679213";
 async function restrictDatabase(client) {
 	await client.query(`DO $$ BEGIN
     EXECUTE format(
-      'REVOKE CREATE, TEMPORARY ON DATABASE %I FROM PUBLIC, coffre_app, coffre_runtime, coffre_vault, coffre_vault_runtime',
+      'REVOKE CREATE, TEMPORARY ON DATABASE %I FROM PUBLIC, coffre_app, coffre_runtime, coffre_vault, coffre_vault_runtime, coffre_backup',
       current_database()
     );
   END $$`);
 }
+/** Why `login` cannot be the backup login, before anything runs, or null when it may. */
+function backupLoginProblem(login) {
+	if (login === "") return "the backup login is empty: name the role to grant coffre_backup";
+	if ([
+		"coffre_backup",
+		"coffre_app",
+		"coffre_vault",
+		"coffre_runtime",
+		"coffre_vault_runtime"
+	].includes(login)) return `the backup login is ${login}, one of coffre's own roles: name the login that backs up`;
+	return null;
+}
+/**
+* The migrations are applied, by this run or an earlier one, and their
+* ledger checked, but reasserting the privileges after them failed: unlike
+* a migration's failure, this one may have changed the database.
+*/
+var AfterMigrations = class extends Error {
+	constructor(error) {
+		super(`the database is at the migrated schema, but reasserting its privileges failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+		this.name = "AfterMigrations";
+	}
+};
 /**
 * The login cannot change coffre's objects, the ledger's schema, the tables
 * and the functions: their owners are roles whose privileges it does not
@@ -171,7 +194,14 @@ async function postgresMigrator(url) {
 			await client.query("SELECT pg_advisory_unlock($1::bigint)", [MIGRATION_LOCK_KEY]);
 		},
 		migrate: (migrationsFolder) => migrate(drizzle(client), { migrationsFolder }),
-		restrict: () => restrictDatabase(client),
+		async restrict(backupLogin) {
+			await restrictDatabase(client);
+			if (backupLogin !== void 0) {
+				const { rowCount } = await client.query("SELECT 1 FROM pg_roles WHERE rolname::text = $1", [backupLogin]);
+				if (rowCount === 0) throw new Error(`role ${client.escapeIdentifier(backupLogin)} does not exist: make it, coffre never does`);
+				await client.query(`GRANT coffre_backup TO ${client.escapeIdentifier(backupLogin)} WITH ADMIN FALSE, INHERIT TRUE, SET FALSE`);
+			}
+		},
 		async notOwner({ relations, functions }) {
 			const { rows } = await client.query(FOREIGN_OWNERS, [relations, functions]);
 			if (rows.length === 0) return null;
@@ -238,14 +268,20 @@ async function migrationStatus(url) {
 	}
 }
 /**
-* Apply missing migrations, check their history and reassert database
-* privileges, as a login that can change coffre's objects: another is
-* refused, NotOwner, before anything changes. `onPlan` hears what there is to apply before it is, under
+* Apply missing migrations, check their history, and reassert database
+* privileges, on every run, even with nothing to apply, as a login that can
+* change coffre's objects: another is refused, NotOwner, before anything
+* changes. `onPlan` hears what there is to apply before it is, under
 * the migration lock, and may stop the run by throwing: all of it then goes
-* in one call, with no word of each.
+* in one call, with no word of each. `backupLogin` names an existing role to
+* grant the backup group, `coffre_backup`, on Postgres; it is never made, and
+* never revoked when a later run names none.
 */
-async function migrateDatabase(url, onPlan) {
+async function migrateDatabase(url, { onPlan, backupLogin } = {}) {
 	const engine = engineOfUrl(url);
+	const problem = backupLogin === void 0 ? null : backupLoginProblem(backupLogin);
+	if (problem !== null) throw new Error(problem);
+	if (engine === "sqlite" && backupLogin !== void 0) throw new Error("SQLite has no roles, so no backup login");
 	const expected = await expectedMigrations(engine);
 	const migrator = await {
 		postgres: postgresMigrator,
@@ -267,7 +303,11 @@ async function migrateDatabase(url, onPlan) {
 		});
 		await migrator.migrate(migrationsFolder(engine));
 		verifyHistory(expected, await migrator.applied(), true);
-		await migrator.restrict();
+		try {
+			await migrator.restrict(backupLogin);
+		} catch (error) {
+			throw new AfterMigrations(error);
+		}
 	} finally {
 		try {
 			if (locked) await migrator.unlock();
@@ -277,4 +317,4 @@ async function migrateDatabase(url, onPlan) {
 	}
 }
 //#endregion
-export { DatabaseAhead, NotOwner, managedObjects, migrateDatabase, migrationStatus, migrationsFolder, restrictDatabase };
+export { AfterMigrations, DatabaseAhead, NotOwner, backupLoginProblem, managedObjects, migrateDatabase, migrationStatus, migrationsFolder, restrictDatabase };

package/dist/migrations/postgres/0019_backup_role.sql

@@ -0,0 +1,63 @@
+-- Backups (W2356): the group coffre_backup reads every row and writes none, so a nightly pg_dump need not hold the owner's password. No login is made or granted here: `coffre migrate --backup-login <role>` grants the group to the role it names. Reading every table is not enough: the audit log's row-level security shows its rows only to the roles a policy names, so pg_dump as a role that reads every table (pg_read_all_data) is refused the log, or with --enable-row-security dumps no entry. It only adds a role, read grants and a read policy: the release before never meets them.
+DO $$
+BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'coffre_backup') THEN
+        -- No migration since the baseline made a role: a login that migrates as a member of the owner inherits its privileges, never its CREATEROLE.
+        IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = current_user AND (rolsuper OR rolcreaterole)) THEN
+            RAISE EXCEPTION '% may not create roles, and this migration makes coffre_backup: migrate as a login with CREATEROLE, or have one run CREATE ROLE coffre_backup NOLOGIN; GRANT coffre_backup TO % WITH ADMIN TRUE, INHERIT FALSE, SET FALSE first', current_user, current_user;
+        END IF;
+        -- Roles are the server's, and the migration lock each database's: another database's 0019 may make it meanwhile.
+        BEGIN
+            CREATE ROLE coffre_backup NOLOGIN INHERIT NOCREATEDB NOCREATEROLE;
+        EXCEPTION WHEN duplicate_object OR unique_violation THEN
+            NULL;
+        END;
+    END IF;
+    -- Managed owners cannot ALTER the superuser-only attributes, even to turn them off.
+    IF EXISTS (
+        SELECT 1 FROM pg_roles WHERE rolname = 'coffre_backup'
+        AND (rolsuper OR rolreplication OR rolbypassrls)
+    ) THEN
+        RAISE EXCEPTION 'coffre_backup has unsafe role attributes: SUPERUSER, REPLICATION and BYPASSRLS must be off';
+    END IF;
+    -- It would pass on what it is a member of to its members.
+    IF EXISTS (SELECT 1 FROM pg_auth_members WHERE member = 'coffre_backup'::regrole) THEN
+        RAISE EXCEPTION 'coffre_backup is a member of another role, whose privileges its members would inherit: revoke its memberships';
+    END IF;
+    -- Revoking cannot take an owner's rights away: its members would write what it owns.
+    IF EXISTS (
+        SELECT 1 FROM pg_shdepend
+         WHERE refclassid = 'pg_authid'::regclass AND refobjid = 'coffre_backup'::regrole AND deptype = 'o'
+    ) THEN
+        RAISE EXCEPTION 'coffre_backup owns database objects, which its members could change: reassign them';
+    END IF;
+    -- Only when it must: altering a role takes CREATEROLE too.
+    IF EXISTS (
+        SELECT 1 FROM pg_roles WHERE rolname = 'coffre_backup'
+        AND (rolcanlogin OR NOT rolinherit OR rolcreatedb OR rolcreaterole)
+    ) THEN
+        ALTER ROLE coffre_backup NOLOGIN INHERIT NOCREATEDB NOCREATEROLE;
+    END IF;
+END
+$$;
+--> statement-breakpoint
+-- coffre's own, by name, as the baseline grants: public may hold a database's other tables (FOREIGN_OWNERS in migrate.ts), which are not coffre's to grant, whichever login migrates, a superuser included. A group made before this keeps no other privilege on them. A later migration that makes a table grants it SELECT too, as it grants coffre_app, rather than default privileges, which would give it every table the login makes, coffre's or not, and none another login makes.
+REVOKE ALL ON SCHEMA public, drizzle FROM coffre_backup;
+--> statement-breakpoint
+GRANT USAGE ON SCHEMA public, drizzle TO coffre_backup;
+--> statement-breakpoint
+REVOKE ALL ON audit_chain_head, audit_log, capped_alerts, consumed_tokens, credentials, device_authorizations, dismissed_keys, enrollments, environments, identities, mcp_approvals, mcp_connections, oauth_clients, projects, secret_references, secret_versions, secrets, service_bindings, vault_grants, vault_members FROM coffre_backup;
+--> statement-breakpoint
+REVOKE ALL ON ALL TABLES IN SCHEMA drizzle FROM coffre_backup;
+--> statement-breakpoint
+REVOKE ALL ON ALL SEQUENCES IN SCHEMA drizzle FROM coffre_backup;
+--> statement-breakpoint
+REVOKE ALL ON FUNCTION audit_log_append_only(), secret_versions_erase_only(), prune_consumed_tokens(integer) FROM coffre_backup;
+--> statement-breakpoint
+GRANT SELECT ON audit_chain_head, audit_log, capped_alerts, consumed_tokens, credentials, device_authorizations, dismissed_keys, enrollments, environments, identities, mcp_approvals, mcp_connections, oauth_clients, projects, secret_references, secret_versions, secrets, service_bindings, vault_grants, vault_members TO coffre_backup;
+--> statement-breakpoint
+GRANT SELECT ON ALL TABLES IN SCHEMA drizzle TO coffre_backup;
+--> statement-breakpoint
+GRANT SELECT ON ALL SEQUENCES IN SCHEMA drizzle TO coffre_backup;
+--> statement-breakpoint
+CREATE POLICY audit_log_backup_read ON audit_log FOR SELECT TO coffre_backup USING (true);