@coffre/vault 0.4.6 → 0.5.1

package/src/vault.ts

@@ -3,15 +3,27 @@ import { randomUUID, timingSafeEqual } from 'node:crypto';
 import {
   allows,
   assignableToEnvironment,
-  everyProjectPath,
+  convertEveryProjectGrants,
+  EVERYWHERE,
+  givesService,
   grantKind,
+  isCredentialScope,
+  isInstanceRole,
   isRole,
+  isScope,
+  managesService,
   mayManageAccess,
-  type GrantPlace,
+  normalScope,
+  NOTHING,
+  runsInstance,
+  setsUpServices,
   type Holdings,
+  type InstanceRole,
   type Permission,
   type Place,
   type Role,
+  type Scope,
+  type ServiceAccount,
 } from '@coffre/core/access';
 import { GENESIS_HASH, verifyEntries, type LogKey, type StoredEntry } from '@coffre/core/audit';
 import { checkContext, type SecretContext } from '@coffre/core/envelope';
@@ -53,6 +65,9 @@ import {
   type RewrapInput,
   type SecretRef,
   type SetAccessInput,
+  type SetSettingsInput,
+  type Settings,
+  type Through,
   type UnwrapInput,
   type Vault,
   type Via,
@@ -62,14 +77,15 @@ import {
 } from '@coffre/core/vault';
 import type { Database, Queryable, Transaction } from '@coffre/db';
 import { isUniqueViolation, SNAPSHOT } from '@coffre/db/dialect';
-import { appendEntries, lockLogHead, type Appended, type NewEntry } from '@coffre/db/log';
+import { newestAccess, reportStands } from '@coffre/db/grants';
+import { appendEntries, LOOK_BACK, lockLogHead, newestAuthentic, type Appended, type Authenticity, type Newest, type NewEntry } from '@coffre/db/log';
 
 import { KeyAccounting } from './accounting.ts';
 import { signer, type Signer } from './checkpoint.ts';
 import type { ResolvedVaultConfig } from './config.ts';
 import { carries, forward, further, UNVERIFIED, vaultLogKey, VERIFY_BATCH, verifyChain, withCause, type Anchor } from './log.ts';
 import { apply, replayFault, type LoggedMember, type Replayed } from './replay.ts';
-import { memberMac, rowKey, sameGrants, sealed } from './rows.ts';
+import { memberMac, rowKey, sameGrants, sealed, standing } from './rows.ts';
 import * as store from './store.ts';
 import { ACCESS_ACTIONS, type GrantRow, type Member } from './store.ts';
 
@@ -120,6 +136,8 @@ export type PreparedVault = {
   kekChecked: boolean;
   /** Why not, once decided that they do not. */
   wrongKek: string | null;
+  /** Whether this process has replaced the grants on every project of 0.4 there were when it started (`#convert`). */
+  converted: boolean;
 };
 
 export async function prepareVault(config: ResolvedVaultConfig, options: VaultOptions = {}): Promise<PreparedVault> {
@@ -134,6 +152,7 @@ export async function prepareVault(config: ResolvedVaultConfig, options: VaultOp
     superseded: null,
     kekChecked: false,
     wrongKek: null,
+    converted: false,
   };
 }
 
@@ -159,6 +178,10 @@ const LOCK_TIMEOUT_MS = 15_000;
 /** A member: `user:<email>` or `token:<name>`. */
 const PRINCIPAL = /^(user|token):[^\s:][^\s]*$/;
 
+/** A person, and a service account: only a person sets one up (`givesService`). */
+const PERSON = /^user:/;
+const SERVICE = /^token:/;
+
 /** Who acts for the vault itself, as when it gives a root admin a member row. */
 const VAULT_ACTOR = 'system:vault';
 
@@ -183,6 +206,18 @@ const TAMPERED_SUBJECT = "this member's record failed the vault's integrity chec
 /** The action of the vault's entry that signs a prefix of the log. */
 const CHECKPOINT = 'audit.checkpoint';
 
+/** The action of the vault's entry that holds the instance's settings, and changes them (`settings`). */
+const SETTINGS = 'settings.change';
+
+/** The settings before anyone changed them: people set up service accounts anywhere they hold access. */
+const DEFAULT_SETTINGS: Settings = { serviceAccounts: EVERYWHERE };
+
+/** The settings when the log has some, but none the vault wrote within reach: people set up no service accounts. */
+const CLOSED_SETTINGS: Settings = { serviceAccounts: { projects: { only: [] }, environments: 'all' } };
+
+/** Why a person's change to a service account is refused. */
+const NOT_THEIRS = 'a person gives a service account at most what they hold, where the instance lets them set one up, and only to one whose every grant they hold';
+
 /** Who asks for checkpoints: the app's scheduled job. */
 const SCHEDULER = 'system:coffre-scheduler';
 
@@ -283,6 +318,17 @@ type KeyAction = 'secret.read' | 'key.wrap' | 'key.rewrap';
 /** What ties an entry to the app's request, and to the one action it is part of. */
 type Correlation = { requestId?: string | null; operationId?: string | null; credentialId?: string | null };
 
+/**
+ * What the one asking holds through the credential their request came in
+ * on: no more than its scope (`allows`). A scope that is not one is a bug
+ * of the app's, which fails the call.
+ */
+function through(standing: Standing, { credentialScope }: Through): Standing {
+  if (credentialScope == null) return standing;
+  if (!isCredentialScope(credentialScope)) throw new Error('credentialScope must be a list of grants, one a place');
+  return { ...standing, live: { ...standing.live, credentialScope }, all: { ...standing.all, credentialScope } };
+}
+
 /** The credential a CI run's request came in on, as its entries record it: copied, never decided on. */
 function traced(correlation: Correlation): { credentialId?: string } {
   return correlation.credentialId == null ? {} : { credentialId: correlation.credentialId };
@@ -345,6 +391,11 @@ class VaultService implements Vault {
   async #decide<T>(principals: readonly string[], decide: (d: Decision) => Promise<T>): Promise<Outcome<T>> {
     const superseded = await this.#settled();
     if (superseded !== null) return { ok: false, refusal: refusal('wrong_kek', superseded) };
+    return this.#decideNow(principals, decide);
+  }
+
+  /** `#decide`, once the vault is settled. */
+  async #decideNow<T>(principals: readonly string[], decide: (d: Decision) => Promise<T>): Promise<Outcome<T>> {
     const reports: NewEntry[] = [];
     for (let attempt = 1; ; attempt += 1) {
       try {
@@ -436,22 +487,28 @@ class VaultService implements Vault {
       this.#report(reports, principal, 'mac', row.mac.toString('hex'));
       return 'mac';
     }
-    const newest = await this.#newestAccessSeq(db, principal, reports);
-    // No row, and no entry: someone never admitted. No row, but entries: one
-    // deleted, unless it was admitted since the row was read.
-    if (row === undefined ? newest === null : newest === row.accessSeq) return null;
+    const newest = await this.#newestAccess(db, principal, reports);
+    // No row, and no entry of the vault's own: someone never admitted. No
+    // row, but one: one deleted, unless it was admitted since the row was
+    // read. Too many forged to see past: neither a row nor the lack of one holds.
+    const seq = typeof newest !== 'string' ? newest.seq : newest === 'unreached' ? undefined : null;
+    if (row === undefined ? seq === null : seq === row.accessSeq) return null;
     if (row === undefined && (await store.member(db, principal)) !== undefined) throw new Retry();
-    this.#report(reports, principal, 'stale', `${row?.accessSeq ?? 'none'}<${newest}`);
+    this.#report(reports, principal, 'stale', `${row?.accessSeq ?? 'none'}<${seq ?? newest}`);
     return 'stale';
   }
 
-  /** The seq of the newest access entry about `principal` that carries the vault's MAC, or null. */
-  async #newestAccessSeq(db: Queryable, principal: string, reports: NewEntry[]): Promise<bigint | null> {
-    for (const entry of await store.accessEntriesAbout(db, principal, 32)) {
-      if (this.#authentic(entry)) return entry.seq;
-      this.#report(reports, principal, 'forged_entry', String(entry.seq), entry.seq);
-    }
-    return null;
+  /** The newest access entry about `principal` that carries the vault's MAC (`newestAccess` in @coffre/db/grants). */
+  #newestAccess(db: Queryable, principal: string, reports: NewEntry[]): Promise<Newest> {
+    return newestAccess(db, principal, this.#check(reports, principal));
+  }
+
+  /** Entries in the vault's name told apart by their MACs, each it did not write reported, about `principal`. */
+  #check(reports: NewEntry[], principal: string | null): Authenticity {
+    return {
+      authentic: (entry) => this.#authentic(entry),
+      forged: (entry) => this.#report(reports, principal, 'forged_entry', String(entry.seq), entry.seq),
+    };
   }
 
   /** Whether `entry` carries the vault's MAC: under any of its keys before `since`, and only its current one from there. */
@@ -472,7 +529,7 @@ class VaultService implements Vault {
   }
 
   /** A `vault.tampered` entry, once per process for each thing found: `#reported` marks it once committed. */
-  #report(reports: NewEntry[], principal: string, code: Fault | 'forged_entry', detail: string, relatedSeq: bigint | null = null): void {
+  #report(reports: NewEntry[], principal: string | null, code: Fault | 'forged_entry', detail: string, relatedSeq: bigint | null = null): void {
     const key = `${principal}|${code}|${detail}`;
     if (this.#prepared.reported.has(key) || reports.some((entry) => REPORTED.get(entry) === key)) return;
     const entry: NewEntry = {
@@ -516,9 +573,109 @@ class VaultService implements Vault {
     // database; calls that race settle it alike, and a rotation they race
     // to write goes in once (`#rotate`).
     if (prepared.since === null && prepared.superseded === null) await this.#settle();
+    if (prepared.superseded === null && !prepared.converted) await this.#convert();
     return prepared.superseded;
   }
 
+  /**
+   * Replace every grant on every project of 0.4 with what 0.5 has instead
+   * (`convertEveryProjectGrants` in @coffre/core/access): a person's
+   * instance role and its scope, and project grants on the projects there
+   * are now. Once per process, before its first call does anything else:
+   * one decision per member who holds any, as `system:vault`, each grant it
+   * replaces an `access.revoke` that says what became of it. Another
+   * process that converts the same member at once finds nothing left under
+   * their lock. A member whose row fails its check is left as they are, and
+   * so is one the vault has reported changed around it since the last
+   * change to what they hold, even if their row checks out again now (a
+   * genuine row put back). `reportStands` is the rule, which `coffre
+   * migrate` applies too, holding no key, to every entry in the vault's
+   * name: it lists and marks a member so reported, forged or not.
+   * Removing them clears both.
+   */
+  async #convert(): Promise<void> {
+    for (const principal of await store.everyProjectHolders(this.#db)) {
+      if (this.#isRootAdmin(principal)) continue;
+      await this.#decideNow([principal], (d) => this.#replaceEveryProject(d, principal));
+    }
+    this.#prepared.converted = true;
+  }
+
+  async #replaceEveryProject(d: Decision, principal: string): Promise<void> {
+    const row = d.members.get(principal);
+    const subject = await this.#standing(d.tx, principal, row, d.at, d.reports);
+    if (row === undefined || subject.status !== 'active') return;
+    const everyProject = subject.stored.filter((grant) => grant.projectId === null && grant.environmentId === null);
+    if (everyProject.length === 0) return;
+    if (await reportStands(d.tx, principal, this.#check(d.reports, principal))) return;
+    // The projects there are now, read under the log's head, which a deletion holds.
+    await lockLogHead(d.tx);
+    const before = roleOf(principal, row);
+    const conversion = convertEveryProjectGrants({
+      person: principal.startsWith('user:'),
+      role: before.role,
+      everyProject: everyProject.filter((grant) => live(grant, d.at)).map((grant) => ({ environmentSlug: grant.environmentSlug, role: grant.role as Role, expiresAt: grant.expiresAt })),
+      grants: subject.stored
+        .filter((grant) => grantKind(grant) !== null && live(grant, d.at))
+        .map((grant) => ({ projectId: grant.projectId, environmentId: grant.environmentId, role: grant.role as Role, expiresAt: grant.expiresAt })),
+      projects: await store.liveProjects(d.tx),
+    });
+    const after = { role: conversion.role, scope: conversion.scope };
+    const replacedBy = { role: after.role, scope: after.scope, grants: conversion.grants.length };
+    d.grants.set(principal, [...subject.stored]);
+    d.touched.add(principal);
+    const correlation = { operationId: randomUUID() };
+    const drop = (grant: GrantRow) =>
+      d.writes.push(async () => {
+        await store.deleteGrant(d.tx, principal, grant);
+        d.grants.set(principal, d.grants.get(principal)!.filter((held) => held !== grant));
+      });
+
+    for (const grant of everyProject) {
+      drop(grant);
+      // A lapsed one goes with no entry: it changes nothing anyone holds.
+      if (!live(grant, d.at)) continue;
+      const narrowed = conversion.narrowed.filter((loss) => loss.grant.environmentSlug === grant.environmentSlug);
+      d.log.push(accessEntry(VAULT_ACTOR, 'access.revoke', principal, 'allow', correlation, {
+        role: null,
+        expiresAt: null,
+        previousRole: grant.role,
+        ...located(grant).detail,
+        replacedBy,
+        ...(narrowed.length === 0 ? {} : { narrowed: narrowed.map(({ grant: _, ...loss }) => loss) }),
+      }));
+    }
+    if (JSON.stringify(standing(after)) !== JSON.stringify(standing(before))) {
+      d.log.push(accessEntry(VAULT_ACTOR, 'member.role', principal, 'allow', correlation, {
+        ...after,
+        previousRole: before.role,
+        previousScope: before.scope,
+        reason: 'every-project',
+      }));
+      d.writes.push(() => store.updateMember(d.tx, principal, after));
+    }
+    for (const given of conversion.grants) {
+      const place = { projectId: given.projectId, environmentId: given.environmentId, environmentSlug: null };
+      // Whatever they held there, lapsed or not, makes way: the conversion never gives less there than it was.
+      const there = subject.stored.find((grant) => grantKind(grant) !== null && placeKey(grant) === placeKey(place));
+      if (there !== undefined) drop(there);
+      d.writes.push(async (at) => {
+        const grant = { principal, ...place, role: given.role, expiresAt: given.expiresAt, grantedAt: at, grantedBy: VAULT_ACTOR };
+        await store.insertGrant(d.tx, grant);
+        d.grants.get(principal)!.push(grant);
+      });
+      d.log.push({
+        ...accessEntry(VAULT_ACTOR, 'access.grant', principal, 'allow', correlation, {
+          role: given.role,
+          expiresAt: given.expiresAt === null ? null : iso(given.expiresAt),
+          previousRole: given.replaces,
+          reason: 'every-project',
+        }),
+        ...located(place).ids,
+      });
+    }
+  }
+
   /**
    * Which of its keys count where. Those it replaced, from the KEKs in
    * previousKeks, verify only what came before its first entry under its
@@ -824,7 +981,7 @@ class VaultService implements Vault {
       vet?: (db: Queryable) => Promise<(RefusalCode | null)[]>;
       remote: boolean;
       entry: (secret: SecretRef, decision: 'allow' | 'deny', code: string | null) => NewEntry;
-      input: Correlation & { purpose?: string };
+      input: Correlation & Through & { purpose?: string };
     },
     /** One per secret; null for a bad claim, an error for an outage or an unexpected fault. */
     operations: () => ((operation: KeyOperation) => Promise<T | null>)[],
@@ -840,7 +997,7 @@ class VaultService implements Vault {
     }
     if (this.#isRootAdmin(principal)) await this.#rootRow(principal);
     const check = async (d: Decision) => {
-      const reader = await this.#standing(d.tx, principal, d.members.get(principal), d.at, d.reports);
+      const reader = through(await this.#standing(d.tx, principal, d.members.get(principal), d.at, d.reports), call.input);
       // One read of the environments the decision is about, as the store has them, not as the app sent them:
       // each secret's and, for a read through a reference, its holder's. A grant on one slug in every project
       // matches the slug there, and a place deleted on either side opens for none.
@@ -1020,7 +1177,7 @@ class VaultService implements Vault {
     };
     if (this.#isRootAdmin(principal)) await this.#rootRow(principal);
     return this.#decide([principal], async (d) => {
-      const reader = await this.#standing(d.tx, principal, d.members.get(principal), d.at, d.reports);
+      const reader = through(await this.#standing(d.tx, principal, d.members.get(principal), d.at, d.reports), input);
       // Both sides as the store has them: a grant on a slug matches there, and neither side may be deleted.
       const environments = await store.environmentsById(d.tx, items.flatMap((item) => {
         const source = sources.get(item.source.secretId);
@@ -1105,7 +1262,7 @@ class VaultService implements Vault {
       return seals.map((seal) => (done.has(seal.seq) ? ('ended' as const) : null));
     };
     return this.#decide([principal], async (d) => {
-      const actor = await this.#standing(d.tx, principal, d.members.get(principal), d.at, d.reports);
+      const actor = through(await this.#standing(d.tx, principal, d.members.get(principal), d.at, d.reports), input);
       // Ending is allowed in a deleted place: deleting one ends the references into and out of it.
       const environments = await store.environmentsById(d.tx, seals.map((seal) => seal.holder.environmentId));
       const codes: (RefusalCode | null)[] = seals.map((seal) => {
@@ -1181,14 +1338,15 @@ class VaultService implements Vault {
           action: 'member.add',
           decision: 'allow',
           subjectPrincipal: principal,
-          metadata: JSON.stringify({ owner: false, rootAdmin: true }),
+          metadata: JSON.stringify({ role: 'member', rootAdmin: true }),
         },
       ]);
       const { occurredAt: at, seqStart } = appended;
       const row = {
         principal,
         status: 'active' as const,
-        owner: false,
+        role: 'member' as const,
+        scope: EVERYWHERE,
         generation: 0,
         createdAt: at,
         createdBy: VAULT_ACTOR,
@@ -1207,9 +1365,9 @@ class VaultService implements Vault {
    * configuration, which no row can change.
    */
   async #standing(db: Queryable, principal: string, row: Member | undefined, at: number, reports: NewEntry[]): Promise<Standing> {
-    const none = { isRootAdmin: false, isOwner: false, grants: [] };
+    const none = NOTHING;
     if (this.#isRootAdmin(principal)) {
-      const root = { isRootAdmin: true, isOwner: true, grants: [] };
+      const root: Holdings = { isRootAdmin: true, role: 'owner', scope: EVERYWHERE, grants: [] };
       return { principal, status: 'active', live: root, all: root, fault: null, stored: [] };
     }
     const grants = row === undefined ? [] : await store.grants(db, principal);
@@ -1218,12 +1376,12 @@ class VaultService implements Vault {
     if (!PRINCIPAL.test(principal)) return { principal, status: 'unknown', live: none, all: none, fault, stored: grants };
     if (row?.status !== 'active') return { principal, status: row?.status ?? 'unknown', live: none, all: none, fault, stored: grants };
     const held = grants.map((grant) => ({ ...grant, role: grant.role as Role }));
-    const isOwner = row.owner && principal.startsWith('user:');
+    const { role, scope } = roleOf(principal, row);
     return {
       principal,
       status: 'active',
-      live: { isRootAdmin: false, isOwner, grants: held.filter((grant) => live(grant, at)) },
-      all: { isRootAdmin: false, isOwner, grants: held },
+      live: { isRootAdmin: false, role, scope, grants: held.filter((grant) => live(grant, at)) },
+      all: { isRootAdmin: false, role, scope, grants: held },
       fault,
       stored: grants,
     };
@@ -1231,7 +1389,7 @@ class VaultService implements Vault {
 
   #access(principal: string, row: Member | undefined, held: readonly GrantRow[], at: number, tampered: boolean): Access {
     if (this.#isRootAdmin(principal)) {
-      return { principal, status: 'active', generation: row?.generation ?? 0, isRootAdmin: true, isOwner: true, grants: [], since: null, by: null };
+      return { principal, status: 'active', generation: row?.generation ?? 0, isRootAdmin: true, role: 'owner', scope: EVERYWHERE, grants: [], since: null, by: null };
     }
     const active = PRINCIPAL.test(principal) && !tampered && row?.status === 'active';
     return {
@@ -1239,8 +1397,8 @@ class VaultService implements Vault {
       status: tampered ? 'tampered' : !PRINCIPAL.test(principal) ? 'unknown' : (row?.status ?? 'unknown'),
       generation: row?.generation ?? 0,
       isRootAdmin: false,
-      isOwner: active && row.owner && principal.startsWith('user:'),
-      grants: active ? held.filter((grant) => live(grant, at)).map(view) : [],
+      ...(active ? roleOf(principal, row) : { role: 'member', scope: EVERYWHERE }),
+      grants: active ? held.filter((grant) => live(grant, at) && grantKind(grant) !== null).map(view) : [],
       since: row ? iso(row.statusChangedAt) : null,
       by: row?.statusChangedBy ?? null,
     };
@@ -1302,7 +1460,7 @@ class VaultService implements Vault {
 
   setAccess(input: SetAccessInput): Promise<Outcome<{ changes: AccessChange[] }>> {
     const { actor, principal } = input;
-    const changes = input.changes.map((change) => ({ ...change, environmentSlug: change.environmentSlug ?? null }));
+    const changes = input.changes.map(({ projectId, environmentId, role, expiresAt }) => ({ projectId, environmentId, environmentSlug: null, role, expiresAt }));
     const action = changes.every((change) => change.role === null) ? 'access.revoke' : 'access.grant';
     // One place refused is shown where it is, to whoever reads that place's log; an invalid one may be no place at all.
     const [only] = changes.length === 1 ? changes : [];
@@ -1313,54 +1471,76 @@ class VaultService implements Vault {
         ...where.ids,
       }]);
     };
-    const onProjects = changes.flatMap(({ projectId, environmentId, role }) => (projectId === null ? [] : [{ projectId, environmentId, role }]));
     return this.#decide([actor, principal], async (d) => {
       validateCorrelation(input);
       if (!PRINCIPAL.test(principal)) throw refused('invalid', `not a principal: ${principal}`);
       if (this.#isRootAdmin(principal)) throw refused('root_admin');
       const places = new Set<string>();
       for (const change of changes) {
-        const shape = placeShape(change);
-        if (shape !== null) throw refused('invalid', shape);
+        if (grantKind(change) === null) {
+          throw refused('invalid', change.projectId === null && change.environmentId === null
+            ? 'grants are on a project or an environment: a person reaches every project by their instance role'
+            : 'an environment is named in its project');
+        }
         const key = placeKey(change);
         if (places.has(key)) throw refused('invalid', 'each place may be changed once per call');
         places.add(key);
         if (change.role !== null && !isRole(change.role)) throw refused('invalid', `no such role: ${change.role}`);
-        if (change.role !== null && (change.environmentId !== null || change.environmentSlug !== null) && !assignableToEnvironment(change.role)) {
-          throw refused('invalid', `${change.role} can only be granted on a project, or on every project`);
+        if (change.role !== null && change.environmentId !== null && !assignableToEnvironment(change.role)) {
+          throw refused('invalid', `${change.role} can only be granted on a project`);
         }
         const expiresAt = change.expiresAt === null ? null : Date.parse(change.expiresAt);
         if (Number.isNaN(expiresAt) || (expiresAt !== null && expiresAt <= d.at)) {
           throw refused('invalid', 'an end date must be in the future');
         }
       }
-      // Every project is always there; a project or an environment must be,
-      // and to be granted, not deleted. Read under the log's head, which a
-      // deletion holds while it renames the place, so the place is as it commits.
-      if (onProjects.length > 0) await lockLogHead(d.tx);
+      // A project or an environment must be there, and to be granted, not
+      // deleted. Read under the log's head, which a deletion holds while it
+      // renames the place, so the place is as it commits.
+      await lockLogHead(d.tx);
       const known = await store.places(
         d.tx,
-        onProjects.map((change) => change.projectId),
-        onProjects.flatMap((change) => (change.environmentId === null ? [] : [change.environmentId])),
+        changes.map((change) => change.projectId!),
+        changes.flatMap((change) => (change.environmentId === null ? [] : [change.environmentId])),
       );
-      for (const { projectId, environmentId, role } of onProjects) {
-        if (!known.projects.has(projectId) || (environmentId !== null && known.environments.get(environmentId) !== projectId)) {
+      const where: Place[] = changes.map(({ projectId, environmentId, role }) => {
+        const environment = environmentId === null ? undefined : known.environments.get(environmentId);
+        if (!known.projects.has(projectId!) || (environmentId !== null && environment?.projectId !== projectId)) {
           throw refused('invalid', `no such place: ${environmentId === null ? projectId : `${projectId}/${environmentId}`}`);
         }
         // A grant there is refused; a revocation, as a deletion makes, is not.
-        if (role !== null && (known.deleted.has(projectId) || (environmentId !== null && known.deleted.has(environmentId)))) {
+        if (role !== null && (known.deleted.has(projectId!) || (environmentId !== null && known.deleted.has(environmentId)))) {
           throw refused('deleted');
         }
-      }
-      const acting = await this.#standing(d.tx, actor, d.members.get(actor), d.at, d.reports);
+        // An environment by its slug as the store has it, which scopes match.
+        return environmentId === null ? { projectId: projectId! } : { projectId: projectId!, environmentId, environmentSlug: environment!.slug };
+      });
+      const acting = through(await this.#standing(d.tx, actor, d.members.get(actor), d.at, d.reports), input);
       if (acting.status === 'tampered') throw refused('tampered');
-      if (!changes.every((change) => mayManageAccess(acting.live, change))) throw refused('not_allowed');
+      // Where they manage access, anything; otherwise only a person to a service account (`givesService`).
+      const manages = where.every((place) => mayManageAccess(acting.live, place));
+      if (!manages && !(SERVICE.test(principal) && PERSON.test(actor))) throw refused('not_allowed');
+      // Managing access never reads a value: nobody gives themselves a role, though they may give one up.
+      if (actor === principal && !acting.live.isRootAdmin && changes.some((change) => change.role !== null)) {
+        throw refused('not_allowed', 'nobody grants themselves a role: ask another admin');
+      }
 
       const row = d.members.get(principal);
       const subject = await this.#standing(d.tx, principal, row, d.at, d.reports);
       if (subject.status === 'tampered') throw refused('tampered', TAMPERED_SUBJECT);
       if (row?.status === 'removed') throw refused('removed');
       if (row === undefined) throw refused('not_a_member');
+      if (!manages) {
+        // The setting as of the log's head, which a change to it takes too.
+        const setting = (await this.#settingsAt(d.tx, d.reports)).serviceAccounts;
+        const account = await this.#account(d.tx, subject, row);
+        // Each place's new role they must hold, and what it held before: taking a grant away is changing it.
+        const gives = changes.every((change, i) => {
+          const before = subject.live.grants.find((grant) => placeKey({ ...grant, environmentSlug: null }) === placeKey(change));
+          return [change.role, before?.role].every((role) => role == null || givesService(acting.live, setting, role, where[i]));
+        });
+        if (!gives || !managesService(acting.live, setting, actor, account)) throw refused('not_allowed', NOT_THEIRS);
+      }
       // The grants the check verified, not a second read: what the decision changes, and seals.
       const held = subject.stored;
       d.grants.set(principal, [...held]);
@@ -1376,7 +1556,7 @@ class VaultService implements Vault {
     actor: string,
     principal: string,
     held: readonly GrantRow[],
-    change: GrantChange & GrantPlace,
+    change: GrantChange & store.Place,
     correlation: Correlation,
   ): AccessChange {
     const existing = held.find((grant) => placeKey(grant) === placeKey(change));
@@ -1421,40 +1601,57 @@ class VaultService implements Vault {
     return current === undefined ? 'created' : 'updated';
   }
 
-  admit(input: AdmitInput): Promise<Outcome<{ created: boolean; owner: boolean; generation: number }>> {
+  admit(input: AdmitInput): Promise<Outcome<{ created: boolean; role: InstanceRole; scope: Scope; generation: number }>> {
     const { actor, principal } = input;
+    const asked = input.role === undefined ? {} : { role: input.role, scope: input.scope ?? EVERYWHERE };
     const refused = (code: RefusalCode, message = MESSAGES[code]) =>
       new Refused(refusal(code, message), [
-        accessEntry(actor, 'member.add', principal, 'deny', input, { owner: input.owner ?? null }, code),
+        accessEntry(actor, 'member.add', principal, 'deny', input, asked, code),
       ]);
     return this.#decide([actor, principal], async (d) => {
       validateCorrelation(input);
-      const acting = await this.#standing(d.tx, actor, d.members.get(actor), d.at, d.reports);
+      const acting = through(await this.#standing(d.tx, actor, d.members.get(actor), d.at, d.reports), input);
       if (acting.status === 'tampered') throw refused('tampered');
-      if (!acting.live.isOwner) throw refused('not_allowed', 'only owners may add or restore members');
+      if (!runsInstance(acting.live)) {
+        // A service account, with no grant yet, any person who could give it one sets up (`setsUpServices`).
+        const service = SERVICE.test(principal) && (input.role ?? 'member') === 'member' && input.scope === undefined;
+        const setting = (await this.#settingsAt(d.tx, d.reports)).serviceAccounts;
+        if (!service || !PERSON.test(actor) || !setsUpServices(acting.live, setting, placesOf(await store.liveProjects(d.tx)))) {
+          throw refused('not_allowed', 'only admins and owners of the whole instance may add people or set their roles, and a service account takes access somewhere the instance lets people set one up');
+        }
+        // One removed they bring back only if they removed it themselves, never one someone else took away.
+        const removed = d.members.get(principal);
+        if (removed?.status === 'removed' && removed.statusChangedBy !== actor) {
+          throw refused('not_allowed', `${shownMember(removed.statusChangedBy)} removed this service account: only they, or someone who runs the whole instance, may bring it back`);
+        }
+      }
       if (!PRINCIPAL.test(principal)) throw refused('invalid', `not a member: ${shownMember(principal)}`);
       if (this.#isRootAdmin(principal)) throw refused('root_admin');
-      if (input.owner === true && !principal.startsWith('user:')) {
-        throw refused('invalid', 'service accounts cannot be owners');
+      if (input.role !== undefined && !isInstanceRole(input.role)) throw refused('invalid', `no such instance role: ${input.role}`);
+      if (input.scope !== undefined && (input.role === undefined || !isScope(input.scope))) throw refused('invalid', 'a scope is a role\'s: { projects, environments }, each all, only or except');
+      const wanted = input.role === undefined ? undefined : { role: input.role, scope: input.role === 'member' ? EVERYWHERE : normalScope(input.scope ?? EVERYWHERE) };
+      if (wanted !== undefined && wanted.role !== 'member' && !principal.startsWith('user:')) {
+        throw refused('invalid', 'service accounts hold project grants only, never an instance role');
       }
       const row = d.members.get(principal);
       const subject = await this.#standing(d.tx, principal, row, d.at, d.reports);
       if (subject.status === 'tampered') throw refused('tampered', TAMPERED_SUBJECT);
       d.touched.add(principal);
       d.grants.set(principal, [...subject.stored]);
-      const entry = (action: string, owner: boolean) =>
-        d.log.push(accessEntry(actor, action, principal, 'allow', input, { owner }));
+      const entry = (action: string, detail: Record<string, unknown>) =>
+        d.log.push(accessEntry(actor, action, principal, 'allow', input, detail));
 
       if (row === undefined || row.status === 'removed') {
-        // Coming back is a fresh start: no owner role unless given again.
-        const owner = input.owner ?? false;
-        entry(row === undefined ? 'member.add' : 'member.restore', owner);
+        // Coming back is a fresh start: a member, unless given a role again.
+        const { role, scope } = wanted ?? { role: 'member' as const, scope: EVERYWHERE };
+        entry(row === undefined ? 'member.add' : 'member.restore', { role, scope });
         d.writes.push(async (at) => {
           if (row === undefined) {
             await store.insertMember(d.tx, {
               principal,
               status: 'active',
-              owner,
+              role,
+              scope,
               generation: 0,
               createdAt: at,
               createdBy: actor,
@@ -1463,18 +1660,21 @@ class VaultService implements Vault {
               ...UNSEALED,
             });
           } else {
-            await store.updateMember(d.tx, principal, { status: 'active', owner, statusChangedAt: at, statusChangedBy: actor });
+            await store.updateMember(d.tx, principal, { status: 'active', role, scope, statusChangedAt: at, statusChangedBy: actor });
           }
         });
         // A removal moved the generation on already; coming back keeps it.
-        return { created: true, owner, generation: row?.generation ?? 0 };
+        return { created: true, role, scope, generation: row?.generation ?? 0 };
       }
-      const owner = input.owner ?? row.owner;
-      if (owner !== row.owner) {
-        entry('member.owner', owner);
-        d.writes.push(() => store.updateMember(d.tx, principal, { owner }));
+      const changed = wanted !== undefined && JSON.stringify(standing(wanted)) !== JSON.stringify(standing(row));
+      // Nobody sets their own role: running the instance never lets anyone widen what they hold themselves.
+      if (changed && actor === principal) throw refused('not_allowed', 'nobody changes their own instance role: ask another admin');
+      if (changed) {
+        entry('member.role', { role: wanted.role, scope: wanted.scope, previousRole: row.role, previousScope: row.scope });
+        d.writes.push(() => store.updateMember(d.tx, principal, { role: wanted.role, scope: wanted.scope }));
+        return { created: false, ...wanted, generation: row.generation };
       }
-      return { created: false, owner, generation: row.generation };
+      return { created: false, role: row.role, scope: row.scope, generation: row.generation };
     });
   }
 
@@ -1487,16 +1687,21 @@ class VaultService implements Vault {
       if (!PRINCIPAL.test(principal)) throw refused('invalid', `not a member: ${shownMember(principal)}`);
       if (this.#isRootAdmin(principal)) throw refused('root_admin');
       const row = d.members.get(principal);
-      const acting = await this.#standing(d.tx, actor, d.members.get(actor), d.at, d.reports);
+      const acting = through(await this.#standing(d.tx, actor, d.members.get(actor), d.at, d.reports), input);
       if (acting.status === 'tampered') throw refused('tampered');
       const holder = acting.live;
       const subject = await this.#standing(d.tx, principal, row, d.at, d.reports);
       const held = subject.stored;
       if (subject.status === 'tampered') {
-        if (!holder.isOwner) throw refused('not_allowed', 'only owners may remove a member whose record failed its check');
+        if (!runsInstance(holder)) throw refused('not_allowed', 'only admins and owners of the whole instance may remove a member whose record failed its check');
         return this.#startOver(d, actor, principal, row, subject.fault!, input, refused);
       }
-      if (!holder.isOwner) throw refused('not_allowed', 'only owners may remove members');
+      if (!runsInstance(holder)) {
+        // A service account its manager removes: they reach everything it holds (`managesService`).
+        const theirs = SERVICE.test(principal) && PERSON.test(actor) && row?.status === 'active' &&
+          managesService(holder, (await this.#settingsAt(d.tx, d.reports)).serviceAccounts, actor, await this.#account(d.tx, subject, row));
+        if (!theirs) throw refused('not_allowed', 'only admins and owners of the whole instance may remove members, and a service account whoever manages it');
+      }
       if (row?.status !== 'active') throw refused(row === undefined ? 'not_a_member' : 'removed');
 
       const revoked = held.filter((grant) => live(grant, d.at));
@@ -1520,7 +1725,8 @@ class VaultService implements Vault {
         d.grants.set(principal, []);
         await store.updateMember(d.tx, principal, {
           status: 'removed',
-          owner: false,
+          role: 'member',
+          scope: EVERYWHERE,
           generation,
           statusChangedAt: at,
           statusChangedBy: actor,
@@ -1530,6 +1736,79 @@ class VaultService implements Vault {
     });
   }
 
+  /**
+   * A service account as `managesService` weighs it: its live grants, each
+   * environment by its slug, which the setting's scope matches, and who
+   * admitted it, as its row says.
+   */
+  async #account(db: Queryable, subject: Standing, row: Member): Promise<ServiceAccount> {
+    const slugs = await store.environmentsById(db, subject.live.grants.flatMap((grant) => (grant.environmentId === null ? [] : [grant.environmentId])));
+    return {
+      grants: subject.live.grants.map((grant) => ({
+        role: grant.role,
+        place: grant.environmentId === null
+          ? { projectId: grant.projectId! }
+          : { projectId: grant.projectId!, environmentId: grant.environmentId, environmentSlug: slugs.get(grant.environmentId)?.slug ?? null },
+      })),
+      admittedBy: row.statusChangedBy,
+    };
+  }
+
+  // --- the instance's settings ------------------------------------------------
+
+  async settings(): Promise<Settings> {
+    await this.#settled();
+    const reports: NewEntry[] = [];
+    const settings = await this.#settingsAt(this.#db, reports);
+    await this.#record(reports);
+    return settings;
+  }
+
+  /**
+   * The settings the vault's newest `settings.change` says, by its MAC: one
+   * in its name it did not write is passed over, and reported. With such
+   * entries and none of its own within reach, the setting is closed, never
+   * the default: otherwise whoever can insert rows could open it again.
+   */
+  async #settingsAt(db: Queryable, reports: NewEntry[]): Promise<Settings> {
+    const entry = await newestAuthentic(
+      (before) => store.newestVaultEntries(db, SETTINGS, LOOK_BACK.page, before),
+      this.#check(reports, null),
+    );
+    if (entry === 'none') return DEFAULT_SETTINGS;
+    if (typeof entry === 'string') return CLOSED_SETTINGS;
+    const { serviceAccounts } = JSON.parse(entry.metadata) as { serviceAccounts?: unknown };
+    return isScope(serviceAccounts) ? { serviceAccounts } : CLOSED_SETTINGS;
+  }
+
+  setSettings(input: SetSettingsInput): Promise<Outcome<{ settings: Settings }>> {
+    const { actor } = input;
+    const entry = (decision: 'allow' | 'deny', detail: Record<string, unknown>, code: RefusalCode | null = null): NewEntry => ({
+      actor,
+      action: SETTINGS,
+      decision,
+      code,
+      operationId: input.operationId ?? null,
+      requestId: input.requestId ?? null,
+      metadata: JSON.stringify({ ...detail, ...traced(input) }),
+    });
+    const refused = (code: RefusalCode, message = MESSAGES[code]) =>
+      new Refused(refusal(code, message), [entry('deny', { serviceAccounts: input.settings?.serviceAccounts ?? null }, code)]);
+    return this.#decide([actor], async (d) => {
+      validateCorrelation(input);
+      const acting = through(await this.#standing(d.tx, actor, d.members.get(actor), d.at, d.reports), input);
+      if (acting.status === 'tampered') throw refused('tampered');
+      if (!runsInstance(acting.live)) throw refused('not_allowed', "only admins and owners of the whole instance change its settings");
+      if (!isScope(input.settings?.serviceAccounts)) throw refused('invalid', 'who sets up service accounts is a scope: { projects, environments }, each all, only or except');
+      // Under the log's head, so two changes at once each name the one before.
+      await lockLogHead(d.tx);
+      const previous = await this.#settingsAt(d.tx, d.reports);
+      const settings: Settings = { serviceAccounts: normalScope(input.settings.serviceAccounts) };
+      if (JSON.stringify(settings) !== JSON.stringify(previous)) d.log.push(entry('allow', { ...settings, previous }));
+      return { settings };
+    });
+  }
+
   /**
    * Remove a member whose row failed its check, from what the log says of
    * them rather than what the row does: their grants go, whatever they were,
@@ -1556,7 +1835,8 @@ class VaultService implements Vault {
       d.grants.set(principal, []);
       const fresh = {
         status: 'removed' as const,
-        owner: false,
+        role: 'member' as const,
+        scope: EVERYWHERE,
         generation,
         createdAt: logged.createdAt,
         createdBy: logged.createdBy,
@@ -2185,39 +2465,38 @@ function live(grant: GrantRow, at: number): boolean {
 
 /**
  * Where an entry about a grant says it is: its project and environment; or,
- * on every project, neither, and the place as a path in its payload. Only a
- * grant that names no place at all is on every project (`grantKind`).
+ * for a grant on every project of 0.4, neither, and the place as a path in
+ * its payload, `*`, or `*` and the slug, as 0.4 wrote it.
  */
-function located(place: GrantPlace): { ids: Pick<NewEntry, 'projectId' | 'environmentId'>; detail: { place?: string } } {
-  return grantKind(place) === 'every-project'
-    ? { ids: {}, detail: { place: everyProjectPath(place.environmentSlug) } }
+function located(place: store.Place): { ids: Pick<NewEntry, 'projectId' | 'environmentId'>; detail: { place?: string } } {
+  return place.projectId === null && place.environmentId === null
+    ? { ids: {}, detail: { place: place.environmentSlug === null ? '*' : `*/${place.environmentSlug}` } }
     : { ids: { projectId: place.projectId, environmentId: place.environmentId }, detail: {} };
 }
 
-/** One key per place a member can hold a grant at, by what the grant names first: its environment, its project, or neither. */
-function placeKey(place: GrantPlace): string {
-  if (place.environmentId !== null) return `environment:${place.environmentId}`;
-  return place.projectId !== null ? `project:${place.projectId}` : everyProjectPath(place.environmentSlug);
+/** One key per place a member can hold a grant at, by what the grant names first: its environment, its project, or neither, on every project of 0.4. */
+/** Every project there is now and each of its environments, as a permission check names them. */
+function placesOf(projects: readonly { id: string; environments: readonly { id: string; slug: string }[] }[]): Place[] {
+  return projects.flatMap((project) => [
+    { projectId: project.id },
+    ...project.environments.map((environment) => ({ projectId: project.id, environmentId: environment.id, environmentSlug: environment.slug })),
+  ]);
 }
 
-/** Why a change's place is not one a grant can be at, or null when it is. */
-function placeShape(place: GrantPlace): string | null {
-  const kind = grantKind(place);
-  if (kind === null) return place.projectId === null ? 'an environment is named in its project' : 'a slug names environments on every project, not in one';
-  if (kind === 'every-project' && place.environmentSlug !== null && !SLUG.test(place.environmentSlug)) {
-    return `not an environment slug: ${place.environmentSlug}`;
-  }
-  return null;
+function placeKey(place: store.Place): string {
+  if (place.environmentId !== null) return `environment:${place.environmentId}`;
+  return place.projectId !== null ? `project:${place.projectId}` : `every-project:${place.environmentSlug ?? ''}`;
 }
 
-/** An environment's slug, as the schema has it. */
-const SLUG = /^[a-z0-9][a-z0-9-]{0,62}$/;
+/** A member's instance role, as their row has it: service accounts are members, whatever a row says. */
+function roleOf(principal: string, row: Member): { role: InstanceRole; scope: Scope } {
+  return principal.startsWith('user:') ? { role: row.role, scope: row.scope } : { role: 'member', scope: EVERYWHERE };
+}
 
 function view(grant: GrantRow): Grant {
   return {
     projectId: grant.projectId,
     environmentId: grant.environmentId,
-    environmentSlug: grant.environmentSlug,
     role: grant.role as Role,
     expiresAt: grant.expiresAt === null ? null : iso(grant.expiresAt),
     grantedAt: iso(grant.grantedAt),