@coffre/db 0.14.2 → 0.14.3

package/dist/migrations/postgres/meta/_journal.json

@@ -134,6 +134,13 @@
       "when": 1792871149580,
       "tag": "0018_rotate_app_key",
       "breakpoints": true
+    },
+    {
+      "idx": 19,
+      "version": "7",
+      "when": 1792937576477,
+      "tag": "0019_backup_role",
+      "breakpoints": true
     }
   ]
 }

package/dist/schema-version.js

@@ -141,6 +141,13 @@ const KNOWN_MIGRATIONS = {
 			"when": 1792871149580,
 			"tag": "0018_rotate_app_key",
 			"breakpoints": true
+		},
+		{
+			"idx": 19,
+			"version": "7",
+			"when": 1792937576477,
+			"tag": "0019_backup_role",
+			"breakpoints": true
 		}
 	].map((entry) => entry.tag),
 	sqlite: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/db",
-  "version": "0.14.2",
+  "version": "0.14.3",
   "description": "coffre's database: the schema, its migrations and the connections, on Postgres or SQLite.",
   "license": "MIT",
   "repository": {
@@ -79,7 +79,7 @@
     "drizzle-orm": "0.45.2",
     "pg": "8.16.3",
     "pg-connection-string": "2.14.0",
-    "@coffre/core": "0.14.2"
+    "@coffre/core": "0.14.3"
   },
   "devDependencies": {
     "@types/node": "26.1.1",

package/src/dialect.ts

@@ -39,11 +39,12 @@ export 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 function forUpdate<Query extends { for: (strength: 'update' | 'no key update') => unknown }>(
+export function forUpdate<Query extends { for: (strength: 'update' | 'no key update' | 'share') => unknown }>(
   db: Queryable,
   query: Query,
-  strength: 'update' | 'no key update' = 'update',
+  strength: 'update' | 'no key update' | 'share' = 'update',
 ): ReturnType<Query['for']> {
   if (engineOf(db) === 'sqlite') return query as ReturnType<Query['for']>;
   return query.for(strength) as ReturnType<Query['for']>;

package/src/migrate-main.ts

@@ -1,8 +1,11 @@
-// `pnpm db:migrate`: the workspace's own migrator, for dev
-// and the tests. A deployment runs `coffre-server migrate`.
+// `pnpm db:migrate [--backup-login <role>]`: the workspace's own migrator,
+// for dev and the tests. A deployment runs `coffre-server migrate`.
+import { parseArgs } from 'node:util';
+
 import { migrateDatabase } from './migrate.ts';
 
 const url = process.env.DATABASE_URL?.trim();
 if (!url) throw new Error('DATABASE_URL is required');
-await migrateDatabase(url);
+const { values } = parseArgs({ options: { 'backup-login': { type: 'string' } }, strict: true });
+await migrateDatabase(url, { backupLogin: values['backup-login'] });
 console.log('database schema is up to date');

package/src/migrate.ts

@@ -24,12 +24,33 @@ const MIGRATION_LOCK_KEY = '7165058122361679213';
 export async function restrictDatabase(client: Pick<PoolClient, 'query'>): Promise<void> {
   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. */
+export function backupLoginProblem(login: string): string | null {
+  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.
+ */
+export class AfterMigrations extends Error {
+  constructor(error: unknown) {
+    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';
+  }
+}
+
 interface JournalEntry {
   idx: number;
   when: number;
@@ -55,8 +76,8 @@ interface Migrator {
   lock(): Promise<void>;
   unlock(): Promise<void>;
   migrate(migrationsFolder: string): Promise<void>;
-  /** Reassert privileges a one-database backup does not carry. */
-  restrict(): Promise<void>;
+  /** Reassert privileges a one-database backup does not carry, and grant `backupLogin` the backup group (0019_backup_role.sql). */
+  restrict(backupLogin: string | undefined): Promise<void>;
   /** Why this login cannot change the objects migrations change, `managed` among them, or null when it can. */
   notOwner(managed: Managed): Promise<NotOwner | null>;
   close(): Promise<void>;
@@ -264,7 +285,15 @@ async function postgresMigrator(url: string): Promise<Migrator> {
       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 !== undefined) {
+        // Compared as text: as a name, Postgres would cut it to 63 bytes, and grant whichever role bears the cut.
+        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<{ owner: string; member: boolean; login: string; grants_inherit: boolean; inherits: boolean }>(FOREIGN_OWNERS, [relations, functions]);
       if (rows.length === 0) return null;
@@ -342,17 +371,23 @@ export async function migrationStatus(url: string): Promise<{ applied: string[];
 }
 
 /**
- * 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 async function migrateDatabase(
   url: string,
-  onPlan?: (plan: MigrationPlan) => void | Promise<void>,
+  { onPlan, backupLogin }: { onPlan?: (plan: MigrationPlan) => void | Promise<void>; backupLogin?: string } = {},
 ): Promise<void> {
   const engine = engineOfUrl(url);
+  const problem = backupLogin === undefined ? null : backupLoginProblem(backupLogin);
+  if (problem !== null) throw new Error(problem);
+  if (engine === 'sqlite' && backupLogin !== undefined) throw new Error('SQLite has no roles, so no backup login');
   const expected = await expectedMigrations(engine);
   const migrator = await { postgres: postgresMigrator, sqlite: sqliteMigrator }[engine](url);
   let locked = false;
@@ -369,7 +404,11 @@ export async function migrateDatabase(
     await onPlan?.({ applied: done, total: expected.length, pending: expected.slice(done).map((entry) => entry.tag) });
     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();

package/src/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);