@coffre/vault 0.6.2 → 0.8.0

package/dist/cloudflare.d.ts

@@ -1,4 +1,4 @@
-import { a as KekUnavailableError, c as awsKms, d as Kek, f as VaultConfig, i as KekProvider, l as checkpointMessage, n as AwsKmsOptions, o as SecretContext, p as derivedSigningKey, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-CwsWOH6j.js";
+import { a as KekUnavailableError, c as awsKms, d as Kek, f as People, i as KekProvider, l as checkpointMessage, m as derivedSigningKey, n as AwsKmsOptions, o as SecretContext, p as VaultConfig, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-BkHJR9Gt.js";
 import { AdmitInput, EndReferencesInput, ReferenceInput, RemoveInput, RewrapInput, SetAccessInput, SetSettingsInput, UnwrapInput, Vault, VerifyLogInput, WrapInput } from "@coffre/core/vault";
 import { PostgresDatabase, PostgresDatabase as PostgresDatabase$1, postgres } from "@coffre/db/hyperdrive";
 import { WorkerEntrypoint } from "cloudflare:workers";
@@ -63,4 +63,4 @@ export declare class VaultEntrypoint extends WorkerEntrypoint implements Vault {
 /** The vault Worker's default export, `VaultEntrypoint`, configured from its `env`. */
 export declare function vault<Env>(configure_: (env: Env) => WorkersVaultConfig): typeof VaultEntrypoint;
 //#endregion
-export { type AwsCredentials, type AwsKmsOptions, type Kek, KekBadClaimError, type KekProvider, KekUnavailableError, type PostgresDatabase, type SecretContext, type Vault, type VaultConfig, type WrappedDek, awsKms, checkpointMessage, derivedSigningKey, postgres, verifyCheckpoint };
+export { type AwsCredentials, type AwsKmsOptions, type Kek, KekBadClaimError, type KekProvider, KekUnavailableError, type People, type PostgresDatabase, type SecretContext, type Vault, type VaultConfig, type WrappedDek, awsKms, checkpointMessage, derivedSigningKey, postgres, verifyCheckpoint };

package/dist/cloudflare.js

@@ -1,5 +1,5 @@
-import { a as verifyCheckpoint, i as checkpointMessage, n as KekUnavailableError, o as derivedSigningKey, r as awsKms, s as resolveVaultConfig, t as KekBadClaimError } from "./src-CQJS3OZZ.js";
-import { n as prepareVault, t as openVault } from "./vault-ihE3Yc4a.js";
+import { a as verifyCheckpoint, i as checkpointMessage, n as KekUnavailableError, o as derivedSigningKey, r as awsKms, s as resolveVaultConfig, t as KekBadClaimError } from "./src-BcttALFQ.js";
+import { n as prepareVault, t as openVault } from "./vault-lBbyZ3kQ.js";
 import { createDatabase } from "@coffre/db";
 import { HyperdrivePool, postgres } from "@coffre/db/hyperdrive";
 import { WorkerEntrypoint } from "cloudflare:workers";

package/dist/{index-CwsWOH6j.d.ts → index-BkHJR9Gt.d.ts}

@@ -2,6 +2,15 @@ import { checkpointMessage as checkpointMessage$1, verifyCheckpoint } from "@cof
 import { AwsCredentials, AwsKmsOptions, KekBadClaimError as KekBadClaimError$1, KekProvider, KekProvider as KekProvider$1, KekRegistry, KekUnavailableError as KekUnavailableError$1, WrappedDek, awsKms } from "@coffre/core/kek";
 import { SecretContext } from "@coffre/core/envelope";
 //#region src/config.d.ts
+/**
+ * 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.
+ */
+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, … })`.
@@ -41,6 +50,8 @@ type VaultConfig = {
     count: number;
     windowMinutes: number;
   };
+  /** What a person's reads open (`People`): `values` unless set. */
+  people?: People;
 } & Owners;
 /**
  * At least one email, each an Owner of the whole instance: made one when
@@ -69,4 +80,4 @@ type Owners = {
 /** The signing key a local KEK stands for, when the vault is given none: HKDF-SHA-256 of the KEK. */
 declare function derivedSigningKey(kek: Uint8Array): Buffer;
 //#endregion
-export { KekUnavailableError$1 as a, awsKms as c, Kek as d, VaultConfig as f, KekProvider$1 as i, checkpointMessage$1 as l, AwsKmsOptions as n, SecretContext as o, derivedSigningKey as p, KekBadClaimError$1 as r, WrappedDek as s, AwsCredentials as t, verifyCheckpoint as u };
+export { KekUnavailableError$1 as a, awsKms as c, Kek as d, People as f, KekProvider$1 as i, checkpointMessage$1 as l, derivedSigningKey as m, AwsKmsOptions as n, SecretContext as o, VaultConfig as p, KekBadClaimError$1 as r, WrappedDek as s, AwsCredentials as t, verifyCheckpoint as u };

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-import { a as KekUnavailableError, c as awsKms, d as Kek, f as VaultConfig, i as KekProvider, l as checkpointMessage, n as AwsKmsOptions, o as SecretContext, p as derivedSigningKey, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-CwsWOH6j.js";
+import { a as KekUnavailableError, c as awsKms, d as Kek, f as People, i as KekProvider, l as checkpointMessage, m as derivedSigningKey, n as AwsKmsOptions, o as SecretContext, p as VaultConfig, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-BkHJR9Gt.js";
 export type * from "@coffre/core/vault";
-export { type AwsCredentials, type AwsKmsOptions, type Kek, KekBadClaimError, type KekProvider, KekUnavailableError, type SecretContext, type VaultConfig, type WrappedDek, awsKms, checkpointMessage, derivedSigningKey, verifyCheckpoint };
+export { type AwsCredentials, type AwsKmsOptions, type Kek, KekBadClaimError, type KekProvider, KekUnavailableError, type People, type SecretContext, type VaultConfig, type WrappedDek, awsKms, checkpointMessage, derivedSigningKey, verifyCheckpoint };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as verifyCheckpoint, i as checkpointMessage, n as KekUnavailableError, o as derivedSigningKey, r as awsKms, t as KekBadClaimError } from "./src-CQJS3OZZ.js";
+import { a as verifyCheckpoint, i as checkpointMessage, n as KekUnavailableError, o as derivedSigningKey, r as awsKms, t as KekBadClaimError } from "./src-BcttALFQ.js";
 export { KekBadClaimError, KekUnavailableError, awsKms, checkpointMessage, derivedSigningKey, verifyCheckpoint };

package/dist/node.d.ts

@@ -1,4 +1,4 @@
-import { a as KekUnavailableError, c as awsKms, d as Kek, f as VaultConfig, i as KekProvider, l as checkpointMessage, n as AwsKmsOptions, o as SecretContext, p as derivedSigningKey, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-CwsWOH6j.js";
+import { a as KekUnavailableError, c as awsKms, d as Kek, f as People, i as KekProvider, l as checkpointMessage, m as derivedSigningKey, n as AwsKmsOptions, o as SecretContext, p as VaultConfig, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-BkHJR9Gt.js";
 import { Vault, Vault as Vault$1 } from "@coffre/core/vault";
 import { Database } from "@coffre/db";
 import "@coffre/core/audit";
@@ -45,4 +45,4 @@ export declare function serveVault(config: NodeVaultConfig & {
 /** The vault that `serveVault` runs, from the server's side of its socket. */
 export declare function connectVault(socket: string): Vault;
 //#endregion
-export { type AwsCredentials, type AwsKmsOptions, type Kek, KekBadClaimError, type KekProvider, KekUnavailableError, type LocalVault, type SecretContext, type Vault, type VaultConfig, type VaultOptions, type WrappedDek, awsKms, checkpointMessage, derivedSigningKey, verifyCheckpoint };
+export { type AwsCredentials, type AwsKmsOptions, type Kek, KekBadClaimError, type KekProvider, KekUnavailableError, type LocalVault, type People, type SecretContext, type Vault, type VaultConfig, type VaultOptions, type WrappedDek, awsKms, checkpointMessage, derivedSigningKey, verifyCheckpoint };

package/dist/node.js

@@ -1,5 +1,5 @@
-import { a as verifyCheckpoint, i as checkpointMessage, n as KekUnavailableError, o as derivedSigningKey, r as awsKms, s as resolveVaultConfig, t as KekBadClaimError } from "./src-CQJS3OZZ.js";
-import { n as prepareVault, t as openVault } from "./vault-ihE3Yc4a.js";
+import { a as verifyCheckpoint, i as checkpointMessage, n as KekUnavailableError, o as derivedSigningKey, r as awsKms, s as resolveVaultConfig, t as KekBadClaimError } from "./src-BcttALFQ.js";
+import { n as prepareVault, t as openVault } from "./vault-lBbyZ3kQ.js";
 import { chmodSync, existsSync, lstatSync, rmSync } from "node:fs";
 import { Agent, createServer, request } from "node:http";
 import { openDatabase } from "@coffre/db/connect";

package/dist/{src-CQJS3OZZ.js → src-BcttALFQ.js}

@@ -57,7 +57,8 @@ function resolveVaultConfig(config) {
 		keks: new KekRegistry(current, previous),
 		owners: checkOwners(config.owners ?? config.bootstrapOwners ?? config.rootAdmins ?? []),
 		signingKeys: signingKeys(config.signingKey, keks),
-		bulkLimit: config.bulkLimit === void 0 ? DEFAULT_BULK_LIMIT : checkBulkLimit(config.bulkLimit)
+		bulkLimit: config.bulkLimit === void 0 ? DEFAULT_BULK_LIMIT : checkBulkLimit(config.bulkLimit),
+		people: checkPeople(config.people ?? "values")
 	};
 }
 /**
@@ -80,6 +81,10 @@ function signingKeys(given, keks) {
 	}
 	return [signing, ...derived].filter((key, i, all) => all.findIndex((other) => other.equals(key)) === i);
 }
+function checkPeople(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 }) {
 	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");
 	return {

package/dist/{vault-ihE3Yc4a.js → vault-lBbyZ3kQ.js}

@@ -1,15 +1,15 @@
-import { ACCESS_ACTIONS, checkpointMessage, checkpointVerifier, describeAccessFault } from "@coffre/core/vault";
+import { ACCESS_ACTIONS, HANDED_BACK, checkpointMessage, checkpointVerifier, describeAccessFault } from "@coffre/core/vault";
 import { DEK_BYTES, KEY_CHECK, KEY_CHECK_CONTEXT, KEY_CHECK_VALUE, KekBadClaimError, KekCancelledError, KekUnavailableError, LocalKekProvider } from "@coffre/core/kek";
 import { createHmac, hkdfSync, randomUUID, timingSafeEqual } from "node:crypto";
 import { tablesOf } from "@coffre/db";
-import { EVERYWHERE, NOTHING, allows, assignableToEnvironment, givesService, grantKind, isCredentialScope, isInstanceRole, isRole, isScope, managesService, mayManageAccess, normalScope, ownsInstance, runsInstance, setsUpServices, unscoped } from "@coffre/core/access";
+import { EVERYWHERE, NOTHING, allows, assignableToEnvironment, givesService, grantKind, isCredentialScope, isInstanceRole, isRole, isScope, managesService, mayManageAccess, normalScope, ownsInstance, runsInstance, setsUpServices, unscoped, withinCredential } from "@coffre/core/access";
 import { GENESIS_HASH, deriveLogKey, verifyEntries } from "@coffre/core/audit";
-import { checkContext } from "@coffre/core/envelope";
+import { checkContext, ownerKey } from "@coffre/core/envelope";
 import { shownMember } from "@coffre/core/schemas";
 import { SNAPSHOT, clockMillis, engineOf, forUpdate, isUniqueViolation, tombstone, truth } from "@coffre/db/dialect";
 import { accessEntriesAbout, everyProjectConversion, insertGrant, liveProjects, newestAccess, readGrants, reportStands, roleColumns, storedRole } from "@coffre/db/grants";
-import { LOOK_BACK, appendEntries, entryColumns, lockLogHead, newestAuthentic, newestVaultEntries } from "@coffre/db/log";
-import { and, asc, count, desc, eq, gt, gte, inArray, isNull, lt, lte, or, sql } from "drizzle-orm";
+import { LOOK_BACK, appendEntries, entryColumns, lockLogHead, newestAuthentic, newestVaultEntries, withinBytes } from "@coffre/db/log";
+import { and, asc, count, desc, eq, gt, gte, inArray, isNotNull, isNull, lt, lte, or, sql } from "drizzle-orm";
 //#region src/accounting.ts
 const KEY_ACTIONS = /* @__PURE__ */ new Set([
 	"secret.read",
@@ -49,12 +49,14 @@ var KeyAccounting = class {
 			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 === void 0 || key === void 0 || intent.seen.has(parsed.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 (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);
-			if (intent.seen.size === intent.keys.length) this.#intents.delete(intent.entry.seq);
+			for (const outcome of parsed.items) {
+				const key = intent?.keys[outcome.item];
+				if (intent === void 0 || key === void 0 || 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 (intent !== void 0 && intent.seen.size === intent.keys.length) this.#intents.delete(intent.entry.seq);
 		}
 	}
 	/** The first fault, or the batches still under way at `at`: live calls can finish after the snapshot. */
@@ -109,19 +111,32 @@ function parseIntent(entry) {
 function parseOutcome(entry) {
 	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";
+	const many = detail.secrets;
+	if (many !== void 0 && (!Array.isArray(many) || many.length === 0)) return "key outcome has no valid item list";
+	const listed = many === void 0 ? [{
+		...detail,
+		secretId: entry.secretId ?? detail.secretId
+	}] : many.map(record);
+	const items = [];
+	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,
-		item,
-		secretId,
-		version,
-		subject
+		items
 	};
 }
 function payload(text) {
@@ -274,12 +289,6 @@ function at(db, place) {
 	if (place.projectId !== null) return and(eq(vaultGrants.projectId, place.projectId), isNull(vaultGrants.environmentId));
 	return and(isNull(vaultGrants.projectId), isNull(vaultGrants.environmentId), place.environmentSlug === null ? isNull(vaultGrants.environmentSlug) : eq(vaultGrants.environmentSlug, place.environmentSlug));
 }
-/**
-* Each of these environments that exists, by id, with its project, its
-* slug, what grants on one slug in every project match, and whether it was
-* deleted, alone or with its project: then no key under it opens, or is
-* wrapped, whatever grant would cover it.
-*/
 async function environmentsById(db, ids) {
 	if (ids.length === 0) return /* @__PURE__ */ new Map();
 	const { environments, projects } = tablesOf(db);
@@ -287,7 +296,10 @@ async function environmentsById(db, ids) {
 		id: environments.id,
 		projectId: environments.projectId,
 		slug: environments.slug,
-		deleted: truth(or(tombstone(environments.slug), tombstone(projects.slug)))
+		owner: environments.owner,
+		parentId: environments.parentId,
+		deleted: truth(or(tombstone(environments.slug), tombstone(projects.slug))),
+		archived: truth(or(isNotNull(environments.archivedAt), isNotNull(projects.archivedAt)))
 	}).from(environments).innerJoin(projects, eq(projects.id, environments.projectId)).where(inArray(environments.id, [...new Set(ids)]));
 	return new Map(rows.map(({ id, ...environment }) => [id, environment]));
 }
@@ -348,11 +360,16 @@ async function everyProjectHolders(db) {
 }
 /** The action of an entry that releases a key, which the bulk limit counts. */
 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.
+*/
 async function releasesSince(db, principal, after) {
 	const { auditLog } = tablesOf(db);
-	const [{ n }] = await db.select({ n: count() }).from(auditLog).where(and(eq(auditLog.author, "vault"), eq(auditLog.actor, principal), eq(auditLog.action, RELEASE), eq(auditLog.decision, "allow"), gt(auditLog.occurredAt, after)));
-	return Number(n);
+	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: sql`SUM(COALESCE(${listed}, 1))` }).from(auditLog).where(and(eq(auditLog.author, "vault"), eq(auditLog.actor, principal), eq(auditLog.action, RELEASE), eq(auditLog.decision, "allow"), gt(auditLog.occurredAt, after)));
+	return Number(n ?? 0);
 }
 /** Rows of the log as the chain's codec reads them: `author` and `decision` are checked by the table. */
 function stored(rows) {
@@ -361,12 +378,17 @@ function stored(rows) {
 /** Up to `limit` entries of either author from `fromSeq`, oldest first: the chain as it runs. */
 async function entriesFrom(db, fromSeq, limit) {
 	const { auditLog } = tablesOf(db);
-	return stored(await db.select(entryColumns(db)).from(auditLog).where(gte(auditLog.seq, fromSeq)).orderBy(asc(auditLog.seq)).limit(limit));
+	const batch = await withinBytes(db, gte(auditLog.seq, fromSeq), limit);
+	if (batch === null) return [];
+	return stored(await db.select(entryColumns(db)).from(auditLog).where(and(gte(auditLog.seq, batch.from), lte(auditLog.seq, batch.to))).orderBy(asc(auditLog.seq)));
 }
 /** Up to `limit` of the vault's entries after `afterSeq`, oldest first: every one, whatever its action or decision. */
 async function vaultEntriesAfter(db, afterSeq, limit) {
 	const { auditLog } = tablesOf(db);
-	return stored(await db.select(entryColumns(db)).from(auditLog).where(and(eq(auditLog.author, "vault"), gt(auditLog.seq, afterSeq))).orderBy(asc(auditLog.seq)).limit(limit));
+	const vault = eq(auditLog.author, "vault");
+	const batch = await withinBytes(db, and(vault, gt(auditLog.seq, afterSeq)), limit);
+	if (batch === null) return [];
+	return stored(await db.select(entryColumns(db)).from(auditLog).where(and(vault, gte(auditLog.seq, batch.from), lte(auditLog.seq, batch.to))).orderBy(asc(auditLog.seq)));
 }
 /** The hash of the entry at each of `seqs` the log holds, by seq. */
 async function hashesAt(db, seqs) {
@@ -552,7 +574,7 @@ const UNVERIFIED = {
 function further(a, b) {
 	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. */
 const VERIFY_BATCH = 5e3;
 /**
 * Check the chain, a batch in memory at a time, and return where it is now
@@ -611,7 +633,6 @@ async function verifyChain(db, logKeys, shown, anchor, onBatch = () => {}) {
 			vaultEntries: verified.vaultEntries + result.authenticated,
 			vaultKeys: moved.keys
 		};
-		if (batch.length < 5e3) break;
 	}
 	return {
 		verification: {
@@ -1061,6 +1082,8 @@ const MESSAGES = {
 	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",
@@ -1161,7 +1184,7 @@ var VaultService = class {
 					underLock: []
 				};
 				const result = await decide(d);
-				const entries = [...reports, ...d.log];
+				const entries = [...reports, ...readsByPlace(d.log)];
 				let at = d.at;
 				const accessSeq = /* @__PURE__ */ new Map();
 				if (entries.length > 0) {
@@ -1184,7 +1207,7 @@ var VaultService = class {
 			};
 		} 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 boundLockWaits(tx, LOCK_TIMEOUT_MS);
 				await this.#append(tx, entries);
@@ -1507,6 +1530,7 @@ var VaultService = class {
 		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;
 		const items = loaded.versions.map((version) => ({
@@ -1515,22 +1539,39 @@ var VaultService = class {
 		}));
 		validateItems(items, "wrapped");
 		const sealed = await this.#referencesAt(vias);
+		const forks = await environmentsById(this.#db, throughs.flatMap((through) => through === null ? [] : [through]));
+		const viaOk = items.map((item, i) => vias[i] === null || sealed[i] !== null && sealed[i].source.secretId === item.secret.secretId && item.current);
+		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 !== void 0 && !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]
+			sealed: sealed[i],
+			through: throughs[i],
+			throughOk: throughOk[i]
 		}]));
 		const entry = (secret, decision, code) => {
-			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)
+					...via === null ? {} : viaDetail(via, seal),
+					...through === null ? {} : ok ? throughDetail(through, forks.get(through), via !== null) : { through: {
+						environmentId: through,
+						refused: true
+					} }
 				}),
 				secretVersionId: versionIds.get(secret)
 			};
 		};
-		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")));
+		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]);
 		const remote = items.some(({ wrapped }) => this.#remote(this.#config.keks.providerOf(wrapped)));
 		return this.#keys({
@@ -1546,8 +1587,8 @@ var VaultService = class {
 			remote,
 			entry,
 			input
-		}, () => items.map(({ secret, wrapped }) => async (operation) => {
-			const key = await this.#open(wrapped, secret, operation);
+		}, (contextOf) => items.map(({ secret, wrapped }) => async (operation) => {
+			const key = await this.#open(wrapped, contextOf(secret), operation);
 			return key && {
 				key,
 				wipe: () => key.fill(0)
@@ -1574,11 +1615,11 @@ var VaultService = class {
 			remote: this.#remote(this.#config.keks.primary),
 			entry,
 			input
-		}, () => items.map(({ secret, key }) => async (operation) => {
+		}, (contextOf) => items.map(({ secret, key }) => async (operation) => {
 			const dek = Buffer.from(key, "base64");
 			try {
 				return {
-					wrapped: serialisable(await this.#config.keks.wrap(dek, context(secret), operation)),
+					wrapped: serialisable(await this.#config.keks.wrap(dek, contextOf(secret), operation)),
 					wipe: () => {}
 				};
 			} finally {
@@ -1617,12 +1658,12 @@ var VaultService = class {
 			remote,
 			entry,
 			input
-		}, () => items.map(({ secret, wrapped }) => async (operation) => {
-			const key = await this.#open(wrapped, secret, operation);
+		}, (contextOf) => items.map(({ secret, wrapped }) => async (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)),
+					wrapped: serialisable(await this.#config.keks.wrap(key, contextOf(secret), operation)),
 					wipe: () => {}
 				};
 			} finally {
@@ -1679,9 +1720,9 @@ var VaultService = class {
 	* 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, secret, operation) {
+	async #open(wrapped, context, operation) {
 		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;
@@ -1705,14 +1746,24 @@ var VaultService = class {
 		if (wrongKek !== null) return this.#decide([], async () => {
 			throw new Refused(refusal("wrong_kek", wrongKek), secrets.map((secret) => entry(secret, "deny", "wrong_kek")));
 		});
+		const owners = /* @__PURE__ */ new Map();
 		const check = async (d) => {
 			const reader = through(await this.#standing(d.tx, principal, d.members.get(principal), d.at, d.reports), call.input);
 			const at = secrets.map((secret, i) => call.places?.[i] ?? secret);
 			const environments = await environmentsById(d.tx, [...secrets, ...at].map((place) => place.environmentId));
+			const parents = [...environments.values()].flatMap((environment) => environment.owner === null || environment.parentId === null ? [] : [environment.parentId]);
+			for (const [id, parent] of await environmentsById(d.tx, parents)) environments.set(id, parent);
 			const gone = (place) => environments.get(place.environmentId)?.deleted ?? false;
-			const codes = 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 = secrets.map((secret, i) => {
+				const personal = personalRefusal(reader, principal, call.permission, secret, at[i], environments);
+				if (personal !== void 0) return personal;
+				return refuses(reader, call.permission, placeIn(at[i], environments), gone(secret) || gone(at[i]));
+			});
 			if (call.vet !== void 0 && !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" && this.#config.people === "stand-ins" && principal.startsWith("user:") && HANDED_BACK.includes(call.input.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(refusal(first, MESSAGES[first]), secrets.map((secret, i) => entry(secret, "deny", codes[i] ?? first)));
 		};
@@ -1774,7 +1825,7 @@ var VaultService = class {
 				if (first === void 0 || 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 { 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) => outcomeEntry(secret, i, "deny", outcomes[i].ok ? "withheld" : outcomes[i].code));
@@ -1861,6 +1912,7 @@ var VaultService = class {
 				const source = sources.get(item.source.secretId);
 				if (source === void 0 || projectOf.get(item.holder.environmentId) !== item.holder.projectId) return "bad_claim";
 				if (source.secretId === item.holder.secretId) return "invalid";
+				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));
 			});
 			const first = codes.find((code) => code !== null) ?? null;
@@ -2965,6 +3017,7 @@ var VaultService = class {
 		let keys = [];
 		for (let after = -1n;;) {
 			const batch = await vaultEntriesAfter(tx, after, VERIFY_BATCH);
+			if (batch.length === 0) return { ok: true };
 			for (const entry of batch) {
 				const result = verifyEntries([entry], {
 					startSeq: entry.seq,
@@ -2985,7 +3038,6 @@ var VaultService = class {
 			};
 			keys = moved.keys;
 			for (const entry of batch) findings.add(entry);
-			if (batch.length < 5e3) return { ok: true };
 			after = batch[batch.length - 1].seq;
 		}
 	}
@@ -3211,6 +3263,30 @@ function validateVia(via) {
 		seq: via.seq
 	};
 }
+/** A read's fork, checked for shape: null for none. */
+function validateThrough(through) {
+	if (through === void 0 || 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, fork, viaReference) {
+	return {
+		through: {
+			environmentId: through,
+			...fork === void 0 ? {} : { slug: fork.slug }
+		},
+		...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.
@@ -3254,6 +3330,26 @@ function placeIn(place, environments) {
 * 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, principal, permission, secret, at, environments) {
+	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 void 0;
+	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;
+	return withinCredential(reader.live, permission, parent) ? null : "no_grant";
+}
 function refuses(reader, permission, where, deleted) {
 	if (reader.status === "tampered") return "tampered";
 	if (reader.status === "removed") return "removed";
@@ -3286,6 +3382,89 @@ function keyEntry(action, principal, secret, decision, code, correlation, detail
 		})
 	};
 }
+/** 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"
+];
+/**
+* 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) {
+	const groups = /* @__PURE__ */ new Map();
+	const out = [];
+	for (const entry of entries) {
+		if (entry.action !== "secret.read") {
+			out.push(entry);
+			continue;
+		}
+		const { also, through } = JSON.parse(entry.metadata ?? "{}");
+		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 !== void 0) {
+			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) {
+	const [first] = group;
+	if (group.length === 1) return first;
+	const details = group.map((entry) => JSON.parse(entry.metadata ?? "{}"));
+	const shared = Object.fromEntries(READ_SHARED.flatMap((field) => details[0][field] === void 0 ? [] : [[field, details[0][field]]]));
+	const beside = details[0].also;
+	const secrets = group.map((entry, i) => {
+		const own = Object.fromEntries(Object.entries(details[i]).filter(([field]) => !READ_SHARED.includes(field) && field !== "also"));
+		const holder = details[i].also?.secretId;
+		return {
+			...entry.secretId == null ? {} : { secretId: entry.secretId },
+			...entry.secretVersionId == null ? {} : { secretVersionId: entry.secretVersionId },
+			...own,
+			...holder === void 0 ? {} : { also: { secretId: holder } }
+		};
+	});
+	return {
+		...first,
+		secretId: null,
+		secretVersionId: null,
+		metadata: JSON.stringify({
+			...shared,
+			...beside === void 0 ? {} : { 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) {
 	return entry.decision === "allow" && entry.subjectPrincipal !== void 0 && entry.subjectPrincipal !== null && ACCESS_ACTIONS.includes(entry.action);
@@ -3366,11 +3545,13 @@ function view(grant) {
 function iso(ms) {
 	return new Date(ms).toISOString();
 }
-function context(secret) {
+/** A secret's binding context: its ids, and a personal config's owner, hashed, as the decision read it. */
+function context(secret, owner) {
 	return {
 		projectId: secret.projectId,
 		environmentId: secret.environmentId,
-		secretId: secret.secretId
+		secretId: secret.secretId,
+		...owner === void 0 ? {} : { owner }
 	};
 }
 function unwrappable(wrapped) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/vault",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "description": "coffre's vault: keys, grants and members, in the database the app uses, as a Cloudflare Worker or on Node.",
   "license": "MIT",
   "repository": {
@@ -36,8 +36,8 @@
   },
   "dependencies": {
     "drizzle-orm": "0.45.2",
-    "@coffre/core": "0.6.2",
-    "@coffre/db": "0.6.2"
+    "@coffre/core": "0.8.0",
+    "@coffre/db": "0.8.0"
   },
   "devDependencies": {
     "@types/node": "26.1.1",