@coffre/vault 0.8.2 → 0.10.0

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

@@ -1,14 +1,14 @@
-import { ACCESS_ACTIONS, HANDED_BACK, checkpointMessage, checkpointVerifier, describeAccessFault } from "@coffre/core/vault";
+import { ACCESS_ACTIONS, POLICY_REVISION, checkpointMessage, checkpointVerifier, describeAccessFault, handsBack, policyRevision } 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, withinCredential } from "@coffre/core/access";
+import { DEFAULT_POLICY, EVERYWHERE, EVERY_ENVIRONMENT, FIXED_ROLES, INSTANCE_ROLES, NOTHING, PROJECT_ONLY_PERMISSIONS, ROLES, ROLE_ID, UNWRITTEN_FORK_MS, allows, assignableToEnvironment, definitionProblem, givesService, grantKind, isBuiltinRole, isCredentialScope, isInstanceRole, isRole, isScope, managesService, mayManageAccess, normalDefinition, normalScope, ownsInstance, runsInstance, setsUpServices, unscoped, withinCredential } from "@coffre/core/access";
 import { GENESIS_HASH, deriveLogKey, verifyEntries } from "@coffre/core/audit";
 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, withinBytes } from "@coffre/db/log";
+import { LOOK_BACK, appendEntries, entryColumns, lockLogHead, newestAuthentic, newestVaultEntries, newestVaultSeq, 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([
@@ -456,6 +456,12 @@ async function endedReferences(db, seqs) {
 	return new Set(rows.map((row) => row.relatedSeq));
 }
 /** The project each environment is in: a holder's ids, checked against each other. */
+/** Whether a project of this id is there, and not deleted. */
+async function projectLive(db, id) {
+	const { projects } = tablesOf(db);
+	const rows = await db.select({ deleted: truth(tombstone(projects.slug)) }).from(projects).where(eq(projects.id, id));
+	return rows.length > 0 && !rows[0].deleted;
+}
 async function projectsOfEnvironments(db, ids) {
 	if (ids.length === 0) return /* @__PURE__ */ new Map();
 	const { environments } = tablesOf(db);
@@ -482,6 +488,41 @@ async function secretsByIds(db, ids) {
 		path: `${project}/${environment}/${key}`
 	}]));
 }
+/**
+* Each secret's nature, as its current version has it: plain where its
+* value is stored as it is, sensitive where it is bound so, and otherwise
+* secret, as is one with no value of its own.
+*/
+async function natures(db, secretIds) {
+	if (secretIds.length === 0) return /* @__PURE__ */ new Map();
+	const { secrets, secretVersions } = tablesOf(db);
+	const rows = await db.select({
+		id: secrets.id,
+		sensitive: secretVersions.sensitive,
+		plain: truth(isNotNull(secretVersions.plaintext))
+	}).from(secrets).innerJoin(secretVersions, eq(secretVersions.id, secrets.currentVersionId)).where(inArray(secrets.id, [...new Set(secretIds)]));
+	return new Map(rows.map((row) => [row.id, Boolean(row.sensitive) ? "sensitive" : Boolean(row.plain) ? "plain" : "secret"]));
+}
+/**
+* For each version a rewrap would bring back into its secret, its nature
+* as stored when it is an old value, not the secret's current one; null
+* for the current one, which a mark wraps again with no value changing.
+*/
+async function restoredNatures(db, items) {
+	if (items.length === 0) return [];
+	const { secrets, secretVersions } = tablesOf(db);
+	const [current, versions] = await Promise.all([db.select({
+		id: secrets.id,
+		version: secrets.currentVersionId
+	}).from(secrets).where(inArray(secrets.id, [...new Set(items.map((item) => item.secretId))])), db.select({
+		id: secretVersions.id,
+		sensitive: secretVersions.sensitive,
+		plain: truth(isNotNull(secretVersions.plaintext))
+	}).from(secretVersions).where(inArray(secretVersions.id, [...new Set(items.map((item) => item.from))]))]);
+	const currentOf = new Map(current.map((row) => [row.id, row.version]));
+	const natureOf = new Map(versions.map((row) => [row.id, Boolean(row.sensitive) ? "sensitive" : Boolean(row.plain) ? "plain" : "secret"]));
+	return items.map(({ secretId, from }) => currentOf.get(secretId) === from ? null : natureOf.get(from) ?? "secret");
+}
 /** The vault's newest entry of any of these actions, allowed, or undefined. */
 async function latestVaultEntry(db, actions) {
 	const { auditLog } = tablesOf(db);
@@ -500,6 +541,19 @@ 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));
 }
+/** Which of these secrets' newest versions are sensitive, by the versions' own order. */
+async function newestSensitive(db, secretIds) {
+	if (secretIds.length === 0) return /* @__PURE__ */ new Set();
+	const { secretVersions } = tablesOf(db);
+	const rows = await db.select({ secretId: secretVersions.secretId }).from(secretVersions).where(and(inArray(secretVersions.secretId, [...new Set(secretIds)]), eq(secretVersions.sensitive, true), sql`${secretVersions.version} = (SELECT max(newest.version) FROM secret_versions newest WHERE newest.secret_id = ${secretVersions.secretId})`));
+	return new Set(rows.map((row) => row.secretId));
+}
+/** How many grants name `role`: all of them, or those on environments. */
+async function grantsNaming(db, role, filter = {}) {
+	const { vaultGrants } = tablesOf(db);
+	const rows = await db.select({ count: sql`count(*)` }).from(vaultGrants).where(and(eq(vaultGrants.role, role), filter.onEnvironments === true ? or(isNotNull(vaultGrants.environmentId), isNotNull(vaultGrants.environmentSlug)) : void 0));
+	return Number(rows[0]?.count ?? 0);
+}
 /**
 * 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
@@ -526,7 +580,9 @@ async function versions(db, ids) {
 		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})`
+		sensitive: secretVersions.sensitive,
+		newest: sql`(SELECT max(newest.version) FROM secret_versions newest WHERE newest.secret_id = ${secretVersions.secretId})`,
+		newestSensitive: sql`(SELECT newest.sensitive FROM secret_versions newest WHERE newest.secret_id = ${secretVersions.secretId} ORDER BY newest.version DESC LIMIT 1)`
 	}).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,
@@ -535,7 +591,8 @@ async function versions(db, ids) {
 			environmentId: row.environmentId,
 			secretId: row.secretId,
 			version: row.version,
-			path: `${row.project}/${row.environment}/${row.key}`
+			path: `${row.project}/${row.environment}/${row.key}`,
+			sensitive: row.sensitive
 		},
 		wrapped: {
 			kekProvider: row.kekProvider,
@@ -543,7 +600,8 @@ async function versions(db, ids) {
 			kekVersion: row.kekVersion,
 			bytes: row.wrappedDek.toString("base64")
 		},
-		current: row.currentVersionId === row.id && Number(row.newest) === row.version
+		current: row.currentVersionId === row.id && Number(row.newest) === row.version,
+		newestSensitive: Boolean(row.newestSensitive)
 	}));
 }
 //#endregion
@@ -1024,6 +1082,31 @@ const CHECKPOINT = "audit.checkpoint";
 const SETTINGS = "settings.change";
 /** The settings before anyone changed them: people set up service accounts anywhere they hold access. */
 const DEFAULT_SETTINGS = { serviceAccounts: EVERYWHERE };
+/** The action of the vault's entry that holds the instance's access policy, and changes it (`policy`). */
+const POLICY = "policy.change";
+const NO_EDITS = {
+	roles: {},
+	instanceRoles: {},
+	protected: []
+};
+/** A role holding nothing, which every role but Owner is under the closed policy. */
+const NOTHING_HELD = (definition) => ({
+	...definition,
+	permissions: [],
+	protected: []
+});
+/**
+* The policy when the log has some, but none the vault wrote within reach:
+* whoever inserted rows may have hidden an Owner's narrowing, so no role
+* holds anything, a service account's neither, but Owner, which holds
+* everything always and so may write the policy again.
+*/
+const CLOSED_POLICY = {
+	roles: Object.fromEntries(Object.entries(ROLES).map(([id, definition]) => [id, id === "owner" ? definition : NOTHING_HELD(definition)])),
+	instanceRoles: Object.fromEntries(Object.entries(INSTANCE_ROLES).map(([id, definition]) => [id, id === "owner" ? definition : NOTHING_HELD(definition)])),
+	protected: [EVERY_ENVIRONMENT],
+	protectedIn: {}
+};
 /** The settings when the log has some, but none the vault wrote within reach: people set up no service accounts. */
 const CLOSED_SETTINGS = { serviceAccounts: {
 	projects: { only: [] },
@@ -1067,6 +1150,8 @@ var Outage = class {
 		this.entries = entries;
 	}
 };
+/** A rewrap that would make a value less sensitive than it is. */
+const LOOSER = "a value is made less sensitive only by writing it again: an old version comes back, and a key is made stricter, as sensitive as its newest version or more";
 function refusal(code, message) {
 	return {
 		code,
@@ -1083,10 +1168,11 @@ const MESSAGES = {
 	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",
+	sensitive: "a sensitive value is never shown to anyone, Owners included: `coffre run` gives your app a placeholder for it through the credential proxy, and a service account reads it",
 	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",
+	policy_changed: "the instance's roles or protected environments changed while this was asked: try again",
 	log_broken: "the vault log does not hold from the last checkpoint",
 	wrong_kek: "this vault's key does not open the data it holds",
 	tampered: "this member's record failed the vault's integrity check"
@@ -1144,36 +1230,44 @@ var VaultService = class {
 		return await now(db) + this.#prepared.options.clockOffset();
 	}
 	/**
-	* Decide in one transaction, with `principals`' rows locked first. A
-	* `Refused` or an `Outage` rolls back all but its own entries, which
-	* commit on their own: then the refusal is the answer, and the outage
-	* fails the call.
+	* Decide in one transaction, with `principals`' rows locked first, then
+	* the log's head. A `Refused` or an `Outage` rolls back all but its own
+	* entries, which commit on their own: then the refusal is the answer, and
+	* the outage fails the call.
+	*
+	* Every change to the policy, the settings, a member or a place appends
+	* under the head, so whatever the decision reads of them stands until it
+	* commits: no decision acts on a policy read before it. A key operation
+	* alone takes the head later (`late`), once its key service has answered,
+	* which it must not wait on holding it, and decides again then (`#keys`).
 	*/
-	async #decide(principals, decide) {
+	async #decide(principals, decide, late = false) {
 		const superseded = await this.#settled();
 		if (superseded !== null) return {
 			ok: false,
 			refusal: refusal("wrong_kek", superseded)
 		};
-		return this.#decideNow(principals, decide);
+		return this.#decideNow(principals, decide, late);
 	}
 	/** `#decide`, once the vault is settled. */
-	async #decideNow(principals, decide) {
+	async #decideNow(principals, decide, late = false) {
 		const reports = [];
 		for (let attempt = 1;; attempt += 1) try {
-			return await this.#decideOnce(principals, decide, reports);
+			return await this.#decideOnce(principals, decide, reports, late);
 		} catch (error) {
 			if (attempt < 3 && (error instanceof Retry || isUniqueViolation(error))) continue;
 			throw error;
 		}
 	}
-	async #decideOnce(principals, decide, reports) {
+	async #decideOnce(principals, decide, reports, late) {
 		try {
 			const result = await this.#db.transaction(async (tx) => {
 				await boundLockWaits(tx, LOCK_TIMEOUT_MS);
+				const members = principals.length === 0 ? /* @__PURE__ */ new Map() : await lockMembers(tx, principals);
+				if (!late) await lockLogHead(tx);
 				const d = {
 					tx,
-					members: principals.length === 0 ? /* @__PURE__ */ new Map() : await lockMembers(tx, principals),
+					members,
 					at: await this.#now(tx),
 					log: [],
 					writes: [],
@@ -1367,7 +1461,6 @@ var VaultService = class {
 		const everyProject = subject.stored.filter((grant) => grant.projectId === null && grant.environmentId === null);
 		if (everyProject.length === 0) return;
 		if (await reportStands(d.tx, principal, this.#check(d.reports, principal))) return;
-		await lockLogHead(d.tx);
 		const before = roleOf(principal, row);
 		const conversion = everyProjectConversion(principal, before.role, subject.stored, d.at, await liveProjects(d.tx));
 		const after = {
@@ -1529,6 +1622,7 @@ var VaultService = class {
 	async unwrap(input) {
 		const { principal } = input;
 		validateText(input.purpose);
+		if (input.keepsSensitive !== void 0 && typeof input.keepsSensitive !== "boolean") throw new Error("keepsSensitive is true, false or absent");
 		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 });
@@ -1577,7 +1671,7 @@ var VaultService = class {
 		return this.#keys({
 			action: "secret.read",
 			principal,
-			permission: "secret.read",
+			permission: input.purpose === "use" ? "secret.use" : "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) => {
@@ -1627,7 +1721,8 @@ var VaultService = class {
 			}
 		}), (done) => ({
 			wrapped: done.map(({ wrapped }) => wrapped),
-			seqs: []
+			seqs: [],
+			sensitive: items.map(({ secret }) => secret.sensitive === true)
 		}));
 	}
 	async rewrap(input) {
@@ -1644,6 +1739,10 @@ var VaultService = class {
 			...keyEntry("key.rewrap", principal, source.secret, "deny", "bad_claim", input),
 			secretVersionId: source.id
 		})));
+		if (items.some((item, i) => item.secret.sensitive !== true && (loaded.versions[i].secret.sensitive || loaded.versions[i].newestSensitive))) return this.#refuseVersions(principal, "invalid", loaded.versions.map((source) => ({
+			...keyEntry("key.rewrap", principal, source.secret, "deny", "invalid", input),
+			secretVersionId: source.id
+		})), LOOSER);
 		const sources = new Map(items.map((item, i) => [item.secret, loaded.versions[i]]));
 		const entry = (secret, decision, code) => ({
 			...keyEntry("key.rewrap", principal, secret, decision, code, input, { from: sources.get(secret).secret.version }),
@@ -1657,9 +1756,19 @@ var VaultService = class {
 			secrets: items.map((item) => item.secret),
 			remote,
 			entry,
-			input
+			input,
+			vet: async (db) => {
+				const newest = await newestSensitive(db, items.map(({ secret }) => secret.secretId));
+				return items.map(({ secret }) => secret.sensitive !== true && newest.has(secret.secretId) ? "invalid" : null);
+			},
+			needs: async (db) => {
+				return (await restoredNatures(db, items.map(({ secret }) => ({
+					secretId: secret.secretId,
+					from: sources.get(secret).id
+				})))).map((nature) => nature === "secret" ? ["secret.read"] : nature === "sensitive" ? ["secret.use"] : null);
+			}
 		}, (contextOf) => items.map(({ secret, wrapped }) => async (operation) => {
-			const key = await this.#open(wrapped, contextOf(secret), operation);
+			const key = await this.#open(wrapped, contextOf(sources.get(secret).secret), operation);
 			if (key === null) return null;
 			try {
 				return {
@@ -1671,7 +1780,8 @@ var VaultService = class {
 			}
 		}), (done) => ({
 			wrapped: done.map(({ wrapped }) => wrapped),
-			seqs: []
+			seqs: [],
+			sensitive: items.map(({ secret }) => secret.sensitive === true)
 		}));
 	}
 	/** 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. */
@@ -1710,9 +1820,9 @@ var VaultService = class {
 			versions: ids.map((id) => found.get(id))
 		};
 	}
-	async #refuseVersions(principal, code, entries) {
+	async #refuseVersions(principal, code, entries, message = MESSAGES[code]) {
 		return this.#decide([principal], async () => {
-			throw new Refused(refusal(code, MESSAGES[code]), entries);
+			throw new Refused(refusal(code, message), entries);
 		});
 	}
 	/**
@@ -1756,14 +1866,27 @@ var VaultService = class {
 			const gone = (place) => environments.get(place.environmentId)?.deleted ?? false;
 			owners.clear();
 			for (const [id, environment] of environments) if (environment.owner !== null) owners.set(id, ownerKey(environment.owner));
+			const needs = call.needs === void 0 ? [] : await call.needs(d.tx);
 			const codes = secrets.map((secret, i) => {
 				const personal = personalRefusal(reader, principal, call.permission, secret, at[i], environments);
 				if (personal !== void 0) return personal;
+				const also = needs[i];
+				if (also != null) {
+					const place = placeIn(at[i], environments);
+					const refused = also.map((permission) => refuses(reader, permission, place, gone(secret) || gone(at[i])));
+					if (refused.every((code) => code !== null)) return refused[0];
+				}
 				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);
+			const copying = action === "secret.read" && call.input.purpose === "copy";
+			if (action === "secret.read" && principal.startsWith("user:") && handsBack({
+				purpose: call.input.purpose ?? "",
+				keepsSensitive: call.input.keepsSensitive === true
+			}) || copying && call.input.keepsSensitive !== true) secrets.forEach((secret, i) => {
+				if (codes[i] === null && secret.sensitive === true) codes[i] = "sensitive";
+			});
 			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)));
 		};
@@ -1785,7 +1908,6 @@ var VaultService = class {
 		if (call.remote) {
 			const intent = await this.#decide([principal], async (d) => {
 				await check(d);
-				await lockLogHead(d.tx);
 				const at = await this.#now(d.tx);
 				return { seq: (await this.#append(d.tx, [{
 					actor: principal,
@@ -1836,6 +1958,12 @@ var VaultService = class {
 				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);
+				try {
+					await check(d);
+				} catch (error) {
+					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 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")));
@@ -1847,7 +1975,7 @@ var VaultService = class {
 			} finally {
 				for (const value of done) value.wipe();
 			}
-		});
+		}, true);
 	}
 	/** Whether `n` more keys would take `principal` past the bulk limit; counted under their row's lock, so exactly. */
 	async #overBulkLimit(d, principal, n) {
@@ -1903,6 +2031,7 @@ var VaultService = class {
 		};
 		return this.#decide([principal], async (d) => {
 			const reader = through(await this.#standing(d.tx, principal, d.members.get(principal), d.at, d.reports), input);
+			const natures$1 = await natures(d.tx, [...sources.values()].map((source) => source.secretId));
 			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];
@@ -1913,14 +2042,11 @@ var VaultService = class {
 				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 at = placeIn(source, environments);
+				return refuses(reader, "secret.write", placeIn(item.holder, environments), gone(item.holder)) ?? refuses(reader, "secret.read", at, gone(source)) ?? (natures$1.get(source.secretId) === "sensitive" ? refuses(reader, "secret.use", at, gone(source)) : null);
 			});
 			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: [] };
@@ -1994,10 +2120,6 @@ var VaultService = class {
 			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: [] };
@@ -2071,11 +2193,11 @@ var VaultService = class {
 	/**
 	* Refuse a change that would leave `principal`, an Owner of the whole
 	* instance, no longer one, unless another is. Counted under the log's
-	* head: two changes at once, each demoting or removing a different
-	* Owner, lock different rows, and only the head puts one after the other.
+	* head, which every decision holds: two changes at once, each demoting or
+	* removing a different Owner, lock different rows, and only the head puts
+	* one after the other.
 	*/
 	async #keepAnOwner(d, actor, principal, refused) {
-		await lockLogHead(d.tx);
 		if (await this.#anOwner(d.tx, d.reports, principal) !== null) return;
 		throw refused("last_owner", actor === principal ? "you're the last Owner of the whole instance: make someone else an Owner first" : `${principal.slice(5)} is the last Owner of the whole instance: make someone else an Owner first`);
 	}
@@ -2175,24 +2297,30 @@ var VaultService = class {
 			role: grant.role
 		}));
 		const { role, scope } = roleOf(principal, row);
+		const { policy } = await this.#policyAt(db, reports, at);
+		const service = !principal.startsWith("user:");
 		return {
 			principal,
 			status: "active",
 			live: {
 				role,
 				scope,
-				grants: held.filter((grant) => live(grant, at))
+				grants: held.filter((grant) => live(grant, at)),
+				policy,
+				service
 			},
 			all: {
 				role,
 				scope,
-				grants: held
+				grants: held,
+				policy,
+				service
 			},
 			fault,
 			stored: grants$1
 		};
 	}
-	#access(principal, row, held, at, tampered) {
+	#access(principal, row, held, at, tampered, policy) {
 		const active = PRINCIPAL.test(principal) && !tampered && row?.status === "active";
 		return {
 			principal,
@@ -2204,7 +2332,8 @@ var VaultService = class {
 			},
 			grants: active ? held.filter((grant) => live(grant, at) && grantKind(grant) !== null).map(view) : [],
 			since: row ? iso(row.statusChangedAt) : null,
-			by: row?.statusChangedBy ?? null
+			by: row?.statusChangedBy ?? null,
+			policy
 		};
 	}
 	/**
@@ -2234,7 +2363,8 @@ var VaultService = class {
 				this.#now(db)
 			]);
 			const fault = await this.#integrity(db, principal, row, held, reports);
-			return this.#access(principal, row, held, at, fault !== null);
+			const { policy } = await this.#policyAt(db, reports, at);
+			return this.#access(principal, row, held, at, fault !== null, policy);
 		};
 		const found = [];
 		const quick = await read(this.#db, found).catch((error) => {
@@ -2304,12 +2434,15 @@ var VaultService = class {
 				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 && typeof change.role !== "string") throw refused("invalid", `no such role: ${String(change.role)}`);
 				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");
 			}
-			await lockLogHead(d.tx);
+			const { policy } = await this.#policyAt(d.tx, d.reports, d.at);
+			for (const change of changes) {
+				if (change.role !== null && !isRole(change.role, policy)) throw refused("invalid", `no such role: ${change.role}`);
+				if (change.role !== null && change.environmentId !== null && !assignableToEnvironment(change.role, policy)) throw refused("invalid", `${change.role} can only be granted on a project`);
+			}
 			const known = await places(d.tx, changes.map((change) => change.projectId), changes.flatMap((change) => change.environmentId === null ? [] : [change.environmentId]));
 			const where = changes.map(({ projectId, environmentId, role }) => {
 				const environment = environmentId === null ? void 0 : known.environments.get(environmentId);
@@ -2633,6 +2766,134 @@ var VaultService = class {
 		const { serviceAccounts } = JSON.parse(entry.metadata);
 		return isScope(serviceAccounts) ? { serviceAccounts } : CLOSED_SETTINGS;
 	}
+	async policy() {
+		await this.#settled();
+		const reports = [];
+		const { policy } = await this.#policyAt(this.#db, reports, await this.#now(this.#db));
+		await this.#record(reports);
+		return policy;
+	}
+	/**
+	* The policy the vault's newest `policy.change` says, by its MAC, and its
+	* edits, as of `at`: one in its name it did not write is passed over, and
+	* reported. With such entries and none of its own within reach, the
+	* policy is unreadable, and closed: every environment is protected, and
+	* no role holds anything but Owner, otherwise whoever can insert rows
+	* could unprotect them. Its edits are then unknown, not none.
+	*/
+	async #policyAt(db, reports, at) {
+		const entry = await newestAuthentic((before) => newestVaultEntries(db, POLICY, LOOK_BACK.page, before), this.#check(reports, null));
+		if (entry === "none") return {
+			policy: DEFAULT_POLICY,
+			edits: NO_EDITS,
+			readable: true
+		};
+		const edits = typeof entry === "string" ? null : readEdits(JSON.parse(entry.metadata));
+		return edits === null ? {
+			policy: CLOSED_POLICY,
+			edits: NO_EDITS,
+			readable: false
+		} : {
+			policy: await livePolicy(db, edits, at),
+			edits,
+			readable: true
+		};
+	}
+	changePolicy(input) {
+		const { actor, change, revision } = input;
+		if (revision !== void 0 && (typeof revision !== "string" || !POLICY_REVISION.test(revision))) throw new Error("revision names a policy as policyRevision writes it");
+		const at = {};
+		const entry = (decision, detail, code = null) => ({
+			actor,
+			action: POLICY,
+			decision,
+			code,
+			operationId: input.operationId ?? null,
+			requestId: input.requestId ?? null,
+			...at,
+			metadata: JSON.stringify({
+				...detail,
+				...traced(input)
+			})
+		});
+		const refused = (code, message = MESSAGES[code]) => new Refused(refusal(code, message), [entry("deny", { change: describeChange(change) }, code)]);
+		return this.#decide([actor], async (d) => {
+			validateCorrelation(input);
+			const acting = through(await this.#standing(d.tx, actor, d.members.get(actor), d.at, d.reports), input);
+			if (acting.status === "tampered") throw refused("tampered");
+			if (acting.status !== "active") throw refused(acting.status === "removed" ? "removed" : "not_a_member");
+			const newest = await newestVaultSeq(d.tx, POLICY);
+			const { policy: before, edits, readable } = await this.#policyAt(d.tx, d.reports, d.at);
+			if (revision !== void 0 && policyRevision(newest, before) !== revision) throw refused("policy_changed");
+			const owner = acting.live.credentialScope == null && ownsInstance(acting.live);
+			if (!readable && !owner) throw refused("not_allowed", "the vault cannot read its own policy: only an Owner of the whole instance writes it again, from the roles as they ship");
+			const next = {
+				roles: { ...edits.roles },
+				instanceRoles: { ...edits.instanceRoles },
+				protected: edits.protected.filter((place) => before.protected.includes(place.environmentId)).map((place) => ({ ...place }))
+			};
+			if (change?.kind === "role" || change?.kind === "instance-role") {
+				if (!owner) throw refused("not_allowed", "only an Owner of the whole instance edits roles");
+				const instance = change.kind === "instance-role";
+				const fixed = instance ? FIXED_ROLES.instanceRoles.includes(change.role) : FIXED_ROLES.roles.includes(change.role);
+				if (typeof change.role !== "string" || fixed) throw refused("invalid", `${change.role} is not edited: it holds ${change.role === "member" ? "nothing" : "everything"}, always`);
+				if (instance && !isInstanceRole(change.role)) throw refused("invalid", `no instance role ${change.role}: an Owner makes project roles`);
+				if (!instance && !isBuiltinRole(change.role) && !ROLE_ID.test(change.role)) throw refused("invalid", "a role is named by lowercase letters, digits and dashes, 2 to 32, starting with a letter");
+				const table = instance ? next.instanceRoles : next.roles;
+				if (change.definition === null) {
+					if (!instance && !isBuiltinRole(change.role)) {
+						if (table[change.role] === void 0) throw refused("invalid", `no role ${change.role}`);
+						const held = await grantsNaming(d.tx, change.role);
+						if (held > 0) throw refused("invalid", `${held === 1 ? "1 grant names" : `${held} grants name`} ${change.role}: revoke ${held === 1 ? "it" : "them"} first`);
+					}
+					const shipped = instance ? void 0 : isBuiltinRole(change.role) ? ROLES[change.role] : void 0;
+					if (shipped !== void 0 && shipped.permissions.some((permission) => PROJECT_ONLY_PERMISSIONS.includes(permission)) && await grantsNaming(d.tx, change.role, { onEnvironments: true }) > 0) throw refused("invalid", `${change.role} is granted on environments: as it ships, it holds a project-wide permission, which would make those grants incoherent`);
+					delete table[change.role];
+				} else {
+					const problem = definitionProblem(change.definition);
+					if (problem !== null) throw refused("invalid", problem);
+					const definition = normalDefinition(change.definition);
+					if (!instance && definition.permissions.some((permission) => PROJECT_ONLY_PERMISSIONS.includes(permission)) && await grantsNaming(d.tx, change.role, { onEnvironments: true }) > 0) throw refused("invalid", `${change.role} is granted on environments: a project-wide permission would make those grants incoherent`);
+					const shipped = instance ? INSTANCE_ROLES[change.role] : isBuiltinRole(change.role) ? ROLES[change.role] : void 0;
+					if (shipped !== void 0 && JSON.stringify(normalDefinition(shipped)) === JSON.stringify(definition)) delete table[change.role];
+					else table[change.role] = definition;
+				}
+			} else if (change?.kind === "protect") {
+				if (typeof change.projectId !== "string" || !UUID.test(change.projectId) || !Array.isArray(change.environmentIds) || change.environmentIds.length === 0 || change.environmentIds.some((id) => typeof id !== "string" || !UUID.test(id)) || typeof change.protected !== "boolean") throw refused("invalid", "protection names a project and some of its environments, by id, and whether they are protected");
+				if (!await projectLive(d.tx, change.projectId)) throw refused("invalid", "no such project");
+				at.projectId = change.projectId;
+				const found = await environmentsById(d.tx, change.environmentIds);
+				if ([...found.values()].some((environment) => environment.projectId !== change.projectId)) throw refused("invalid", "each environment is one of the project's");
+				if (change.environmentIds.length === 1 && found.has(change.environmentIds[0])) at.environmentId = change.environmentIds[0];
+				if (change.protected) {
+					if (!allows(acting.live, "environment.manage", { projectId: change.projectId })) throw refused("not_allowed", "protecting an environment takes managing its project's environments");
+					const known = new Set(next.protected.map((place) => place.environmentId));
+					next.protected = [...next.protected, ...change.environmentIds.filter((id) => !known.has(id)).map((environmentId) => ({
+						projectId: change.projectId,
+						environmentId,
+						at: d.at
+					}))].sort((a, b) => a.environmentId < b.environmentId ? -1 : 1);
+				} else {
+					if (!owner) throw refused("not_allowed", "only an Owner of the whole instance unprotects an environment");
+					next.protected = next.protected.filter((place) => !change.environmentIds.includes(place.environmentId));
+				}
+			} else throw refused("invalid", "a change is to a role, an instance role, or protection");
+			const answer = {
+				policy: await livePolicy(d.tx, next, d.at),
+				seq: newest === null ? null : Number(newest)
+			};
+			if (!readable || JSON.stringify(next) !== JSON.stringify(edits)) {
+				const made = entry("allow", {
+					policy: next,
+					change: describeChange(change),
+					before: describeBefore(change, before)
+				});
+				d.log.push(made);
+				d.after.push((seqOf) => answer.seq = seqOf(made));
+			}
+			return answer;
+		});
+	}
 	setSettings(input) {
 		const { actor } = input;
 		const entry = (decision, detail, code = null) => ({
@@ -2654,7 +2915,6 @@ var VaultService = class {
 			if (acting.status === "tampered") throw refused("tampered");
 			if (!runsInstance(acting.live)) throw refused("not_allowed", "only admins and owners of the whole instance change its settings");
 			if (!isScope(input.settings?.serviceAccounts)) throw refused("invalid", "who sets up service accounts is a scope: { projects, environments }, each all, only or except");
-			await lockLogHead(d.tx);
 			const previous = await this.#settingsAt(d.tx, d.reports);
 			const settings = { serviceAccounts: normalScope(input.settings.serviceAccounts) };
 			if (JSON.stringify(settings) !== JSON.stringify(previous)) d.log.push(entry("allow", {
@@ -3199,6 +3459,7 @@ function validateItems(items, field) {
 		if (field === "key" && typeof key !== "string") throw new Error("DEK must be base64");
 		if (field === "wrapped" && (wrapped === void 0 || wrapped === null)) throw new Error("wrapped key is required");
 		checkContext(context(secret));
+		if (secret.sensitive !== void 0 && typeof secret.sensitive !== "boolean") throw new Error("a secret is sensitive or not: true, false or absent");
 		if (!Number.isSafeInteger(secret.version) || secret.version < 1) throw new Error("secret version must be a positive integer");
 		if (typeof secret.path !== "string" || /[\uD800-\uDFFF]/u.test(secret.path)) throw new Error("secret path must be a well-formed string");
 		if (key !== void 0) {
@@ -3346,9 +3607,10 @@ function personalRefusal(reader, principal, permission, secret, at, environments
 		projectId: secret.projectId,
 		environmentId: own.parentId
 	}, environments);
-	const refused = refuses(reader, "secret.read", parent, own.deleted || (environments.get(own.parentId)?.deleted ?? true));
+	const gone = own.deleted || (environments.get(own.parentId)?.deleted ?? true);
+	const refused = refuses(reader, "secret.use", parent, gone) === null ? null : refuses(reader, "secret.read", parent, gone);
 	if (refused !== null) return refused;
-	return withinCredential(reader.live, permission, parent) ? null : "no_grant";
+	return withinCredential(reader.live, permission === "secret.read" ? "secret.use" : permission, parent) ? null : "no_grant";
 }
 function refuses(reader, permission, where, deleted) {
 	if (reader.status === "tampered") return "tampered";
@@ -3545,13 +3807,87 @@ function view(grant) {
 function iso(ms) {
 	return new Date(ms).toISOString();
 }
-/** A secret's binding context: its ids, and a personal config's owner, hashed, as the decision read it. */
+/** A policy entry's edits, checked as the vault wrote them, or null for any that does not hold. */
+function readEdits(stored) {
+	const edits = stored.policy;
+	if (typeof edits !== "object" || edits === null) return null;
+	const { roles, instanceRoles, protected: protectedIds } = edits;
+	if (typeof roles !== "object" || roles === null || typeof instanceRoles !== "object" || instanceRoles === null || !Array.isArray(protectedIds)) return null;
+	const defined = (table) => Object.values(table).every((definition) => definitionProblem(definition) === null);
+	if (!defined(roles) || !defined(instanceRoles) || Object.keys(instanceRoles).some((role) => !isInstanceRole(role))) return null;
+	if (protectedIds.some((place) => typeof place !== "object" || place === null || !UUID.test(place.projectId) || !UUID.test(place.environmentId) || !Number.isSafeInteger(place.at))) return null;
+	return {
+		roles,
+		instanceRoles,
+		protected: protectedIds
+	};
+}
+/**
+* The policy `edits` say as of `at`: the roles as they ship, each edited
+* one replaced and each made one added; and the protected environments, but
+* for those deleted since, the project around one's included: a deleted
+* prod protects nothing, and holds nobody back from giving a service
+* account a role on all of its project (`givesService`). A fork's id with
+* no row yet stays, protected before it is written, ten minutes: one with
+* none after that is a fork refused or abandoned, never written. Each
+* keeps its slug, which a scoped instance role's filters read. The edits
+* keep them all: no write is needed.
+*/
+async function livePolicy(db, edits, at) {
+	const rows = await environmentsById(db, edits.protected.map((place) => place.environmentId));
+	const live = edits.protected.filter((place) => {
+		const row = rows.get(place.environmentId);
+		return row === void 0 ? at - place.at < UNWRITTEN_FORK_MS : !row.deleted;
+	});
+	const slugOf = (place) => rows.get(place.environmentId)?.slug ?? null;
+	return {
+		roles: {
+			...ROLES,
+			...edits.roles
+		},
+		instanceRoles: {
+			...INSTANCE_ROLES,
+			...edits.instanceRoles
+		},
+		protected: live.map((place) => place.environmentId),
+		protectedIn: live.reduce((byProject, place) => ({
+			...byProject,
+			[place.projectId]: [...byProject[place.projectId] ?? [], {
+				environmentId: place.environmentId,
+				slug: slugOf(place)
+			}]
+		}), {})
+	};
+}
+/** A change, as its entry names it. */
+function describeChange(change) {
+	if (change === void 0 || change === null || typeof change !== "object") return null;
+	if (change.kind === "protect") return {
+		kind: "protect",
+		projectId: change.projectId,
+		environmentIds: change.environmentIds,
+		protected: change.protected
+	};
+	return {
+		kind: change.kind,
+		role: change.role,
+		definition: change.definition
+	};
+}
+/** What a change changed, as it was: the role's definition, or which environments were protected. */
+function describeBefore(change, before) {
+	if (change.kind === "protect") return { protected: change.environmentIds.filter((id) => before.protected.includes(id)) };
+	const table = change.kind === "instance-role" ? before.instanceRoles : before.roles;
+	return { definition: Object.hasOwn(table, change.role) ? table[change.role] : null };
+}
+/** A secret's binding context: its ids, a personal config's owner, hashed, as the decision read it, and whether it is sensitive. */
 function context(secret, owner) {
 	return {
 		projectId: secret.projectId,
 		environmentId: secret.environmentId,
 		secretId: secret.secretId,
-		...owner === void 0 ? {} : { owner }
+		...owner === void 0 ? {} : { owner },
+		...secret.sensitive === true ? { sensitive: true } : {}
 	};
 }
 function unwrappable(wrapped) {