@coffre/vault 0.2.0 → 0.4.0

package/src/vault.ts

@@ -3,14 +3,19 @@ import { randomUUID, timingSafeEqual } from 'node:crypto';
 import {
   allows,
   assignableToEnvironment,
+  everyProjectPath,
+  grantKind,
   isRole,
   mayManageAccess,
+  type GrantPlace,
   type Holdings,
   type Permission,
+  type Place,
   type Role,
 } from '@coffre/core/access';
 import { GENESIS_HASH, verifyEntries, type LogKey, type StoredEntry } from '@coffre/core/audit';
 import { checkContext, type SecretContext } from '@coffre/core/envelope';
+import { shownMember } from '@coffre/core/schemas';
 import {
   DEK_BYTES,
   KEY_CHECK,
@@ -34,12 +39,14 @@ import {
   type AdmitInput,
   type Checkpoint,
   type CheckpointKey,
+  type EndReferencesInput,
   type Grant,
   type GrantChange,
   type KeyChecks,
   type LogHead,
   type LogVerification,
   type Outcome,
+  type ReferenceInput,
   type Refusal,
   type RefusalCode,
   type RemoveInput,
@@ -48,6 +55,7 @@ import {
   type SetAccessInput,
   type UnwrapInput,
   type Vault,
+  type Via,
   type VerifyLogInput,
   type WrapInput,
   type WrappedKey,
@@ -148,9 +156,8 @@ const KEY_BUDGET_MS = 5_000;
 /** How long a decision waits for a lock: above the key budget, so a removal outwaits a read in flight. */
 const LOCK_TIMEOUT_MS = 15_000;
 
-// Historical principals remain valid audit subjects and sealed rows.
-const PRINCIPAL = /^(user|token|sync):[^\s:][^\s]*$/;
-const LIVE_PRINCIPAL = /^(user|token):[^\s:][^\s]*$/;
+/** A member: `user:<email>` or `token:<name>`. */
+const PRINCIPAL = /^(user|token):[^\s:][^\s]*$/;
 
 /** Who acts for the vault itself, as when it gives a root admin a member row. */
 const VAULT_ACTOR = 'system:vault';
@@ -225,6 +232,8 @@ const MESSAGES: Record<RefusalCode, string> = {
   expired: 'the grant that covered this has expired',
   bulk_limit: 'too many secrets read in too short a time',
   bad_claim: 'the key does not belong to this secret',
+  deleted: 'this project or environment was deleted',
+  ended: 'the reference read through was ended',
   not_allowed: 'not allowed to change this',
   root_admin: 'root admins are set in the vault configuration',
   invalid: 'not something the rules allow',
@@ -259,6 +268,13 @@ type Decision = {
   reports: NewEntry[];
   /** Run once the entries are appended, with the seq each was given. */
   after: ((seqOf: (entry: NewEntry) => number) => void)[];
+  /**
+   * Checks made again once the log's head is locked, just before this
+   * decision's entries append: what another decision could have changed
+   * since it checked, such as a reference ended while a read through it
+   * was deciding. A `Refused` there refuses the decision.
+   */
+  underLock: ((locked: Queryable) => Promise<void>)[];
 };
 
 /** The actions of the entries the vault writes about keys. */
@@ -348,7 +364,7 @@ class VaultService implements Vault {
         await store.boundLockWaits(tx, LOCK_TIMEOUT_MS);
         const members = principals.length === 0 ? new Map<string, Member>() : await store.lockMembers(tx, principals);
         const d: Decision = {
-          tx, members, at: await this.#now(tx), log: [], writes: [], touched: new Set(), grants: new Map(), reports, after: [],
+          tx, members, at: await this.#now(tx), log: [], writes: [], touched: new Set(), grants: new Map(), reports, after: [], underLock: [],
         };
         const result = await decide(d);
         const entries = [...reports, ...d.log];
@@ -356,7 +372,7 @@ class VaultService implements Vault {
         // Each member's newest access entry, which their row names (rows.ts).
         const accessSeq = new Map<string, bigint>();
         if (entries.length > 0) {
-          const appended = await this.#append(tx, entries);
+          const appended = await this.#append(tx, entries, d.underLock);
           at = appended.occurredAt;
           entries.forEach((entry, i) => {
             if (isAccessEntry(entry)) accessSeq.set(entry.subjectPrincipal!, appended.seqStart + BigInt(i));
@@ -585,13 +601,15 @@ class VaultService implements Vault {
    * that an instance still running with the replaced KEK, as during a
    * deploy, cannot write after the rotation.
    */
-  #append(tx: Transaction, entries: readonly NewEntry[]): Promise<Appended> {
+  #append(tx: Transaction, entries: readonly NewEntry[], underLock: readonly ((locked: Queryable) => Promise<void>)[] = []): Promise<Appended> {
     const prepared = this.#prepared;
     return appendEntries(tx, prepared.logKey, entries, async (locked) => {
       const rotation = await store.latestVaultEntry(locked, [KEY_ROTATE]);
-      if (rotation === undefined || prepared.logKeys.some((key) => key.keyId === rotation.keyId)) return;
-      prepared.superseded = `the log moved on to ${rotation.keyId}, a key this vault does not hold: a vault given a newer vault key replaced it, and a replaced key writes nothing more`;
-      throw new Error(prepared.superseded);
+      if (rotation !== undefined && !prepared.logKeys.some((key) => key.keyId === rotation.keyId)) {
+        prepared.superseded = `the log moved on to ${rotation.keyId}, a key this vault does not hold: a vault given a newer vault key replaced it, and a replaced key writes nothing more`;
+        throw new Error(prepared.superseded);
+      }
+      for (const check of underLock) await check(locked);
     });
   }
 
@@ -602,18 +620,44 @@ class VaultService implements Vault {
   async unwrap(input: UnwrapInput): Promise<Outcome<{ keys: string[] }>> {
     const { principal } = input;
     validateText(input.purpose);
+    const vias = input.items.map((item) => validateVia(item.via));
     const loaded = await this.#versions(input, 'secret.read', { purpose: input.purpose });
     if (!loaded.ok) return loaded;
-    const items = loaded.versions;
+    // RPC can preserve shared objects, and two holders can read one source: each item its own secret.
+    const items = loaded.versions.map((version) => ({ ...version, secret: { ...version.secret } }));
     validateItems(items, 'wrapped');
+    const sealed = await this.#referencesAt(vias);
     const versionIds = new Map(items.map((item) => [item.secret, item.id]));
-    const entry = (secret: SecretRef, decision: 'allow' | 'deny', code: string | null): NewEntry => ({
-      ...keyEntry('secret.read', principal, secret, decision, code, input, { purpose: input.purpose }),
-      secretVersionId: versionIds.get(secret),
-    });
+    const viaOf = new Map(items.map((item, i) => [item.secret, { via: vias[i], sealed: sealed[i] }]));
+    const entry = (secret: SecretRef, decision: 'allow' | 'deny', code: string | null): NewEntry => {
+      const { via, sealed: seal } = viaOf.get(secret)!;
+      return {
+        ...keyEntry('secret.read', principal, secret, decision, code, input, { purpose: input.purpose, ...(via === null ? {} : viaDetail(via, seal)) }),
+        secretVersionId: versionIds.get(secret),
+      };
+    };
+    // A reference reads only the current version of the source its entry names.
+    if (items.some((item, i) => vias[i] !== null && (sealed[i] === null || sealed[i]!.source.secretId !== item.secret.secretId || !item.current))) {
+      return this.#refuseVersions(principal, 'bad_claim', items.map((item) => entry(item.secret, 'deny', 'bad_claim')));
+    }
+    const ends = sealed.flatMap((seal) => (seal === null ? [] : [seal.seq]));
     const remote = items.some(({ wrapped }) => this.#remote(this.#config.keks.providerOf(wrapped)));
     return this.#keys(
-      { action: 'secret.read', principal, permission: 'secret.read', secrets: items.map((item) => item.secret), remote, entry, input },
+      {
+        action: 'secret.read',
+        principal,
+        permission: 'secret.read',
+        secrets: items.map((item) => item.secret),
+        // Through a reference, the reader's grants on the holder's environment decide.
+        places: sealed.map((seal, i) => seal?.holder ?? items[i]!.secret),
+        vet: ends.length === 0 ? undefined : async (db) => {
+          const ended = await store.endedReferences(db, ends);
+          return sealed.map((seal) => (seal !== null && ended.has(seal.seq) ? 'ended' : null));
+        },
+        remote,
+        entry,
+        input,
+      },
       () =>
         items.map(({ secret, wrapped }) => async (operation: KeyOperation) => {
           const key = await this.#open(wrapped, secret, operation);
@@ -671,7 +715,7 @@ class VaultService implements Vault {
     const sameSecret = (secret: SecretRef, source: SecretRef) =>
       secret.projectId === source.projectId && secret.environmentId === source.environmentId && secret.secretId === source.secretId;
     if (items.some((item, i) => !sameSecret(item.secret, loaded.versions[i].secret))) {
-      return this.#badVersions(principal, loaded.versions.map((source) => ({
+      return this.#refuseVersions(principal, 'bad_claim', loaded.versions.map((source) => ({
         ...keyEntry('key.rewrap', principal, source.secret, 'deny', 'bad_claim', input), secretVersionId: source.id,
       })));
     }
@@ -698,7 +742,7 @@ class VaultService implements Vault {
     );
   }
 
-  /** Immutable versions need no lock; their ids determine the whole batch before any key call. */
+  /** Versions need no lock: they change only by being erased, once their place is archived, and their ids determine the whole batch before any key call. */
   async #versions(
     input: Correlation & { principal: string; items: { secretVersionId: string }[] },
     action: KeyAction,
@@ -713,8 +757,13 @@ class VaultService implements Vault {
       }
     }
     const found = new Map((await store.versions(this.#db, ids)).map((version) => [version.id, version]));
+    if ([...found.values()].some((version) => version.deleted)) {
+      return this.#refuseVersions(input.principal, 'deleted', [...found.values()].map((version) => ({
+        ...keyEntry(action, input.principal, version.secret, 'deny', 'deleted', input, detail), secretVersionId: version.id,
+      })));
+    }
     if (ids.some((id) => !found.has(id))) {
-      return this.#badVersions(input.principal, ids.map((id) => {
+      return this.#refuseVersions(input.principal, 'bad_claim', ids.map((id) => {
         const version = found.get(id);
         if (version === undefined) return {
           actor: input.principal, action, decision: 'deny', code: 'bad_claim',
@@ -727,10 +776,10 @@ class VaultService implements Vault {
     return { ok: true, versions: ids.map((id) => found.get(id)!) };
   }
 
-  async #badVersions(principal: string, entries: NewEntry[]): Promise<Outcome<never>> {
+  async #refuseVersions(principal: string, code: 'bad_claim' | 'deleted', entries: NewEntry[]): Promise<Outcome<never>> {
     if (this.#isRootAdmin(principal)) await this.#rootRow(principal);
     return this.#decide([principal], async () => {
-      throw new Refused(refusal('bad_claim', MESSAGES.bad_claim), entries);
+      throw new Refused(refusal(code, MESSAGES[code]), entries);
     });
   }
 
@@ -766,6 +815,13 @@ class VaultService implements Vault {
       principal: string;
       permission: Permission;
       secrets: readonly SecretRef[];
+      /** Where each secret's permission is checked, when not where it is: a reference's holder. */
+      places?: readonly SecretPlace[];
+      /**
+       * What else refuses each secret, checked in the decision and again
+       * once the log's head is locked, before its entries append.
+       */
+      vet?: (db: Queryable) => Promise<(RefusalCode | null)[]>;
       remote: boolean;
       entry: (secret: SecretRef, decision: 'allow' | 'deny', code: string | null) => NewEntry;
       input: Correlation & { purpose?: string };
@@ -785,7 +841,17 @@ 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 codes = secrets.map((secret) => refuses(reader, call.permission, secret));
+      // 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.
+      const at = secrets.map((secret, i) => call.places?.[i] ?? secret);
+      const environments = await store.environmentsById(d.tx, [...secrets, ...at].map((place) => place.environmentId));
+      const gone = (place: SecretPlace) => environments.get(place.environmentId)?.deleted ?? false;
+      const codes: (RefusalCode | null)[] = secrets.map((secret, i) =>
+        refuses(reader, call.permission, placeIn(at[i]!, environments), gone(secret) || gone(at[i]!)));
+      if (call.vet !== undefined && !codes.some((code) => code !== null)) {
+        (await call.vet(d.tx)).forEach((code, i) => (codes[i] = code));
+      }
       let first = codes.find((code) => code !== null) ?? null;
       if (first === null && action === 'secret.read' && (await this.#overBulkLimit(d, principal, secrets.length))) first = 'bulk_limit';
       if (first !== null) {
@@ -849,6 +915,16 @@ class VaultService implements Vault {
         }
         throw error;
       }
+      // A reference ended while this decided refuses it, rather than a read logged after its end.
+      const { vet } = call;
+      if (vet !== undefined) {
+        d.underLock.push(async (locked) => {
+          const codes = await vet(locked);
+          const first = codes.find((code) => code !== null);
+          if (first === undefined || first === null) return;
+          throw new Refused(refusal(first, MESSAGES[first]), secrets.map((secret, item) => outcomeEntry(secret, item, 'deny', codes[item] ?? first)));
+        });
+      }
       const { outcomes, expired } = await settle(operations(), this.#prepared.options.keyBudgetMs);
       const done = outcomes.flatMap((outcome) => (outcome.ok ? [outcome.value] : []));
       try {
@@ -868,6 +944,16 @@ class VaultService implements Vault {
         if (done.length < outcomes.length) {
           throw new Refused(refusal('bad_claim', MESSAGES.bad_claim), entries());
         }
+        // Again under the log's head, the append's, taken a statement early: a
+        // deletion renames its place under it, so one that committed since the
+        // check above is seen here, and nothing is released after it.
+        // A read through a reference: its holder's place too, which a deletion may have taken.
+        await lockLogHead(d.tx);
+        const places = secrets.flatMap((secret, i) => [secret, call.places?.[i] ?? secret]);
+        const now = await store.environmentsById(d.tx, places.map((place) => place.environmentId));
+        if (places.some((place) => now.get(place.environmentId)?.deleted ?? false)) {
+          throw new Refused(refusal('deleted', MESSAGES.deleted), secrets.map((secret, i) => outcomeEntry(secret, i, 'deny', 'deleted')));
+        }
         const released = secrets.map((secret, i) => outcomeEntry(secret, i, 'allow', null));
         d.log.push(...released);
         const answer = result(done);
@@ -886,6 +972,184 @@ class VaultService implements Vault {
     return (await store.releasesSince(d.tx, principal, d.at - windowMs)) + n > count;
   }
 
+  // --- references ---------------------------------------------------------------
+
+  /**
+   * Make each holder a reference to its source: the actor writes the holder
+   * and reads the source, by their own grants, and the vault's
+   * `reference.create` entry is the reference. The app's row only points at
+   * it; a read through one is checked against the entry (`#referencesAt`).
+   */
+  async reference(input: ReferenceInput): Promise<Outcome<{ seqs: number[] }>> {
+    const { principal, items } = input;
+    validateText(principal);
+    validateCorrelation(input);
+    for (const item of items) {
+      if (typeof item.id !== 'string' || !UUID.test(item.id)) throw new Error('a reference id must be a lowercase UUID');
+      if (typeof item.source?.secretId !== 'string' || !UUID.test(item.source.secretId)) throw new Error('a source must be named by its secret id');
+      checkContext(item.holder);
+      validateText(item.holder.path);
+    }
+    if (new Set(items.map((item) => item.id)).size !== items.length) throw new Error('each reference needs its own id');
+    if (items.length === 0) return { ok: true, seqs: [] };
+    const [sources, projectOf] = await Promise.all([
+      store.secretsByIds(this.#db, items.map((item) => item.source.secretId)),
+      store.projectsOfEnvironments(this.#db, items.map((item) => item.holder.environmentId)),
+    ]);
+    const entry = (item: ReferenceInput['items'][number], decision: 'allow' | 'deny', code: string | null): NewEntry => {
+      const source = sources.get(item.source.secretId);
+      return {
+        actor: principal,
+        action: 'reference.create',
+        decision,
+        code,
+        projectId: projectOf.has(item.holder.environmentId) ? item.holder.projectId : null,
+        environmentId: projectOf.has(item.holder.environmentId) ? item.holder.environmentId : null,
+        operationId: input.operationId ?? null,
+        requestId: input.requestId ?? null,
+        // A new holder's row is not committed yet: it is named here, as a wrap names its secret.
+        metadata: JSON.stringify({
+          reference: item.id,
+          subject: item.holder.path,
+          secretId: item.holder.secretId,
+          source: source === undefined ? { secretId: item.source.secretId } : { path: source.path },
+          ...(source === undefined ? {} : { also: { projectId: source.projectId, environmentId: source.environmentId, secretId: source.secretId } }),
+          ...traced(input),
+        }),
+      };
+    };
+    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);
+      // 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);
+        return source === undefined ? [item.holder.environmentId] : [item.holder.environmentId, source.environmentId];
+      }));
+      const gone = (place: SecretPlace) => environments.get(place.environmentId)?.deleted ?? false;
+      const codes = items.map((item): RefusalCode | null => {
+        const source = sources.get(item.source.secretId);
+        if (source === undefined || projectOf.get(item.holder.environmentId) !== item.holder.projectId) return 'bad_claim';
+        if (source.secretId === item.holder.secretId) return 'invalid';
+        return refuses(reader, 'secret.write', placeIn(item.holder, environments), gone(item.holder))
+          ?? refuses(reader, 'secret.read', placeIn(source, environments), gone(source));
+      });
+      const first = codes.find((code) => code !== null) ?? null;
+      if (first !== null) throw new Refused(refusal(first, MESSAGES[first]), items.map((item, i) => entry(item, 'deny', codes[i] ?? first)));
+      // Again under the log's head, as a read is: neither side was deleted since the check above.
+      d.underLock.push(async (locked) => {
+        const now = await store.environmentsById(locked, [...environments.keys()]);
+        if (![...now.values()].some((environment) => environment.deleted)) return;
+        throw new Refused(refusal('deleted', MESSAGES.deleted), items.map((item) => entry(item, 'deny', 'deleted')));
+      });
+      const entries = items.map((item) => entry(item, 'allow', null));
+      d.log.push(...entries);
+      const answer = { seqs: [] as number[] };
+      d.after.push((seqOf) => (answer.seqs = entries.map(seqOf)));
+      return answer;
+    });
+  }
+
+  /**
+   * End references, each with a `reference.end` naming its creation by
+   * `related_seq`, where the next read through it looks. `replaced` takes
+   * write on the holder; `broken`, write on the holder or managing the
+   * source's project's access. Ending one already ended is refused.
+   */
+  async endReferences(input: EndReferencesInput): Promise<Outcome<{ seqs: number[] }>> {
+    const { principal, reason } = input;
+    validateText(principal);
+    validateCorrelation(input);
+    if (reason !== 'replaced' && reason !== 'broken' && reason !== 'abandoned') throw new Error('a reference ends replaced, broken or abandoned');
+    const vias = input.items.map((item) => validateVia(item)!);
+    if (vias.some((via) => via === null) || new Set(vias.map((via) => via.seq)).size !== vias.length) throw new Error('each reference to end, once');
+    if (vias.length === 0) return { ok: true, seqs: [] };
+    const sealed = await this.#referencesAt(vias);
+    // A holder's row is committed after its reference is sealed, if the write went through: an end names it only then.
+    const holders = await store.secretsByIds(this.#db, sealed.flatMap((seal) => (seal === null ? [] : [seal.holder.secretId])));
+    const entry = (via: Via, seal: Sealed | null, decision: 'allow' | 'deny', code: string | null): NewEntry => ({
+      actor: principal,
+      action: 'reference.end',
+      decision,
+      code,
+      projectId: seal?.holder.projectId ?? null,
+      environmentId: seal?.holder.environmentId ?? null,
+      // So that the holder key's own log shows the reference ending.
+      secretId: seal !== null && holders.has(seal.holder.secretId) ? seal.holder.secretId : null,
+      relatedSeq: seal === null ? null : seal.seq,
+      operationId: input.operationId ?? null,
+      requestId: input.requestId ?? null,
+      metadata: JSON.stringify({
+        reference: via.reference,
+        reason,
+        ...(seal === null
+          ? { seq: via.seq }
+          : {
+              subject: seal.holder.path,
+              secretId: seal.holder.secretId,
+              source: { path: seal.source.path },
+              also: { projectId: seal.source.projectId, environmentId: seal.source.environmentId, secretId: seal.source.secretId },
+            }),
+        ...traced(input),
+      }),
+    });
+    if (this.#isRootAdmin(principal)) await this.#rootRow(principal);
+    if (sealed.some((seal) => seal === null)) {
+      return this.#decide([principal], async () => {
+        throw new Refused(refusal('bad_claim', MESSAGES.bad_claim), vias.map((via, i) => entry(via, sealed[i]!, 'deny', 'bad_claim')));
+      });
+    }
+    const seals = sealed as Sealed[];
+    const ended = async (db: Queryable) => {
+      const done = await store.endedReferences(db, seals.map((seal) => seal.seq));
+      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);
+      // 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) => {
+        const holder = refuses(actor, 'secret.write', placeIn(seal.holder, environments), false);
+        // Abandoning is its maker's alone, for a write of theirs that stored nothing: the vault
+        // never reads the app's rows, so whose seal it is decides, and no one else's end says it.
+        if (reason === 'abandoned' && seal.createdBy !== principal) return 'not_allowed';
+        // Replacing or abandoning is the holder's side: write where it is held.
+        if (holder === null || reason !== 'broken') return holder;
+        return refuses(actor, 'grant.manage', { projectId: seal.source.projectId }, false) === null ? null : holder;
+      });
+      if (!codes.some((code) => code !== null)) (await ended(d.tx)).forEach((code, i) => (codes[i] = code));
+      const first = codes.find((code) => code !== null) ?? null;
+      if (first !== null) throw new Refused(refusal(first, MESSAGES[first]), vias.map((via, i) => entry(via, seals[i]!, 'deny', codes[i] ?? first)));
+      // Two ends of one reference at once: the second finds the first under the head's lock.
+      d.underLock.push(async (locked) => {
+        if ((await ended(locked)).every((code) => code === null)) return;
+        throw new Refused(refusal('ended', MESSAGES.ended), vias.map((via, i) => entry(via, seals[i]!, 'deny', 'ended')));
+      });
+      const entries = vias.map((via, i) => entry(via, seals[i]!, 'allow', null));
+      d.log.push(...entries);
+      const answer = { seqs: [] as number[] };
+      d.after.push((seqOf) => (answer.seqs = entries.map(seqOf)));
+      return answer;
+    });
+  }
+
+  /**
+   * The reference each read names, as the vault's own `reference.create`
+   * entry at its seq says it is: an entry of the vault's, allowed, under its
+   * MAC, about that reference. Null for an item that names none, and for
+   * one that names something else: a row the vault never sealed.
+   */
+  async #referencesAt(vias: readonly (Via | null)[]): Promise<(Sealed | null)[]> {
+    const found = await store.entriesAt(this.#db, vias.flatMap((via) => (via === null ? [] : [BigInt(via.seq)])));
+    return vias.map((via) => {
+      if (via === null) return null;
+      const entry = found.get(BigInt(via.seq));
+      if (entry === undefined || entry.author !== 'vault' || entry.action !== 'reference.create' || entry.decision !== 'allow') return null;
+      if (!this.#authentic(entry)) return null;
+      return sealedReference(entry, via.reference);
+    });
+  }
+
   // --- who holds what -----------------------------------------------------------
 
   #isRootAdmin(principal: string): boolean {
@@ -951,7 +1215,7 @@ class VaultService implements Vault {
     const grants = row === undefined ? [] : await store.grants(db, principal);
     const fault = await this.#integrity(db, principal, row, grants, reports);
     if (fault !== null) return { principal, status: 'tampered', live: none, all: none, fault, stored: grants };
-    if (!LIVE_PRINCIPAL.test(principal)) return { principal, status: 'unknown', live: none, all: none, fault, stored: grants };
+    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:');
@@ -969,10 +1233,10 @@ class VaultService implements Vault {
     if (this.#isRootAdmin(principal)) {
       return { principal, status: 'active', generation: row?.generation ?? 0, isRootAdmin: true, isOwner: true, grants: [], since: null, by: null };
     }
-    const active = LIVE_PRINCIPAL.test(principal) && !tampered && row?.status === 'active';
+    const active = PRINCIPAL.test(principal) && !tampered && row?.status === 'active';
     return {
       principal,
-      status: tampered ? 'tampered' : !LIVE_PRINCIPAL.test(principal) ? 'unknown' : (row?.status ?? 'unknown'),
+      status: tampered ? 'tampered' : !PRINCIPAL.test(principal) ? 'unknown' : (row?.status ?? 'unknown'),
       generation: row?.generation ?? 0,
       isRootAdmin: false,
       isOwner: active && row.owner && principal.startsWith('user:'),
@@ -1038,45 +1302,59 @@ class VaultService implements Vault {
 
   setAccess(input: SetAccessInput): Promise<Outcome<{ changes: AccessChange[] }>> {
     const { actor, principal } = input;
-    const action = input.changes.every((change) => change.role === null) ? 'access.revoke' : 'access.grant';
+    const changes = input.changes.map((change) => ({ ...change, environmentSlug: change.environmentSlug ?? null }));
+    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] = input.changes.length === 1 ? input.changes : [];
-    const refused = (code: RefusalCode, message = MESSAGES[code]) =>
-      new Refused(refusal(code, message), [{
-        ...accessEntry(actor, action, principal, 'deny', input, { changes: input.changes }, code),
-        ...(only === undefined || code === 'invalid' ? {} : { projectId: only.projectId, environmentId: only.environmentId }),
+    const [only] = changes.length === 1 ? changes : [];
+    const refused = (code: RefusalCode, message = MESSAGES[code]) => {
+      const where = only === undefined || code === 'invalid' ? { ids: {}, detail: {} } : located(only);
+      return new Refused(refusal(code, message), [{
+        ...accessEntry(actor, action, principal, 'deny', input, { changes: input.changes, ...where.detail }, code),
+        ...where.ids,
       }]);
+    };
+    const onProjects = changes.flatMap(({ projectId, environmentId, role }) => (projectId === null ? [] : [{ projectId, environmentId, role }]));
     return this.#decide([actor, principal], async (d) => {
       validateCorrelation(input);
-      if (!LIVE_PRINCIPAL.test(principal)) throw refused('invalid', `not a principal: ${principal}`);
+      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 input.changes) {
-        const key = `${change.projectId}/${change.environmentId ?? ''}`;
+      for (const change of changes) {
+        const shape = placeShape(change);
+        if (shape !== null) throw refused('invalid', shape);
+        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 && !assignableToEnvironment(change.role)) {
-          throw refused('invalid', `${change.role} can only be granted on a project`);
+        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`);
         }
         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);
       const known = await store.places(
         d.tx,
-        input.changes.map((change) => change.projectId),
-        input.changes.flatMap((change) => (change.environmentId === null ? [] : [change.environmentId])),
+        onProjects.map((change) => change.projectId),
+        onProjects.flatMap((change) => (change.environmentId === null ? [] : [change.environmentId])),
       );
-      for (const { projectId, environmentId } of input.changes) {
+      for (const { projectId, environmentId, role } of onProjects) {
         if (!known.projects.has(projectId) || (environmentId !== null && known.environments.get(environmentId) !== 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)))) {
+          throw refused('deleted');
+        }
       }
       const acting = await this.#standing(d.tx, actor, d.members.get(actor), d.at, d.reports);
       if (acting.status === 'tampered') throw refused('tampered');
-      if (!input.changes.every((change) => mayManageAccess(acting.live, change))) throw refused('not_allowed');
+      if (!changes.every((change) => mayManageAccess(acting.live, change))) throw refused('not_allowed');
 
       const row = d.members.get(principal);
       const subject = await this.#standing(d.tx, principal, row, d.at, d.reports);
@@ -1086,9 +1364,9 @@ class VaultService implements Vault {
       // The grants the check verified, not a second read: what the decision changes, and seals.
       const held = subject.stored;
       d.grants.set(principal, [...held]);
-      const changes = input.changes.map((change) => this.#apply(d, actor, principal, held, change, input));
+      const outcomes = changes.map((change) => this.#apply(d, actor, principal, held, change, input));
       if (d.writes.length > 0) d.touched.add(principal);
-      return { changes };
+      return { changes: outcomes };
     });
   }
 
@@ -1098,21 +1376,23 @@ class VaultService implements Vault {
     actor: string,
     principal: string,
     held: readonly GrantRow[],
-    change: GrantChange,
+    change: GrantChange & GrantPlace,
     correlation: Correlation,
   ): AccessChange {
-    const existing = held.find((grant) => grant.projectId === change.projectId && grant.environmentId === change.environmentId);
+    const existing = held.find((grant) => placeKey(grant) === placeKey(change));
     const current = existing !== undefined && live(existing, d.at) ? existing : undefined;
     const expiresAt = change.expiresAt === null ? null : Date.parse(change.expiresAt);
-    const place = { projectId: change.projectId, environmentId: change.environmentId };
+    const place = { projectId: change.projectId, environmentId: change.environmentId, environmentSlug: change.environmentSlug };
+    const where = located(place);
     const entry = (action: string, role: string | null) =>
       d.log.push({
         ...accessEntry(actor, action, principal, 'allow', correlation, {
           role,
           expiresAt: expiresAt === null ? null : iso(expiresAt),
           previousRole: current?.role ?? null,
+          ...where.detail,
         }),
-        ...place,
+        ...where.ids,
       });
     // A lapsed grant is cleared with no entry: it changes nothing anyone holds.
     const clear = () => {
@@ -1152,7 +1432,7 @@ class VaultService implements Vault {
       const acting = await this.#standing(d.tx, actor, d.members.get(actor), d.at, d.reports);
       if (acting.status === 'tampered') throw refused('tampered');
       if (!acting.live.isOwner) throw refused('not_allowed', 'only owners may add or restore members');
-      if (!LIVE_PRINCIPAL.test(principal)) throw refused('invalid', `not a member: ${principal}`);
+      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');
@@ -1204,7 +1484,7 @@ class VaultService implements Vault {
       new Refused(refusal(code, message), [accessEntry(actor, 'member.remove', principal, 'deny', input, {}, code)]);
     return this.#decide([actor, principal], async (d) => {
       validateCorrelation(input);
-      if (!LIVE_PRINCIPAL.test(principal)) throw refused('invalid', `not a member: ${principal}`);
+      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);
@@ -1221,14 +1501,15 @@ class VaultService implements Vault {
 
       const revoked = held.filter((grant) => live(grant, d.at));
       for (const grant of revoked) {
+        const where = located(grant);
         d.log.push({
           ...accessEntry(actor, 'access.revoke', principal, 'allow', input, {
             role: null,
             expiresAt: null,
             previousRole: grant.role,
+            ...where.detail,
           }),
-          projectId: grant.projectId,
-          environmentId: grant.environmentId,
+          ...where.ids,
         });
       }
       const generation = row.generation + 1;
@@ -1750,12 +2031,83 @@ function validateItems(items: readonly { secret: SecretRef; key?: string; wrappe
   }
 }
 
-/** Why `reader` may not do `permission` on `secret`, or null if they may. */
-function refuses(reader: Standing, permission: Permission, secret: SecretRef): RefusalCode | null {
+/** A reference as its `reference.create` entry seals it. */
+type Sealed = {
+  reference: string;
+  seq: bigint;
+  holder: { projectId: string; environmentId: string; secretId: string; path: string };
+  source: { projectId: string; environmentId: string; secretId: string; path: string };
+  createdBy: string;
+  createdAt: number;
+};
+
+/** What a genuine `reference.create` entry seals, if it is about `reference`; null if not, or malformed. */
+function sealedReference(entry: StoredEntry, reference: string): Sealed | null {
+  let detail: { reference?: unknown; subject?: unknown; secretId?: unknown; source?: { path?: unknown }; also?: Record<string, unknown> };
+  try {
+    detail = JSON.parse(entry.metadata) as typeof detail;
+  } catch {
+    return null;
+  }
+  const text = (value: unknown): value is string => typeof value === 'string' && value !== '';
+  const also = detail.also ?? {};
+  if (detail.reference !== reference || entry.projectId === null || entry.environmentId === null) return null;
+  if (!text(detail.subject) || !text(detail.secretId) || !text(detail.source?.path)) return null;
+  if (!text(also.projectId) || !text(also.environmentId) || !text(also.secretId)) return null;
+  return {
+    reference,
+    seq: entry.seq,
+    holder: { projectId: entry.projectId, environmentId: entry.environmentId, secretId: detail.secretId, path: detail.subject },
+    source: { projectId: also.projectId, environmentId: also.environmentId, secretId: also.secretId, path: detail.source!.path as string },
+    createdBy: entry.actor,
+    createdAt: entry.occurredAt,
+  };
+}
+
+/** A read's reference, checked for shape: null for none. */
+function validateVia(via: Via | null | undefined): Via | null {
+  if (via === undefined || via === null) return null;
+  if (typeof via.reference !== 'string' || !UUID.test(via.reference)) throw new Error('a reference id must be a lowercase UUID');
+  if (!Number.isSafeInteger(via.seq) || via.seq < 0) throw new Error("a reference's seq must be a whole number");
+  return { reference: via.reference, seq: via.seq };
+}
+
+/**
+ * How a read through a reference is logged: the way in, and `also`, the
+ * holder's place, which puts the read in the holder's project's log too.
+ */
+function viaDetail(via: Via, seal: Sealed | null): Record<string, unknown> {
+  if (seal === null) return { via: { reference: via.reference, seq: via.seq } };
+  return {
+    via: { reference: via.reference, seq: via.seq, path: seal.holder.path, createdBy: seal.createdBy, createdAt: iso(seal.createdAt) },
+    also: { projectId: seal.holder.projectId, environmentId: seal.holder.environmentId, secretId: seal.holder.secretId },
+  };
+}
+
+/** An environment a secret is in, or that holds a reference to one. */
+type SecretPlace = { projectId: string; environmentId: string };
+
+/**
+ * Where a decision checks a permission: an environment, with its slug as
+ * the store has it when it was read and is in the project claimed;
+ * otherwise none, which no grant on a slug matches.
+ */
+function placeIn(place: SecretPlace, environments: ReadonlyMap<string, { projectId: string; slug: string }>): Place {
+  const environment = environments.get(place.environmentId);
+  const slug = environment?.projectId === place.projectId ? environment.slug : null;
+  return { projectId: place.projectId, environmentId: place.environmentId, environmentSlug: slug };
+}
+
+/**
+ * Why `reader` may not do `permission` at `where`, or null if they may. A
+ * deleted place is refused before any grant is asked, so no kind of grant,
+ * on the project, the environment or every project, can reach into one.
+ */
+function refuses(reader: Standing, permission: Permission, where: Place, deleted: boolean): RefusalCode | null {
   if (reader.status === 'tampered') return 'tampered';
   if (reader.status === 'removed') return 'removed';
   if (reader.status === 'unknown') return 'not_a_member';
-  const where = { projectId: secret.projectId, environmentId: secret.environmentId };
+  if (deleted) return 'deleted';
   if (allows(reader.live, permission, where)) return null;
   // Would a grant that has lapsed have covered it?
   return allows(reader.all, permission, where) ? 'expired' : 'no_grant';
@@ -1831,10 +2183,41 @@ function live(grant: GrantRow, at: number): boolean {
   return grant.expiresAt === null || grant.expiresAt > at;
 }
 
+/**
+ * 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`).
+ */
+function located(place: GrantPlace): { ids: Pick<NewEntry, 'projectId' | 'environmentId'>; detail: { place?: string } } {
+  return grantKind(place) === 'every-project'
+    ? { ids: {}, detail: { place: everyProjectPath(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);
+}
+
+/** 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;
+}
+
+/** An environment's slug, as the schema has it. */
+const SLUG = /^[a-z0-9][a-z0-9-]{0,62}$/;
+
 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),