@pithy-sh/core 0.10.0 → 0.12.0

package/dist/controlPlane/migrationState/migrationState.js

@@ -0,0 +1,142 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { InternalError } from "../../error/pithyError.js";
+import { MIGRATIONS_READ_SCOPE } from "../scope/scope.js";
+import { composeDatabases } from "../../data/databases.js";
+import { composedMigrationKey, createMigrationRegistry, decomposeMigrationKey } from "../../migrations/registry.js";
+import { collectMigrationSets } from "../../migrations/capabilitySets.js";
+import { readMigrationLedger } from "../../migrations/runner.js";
+import { readMigrationState } from "../../migrations/state.js";
+//#region src/controlPlane/migrationState/migrationState.ts
+/** A provider declaring nothing, for a database bound with no migrations: everything applied is undeclared. */
+const NOTHING_DECLARED = { getMigrations: async () => ({}) };
+/**
+* Every database this Worker binds, with the provider this build composes for it, sorted by name.
+*
+* One entry per database `composeDatabases` maps to a binding — the same map the request registry is built
+* from — so a database bound with no migrations is still reported. Leaving it out would read as not bound.
+*/
+function composeMigrationDatabases(capabilities) {
+	const sets = collectMigrationSets([...capabilities]);
+	const registry = createMigrationRegistry(sets);
+	const bound = composeDatabases([...capabilities]);
+	return Object.entries(bound).sort(([left], [right]) => left.localeCompare(right)).map(([database, group]) => {
+		const namespaces = /* @__PURE__ */ new Map();
+		for (const set of sets) {
+			if (set.database !== database) continue;
+			for (const localKey of Object.keys(set.migrations)) namespaces.set(composedMigrationKey(set, localKey), set.namespace);
+		}
+		return {
+			database,
+			binding: group.binding,
+			provider: registry[database] ?? NOTHING_DECLARED,
+			namespaces
+		};
+	});
+}
+/**
+* One migration as the route reports it.
+*
+* A declared migration's namespace comes from the set it was declared in. An undeclared one has only its
+* key, so it is decomposed — and a key no registry composed answers null rather than a guess.
+*/
+function migrationView(name, namespaces) {
+	return {
+		name,
+		namespace: namespaces.get(name) ?? decomposeMigrationKey(name)?.namespace ?? null
+	};
+}
+/** The D1 binding for `entry`, or a refusal naming it — a Worker missing the binding cannot read it. */
+function bindingOf(env, entry) {
+	const database = env[entry.binding];
+	if (database == null) throw new InternalError({
+		message: `The ${entry.binding} binding is missing, so database "${entry.database}" cannot be read.`,
+		action: `Declare ${entry.binding} in this Worker's wrangler.jsonc, then deploy again.`
+	});
+	return database;
+}
+function groupView(group, namespaces) {
+	return {
+		group: group.group,
+		appliedAt: group.appliedAt.toISOString(),
+		migrations: group.migrations.map((name) => migrationView(name, namespaces)),
+		position: group.position.state === "top" ? { state: "top" } : {
+			state: "buried",
+			above: group.position.above,
+			ungrouped: group.position.ungrouped.map((name) => migrationView(name, namespaces))
+		}
+	};
+}
+/**
+* Read one database's migration state for the route.
+*
+* **A database that cannot be read is `unreadable`, and costs only itself.** The cause goes to
+* `onUnreadable` — the route logs it, where the operator's context stays the operator's — and never into
+* the view: a D1 error can name a table or a query, and the view crosses to a management client.
+*/
+async function readDatabaseMigrations(env, entry, onUnreadable) {
+	try {
+		const state = await readMigrationState(bindingOf(env, entry), entry.provider);
+		const view = (name) => migrationView(name, entry.namespaces);
+		return {
+			state: "readable",
+			database: entry.database,
+			binding: entry.binding,
+			applied: state.applied.map(view),
+			pending: state.pending.map(view),
+			undeclared: state.undeclared.map(view),
+			lastGroup: state.lastGroup ? groupView(state.lastGroup, entry.namespaces) : null
+		};
+	} catch (cause) {
+		onUnreadable?.(entry, cause);
+		return {
+			state: "unreadable",
+			database: entry.database,
+			binding: entry.binding
+		};
+	}
+}
+/**
+* The two health keys the seam contributes to its own manifest entry.
+*
+* Both `indexed`: one small select per bound database, bounded by the declared migration count rather
+* than by the adopter's data. Both behind {@link MIGRATIONS_READ_SCOPE}, which the seam's own route
+* requires, so a connection without it gets no value rather than a zero.
+*
+* **`undeclaredMigrations` declares no nominal, on purpose.** From inside one Worker, a database shared
+* with another lists the other's migrations as undeclared, so `atMost: 0` would report a corrupted chain
+* on a database that is entirely fine. Null is what a client reads as unknowable, never as healthy (#471).
+*/
+const MIGRATION_HEALTH_KEYS = [{
+	key: "pendingMigrations",
+	kind: "count",
+	states: null,
+	scope: MIGRATIONS_READ_SCOPE,
+	cost: "indexed",
+	summary: "Migrations this build declares that a bound database has not applied.",
+	nominal: { atMost: 0 }
+}, {
+	key: "undeclaredMigrations",
+	kind: "count",
+	states: null,
+	scope: MIGRATIONS_READ_SCOPE,
+	cost: "indexed",
+	summary: "Migrations a bound database holds that this Worker does not declare. Relative to this Worker: a database shared with another lists that Worker's migrations here.",
+	nominal: null
+}];
+/**
+* Total pending and undeclared across every bound database, for the manifest.
+*
+* **Throws rather than total a database it could not read.** A partial total is a zero for the database
+* nobody read. The seam catches the throw and reports the summary `unavailable`, which a client reads as
+* unknown — null is never zero.
+*/
+async function readMigrationHealth(env, databases) {
+	const ledgers = await Promise.all(databases.map((entry) => readMigrationLedger(bindingOf(env, entry), entry.provider)));
+	return {
+		pendingMigrations: ledgers.reduce((total, ledger) => total + ledger.pending.length, 0),
+		undeclaredMigrations: ledgers.reduce((total, ledger) => total + ledger.undeclared.length, 0)
+	};
+}
+//#endregion
+export { MIGRATION_HEALTH_KEYS, composeMigrationDatabases, migrationView, readDatabaseMigrations, readMigrationHealth };

package/dist/controlPlane/migrations/0003_connection_principal.d.ts

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Migration } from "kysely/migration";
+/**
+ * Who sanctioned a connection, what kind of client it is, and what it is for — `#721`.
+ *
+ * **Appended, not folded into `0001`.** The seam has shipped and adopters' databases hold rows written by
+ * it, so the three columns arrive in a migration of their own, as `0002`'s origin did.
+ *
+ * **Nullable, with no default, and nothing backfilled.** A row registered before this carries no
+ * principal, and none can be recovered: most of the trail that might be mined for one names a token
+ * rather than a person, and a principal read off a token name is the self-assertion this issue exists to
+ * end. So null means *registered before principals were recorded*, the connection keeps working exactly
+ * as it did, its purpose may be set with `pithy dashboard connect --update --purpose`, and its principal
+ * is set only by registering again, under a signed-in session.
+ *
+ * **The Worker reads only `actorKind`**, to stamp it onto the audit rows a connection's calls write. The
+ * other two exist for the adopter's own review, on their own side.
+ */
+export declare const controlplane_0003_connection_principal: Migration;
+//# sourceMappingURL=0003_connection_principal.d.ts.map

package/dist/controlPlane/migrations/0003_connection_principal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"0003_connection_principal.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/migrations/0003_connection_principal.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sCAAsC,EAAE,SAcpD,CAAC"}

package/dist/controlPlane/migrations/0003_connection_principal.js

@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/controlPlane/migrations/0003_connection_principal.ts
+/**
+* Who sanctioned a connection, what kind of client it is, and what it is for — `#721`.
+*
+* **Appended, not folded into `0001`.** The seam has shipped and adopters' databases hold rows written by
+* it, so the three columns arrive in a migration of their own, as `0002`'s origin did.
+*
+* **Nullable, with no default, and nothing backfilled.** A row registered before this carries no
+* principal, and none can be recovered: most of the trail that might be mined for one names a token
+* rather than a person, and a principal read off a token name is the self-assertion this issue exists to
+* end. So null means *registered before principals were recorded*, the connection keeps working exactly
+* as it did, its purpose may be set with `pithy dashboard connect --update --purpose`, and its principal
+* is set only by registering again, under a signed-in session.
+*
+* **The Worker reads only `actorKind`**, to stamp it onto the audit rows a connection's calls write. The
+* other two exist for the adopter's own review, on their own side.
+*/
+const controlplane_0003_connection_principal = {
+	up: async (db) => {
+		await db.schema.alterTable("pithyControlplaneConnections").addColumn("authorizedBy", "text").execute();
+		await db.schema.alterTable("pithyControlplaneConnections").addColumn("actorKind", "text").execute();
+		await db.schema.alterTable("pithyControlplaneConnections").addColumn("purpose", "text").execute();
+	},
+	down: async (db) => {
+		await db.schema.alterTable("pithyControlplaneConnections").dropColumn("purpose").execute();
+		await db.schema.alterTable("pithyControlplaneConnections").dropColumn("actorKind").execute();
+		await db.schema.alterTable("pithyControlplaneConnections").dropColumn("authorizedBy").execute();
+	}
+};
+//#endregion
+export { controlplane_0003_connection_principal };

package/dist/controlPlane/scope/scope.d.ts

@@ -50,8 +50,29 @@ export declare const MANIFEST_READ_SCOPE: ControlPlaneScope;
  */
 export declare const KEYS_ROTATE_SCOPE: ControlPlaneScope;
 /**
- * Every grantable scope the seam's own routes use — what `pithy dashboard connect` offers by default.
- * Ping is absent because it is not grantable; see {@link ANY_VERIFIED_CALLER}.
+ * Read where each database this Worker binds stands: what is applied, what is pending, what is undeclared,
+ * and which run put it there (#729). Read-only by construction — every route behind it is a `GET`, and
+ * nothing over the seam runs, reverses or resets a migration. The two migration health keys on the seam's
+ * manifest entry sit behind it too, so a connection without it gets no number rather than a zero.
+ */
+export declare const MIGRATIONS_READ_SCOPE: ControlPlaneScope;
+/**
+ * Read this Worker's full privacy inventory: every storage schema holding a marked field, each marked field's
+ * path, its class, and where it is stored (#132). Read-only — the one route behind it is a `GET`.
+ *
+ * **Its own scope rather than `manifest:read`**, because field names are the kind of thing an adopter may
+ * reasonably withhold from a client that has no business seeing them. The manifest's privacy block carries
+ * classes and counts only, so a connection without this one still sees the posture headline.
+ */
+export declare const PRIVACY_READ_SCOPE: ControlPlaneScope;
+/**
+ * The seam's base grant — what `pithy dashboard connect` grants whatever the Worker composes. Ping is absent
+ * because it is not grantable; see {@link ANY_VERIFIED_CALLER}.
+ *
+ * **{@link MIGRATIONS_READ_SCOPE} and {@link PRIVACY_READ_SCOPE} are absent on purpose.** Each is a read —
+ * every route requiring it is a `GET` — so `connect` derives it from the seam's `adminRoutes` the way it
+ * derives every capability's reads. The base exists for `keys:rotate`, which is not a read and would
+ * otherwise drop out.
  */
 export declare const SEAM_SCOPES: readonly ControlPlaneScope[];
 /**

package/dist/controlPlane/scope/scope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/scope/scope.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAexB;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,aAQ3B,CAAC;AACJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAA2D,CAAC;AAErG;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,GAAG,OAAO,mBAAmB,CAAC;AAErF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,iBAAmC,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,iBAAiC,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,iBAAiB,EAA6C,CAAC;AAElG;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAIrH"}
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/scope/scope.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAexB;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,aAQ3B,CAAC;AACJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAA2D,CAAC;AAErG;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,GAAG,OAAO,mBAAmB,CAAC;AAErF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,iBAAmC,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,iBAAiC,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,iBAAqC,CAAC;AAE1E;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,iBAAkC,CAAC;AAEpE;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,iBAAiB,EAA6C,CAAC;AAElG;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,uBAAuB,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAIrH"}

package/dist/controlPlane/scope/scope.js

@@ -40,8 +40,29 @@ const MANIFEST_READ_SCOPE = "manifest:read";
 */
 const KEYS_ROTATE_SCOPE = "keys:rotate";
 /**
-* Every grantable scope the seam's own routes use — what `pithy dashboard connect` offers by default.
-* Ping is absent because it is not grantable; see {@link ANY_VERIFIED_CALLER}.
+* Read where each database this Worker binds stands: what is applied, what is pending, what is undeclared,
+* and which run put it there (#729). Read-only by construction — every route behind it is a `GET`, and
+* nothing over the seam runs, reverses or resets a migration. The two migration health keys on the seam's
+* manifest entry sit behind it too, so a connection without it gets no number rather than a zero.
+*/
+const MIGRATIONS_READ_SCOPE = "migrations:read";
+/**
+* Read this Worker's full privacy inventory: every storage schema holding a marked field, each marked field's
+* path, its class, and where it is stored (#132). Read-only — the one route behind it is a `GET`.
+*
+* **Its own scope rather than `manifest:read`**, because field names are the kind of thing an adopter may
+* reasonably withhold from a client that has no business seeing them. The manifest's privacy block carries
+* classes and counts only, so a connection without this one still sees the posture headline.
+*/
+const PRIVACY_READ_SCOPE = "privacy:read";
+/**
+* The seam's base grant — what `pithy dashboard connect` grants whatever the Worker composes. Ping is absent
+* because it is not grantable; see {@link ANY_VERIFIED_CALLER}.
+*
+* **{@link MIGRATIONS_READ_SCOPE} and {@link PRIVACY_READ_SCOPE} are absent on purpose.** Each is a read —
+* every route requiring it is a `GET` — so `connect` derives it from the seam's `adminRoutes` the way it
+* derives every capability's reads. The base exists for `keys:rotate`, which is not a read and would
+* otherwise drop out.
 */
 const SEAM_SCOPES = [MANIFEST_READ_SCOPE, KEYS_ROTATE_SCOPE];
 /**
@@ -62,4 +83,4 @@ function scopeCovers(required, presented, granted) {
 	return granted.includes(required);
 }
 //#endregion
-export { ANY_VERIFIED_CALLER, ControlPlaneScope, KEYS_ROTATE_SCOPE, MANIFEST_READ_SCOPE, SEAM_SCOPES, scopeCovers };
+export { ANY_VERIFIED_CALLER, ControlPlaneScope, KEYS_ROTATE_SCOPE, MANIFEST_READ_SCOPE, MIGRATIONS_READ_SCOPE, PRIVACY_READ_SCOPE, SEAM_SCOPES, scopeCovers };

package/dist/createBackend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createBackend.d.ts","sourceRoot":"","sources":["../src/createBackend.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EAEpB,SAAS,EACV,MAAM,yBAAyB,CAAC;AAMjC,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMtF,OAAO,EAA8B,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE9E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAO9C,OAAO,EAA2B,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAGvF,oGAAoG;AACpG,MAAM,WAAW,oBAAoB,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,EAAE,GAAG,SAAS,UAAU;IAC9F,2EAA2E;IAC3E,YAAY,EAAE,IAAI,CAAC;IACnB;;;OAGG;IACH,GAAG,CAAC,EAAE,GAAG,CAAC;IACV;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,iHAAiH;AACjH,KAAK,UAAU,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,IAAI;IACpD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,GAAG,IAAI,GAAG,WAAW,CAAC,GAAG;QACtD,EAAE,EAAE,UAAU,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;QACtC,EAAE,EAAE,UAAU,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;QACzC,SAAS,EAAE,kBAAkB,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC;KAC3D,CAAC;CACH,CAAC;AAuCF,kCAAkC;AAClC,eAAO,MAAM,UAAU;;;iBAQ+B,CAAC;AACvD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,KAAK,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,EACxC,KAAK,CAAC,GAAG,SAAS,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,EACrF,OAAO,EAAE,oBAAoB,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CA0LrF"}
+{"version":3,"file":"createBackend.d.ts","sourceRoot":"","sources":["../src/createBackend.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EAEpB,SAAS,EACV,MAAM,yBAAyB,CAAC;AAOjC,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMtF,OAAO,EAA8B,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE9E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAQ9C,OAAO,EAA2B,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAGvF,oGAAoG;AACpG,MAAM,WAAW,oBAAoB,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,EAAE,GAAG,SAAS,UAAU;IAC9F,2EAA2E;IAC3E,YAAY,EAAE,IAAI,CAAC;IACnB;;;OAGG;IACH,GAAG,CAAC,EAAE,GAAG,CAAC;IACV;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,iHAAiH;AACjH,KAAK,UAAU,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,IAAI;IACpD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,GAAG,IAAI,GAAG,WAAW,CAAC,GAAG;QACtD,EAAE,EAAE,UAAU,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;QACtC,EAAE,EAAE,UAAU,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;QACzC,SAAS,EAAE,kBAAkB,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC;KAC3D,CAAC;CACH,CAAC;AAuCF,kCAAkC;AAClC,eAAO,MAAM,UAAU;;;iBAQ+B,CAAC;AACvD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,KAAK,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,EACxC,KAAK,CAAC,GAAG,SAAS,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,EACrF,OAAO,EAAE,oBAAoB,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CA6MrF"}

package/dist/createBackend.js

@@ -1,16 +1,19 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
+import { noActingOrganization } from "./access/acting.js";
 import { noopEmit } from "./audit/recorder.js";
 import { ValidationError } from "./error/pithyError.js";
 import { pithyCommandOf } from "./cli/command.js";
 import { BindingSpec } from "./capability/bindings.js";
 import { recordComposition } from "./capability/composition.js";
 import { validateBindings } from "./capability/validateBindings.js";
+import { refuseEncryptedKvStores } from "./privacy/encryptedColumns.js";
 import { workerVersion } from "./worker/identity.js";
 import { describeRoute } from "./http/routeSpec.js";
+import { buildDbRegistry, composeDatabases } from "./data/databases.js";
 import { isControlPlaneCapability } from "./controlPlane/capability.js";
 import { allowedOriginSet, corsSurface, registerControlPlaneCors } from "./controlPlane/http/cors.js";
-import { buildDbRegistry, composeDatabases } from "./data/databases.js";
+import { registerReadinessGuards } from "./controlPlane/http/readiness.js";
 import { noEntitlementProvider } from "./entitlement/entitlement.js";
 import { bakedTranslator } from "./i18n/translator.js";
 import { catalogFor, composeMessages } from "./i18n/registry.js";
@@ -97,6 +100,7 @@ function createBackend(options) {
 	const messages = composeMessages(all);
 	const defaultTranslator = bakedTranslator(catalogFor(messages, "en"));
 	const namespaces = composeKv(all);
+	refuseEncryptedKvStores(all);
 	const workflows = composeWorkflows(all);
 	const required = dedupeBindings([
 		...all.flatMap((cap) => cap.requiredBindings),
@@ -113,10 +117,11 @@ function createBackend(options) {
 	const app = new Hono();
 	app.onError(loggingErrorHandler);
 	const baseLogger = options.logger ?? createWorkerLogger();
+	const adminSurface = corsSurface(all);
 	const controlPlane = all.find(isControlPlaneCapability);
 	if (controlPlane) {
 		const cors = controlPlane.controlPlaneConfig;
-		registerControlPlaneCors(app, corsSurface(all), allowedOriginSet(cors), cors.corsMaxAgeSeconds);
+		registerControlPlaneCors(app, adminSurface, allowedOriginSet(cors), cors.corsMaxAgeSeconds);
 	}
 	let validated = false;
 	app.use("*", async (c, next) => {
@@ -126,6 +131,7 @@ function createBackend(options) {
 			validated = true;
 		}
 		if (c.get("auth") === void 0) c.set("auth", null);
+		if (c.get("actingOrganization") === void 0) c.set("actingOrganization", noActingOrganization);
 		if (c.get("locale") === void 0) c.set("locale", null);
 		if (c.get("t") === void 0) c.set("t", defaultTranslator);
 		if (c.get("controlPlane") === void 0) c.set("controlPlane", null);
@@ -188,6 +194,7 @@ function createBackend(options) {
 		routes: app.routes.slice(healthStart)
 	});
 	for (const cap of all) for (const middleware of cap.middleware ?? []) middleware(app);
+	registerReadinessGuards(app, adminSurface, all.flatMap((cap) => cap.readiness ?? []));
 	for (const cap of all) {
 		const start = app.routes.length;
 		cap.routes?.(app);

package/dist/createEntrypoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createEntrypoint.d.ts","sourceRoot":"","sources":["../src/createEntrypoint.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAC3F,OAAO,KAAK,EAAE,UAAU,EAA0B,MAAM,yBAAyB,CAAC;AAClF,OAAO,EAAE,KAAK,oBAAoB,EAAiB,MAAM,iBAAiB,CAAC;AAI3E;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,gBAAgB,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/G;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjH;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CAAC,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACzG;AAkBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,EACxC,KAAK,CAAC,GAAG,SAAS,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,EACrF,OAAO,EAAE,oBAAoB,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,eAAe,CAoD3D"}
+{"version":3,"file":"createEntrypoint.d.ts","sourceRoot":"","sources":["../src/createEntrypoint.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAC3F,OAAO,KAAK,EAAE,UAAU,EAA0B,MAAM,yBAAyB,CAAC;AAClF,OAAO,EAAE,KAAK,oBAAoB,EAAiB,MAAM,iBAAiB,CAAC;AAK3E;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,gBAAgB,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/G;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjH;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CAAC,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACzG;AAkBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,EACxC,KAAK,CAAC,GAAG,SAAS,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,EACrF,OAAO,EAAE,oBAAoB,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,eAAe,CAyD3D"}

package/dist/createEntrypoint.js

@@ -3,6 +3,7 @@
 import { triggerWorkflow } from "./workflow/dispatch.js";
 import { composeWorkflows, scheduledWorkflows } from "./workflow/register.js";
 import { createBackend } from "./createBackend.js";
+import { withLocalServices } from "./worker/serviceLoopback.js";
 //#region src/createEntrypoint.ts
 /**
 * The raw MIME stream of a `ForwardableEmailMessage` is **single-use** — once one handler reads it,
@@ -31,17 +32,18 @@ function createEntrypoint(options) {
 	for (const cap of all) cap.boot?.({ capabilities: all });
 	const registry = composeWorkflows(all);
 	const scheduled = scheduledWorkflows(registry);
-	const entrypoint = { fetch: (request, env, ctx) => app.fetch(request, env, ctx) };
+	const entrypoint = { fetch: (request, env, ctx) => app.fetch(request, withLocalServices(env), ctx) };
 	if (scheduled.length > 0) entrypoint.scheduled = async (_controller, env) => {
 		const failures = [];
 		for (const entry of scheduled) try {
-			await triggerWorkflow(env, registry, entry.key, {});
+			await triggerWorkflow(withLocalServices(env), registry, entry.key, {});
 		} catch (error) {
 			failures.push(error);
 		}
 		if (failures[0] !== void 0) throw failures[0];
 	};
-	if (handlers.length > 0) entrypoint.email = async (message, env, ctx) => {
+	if (handlers.length > 0) entrypoint.email = async (message, given, ctx) => {
+		const env = withLocalServices(given);
 		if (handlers.length === 1) {
 			await handlers[0]?.(message, env, ctx);
 			return;

package/dist/crypto/envelope.d.ts

@@ -0,0 +1,86 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * **The AES-256-GCM envelope: one primitive, two callers** (#390).
+ *
+ * It was `@pithy-sh/secrets`' own, ported from the CMS `secretsCrypto`, and it sealed that capability's rows and
+ * nothing else. Field encryption needs the same primitive inside an adopter's own Workers, and a capability may not
+ * depend on another's internals (principle 4), so it lives in core now and both callers import it from here. The
+ * format did not change: a row secrets sealed before the move opens after it, byte for byte.
+ *
+ * ## Two version axes
+ *
+ * `currentVersion` says which key seals new writes, and the `keyVersion` persisted on every envelope says which key
+ * opens it. A rotation adds a version, moves the pointer and keeps the old key until nothing is sealed under it, so
+ * a row opens under whichever version sealed it, for as long as that version is in the set. This is the
+ * *encryption-key* version. A secret's *value* version is a separate concern (`secrets/src/crypto/versionedValue.ts`).
+ *
+ * The config is the uniform `{ currentVersion, versions }` shape every versioned value uses, plus `lastRotatedAt`
+ * beside it as rotation metadata. Version keys are stringified integers, so reading the keys is a full-set read:
+ * every still-valid version, never the current one alone.
+ *
+ * ## The bound context is the caller's, and it is authenticated
+ *
+ * Every seal binds a **context** string as AES-GCM additional authenticated data. It is not encrypted; it is bound.
+ * Without it a ciphertext is valid under the key alone, so one lifted from one row and written into another opens
+ * cleanly, and every decision about which value a caller gets lives in the query above. With it, a moved ciphertext
+ * fails inside the primitive, however that query is later rewritten.
+ *
+ * The primitive takes the context whole, because what to bind is the caller's fact, not this module's:
+ *
+ * - `@pithy-sh/secrets` binds `pithy.secrets.v1:<stored name>` — exactly what it always bound.
+ * - A field marked `encrypted()` binds `pithy/enc/1:<declared name>:<field path>:<primary key>` (`../privacy/sealed`).
+ *
+ * Each prefix is versioned, so a later change to what is bound is a deliberate, visible break, and the two prefixes
+ * are distinct, so a secret's ciphertext never opens as a field and a field's never opens as a secret. **What is bound
+ * must be stable for the life of the ciphertext**: each caller states why its own context is.
+ *
+ * An empty context is refused on both halves. It binds nothing, and it would fail open rather than loudly.
+ */
+/** The key set a seal draws from: which version is current, every still-valid key, and when it last rotated. */
+export declare const EncryptionConfig: z.ZodObject<{
+    currentVersion: z.ZodString;
+    versions: z.ZodRecord<z.ZodString, z.ZodString>;
+    lastRotatedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type EncryptionConfig = z.output<typeof EncryptionConfig>;
+/**
+ * One AES-256-GCM envelope: base64 ciphertext, base64 IV, and the key version that sealed it.
+ *
+ * The bound context is deliberately not in here. It is supplied by the caller on the way back in, from the row's own
+ * identity, so a row that has been moved cannot carry its old context with it.
+ */
+export declare const EncryptedEnvelope: z.ZodObject<{
+    encryptedValue: z.ZodString;
+    iv: z.ZodString;
+    keyVersion: z.ZodNumber;
+}, z.core.$strip>;
+export type EncryptedEnvelope = z.output<typeof EncryptedEnvelope>;
+/** What the refusals name the key set by — its binding, so an operator knows which entry to inspect. */
+export interface EnvelopeOptions {
+    /** The binding the key set was read from, e.g. `SECRETS_ENCRYPTION_KEYS`. Defaults to `the key set`. */
+    keys?: string;
+}
+/** Base64-encode raw bytes without spreading into `fromCharCode` (stack-safe, lint-clean). */
+export declare function toBase64(bytes: Uint8Array): string;
+/** Decode base64 to raw bytes. */
+export declare function fromBase64(b64: string): Uint8Array<ArrayBuffer>;
+/** The raw key bytes for `version`, or a refusal naming the key set. Never the key itself. */
+export declare function keyBytes(config: EncryptionConfig, version: number, options?: EnvelopeOptions): Uint8Array<ArrayBuffer>;
+/**
+ * Seal `plaintext` under the config's current key version, binding `context`. The IV is 12 fresh random bytes, so
+ * two seals of one value never share a ciphertext.
+ */
+export declare function encryptValue(config: EncryptionConfig, context: string, plaintext: string, options?: EnvelopeOptions): Promise<EncryptedEnvelope>;
+/**
+ * Open an envelope sealed under `context`. The key version may differ from `currentVersion` during a rotation window;
+ * the matching key must still be in the config.
+ *
+ * A missing key version, a tampered ciphertext, the wrong key, or a ciphertext sealed under another context all throw
+ * — never the plaintext or key material. GCM cannot tell those apart, and separating them for the caller would be an
+ * oracle: the `detail` names the context the open was *attempted under*, which is what an operator needs. Each caller
+ * binds a context composed from validated identifiers, so it is safe in a log; neither binds a value.
+ */
+export declare function decryptValue(config: EncryptionConfig, context: string, envelope: EncryptedEnvelope, options?: EnvelopeOptions): Promise<string>;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/crypto/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/crypto/envelope.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,gHAAgH;AAChH,eAAO,MAAM,gBAAgB;;;;iBAsB1B,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;iBASqE,CAAC;AACpG,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE,wGAAwG;AACxG,MAAM,WAAW,eAAe;IAC9B,wGAAwG;IACxG,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,8FAA8F;AAC9F,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAIlD;AAED,kCAAkC;AAClC,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,CAE/D;AAYD,8FAA8F;AAC9F,wBAAgB,QAAQ,CACtB,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,eAAoB,GAC5B,UAAU,CAAC,WAAW,CAAC,CAQzB;AAYD;;;GAGG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CAW5B;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,MAAM,CAAC,CAkBjB"}

package/dist/crypto/envelope.js

@@ -0,0 +1,129 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { InternalError } from "../error/pithyError.js";
+import { z } from "zod";
+//#region src/crypto/envelope.ts
+/**
+* **The AES-256-GCM envelope: one primitive, two callers** (#390).
+*
+* It was `@pithy-sh/secrets`' own, ported from the CMS `secretsCrypto`, and it sealed that capability's rows and
+* nothing else. Field encryption needs the same primitive inside an adopter's own Workers, and a capability may not
+* depend on another's internals (principle 4), so it lives in core now and both callers import it from here. The
+* format did not change: a row secrets sealed before the move opens after it, byte for byte.
+*
+* ## Two version axes
+*
+* `currentVersion` says which key seals new writes, and the `keyVersion` persisted on every envelope says which key
+* opens it. A rotation adds a version, moves the pointer and keeps the old key until nothing is sealed under it, so
+* a row opens under whichever version sealed it, for as long as that version is in the set. This is the
+* *encryption-key* version. A secret's *value* version is a separate concern (`secrets/src/crypto/versionedValue.ts`).
+*
+* The config is the uniform `{ currentVersion, versions }` shape every versioned value uses, plus `lastRotatedAt`
+* beside it as rotation metadata. Version keys are stringified integers, so reading the keys is a full-set read:
+* every still-valid version, never the current one alone.
+*
+* ## The bound context is the caller's, and it is authenticated
+*
+* Every seal binds a **context** string as AES-GCM additional authenticated data. It is not encrypted; it is bound.
+* Without it a ciphertext is valid under the key alone, so one lifted from one row and written into another opens
+* cleanly, and every decision about which value a caller gets lives in the query above. With it, a moved ciphertext
+* fails inside the primitive, however that query is later rewritten.
+*
+* The primitive takes the context whole, because what to bind is the caller's fact, not this module's:
+*
+* - `@pithy-sh/secrets` binds `pithy.secrets.v1:<stored name>` — exactly what it always bound.
+* - A field marked `encrypted()` binds `pithy/enc/1:<declared name>:<field path>:<primary key>` (`../privacy/sealed`).
+*
+* Each prefix is versioned, so a later change to what is bound is a deliberate, visible break, and the two prefixes
+* are distinct, so a secret's ciphertext never opens as a field and a field's never opens as a secret. **What is bound
+* must be stable for the life of the ciphertext**: each caller states why its own context is.
+*
+* An empty context is refused on both halves. It binds nothing, and it would fail open rather than loudly.
+*/
+/** The key set a seal draws from: which version is current, every still-valid key, and when it last rotated. */
+const EncryptionConfig = z.object({
+	currentVersion: z.string().meta({ multiline: false }).describe("The version key (a stringified integer) whose key seals new writes — the active key."),
+	versions: z.record(z.string(), z.string().meta({ multiline: false })).describe("Every still-valid key: version key (stringified integer) → base64-encoded AES-256 key. Holds the current key plus any prior versions still needed to open values not yet re-sealed."),
+	lastRotatedAt: z.iso.datetime().meta({ multiline: false }).describe("ISO-8601 timestamp of the last rotation; the rotation cron compares against it to decide when to rotate.")
+}).describe("A versioned AES-256 key set: the uniform versioned-value shape (currentVersion + versions) plus rotation metadata. Secrets' master key (`SECRETS_ENCRYPTION_KEYS`) and the field key (`PITHY_FIELD_KEYS`) both take it.");
+/**
+* One AES-256-GCM envelope: base64 ciphertext, base64 IV, and the key version that sealed it.
+*
+* The bound context is deliberately not in here. It is supplied by the caller on the way back in, from the row's own
+* identity, so a row that has been moved cannot carry its old context with it.
+*/
+const EncryptedEnvelope = z.object({
+	encryptedValue: z.string().min(1).describe("The AES-256-GCM ciphertext and tag, base64."),
+	iv: z.string().min(1).describe("The 12-byte initialization vector, base64. Fresh for every seal."),
+	keyVersion: z.number().int().describe("The version of the key that sealed this value: the key set entry that opens it.")
+}).describe("An AES-256-GCM envelope: the ciphertext, its IV, and the key version that sealed it.");
+/** Base64-encode raw bytes without spreading into `fromCharCode` (stack-safe, lint-clean). */
+function toBase64(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary);
+}
+/** Decode base64 to raw bytes. */
+function fromBase64(b64) {
+	return Uint8Array.from(atob(b64), (char) => char.charCodeAt(0));
+}
+/** The authenticated data for one seal. An empty context is refused: it would bind nothing. */
+function additionalData(context) {
+	if (context.length === 0) throw new InternalError({ detail: "the envelope needs a context to bind; an empty context binds nothing" });
+	return Uint8Array.from(new TextEncoder().encode(context));
+}
+/** The raw key bytes for `version`, or a refusal naming the key set. Never the key itself. */
+function keyBytes(config, version, options = {}) {
+	const b64 = config.versions[String(version)];
+	if (!b64) throw new InternalError({ detail: `encryption key version ${version} not present in ${options.keys ?? "the key set"}` });
+	return fromBase64(b64);
+}
+/** Import the AES-GCM key for `version` from the config, or throw if that version is absent. */
+async function importKey(config, version, usage, options) {
+	return crypto.subtle.importKey("raw", keyBytes(config, version, options), "AES-GCM", false, usage);
+}
+/**
+* Seal `plaintext` under the config's current key version, binding `context`. The IV is 12 fresh random bytes, so
+* two seals of one value never share a ciphertext.
+*/
+async function encryptValue(config, context, plaintext, options = {}) {
+	const aad = additionalData(context);
+	const keyVersion = Number(config.currentVersion);
+	const key = await importKey(config, keyVersion, ["encrypt"], options);
+	const iv = crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(12));
+	const ciphertext = await crypto.subtle.encrypt({
+		name: "AES-GCM",
+		iv,
+		additionalData: aad
+	}, key, new TextEncoder().encode(plaintext));
+	return {
+		encryptedValue: toBase64(new Uint8Array(ciphertext)),
+		iv: toBase64(iv),
+		keyVersion
+	};
+}
+/**
+* Open an envelope sealed under `context`. The key version may differ from `currentVersion` during a rotation window;
+* the matching key must still be in the config.
+*
+* A missing key version, a tampered ciphertext, the wrong key, or a ciphertext sealed under another context all throw
+* — never the plaintext or key material. GCM cannot tell those apart, and separating them for the caller would be an
+* oracle: the `detail` names the context the open was *attempted under*, which is what an operator needs. Each caller
+* binds a context composed from validated identifiers, so it is safe in a log; neither binds a value.
+*/
+async function decryptValue(config, context, envelope, options = {}) {
+	const aad = additionalData(context);
+	const key = await importKey(config, envelope.keyVersion, ["decrypt"], options);
+	try {
+		const plaintext = await crypto.subtle.decrypt({
+			name: "AES-GCM",
+			iv: fromBase64(envelope.iv),
+			additionalData: aad
+		}, key, fromBase64(envelope.encryptedValue));
+		return new TextDecoder().decode(plaintext);
+	} catch (cause) {
+		throw new InternalError({ detail: `AES-GCM decrypt failed for '${context}' under key version ${envelope.keyVersion}: wrong key, tampered ciphertext, or a ciphertext sealed under a different context` }, { cause });
+	}
+}
+//#endregion
+export { EncryptedEnvelope, EncryptionConfig, decryptValue, encryptValue, fromBase64, keyBytes, toBase64 };