@pithy-sh/core 0.13.0 → 0.14.0

package/dist/controlPlane/evidence/derive.js

@@ -0,0 +1,343 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { MIGRATIONS_READ_SCOPE } from "../scope/scope.js";
+import { standingOf } from "../discovery/healthSummary.js";
+import { AUDIT_PACKAGE, EVIDENCE_CONTROLS, SECRETS_CAPABILITY, SECRETS_PACKAGE } from "./mapping.js";
+//#region src/controlPlane/evidence/derive.ts
+/** Settle a control's state from what was missing and what could not be read. See the module doc. */
+function settle(gaps, unknowns, facts) {
+	return {
+		state: gaps.length > 0 ? "gap" : unknowns.length > 0 ? "not-derivable" : "evidenced",
+		reasons: [...gaps, ...unknowns],
+		facts
+	};
+}
+/** One entry of the pack: the mapping table's row for the control, beside what was derived. */
+function evidenceEntry(control, derived) {
+	const row = EVIDENCE_CONTROLS[control];
+	return {
+		control,
+		title: row.title,
+		soc2: [...row.soc2],
+		iso27001: [...row.iso27001],
+		state: derived.state,
+		reasons: derived.reasons,
+		facts: derived.facts
+	};
+}
+/** How many undescribed routes a reason names before it counts the rest. */
+const NAMED_ROUTE_LIMIT = 10;
+/**
+* Audit logging in force: a composed recorder, the binding it writes through, and this request's emit seam
+* actually recording. The seam's guard emits on every control-plane call, allowed or denied, so a recorder on
+* the seam is a record of every management call — including the one reading this pack.
+*/
+function deriveAuditLogging(input) {
+	const facts = [{
+		fact: "auditRecorder",
+		value: input.recorder?.capability ?? null,
+		source: "composition"
+	}];
+	const gaps = [];
+	if (!input.recorder) {
+		gaps.push(`No composed capability records audit events, so control-plane calls and every other audited action go unrecorded. Compose ${AUDIT_PACKAGE}.`);
+		return settle(gaps, [], facts);
+	}
+	for (const { binding, present } of input.recorder.bindings) {
+		facts.push({
+			fact: "bindingPresent",
+			subject: binding,
+			value: present,
+			source: "bindings"
+		});
+		if (!present) gaps.push(`The \`${binding}\` binding \`${input.recorder.capability}\` records through is missing from this Worker, so its events are dropped.`);
+	}
+	facts.push({
+		fact: "controlPlaneCallsRecorded",
+		value: input.emitting,
+		source: "auditRecorder"
+	});
+	if (!input.emitting) gaps.push(`This request's emit seam is not \`${input.recorder.capability}\`'s recorder, so control-plane calls go unrecorded.`);
+	return settle(gaps, [], facts);
+}
+/** The strategies a spec names, as a list. */
+function strategiesOf(operation) {
+	const verification = operation.spec?.verification;
+	if (verification === void 0) return [];
+	return typeof verification === "string" ? [verification] : verification;
+}
+/** Why a control reading the route table cannot: an app `createBackend` did not assemble has no recorded groups. */
+const NO_ROUTE_TABLE = "This Worker's route table was not assembled by `createBackend`, so it cannot be read.";
+/**
+* Every route declares how a caller is verified: `describeRoute`'s `verification`, read off the composed route
+* table. A route with no `describeRoute` declares nothing, and is named.
+*/
+function deriveRouteVerification(operations) {
+	if (operations === void 0) return settle([], [NO_ROUTE_TABLE], []);
+	const undescribed = operations.filter((operation) => operation.spec === void 0);
+	const counts = /* @__PURE__ */ new Map();
+	for (const operation of operations) for (const strategy of strategiesOf(operation)) counts.set(strategy, (counts.get(strategy) ?? 0) + 1);
+	const facts = [
+		{
+			fact: "routes",
+			value: operations.length,
+			source: "routeSpec"
+		},
+		{
+			fact: "undescribedRoutes",
+			value: undescribed.length,
+			source: "routeSpec"
+		},
+		...[...counts].map(([strategy, count]) => ({
+			fact: "routesVerifiedBy",
+			subject: strategy,
+			value: count,
+			source: "routeSpec"
+		}))
+	];
+	const gaps = undescribed.slice(0, NAMED_ROUTE_LIMIT).map((operation) => `\`${operation.method} ${operation.path}\` declares no verification.`);
+	const rest = undescribed.length - NAMED_ROUTE_LIMIT;
+	if (rest > 0) gaps.push(`${rest} more ${rest === 1 ? "route declares" : "routes declare"} no verification.`);
+	return settle(gaps, [], facts);
+}
+/** Why a control reading the connections table cannot. */
+const CONNECTIONS_UNREADABLE = "The control-plane connections table could not be read on this call.";
+/**
+* Management access attributed and scoped: every connection in this environment, with the principal who
+* authorized it, its actor kind, its purpose (#721) and its granted scopes. The principal is the email the
+* connection records and nothing else; no audit row's actor is copied in.
+*/
+function deriveManagementAccess(connections) {
+	if (connections === null) return settle([], [CONNECTIONS_UNREADABLE], []);
+	const facts = [{
+		fact: "connections",
+		value: connections.length,
+		source: "connection"
+	}];
+	const gaps = [];
+	for (const connection of connections) {
+		facts.push({
+			fact: "authorizedBy",
+			subject: connection.id,
+			value: connection.authorizedBy,
+			source: "connection"
+		}, {
+			fact: "actorKind",
+			subject: connection.id,
+			value: connection.actorKind,
+			source: "connection"
+		}, {
+			fact: "purpose",
+			subject: connection.id,
+			value: connection.purpose,
+			source: "connection"
+		}, {
+			fact: "scopes",
+			subject: connection.id,
+			value: [...connection.scopes],
+			source: "connection"
+		});
+		const missing = [
+			connection.authorizedBy === null ? "principal" : null,
+			connection.actorKind === null ? "actor kind" : null,
+			connection.purpose === null ? "purpose" : null
+		].filter((name) => name !== null);
+		if (missing.length > 0) gaps.push(`Connection ${connection.id} records no ${missing.join(", ")}: it was registered before they were recorded. Registering it again records them.`);
+	}
+	return settle(gaps, [], facts);
+}
+/** A day, in ms. Key ages are reported in whole days, which is how a rotation cadence is reasoned about. */
+const MS_PER_DAY = 864e5;
+/** Whether a key verifies right now: started, not past its window, not revoked. */
+function isLive(key, now) {
+	if (key.revokedAt !== null) return false;
+	if (key.validFrom.getTime() > now.getTime()) return false;
+	return key.validUntil === null || key.validUntil.getTime() > now.getTime();
+}
+/** Secrets' facts, gaps and unknowns from its declared health — by standing for a state, never by its word. */
+function secretsRotation(input, facts, gaps, unknowns) {
+	if (input.state === "not-composed") {
+		unknowns.push(`${SECRETS_PACKAGE} is not composed, so no secret's rotation cadence is declared here.`);
+		return;
+	}
+	const report = input.report;
+	if (report.state === "withheld") {
+		const scopes = [...new Set(input.keys.map((key) => `\`${key.scope}\``))].join(", ");
+		unknowns.push(`This connection is not granted ${scopes}, the scope \`${SECRETS_CAPABILITY}\` reports rotation status under.`);
+		return;
+	}
+	if (report.state === "unavailable") {
+		unknowns.push(`\`${SECRETS_CAPABILITY}\` could not report its rotation status on this call.`);
+		return;
+	}
+	if (report.state === "undeclared") {
+		unknowns.push(`\`${SECRETS_CAPABILITY}\` reports no rotation status: it predates the health summary.`);
+		return;
+	}
+	for (const key of input.keys) {
+		const value = report.values[key.key];
+		if (value === void 0) continue;
+		const standing = standingOf(key, value);
+		facts.push({
+			fact: key.key,
+			subject: SECRETS_CAPABILITY,
+			value: key.kind === "count" ? value : standing,
+			source: "capabilityHealth"
+		});
+		if (standing === "attention") gaps.push(`\`${SECRETS_CAPABILITY}\` reports \`${key.key}\` wanting attention. Its status route says which and why.`);
+	}
+}
+/**
+* Keys and secrets rotate: each connection's live keys and the age of the oldest, secrets' declared cadence and
+* what is past it, and the field key's retirement guard (#390). Ages are facts and never graded here: the seam
+* declares no cadence for control-plane keys, and inventing one would be the pack's opinion.
+*/
+function deriveKeyRotation(input) {
+	const facts = [];
+	const gaps = [];
+	const unknowns = [];
+	if (input.connections === null) unknowns.push(`${CONNECTIONS_UNREADABLE} Key ages are unknown.`);
+	else for (const connection of input.connections) {
+		const live = connection.keys.filter((key) => isLive(key, input.now));
+		const oldest = live.reduce((min, key) => min === null ? key.validFrom.getTime() : Math.min(min, key.validFrom.getTime()), null);
+		facts.push({
+			fact: "liveKeys",
+			subject: connection.id,
+			value: live.length,
+			source: "connectionKeys"
+		}, {
+			fact: "oldestLiveKeyAgeDays",
+			subject: connection.id,
+			value: oldest === null ? null : Math.floor((input.now.getTime() - oldest) / MS_PER_DAY),
+			source: "connectionKeys"
+		});
+	}
+	secretsRotation(input.secrets, facts, gaps, unknowns);
+	facts.push({
+		fact: "fieldKeyRetirementBlocked",
+		value: input.retirement.blocked,
+		source: "fieldKeyRetirement"
+	}, {
+		fact: "fieldKeyRetirementReasons",
+		value: [...input.retirement.reasons],
+		source: "fieldKeyRetirement"
+	}, {
+		fact: "liveFieldKeyVersions",
+		value: input.retirement.liveVersions,
+		source: "fieldKeyRetirement"
+	});
+	if (input.retirement.blocked) gaps.push(`The field key's oldest live version is held from retirement: ${input.retirement.reasons.join(", ")}.`);
+	else if (input.retirement.reasons.includes("incomplete-coverage")) unknowns.push("The field key's retirement guard could not read every source on this call.");
+	return settle(gaps, unknowns, facts);
+}
+/**
+* Change history per environment: each bound database's applied migrations, the last group and when it applied
+* (#729). Behind `migrations:read`, as the same numbers are on the manifest, so the pack never widens it.
+*/
+function deriveChangeHistory(input) {
+	if (!input.granted) return settle([], [`This connection is not granted \`${MIGRATIONS_READ_SCOPE}\`, the scope migration state is read under.`], []);
+	const facts = [];
+	const gaps = [];
+	const unknowns = [];
+	for (const database of input.databases) {
+		if (database.state === "unreadable") {
+			unknowns.push(`The migration ledger of database \`${database.database}\` could not be read on this call.`);
+			continue;
+		}
+		const subject = database.database;
+		facts.push({
+			fact: "applied",
+			subject,
+			value: database.applied.length,
+			source: "migrationLedger"
+		}, {
+			fact: "pending",
+			subject,
+			value: database.pending.length,
+			source: "migrationLedger"
+		}, {
+			fact: "undeclared",
+			subject,
+			value: database.undeclared.length,
+			source: "migrationLedger"
+		}, {
+			fact: "lastGroup",
+			subject,
+			value: database.lastGroup?.group ?? null,
+			source: "migrationLedger"
+		}, {
+			fact: "lastGroupAppliedAt",
+			subject,
+			value: database.lastGroup?.appliedAt ?? null,
+			source: "migrationLedger"
+		});
+		if (database.pending.length > 0) gaps.push(`Database \`${subject}\` has ${database.pending.length} declared ${database.pending.length === 1 ? "migration" : "migrations"} this build ships and has not applied.`);
+	}
+	return settle(gaps, unknowns, facts);
+}
+/**
+* Data classified and encrypted at rest: the classes the stored schemas hold (#132) beside the classes the
+* project declared, and the fields marked `encrypted()` (#390). Classes and counts only, never a field's name:
+* those are `GET /privacy`'s, behind their own scope.
+*/
+function deriveDataProtection(input) {
+	if (input.inventory === null) return settle([], ["This Worker's stored schemas could not be walked for privacy markers on this call."], []);
+	const held = input.inventory;
+	const facts = [
+		{
+			fact: "classesHeld",
+			value: [...held.observed],
+			source: "privacyMarkers"
+		},
+		...held.observed.map((name) => ({
+			fact: "markedFields",
+			subject: name,
+			value: held.counts[name] ?? 0,
+			source: "privacyMarkers"
+		})),
+		{
+			fact: "schemasWalked",
+			value: held.schemasWalked,
+			source: "privacyMarkers"
+		},
+		{
+			fact: "encryptedFields",
+			value: held.encryptedFields,
+			source: "encryptedMarkers"
+		},
+		{
+			fact: "unrotatableEncryptedFields",
+			value: held.unrotatable,
+			source: "encryptedMarkers"
+		},
+		{
+			fact: "classesDeclared",
+			value: input.attestation === null ? null : [...input.attestation.classes],
+			source: "privacyAttestation"
+		}
+	];
+	if (input.attestation === null) return settle([], ["No privacy attestation reached this Worker, so what the project declares cannot be read. A deploy through the CLI writes one."], facts);
+	const declared = new Set(input.attestation.classes);
+	const observed = new Set(held.observed);
+	return settle([...held.observed.filter((name) => !declared.has(name)).map((name) => `Stored schemas hold \`${name}\` fields the project never declared.`), ...input.attestation.classes.filter((name) => !observed.has(name)).map((name) => `The project declares \`${name}\` and no stored field is marked with it.`)], [], facts);
+}
+/**
+* CSRF wherever cookie mode is: the routes that accept a session cookie, and whether a composed capability
+* publishes the same-origin policy `requireSameOrigin()` enforces. No route taking a cookie needs none.
+*/
+function deriveCsrf(input) {
+	if (input.operations === void 0) return settle([], [NO_ROUTE_TABLE], []);
+	const sessionRoutes = input.operations.filter((operation) => strategiesOf(operation).includes("session")).length;
+	const facts = [{
+		fact: "sessionRoutes",
+		value: sessionRoutes,
+		source: "routeSpec"
+	}, {
+		fact: "sameOriginPolicy",
+		value: input.sameOriginPublished,
+		source: "sameOriginGate"
+	}];
+	return settle(sessionRoutes > 0 && !input.sameOriginPublished ? [`${sessionRoutes} ${sessionRoutes === 1 ? "route accepts" : "routes accept"} a session cookie and no composed capability publishes a same-origin policy. Compose \`@pithy-sh/auth\`.`] : [], [], facts);
+}
+//#endregion
+export { deriveAuditLogging, deriveChangeHistory, deriveCsrf, deriveDataProtection, deriveKeyRotation, deriveManagementAccess, deriveRouteVerification, evidenceEntry, settle };

package/dist/controlPlane/evidence/mapping.d.ts

@@ -0,0 +1,85 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * The evidence pack's mapping table (#821): which controls the Worker derives evidence for, and the SOC 2 and
+ * ISO/IEC 27001:2022 references each one answers.
+ *
+ * **Evidence, never a verdict.** Each control the pack reports carries the facts it read, where each came from,
+ * and one of three states. None of them is a judgment about a framework: an auditor decides that, and nothing
+ * here or on the wire uses the vocabulary of one.
+ *
+ * **Versioned, and the version travels with every pack.** A reference moving, a control joining or leaving, or
+ * a rule for a state changing is a new {@link EVIDENCE_MAPPING_VERSION}, so a pack read last quarter and one read
+ * today can be told apart by the number on them. A control needing a declaration the kit does not hold is a
+ * later version of this table, never a guess in this one.
+ *
+ * Zod-only, so a management client can import the table and the vocabulary without the Worker's runtime.
+ */
+/** The version of this table. Bumped whenever a control, a reference, or a state rule changes. */
+export declare const EVIDENCE_MAPPING_VERSION = 1;
+/** The seven controls, by id. Stable: a client keys on these, and the title may be reworded. */
+export declare const EVIDENCE_CONTROL_IDS: readonly ["audit-logging", "route-verification", "management-access", "key-rotation", "change-history", "data-protection", "csrf"];
+/** One control's id. */
+export declare const EvidenceControlId: z.ZodEnum<{
+    "audit-logging": "audit-logging";
+    "change-history": "change-history";
+    csrf: "csrf";
+    "data-protection": "data-protection";
+    "key-rotation": "key-rotation";
+    "management-access": "management-access";
+    "route-verification": "route-verification";
+}>;
+export type EvidenceControlId = z.infer<typeof EvidenceControlId>;
+/**
+ * What the Worker could say about a control. Three states, and none of them a verdict.
+ *
+ * - `evidenced`: the facts are present.
+ * - `gap`: something is missing, and the entry names what.
+ * - `not-derivable`: the Worker cannot say, and the entry names why.
+ */
+export declare const EvidenceState: z.ZodEnum<{
+    evidenced: "evidenced";
+    gap: "gap";
+    "not-derivable": "not-derivable";
+}>;
+export type EvidenceState = z.infer<typeof EvidenceState>;
+/**
+ * Where a fact came from: the declaration or record the Worker read it off. Every fact names one, so an auditor
+ * can follow each back to the code or the row it is about.
+ */
+export declare const EvidenceSource: z.ZodEnum<{
+    auditRecorder: "auditRecorder";
+    bindings: "bindings";
+    capabilityHealth: "capabilityHealth";
+    composition: "composition";
+    connection: "connection";
+    connectionKeys: "connectionKeys";
+    encryptedMarkers: "encryptedMarkers";
+    fieldKeyRetirement: "fieldKeyRetirement";
+    migrationLedger: "migrationLedger";
+    privacyAttestation: "privacyAttestation";
+    privacyMarkers: "privacyMarkers";
+    routeSpec: "routeSpec";
+    sameOriginGate: "sameOriginGate";
+}>;
+export type EvidenceSource = z.infer<typeof EvidenceSource>;
+/** One row of the table: what a control is called and the framework references it answers. */
+export interface EvidenceControl {
+    readonly title: string;
+    readonly soc2: readonly string[];
+    readonly iso27001: readonly string[];
+}
+/**
+ * The table itself, keyed by control so every id has exactly one row by construction. The pack reports them in
+ * {@link EVIDENCE_CONTROL_IDS} order. SOC 2 references are the AICPA Trust Services Criteria; ISO references are
+ * ISO/IEC 27001:2022 Annex A.
+ */
+export declare const EVIDENCE_CONTROLS: Readonly<Record<EvidenceControlId, EvidenceControl>>;
+/** The capability whose composition is the audit-logging control's subject. Named in the gap it reports. */
+export declare const AUDIT_PACKAGE = "@pithy-sh/audit";
+/** The capability whose declared health carries secrets' rotation cadence and what is overdue. */
+export declare const SECRETS_CAPABILITY = "secrets";
+/** Its package, named in a reason. */
+export declare const SECRETS_PACKAGE = "@pithy-sh/secrets";
+//# sourceMappingURL=mapping.d.ts.map

package/dist/controlPlane/evidence/mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapping.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/evidence/mapping.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;GAcG;AAEH,kGAAkG;AAClG,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,gGAAgG;AAChG,eAAO,MAAM,oBAAoB,YAC/B,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,MAAM,CACE,CAAC;AAEX,wBAAwB;AACxB,eAAO,MAAM,iBAAiB;;;;;;;;EAEmF,CAAC;AAClH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;;EAIvB,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;EAkBxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,8FAA8F;AAC9F,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,iBAAiB,EAAE,eAAe,CAAC,CAgBlF,CAAC;AAEF,4GAA4G;AAC5G,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAE/C,kGAAkG;AAClG,eAAO,MAAM,kBAAkB,YAAY,CAAC;AAE5C,sCAAsC;AACtC,eAAO,MAAM,eAAe,sBAAsB,CAAC"}

package/dist/controlPlane/evidence/mapping.js

@@ -0,0 +1,114 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+//#region src/controlPlane/evidence/mapping.ts
+/**
+* The evidence pack's mapping table (#821): which controls the Worker derives evidence for, and the SOC 2 and
+* ISO/IEC 27001:2022 references each one answers.
+*
+* **Evidence, never a verdict.** Each control the pack reports carries the facts it read, where each came from,
+* and one of three states. None of them is a judgment about a framework: an auditor decides that, and nothing
+* here or on the wire uses the vocabulary of one.
+*
+* **Versioned, and the version travels with every pack.** A reference moving, a control joining or leaving, or
+* a rule for a state changing is a new {@link EVIDENCE_MAPPING_VERSION}, so a pack read last quarter and one read
+* today can be told apart by the number on them. A control needing a declaration the kit does not hold is a
+* later version of this table, never a guess in this one.
+*
+* Zod-only, so a management client can import the table and the vocabulary without the Worker's runtime.
+*/
+/** The version of this table. Bumped whenever a control, a reference, or a state rule changes. */
+const EVIDENCE_MAPPING_VERSION = 1;
+/** The seven controls, by id. Stable: a client keys on these, and the title may be reworded. */
+const EVIDENCE_CONTROL_IDS = [
+	"audit-logging",
+	"route-verification",
+	"management-access",
+	"key-rotation",
+	"change-history",
+	"data-protection",
+	"csrf"
+];
+/** One control's id. */
+const EvidenceControlId = z.enum(EVIDENCE_CONTROL_IDS).describe("The control this entry reports on, as a stable id. Keyed on by clients; the title may be reworded.");
+/**
+* What the Worker could say about a control. Three states, and none of them a verdict.
+*
+* - `evidenced`: the facts are present.
+* - `gap`: something is missing, and the entry names what.
+* - `not-derivable`: the Worker cannot say, and the entry names why.
+*/
+const EvidenceState = z.enum([
+	"evidenced",
+	"gap",
+	"not-derivable"
+]).describe("What the Worker could say about this control: `evidenced` when the facts are present, `gap` when something is missing and the entry names what, `not-derivable` when the Worker cannot say and the entry names why. Evidence for an auditor, never a judgment.");
+/**
+* Where a fact came from: the declaration or record the Worker read it off. Every fact names one, so an auditor
+* can follow each back to the code or the row it is about.
+*/
+const EvidenceSource = z.enum([
+	"composition",
+	"auditRecorder",
+	"bindings",
+	"routeSpec",
+	"connection",
+	"connectionKeys",
+	"capabilityHealth",
+	"fieldKeyRetirement",
+	"migrationLedger",
+	"privacyMarkers",
+	"encryptedMarkers",
+	"privacyAttestation",
+	"sameOriginGate"
+]).describe("The declaration a fact was read from: `composition` (the capabilities this Worker composes), `auditRecorder` (the audit emit seam), `bindings` (this Worker's bindings), `routeSpec` (each route's `describeRoute`), `connection` (a control-plane connection's row), `connectionKeys` (its registered keys), `capabilityHealth` (a capability's declared health summary), `fieldKeyRetirement` (the field key's retirement guard), `migrationLedger` (a database's migration ledger), `privacyMarkers` (privacy-class markers on stored schemas), `encryptedMarkers` (`encrypted()` markers), `privacyAttestation` (the classes the last `pithy deploy` declared), or `sameOriginGate` (the same-origin policy a capability publishes).");
+/**
+* The table itself, keyed by control so every id has exactly one row by construction. The pack reports them in
+* {@link EVIDENCE_CONTROL_IDS} order. SOC 2 references are the AICPA Trust Services Criteria; ISO references are
+* ISO/IEC 27001:2022 Annex A.
+*/
+const EVIDENCE_CONTROLS = {
+	"audit-logging": {
+		title: "Audit logging in force",
+		soc2: ["CC7.2"],
+		iso27001: ["A.8.15"]
+	},
+	"route-verification": {
+		title: "Every route declares how a caller is verified",
+		soc2: ["CC6.1"],
+		iso27001: ["A.5.15"]
+	},
+	"management-access": {
+		title: "Management access attributed and scoped",
+		soc2: ["CC6.2", "CC6.3"],
+		iso27001: ["A.5.18"]
+	},
+	"key-rotation": {
+		title: "Keys and secrets rotate",
+		soc2: ["CC6.1"],
+		iso27001: ["A.8.24"]
+	},
+	"change-history": {
+		title: "Change history per environment",
+		soc2: ["CC8.1"],
+		iso27001: ["A.8.32"]
+	},
+	"data-protection": {
+		title: "Data classified and encrypted at rest",
+		soc2: ["C1.1"],
+		iso27001: ["A.8.24"]
+	},
+	csrf: {
+		title: "CSRF wherever cookie mode is",
+		soc2: ["CC6.6"],
+		iso27001: ["A.8.26"]
+	}
+};
+/** The capability whose composition is the audit-logging control's subject. Named in the gap it reports. */
+const AUDIT_PACKAGE = "@pithy-sh/audit";
+/** The capability whose declared health carries secrets' rotation cadence and what is overdue. */
+const SECRETS_CAPABILITY = "secrets";
+/** Its package, named in a reason. */
+const SECRETS_PACKAGE = "@pithy-sh/secrets";
+//#endregion
+export { AUDIT_PACKAGE, EVIDENCE_CONTROLS, EVIDENCE_CONTROL_IDS, EVIDENCE_MAPPING_VERSION, EvidenceControlId, EvidenceSource, EvidenceState, SECRETS_CAPABILITY, SECRETS_PACKAGE };

package/dist/controlPlane/evidence/pack.d.ts

@@ -0,0 +1,46 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Context } from "hono";
+import type { Capability, PithyHonoEnv } from "../../capability/capability";
+import type { RouteGroup } from "../../openapi/document";
+import type { PrivacyInventory } from "../../privacy/report";
+import type { RetirementVerdict } from "../../privacy/retirement";
+import type { ControlPlaneContext } from "../context";
+import { type ControlPlaneDatabase } from "../data/tables";
+import { type CapabilityHealthSource } from "../discovery/health";
+import type { ControlPlaneEvidenceResponse } from "../http/responses";
+import { type ComposedMigrationDatabase } from "../migrationState/migrationState";
+/**
+ * The reads behind the evidence pack (#821): what the Worker composes, records and declares, gathered once per
+ * call and handed to the pure derivations in `./derive.ts`.
+ *
+ * **Every read reports what it found or that it could not look, and never throws past here.** One unreadable
+ * table costs the controls that read it their answer — `not-derivable`, with the reason — and the pack still
+ * answers. A cause goes to the Worker's log, for the operator, and never into the pack: a D1 error can name a
+ * table or a query.
+ *
+ * **The pack never widens a scope.** Migration state is read only when the connection holds `migrations:read`,
+ * and a capability's health only for the keys this connection is granted, exactly as the manifest reads them.
+ */
+/** What the pack reads from the composed seam. Thunks, because the `compose` hook fills them after routes mount. */
+export interface EvidenceSources {
+    /** Every capability this Worker composed. */
+    composition: () => readonly Capability[];
+    /** Every capability's health contribution, by name. */
+    composedHealth: () => ReadonlyMap<string, CapabilityHealthSource>;
+    /** Every database this Worker binds, with what this build declares for it. */
+    composedMigrations: () => readonly ComposedMigrationDatabase[];
+    /** The privacy inventory, walked once per isolate. */
+    privacyInventory: () => PrivacyInventory;
+    /** The field key's retirement guard. Never throws. */
+    retirement: (env: Record<string, unknown>) => Promise<RetirementVerdict>;
+    /** The route table `createBackend` recorded, or `undefined` for an app it did not assemble. */
+    routeGroups: () => readonly RouteGroup[] | undefined;
+    /** The app database for this request. */
+    database: (c: Context<PithyHonoEnv>) => ControlPlaneDatabase;
+    /** The clock. */
+    now: () => Date;
+}
+/** Read everything the pack derives from, and derive it. */
+export declare function readEvidencePack(c: Context<PithyHonoEnv>, sources: EvidenceSources, context: ControlPlaneContext): Promise<ControlPlaneEvidenceResponse>;
+//# sourceMappingURL=pack.d.ts.map

package/dist/controlPlane/evidence/pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/evidence/pack.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAmC,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,OAAO,EAAE,KAAK,sBAAsB,EAAwB,MAAM,qBAAqB,CAAC;AACxF,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,EAAE,KAAK,yBAAyB,EAA0B,MAAM,kCAAkC,CAAC;AAiB1G;;;;;;;;;;;GAWG;AAEH,oHAAoH;AACpH,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,WAAW,EAAE,MAAM,SAAS,UAAU,EAAE,CAAC;IACzC,uDAAuD;IACvD,cAAc,EAAE,MAAM,WAAW,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAClE,8EAA8E;IAC9E,kBAAkB,EAAE,MAAM,SAAS,yBAAyB,EAAE,CAAC;IAC/D,sDAAsD;IACtD,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;IACzC,sDAAsD;IACtD,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACzE,+FAA+F;IAC/F,WAAW,EAAE,MAAM,SAAS,UAAU,EAAE,GAAG,SAAS,CAAC;IACrD,yCAAyC;IACzC,QAAQ,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,KAAK,oBAAoB,CAAC;IAC7D,iBAAiB;IACjB,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAqED,4DAA4D;AAC5D,wBAAsB,gBAAgB,CACpC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,EACxB,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,4BAA4B,CAAC,CAiDvC"}