@coffre/db 0.4.6 → 0.5.1

package/src/grants.ts

@@ -1,13 +1,31 @@
-import { and, eq, gt, isNull, or } from 'drizzle-orm';
+import {
+  administers,
+  convertEveryProjectGrants,
+  EVERYWHERE,
+  isInstanceRole,
+  isScope,
+  normalScope,
+  unscoped,
+  type Conversion,
+  type InstanceRole,
+  type Role,
+  type Scope,
+} from '@coffre/core/access';
+import type { StoredEntry } from '@coffre/core/audit';
+import { isTombstone } from '@coffre/core/schemas';
+import { ACCESS_ACTIONS } from '@coffre/core/vault';
+import { and, desc, eq, gt, inArray, isNull, lt, or, sql, type SQL } from 'drizzle-orm';
 
 import { tablesOf, type Queryable } from './database.ts';
+import { entryColumns, LOOK_BACK, newestAuthentic, type Authenticity, type Newest } from './log.ts';
 
 /**
  * One grant, as `vault_grants` holds it: on a project (`environmentId`
- * null), one of its environments (`projectId` is the environment's
- * project), every project (both ids null), or one environment slug in every
- * project (`environmentSlug`). Only the vault writes grants; the app reads
- * them for its lists.
+ * null), or one of its environments (`projectId` is the environment's
+ * project). A grant on every project of 0.4 names neither, and
+ * `environmentSlug` the one environment slug it covers in each, until the
+ * vault replaces it. Only the vault writes grants; the app reads them for
+ * its lists.
  */
 export type GrantRow = {
   principal: string;
@@ -21,13 +39,10 @@ export type GrantRow = {
   grantedBy: string;
 };
 
-/**
- * Grants, lapsed ones too unless `liveAt` says when to judge them: one
- * member's, or everyone's; `everyProject`, only those on every project.
- */
+/** Grants, lapsed ones too unless `liveAt` says when to judge them: one member's, or everyone's. */
 export async function readGrants(
   db: Queryable,
-  filter: { principal?: string; liveAt?: number; everyProject?: boolean } = {},
+  filter: { principal?: string; liveAt?: number } = {},
 ): Promise<GrantRow[]> {
   const { vaultGrants, environments } = tablesOf(db);
   const rows = await db
@@ -38,7 +53,6 @@ export async function readGrants(
       and(
         filter.principal === undefined ? undefined : eq(vaultGrants.principal, filter.principal),
         filter.liveAt === undefined ? undefined : or(isNull(vaultGrants.expiresAt), gt(vaultGrants.expiresAt, filter.liveAt)),
-        filter.everyProject === true ? and(isNull(vaultGrants.projectId), isNull(vaultGrants.environmentId)) : undefined,
       ),
     );
   return rows.map(({ grant, environmentProjectId }) => ({ ...grant, projectId: grant.projectId ?? environmentProjectId }));
@@ -49,3 +63,250 @@ export async function insertGrant(db: Queryable, grant: GrantRow): Promise<void>
   const { vaultGrants } = tablesOf(db);
   await db.insert(vaultGrants).values({ ...grant, projectId: grant.environmentId === null ? grant.projectId : null });
 }
+
+/** A member's instance role and its scope, as `vault_members` stores them. */
+export type StoredRole = { owner: boolean; role: string | null; scope: string | null };
+
+/**
+ * A member's instance role and its scope, as their row says: a row no vault
+ * of 0.5 wrote has no role, and its `owner` says whether they are an Admin.
+ * A role or a scope the vault would never have written reads as holding
+ * nothing (the vault then refuses the row by its MAC); a member's scope is
+ * everywhere, since a member's role reaches nothing.
+ */
+export function storedRole({ owner, role, scope }: StoredRole): { role: InstanceRole; scope: Scope } {
+  const named: InstanceRole = role === null ? (owner ? 'admin' : 'member') : isInstanceRole(role) ? role : 'member';
+  if (named === 'member' || scope === null) return { role: named, scope: EVERYWHERE };
+  let parsed: unknown = null;
+  try {
+    parsed = JSON.parse(scope);
+  } catch {}
+  return { role: named, scope: isScope(parsed) ? normalScope(parsed) : NOWHERE };
+}
+
+/** A scope that takes in nothing: what a stored scope nobody can read means. */
+const NOWHERE: Scope = { projects: { only: [] }, environments: { only: [] } };
+
+/** The columns that store a member's instance role and scope: `owner` too, for a vault of 0.4 to read. */
+export function roleColumns(role: InstanceRole, scope: Scope): StoredRole {
+  const normal = normalScope(scope);
+  return { owner: administers(role), role, scope: role === 'member' || unscoped(normal) ? null : JSON.stringify(normal) };
+}
+
+/** What the vault does, when this version first runs, to one member's grants on every project of 0.4. */
+export type EveryProjectPreview = {
+  principal: string;
+  /** Each, as a path (`*`, or `*` and the slug it covers), its role and its end. */
+  before: { place: string; role: string; expiresAt: number | null }[];
+  conversion: Conversion;
+  /** The places the conversion names, by id: `market`, `market/dev`. */
+  paths: Record<string, string>;
+  /**
+   * Whether the vault has reported their row changed around it since the
+   * last change to what they hold (`tamperedMembers`), by the entries in its
+   * name: then it leaves them as they are, unless the report is forged.
+   */
+  reported: boolean;
+};
+
+/**
+ * What the vault will make of the grants on every project of 0.4 that live
+ * members hold, by the rule it converts them with
+ * (`convertEveryProjectGrants`), from the rows as they are: what
+ * `coffre migrate` says before the vault does it. A display: the vault
+ * reads again, under its locks, when it converts, and checks what this
+ * cannot, holding no key: each row's MAC, and each entry's in its name. So
+ * a member it has reported changed around it is listed, and marked
+ * `reported`, by the vault's own rule (`tamperedMembers`) over the entries as
+ * they read: whether that report is the vault's own, or forged so as to
+ * hide what it will do, only the vault can tell. Any member the vault
+ * converts is listed. A root admin's it leaves while they are one, until
+ * they are not; which they are, the vault's configuration says and the
+ * database does not, so they are listed too.
+ */
+export async function everyProjectPreview(db: Queryable, at: number): Promise<EveryProjectPreview[]> {
+  const { vaultMembers, projects, environments } = tablesOf(db);
+  const held = (await readGrants(db, { liveAt: at })).filter((grant) => grant.projectId === null && grant.environmentId === null);
+  if (held.length === 0) return [];
+  const holders = [...new Set(held.map((grant) => grant.principal))].sort();
+  const [members, grants, places, inside, tampered] = await Promise.all([
+    db.select({ principal: vaultMembers.principal, status: vaultMembers.status, owner: vaultMembers.owner, role: vaultMembers.role, scope: vaultMembers.scope }).from(vaultMembers),
+    readGrants(db, { liveAt: at }),
+    db.select({ id: projects.id, slug: projects.slug }).from(projects),
+    db.select({ id: environments.id, projectId: environments.projectId, slug: environments.slug }).from(environments),
+    // The vault's own rule (`reportStands`), over every entry in its name, for everyone in two queries.
+    tamperedMembers(db),
+  ]);
+  // A deleted place keeps its row under a tombstone's slug, its own or its project's: no grant reaches it.
+  const live = places.filter((project) => !isTombstone(project.slug)).map((project) => ({
+    id: project.id,
+    environments: inside.filter((environment) => environment.projectId === project.id && !isTombstone(environment.slug)).map(({ id, slug }) => ({ id, slug })),
+  }));
+  const paths = Object.fromEntries(places.flatMap((project) => [
+    [project.id, project.slug],
+    ...inside.filter((environment) => environment.projectId === project.id).map((environment) => [environment.id, `${project.slug}/${environment.slug}`]),
+  ]));
+  return holders.flatMap((principal) => {
+    const member = members.find((row) => row.principal === principal);
+    if (member?.status !== 'active') return [];
+    const theirs = held.filter((grant) => grant.principal === principal);
+    return [{
+      principal,
+      before: theirs.map((grant) => ({ place: grant.environmentSlug === null ? '*' : `*/${grant.environmentSlug}`, role: grant.role, expiresAt: grant.expiresAt })),
+      conversion: convertEveryProjectGrants({
+        person: principal.startsWith('user:'),
+        role: principal.startsWith('user:') ? storedRole(member).role : 'member',
+        everyProject: theirs.map((grant) => ({ environmentSlug: grant.environmentSlug, role: grant.role as Role, expiresAt: grant.expiresAt })),
+        grants: grants
+          .filter((grant) => grant.principal === principal && grant.projectId !== null)
+          .map((grant) => ({ projectId: grant.projectId, environmentId: grant.environmentId, role: grant.role as Role, expiresAt: grant.expiresAt })),
+        projects: live,
+      }),
+      paths,
+      reported: tampered.has(principal),
+    }];
+  });
+}
+
+/** A service token or trust binding of 0.4, which carries no scope of its own yet. */
+export type Unsealed = { kind: 'token' | 'binding'; id: string; principal: string };
+
+/**
+ * The live service tokens and trust bindings of active service accounts
+ * that carry no scope yet, as 0.4 made them: what the app seals with each
+ * account's grants once a process (`sealScopes`), and what `coffre migrate`
+ * says it will. A credential a binding issued carries its binding's.
+ */
+export async function unsealedCredentials(db: Queryable, at: Date): Promise<Unsealed[]> {
+  const { credentials, serviceBindings, vaultMembers } = tablesOf(db);
+  const [tokens, bindings] = await Promise.all([
+    db
+      .select({ id: credentials.id, principal: credentials.principal })
+      .from(credentials)
+      .innerJoin(vaultMembers, and(eq(vaultMembers.principal, credentials.principal), eq(vaultMembers.generation, credentials.generation)))
+      .where(and(
+        eq(credentials.kind, 'service'),
+        isNull(credentials.scope),
+        sql`${credentials.createdBy} NOT LIKE 'binding:%'`,
+        isNull(credentials.revokedAt),
+        gt(credentials.expiresAt, at),
+        eq(vaultMembers.status, 'active'),
+      )),
+    db
+      .select({ id: serviceBindings.id, principal: serviceBindings.principal })
+      .from(serviceBindings)
+      .innerJoin(vaultMembers, and(eq(vaultMembers.principal, serviceBindings.principal), eq(vaultMembers.generation, serviceBindings.generation)))
+      .where(and(isNull(serviceBindings.scope), isNull(serviceBindings.revokedAt), eq(vaultMembers.status, 'active'))),
+  ]);
+  return [
+    ...tokens.map((row) => ({ kind: 'token' as const, ...row })),
+    ...bindings.map((row) => ({ kind: 'binding' as const, ...row })),
+  ].sort((a, b) => a.principal.localeCompare(b.principal) || a.kind.localeCompare(b.kind) || a.id.localeCompare(b.id));
+}
+
+/**
+ * The members the vault has found changed around it, and not started over
+ * since, as a reader without its key can tell: `reportStands`' rule, taking
+ * every entry in the vault's name as its own, for everyone at once, where
+ * the app lists members and `coffre migrate` marks them. Their newest
+ * `vault.tampered`, for their row (`mac`) or an older one put back
+ * (`stale`), is newer than the newest entry changing what they hold. Both
+ * reads go by the log's (author, action, seq) and (author, subject, seq)
+ * indexes, and findings are few.
+ */
+export async function tamperedMembers(db: Queryable, principal?: string): Promise<Set<string>> {
+  const { auditLog } = tablesOf(db);
+  const newest = (actions: readonly string[], extra?: SQL) =>
+    db
+      .select({ principal: auditLog.subjectPrincipal, seq: sql<string>`max(${auditLog.seq})`.mapWith(BigInt) })
+      .from(auditLog)
+      .where(
+        and(
+          eq(auditLog.author, 'vault'),
+          inArray(auditLog.action, [...actions]),
+          principal === undefined ? undefined : eq(auditLog.subjectPrincipal, principal),
+          extra,
+        ),
+      )
+      .groupBy(auditLog.subjectPrincipal);
+  const found = await newest(['vault.tampered'], inArray(auditLog.code, [...TAMPER_CODES]));
+  if (found.length === 0) return new Set();
+  const changed = new Map(
+    (await newest(ACCESS_ACTIONS, and(eq(auditLog.decision, 'allow'), inArray(auditLog.subjectPrincipal, found.map((row) => row.principal!)))))
+      .map((row) => [row.principal!, row.seq]),
+  );
+  return new Set(found.filter((row) => row.seq > (changed.get(row.principal!) ?? -1n)).map((row) => row.principal!));
+}
+
+/** The codes of the vault's reports that a member's row was changed around it: their row's MAC fails (`mac`), or an older one was put back (`stale`). */
+const TAMPER_CODES = ['mac', 'stale'] as const;
+
+/**
+ * Whether the vault's report that `principal`'s row was changed around it
+ * stands: one of its own is newer than its newest entry changing what they
+ * hold, and only starting them over, or another change, settles it. While
+ * one stands the vault leaves their grants on every project of 0.4 as they
+ * are. Both entries as `check`, the vault's MACs, tells them apart,
+ * passing over those forged in its name; a reader without its key takes
+ * them all as the vault's (`tamperedMembers`). Only reports after that
+ * entry are read, so older ones, forged or not, never hide one. From
+ * LOOK_BACK forged entries on, of either kind, one may stand, so it is
+ * taken to.
+ */
+export async function reportStands(db: Queryable, principal: string, check: Authenticity): Promise<boolean> {
+  const access = await newestAccess(db, principal, check);
+  if (access === 'unreached') return true;
+  const after = typeof access === 'string' ? -1n : access.seq;
+  const report = await newestAuthentic((before) => tamperReportsAbout(db, principal, LOOK_BACK.page, after, before), check);
+  return report === 'unreached' || typeof report !== 'string';
+}
+
+/** The newest access entry about `principal` that `check` finds the vault's own. */
+export function newestAccess(db: Queryable, principal: string, check: Authenticity): Promise<Newest> {
+  return newestAuthentic((before) => accessEntriesAbout(db, principal, LOOK_BACK.page, before), check);
+}
+
+/** Up to `limit` of the vault's allowed access entries about `principal` before `before` (the newest when undefined), newest first. */
+export async function accessEntriesAbout(db: Queryable, principal: string, limit: number, before?: bigint): Promise<StoredEntry[]> {
+  const { auditLog } = tablesOf(db);
+  const rows = await db
+    .select(entryColumns(db))
+    .from(auditLog)
+    .where(
+      and(
+        eq(auditLog.author, 'vault'),
+        eq(auditLog.subjectPrincipal, principal),
+        inArray(auditLog.action, [...ACCESS_ACTIONS]),
+        eq(auditLog.decision, 'allow'),
+        before === undefined ? undefined : lt(auditLog.seq, before),
+      ),
+    )
+    .orderBy(desc(auditLog.seq))
+    .limit(limit);
+  return rows as StoredEntry[];
+}
+
+/**
+ * Up to `limit` of the vault's reports that `principal`'s row was changed
+ * around it (`TAMPER_CODES`), after `after` and before `before` (the newest
+ * when undefined), newest first.
+ */
+async function tamperReportsAbout(db: Queryable, principal: string, limit: number, after: bigint, before?: bigint): Promise<StoredEntry[]> {
+  const { auditLog } = tablesOf(db);
+  const rows = await db
+    .select(entryColumns(db))
+    .from(auditLog)
+    .where(
+      and(
+        eq(auditLog.author, 'vault'),
+        eq(auditLog.subjectPrincipal, principal),
+        eq(auditLog.action, 'vault.tampered'),
+        inArray(auditLog.code, [...TAMPER_CODES]),
+        gt(auditLog.seq, after),
+        before === undefined ? undefined : lt(auditLog.seq, before),
+      ),
+    )
+    .orderBy(desc(auditLog.seq))
+    .limit(limit);
+  return rows as StoredEntry[];
+}

package/src/log.ts

@@ -1,8 +1,8 @@
-import { GENESIS_HASH, sealEntry, type LogFields, type LogKey } from '@coffre/core/audit';
+import { GENESIS_HASH, sealEntry, type LogFields, type LogKey, type StoredEntry } from '@coffre/core/audit';
 import { desc, eq } from 'drizzle-orm';
 
 import { afterCommit } from './commits.ts';
-import { tablesOf, type Transaction } from './database.ts';
+import { tablesOf, type Queryable, type Transaction } from './database.ts';
 import { clockMillis, forUpdate } from './dialect.ts';
 
 /**
@@ -187,3 +187,67 @@ export async function appendEntries(
   afterCommit(tx, () => remember(key, written));
   return { seqStart: head.nextSeq, ...written, occurredAt: now };
 }
+
+// --- reading the vault's entries back ---------------------------------------------
+
+/** An entry's columns, as the chain's codec reads them (`StoredEntry`). */
+export function entryColumns(db: Queryable) {
+  const { auditLog } = tablesOf(db);
+  return {
+    seq: auditLog.seq,
+    author: auditLog.author,
+    keyId: auditLog.keyId,
+    occurredAt: auditLog.occurredAt,
+    actor: auditLog.actor,
+    action: auditLog.action,
+    decision: auditLog.decision,
+    code: auditLog.code,
+    subjectPrincipal: auditLog.subjectPrincipal,
+    projectId: auditLog.projectId,
+    environmentId: auditLog.environmentId,
+    secretId: auditLog.secretId,
+    secretVersionId: auditLog.secretVersionId,
+    operationId: auditLog.operationId,
+    requestId: auditLog.requestId,
+    sourceIp: auditLog.sourceIp,
+    relatedSeq: auditLog.relatedSeq,
+    metadata: auditLog.metadata,
+    prevHash: auditLog.prevHash,
+    mac: auditLog.mac,
+    hash: auditLog.hash,
+  };
+}
+
+/**
+ * How a reader tells the vault's own entries from those forged in its name:
+ * by their MAC, which only the vault holds the key to check. Each it finds
+ * forged goes to `forged`.
+ */
+export type Authenticity = { authentic: (entry: StoredEntry) => boolean; forged: (entry: StoredEntry) => void };
+
+/** How many entries in its name the vault reads back, a page at a time, for its own newest of a kind (`newestAuthentic`). */
+export const LOOK_BACK = { page: 32, pages: 32 };
+
+/** What `newestAuthentic` finds: the entry, or why there is none. */
+export type Newest = StoredEntry | 'none' | 'forged' | 'unreached';
+
+/**
+ * The newest of the entries `page` reads, newest first and before a seq,
+ * that `check` finds authentic, read back a page at a time: 'none' when
+ * there are none at all, 'forged' when every one is in the vault's name but
+ * not its own, and 'unreached' once it has read LOOK_BACK such entries
+ * (1024), whether or not more are left.
+ */
+export async function newestAuthentic(page: (before: bigint | undefined) => Promise<StoredEntry[]>, check: Authenticity): Promise<Newest> {
+  let before: bigint | undefined;
+  for (let read = 0; read < LOOK_BACK.pages; read += 1) {
+    const entries = await page(before);
+    for (const entry of entries) {
+      if (check.authentic(entry)) return entry;
+      check.forged(entry);
+    }
+    if (entries.length < LOOK_BACK.page) return before === undefined && entries.length === 0 ? 'none' : 'forged';
+    before = entries.at(-1)!.seq;
+  }
+  return 'unreached';
+}

package/src/migrate.ts

@@ -40,6 +40,7 @@ interface ExpectedMigration {
   createdAt: string;
   hash: string;
   tag: string;
+  sql: string;
 }
 
 interface AppliedMigration {
@@ -56,9 +57,95 @@ interface Migrator {
   migrate(migrationsFolder: string): Promise<void>;
   /** Reassert privileges a one-database backup does not carry. */
   restrict(): 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>;
 }
 
+/** 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; member: boolean };
+
+/**
+ * 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
+ * have, as neither one of them nor a member of one that inherits them.
+ * Postgres would refuse the first migration that touches one, "permission
+ * denied for schema drizzle"; this says whose login migrates, or what makes
+ * this one able to: on Postgres 16 and later, a membership that inherits,
+ * which each one's GRANT says; before, a membership, and a login that
+ * inherits (`ALTER ROLE … INHERIT`).
+ */
+export class NotOwner extends Error {
+  readonly login: string;
+  readonly owners: ForeignOwner[];
+
+  constructor(login: string, owners: ForeignOwner[], { grantsInherit, inherits }: { grantsInherit: boolean; inherits: boolean }) {
+    const one = owners.length === 1;
+    const members = owners.every((owner) => owner.member);
+    const fixes = [
+      ...owners.filter((owner) => grantsInherit || !owner.member).map((owner) => `GRANT ${identifier(owner.name)} TO ${identifier(login)}${grantsInherit ? ' WITH INHERIT TRUE' : ''}`),
+      ...(grantsInherit || inherits ? [] : [`ALTER ROLE ${identifier(login)} INHERIT`]),
+    ];
+    super(
+      `coffre's tables are owned by ${owners.map((owner) => owner.name).join(' and ')}, and this login, ${login}, ` +
+        (members
+          ? `is a member of ${one ? 'it' : 'them'} but does not inherit ${one ? 'its' : 'their'} privileges: `
+          : `is neither ${one ? 'it nor a member of it' : 'one nor a member of one'}: `) +
+        `migrate with ${one ? `${owners[0]!.name}'s` : 'their'} connection string, or, as a role that administers ${one ? 'it' : 'them'}, run ${fixes.join('; ')}`,
+    );
+    this.name = 'NotOwner';
+    this.login = login;
+    this.owners = owners;
+  }
+}
+
+/** A role's name as SQL takes it: always quoted, as a keyword such as `user` must be. */
+function identifier(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+/** What coffre's migrations make and so change later: relations and functions, by name, in public. */
+type Managed = { relations: string[]; functions: string[] };
+
+/**
+ * The names a migration's SQL makes: CREATE TABLE, VIEW, MATERIALIZED VIEW
+ * and SEQUENCE, and CREATE FUNCTION, in public. Unquoted, a name is folded
+ * to lower case, as Postgres folds it.
+ */
+export function managedObjects(sqlTexts: readonly string[]): Managed {
+  const name = String.raw`(?:"?public"?\.)?(?:"((?:[^"]|"")+)"|([A-Za-z_][A-Za-z0-9_$]*))`;
+  const relation = new RegExp(String.raw`\bCREATE\s+(?:OR\s+REPLACE\s+)?(?:UNLOGGED\s+)?(?:TABLE|VIEW|MATERIALIZED\s+VIEW|SEQUENCE)\s+(?:IF\s+NOT\s+EXISTS\s+)?${name}`, 'gi');
+  const fn = new RegExp(String.raw`\bCREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\s+${name}\s*\(`, 'gi');
+  const names = (pattern: RegExp) => [
+    ...new Set(sqlTexts.flatMap((text) => [...text.matchAll(pattern)].map(([, quoted, bare]) => (quoted !== undefined ? quoted.replace(/""/g, '"') : bare!.toLowerCase())))),
+  ];
+  return { relations: names(relation), functions: names(fn) };
+}
+
+/**
+ * The owners of what migrations change, whose privileges the login lacks:
+ * the drizzle schema and everything in it, and in public the relations and
+ * functions coffre's migrations make ($1, $2), and nothing else of public,
+ * which may hold a database's other tables. A superuser has every role's.
+ */
+const FOREIGN_OWNERS = `
+  WITH owned AS (
+    SELECT nspowner AS owner FROM pg_namespace WHERE nspname = 'drizzle'
+    UNION ALL
+    SELECT c.relowner FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE c.relkind IN ('r', 'p', 'v', 'm', 'S', 'f')
+        AND (n.nspname = 'drizzle' OR (n.nspname = 'public' AND c.relname = ANY($1::text[])))
+    UNION ALL
+    SELECT p.proowner FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+      WHERE n.nspname = 'public' AND p.proname = ANY($2::text[])
+  )
+  SELECT DISTINCT r.rolname AS owner, pg_has_role(owned.owner, 'MEMBER') AS member, current_user AS login,
+    current_setting('server_version_num')::int >= 160000 AS grants_inherit,
+    (SELECT rolinherit FROM pg_roles WHERE rolname = current_user) AS inherits
+  FROM owned JOIN pg_roles r ON r.oid = owned.owner
+  WHERE NOT pg_has_role(owned.owner, 'USAGE')
+  ORDER BY r.rolname`;
+
 /**
  * Beside this module: src/migrations in the workspace, and dist/migrations
  * in the built package, where the build copies them.
@@ -89,6 +176,7 @@ async function expectedMigrations(engine: Engine): Promise<ExpectedMigration[]>
         createdAt: String(entry.when),
         hash: createHash('sha256').update(sqlText).digest('hex'),
         tag: entry.tag,
+        sql: sqlText,
       };
     }),
   );
@@ -177,6 +265,12 @@ async function postgresMigrator(url: string): Promise<Migrator> {
     },
     migrate: (migrationsFolder) => migrate(drizzle(client), { migrationsFolder }),
     restrict: () => restrictDatabase(client),
+    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;
+      const [{ login, grants_inherit: grantsInherit, inherits }] = rows as [(typeof rows)[number]];
+      return new NotOwner(login, rows.map(({ owner, member }) => ({ name: owner, member })), { grantsInherit, inherits });
+    },
     async close() {
       client.release();
       await pool.end();
@@ -206,6 +300,8 @@ async function sqliteMigrator(url: string): Promise<Migrator> {
     async unlock() {},
     migrate: (migrationsFolder) => migrate(sqlite, { migrationsFolder }),
     async restrict() {},
+    // One file, which whoever opens it may change.
+    notOwner: async () => null,
     close,
   };
 }
@@ -218,21 +314,27 @@ export type MigrationPlan = { applied: number; total: number; pending: string[]
 
 /**
  * Which of this version's migrations a database has applied, and which it
- * has not, without changing it or waiting on a migration under way. A
- * history that is not a prefix of this version's is refused, as
- * `migrateDatabase` refuses it.
+ * has not, without changing it or waiting on a migration under way; and
+ * whether this login could apply them (`notOwner`), as `migrateDatabase`
+ * requires: thrown, when it cannot read which. A history that is not a
+ * prefix of this version's is refused, as `migrateDatabase` refuses it.
  */
-export async function migrationStatus(url: string): Promise<{ applied: string[]; pending: string[] }> {
+export async function migrationStatus(url: string): Promise<{ applied: string[]; pending: string[]; notOwner: NotOwner | null }> {
   const engine = engineOfUrl(url);
   const expected = await expectedMigrations(engine);
   const migrator = await { postgres: postgresMigrator, sqlite: sqliteMigrator }[engine](url);
   try {
-    const history = await migrator.applied();
+    const notOwner = await migrator.notOwner(managedObjects(expected.map((entry) => entry.sql)));
+    // A login that may not even read the ledger is told why.
+    const history = await migrator.applied().catch((error: unknown) => {
+      throw notOwner ?? error;
+    });
     verifyHistory(expected, history, false);
     const applied = history?.length ?? 0;
     return {
       applied: expected.slice(0, applied).map((entry) => entry.tag),
       pending: expected.slice(applied).map((entry) => entry.tag),
+      notOwner,
     };
   } finally {
     await migrator.close();
@@ -241,7 +343,8 @@ export async function migrationStatus(url: string): Promise<{ applied: string[];
 
 /**
  * Apply missing migrations, check their history and reassert database
- * privileges. `onPlan` hears what there is to apply before it is, under
+ * 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
  * the migration lock, and may stop the run by throwing: all of it then goes
  * in one call, with no word of each.
  */
@@ -258,6 +361,8 @@ export async function migrateDatabase(
     await migrator.lock();
     locked = true;
 
+    const notOwner = await migrator.notOwner(managedObjects(expected.map((entry) => entry.sql)));
+    if (notOwner !== null) throw notOwner;
     const applied = await migrator.applied();
     verifyHistory(expected, applied, false);
     const done = applied?.length ?? 0;

package/src/migrations/postgres/0002_instance_roles.sql

@@ -0,0 +1,4 @@
+ALTER TABLE "vault_members" ADD COLUMN "role" text;--> statement-breakpoint
+ALTER TABLE "vault_members" ADD COLUMN "scope" text;--> statement-breakpoint
+-- The vault sets a person's instance role and its scope, as it sets the rest of their row.
+GRANT UPDATE (role, scope) ON vault_members TO coffre_vault;

package/src/migrations/postgres/0003_credential_scopes.sql

@@ -0,0 +1,4 @@
+ALTER TABLE "credentials" ADD COLUMN "scope" text;--> statement-breakpoint
+ALTER TABLE "service_bindings" ADD COLUMN "scope" text;--> statement-breakpoint
+-- The app seals each token and binding of 0.4 with its account's grants, once, as it seals the rest of their rows.
+GRANT UPDATE (scope) ON credentials, service_bindings TO coffre_app;