@coffre/vault 0.6.2 → 0.8.0

package/src/accounting.ts

@@ -5,7 +5,8 @@ const KEY_ACTIONS = new Set(['secret.read', 'key.wrap', 'key.rewrap']);
 
 type Item = { item: number; secretId: string; version: number; subject: string };
 type ParsedIntent = { intentId: string; operation: string; expiresAt: number; keys: Item[] };
-type ParsedOutcome = Item & { intentId: string; relatedSeq: bigint };
+/** An outcome entry: one item of its intent, or several, for a read logged once per place. */
+type ParsedOutcome = { intentId: string; relatedSeq: bigint; items: Item[] };
 type Intent = ParsedIntent & { entry: StoredEntry; seen: Set<number> };
 type Accounting = { ok: true; pending: number } | Extract<LogVerification, { ok: false }>;
 
@@ -36,19 +37,21 @@ export class KeyAccounting {
       const parsed = parseOutcome(entry);
       if (typeof parsed === 'string') return broken(parsed);
       const intent = this.#intents.get(parsed.relatedSeq);
-      const key = intent?.keys[parsed.item];
-      if (intent === undefined || key === undefined || intent.seen.has(parsed.item)) {
-        return broken('key outcome does not identify one item of its intent');
+      for (const outcome of parsed.items) {
+        const key = intent?.keys[outcome.item];
+        if (intent === undefined || key === undefined || intent.seen.has(outcome.item)) {
+          return broken('key outcome does not identify one item of its intent');
+        }
+        if (parsed.intentId !== intent.intentId || entry.actor !== intent.entry.actor || entry.action !== intent.operation) {
+          return broken('key outcome belongs to another operation');
+        }
+        if (outcome.secretId !== key.secretId || outcome.version !== key.version || outcome.subject !== key.subject) {
+          return broken('key outcome does not match its intended secret');
+        }
+        intent.seen.add(outcome.item);
       }
-      if (parsed.intentId !== intent.intentId || entry.actor !== intent.entry.actor || entry.action !== intent.operation) {
-        return broken('key outcome belongs to another operation');
-      }
-      if (parsed.secretId !== key.secretId || parsed.version !== key.version || parsed.subject !== key.subject) {
-        return broken('key outcome does not match its intended secret');
-      }
-      intent.seen.add(parsed.item);
       // Completed batches need no state, and another outcome for one is a duplicate.
-      if (intent.seen.size === intent.keys.length) this.#intents.delete(intent.entry.seq);
+      if (intent !== undefined && intent.seen.size === intent.keys.length) this.#intents.delete(intent.entry.seq);
     }
   }
 
@@ -91,13 +94,22 @@ function parseIntent(entry: StoredEntry): ParsedIntent | string {
 function parseOutcome(entry: StoredEntry): ParsedOutcome | string {
   const detail = payload(entry.metadata);
   if (detail === null) return 'key outcome has no valid accounting payload';
-  const { intent, item, version, subject } = detail;
+  const { intent } = detail;
   if (typeof intent !== 'string' || entry.relatedSeq === null) return 'key outcome has no intent identity';
-  if (typeof item !== 'number' || !Number.isSafeInteger(item) || item < 0) return 'key outcome has no valid item number';
-  const secretId = entry.secretId ?? detail.secretId;
-  if (typeof secretId !== 'string' || typeof subject !== 'string') return 'key outcome has no secret identity';
-  if (typeof version !== 'number' || !Number.isSafeInteger(version) || version < 1) return 'key outcome has no valid version';
-  return { intentId: intent, relatedSeq: entry.relatedSeq, item, secretId, version, subject };
+  // Several secrets read at one place share one entry, each its item there.
+  const many = detail.secrets;
+  if (many !== undefined && (!Array.isArray(many) || many.length === 0)) return 'key outcome has no valid item list';
+  const listed = many === undefined ? [{ ...detail, secretId: entry.secretId ?? detail.secretId }] : many.map(record);
+  const items: Item[] = [];
+  for (const one of listed) {
+    if (one === null) return 'key outcome has no valid item list';
+    const { item, secretId, version, subject } = one;
+    if (typeof item !== 'number' || !Number.isSafeInteger(item) || item < 0) return 'key outcome has no valid item number';
+    if (typeof secretId !== 'string' || typeof subject !== 'string') return 'key outcome has no secret identity';
+    if (typeof version !== 'number' || !Number.isSafeInteger(version) || version < 1) return 'key outcome has no valid version';
+    items.push({ item, secretId, version, subject });
+  }
+  return { intentId: intent, relatedSeq: entry.relatedSeq, items };
 }
 
 function payload(text: string): Record<string, unknown> | null {

package/src/config.ts

@@ -28,8 +28,20 @@ export type ResolvedVaultConfig = {
    */
   signingKeys: readonly Uint8Array[];
   bulkLimit: BulkLimit;
+  /** `values` when left out. */
+  people?: People;
 };
 
+/**
+ * What a person's reads open (docs/design/credential-proxy.md): `values`,
+ * as any member's; or `stand-ins`, where a person, on any credential of
+ * theirs (a session, a personal token, an MCP connection), opens values
+ * only for coffre to use for them, never to be handed back: the credential
+ * proxy injects them, and the deployment's `expose` list names the few it
+ * may pass on. Service accounts read values either way.
+ */
+export type People = 'values' | 'stand-ins';
+
 /**
  * A key-encryption key: 32 random bytes, base64, and the id envelopes record
  * it under; or one a key service holds, such as `awsKms({ keyArn, … })`.
@@ -64,6 +76,8 @@ export type VaultConfig = {
   signingKey?: string;
   /** At most `count` data keys unwrapped per principal in any `windowMinutes`; 1000 in 15 unless set. */
   bulkLimit?: { count: number; windowMinutes: number };
+  /** What a person's reads open (`People`): `values` unless set. */
+  people?: People;
 } & Owners;
 
 /**
@@ -142,6 +156,7 @@ export function resolveVaultConfig(config: VaultConfig): ResolvedVaultConfig {
     owners: checkOwners(config.owners ?? config.bootstrapOwners ?? config.rootAdmins ?? []),
     signingKeys: signingKeys(config.signingKey, keks),
     bulkLimit: config.bulkLimit === undefined ? DEFAULT_BULK_LIMIT : checkBulkLimit(config.bulkLimit),
+    people: checkPeople(config.people ?? 'values'),
   };
 }
 
@@ -169,6 +184,11 @@ function signingKeys(given: string | undefined, keks: { provider: KekProvider; s
   return [signing, ...derived].filter((key, i, all) => all.findIndex((other) => other.equals(key)) === i);
 }
 
+function checkPeople(people: People): People {
+  if (people !== 'values' && people !== 'stand-ins') throw new Error(`people is 'values' or 'stand-ins'; got ${JSON.stringify(people)}`);
+  return people;
+}
+
 function checkBulkLimit({ count, windowMinutes }: { count: number; windowMinutes: number }): BulkLimit {
   if (!Number.isInteger(count) || count < 1 || !(windowMinutes > 0)) {
     throw new Error('bulkLimit needs a whole count of at least 1 and a window above 0 minutes');

package/src/index.ts

@@ -3,6 +3,6 @@ export { checkpointMessage, verifyCheckpoint } from '@coffre/core/vault';
 export type { SecretContext } from '@coffre/core/envelope';
 export { awsKms, KekBadClaimError, KekUnavailableError } from '@coffre/core/kek';
 export type { AwsCredentials, AwsKmsOptions, KekProvider, WrappedDek } from '@coffre/core/kek';
-export type { Kek, VaultConfig } from './config.ts';
+export type { Kek, People, VaultConfig } from './config.ts';
 /** The signing key a local KEK stands for, for tools that check the vault's records from outside. */
 export { derivedSigningKey } from './config.ts';

package/src/log.ts

@@ -38,7 +38,7 @@ export function further(a: Anchor, b: Anchor): Anchor {
   return b.nextSeq > a.nextSeq ? b : a;
 }
 
-/** Entries read at once: a few megabytes, well within a Worker's memory, and a fifth of the round trips of 1000. */
+/** Entries read at once, at most, and no more than `BATCH_BYTES` of what they say: well within a Worker's memory, and a fifth of the round trips of 1000. */
 export const VERIFY_BATCH = 5000;
 
 type Verified = { verification: LogVerification; anchor: Anchor };
@@ -96,7 +96,6 @@ export async function verifyChain(
       vaultEntries: verified.vaultEntries + result.authenticated,
       vaultKeys: moved.keys,
     };
-    if (batch.length < VERIFY_BATCH) break;
   }
   return { verification: { ok: true, entries: verified.vaultEntries }, anchor: verified };
 }

package/src/store.ts

@@ -4,8 +4,8 @@ import { ACCESS_ACTIONS, type SecretRef, type WrappedKey } from '@coffre/core/va
 import { tablesOf, type Queryable, type Transaction } from '@coffre/db';
 import { clockMillis, engineOf, forUpdate, tombstone, truth } from '@coffre/db/dialect';
 import { readGrants, roleColumns, storedRole, type GrantRow } from '@coffre/db/grants';
-import { entryColumns } from '@coffre/db/log';
-import { and, asc, count, desc, eq, gt, gte, inArray, isNull, like, lt, lte, or, sql, type SQL, type SQLWrapper } from 'drizzle-orm';
+import { entryColumns, withinBytes } from '@coffre/db/log';
+import { and, asc, count, desc, eq, gt, gte, inArray, isNotNull, isNull, like, lt, lte, or, sql, type SQL, type SQLWrapper } from 'drizzle-orm';
 
 /**
  * Every query the vault makes, and the only code in it that holds them.
@@ -193,10 +193,20 @@ function at(db: Queryable, place: Place) {
  * deleted, alone or with its project: then no key under it opens, or is
  * wrapped, whatever grant would cover it.
  */
+/** An environment as a decision reads it. */
+export type EnvironmentRow = {
+  projectId: string;
+  slug: string;
+  owner: string | null;
+  parentId: string | null;
+  deleted: boolean;
+  archived: boolean;
+};
+
 export async function environmentsById(
   db: Queryable,
   ids: readonly string[],
-): Promise<Map<string, { projectId: string; slug: string; deleted: boolean }>> {
+): Promise<Map<string, EnvironmentRow>> {
   if (ids.length === 0) return new Map();
   const { environments, projects } = tablesOf(db);
   const rows = await db
@@ -204,7 +214,12 @@ export async function environmentsById(
       id: environments.id,
       projectId: environments.projectId,
       slug: environments.slug,
+      // A personal config's owner, and the environment it is a config of, whose read it takes.
+      owner: environments.owner,
+      parentId: environments.parentId,
       deleted: truth(or(tombstone(environments.slug), tombstone(projects.slug))!),
+      // Only what names a fork asks it: nothing is decided on it.
+      archived: truth(or(isNotNull(environments.archivedAt), isNotNull(projects.archivedAt))!),
     })
     .from(environments)
     .innerJoin(projects, eq(projects.id, environments.projectId))
@@ -291,11 +306,18 @@ export async function everyProjectHolders(db: Queryable): Promise<string[]> {
 /** The action of an entry that releases a key, which the bulk limit counts. */
 export const RELEASE = 'secret.read';
 
-/** How many keys the vault has released to `principal` since `after`. */
+/**
+ * How many keys the vault has released to `principal` since `after`: one
+ * for an entry about one secret, and as many as it lists for one about
+ * several (`secrets`), a read logged once per place.
+ */
 export async function releasesSince(db: Queryable, principal: string, after: number): Promise<number> {
   const { auditLog } = tablesOf(db);
+  const listed = engineOf(db) === 'postgres'
+    ? sql`jsonb_array_length((${auditLog.metadata})::jsonb -> 'secrets')`
+    : sql`json_array_length(${auditLog.metadata}, '$.secrets')`;
   const [{ n }] = await db
-    .select({ n: count() })
+    .select({ n: sql<string | number | null>`SUM(COALESCE(${listed}, 1))` })
     .from(auditLog)
     .where(
       and(
@@ -306,7 +328,7 @@ export async function releasesSince(db: Queryable, principal: string, after: num
         gt(auditLog.occurredAt, after),
       ),
     );
-  return Number(n);
+  return Number(n ?? 0);
 }
 
 /** Rows of the log as the chain's codec reads them: `author` and `decision` are checked by the table. */
@@ -317,24 +339,27 @@ function stored(rows: object[]): StoredEntry[] {
 /** Up to `limit` entries of either author from `fromSeq`, oldest first: the chain as it runs. */
 export async function entriesFrom(db: Queryable, fromSeq: bigint, limit: number): Promise<StoredEntry[]> {
   const { auditLog } = tablesOf(db);
+  const batch = await withinBytes(db, gte(auditLog.seq, fromSeq), limit);
+  if (batch === null) return [];
   const rows = await db
     .select(entryColumns(db))
     .from(auditLog)
-    .where(gte(auditLog.seq, fromSeq))
-    .orderBy(asc(auditLog.seq))
-    .limit(limit);
+    .where(and(gte(auditLog.seq, batch.from), lte(auditLog.seq, batch.to)))
+    .orderBy(asc(auditLog.seq));
   return stored(rows);
 }
 
 /** Up to `limit` of the vault's entries after `afterSeq`, oldest first: every one, whatever its action or decision. */
 export async function vaultEntriesAfter(db: Queryable, afterSeq: bigint, limit: number): Promise<StoredEntry[]> {
   const { auditLog } = tablesOf(db);
+  const vault = eq(auditLog.author, 'vault' satisfies Author);
+  const batch = await withinBytes(db, and(vault, gt(auditLog.seq, afterSeq)), limit);
+  if (batch === null) return [];
   const rows = await db
     .select(entryColumns(db))
     .from(auditLog)
-    .where(and(eq(auditLog.author, 'vault' satisfies Author), gt(auditLog.seq, afterSeq)))
-    .orderBy(asc(auditLog.seq))
-    .limit(limit);
+    .where(and(vault, gte(auditLog.seq, batch.from), lte(auditLog.seq, batch.to)))
+    .orderBy(asc(auditLog.seq));
   return stored(rows);
 }
 

package/src/vault.ts

@@ -24,9 +24,10 @@ import {
   type Role,
   type Scope,
   type ServiceAccount,
+  withinCredential,
 } 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 { checkContext, ownerKey, type SecretContext } from '@coffre/core/envelope';
 import { shownMember } from '@coffre/core/schemas';
 import {
   DEK_BYTES,
@@ -45,6 +46,7 @@ import {
   checkpointMessage,
   checkpointVerifier,
   describeAccessFault,
+  HANDED_BACK,
   type Access,
   type AccessChange,
   type AccessFault,
@@ -59,6 +61,7 @@ import {
   type LogHead,
   type LogVerification,
   type Outcome,
+  type Purpose,
   type ReferenceInput,
   type Refusal,
   type RefusalCode,
@@ -279,6 +282,8 @@ const MESSAGES: Record<RefusalCode, string> = {
   bad_claim: 'the key does not belong to this secret',
   deleted: 'this project or environment was deleted',
   ended: 'the reference read through was ended',
+  personal: "a personal config's values are its owner's alone",
+  stand_ins: "people use this instance's values through stand-ins, never as values: `coffre run` gives your app them; a service account reads values",
   not_allowed: 'not allowed to change this',
   last_owner: 'the last Owner of the whole instance stays one: make someone else an Owner first',
   invalid: 'not something the rules allow',
@@ -428,7 +433,8 @@ class VaultService implements Vault {
           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];
+        // A read is logged once per place, whichever way it ends (`readsByPlace`).
+        const entries = [...reports, ...readsByPlace(d.log)];
         let at = d.at;
         // Each member's newest access entry, which their row names (rows.ts).
         const accessSeq = new Map<string, bigint>();
@@ -451,7 +457,7 @@ class VaultService implements Vault {
       return { ok: true, ...result };
     } catch (error) {
       if (!(error instanceof Refused || error instanceof Outage)) throw error;
-      const entries = [...reports, ...error.entries];
+      const entries = [...reports, ...readsByPlace(error.entries)];
       if (entries.length > 0) {
         await this.#db.transaction(async (tx) => {
           await store.boundLockWaits(tx, LOCK_TIMEOUT_MS);
@@ -785,23 +791,45 @@ class VaultService implements Vault {
     const { principal } = input;
     validateText(input.purpose);
     const vias = input.items.map((item) => validateVia(item.via));
+    const throughs = input.items.map((item) => validateThrough(item.through));
     const loaded = await this.#versions(input, 'secret.read', { purpose: input.purpose });
     if (!loaded.ok) return loaded;
     // 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 forks = await store.environmentsById(this.#db, throughs.flatMap((through) => (through === null ? [] : [through])));
+    // A reference reads only the current version of the source its entry names.
+    const viaOk = items.map((item, i) => vias[i] === null || (sealed[i] !== null && sealed[i]!.source.secretId === item.secret.secretId && item.current));
+    // A fork an inherited value is read in is a live environment of the same project as the value's, and not its own,
+    // for a read whose reference, if any, holds. Checked once, not again under the log's head: it decides nothing, so a
+    // fork archived meanwhile only names a read.
+    const throughOk = items.map((item, i) => {
+      const through = throughs[i];
+      if (through === null) return true;
+      if (!viaOk[i]) return false;
+      const fork = forks.get(through);
+      const decidedAt = sealed[i]?.holder ?? item.secret;
+      return fork !== undefined && !fork.deleted && !fork.archived && fork.projectId === decidedAt.projectId && through !== decidedAt.environmentId;
+    });
     const versionIds = new Map(items.map((item) => [item.secret, item.id]));
-    const viaOf = new Map(items.map((item, i) => [item.secret, { via: vias[i], sealed: sealed[i] }]));
+    const viaOf = new Map(items.map((item, i) => [item.secret, { via: vias[i], sealed: sealed[i], through: throughs[i], throughOk: throughOk[i] }]));
     const entry = (secret: SecretRef, decision: 'allow' | 'deny', code: string | null): NewEntry => {
-      const { via, sealed: seal } = viaOf.get(secret)!;
+      const { via, sealed: seal, through, throughOk: ok } = viaOf.get(secret)!;
       return {
-        ...keyEntry('secret.read', principal, secret, decision, code, input, { purpose: input.purpose, ...(via === null ? {} : viaDetail(via, seal)) }),
+        ...keyEntry('secret.read', principal, secret, decision, code, input, {
+          purpose: input.purpose,
+          ...(via === null ? {} : viaDetail(via, seal)),
+          // A fork that failed the check is named, never filed under: its project's log is no place for this read.
+          ...(through === null ? {} : ok ? throughDetail(through, forks.get(through), via !== null) : { through: { environmentId: through, refused: true } }),
+        }),
         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))) {
+    if (viaOk.includes(false)) {
+      return this.#refuseVersions(principal, 'bad_claim', items.map((item) => entry(item.secret, 'deny', 'bad_claim')));
+    }
+    if (throughOk.includes(false)) {
       return this.#refuseVersions(principal, 'bad_claim', items.map((item) => entry(item.secret, 'deny', 'bad_claim')));
     }
     const ends = sealed.flatMap((seal) => (seal === null ? [] : [seal.seq]));
@@ -822,9 +850,9 @@ class VaultService implements Vault {
         entry,
         input,
       },
-      () =>
+      (contextOf) =>
         items.map(({ secret, wrapped }) => async (operation: KeyOperation) => {
-          const key = await this.#open(wrapped, secret, operation);
+          const key = await this.#open(wrapped, contextOf(secret), operation);
           return key && { key, wipe: () => key.fill(0) };
         }),
       (opened) => ({
@@ -856,11 +884,11 @@ class VaultService implements Vault {
         entry,
         input,
       },
-      () =>
+      (contextOf) =>
         items.map(({ secret, key }) => async (operation: KeyOperation) => {
           const dek = Buffer.from(key, 'base64');
           try {
-            return { wrapped: serialisable(await this.#config.keks.wrap(dek, context(secret), operation)), wipe: () => {} };
+            return { wrapped: serialisable(await this.#config.keks.wrap(dek, contextOf(secret), operation)), wipe: () => {} };
           } finally {
             dek.fill(0);
           }
@@ -892,12 +920,12 @@ class VaultService implements Vault {
       this.#remote(this.#config.keks.primary) || items.some(({ wrapped }) => this.#remote(this.#config.keks.providerOf(wrapped)));
     return this.#keys(
       { action: 'key.rewrap', principal, permission: 'secret.write', secrets: items.map((item) => item.secret), remote, entry, input },
-      () =>
+      (contextOf) =>
         items.map(({ secret, wrapped }) => async (operation: KeyOperation) => {
-          const key = await this.#open(wrapped, secret, operation);
+          const key = await this.#open(wrapped, contextOf(secret), operation);
           if (key === null) return null;
           try {
-            return { wrapped: serialisable(await this.#config.keks.wrap(key, context(secret), operation)), wipe: () => {} };
+            return { wrapped: serialisable(await this.#config.keks.wrap(key, contextOf(secret), operation)), wipe: () => {} };
           } finally {
             key.fill(0);
           }
@@ -951,9 +979,9 @@ class VaultService implements Vault {
    * that is not what it says. A key service that cannot answer is an outage,
    * not a verdict on the claim, and throws.
    */
-  async #open(wrapped: WrappedKey, secret: SecretRef, operation: KeyOperation): Promise<Buffer | null> {
+  async #open(wrapped: WrappedKey, context: SecretContext, operation: KeyOperation): Promise<Buffer | null> {
     try {
-      return await this.#config.keks.unwrap(unwrappable(wrapped), context(secret), operation);
+      return await this.#config.keks.unwrap(unwrappable(wrapped), context, operation);
     } catch (error) {
       if (error instanceof KekBadClaimError) return null;
       throw error;
@@ -989,8 +1017,12 @@ class VaultService implements Vault {
       entry: (secret: SecretRef, decision: 'allow' | 'deny', code: string | null) => NewEntry;
       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>)[],
+    /**
+     * One per secret; null for a bad claim, an error for an outage or an
+     * unexpected fault. `context` is each secret's, as the decision read its
+     * environment: a personal config's binds its owner.
+     */
+    operations: (context: (secret: SecretRef) => SecretContext) => ((operation: KeyOperation) => Promise<T | null>)[],
     result: (done: T[]) => R,
   ): Promise<Outcome<R>> {
     const { action, principal, secrets, entry } = call;
@@ -1001,6 +1033,8 @@ class VaultService implements Vault {
         throw new Refused(refusal('wrong_kek', wrongKek), secrets.map((secret) => entry(secret, 'deny', 'wrong_kek')));
       });
     }
+    // Each personal config's owner, hashed, by environment, as the decision read them: what its keys' contexts bind.
+    const owners = new Map<string, string>();
     const check = async (d: Decision) => {
       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:
@@ -1008,13 +1042,23 @@ class VaultService implements Vault {
       // 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));
+      // A personal config's parent, whose read its owner needs.
+      const parents = [...environments.values()].flatMap((environment) => (environment.owner === null || environment.parentId === null ? [] : [environment.parentId]));
+      for (const [id, parent] of await store.environmentsById(d.tx, parents)) environments.set(id, parent);
       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]!)));
+      owners.clear();
+      for (const [id, environment] of environments) if (environment.owner !== null) owners.set(id, ownerKey(environment.owner));
+      const codes: (RefusalCode | null)[] = secrets.map((secret, i) => {
+        const personal = personalRefusal(reader, principal, call.permission, secret, at[i]!, environments);
+        if (personal !== undefined) return personal;
+        return 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;
+      // A person's values are only ever used for them, where people get stand-ins: by whatever credential of theirs asks.
+      if (first === null && action === 'secret.read' && this.#config.people === 'stand-ins' && principal.startsWith('user:') && HANDED_BACK.includes(call.input.purpose as Purpose)) first = 'stand_ins';
       if (first === null && action === 'secret.read' && (await this.#overBulkLimit(d, principal, secrets.length))) first = 'bulk_limit';
       if (first !== null) {
         throw new Refused(
@@ -1087,7 +1131,7 @@ class VaultService implements Vault {
           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 { outcomes, expired } = await settle(operations((secret) => context(secret, owners.get(secret.environmentId))), this.#prepared.options.keyBudgetMs);
       const done = outcomes.flatMap((outcome) => (outcome.ok ? [outcome.value] : []));
       try {
         const entries = () => secrets.map((secret, i) =>
@@ -1192,6 +1236,8 @@ class VaultService implements Vault {
         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';
+        // A personal config's values are bound to its owner: no reference holds one, nor reads one.
+        if (environments.get(item.holder.environmentId)?.owner != null || environments.get(source.environmentId)?.owner != null) return 'personal';
         return refuses(reader, 'secret.write', placeIn(item.holder, environments), gone(item.holder))
           ?? refuses(reader, 'secret.read', placeIn(source, environments), gone(source));
       });
@@ -2238,6 +2284,7 @@ class VaultService implements Vault {
     let keys: readonly string[] = [];
     for (let after = -1n; ; ) {
       const batch = await store.vaultEntriesAfter(tx, after, VERIFY_BATCH);
+      if (batch.length === 0) return { ok: true };
       for (const entry of batch) {
         const result = verifyEntries([entry], { startSeq: entry.seq, startPrevHash: entry.prevHash, keys: logKeys });
         if (!result.ok) return { ok: false, failedAtSeq: Number(result.failedAtSeq), reason: withCause(result.reason) };
@@ -2246,7 +2293,6 @@ class VaultService implements Vault {
       if ('failedAtSeq' in moved) return { ok: false, failedAtSeq: Number(moved.failedAtSeq), reason: moved.reason };
       keys = moved.keys;
       for (const entry of batch) findings.add(entry);
-      if (batch.length < VERIFY_BATCH) return { ok: true };
       after = batch[batch.length - 1]!.seq;
     }
   }
@@ -2458,6 +2504,29 @@ function validateVia(via: Via | null | undefined): Via | null {
   return { reference: via.reference, seq: via.seq };
 }
 
+/** A read's fork, checked for shape: null for none. */
+function validateThrough(through: string | null | undefined): string | null {
+  if (through === undefined || through === null) return null;
+  if (typeof through !== 'string' || !UUID.test(through)) throw new Error("a fork's id must be a lowercase UUID");
+  return through;
+}
+
+/**
+ * How a read of an inherited value is logged: the fork it was read in,
+ * `through`, and as `also`, which puts it in the fork's log too, unless it
+ * was read through the parent's reference. The fork decides nothing: the
+ * reader's grants where the value is held do, as for any read.
+ */
+function throughDetail(through: string, fork: { projectId: string; slug: string } | undefined, viaReference: boolean): Record<string, unknown> {
+  return {
+    through: { environmentId: through, ...(fork === undefined ? {} : { slug: fork.slug }) },
+    // Through a reference, the entry is the source's, in another project perhaps, and stays filed where references
+    // file theirs: the source and the holder, the parent. A fork's own log would show a reader of the fork alone
+    // what the parent's reference reads, which is the parent's to tell.
+    ...(viaReference ? {} : { also: { projectId: fork?.projectId ?? null, environmentId: through } }),
+  };
+}
+
 /**
  * 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.
@@ -2489,6 +2558,32 @@ function placeIn(place: SecretPlace, environments: ReadonlyMap<string, { project
  * 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.
  */
+/**
+ * A key of a personal config is its owner's alone (docs/design/forking.md,
+ * section 4): no grant or role opens or wraps it, an Owner's included,
+ * only its owner, while they read the environment it is a config of,
+ * whatever the call is. Nor does any reference reach into or out of one.
+ * Undefined for a key of any other environment, decided as ever.
+ */
+function personalRefusal(
+  reader: Standing,
+  principal: string,
+  permission: Permission,
+  secret: SecretPlace,
+  at: SecretPlace,
+  environments: ReadonlyMap<string, store.EnvironmentRow>,
+): RefusalCode | null | undefined {
+  const own = environments.get(secret.environmentId);
+  const held = at.environmentId === secret.environmentId ? own : environments.get(at.environmentId);
+  if (own?.owner == null && held?.owner == null) return undefined;
+  if (own !== held || principal !== own?.owner || own.parentId === null) return 'personal';
+  const parent = placeIn({ projectId: secret.projectId, environmentId: own.parentId }, environments);
+  const refused = refuses(reader, 'secret.read', parent, own.deleted || (environments.get(own.parentId)?.deleted ?? true));
+  if (refused !== null) return refused;
+  // The credential's scope caps the owner still: their viewer token on the parent reads, and wraps no key.
+  return withinCredential(reader.live, permission, parent) ? null : 'no_grant';
+}
+
 function refuses(reader: Standing, permission: Permission, where: Place, deleted: boolean): RefusalCode | null {
   if (reader.status === 'tampered') return 'tampered';
   if (reader.status === 'removed') return 'removed';
@@ -2532,6 +2627,78 @@ function keyEntry(
   };
 }
 
+/** What every secret of one read at a place shares, said once in its entry rather than in each of its `secrets`. */
+const READ_SHARED = ['purpose', 'intent', 'credentialId', 'through'] as const;
+
+/**
+ * A decision's `secret.read` entries, made one per secret, as the log keeps
+ * them: one per place it was decided at, the environment read and, through
+ * a reference, the holder's, or the fork that inherits it (`also`,
+ * `through`). An entry about several secrets lists
+ * them in `secrets`, each with what its own entry would have said: its
+ * `secretId`, `secretVersionId`, `subject`, `version`, and its `via`, holder
+ * (`also.secretId`) and intent `item` when it has them. An entry about one
+ * secret is as it always was. A `coffre run` of a hundred keys is one entry,
+ * not a hundred; what it decided, and for which keys, is the same. Other
+ * entries pass through, in order.
+ */
+function readsByPlace(entries: readonly NewEntry[]): NewEntry[] {
+  const groups = new Map<string, NewEntry[]>();
+  const out: (NewEntry | NewEntry[])[] = [];
+  for (const entry of entries) {
+    if (entry.action !== 'secret.read') {
+      out.push(entry);
+      continue;
+    }
+    const { also, through } = JSON.parse(entry.metadata ?? '{}') as { also?: { projectId?: string; environmentId?: string }; through?: unknown };
+    const place = JSON.stringify([
+      entry.actor, entry.decision, entry.code ?? null, entry.projectId ?? null, entry.environmentId ?? null,
+      entry.operationId ?? null, entry.requestId ?? null, String(entry.relatedSeq ?? null), also?.projectId ?? null, also?.environmentId ?? null,
+      through ?? null,
+    ]);
+    const group = groups.get(place);
+    if (group !== undefined) {
+      group.push(entry);
+      continue;
+    }
+    const fresh = [entry];
+    groups.set(place, fresh);
+    out.push(fresh);
+  }
+  return out.map((item) => (Array.isArray(item) ? oneRead(item) : item));
+}
+
+/** Entries of one read at one place as one entry: `readsByPlace`. */
+function oneRead(group: NewEntry[]): NewEntry {
+  const [first] = group as [NewEntry];
+  if (group.length === 1) return first;
+  const details = group.map((entry) => JSON.parse(entry.metadata ?? '{}') as Record<string, unknown>);
+  const shared = Object.fromEntries(READ_SHARED.flatMap((field) => (details[0]![field] === undefined ? [] : [[field, details[0]![field]]])));
+  // The place on the other side, which the group shares: a reference's holder, or the fork reading.
+  const beside = details[0]!.also as { projectId: string | null; environmentId: string } | undefined;
+  const secrets = group.map((entry, i) => {
+    const own = Object.fromEntries(Object.entries(details[i]!).filter(([field]) => !(READ_SHARED as readonly string[]).includes(field) && field !== 'also'));
+    // A reference's holder is its own; a fork's `also` names only the fork, which the entry says once.
+    const holder = (details[i]!.also as { secretId?: string } | undefined)?.secretId;
+    return {
+      ...(entry.secretId == null ? {} : { secretId: entry.secretId }),
+      ...(entry.secretVersionId == null ? {} : { secretVersionId: entry.secretVersionId }),
+      ...own,
+      ...(holder === undefined ? {} : { also: { secretId: holder } }),
+    };
+  });
+  return {
+    ...first,
+    secretId: null,
+    secretVersionId: null,
+    metadata: JSON.stringify({
+      ...shared,
+      ...(beside === undefined ? {} : { also: { projectId: beside.projectId, environmentId: beside.environmentId } }),
+      secrets,
+    }),
+  };
+}
+
 /** Whether `entry` changes a member's access: what their row's `access_seq` names. */
 function isAccessEntry(entry: NewEntry): boolean {
   return (
@@ -2614,8 +2781,9 @@ function iso(ms: number): string {
   return new Date(ms).toISOString();
 }
 
-function context(secret: SecretRef): SecretContext {
-  return { projectId: secret.projectId, environmentId: secret.environmentId, secretId: secret.secretId };
+/** A secret's binding context: its ids, and a personal config's owner, hashed, as the decision read it. */
+function context(secret: SecretRef, owner?: string): SecretContext {
+  return { projectId: secret.projectId, environmentId: secret.environmentId, secretId: secret.secretId, ...(owner === undefined ? {} : { owner }) };
 }
 
 function unwrappable(wrapped: WrappedKey) {