@coffre/vault 0.2.0 → 0.4.0

package/dist/{vault-BexBMpZL.js → vault-CeKwkzSV.js}

@@ -2,12 +2,14 @@ import { ACCESS_ACTIONS, checkpointMessage, checkpointVerifier, describeAccessFa
 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 { allows, assignableToEnvironment, isRole, mayManageAccess } from "@coffre/core/access";
+import { allows, assignableToEnvironment, everyProjectPath, grantKind, isRole, mayManageAccess } from "@coffre/core/access";
 import { GENESIS_HASH, deriveLogKey, verifyEntries } from "@coffre/core/audit";
 import { checkContext } from "@coffre/core/envelope";
-import { SNAPSHOT, clockMillis, engineOf, forUpdate, isUniqueViolation } from "@coffre/db/dialect";
+import { shownMember } from "@coffre/core/schemas";
+import { SNAPSHOT, clockMillis, engineOf, forUpdate, isUniqueViolation, tombstone, truth } from "@coffre/db/dialect";
 import { appendEntries, lockLogHead } from "@coffre/db/log";
-import { and, asc, count, desc, eq, gt, gte, inArray, isNull, lt, lte, sql } from "drizzle-orm";
+import { insertGrant, readGrants } from "@coffre/db/grants";
+import { and, asc, count, desc, eq, gt, gte, inArray, isNull, lt, lte, or, sql } from "drizzle-orm";
 //#region src/accounting.ts
 const KEY_ACTIONS = /* @__PURE__ */ new Set([
 	"secret.read",
@@ -228,29 +230,35 @@ async function updateMember(tx, principal, change) {
 	await tx.update(vaultMembers).set(change).where(eq(vaultMembers.principal, principal));
 }
 /** Grants, lapsed ones too, each with its project, which an environment's grant finds through `environments`. */
-async function grants(db, principal) {
-	const { vaultGrants, environments } = tablesOf(db);
-	return db.select({
-		principal: vaultGrants.principal,
-		projectId: sql`coalesce(${vaultGrants.projectId}, ${environments.projectId})`,
-		environmentId: vaultGrants.environmentId,
-		role: vaultGrants.role,
-		expiresAt: vaultGrants.expiresAt,
-		grantedAt: vaultGrants.grantedAt,
-		grantedBy: vaultGrants.grantedBy
-	}).from(vaultGrants).leftJoin(environments, eq(environments.id, vaultGrants.environmentId)).where(principal === void 0 ? void 0 : eq(vaultGrants.principal, principal));
-}
-/** A grant names its environment, or its project when it has none: exactly one. */
+function grants(db, principal) {
+	return readGrants(db, principal === void 0 ? {} : { principal });
+}
+/**
+* A grant's row names its environment, or its project when it has none, or
+* neither on every project, with the slug it covers there, if any.
+*/
 function at(db, place) {
 	const { vaultGrants } = tablesOf(db);
-	return place.environmentId === null ? and(eq(vaultGrants.projectId, place.projectId), isNull(vaultGrants.environmentId)) : eq(vaultGrants.environmentId, place.environmentId);
+	if (place.environmentId !== null) return eq(vaultGrants.environmentId, place.environmentId);
+	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));
 }
-async function insertGrant(tx, grant) {
-	const { vaultGrants } = tablesOf(tx);
-	await tx.insert(vaultGrants).values({
-		...grant,
-		projectId: grant.environmentId === null ? grant.projectId : null
-	});
+/**
+* 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);
+	const rows = await db.select({
+		id: environments.id,
+		projectId: environments.projectId,
+		slug: environments.slug,
+		deleted: truth(or(tombstone(environments.slug), tombstone(projects.slug)))
+	}).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]));
 }
 async function deleteGrant(tx, principal, place) {
 	const { vaultGrants } = tablesOf(tx);
@@ -276,7 +284,7 @@ async function wrappedUnder(db, provider, keyId, limit) {
 		kekId: secretVersions.kekId,
 		kekVersion: secretVersions.kekVersion,
 		bytes: secretVersions.wrappedDek
-	}).from(secretVersions).innerJoin(secrets, eq(secrets.id, secretVersions.secretId)).where(and(eq(secretVersions.kekProvider, provider), eq(secretVersions.kekId, keyId))).orderBy(desc(secretVersions.createdAt)).limit(limit)).map((row) => ({
+	}).from(secretVersions).innerJoin(secrets, eq(secrets.id, secretVersions.secretId)).where(and(eq(secretVersions.kekProvider, provider), eq(secretVersions.kekId, keyId), sealed$1(secretVersions.wrappedDek))).orderBy(desc(secretVersions.createdAt)).limit(limit)).map((row) => ({
 		...row,
 		bytes: Buffer.from(row.bytes)
 	}));
@@ -284,13 +292,18 @@ async function wrappedUnder(db, provider, keyId, limit) {
 /** Of these projects and environments, the ones that exist, each environment with its project. */
 async function places(db, projectIds, environmentIds) {
 	const { projects, environments } = tablesOf(db);
-	const [foundProjects, foundEnvironments] = await Promise.all([projectIds.length === 0 ? [] : db.select({ id: projects.id }).from(projects).where(inArray(projects.id, [...projectIds])), environmentIds.length === 0 ? [] : db.select({
+	const [foundProjects, foundEnvironments] = await Promise.all([projectIds.length === 0 ? [] : db.select({
+		id: projects.id,
+		deleted: truth(tombstone(projects.slug))
+	}).from(projects).where(inArray(projects.id, [...projectIds])), environmentIds.length === 0 ? [] : db.select({
 		id: environments.id,
-		projectId: environments.projectId
-	}).from(environments).where(inArray(environments.id, [...environmentIds]))]);
+		projectId: environments.projectId,
+		deleted: truth(or(tombstone(environments.slug), tombstone(projects.slug)))
+	}).from(environments).innerJoin(projects, eq(projects.id, environments.projectId)).where(inArray(environments.id, [...environmentIds]))]);
 	return {
 		projects: new Set(foundProjects.map((row) => row.id)),
-		environments: new Map(foundEnvironments.map((row) => [row.id, row.projectId]))
+		environments: new Map(foundEnvironments.map((row) => [row.id, row.projectId])),
+		deleted: new Set([...foundProjects, ...foundEnvironments].filter((row) => row.deleted).map((row) => row.id))
 	};
 }
 /** The action of an entry that releases a key, which the bulk limit counts. */
@@ -387,6 +400,52 @@ async function firstVaultEntryUnder(db, keyId) {
 	const [row] = await db.select({ seq: auditLog.seq }).from(auditLog).where(and(eq(auditLog.author, "vault"), eq(auditLog.keyId, keyId))).orderBy(asc(auditLog.seq)).limit(1);
 	return row?.seq;
 }
+/** The entries at these seqs, any author, by seq: what a reference names as its seal. */
+async function entriesAt(db, seqs) {
+	if (seqs.length === 0) return /* @__PURE__ */ new Map();
+	const { auditLog } = tablesOf(db);
+	const rows = stored(await db.select(entryColumns(db)).from(auditLog).where(inArray(auditLog.seq, [...new Set(seqs)])));
+	return new Map(rows.map((row) => [row.seq, row]));
+}
+/**
+* Which of these `reference.create` entries a `reference.end` of the
+* vault's names, allowed: one read through `audit_log_reference_end_idx`.
+* An end that fails its MAC still ends: putting a reference back takes
+* more than a forged end can undo, and refusing is the safe side.
+*/
+async function endedReferences(db, seqs) {
+	if (seqs.length === 0) return /* @__PURE__ */ new Set();
+	const { auditLog } = tablesOf(db);
+	const rows = await db.select({ relatedSeq: auditLog.relatedSeq }).from(auditLog).where(and(eq(auditLog.author, "vault"), eq(auditLog.action, "reference.end"), eq(auditLog.decision, "allow"), inArray(auditLog.relatedSeq, [...new Set(seqs)])));
+	return new Set(rows.map((row) => row.relatedSeq));
+}
+/** The project each environment is in: a holder's ids, checked against each other. */
+async function projectsOfEnvironments(db, ids) {
+	if (ids.length === 0) return /* @__PURE__ */ new Map();
+	const { environments } = tablesOf(db);
+	const rows = await db.select({
+		id: environments.id,
+		projectId: environments.projectId
+	}).from(environments).where(inArray(environments.id, [...new Set(ids)]));
+	return new Map(rows.map((row) => [row.id, row.projectId]));
+}
+async function secretsByIds(db, ids) {
+	if (ids.length === 0) return /* @__PURE__ */ new Map();
+	const { secrets, environments, projects } = tablesOf(db);
+	const rows = await db.select({
+		secretId: secrets.id,
+		projectId: secrets.projectId,
+		environmentId: secrets.environmentId,
+		project: projects.slug,
+		environment: environments.slug,
+		key: secrets.key,
+		currentVersionId: secrets.currentVersionId
+	}).from(secrets).innerJoin(environments, eq(environments.id, secrets.environmentId)).innerJoin(projects, eq(projects.id, secrets.projectId)).where(inArray(secrets.id, [...new Set(ids)]));
+	return new Map(rows.map(({ project, environment, key, ...row }) => [row.secretId, {
+		...row,
+		path: `${project}/${environment}/${key}`
+	}]));
+}
 /** The vault's newest entry of any of these actions, allowed, or undefined. */
 async function latestVaultEntry(db, actions) {
 	const { auditLog } = tablesOf(db);
@@ -410,6 +469,14 @@ async function vaultEntriesOf(db, actions, afterSeq, limit) {
 	const { auditLog } = tablesOf(db);
 	return stored(await db.select(entryColumns(db)).from(auditLog).where(and(eq(auditLog.author, "vault"), inArray(auditLog.action, [...actions]), eq(auditLog.decision, "allow"), gt(auditLog.seq, afterSeq))).orderBy(asc(auditLog.seq)).limit(limit));
 }
+/**
+* A version that still holds its wrapped key. A deleted place's versions are
+* erased, their keys emptied: there is nothing left to open, or to try a
+* vault key on.
+*/
+function sealed$1(wrappedDek) {
+	return sql`length(${wrappedDek}) > 0`;
+}
 async function versions(db, ids) {
 	if (ids.length === 0) return [];
 	const { secretVersions, secrets, environments, projects } = tablesOf(db);
@@ -425,9 +492,13 @@ async function versions(db, ids) {
 		kekProvider: secretVersions.kekProvider,
 		kekId: secretVersions.kekId,
 		kekVersion: secretVersions.kekVersion,
-		wrappedDek: secretVersions.wrappedDek
-	}).from(secretVersions).innerJoin(secrets, eq(secrets.id, secretVersions.secretId)).innerJoin(environments, eq(environments.id, secrets.environmentId)).innerJoin(projects, eq(projects.id, secrets.projectId)).where(inArray(secretVersions.id, [...new Set(ids)]))).map((row) => ({
+		wrappedDek: secretVersions.wrappedDek,
+		deleted: truth(or(tombstone(environments.slug), tombstone(projects.slug))),
+		currentVersionId: secrets.currentVersionId,
+		newest: sql`(SELECT max(newest.version) FROM secret_versions newest WHERE newest.secret_id = ${secretVersions.secretId})`
+	}).from(secretVersions).innerJoin(secrets, eq(secrets.id, secretVersions.secretId)).innerJoin(environments, eq(environments.id, secrets.environmentId)).innerJoin(projects, eq(projects.id, secrets.projectId)).where(and(inArray(secretVersions.id, [...new Set(ids)]), or(sealed$1(secretVersions.wrappedDek), tombstone(environments.slug), tombstone(projects.slug))))).map((row) => ({
 		id: row.id,
+		deleted: row.deleted,
 		secret: {
 			projectId: row.projectId,
 			environmentId: row.environmentId,
@@ -440,7 +511,8 @@ async function versions(db, ids) {
 			kekId: row.kekId,
 			kekVersion: row.kekVersion,
 			bytes: row.wrappedDek.toString("base64")
-		}
+		},
+		current: row.currentVersionId === row.id && Number(row.newest) === row.version
 	}));
 }
 //#endregion
@@ -635,10 +707,7 @@ function replayFault(state, rows, storedGrants, at) {
 function apply(state, row) {
 	const principal = row.subjectPrincipal;
 	const detail = JSON.parse(row.metadata);
-	const place = {
-		projectId: row.projectId,
-		environmentId: row.environmentId
-	};
+	const place = placeOf(row, detail);
 	const grantsOf = state.held.get(principal) ?? /* @__PURE__ */ new Map();
 	state.held.set(principal, grantsOf);
 	const before = state.members.get(principal);
@@ -691,7 +760,7 @@ function apply(state, row) {
 			return null;
 		}
 		case "access.grant":
-			grantsOf.set(placeKey(place), {
+			grantsOf.set(placeKey$1(place), {
 				principal,
 				...place,
 				role: detail.role,
@@ -705,7 +774,7 @@ function apply(state, row) {
 			});
 			return null;
 		case "access.revoke":
-			grantsOf.delete(placeKey(place));
+			grantsOf.delete(placeKey$1(place));
 			if (before !== void 0) state.members.set(principal, {
 				...before,
 				accessSeq: row.seq
@@ -725,15 +794,32 @@ const MEMBER_FIELDS = [
 	["statusChangedBy", "status_changed_by"],
 	["accessSeq", "access_seq"]
 ];
-/** A grant's place: its environment, or its project when it has none. */
-function placeKey(place) {
-	return place.environmentId ?? place.projectId;
+/**
+* The place an access entry is about: its project and environment, or, with
+* neither, every project, which it names as a path (`*`, or `*` and a slug).
+*/
+function placeOf(row, detail) {
+	if (row.projectId !== null || row.environmentId !== null) return {
+		projectId: row.projectId,
+		environmentId: row.environmentId,
+		environmentSlug: null
+	};
+	return {
+		projectId: null,
+		environmentId: null,
+		environmentSlug: (typeof detail.place === "string" ? detail.place.split("/")[1] : void 0) ?? null
+	};
+}
+/** A grant's place: its environment, or its project when it has none, or every project's path. */
+function placeKey$1(place) {
+	return place.environmentId ?? place.projectId ?? everyProjectPath(place.environmentSlug);
 }
 function grantKey(grant) {
 	return JSON.stringify([
 		grant.principal,
 		grant.projectId,
 		grant.environmentId,
+		grant.environmentSlug,
 		grant.role,
 		grant.expiresAt,
 		grant.grantedAt,
@@ -741,11 +827,12 @@ function grantKey(grant) {
 	]);
 }
 function faultGrant(key) {
-	const [principal, projectId, environmentId, role] = JSON.parse(key);
+	const [principal, projectId, environmentId, environmentSlug, role] = JSON.parse(key);
 	return {
 		principal,
 		projectId,
 		environmentId,
+		environmentSlug,
 		role
 	};
 }
@@ -768,11 +855,17 @@ function faultGrant(key) {
 function rowKey(signingKey) {
 	return Buffer.from(hkdfSync("sha256", signingKey, /* @__PURE__ */ new Uint8Array(0), "coffre.vault.rows.v1", 32));
 }
-/** A member's grants as the MAC covers them: each one's place, role, end and grant, as a sorted set. */
+/**
+* A member's grants as the MAC covers them: each one's place, role, end and
+* grant, as a sorted set. A grant is kept by what its row names first: its
+* environment, its project, or neither, which is a grant on every project,
+* with the slug it covers, or null. A member who holds none of those has the
+* set, and so the MAC, they had before there were any.
+*/
 function grantSet(grants) {
 	return grants.map((grant) => [
-		grant.environmentId === null ? "project" : "environment",
-		grant.environmentId ?? grant.projectId,
+		grant.environmentId !== null ? "environment" : grant.projectId !== null ? "project" : "every-project",
+		grant.environmentId ?? grant.projectId ?? grant.environmentSlug,
 		grant.role,
 		grant.expiresAt,
 		grant.grantedAt,
@@ -847,8 +940,8 @@ function openVault(db, prepared) {
 const KEY_BUDGET_MS = 5e3;
 /** How long a decision waits for a lock: above the key budget, so a removal outwaits a read in flight. */
 const LOCK_TIMEOUT_MS = 15e3;
-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";
 /** How many stored keys a KEK with no check yet is tried on: one that opens proves it. */
@@ -907,6 +1000,8 @@ const MESSAGES = {
 	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",
@@ -979,14 +1074,15 @@ var VaultService = class {
 					touched: /* @__PURE__ */ new Set(),
 					grants: /* @__PURE__ */ new Map(),
 					reports,
-					after: []
+					after: [],
+					underLock: []
 				};
 				const result = await decide(d);
 				const entries = [...reports, ...d.log];
 				let at = d.at;
 				const accessSeq = /* @__PURE__ */ new Map();
 				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));
@@ -1204,33 +1300,57 @@ var VaultService = class {
 	* that an instance still running with the replaced KEK, as during a
 	* deploy, cannot write after the rotation.
 	*/
-	#append(tx, entries) {
+	#append(tx, entries, underLock = []) {
 		const prepared = this.#prepared;
 		return appendEntries(tx, prepared.logKey, entries, async (locked) => {
 			const rotation = await latestVaultEntry(locked, [KEY_ROTATE]);
-			if (rotation === void 0 || 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 !== void 0 && !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);
 		});
 	}
 	async unwrap(input) {
 		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;
+		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, decision, code) => ({
-			...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, decision, code) => {
+			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)
+			};
+		};
+		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),
+			places: sealed.map((seal, i) => seal?.holder ?? items[i].secret),
+			vet: ends.length === 0 ? void 0 : async (db) => {
+				const ended = await endedReferences(db, ends);
+				return sealed.map((seal) => seal !== null && ended.has(seal.seq) ? "ended" : null);
+			},
 			remote,
 			entry,
 			input
@@ -1287,7 +1407,7 @@ var VaultService = class {
 		}));
 		validateItems(items, "wrapped");
 		const sameSecret = (secret, source) => 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) => ({
+		if (items.some((item, i) => !sameSecret(item.secret, loaded.versions[i].secret))) return this.#refuseVersions(principal, "bad_claim", loaded.versions.map((source) => ({
 			...keyEntry("key.rewrap", principal, source.secret, "deny", "bad_claim", input),
 			secretVersionId: source.id
 		})));
@@ -1321,14 +1441,18 @@ var VaultService = class {
 			seqs: []
 		}));
 	}
-	/** 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, action, detail = {}) {
 		validateText(input.principal);
 		validateCorrelation(input);
 		const ids = input.items.map((item) => item.secretVersionId);
 		for (const id of ids) if (typeof id !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(id)) throw new Error("secret version id must be a lowercase UUID");
 		const found = new Map((await versions(this.#db, ids)).map((version) => [version.id, version]));
-		if (ids.some((id) => !found.has(id))) return this.#badVersions(input.principal, ids.map((id) => {
+		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.#refuseVersions(input.principal, "bad_claim", ids.map((id) => {
 			const version = found.get(id);
 			if (version === void 0) return {
 				actor: input.principal,
@@ -1353,10 +1477,10 @@ var VaultService = class {
 			versions: ids.map((id) => found.get(id))
 		};
 	}
-	async #badVersions(principal, entries) {
+	async #refuseVersions(principal, code, entries) {
 		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);
 		});
 	}
 	/**
@@ -1393,7 +1517,11 @@ var VaultService = class {
 		if (this.#isRootAdmin(principal)) await this.#rootRow(principal);
 		const check = async (d) => {
 			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));
+			const at = secrets.map((secret, i) => call.places?.[i] ?? secret);
+			const environments = await environmentsById(d.tx, [...secrets, ...at].map((place) => place.environmentId));
+			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])));
+			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" && 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)));
@@ -1449,6 +1577,13 @@ var VaultService = class {
 				if (error instanceof Refused) throw new Refused(error.refusal, secrets.map((secret, item) => outcomeEntry(secret, item, "deny", error.entries[item].code ?? error.refusal.code)));
 				throw error;
 			}
+			const { vet } = call;
+			if (vet !== void 0) d.underLock.push(async (locked) => {
+				const codes = await vet(locked);
+				const first = codes.find((code) => code !== null);
+				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 done = outcomes.flatMap((outcome) => outcome.ok ? [outcome.value] : []);
 			try {
@@ -1459,6 +1594,10 @@ var VaultService = class {
 				if (unanswered > 0) throw new Outage(new KekUnavailableError(`the key service did not answer for ${unanswered} of ${secrets.length} keys`, outcomes.some((outcome) => !outcome.ok && outcome.code === "kms_uncertain")), entries());
 				if (expired) throw new Outage(new KekUnavailableError("key operation exceeded its deadline"), entries());
 				if (done.length < outcomes.length) throw new Refused(refusal("bad_claim", MESSAGES.bad_claim), entries());
+				await lockLogHead(d.tx);
+				const places = secrets.flatMap((secret, i) => [secret, call.places?.[i] ?? secret]);
+				const now = await 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);
@@ -1474,6 +1613,174 @@ var VaultService = class {
 		const { count, windowMs } = this.#config.bulkLimit;
 		return await releasesSince(d.tx, principal, d.at - windowMs) + n > count;
 	}
+	/**
+	* 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) {
+		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([secretsByIds(this.#db, items.map((item) => item.source.secretId)), projectsOfEnvironments(this.#db, items.map((item) => item.holder.environmentId))]);
+		const entry = (item, decision, code) => {
+			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,
+				metadata: JSON.stringify({
+					reference: item.id,
+					subject: item.holder.path,
+					secretId: item.holder.secretId,
+					source: source === void 0 ? { secretId: item.source.secretId } : { path: source.path },
+					...source === void 0 ? {} : { 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);
+			const environments = await environmentsById(d.tx, items.flatMap((item) => {
+				const source = sources.get(item.source.secretId);
+				return source === void 0 ? [item.holder.environmentId] : [item.holder.environmentId, source.environmentId];
+			}));
+			const gone = (place) => environments.get(place.environmentId)?.deleted ?? false;
+			const codes = items.map((item) => {
+				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";
+				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)));
+			d.underLock.push(async (locked) => {
+				if (![...(await environmentsById(locked, [...environments.keys()])).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: [] };
+			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) {
+		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);
+		const holders = await secretsByIds(this.#db, sealed.flatMap((seal) => seal === null ? [] : [seal.holder.secretId]));
+		const entry = (via, seal, decision, code) => ({
+			actor: principal,
+			action: "reference.end",
+			decision,
+			code,
+			projectId: seal?.holder.projectId ?? null,
+			environmentId: seal?.holder.environmentId ?? null,
+			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;
+		const ended = async (db) => {
+			const done = await endedReferences(db, seals.map((seal) => seal.seq));
+			return seals.map((seal) => done.has(seal.seq) ? "ended" : null);
+		};
+		return this.#decide([principal], async (d) => {
+			const actor = await this.#standing(d.tx, principal, d.members.get(principal), d.at, d.reports);
+			const environments = await environmentsById(d.tx, seals.map((seal) => seal.holder.environmentId));
+			const codes = seals.map((seal) => {
+				const holder = refuses(actor, "secret.write", placeIn(seal.holder, environments), false);
+				if (reason === "abandoned" && seal.createdBy !== principal) return "not_allowed";
+				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)));
+			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: [] };
+			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) {
+		const found = await 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 === void 0 || entry.author !== "vault" || entry.action !== "reference.create" || entry.decision !== "allow") return null;
+			if (!this.#authentic(entry)) return null;
+			return sealedReference(entry, via.reference);
+		});
+	}
 	#isRootAdmin(principal) {
 		return principal.startsWith("user:") && this.#config.rootAdmins.includes(principal.slice(5));
 	}
@@ -1560,7 +1867,7 @@ var VaultService = class {
 			fault,
 			stored: grants$1
 		};
-		if (!LIVE_PRINCIPAL.test(principal)) return {
+		if (!PRINCIPAL.test(principal)) return {
 			principal,
 			status: "unknown",
 			live: none,
@@ -1609,10 +1916,10 @@ var VaultService = class {
 			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:"),
@@ -1676,34 +1983,55 @@ var VaultService = class {
 	}
 	setAccess(input) {
 		const { actor, principal } = input;
-		const action = input.changes.every((change) => change.role === null) ? "access.revoke" : "access.grant";
-		const [only] = input.changes.length === 1 ? input.changes : [];
-		const refused = (code, message = MESSAGES[code]) => new Refused(refusal(code, message), [{
-			...accessEntry(actor, action, principal, "deny", input, { changes: input.changes }, code),
-			...only === void 0 || code === "invalid" ? {} : {
-				projectId: only.projectId,
-				environmentId: only.environmentId
-			}
+		const changes = input.changes.map((change) => ({
+			...change,
+			environmentSlug: change.environmentSlug ?? null
+		}));
+		const action = changes.every((change) => change.role === null) ? "access.revoke" : "access.grant";
+		const [only] = changes.length === 1 ? changes : [];
+		const refused = (code, message = MESSAGES[code]) => {
+			const where = only === void 0 || 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$1 = /* @__PURE__ */ new Set();
-			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$1.has(key)) throw refused("invalid", "each place may be changed once per call");
 				places$1.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");
 			}
-			const known = await places(d.tx, input.changes.map((change) => change.projectId), input.changes.flatMap((change) => change.environmentId === null ? [] : [change.environmentId]));
-			for (const { projectId, environmentId } of input.changes) if (!known.projects.has(projectId) || environmentId !== null && known.environments.get(environmentId) !== projectId) throw refused("invalid", `no such place: ${environmentId === null ? projectId : `${projectId}/${environmentId}`}`);
+			if (onProjects.length > 0) await lockLogHead(d.tx);
+			const known = await places(d.tx, onProjects.map((change) => change.projectId), onProjects.flatMap((change) => change.environmentId === null ? [] : [change.environmentId]));
+			for (const { projectId, environmentId, role } of onProjects) {
+				if (!known.projects.has(projectId) || environmentId !== null && known.environments.get(environmentId) !== projectId) throw refused("invalid", `no such place: ${environmentId === null ? projectId : `${projectId}/${environmentId}`}`);
+				if (role !== null && (known.deleted.has(projectId) || environmentId !== null && known.deleted.has(environmentId))) throw refused("deleted");
+			}
 			const acting = await this.#standing(d.tx, actor, d.members.get(actor), d.at, d.reports);
 			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);
 			if (subject.status === "tampered") throw refused("tampered", TAMPERED_SUBJECT);
@@ -1711,27 +2039,30 @@ var VaultService = class {
 			if (row === void 0) throw refused("not_a_member");
 			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 };
 		});
 	}
 	/** One place's change, logged when it changes what is live. */
 	#apply(d, actor, principal, held, change, correlation) {
-		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 !== void 0 && live(existing, d.at) ? existing : void 0;
 		const expiresAt = change.expiresAt === null ? null : Date.parse(change.expiresAt);
 		const place = {
 			projectId: change.projectId,
-			environmentId: change.environmentId
+			environmentId: change.environmentId,
+			environmentSlug: change.environmentSlug
 		};
+		const where = located(place);
 		const entry = (action, role) => d.log.push({
 			...accessEntry(actor, action, principal, "allow", correlation, {
 				role,
 				expiresAt: expiresAt === null ? null : iso(expiresAt),
-				previousRole: current?.role ?? null
+				previousRole: current?.role ?? null,
+				...where.detail
 			}),
-			...place
+			...where.ids
 		});
 		const clear = () => {
 			if (existing === void 0) return;
@@ -1772,7 +2103,7 @@ var VaultService = class {
 			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");
 			const row = d.members.get(principal);
@@ -1826,7 +2157,7 @@ var VaultService = class {
 		const refused = (code, message = MESSAGES[code]) => 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);
@@ -1841,15 +2172,18 @@ var VaultService = class {
 			if (!holder.isOwner) throw refused("not_allowed", "only owners may remove members");
 			if (row?.status !== "active") throw refused(row === void 0 ? "not_a_member" : "removed");
 			const revoked = held.filter((grant) => live(grant, d.at));
-			for (const grant of revoked) d.log.push({
-				...accessEntry(actor, "access.revoke", principal, "allow", input, {
-					role: null,
-					expiresAt: null,
-					previousRole: grant.role
-				}),
-				projectId: grant.projectId,
-				environmentId: grant.environmentId
-			});
+			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
+					}),
+					...where.ids
+				});
+			}
 			const generation = row.generation + 1;
 			d.log.push(accessEntry(actor, "member.remove", principal, "allow", input, {
 				revoked: revoked.length,
@@ -2428,15 +2762,96 @@ function validateItems(items, field) {
 		}
 	}
 }
-/** Why `reader` may not do `permission` on `secret`, or null if they may. */
-function refuses(reader, permission, secret) {
+/** What a genuine `reference.create` entry seals, if it is about `reference`; null if not, or malformed. */
+function sealedReference(entry, reference) {
+	let detail;
+	try {
+		detail = JSON.parse(entry.metadata);
+	} catch {
+		return null;
+	}
+	const text = (value) => 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
+		},
+		createdBy: entry.actor,
+		createdAt: entry.occurredAt
+	};
+}
+/** A read's reference, checked for shape: null for none. */
+function validateVia(via) {
+	if (via === void 0 || 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, seal) {
+	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
+		}
+	};
+}
+/**
+* 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, environments) {
+	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, permission, where, deleted) {
 	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;
 	return allows(reader.all, permission, where) ? "expired" : "no_grant";
 }
@@ -2491,10 +2906,42 @@ function accessEntry(actor, action, principal, decision, correlation, detail, co
 function live(grant, at) {
 	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) {
+	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) {
+	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) {
+	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) {
 	return {
 		projectId: grant.projectId,
 		environmentId: grant.environmentId,
+		environmentSlug: grant.environmentSlug,
 		role: grant.role,
 		expiresAt: grant.expiresAt === null ? null : iso(grant.expiresAt),
 		grantedAt: iso(grant.grantedAt),