@pithy-sh/core 0.13.0 → 0.14.0

package/dist/audit/chain.js

@@ -0,0 +1,400 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+//#region src/audit/chain.ts
+/**
+* **The audit trail's hash chain (#822): its canonical form, its commitments, and its verifier.**
+*
+* Every event `@pithy-sh/audit` records after the upgrade carries the hash of the event before it in its tenant's
+* chain, computed over a canonical serialization. Editing, deleting or inserting a row then breaks a link, and a
+* chain rewritten end to end is caught against a checkpoint written outside the database.
+*
+* **It lives in core, not in the audit package**, because three readers need the same bytes: the recorder that
+* writes a link, the Worker's verify read, and `pithy audit verify`, which an auditor runs on an export with no
+* project and no `@pithy-sh/audit` installed. A second copy of the canonical form is a second definition of the
+* evidence, and the first time they differ every export reads as tampered.
+*
+* **Personal fields are committed, not included.** An event's hash covers a salted hash of its IP, user-agent and
+* metadata rather than the values, so an export that leaves them out still verifies. The salt is per event and
+* travels only with the values, so a commitment cannot be reversed by hashing every IPv4 address.
+*
+* **Nothing is signed.** The chain proves the trail is whole against its checkpoints; it adds no key and no way
+* to change the trail.
+*/
+/** The canonical form's version, the first element of every serialization. A new form is a new string. */
+const AUDIT_CHAIN_FORMAT = "pithy-audit-chain/1";
+/** A lowercase hex SHA-256 digest. */
+const Sha256Hex = z.string().regex(/^[0-9a-f]{64}$/, "A SHA-256 digest is 64 lowercase hex characters.").describe("A SHA-256 digest, 64 lowercase hex characters.");
+/**
+* Every field of an event its hash covers, as the row stores it. Loose strings, never the taxonomy's enums: a
+* verifier reads an export somebody may have altered, and an altered value must reach the hash check and be
+* named as a break rather than fail to parse.
+*/
+const ChainedEventFields = z.object({
+	eventId: z.string().describe("The event's stable public id."),
+	occurredAt: z.number().int().describe("When it happened, ms since the epoch, exactly as stored."),
+	action: z.string().describe("The `domain/reason` action code."),
+	outcome: z.string().describe("Whether it succeeded, failed, or was denied."),
+	severity: z.string().describe("How serious it is."),
+	actorType: z.string().describe("The kind of principal that acted."),
+	actorId: z.string().nullable().describe("The acting principal's id, or null."),
+	actorKind: z.string().nullable().describe("For a control-plane actor, the kind of client, or null."),
+	sessionId: z.string().nullable().describe("The session the action belongs to, or null."),
+	resourceType: z.string().nullable().describe("The kind of thing acted on, or null."),
+	resourceId: z.string().nullable().describe("The thing acted on, or null."),
+	requestId: z.string().nullable().describe("The request correlation id, or null."),
+	tenant: z.string().nullable().describe("The tenant whose chain this event is in, or null for the untenanted chain."),
+	project: z.string().nullable().describe("The project the recorder stamped, or null."),
+	environment: z.string().nullable().describe("The environment the recorder stamped, or null."),
+	worker: z.string().nullable().describe("The Worker that recorded it, or null."),
+	version: z.string().nullable().describe("The Cloudflare build id that recorded it, or null."),
+	ipCommitment: Sha256Hex.nullable().describe("The salted hash of the client IP, or null when there was none."),
+	userAgentCommitment: Sha256Hex.nullable().describe("The salted hash of the user-agent, or null when there was none."),
+	metadataCommitment: Sha256Hex.nullable().describe("The salted hash of the metadata's stored JSON text, or null when there was none.")
+}).describe("Every field of an audit event its chain hash covers, personal values committed by hash.");
+/** A link a range starts from or ends at: a position and the hash of the event there. */
+const ChainLink = z.object({
+	seq: z.number().int().min(1).describe("The 1-based position in the tenant's chain."),
+	hash: Sha256Hex.describe("The hash of the event at that position.")
+}).describe("One position in a tenant's chain and the hash of the event there.");
+/**
+* One chained event as an export carries it: the hashed fields, its link, and — only with the detail scope — the
+* personal values and the salt their commitments were made under.
+*/
+const ChainedEvent = ChainedEventFields.extend({
+	seq: z.number().int().min(1).describe("The 1-based position in the tenant's chain."),
+	prev: Sha256Hex.nullable().describe("The hash of the event before it, or null for the first event."),
+	hash: Sha256Hex.describe("This event's hash, over its canonical serialization."),
+	salt: z.string().optional().describe("The per-event salt the commitments were made under. Present only with the personal values."),
+	ip: z.string().nullable().optional().describe("The client IP. Present only with the detail scope."),
+	userAgent: z.string().nullable().optional().describe("The user-agent. Present only with the detail scope."),
+	metadata: z.string().nullable().optional().describe("The metadata's stored JSON text, byte for byte. Present only with the detail scope.")
+}).describe("One chained audit event as an export carries it.");
+/** The format string of a checkpoint object. */
+const AUDIT_CHECKPOINT_FORMAT = "pithy-audit-checkpoint/1";
+/** One checkpoint: a tenant chain's length and head, written outside the database on a schedule. */
+const AuditCheckpoint = z.object({
+	format: z.literal(AUDIT_CHECKPOINT_FORMAT).describe("The checkpoint format."),
+	tenant: z.string().nullable().describe("The tenant whose chain this is, or null for the untenanted chain."),
+	count: z.number().int().min(1).describe("How many events the chain held: the head's position."),
+	head: Sha256Hex.describe("The hash of the event at that position."),
+	takenAt: z.iso.datetime().describe("When the checkpoint was written, ISO-8601.")
+}).describe("A tenant chain's length and head, written to append-only object storage on a schedule.");
+/** The format string of a tombstone object. */
+const AUDIT_TOMBSTONE_FORMAT = "pithy-audit-tombstone/1";
+/**
+* A pruned run of one chain: which positions the retention prune removed, the link before them, and the hashes at
+* either end. Written to the checkpoint bucket before the rows are deleted, never overwritten, so a verify bridges
+* the gap from the event before it to the event after it and reads the chain as whole across it.
+*/
+const AuditTombstone = z.object({
+	format: z.literal(AUDIT_TOMBSTONE_FORMAT).describe("The tombstone format."),
+	tenant: z.string().nullable().describe("The tenant whose chain was pruned, or null for the untenanted chain."),
+	fromSeq: z.number().int().min(1).describe("The first position the prune removed."),
+	throughSeq: z.number().int().min(1).describe("The last position the prune removed."),
+	count: z.number().int().min(1).describe("How many events the prune removed: every position from first to last."),
+	prior: Sha256Hex.nullable().describe("The hash of the event before the first one removed, or null when the run began the chain."),
+	first: Sha256Hex.describe("The hash of the first event removed."),
+	last: Sha256Hex.describe("The hash of the last event removed, which the event after the gap names as its link."),
+	prunedAt: z.iso.datetime().describe("When the run was pruned, ISO-8601.")
+}).describe("A run of a tenant chain the retention prune removed, written to append-only object storage.");
+/** The format string of an export document. */
+const AUDIT_EXPORT_FORMAT = "pithy-audit-export/1";
+/** An export: one tenant's events in a range, the link before it, and the checkpoints covering it. */
+const AuditChainExport = z.object({
+	format: z.literal(AUDIT_EXPORT_FORMAT).describe("The export format."),
+	chain: z.literal(AUDIT_CHAIN_FORMAT).describe("The canonical form every hash in it was computed over."),
+	tenant: z.string().nullable().describe("The tenant whose chain this is, or null for the untenanted chain."),
+	since: z.iso.datetime().nullable().describe("The range's inclusive start as asked, or null for the chain's start."),
+	until: z.iso.datetime().nullable().describe("The range's inclusive end as asked, or null for the chain's head."),
+	exportedAt: z.iso.datetime().describe("When the export was taken."),
+	detail: z.boolean().describe("Whether the personal values travel with their commitments. Only with `audit:events:read_detail`."),
+	prior: ChainLink.nullable().describe("The link before the first event, or null when the range starts the chain."),
+	events: z.array(ChainedEvent).describe("The range's chained events, in chain order."),
+	checkpoints: z.array(AuditCheckpoint).describe("Every checkpoint covering the range, and the latest one after it."),
+	tombstones: z.array(AuditTombstone).optional().describe("Every pruned run of the chain, so a verify bridges each gap the retention prune left. Absent from a Worker that has never pruned one."),
+	complete: z.boolean().describe("Whether the events run to the chain's head, so a checkpoint past the last event is a truncation."),
+	beforeChain: z.number().int().nonnegative().describe("How many of the tenant's events in the range were written before the chain, and are not in it."),
+	outsideChain: z.number().int().nonnegative().describe("How many rows in the range carry no chain though written after it began — an older recorder's during an upgrade or a rollback. Not in the chain, and not a break."),
+	nextCursor: z.string().nullable().describe("Where the next page resumes, or null at the end of the range.")
+}).describe("One tenant's chained audit events over a range, verifiable offline against its checkpoints.");
+/** Why a chain is not whole. */
+const ChainBreakReason = z.enum([
+	"edited",
+	"commitment",
+	"missing",
+	"inserted",
+	"unlinked",
+	"checkpoint",
+	"truncated"
+]).describe("`edited` — the event's hash does not match its fields. `commitment` — a personal value does not match its commitment. `missing` — events before it are gone. `inserted` — it is not where the chain says it should be. `unlinked` — it does not name the event before it. `checkpoint` — its hash differs from the checkpoint at its position. `truncated` — the chain ends before a checkpoint says it reached.");
+/** The first place a chain is not whole. */
+const ChainBreak = z.object({
+	eventId: z.string().nullable().describe("The event at the break, or null where the break is an absence the trail no longer holds."),
+	position: z.number().int().min(1).describe("The position in the tenant's chain where the break is."),
+	reason: ChainBreakReason,
+	detail: z.string().describe("The break in one sentence.")
+}).describe("The first break in a chain: which event, at which position, and why.");
+/** The canonical serialization: a JSON array in one fixed order, so no key order or whitespace can vary it. */
+function canonicalEvent(position, fields) {
+	return JSON.stringify([
+		AUDIT_CHAIN_FORMAT,
+		position.seq,
+		position.prev,
+		fields.eventId,
+		fields.occurredAt,
+		fields.action,
+		fields.outcome,
+		fields.severity,
+		fields.actorType,
+		fields.actorId,
+		fields.actorKind,
+		fields.sessionId,
+		fields.resourceType,
+		fields.resourceId,
+		fields.requestId,
+		fields.tenant,
+		fields.project,
+		fields.environment,
+		fields.worker,
+		fields.version,
+		fields.ipCommitment,
+		fields.userAgentCommitment,
+		fields.metadataCommitment
+	]);
+}
+/** Lowercase hex SHA-256 of a UTF-8 string. */
+async function sha256Hex(text) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** A fresh per-event salt: 16 random bytes, hex. */
+function newChainSalt() {
+	return [...crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(16))].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** The salted commitment to one personal value, or null when there is no value. */
+async function commitment(salt, value) {
+	return value === null ? null : sha256Hex(JSON.stringify([salt, value]));
+}
+/** An event's chain hash: SHA-256 over its canonical serialization. */
+async function chainHash(position, fields) {
+	return sha256Hex(canonicalEvent(position, fields));
+}
+/** The hashed fields of an exported event, without its link or its personal values. */
+function hashedFields(event) {
+	return {
+		eventId: event.eventId,
+		occurredAt: event.occurredAt,
+		action: event.action,
+		outcome: event.outcome,
+		severity: event.severity,
+		actorType: event.actorType,
+		actorId: event.actorId,
+		actorKind: event.actorKind,
+		sessionId: event.sessionId,
+		resourceType: event.resourceType,
+		resourceId: event.resourceId,
+		requestId: event.requestId,
+		tenant: event.tenant,
+		project: event.project,
+		environment: event.environment,
+		worker: event.worker,
+		version: event.version,
+		ipCommitment: event.ipCommitment,
+		userAgentCommitment: event.userAgentCommitment,
+		metadataCommitment: event.metadataCommitment
+	};
+}
+/** The personal value an event carries for one commitment, when it carries the values at all. */
+const COMMITTED = [
+	[
+		"ip",
+		"ipCommitment",
+		"IP"
+	],
+	[
+		"userAgent",
+		"userAgentCommitment",
+		"user-agent"
+	],
+	[
+		"metadata",
+		"metadataCommitment",
+		"metadata"
+	]
+];
+/**
+* Walk one tenant's chain in order. Each event is checked for its tenant, its position, its link, its commitments
+* (when it carries its values), its hash, and the checkpoint at its position — in that order, so the reason names
+* the first thing wrong.
+*/
+function chainVerifier(options) {
+	const own = options.checkpoints.filter((checkpoint) => checkpoint.tenant === options.tenant);
+	const byCount = /* @__PURE__ */ new Map();
+	for (const checkpoint of own) byCount.set(checkpoint.count, checkpoint);
+	const tombstones = (options.tombstones ?? []).filter((tombstone) => tombstone.tenant === options.tenant);
+	let head = options.prior;
+	let checked = 0;
+	let pruned = 0;
+	/**
+	* Cross every pruned run that starts where the walk stands and links to its head, before the event at `seq`. A
+	* tombstone that does not link, or that a checkpoint at either end disagrees with, bridges nothing.
+	*/
+	const bridge = (seq) => {
+		for (;;) {
+			const expected = (head?.seq ?? 0) + 1;
+			if (seq <= expected) return null;
+			const run = tombstones.find((tombstone) => tombstone.fromSeq === expected && tombstone.throughSeq < seq && tombstone.count === tombstone.throughSeq - tombstone.fromSeq + 1 && tombstone.prior === (head?.hash ?? null));
+			if (!run) return null;
+			for (const [position, hash] of [[run.fromSeq, run.first], [run.throughSeq, run.last]]) {
+				const checkpoint = byCount.get(position);
+				if (checkpoint && checkpoint.head !== hash) return {
+					eventId: null,
+					position,
+					reason: "checkpoint",
+					detail: `The pruned run ${run.fromSeq} to ${run.throughSeq} differs from the checkpoint taken at ${checkpoint.takenAt}.`
+				};
+			}
+			head = {
+				seq: run.throughSeq,
+				hash: run.last
+			};
+			pruned += run.count;
+		}
+	};
+	return {
+		get head() {
+			return head;
+		},
+		get checked() {
+			return checked;
+		},
+		get checkpoints() {
+			return own.length;
+		},
+		get pruned() {
+			return pruned;
+		},
+		async push(event) {
+			if (event.tenant === options.tenant) {
+				const bridged = bridge(event.seq);
+				if (bridged) return bridged;
+			}
+			const expected = (head?.seq ?? 0) + 1;
+			if (event.tenant !== options.tenant) return {
+				eventId: event.eventId,
+				position: expected,
+				reason: "inserted",
+				detail: `Event ${event.eventId} belongs to another tenant's chain.`
+			};
+			if (event.seq > expected) return {
+				eventId: event.eventId,
+				position: expected,
+				reason: "missing",
+				detail: event.seq - expected === 1 ? `The event at position ${expected} is missing.` : `The events at positions ${expected} to ${event.seq - 1} are missing.`
+			};
+			if (event.seq < expected) return {
+				eventId: event.eventId,
+				position: expected,
+				reason: "inserted",
+				detail: `Event ${event.eventId} claims position ${event.seq}, which the chain has already passed.`
+			};
+			if (event.prev !== (head?.hash ?? null)) return {
+				eventId: event.eventId,
+				position: event.seq,
+				reason: "unlinked",
+				detail: `Event ${event.eventId} does not name the event before it.`
+			};
+			if (event.salt === void 0) {
+				const carried = COMMITTED.find(([valueKey]) => event[valueKey] !== void 0);
+				if (carried || options.values) return {
+					eventId: event.eventId,
+					position: event.seq,
+					reason: "commitment",
+					detail: carried ? `Event ${event.eventId} carries its ${carried[2]} without the salt its commitment needs.` : `Event ${event.eventId} carries no salt, though the export says it carries the values.`
+				};
+			} else for (const [valueKey, commitmentKey, label] of COMMITTED) {
+				const value = event[valueKey];
+				if (value === void 0) {
+					if (!options.values) continue;
+					return {
+						eventId: event.eventId,
+						position: event.seq,
+						reason: "commitment",
+						detail: `Event ${event.eventId} carries no ${label}, though the export says it carries the values.`
+					};
+				}
+				if (await commitment(event.salt, value) !== event[commitmentKey]) return {
+					eventId: event.eventId,
+					position: event.seq,
+					reason: "commitment",
+					detail: `Event ${event.eventId}'s ${label} does not match its commitment.`
+				};
+			}
+			if (await chainHash({
+				seq: event.seq,
+				prev: event.prev
+			}, hashedFields(event)) !== event.hash) return {
+				eventId: event.eventId,
+				position: event.seq,
+				reason: "edited",
+				detail: `Event ${event.eventId} does not hash to the value it carries.`
+			};
+			const checkpoint = byCount.get(event.seq);
+			if (checkpoint && checkpoint.head !== event.hash) return {
+				eventId: event.eventId,
+				position: event.seq,
+				reason: "checkpoint",
+				detail: `Event ${event.eventId} differs from the checkpoint taken at ${checkpoint.takenAt}.`
+			};
+			head = {
+				seq: event.seq,
+				hash: event.hash
+			};
+			checked++;
+			return null;
+		},
+		finish(complete) {
+			if (!complete) return null;
+			const end = head?.seq ?? 0;
+			const beyond = own.filter((checkpoint) => checkpoint.count > end).sort((a, b) => b.count - a.count)[0];
+			if (!beyond) return null;
+			return {
+				eventId: null,
+				position: end + 1,
+				reason: "truncated",
+				detail: `The chain ends at position ${end}, and the checkpoint taken at ${beyond.takenAt} recorded ${beyond.count}.`
+			};
+		}
+	};
+}
+/** Verify an export offline: every link, every commitment it can check, every checkpoint it carries. */
+async function verifyChainExport(document) {
+	const verifier = chainVerifier({
+		tenant: document.tenant,
+		prior: document.prior,
+		checkpoints: document.checkpoints,
+		tombstones: document.tombstones ?? [],
+		values: document.detail
+	});
+	for (const event of document.events) {
+		const found = await verifier.push(event);
+		if (found) return {
+			intact: false,
+			checked: verifier.checked,
+			checkpoints: verifier.checkpoints,
+			pruned: verifier.pruned,
+			break: found
+		};
+	}
+	const truncated = verifier.finish(document.complete);
+	return {
+		intact: truncated === null,
+		checked: verifier.checked,
+		checkpoints: verifier.checkpoints,
+		pruned: verifier.pruned,
+		break: truncated
+	};
+}
+//#endregion
+export { AUDIT_CHAIN_FORMAT, AUDIT_CHECKPOINT_FORMAT, AUDIT_EXPORT_FORMAT, AUDIT_TOMBSTONE_FORMAT, AuditChainExport, AuditCheckpoint, AuditTombstone, ChainBreak, ChainBreakReason, ChainLink, ChainedEvent, ChainedEventFields, Sha256Hex, canonicalEvent, chainHash, chainVerifier, commitment, newChainSalt, sha256Hex, verifyChainExport };

package/dist/audit/citations.d.ts

@@ -0,0 +1,52 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Capability } from "../capability/capability";
+/**
+ * **Citing the trail (#823): which recorded events name a resource, and where each sits in its chain.**
+ *
+ * An erasure attestation proves a purge happened by pointing at the audit events the purge wrote, by event id and
+ * chain position. The chain (#822) is what makes those events tamper-evident, so the attestation adds no second
+ * integrity mechanism: it cites, and an auditor checks the citation with `pithy audit verify`.
+ *
+ * Reading the trail is `@pithy-sh/audit`'s, and nothing may import it (principle 4). So, like
+ * {@link Capability.auditRecorder}, the audit capability declares a reader built from the env, and
+ * {@link composedAuditCitations} finds it among the composed capabilities. With no audit composed there is no
+ * trail to cite, and the answer is `null` rather than an empty list: *nothing recorded* and *no recorder* are two
+ * different facts, and an attestation must say which.
+ */
+/** Which events to cite: one kind of resource, some of its ids, and the actions that matter. */
+export interface AuditCitationQuery {
+    /** The `resourceType` the events were recorded against — `user`, `organization`. */
+    readonly resourceType: string;
+    /** The resource ids. Every event for any of them, among {@link actions}. */
+    readonly resourceIds: readonly string[];
+    /** The `domain/reason` actions to cite. Every other action on the resource is left out. */
+    readonly actions: readonly string[];
+}
+/** One recorded event, as an attestation cites it: never its personal values, only where it is. */
+export interface AuditCitation {
+    /** The event's stable public id. */
+    readonly eventId: string;
+    /** The `domain/reason` action. */
+    readonly action: string;
+    /** The resource it was recorded against. */
+    readonly resourceId: string;
+    /** When it happened. */
+    readonly occurredAt: Date;
+    /** The tenant whose chain it is in, or null for the untenanted chain. */
+    readonly tenant: string | null;
+    /** Its 1-based position in that chain, or null for an event recorded before the chain began. */
+    readonly seq: number | null;
+    /** Its chain hash, or null before the chain. */
+    readonly hash: string | null;
+    /** The `step` its metadata names, when it names one as a string — which purge step the event records. */
+    readonly step: string | null;
+}
+/** Read the citations for one query, oldest first. */
+export type AuditCitationReader = (query: AuditCitationQuery) => Promise<AuditCitation[]>;
+/**
+ * The composed audit capability's citation reader over this env, or `null` when no capability provides one — no
+ * audit is composed, so there is no trail to cite.
+ */
+export declare function composedAuditCitations(capabilities: readonly Capability[], env: Record<string, unknown>): AuditCitationReader | null;
+//# sourceMappingURL=citations.d.ts.map

package/dist/audit/citations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citations.d.ts","sourceRoot":"","sources":["../../src/audit/citations.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D;;;;;;;;;;;;GAYG;AAEH,gGAAgG;AAChG,MAAM,WAAW,kBAAkB;IACjC,oFAAoF;IACpF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,mGAAmG;AACnG,MAAM,WAAW,aAAa;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wBAAwB;IACxB,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,gGAAgG;IAChG,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,yGAAyG;IACzG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,sDAAsD;AACtD,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;AAE1F;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,SAAS,UAAU,EAAE,EACnC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,mBAAmB,GAAG,IAAI,CAG5B"}

package/dist/audit/citations.js

@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/audit/citations.ts
+/**
+* The composed audit capability's citation reader over this env, or `null` when no capability provides one — no
+* audit is composed, so there is no trail to cite.
+*/
+function composedAuditCitations(capabilities, env) {
+	const provider = capabilities.find((capability) => capability.auditCitations !== void 0);
+	return provider?.auditCitations ? provider.auditCitations(env) : null;
+}
+//#endregion
+export { composedAuditCitations };

package/dist/capability/bindings.d.ts

@@ -88,6 +88,23 @@ export declare const TARGET_KINDS: Readonly<Partial<Record<BindingType, {
     field: string;
     required: boolean;
 }>>>;
+/**
+ * **How a Worker consumes a queue it also produces to (#824).**
+ *
+ * A consumer is half of the queue's own configuration — Cloudflare reads it off the `queues.consumers` entry, not
+ * off the code — so it is declared beside the producer binding and written with it, by the same writer. The
+ * dead-letter queue is named by **binding**, never by queue name: the name is `<project>-<env>-<thing>`, composed
+ * per environment by the same namer that names the producer's, so a spec that stated it would be one environment's.
+ *
+ * `maxRetries` is bounded by what Cloudflare Queues accepts (0 to 100), and the capability's handler reads the same
+ * number to know a message's last attempt, which is the moment it can count one as dead-lettered.
+ */
+export declare const QueueConsumerSpec: z.ZodObject<{
+    deadLetter: z.ZodString;
+    maxRetries: z.ZodNumber;
+    maxBatchSize: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type QueueConsumerSpec = z.infer<typeof QueueConsumerSpec>;
 /**
  * Declares a Cloudflare binding a capability requires in the Worker env. The authoring
  * shape lets `optional` be omitted (defaults false); `createBackend` normalizes via parse.
@@ -107,6 +124,11 @@ export declare const BindingSpec: z.ZodObject<{
         global: "global";
     }>>;
     resource: z.ZodOptional<z.ZodString>;
+    consumer: z.ZodOptional<z.ZodObject<{
+        deadLetter: z.ZodString;
+        maxRetries: z.ZodNumber;
+        maxBatchSize: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type BindingSpec = z.infer<typeof BindingSpec>;
 /** Authoring shape for a capability's `requiredBindings`: `optional` may be omitted. */

package/dist/capability/bindings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../../src/capability/bindings.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,WAAW,4iBAuCuC,CAAC;AAChE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,WAAW,GAAG,QAAQ,CAAC;AA8B1D,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,CAExD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAE/D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAE3D;AAsBD;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC,CAMrG,CAAC;AAqCF;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;iBAuJpB,CAAC;AACL,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,wFAAwF;AACxF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC"}
+{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../../src/capability/bindings.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,WAAW,4iBAuCuC,CAAC;AAChE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,WAAW,GAAG,QAAQ,CAAC;AA8B1D,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,CAExD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAE/D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAE3D;AAsBD;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC,CAMrG,CAAC;AAqCF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB;;;;iBAyByF,CAAC;AACxH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;iBA6KpB,CAAC;AACL,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,wFAAwF;AACxF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC"}

package/dist/capability/bindings.js

@@ -189,6 +189,22 @@ const TARGET = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 */
 const NAMED_RESOURCE_KINDS = new Set(FEATURE_RESOURCE_KINDS);
 /**
+* **How a Worker consumes a queue it also produces to (#824).**
+*
+* A consumer is half of the queue's own configuration — Cloudflare reads it off the `queues.consumers` entry, not
+* off the code — so it is declared beside the producer binding and written with it, by the same writer. The
+* dead-letter queue is named by **binding**, never by queue name: the name is `<project>-<env>-<thing>`, composed
+* per environment by the same namer that names the producer's, so a spec that stated it would be one environment's.
+*
+* `maxRetries` is bounded by what Cloudflare Queues accepts (0 to 100), and the capability's handler reads the same
+* number to know a message's last attempt, which is the moment it can count one as dead-lettered.
+*/
+const QueueConsumerSpec = z.object({
+	deadLetter: z.string().min(1).regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "A dead-letter queue is named by its binding: letters, digits and `_`.").describe("The binding of the queue a message goes to once its retries are spent. Declared as a `queue` binding of its own, so `pithy provision` creates it; its queue name is composed the same way as this one's."),
+	maxRetries: z.number().int().min(0).max(100).describe("How many times a failed message is retried before it is dead-lettered. Cloudflare allows 0 to 100."),
+	maxBatchSize: z.number().int().min(1).max(100).optional().describe("The most messages one invocation of the handler receives. Absent leaves Cloudflare's default.")
+}).describe("How a Worker consumes a queue it produces to: where exhausted messages go, and how often one is retried.");
+/**
 * Declares a Cloudflare binding a capability requires in the Worker env. The authoring
 * shape lets `optional` be omitted (defaults false); `createBackend` normalizes via parse.
 */
@@ -203,7 +219,8 @@ const BindingSpec = z.object({
 	target: z.string().min(1).regex(TARGET, "A target is a resource id or name: letters, digits, `.`, `_` and `-`.").optional().describe("The account-level resource this binding addresses, which the adopter creates themselves: a Hyperdrive config id, an mTLS certificate id, a Pipelines stream, a dispatch namespace, or an Analytics Engine dataset. Written into the field wrangler names for it (`id`, `certificate_id`, `stream`, `namespace`, `dataset`), and carried whole into every environment, because the resource is the account's. Required for `hyperdrive`, `mtls_certificates`, `pipelines` and `dispatch_namespaces`; optional for `analytics_engine_datasets`. Refused on every other kind."),
 	remote: z.boolean().optional().describe("Reach the real Cloudflare resource during local development instead of a local emulation. Set it for a binding that has none — Vectorize and Workers AI both lack local simulation — so `wrangler dev` and any Workflow host, which always runs locally, still work. Left unset rather than defaulting to false, so a spec that does not care emits no flag at all. Ignored in a deployed Worker."),
 	scope: z.enum(["environment", "global"]).optional().describe("Whether the resource behind this binding is one per environment (absent, the default) or one for the whole project. A `global` resource takes the literal `global` where the environment segment goes — `<project>-global-<thing>` — so every environment's stanza names the identical resource and provisioning creates it once. Declare it where the data is not an environment-local fact: `@pithy-sh/email`'s suppression list is one per project, because an unsubscribe recorded through a staging Worker has to be honored by a production one, and three per-environment databases meant it was not (#513). Say nothing where it is: a session store, a cache, and `@pithy-sh/secrets`' own database are per environment, and one line apart in the same env there is no convention to tell them apart by — which is why this is declared rather than inferred. Meaningful only for a `d1`, `kv`, `r2` or `queue` binding."),
-	resource: z.string().min(1).regex(NAME_SEGMENT, "A resource is one name segment: lowercase letters, digits, and single hyphens.").optional().describe("The `<thing>` segment of this resource's name, when it is not the kebabbed binding name. Absent is the ordinary case and means the binding name is the segment (`EMAIL_SUPPRESSIONS` → `email-suppressions`). Declare it where the two must differ: `SUPPORT_BUCKET` backs `<project>-global-support`, because the binding keeps `_BUCKET` for whoever reads `env.SUPPORT_BUCKET` in a Worker while the resource drops it — `r2` is already the composed name's kind, so the suffix repeats it. Meaningful only for a `d1`, `kv`, `r2` or `queue` binding.")
+	resource: z.string().min(1).regex(NAME_SEGMENT, "A resource is one name segment: lowercase letters, digits, and single hyphens.").optional().describe("The `<thing>` segment of this resource's name, when it is not the kebabbed binding name. Absent is the ordinary case and means the binding name is the segment (`EMAIL_SUPPRESSIONS` → `email-suppressions`). Declare it where the two must differ: `SUPPORT_BUCKET` backs `<project>-global-support`, because the binding keeps `_BUCKET` for whoever reads `env.SUPPORT_BUCKET` in a Worker while the resource drops it — `r2` is already the composed name's kind, so the suffix repeats it. Meaningful only for a `d1`, `kv`, `r2` or `queue` binding."),
+	consumer: QueueConsumerSpec.optional().describe("That this Worker also **consumes** the queue it produces to, and how: the queue its exhausted messages go to and how many times one is retried first. Written as the `queues.consumers` entry beside the producer, so the queue's handler is the Worker's own `queue` export (`Capability.queue`). Absent, the Worker only sends. Meaningful only for a `queue` binding.")
 }).describe("Declares a Cloudflare binding a capability requires in the Worker env.").check((ctx) => {
 	if (ctx.value.type === "durable_object" && ctx.value.className === void 0) ctx.issues.push({
 		code: "custom",
@@ -239,6 +256,19 @@ const BindingSpec = z.object({
 		path: ["target"],
 		message: `Binding "${ctx.value.name}" needs a target — the ${ctx.value.type} resource it addresses, written as \`${target.field}\`.`
 	});
+	const consumer = ctx.value.consumer;
+	if (consumer !== void 0 && ctx.value.type !== "queue") ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		path: ["consumer"],
+		message: `Binding "${ctx.value.name}" declares a consumer, which only a queue binding has — this one is a ${ctx.value.type}.`
+	});
+	if (consumer !== void 0 && consumer.deadLetter === ctx.value.name) ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		path: ["consumer", "deadLetter"],
+		message: `Queue "${ctx.value.name}" names itself as its dead-letter queue. Declare a second queue binding for it.`
+	});
 	if (target === void 0 && ctx.value.target !== void 0) ctx.issues.push({
 		code: "custom",
 		input: ctx.value,
@@ -247,4 +277,4 @@ const BindingSpec = z.object({
 	});
 });
 //#endregion
-export { BindingSpec, BindingType, TARGET_KINDS, isProvisionedBinding, isWrittenBinding, seedPolicy };
+export { BindingSpec, BindingType, QueueConsumerSpec, TARGET_KINDS, isProvisionedBinding, isWrittenBinding, seedPolicy };