@pithy-sh/core 0.12.0 → 0.14.0

package/dist/controlPlane/erasure/attest.js

@@ -0,0 +1,164 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/controlPlane/erasure/attest.ts
+/**
+* **The erasure attestation, assembled (#823)** — pure functions over a subject's lifecycle rows and the audit events
+* that name it, so every rule here is tested without a database.
+*
+* ## Which deletion
+*
+* A subject can be deleted, restored, and deleted again. The attestation is about the **deletion in force**: the
+* first `deleted` row after the last `restored`. A subject whose last act was a restore has no erasure to attest.
+* A hard deletion that brought a soft one forward writes a second `deleted` row in the same cycle, so the deletion
+* reads as `hard` and comes due when the later row says.
+*
+* ## Where the purge stands
+*
+* `complete` once a `purged` row is written. `failed` when the last thing the purge wrote was its failure — a later
+* pass that runs a step again puts it back `in_progress`. `scheduled` while nothing has run and the window is still
+* open. `in_progress` otherwise. **Overdue** is not a state: a purge not complete two days after it came due has
+* missed a daily pass, whatever it last wrote, and is named with the step it stopped at.
+*
+* ## A step run twice
+*
+* The daily pass is the purge's outer retry, so a failed purge's steps run again the next day and record again.
+* Each capability is shown once, in the order it first ran, as it last finished.
+*/
+/** How long after coming due a purge that has not completed is overdue: two daily passes. */
+const ERASURE_OVERDUE_AFTER_MS = 1728e5;
+/** The step a purge that has run nothing is named as having stopped at. */
+const ERASURE_NOT_STARTED = "due";
+/** The rows of the deletion in force, or `null` when there is none — never deleted, or restored since. */
+function deletionInForce(rows) {
+	let start = -1;
+	for (let index = 0; index < rows.length; index += 1) {
+		const row = rows[index];
+		if (row?.action === "restored") start = -1;
+		else if (row?.action === "deleted" && start === -1) start = index;
+	}
+	return start === -1 ? null : rows.slice(start);
+}
+/** A citation as the wire carries it. */
+function cited(citation) {
+	if (!citation) return null;
+	return {
+		eventId: citation.eventId,
+		action: citation.action,
+		occurredAt: citation.occurredAt.toISOString(),
+		tenant: citation.tenant,
+		seq: citation.seq,
+		hash: citation.hash
+	};
+}
+/** The newest citation matching, or undefined. */
+function latest(citations, match) {
+	let found;
+	for (const citation of citations) if (match(citation) && (!found || citation.occurredAt.getTime() >= found.occurredAt.getTime())) found = citation;
+	return found;
+}
+/** One subject's attestation, or `null` when it has no deletion in force. */
+function attest(input) {
+	const cycle = deletionInForce(input.rows);
+	const deletion = cycle?.[0];
+	if (!cycle || !deletion) return null;
+	const deletions = cycle.filter((row) => row.action === "deleted");
+	const mode = deletions.some((row) => row.mode === "hard") ? "hard" : deletion.mode ?? null;
+	const purgeAfter = [...deletions].reverse().find((row) => row.purgeAfter)?.purgeAfter ?? null;
+	const citations = (input.citations ?? []).filter((each) => each.occurredAt.getTime() >= deletion.at.getTime());
+	const steps = /* @__PURE__ */ new Map();
+	let activity;
+	let purged;
+	for (const row of cycle) if (row.action === "purge_step" || row.action === "purge_retained") {
+		steps.set(row.step ?? "", row);
+		activity = row;
+	} else if (row.action === "purge_failed") activity = row;
+	else if (row.action === "purged") purged = row;
+	const state = stateOf({
+		purged,
+		activity,
+		purgeAfter,
+		now: input.now
+	});
+	const overdue = (state === "in_progress" || state === "failed") && purgeAfter !== null && input.now.getTime() - purgeAfter.getTime() > 1728e5;
+	const stoppedAt = state === "failed" || overdue ? activity?.step ?? "due" : null;
+	const views = [...steps.values()].map((row) => {
+		const capability = row.step ?? "";
+		const retained = row.action === "purge_retained";
+		return {
+			capability,
+			disposition: retained ? "retained" : "erased",
+			reason: retained ? row.reason : null,
+			summary: retained ? null : row.reason,
+			completedAt: row.at.toISOString(),
+			audit: cited(latest(citations, (each) => each.action === input.actions.step && each.step === capability))
+		};
+	});
+	return {
+		subject: {
+			type: input.subject,
+			id: input.subjectId
+		},
+		deletion: {
+			at: deletion.at.toISOString(),
+			actorType: deletion.actorType,
+			reason: deletion.reason,
+			mode,
+			purgeAfter: purgeAfter ? purgeAfter.toISOString() : null,
+			audit: cited(citations.find((each) => input.actions.deleted.includes(each.action)))
+		},
+		state,
+		overdue,
+		stoppedAt,
+		steps: views,
+		completedAt: purged ? purged.at.toISOString() : null,
+		completion: purged ? cited(latest(citations, (each) => each.action === input.actions.purged)) : null,
+		failure: state === "failed" ? cited(latest(citations, (each) => each.action === input.actions.failed)) : null,
+		trail: input.citations === null ? "absent" : "recorded"
+	};
+}
+/** Where a purge stands, from its last activity. See the file header. */
+function stateOf(input) {
+	if (input.purged) return "complete";
+	if (input.activity?.action === "purge_failed") return "failed";
+	if (!input.activity && (input.purgeAfter === null || input.purgeAfter.getTime() > input.now.getTime())) return "scheduled";
+	return "in_progress";
+}
+/** One attestation, summarized for the period read. */
+function periodEntry(attestation) {
+	return {
+		subject: attestation.subject,
+		state: attestation.state,
+		overdue: attestation.overdue,
+		purgeAfter: attestation.deletion.purgeAfter,
+		completedAt: attestation.completedAt,
+		stoppedAt: attestation.stoppedAt
+	};
+}
+/** The period's counts and the purges that need someone, from its entries. */
+function summarize(entries) {
+	const counts = {
+		scheduled: 0,
+		inProgress: 0,
+		complete: 0,
+		failed: 0,
+		overdue: 0
+	};
+	for (const entry of entries) {
+		if (entry.state === "scheduled") counts.scheduled += 1;
+		else if (entry.state === "in_progress") counts.inProgress += 1;
+		else if (entry.state === "complete") counts.complete += 1;
+		else counts.failed += 1;
+		if (entry.overdue) counts.overdue += 1;
+	}
+	return {
+		counts,
+		attention: entries.filter((entry) => entry.state === "failed" || entry.overdue)
+	};
+}
+/** Every entry, oldest due first; a deletion recorded before #823 has no due instant and sorts last. */
+function byDue(entries) {
+	const key = (entry) => entry.purgeAfter ? Date.parse(entry.purgeAfter) : Number.MAX_SAFE_INTEGER;
+	return [...entries].sort((a, b) => key(a) - key(b) || a.subject.id.localeCompare(b.subject.id));
+}
+//#endregion
+export { ERASURE_NOT_STARTED, ERASURE_OVERDUE_AFTER_MS, attest, byDue, deletionInForce, periodEntry, summarize };

package/dist/controlPlane/erasure/read.d.ts

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Capability } from "../../capability/capability";
+import type { ErasureRecords } from "../../capability/erasure";
+import type { PurgeSubject } from "../../capability/purge";
+import type { ControlPlaneErasurePeriodResponse, ControlPlaneErasureSubjectResponse } from "../http/responses";
+import type { ErasurePeriodQuery } from "../http/schemas";
+/**
+ * **The two erasure reads (#823), over whatever this Worker composes.**
+ *
+ * The rows live in the capability that owns each subject — auth for a user, organization for an organization —
+ * and are read through the {@link ErasureRecords} each declares. The events live in the audit trail and are read
+ * through the citation reader `@pithy-sh/audit` declares. Neither is imported: both are found among the composed
+ * capabilities, so a Worker with no organization attests users only and says so, and one with no audit attests from
+ * the lifecycle rows and says the trail is absent.
+ */
+/** The default window: a quarter. */
+export declare const ERASURE_DEFAULT_WINDOW_MS: number;
+/** The longest window one read covers: a year and a day, so a year's audit is one call. */
+export declare const ERASURE_MAX_WINDOW_MS: number;
+/** What the reads need from the seam. */
+export interface ErasureReadDeps {
+    /** Every composed capability. */
+    readonly composition: () => readonly Capability[];
+    /** The clock. */
+    readonly now: () => Date;
+}
+/** The capability recording each subject's purges, first declared wins. */
+export declare function erasureProviders(capabilities: readonly Capability[]): Map<PurgeSubject, ErasureRecords>;
+/** The window a period read covers, defaulted and bounded. */
+export declare function erasureWindow(query: ErasurePeriodQuery, now: Date): {
+    since: Date;
+    until: Date;
+};
+/** `GET /control-plane/erasure/:subjectType/:subjectId`. */
+export declare function readErasureSubject(env: Record<string, unknown>, deps: ErasureReadDeps, subject: PurgeSubject, subjectId: string): Promise<ControlPlaneErasureSubjectResponse>;
+/** `GET /control-plane/erasure?since&until`. */
+export declare function readErasurePeriod(env: Record<string, unknown>, deps: ErasureReadDeps, query: ErasurePeriodQuery): Promise<ControlPlaneErasurePeriodResponse>;
+//# sourceMappingURL=read.d.ts.map

package/dist/controlPlane/erasure/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/erasure/read.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,KAAK,EACV,iCAAiC,EACjC,kCAAkC,EAEnC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAG1D;;;;;;;;GAQG;AAEH,qCAAqC;AACrC,eAAO,MAAM,yBAAyB,QAAkB,CAAC;AAEzD,2FAA2F;AAC3F,eAAO,MAAM,qBAAqB,QAAmB,CAAC;AAKtD,yCAAyC;AACzC,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,SAAS,UAAU,EAAE,CAAC;IAClD,iBAAiB;IACjB,QAAQ,CAAC,GAAG,EAAE,MAAM,IAAI,CAAC;CAC1B;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,GAAG,GAAG,CAAC,YAAY,EAAE,cAAc,CAAC,CAOvG;AAED,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,EAAE,GAAG,EAAE,IAAI,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,CAgBhG;AA2BD,4DAA4D;AAC5D,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,kCAAkC,CAAC,CAuB7C;AAED,gDAAgD;AAChD,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,iCAAiC,CAAC,CAmC5C"}

package/dist/controlPlane/erasure/read.js

@@ -0,0 +1,140 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { NotFoundError, ValidationError } from "../../error/pithyError.js";
+import { composedAuditCitations } from "../../audit/citations.js";
+import { attest, byDue, periodEntry, summarize } from "./attest.js";
+//#region src/controlPlane/erasure/read.ts
+/**
+* **The two erasure reads (#823), over whatever this Worker composes.**
+*
+* The rows live in the capability that owns each subject — auth for a user, organization for an organization —
+* and are read through the {@link ErasureRecords} each declares. The events live in the audit trail and are read
+* through the citation reader `@pithy-sh/audit` declares. Neither is imported: both are found among the composed
+* capabilities, so a Worker with no organization attests users only and says so, and one with no audit attests from
+* the lifecycle rows and says the trail is absent.
+*/
+/** The default window: a quarter. */
+const ERASURE_DEFAULT_WINDOW_MS = 7776e6;
+/** The longest window one read covers: a year and a day, so a year's audit is one call. */
+const ERASURE_MAX_WINDOW_MS = 316224e5;
+/** How many subjects one history or citation read names at once — inside D1's bound-parameter limit. */
+const CHUNK = 50;
+/** The capability recording each subject's purges, first declared wins. */
+function erasureProviders(capabilities) {
+	const providers = /* @__PURE__ */ new Map();
+	for (const capability of capabilities) {
+		const records = capability.erasureRecords;
+		if (records && !providers.has(records.subject)) providers.set(records.subject, records);
+	}
+	return providers;
+}
+/** The window a period read covers, defaulted and bounded. */
+function erasureWindow(query, now) {
+	const until = query.until ? new Date(query.until) : now;
+	const since = query.since ? new Date(query.since) : /* @__PURE__ */ new Date(until.getTime() - ERASURE_DEFAULT_WINDOW_MS);
+	if (since.getTime() > until.getTime()) throw new ValidationError({
+		message: "`since` is after `until`.",
+		detail: `erasure window ${since.toISOString()} to ${until.toISOString()}`
+	});
+	if (until.getTime() - since.getTime() > 316224e5) throw new ValidationError({
+		message: "An erasure window is at most 366 days. Ask for a shorter one.",
+		detail: `erasure window ${since.toISOString()} to ${until.toISOString()}`
+	});
+	return {
+		since,
+		until
+	};
+}
+/** Every value in chunks of {@link CHUNK}. */
+function chunks(values) {
+	const out = [];
+	for (let index = 0; index < values.length; index += CHUNK) out.push(values.slice(index, index + CHUNK));
+	return out;
+}
+/** The audit events a subject's purge records, for these ids, or `null` with no audit composed. */
+async function citationsFor(capabilities, env, records, ids) {
+	const reader = composedAuditCitations(capabilities, env);
+	if (!reader) return null;
+	const { deleted, step, failed, purged } = records.auditActions;
+	const actions = [
+		...deleted,
+		step,
+		failed,
+		purged
+	];
+	const found = [];
+	for (const resourceIds of chunks(ids)) found.push(...await reader({
+		resourceType: records.resourceType,
+		resourceIds,
+		actions
+	}));
+	return found;
+}
+/** `GET /control-plane/erasure/:subjectType/:subjectId`. */
+async function readErasureSubject(env, deps, subject, subjectId) {
+	const capabilities = deps.composition();
+	const records = erasureProviders(capabilities).get(subject);
+	if (!records) throw new NotFoundError({
+		message: `This Worker records no erasures for ${subject === "user" ? "a user" : "an organization"}.`,
+		action: `Compose the capability that owns ${subject} purges in this Worker, then ask again.`,
+		detail: `no composed capability declares erasureRecords for ${subject}`
+	});
+	const now = deps.now();
+	const rows = await records.read(env).history([subjectId]);
+	const citations = rows.length === 0 ? null : await citationsFor(capabilities, env, records, [subjectId]);
+	const attestation = rows.length === 0 ? null : attest({
+		subject,
+		subjectId,
+		rows,
+		citations,
+		actions: records.auditActions,
+		now
+	});
+	if (!attestation) throw new NotFoundError({
+		message: "No erasure on record for this subject.",
+		action: "It was never deleted, or it was restored. Nothing has been erased.",
+		detail: `no deletion in force for ${subject} ${subjectId}`
+	});
+	return {
+		generatedAt: now.toISOString(),
+		attestation
+	};
+}
+/** `GET /control-plane/erasure?since&until`. */
+async function readErasurePeriod(env, deps, query) {
+	const now = deps.now();
+	const { since, until } = erasureWindow(query, now);
+	const providers = erasureProviders(deps.composition());
+	const entries = [];
+	for (const [subject, records] of providers) {
+		const reader = records.read(env);
+		const ids = await reader.subjectsIn(since, until);
+		for (const batch of chunks(ids)) {
+			const rows = await reader.history(batch);
+			for (const subjectId of batch) {
+				const attestation = attest({
+					subject,
+					subjectId,
+					rows: rows.filter((row) => row.subjectId === subjectId),
+					citations: null,
+					actions: records.auditActions,
+					now
+				});
+				if (attestation) entries.push(periodEntry(attestation));
+			}
+		}
+	}
+	const purges = byDue(entries);
+	const { counts, attention } = summarize(purges);
+	return {
+		generatedAt: now.toISOString(),
+		since: since.toISOString(),
+		until: until.toISOString(),
+		subjects: [...providers.keys()],
+		counts,
+		attention,
+		purges
+	};
+}
+//#endregion
+export { ERASURE_DEFAULT_WINDOW_MS, ERASURE_MAX_WINDOW_MS, erasureProviders, erasureWindow, readErasurePeriod, readErasureSubject };

package/dist/controlPlane/error/errors.d.ts

@@ -3,6 +3,7 @@
 import { PithyError } from "../../error/pithyError";
 import type { MessageParams } from "../../i18n/catalog";
 import type { UnmarkedString } from "../../privacy/types";
+import type { ControlPlaneActorKind } from "../data/connection";
 /**
  * The `control-plane` strategy's throw sugar. The `controlplane/*` codes live in core's closed
  * `KitErrorPayload` union (CLAUDE.md §Errors); these subclasses are the vehicles that set one.
@@ -35,18 +36,76 @@ export declare class ControlPlaneNotConnectedError extends PithyError {
         cause?: unknown;
     });
 }
+/**
+ * What a call under an OIDC trust carried when its claims did not match (#722), for the audit row and nobody
+ * else.
+ *
+ * Set only once the token's signature, issuer and audience have verified: by then the caller demonstrably
+ * holds a genuine token for this audience, so naming the claims it sent leaks nothing it does not already
+ * hold — and those claims are what an operator picks a matcher from. Before that the single-error discipline
+ * holds, and no refusal carries this.
+ */
+export interface ControlPlaneRefusedTrust {
+    /** The connection whose trust was named. */
+    readonly connectionId: string;
+    /** The trust the call named. */
+    readonly trustId: string;
+    /** The workload's claims, as strings, capped — `observedClaims` in `../data/oidcTrust`. */
+    readonly observedClaims: Readonly<Record<string, string>>;
+}
 /**
  * The credential failed verification. One error for every step — pass the step in `detail` so the log
  * can say which, and the caller cannot.
  */
 export declare class ControlPlaneInvalidCredentialError extends PithyError {
-    constructor(args?: ControlPlaneErrorArgs, options?: {
+    /**
+     * A claim mismatch on an otherwise verified OIDC token, for the denial row. A property of the vehicle, never of
+     * `payload`, so the refusal a caller receives is the same one every other step answers. Null everywhere else.
+     */
+    readonly refusedTrust: ControlPlaneRefusedTrust | null;
+    constructor(args?: ControlPlaneErrorArgs & {
+        refusedTrust?: ControlPlaneRefusedTrust;
+    }, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Who a scope refusal refused, as verification proved it (#812).
+ *
+ * By the scope step the signature, the key, the lifetime and the body digest have all verified, so these are facts
+ * rather than claims. The gate writes them onto the denial row, which is what lets a known credential probing
+ * for scopes it lacks be traced back to it.
+ */
+export interface ControlPlaneRefusedCaller {
+    /** The connection the verified token addressed. */
+    readonly connectionId: string;
+    /** The token's `sub`, proven by the signature. */
+    readonly subject: string;
+    /** The registered key that verified the signature — or, for a call under an OIDC trust, the trust. */
+    readonly keyId: string;
+    /**
+     * Said only for a call under an OIDC trust (#722), in which case `keyId` names the trust. Absent reads as a key, as
+     * it does on the allowed row, so a trust's refusals are not recorded as a key's with an id no key has.
+     */
+    readonly credentialKind?: "trust";
+    /**
+     * The kind of client the connection was registered as, from the adopter's row and never the token — the same value
+     * the allowed row is stamped with, so a trail filtered on kind holds a client's refusals beside its calls. Null for a
+     * connection registered before kinds were recorded.
+     */
+    readonly actorKind: ControlPlaneActorKind | null;
+}
 /** The credential verified, but nothing granted it this operation. */
 export declare class ControlPlaneInsufficientScopeError extends PithyError {
-    constructor(args?: ControlPlaneErrorArgs, options?: {
+    /**
+     * The verified caller, for the audit row and nobody else. A property of the vehicle, never of `payload`: the HTTP
+     * codec encodes the payload alone, so the refusal a caller receives is unchanged. Null when a throw site has no
+     * verified caller to name.
+     */
+    readonly caller: ControlPlaneRefusedCaller | null;
+    constructor(args?: ControlPlaneErrorArgs & {
+        caller?: ControlPlaneRefusedCaller;
+    }, options?: {
         cause?: unknown;
     });
 }

package/dist/controlPlane/error/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/error/errors.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;;;;;;GAYG;AAEH,UAAU,qBAAqB;IAC7B,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;GAGG;AACH,qBAAa,6BAA8B,SAAQ,UAAU;IAC3D,YAAY,IAAI,GAAE,qBAA0B,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAc1E;CACF;AAED;;;GAGG;AACH,qBAAa,kCAAmC,SAAQ,UAAU;IAChE,YAAY,IAAI,GAAE,qBAA0B,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAc1E;CACF;AAED,sEAAsE;AACtE,qBAAa,kCAAmC,SAAQ,UAAU;IAChE,YAAY,IAAI,GAAE,qBAA0B,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAc1E;CACF;AAED,0DAA0D;AAC1D,qBAAa,4BAA6B,SAAQ,UAAU;IAC1D,YAAY,IAAI,GAAE,qBAA0B,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAY1E;CACF;AAED;;;;GAIG;AACH,qBAAa,4BAA6B,SAAQ,UAAU;IAC1D,YAAY,IAAI,GAAE,qBAA0B,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAY1E;CACF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/error/errors.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhE;;;;;;;;;;;;GAYG;AAEH,UAAU,qBAAqB;IAC7B,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;GAGG;AACH,qBAAa,6BAA8B,SAAQ,UAAU;IAC3D,YAAY,IAAI,GAAE,qBAA0B,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAc1E;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,wBAAwB;IACvC,4CAA4C;IAC5C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,gCAAgC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2FAA2F;IAC3F,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC3D;AAED;;;GAGG;AACH,qBAAa,kCAAmC,SAAQ,UAAU;IAChE;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAEvD,YACE,IAAI,GAAE,qBAAqB,GAAG;QAAE,YAAY,CAAC,EAAE,wBAAwB,CAAA;KAAO,EAC9E,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAgB9B;CACF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,mDAAmD;IACnD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sGAAsG;IACtG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,qBAAqB,GAAG,IAAI,CAAC;CAClD;AAED,sEAAsE;AACtE,qBAAa,kCAAmC,SAAQ,UAAU;IAChE;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,yBAAyB,GAAG,IAAI,CAAC;IAElD,YACE,IAAI,GAAE,qBAAqB,GAAG;QAAE,MAAM,CAAC,EAAE,yBAAyB,CAAA;KAAO,EACzE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAgB9B;CACF;AAED,0DAA0D;AAC1D,qBAAa,4BAA6B,SAAQ,UAAU;IAC1D,YAAY,IAAI,GAAE,qBAA0B,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAY1E;CACF;AAED;;;;GAIG;AACH,qBAAa,4BAA6B,SAAQ,UAAU;IAC1D,YAAY,IAAI,GAAE,qBAA0B,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAY1E;CACF"}

package/dist/controlPlane/error/errors.js

@@ -24,6 +24,11 @@ var ControlPlaneNotConnectedError = class extends PithyError {
 * can say which, and the caller cannot.
 */
 var ControlPlaneInvalidCredentialError = class extends PithyError {
+	/**
+	* A claim mismatch on an otherwise verified OIDC token, for the denial row. A property of the vehicle, never of
+	* `payload`, so the refusal a caller receives is the same one every other step answers. Null everywhere else.
+	*/
+	refusedTrust;
 	constructor(args = {}, options) {
 		super({
 			code: "controlplane/invalid_credential",
@@ -33,10 +38,17 @@ var ControlPlaneInvalidCredentialError = class extends PithyError {
 			detail: args.detail,
 			params: args.params
 		}, options);
+		this.refusedTrust = args.refusedTrust ?? null;
 	}
 };
 /** The credential verified, but nothing granted it this operation. */
 var ControlPlaneInsufficientScopeError = class extends PithyError {
+	/**
+	* The verified caller, for the audit row and nobody else. A property of the vehicle, never of `payload`: the HTTP
+	* codec encodes the payload alone, so the refusal a caller receives is unchanged. Null when a throw site has no
+	* verified caller to name.
+	*/
+	caller;
 	constructor(args = {}, options) {
 		super({
 			code: "controlplane/insufficient_scope",
@@ -46,6 +58,7 @@ var ControlPlaneInsufficientScopeError = class extends PithyError {
 			detail: args.detail,
 			params: args.params
 		}, options);
+		this.caller = args.caller ?? null;
 	}
 };
 /** The named key is not registered on this connection. */

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

@@ -0,0 +1,124 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { DescribedOperation } from "../../openapi/operations";
+import type { PrivacyAttestation } from "../../privacy/posture";
+import type { PrivacyInventory } from "../../privacy/report";
+import type { RetirementVerdict } from "../../privacy/retirement";
+import type { ControlPlaneConnection, RegisteredKey } from "../data/connection";
+import { type CapabilityHealthReport, type HealthSummaryKey } from "../discovery/healthSummary";
+import type { EvidenceEntry, EvidenceFact, MigrationDatabaseView } from "../http/responses";
+import { type EvidenceControlId, type EvidenceState } from "./mapping";
+/**
+ * The derivation behind each control in the evidence pack (#821): plain inputs in, facts and a state out.
+ *
+ * **Every function here is pure.** The reads — a D1 query, a health producer, the route table — happen in
+ * `./pack.ts`, which hands each one what it found or the fact that it could not look. So every rule for a state
+ * is tested here directly, without a Worker, and the rules cannot drift by being restated at a read site.
+ *
+ * **What decides a state.** A gap is something positively missing. Not-derivable is the Worker being unable to
+ * say. Evidenced is neither. A control with both reports `gap`, and lists the gaps first and the unknowns after,
+ * because something known to be missing is the more actionable fact and the unknowns are still there to read.
+ * Nothing here says more than the facts do: an unknown is never folded into `evidenced`.
+ */
+/** What a control's derivation produced, before the mapping table's references are attached. */
+export interface Derived {
+    state: EvidenceState;
+    reasons: string[];
+    facts: EvidenceFact[];
+}
+/** Settle a control's state from what was missing and what could not be read. See the module doc. */
+export declare function settle(gaps: readonly string[], unknowns: readonly string[], facts: EvidenceFact[]): Derived;
+/** One entry of the pack: the mapping table's row for the control, beside what was derived. */
+export declare function evidenceEntry(control: EvidenceControlId, derived: Derived): EvidenceEntry;
+/** What the audit-logging control reads. */
+export interface AuditLoggingInput {
+    /** The composed capability declaring an audit recorder, with each binding it writes through, or null for none. */
+    recorder: {
+        capability: string;
+        bindings: readonly {
+            binding: string;
+            present: boolean;
+        }[];
+    } | null;
+    /** Whether this very request's emit seam is a recorder rather than the no-op: the guard wrote through it. */
+    emitting: boolean;
+}
+/**
+ * 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.
+ */
+export declare function deriveAuditLogging(input: AuditLoggingInput): Derived;
+/**
+ * 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.
+ */
+export declare function deriveRouteVerification(operations: readonly DescribedOperation[] | undefined): Derived;
+/** What the management-access and key-rotation controls read off one connection row. Never key material. */
+export type ConnectionRecord = Pick<ControlPlaneConnection, "id" | "authorizedBy" | "actorKind" | "purpose" | "scopes"> & {
+    keys: readonly Pick<RegisteredKey, "validFrom" | "validUntil" | "revokedAt">[];
+};
+/**
+ * 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.
+ */
+export declare function deriveManagementAccess(connections: readonly ConnectionRecord[] | null): Derived;
+/** What secrets' rotation status was on this call: its health report and the keys that declare it, or absent. */
+export type SecretsRotationInput = {
+    state: "not-composed";
+} | {
+    state: "composed";
+    keys: readonly HealthSummaryKey[];
+    report: CapabilityHealthReport;
+};
+/** What the key-rotation control reads. */
+export interface KeyRotationInput {
+    connections: readonly ConnectionRecord[] | null;
+    now: Date;
+    secrets: SecretsRotationInput;
+    retirement: RetirementVerdict;
+}
+/**
+ * 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.
+ */
+export declare function deriveKeyRotation(input: KeyRotationInput): Derived;
+/** What the change-history control reads. */
+export interface ChangeHistoryInput {
+    /** Whether this connection holds `migrations:read`, the scope the seam keeps migration state behind. */
+    granted: boolean;
+    /** Each bound database's ledger, read only when granted. */
+    databases: readonly MigrationDatabaseView[];
+}
+/**
+ * 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.
+ */
+export declare function deriveChangeHistory(input: ChangeHistoryInput): Derived;
+/** What the data-protection control reads. */
+export interface DataProtectionInput {
+    /** The privacy inventory of every stored schema, or null where the walk could not run. */
+    inventory: PrivacyInventory | null;
+    /** What the last `pithy deploy` attested the project declares, or null where none reached this Worker. */
+    attestation: PrivacyAttestation | null;
+}
+/**
+ * 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.
+ */
+export declare function deriveDataProtection(input: DataProtectionInput): Derived;
+/** What the CSRF control reads. */
+export interface CsrfInput {
+    operations: readonly DescribedOperation[] | undefined;
+    /** Whether a composed capability published a same-origin policy on this request. */
+    sameOriginPublished: boolean;
+}
+/**
+ * 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.
+ */
+export declare function deriveCsrf(input: CsrfInput): Derived;
+//# sourceMappingURL=derive.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../../src/controlPlane/evidence/derive.ts"],"names":[],"mappings":"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"}