@happyvertical/secrets 0.87.0 → 0.88.0

package/dist/index.js

@@ -1,6 +1,9 @@
 import { syncSchema } from "@happyvertical/sql";
 import { createId } from "@happyvertical/utils";
 import * as crypto from "node:crypto";
+import { createHash, randomUUID, sign, verify } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { spawn } from "node:child_process";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
@@ -341,7 +344,7 @@ var DEFAULT_ROTATION_PERIOD_MS = 2160 * 60 * 60 * 1e3;
 * await store.initialize();
 *
 * // Encrypt a secret for a tenant
-* const envelope = await store.encrypt('tenant-123', 'api-key', 'sk_live_xxx');
+* const envelope = await store.encrypt('tenant-123', 'api-key', 'synthetic-secret');
 *
 * // Decrypt
 * const { value } = await store.decrypt('tenant-123', envelope);
@@ -644,6 +647,1069 @@ var DatabaseSecretStore = class {
 	}
 };
 //#endregion
+//#region src/shared/custody.ts
+var REDACTED = "[REDACTED]";
+var MAX_TIMER_DELAY_MS = 2147483647;
+var SAFE_IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/;
+var ENVIRONMENT_VARIABLE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var CREDENTIAL_PATTERNS = [
+	{
+		pattern: /\b(?:gh[pousr]|github_pat|hvwk|sk|xox[baprs])_[A-Za-z0-9_-]{16,}\b/gi,
+		replacement: REDACTED
+	},
+	{
+		pattern: /\b[A-Za-z0-9_-]{12,}\.[A-Za-z0-9_-]{12,}\.[A-Za-z0-9_-]{12,}\b/g,
+		replacement: REDACTED
+	},
+	{
+		pattern: /((?:authorization|credential|password|secret|token)\s*[:=]\s*(?:bearer\s+)?)[^\s,;]+/gi,
+		replacement: `$1${REDACTED}`
+	}
+];
+var environmentLock = Promise.resolve();
+var environmentLockContext = new AsyncLocalStorage();
+async function withEnvironmentLock(operation) {
+	if (environmentLockContext.getStore()) throw new CustodyError("REENTRANT_ENVIRONMENT_INJECTION", "inject", "Nested environment credential injection is not allowed");
+	const previous = environmentLock;
+	let release = () => void 0;
+	const current = new Promise((resolve) => {
+		release = resolve;
+	});
+	const queued = previous.then(() => current);
+	environmentLock = queued;
+	await previous;
+	try {
+		return await environmentLockContext.run(true, operation);
+	} finally {
+		release();
+		if (environmentLock === queued) environmentLock = Promise.resolve();
+	}
+}
+var CustodyError = class extends Error {
+	code;
+	stage;
+	details;
+	constructor(code, stage, message, options) {
+		super(redactCredentialText(message));
+		this.name = "CustodyError";
+		this.code = SAFE_IDENTIFIER.test(code) && redactCredentialText(code) === code ? code : "INVALID_CUSTODY_ERROR_CODE";
+		this.stage = stage;
+		this.details = options?.details ? redactCredentialValues(options.details) : void 0;
+	}
+	toJSON() {
+		return {
+			name: this.name,
+			code: this.code,
+			stage: this.stage,
+			message: this.message,
+			...this.details ? { details: this.details } : {}
+		};
+	}
+};
+var SecretMaterial = class SecretMaterial {
+	#bytes;
+	#destroyed = false;
+	constructor(value) {
+		this.#bytes = Buffer.from(value, "utf8");
+	}
+	static fromString(value) {
+		if (!value) throw new CustodyError("EMPTY_SECRET_MATERIAL", "issue", "Secret material must not be empty");
+		return new SecretMaterial(value);
+	}
+	get destroyed() {
+		return this.#destroyed;
+	}
+	async use(operation) {
+		if (this.#destroyed) throw new CustodyError("SECRET_MATERIAL_DESTROYED", "inject", "Secret material is no longer available");
+		const plaintext = this.#bytes.toString("utf8");
+		try {
+			await operation(plaintext);
+		} catch (cause) {
+			if (cause instanceof CustodyError) throw new CustodyError(redactCredentialText(cause.code, [plaintext]) === cause.code ? cause.code : "INVALID_CUSTODY_ERROR_CODE", cause.stage, redactCredentialText(cause.message, [plaintext]), { details: redactCredentialValues(cause.details, [plaintext]) });
+			throw new CustodyError("SECRET_MATERIAL_OPERATION_FAILED", "inject", "Secret material operation failed", { cause });
+		}
+	}
+	destroy() {
+		this.#bytes.fill(0);
+		this.#destroyed = true;
+	}
+	toJSON() {
+		return REDACTED;
+	}
+	toString() {
+		return REDACTED;
+	}
+	[Symbol.for("nodejs.util.inspect.custom")]() {
+		return REDACTED;
+	}
+};
+var Ed25519CustodyReceiptAttestor = class {
+	name;
+	keyId;
+	#privateKey;
+	constructor(options) {
+		if (options.privateKey.type !== "private" || options.privateKey.asymmetricKeyType !== "ed25519") throw new CustodyError("INVALID_ATTESTATION_KEY", "record", "Custody attestation requires a private signing key");
+		this.#privateKey = options.privateKey;
+		this.name = options.name ?? "ed25519";
+		this.keyId = options.keyId;
+		assertSafeIdentifier(this.name, "attestor.name", "record");
+		assertSafeIdentifier(this.keyId, "attestor.keyId", "record");
+	}
+	async attest(payload) {
+		return sign(null, Buffer.from(payload), this.#privateKey).toString("base64url");
+	}
+};
+var InMemoryCustodyLedger = class {
+	#receipts = [];
+	#events = [];
+	async recordIssuance(receipt, event) {
+		if (event.type !== "finalization-pending") throw new CustodyError("INVALID_CUSTODY_EVENT", "record", "Prepared receipt requires a finalization-pending event");
+		if (this.#receipts.some((item) => item.receiptId === receipt.receiptId)) throw new CustodyError("DUPLICATE_CUSTODY_RECEIPT", "record", "Custody receipt already exists");
+		if (receipt.replacesReceiptId) {
+			const predecessor = this.#receipts.find((item) => item.receiptId === receipt.replacesReceiptId);
+			const predecessorTerminal = this.#events.some((item) => item.receiptId === receipt.replacesReceiptId && [
+				"revoked",
+				"expired",
+				"replaced"
+			].includes(item.type));
+			const predecessorIssued = this.#events.some((item) => item.receiptId === receipt.replacesReceiptId && item.type === "issued");
+			const existingChild = this.#receipts.some((item) => item.replacesReceiptId === receipt.replacesReceiptId && !this.#events.some((event) => event.receiptId === item.receiptId && [
+				"revoked",
+				"expired",
+				"replaced"
+			].includes(event.type)));
+			if (!predecessor || !predecessorIssued || predecessorTerminal || existingChild) throw new CustodyError("CUSTODY_ROTATION_CONFLICT", "record", "Custody predecessor is not active and replaceable");
+		}
+		this.#receipts.push(structuredClone(receipt));
+		this.#events.push(structuredClone(event));
+	}
+	async appendEvent(event) {
+		const existing = this.#events.find((item) => item.eventId === event.eventId);
+		if (existing) {
+			if (sameCustodyEvent(existing, event)) return;
+			throw new CustodyError("CUSTODY_EVENT_ID_CONFLICT", "record", "Custody event ID is already bound to different content");
+		}
+		this.#events.push(structuredClone(event));
+	}
+	async commitIssuance(receiptId, event, followup) {
+		if (event.type !== "issued" || followup !== void 0 && followup.type !== "retirement-pending") throw new CustodyError("INVALID_CUSTODY_EVENT", "record", "Issuance commit requires issued and optional retirement-pending events");
+		if (!this.#receipts.some((receipt) => receipt.receiptId === receiptId)) throw new CustodyError("CUSTODY_RECEIPT_NOT_FOUND", "record", "Prepared custody receipt was not found");
+		if (!this.#events.some((item) => item.receiptId === receiptId && item.type === "issued")) {
+			this.#events.push(structuredClone(event));
+			if (followup) this.#events.push(structuredClone(followup));
+		}
+	}
+	async listReceipts() {
+		return structuredClone(this.#receipts);
+	}
+	async listEvents() {
+		return structuredClone(this.#events);
+	}
+};
+var CredentialCustody = class {
+	#issuer;
+	#verifier;
+	#ledger;
+	#attestor;
+	#finalizer;
+	#sink;
+	#ephemeralTtlMs;
+	#ephemeralRevokeRetryMs;
+	#orphanGraceMs;
+	#finalizationTakeoverMs;
+	#now;
+	#onBackgroundError;
+	#leaseInvalidators = /* @__PURE__ */ new Map();
+	#pendingTimers = /* @__PURE__ */ new Map();
+	constructor(options) {
+		assertSafeIdentifier(options.issuer.name, "issuer.name", "issue");
+		assertSafeIdentifier(options.verifier.name, "verifier.name", "verify");
+		assertSafeIdentifier(options.attestor.name, "attestor.name", "record");
+		assertSafeIdentifier(options.attestor.keyId, "attestor.keyId", "record");
+		assertSafeIdentifier(options.finalizer.name, "finalizer.name", "activate");
+		if (options.sink) assertSafeIdentifier(options.sink.name, "sink.name", "store");
+		this.#issuer = options.issuer;
+		this.#verifier = options.verifier;
+		this.#ledger = options.ledger;
+		this.#attestor = options.attestor;
+		this.#finalizer = options.finalizer;
+		this.#sink = options.sink;
+		this.#ephemeralTtlMs = options.ephemeralTtlMs ?? 5 * 6e4;
+		this.#ephemeralRevokeRetryMs = options.ephemeralRevokeRetryMs ?? 1e3;
+		this.#orphanGraceMs = options.orphanGraceMs ?? 5 * 6e4;
+		this.#finalizationTakeoverMs = options.finalizationTakeoverMs ?? 3e4;
+		if (!Number.isFinite(this.#ephemeralTtlMs) || !Number.isFinite(this.#ephemeralRevokeRetryMs) || !Number.isFinite(this.#orphanGraceMs) || !Number.isFinite(this.#finalizationTakeoverMs) || this.#ephemeralTtlMs <= 0 || this.#ephemeralRevokeRetryMs <= 0 || this.#orphanGraceMs < 0 || this.#finalizationTakeoverMs < 0) throw new CustodyError("INVALID_CUSTODY_DURATION", "issue", "Custody durations must be positive");
+		this.#now = options.now ?? (() => /* @__PURE__ */ new Date());
+		this.#onBackgroundError = options.onBackgroundError;
+	}
+	async issue(request) {
+		if (request.mode === "durable" && !this.#sink) throw new CustodyError("DURABLE_SINK_REQUIRED", "store", "Durable credential issuance requires a secret sink");
+		if (request.replacesReceiptId && request.mode !== "durable") throw new CustodyError("DURABLE_ROTATION_REQUIRED", "issue", "Credential replacement requires durable mode");
+		assertSafeIdentifier(request.subject, "subject", "issue");
+		assertAttribution(request.attribution);
+		const replacedReceipt = request.replacesReceiptId ? await this.#findReceipt(request.replacesReceiptId) : void 0;
+		if (replacedReceipt?.mode !== void 0 && replacedReceipt.mode !== "durable") throw new CustodyError("DURABLE_ROTATION_REQUIRED", "issue", "Only durable credentials can be replaced");
+		const now = this.#now();
+		const expiresAt = request.expiresAt ?? (request.mode === "ephemeral" ? new Date(now.getTime() + this.#ephemeralTtlMs).toISOString() : void 0);
+		const requestedExpiryMs = expiresAt ? parseTimestamp(expiresAt, "expiresAt", "issue") : void 0;
+		if (requestedExpiryMs !== void 0 && requestedExpiryMs <= now.getTime()) throw new CustodyError("INVALID_EXPIRY", "issue", "Credential expiry must be in the future");
+		const metadata = sanitizeMetadata(request.metadata);
+		let issued;
+		let sinkRecord;
+		let retrieved;
+		let preparedReceipt;
+		let receiptRecorded = false;
+		let stage = "issue";
+		try {
+			issued = await this.#issuer.issue({
+				mode: request.mode,
+				subject: request.subject,
+				expiresAt,
+				metadata
+			});
+			assertSafeIdentifier(issued.credentialId, "credentialId", "issue");
+			if (issued.issuedAt) parseTimestamp(issued.issuedAt, "issuedAt", "issue");
+			if (issued.expiresAt) {
+				const providerExpiryMs = parseTimestamp(issued.expiresAt, "provider expiresAt", "issue");
+				if (providerExpiryMs <= now.getTime()) throw new CustodyError("INVALID_EXPIRY", "issue", "Credential provider returned an expired credential");
+				if (requestedExpiryMs !== void 0 && providerExpiryMs > requestedExpiryMs) throw new CustodyError("EXPIRY_BOUND_EXCEEDED", "issue", "Credential provider exceeded the requested expiry bound");
+			}
+			let material = issued.secret;
+			if (request.mode === "durable") {
+				const sink = this.#sink;
+				if (!sink) throw new CustodyError("DURABLE_SINK_REQUIRED", "store", "Durable credential issuance requires a secret sink");
+				stage = "store";
+				sinkRecord = await sink.store({
+					credentialId: issued.credentialId,
+					secret: issued.secret,
+					metadata
+				});
+				assertSinkRecord(sinkRecord, sink.name);
+				stage = "retrieve";
+				retrieved = await sink.retrieve(sinkRecord);
+				material = retrieved;
+			}
+			stage = "verify";
+			const verification = await this.#verifier.verify({
+				credentialId: issued.credentialId,
+				secret: material
+			});
+			if (!verification.verified) throw new CustodyError("CREDENTIAL_VERIFICATION_FAILED", "verify", "Credential verification failed");
+			if (verification.verificationId) assertSafeIdentifier(verification.verificationId, "verificationId", "verify");
+			const receiptId = randomUUID();
+			const finalizationId = randomUUID();
+			const unsignedReceipt = {
+				receiptId,
+				mode: request.mode,
+				credentialId: issued.credentialId,
+				subject: request.subject,
+				issuer: this.#issuer.name,
+				verifier: this.#verifier.name,
+				...verification.verificationId ? { verificationId: verification.verificationId } : {},
+				verificationState: "verified",
+				issuedAt: issued.issuedAt ?? now.toISOString(),
+				verifiedAt: this.#now().toISOString(),
+				...issued.expiresAt ?? expiresAt ? { expiresAt: issued.expiresAt ?? expiresAt } : {},
+				...sinkRecord ? { sink: sinkRecord } : {},
+				...request.replacesReceiptId ? { replacesReceiptId: request.replacesReceiptId } : {},
+				rotationRootReceiptId: replacedReceipt?.rotationRootReceiptId ?? receiptId,
+				attribution: { ...request.attribution },
+				metadata,
+				finalizer: this.#finalizer.name,
+				finalizationId
+			};
+			stage = "record";
+			let signature = "";
+			await material.use(async (plaintext) => {
+				signature = await this.#attestor.attest(custodyAttestationPayload(unsignedReceipt, credentialCommitment(plaintext), {
+					algorithm: "Ed25519",
+					attestor: this.#attestor.name,
+					keyId: this.#attestor.keyId
+				}));
+			});
+			if (!/^[A-Za-z0-9_-]{86}$/.test(signature) || Buffer.from(signature, "base64url").byteLength !== 64 || Buffer.from(signature, "base64url").toString("base64url") !== signature || redactCredentialText(signature) !== signature) throw new CustodyError("INVALID_CUSTODY_ATTESTATION", "record", "Custody attestor returned an invalid signature");
+			const receipt = {
+				...unsignedReceipt,
+				attestation: {
+					algorithm: "Ed25519",
+					attestor: this.#attestor.name,
+					keyId: this.#attestor.keyId,
+					signature
+				}
+			};
+			stage = "record";
+			await this.#ledger.recordIssuance(receipt, this.#event("finalization-pending", receiptId));
+			receiptRecorded = true;
+			stage = "activate";
+			preparedReceipt = receipt;
+			if (!(await this.#finalizer.prepare({
+				receipt: structuredClone(receipt),
+				secret: material
+			})).prepared) throw new CustodyError("CREDENTIAL_ACTIVATION_FAILED", "activate", "Credential post-attestation activation failed");
+			retrieved?.destroy();
+			retrieved = void 0;
+			if (request.mode === "durable") issued.secret.destroy();
+			stage = "activate";
+			await this.#finalizer.commit({ receipt: structuredClone(receipt) });
+			stage = "record";
+			const retirementRecoveryId = replacedReceipt ? randomUUID() : void 0;
+			const retirementPending = replacedReceipt && retirementRecoveryId ? {
+				...this.#event("retirement-pending", replacedReceipt.receiptId),
+				eventId: retirementRecoveryId,
+				recoveryId: retirementRecoveryId,
+				credentialId: replacedReceipt.credentialId,
+				recoveryReceipt: structuredClone(replacedReceipt),
+				replacementReceiptId: receipt.receiptId
+			} : void 0;
+			await this.#ledger.commitIssuance(receipt.receiptId, this.#event("issued", receipt.receiptId), retirementPending);
+			const lease = this.#createLease(receipt, request.mode === "ephemeral" ? issued.secret : void 0);
+			if (replacedReceipt) try {
+				this.#leaseInvalidators.get(replacedReceipt.receiptId)?.();
+				await this.#revokeReceipt(replacedReceipt, "replaced", "replaced");
+				this.#leaseInvalidators.delete(replacedReceipt.receiptId);
+				await this.#ledger.appendEvent({
+					...this.#event("retirement-complete", replacedReceipt.receiptId),
+					recoveryId: retirementRecoveryId
+				});
+			} catch (cause) {
+				if (retirementRecoveryId) this.#scheduleRetirement(retirementRecoveryId, replacedReceipt, receipt.receiptId);
+				try {
+					this.#onBackgroundError?.(new CustodyError("PREDECESSOR_RETIREMENT_PENDING", "revoke", "Replacement is active while predecessor retirement retries", {
+						cause,
+						details: { recoveryId: retirementRecoveryId }
+					}));
+				} catch {}
+			}
+			preparedReceipt = void 0;
+			return lease;
+		} catch (cause) {
+			const safeCause = await sanitizeCustodyCause(cause, [retrieved, issued?.secret]);
+			retrieved?.destroy();
+			issued?.secret.destroy();
+			if (issued) {
+				const requiresSink = request.mode === "durable";
+				try {
+					if (receiptRecorded && preparedReceipt) await this.#abortAndRevoke(preparedReceipt, `rollback after ${stage}`);
+					else await this.#rollback(issued.credentialId, sinkRecord, stage, requiresSink);
+				} catch (rollbackCause) {
+					const recoveryId = randomUUID();
+					const pendingEvent = {
+						...this.#event("rollback-pending", receiptRecorded ? preparedReceipt?.receiptId : void 0, sinkRecord?.reference, `rollback after ${stage}`),
+						eventId: recoveryId,
+						recoveryId,
+						credentialId: issued.credentialId,
+						requiresSink,
+						finalizationReceipt: preparedReceipt ? structuredClone(preparedReceipt) : void 0
+					};
+					try {
+						await this.#ledger.appendEvent(pendingEvent);
+					} catch {}
+					this.#scheduleRollback(recoveryId, issued.credentialId, sinkRecord, stage, requiresSink, preparedReceipt, receiptRecorded);
+					throw new CustodyError("CUSTODY_ROLLBACK_FAILED", "revoke", "Credential rollback is pending automatic retry", {
+						cause: rollbackCause,
+						details: {
+							recoveryId,
+							credentialId: issued.credentialId,
+							requiresSink,
+							failedStage: stage
+						}
+					});
+				}
+			}
+			if (safeCause instanceof CustodyError) throw safeCause;
+			throw new CustodyError(`CUSTODY_${stage.toUpperCase()}_FAILED`, stage, `Credential custody failed during ${stage}`, { cause: safeCause });
+		}
+	}
+	async rotate(receiptId, request) {
+		if ((await this.#findReceipt(receiptId)).mode !== "durable") throw new CustodyError("DURABLE_ROTATION_REQUIRED", "issue", "Only durable credentials can be rotated");
+		return this.issue({
+			...request,
+			mode: "durable",
+			replacesReceiptId: receiptId
+		});
+	}
+	async revoke(receiptId, reason = "recovery") {
+		const receipt = await this.#findReceipt(receiptId);
+		this.#leaseInvalidators.get(receiptId)?.();
+		await this.#revokeReceipt(receipt, reason);
+		this.#leaseInvalidators.delete(receiptId);
+	}
+	async recoverPendingRollbacks() {
+		const events = await this.#ledger.listEvents();
+		const receipts = await this.#ledger.listReceipts();
+		const activeIds = new Set(events.filter((event) => event.type === "issued").map((event) => event.receiptId));
+		const terminalIds = new Set(events.filter((event) => [
+			"revoked",
+			"expired",
+			"replaced"
+		].includes(event.type)).map((event) => event.receiptId));
+		const completedRollbackIds = new Set(events.filter((event) => event.type === "rollback-complete").map((event) => event.recoveryId));
+		const rollbackReceiptIds = new Set(events.filter((event) => event.type === "rollback-pending" && !completedRollbackIds.has(event.recoveryId)).map((event) => event.receiptId));
+		const pendingByReceipt = new Map(events.filter((event) => event.type === "finalization-pending" && event.receiptId).map((event) => [event.receiptId, event]));
+		const takeoverCutoff = this.#now().getTime() - this.#finalizationTakeoverMs;
+		const failures = [];
+		for (const receipt of receipts.filter((item) => !activeIds.has(item.receiptId) && !terminalIds.has(item.receiptId) && !rollbackReceiptIds.has(item.receiptId) && (() => {
+			const pending = pendingByReceipt.get(item.receiptId);
+			if (pending) {
+				const pendingAt = parseTimestamp(pending.occurredAt, "occurredAt", "reconcile");
+				if (pendingAt > takeoverCutoff) {
+					this.#scheduleFinalizationTakeover(item.finalizationId, pendingAt + this.#finalizationTakeoverMs);
+					return false;
+				}
+			}
+			return pending !== void 0 && parseTimestamp(pending.occurredAt, "occurredAt", "reconcile") <= takeoverCutoff;
+		})())) try {
+			if (await this.#finalizer.status({ receipt: structuredClone(receipt) }) === "committed") {
+				const predecessor = receipt.replacesReceiptId ? receipts.find((item) => item.receiptId === receipt.replacesReceiptId) : void 0;
+				const recoveryId = predecessor ? randomUUID() : void 0;
+				await this.#ledger.commitIssuance(receipt.receiptId, this.#event("issued", receipt.receiptId), predecessor && recoveryId ? {
+					...this.#event("retirement-pending", predecessor.receiptId),
+					eventId: recoveryId,
+					recoveryId,
+					credentialId: predecessor.credentialId,
+					recoveryReceipt: structuredClone(predecessor),
+					replacementReceiptId: receipt.receiptId
+				} : void 0);
+				activeIds.add(receipt.receiptId);
+				if (predecessor && recoveryId) this.#scheduleRetirement(recoveryId, predecessor, receipt.receiptId);
+			} else await this.#abortAndRevoke(receipt, "incomplete finalization recovery");
+		} catch {
+			failures.push(receipt.finalizationId);
+			this.#scheduleFinalizationTakeover(receipt.finalizationId, this.#now().getTime() + this.#ephemeralRevokeRetryMs);
+		}
+		for (const receipt of receipts.filter((item) => item.mode === "ephemeral" && activeIds.has(item.receiptId) && !terminalIds.has(item.receiptId) && item.expiresAt !== void 0)) try {
+			const deadline = parseTimestamp(receipt.expiresAt ?? "", "expiresAt", "revoke");
+			if (deadline <= this.#now().getTime()) await this.#revokeReceipt(receipt, "restart expiry recovery", "expired");
+			else this.#scheduleReceiptExpiry(receipt, deadline);
+		} catch {
+			failures.push(receipt.receiptId);
+		}
+		const completed = new Set(events.filter((event) => event.type === "rollback-complete").map((event) => event.recoveryId));
+		const pendingRollbacks = new Map(events.filter((event) => event.type === "rollback-pending" && event.recoveryId && !completed.has(event.recoveryId)).map((event) => [event.recoveryId, event]));
+		for (const pending of pendingRollbacks.values()) {
+			if (!pending.credentialId || !pending.recoveryId) continue;
+			const timer = this.#pendingTimers.get(pending.recoveryId);
+			if (timer) clearTimeout(timer);
+			this.#pendingTimers.delete(pending.recoveryId);
+			try {
+				assertSafeIdentifier(pending.credentialId, "credentialId", "revoke");
+				if (pending.receiptId && pending.finalizationReceipt) await this.#abortAndRevoke(pending.finalizationReceipt, "pending rollback recovery");
+				else await this.#rollback(pending.credentialId, void 0, "revoke", pending.requiresSink === true);
+				await this.#completeRollback(pending.recoveryId, pending.credentialId, pending.sinkReference);
+				if (pending.receiptId) {
+					terminalIds.add(pending.receiptId);
+					this.#leaseInvalidators.delete(pending.receiptId);
+				}
+			} catch {
+				failures.push(pending.recoveryId);
+				this.#scheduleRollback(pending.recoveryId, pending.credentialId, void 0, "revoke", pending.requiresSink === true, pending.finalizationReceipt, Boolean(pending.receiptId));
+			}
+		}
+		const retired = new Set(events.filter((event) => event.type === "retirement-complete").map((event) => event.recoveryId));
+		for (const pending of events.filter((event) => event.type === "retirement-pending" && event.recoveryId && !retired.has(event.recoveryId))) {
+			if (!pending.recoveryId || !pending.recoveryReceipt) continue;
+			if (pending.replacementReceiptId && (!activeIds.has(pending.replacementReceiptId) || terminalIds.has(pending.replacementReceiptId))) {
+				await this.#ledger.appendEvent({
+					...this.#event("retirement-complete", pending.recoveryReceipt.receiptId),
+					recoveryId: pending.recoveryId,
+					reason: "replacement is not active"
+				});
+				continue;
+			}
+			try {
+				await this.#revokeReceipt(pending.recoveryReceipt, "replacement retirement recovery", "replaced");
+				await this.#ledger.appendEvent({
+					...this.#event("retirement-complete", pending.recoveryReceipt.receiptId),
+					recoveryId: pending.recoveryId
+				});
+				this.#leaseInvalidators.delete(pending.recoveryReceipt.receiptId);
+			} catch {
+				failures.push(pending.recoveryId);
+				this.#scheduleRetirement(pending.recoveryId, pending.recoveryReceipt, pending.replacementReceiptId);
+			}
+		}
+		if (failures.length) throw new CustodyError("PENDING_ROLLBACK_RECOVERY_FAILED", "revoke", "One or more pending credential rollbacks could not be recovered", { details: { recoveryIds: failures } });
+	}
+	async recoverCredential(credentialId, options = {}) {
+		assertSafeIdentifier(credentialId, "credentialId", "revoke");
+		await this.#rollback(credentialId, void 0, "revoke", options.requiresSink === true);
+	}
+	async reconcile() {
+		if (!this.#sink) throw new CustodyError("DURABLE_SINK_REQUIRED", "reconcile", "Reconciliation requires a secret sink");
+		const [receipts, events, inventory] = await Promise.all([
+			this.#ledger.listReceipts(),
+			this.#ledger.listEvents(),
+			this.#sink.inventory()
+		]);
+		for (const entry of inventory) {
+			assertSinkRecord(entry, this.#sink.name);
+			assertSafeIdentifier(entry.credentialId, "credentialId", "reconcile");
+		}
+		const terminal = new Set(events.filter((event) => [
+			"revoked",
+			"expired",
+			"replaced"
+		].includes(event.type)).map((event) => event.receiptId));
+		const issued = new Set(events.filter((event) => event.type === "issued").map((event) => event.receiptId));
+		for (const replacement of receipts) if (replacement.replacesReceiptId && issued.has(replacement.receiptId) && !terminal.has(replacement.receiptId)) terminal.add(replacement.replacesReceiptId);
+		const active = receipts.filter((receipt) => receipt.mode === "durable" && receipt.sink !== void 0 && issued.has(receipt.receiptId) && !terminal.has(receipt.receiptId));
+		const orphanCutoff = this.#now().getTime() - this.#orphanGraceMs;
+		return {
+			checkedAt: this.#now().toISOString(),
+			orphaned: inventory.filter((entry) => parseTimestamp(entry.storedAt, "storedAt", "reconcile") <= orphanCutoff && !active.some((receipt) => sameSinkRecord(receipt.sink, entry) && entry.credentialId === receipt.credentialId)),
+			missing: active.filter((receipt) => !inventory.some((entry) => sameSinkRecord(receipt.sink, entry) && entry.credentialId === receipt.credentialId))
+		};
+	}
+	async recoverOrphans(report) {
+		if (!this.#sink) throw new CustodyError("DURABLE_SINK_REQUIRED", "reconcile", "Orphan recovery requires a secret sink");
+		const current = await this.reconcile();
+		const requested = new Set(report.orphaned.map((entry) => sinkIdentity(entry, entry.credentialId)));
+		const confirmed = current.orphaned.filter((entry) => requested.has(sinkIdentity(entry, entry.credentialId)));
+		for (const orphan of confirmed) {
+			assertSinkRecord(orphan, this.#sink.name);
+			await this.#ledger.appendEvent(this.#event("orphan-detected", void 0, orphan.reference));
+			assertSafeIdentifier(orphan.credentialId, "credentialId", "reconcile");
+			try {
+				await this.#issuer.revoke(orphan.credentialId, "orphan recovery");
+			} catch {
+				throw new CustodyError("ORPHAN_REVOCATION_FAILED", "reconcile", "Orphan credential revocation failed");
+			}
+			await this.#sink.remove(orphan, "orphan recovery");
+			await this.#ledger.appendEvent(this.#event("orphan-removed", void 0, orphan.reference));
+		}
+	}
+	#createLease(receipt, ephemeralMaterial) {
+		let unavailable = false;
+		let revocationComplete = false;
+		let revocationInFlight;
+		let timer;
+		const revoke = async (reason = "requested", terminalType = "revoked") => {
+			unavailable = true;
+			if (timer) clearTimeout(timer);
+			ephemeralMaterial?.destroy();
+			if (revocationComplete) return;
+			if (revocationInFlight) return revocationInFlight;
+			revocationInFlight = this.#revokeReceipt(receipt, reason, terminalType).then(() => {
+				revocationComplete = true;
+				this.#leaseInvalidators.delete(receipt.receiptId);
+			}).finally(() => {
+				revocationInFlight = void 0;
+			});
+			return revocationInFlight;
+		};
+		const invalidate = () => {
+			unavailable = true;
+			if (timer) clearTimeout(timer);
+			ephemeralMaterial?.destroy();
+		};
+		this.#leaseInvalidators.set(receipt.receiptId, invalidate);
+		if (receipt.mode === "ephemeral" && receipt.expiresAt) {
+			const deadline = parseTimestamp(receipt.expiresAt, "expiresAt", "issue");
+			const schedule = (delay) => {
+				timer = setTimeout(() => {
+					const remaining = deadline - this.#now().getTime();
+					if (remaining > 0) {
+						schedule(Math.min(remaining, MAX_TIMER_DELAY_MS));
+						return;
+					}
+					revoke("expired", "expired").catch((cause) => {
+						try {
+							this.#onBackgroundError?.(cause instanceof CustodyError ? cause : new CustodyError("EPHEMERAL_CLEANUP_FAILED", "revoke", "Ephemeral credential cleanup failed", { cause }));
+						} catch {} finally {
+							schedule(this.#ephemeralRevokeRetryMs);
+						}
+					});
+				}, Math.min(Math.max(0, delay), MAX_TIMER_DELAY_MS));
+				timer.unref?.();
+			};
+			schedule(deadline - this.#now().getTime());
+		}
+		return {
+			receipt: structuredClone(receipt),
+			withEnvironment: async (variableName, operation) => {
+				this.#assertLeaseAvailable(receipt, unavailable);
+				if (!ENVIRONMENT_VARIABLE.test(variableName)) throw new CustodyError("INVALID_ENVIRONMENT_VARIABLE", "inject", "Environment variable name is invalid");
+				let material = ephemeralMaterial;
+				if (!material) {
+					if (!this.#sink || !receipt.sink) throw new CustodyError("DURABLE_SINK_REQUIRED", "retrieve", "Durable credential retrieval requires a secret sink record");
+					material = await this.#sink.retrieve(receipt.sink);
+				}
+				try {
+					this.#assertLeaseAvailable(receipt, unavailable);
+					await withEnvironmentSecret(material, variableName, operation, { expiresAt: receipt.expiresAt });
+				} finally {
+					if (!ephemeralMaterial) material.destroy();
+				}
+			},
+			withChildProcess: async (options) => {
+				this.#assertLeaseAvailable(receipt, unavailable);
+				let material = ephemeralMaterial;
+				if (!material) {
+					if (!this.#sink || !receipt.sink) throw new CustodyError("DURABLE_SINK_REQUIRED", "retrieve", "Durable credential retrieval requires a secret sink record");
+					material = await this.#sink.retrieve(receipt.sink);
+				}
+				try {
+					this.#assertLeaseAvailable(receipt, unavailable);
+					return await runCredentialChildProcess(material, options, { expiresAt: receipt.expiresAt });
+				} catch (cause) {
+					if (cause instanceof CustodyError && cause.code === "CREDENTIAL_CHILD_PROCESS_CLEANUP_FAILED") {
+						invalidate();
+						await this.#recoverChildProcessCleanupFailure(receipt);
+					}
+					throw cause;
+				} finally {
+					if (!ephemeralMaterial) material.destroy();
+				}
+			},
+			revoke: (reason) => revoke(reason)
+		};
+	}
+	#assertLeaseAvailable(receipt, unavailable) {
+		const expired = receipt.expiresAt !== void 0 && parseTimestamp(receipt.expiresAt, "expiresAt", "inject") <= this.#now().getTime();
+		if (unavailable || expired) throw new CustodyError("CREDENTIAL_REVOKED", "inject", "Credential is no longer available");
+	}
+	async #revokeReceipt(receipt, reason, terminalType = "revoked") {
+		const failures = [];
+		try {
+			await this.#issuer.revoke(receipt.credentialId, reason);
+		} catch {
+			failures.push("issuer");
+		}
+		if (!failures.length && receipt.sink && this.#sink) try {
+			await this.#sink.remove(receipt.sink, reason);
+		} catch {
+			failures.push("sink");
+		}
+		if (failures.length) throw new CustodyError("CREDENTIAL_REVOCATION_FAILED", "revoke", "Credential revocation did not complete", { details: { failedOperations: failures } });
+		await this.#appendEventEventually(this.#event(terminalType, receipt.receiptId, void 0, reason));
+	}
+	async #rollback(credentialId, sinkRecord, failedStage, requiresSink = false) {
+		const failures = [];
+		try {
+			await this.#issuer.revoke(credentialId, `rollback after ${failedStage}`);
+		} catch {
+			failures.push("issuer");
+		}
+		if (!failures.length && requiresSink && !this.#sink) failures.push("sink");
+		if (!failures.length && requiresSink && this.#sink) try {
+			if (sinkRecord) await this.#sink.remove(sinkRecord, `rollback after ${failedStage}`);
+			else await this.#sink.removeByCredentialId(credentialId, `rollback after ${failedStage}`);
+		} catch {
+			failures.push("sink");
+		}
+		if (failures.length) throw new CustodyError("CUSTODY_ROLLBACK_FAILED", "revoke", "Credential rollback did not complete", { details: {
+			failedOperations: failures,
+			failedStage
+		} });
+	}
+	async #abortAndRevoke(receipt, reason) {
+		const failures = [];
+		try {
+			await this.#finalizer.abort({
+				receipt: structuredClone(receipt),
+				reason
+			});
+		} catch {
+			failures.push("finalizer");
+		}
+		try {
+			await this.#revokeReceipt(receipt, reason);
+		} catch {
+			failures.push("credential");
+		}
+		if (failures.length) throw new CustodyError("CUSTODY_ROLLBACK_FAILED", "revoke", "Finalization rollback did not complete", { details: { failedOperations: failures } });
+	}
+	async #recoverChildProcessCleanupFailure(receipt) {
+		const reason = "child process cleanup could not be verified";
+		try {
+			await this.#abortAndRevoke(receipt, reason);
+			this.#leaseInvalidators.delete(receipt.receiptId);
+			return;
+		} catch (cause) {
+			const recoveryId = randomUUID();
+			const pendingEvent = {
+				...this.#event("rollback-pending", receipt.receiptId, receipt.sink?.reference, reason),
+				eventId: recoveryId,
+				recoveryId,
+				credentialId: receipt.credentialId,
+				requiresSink: receipt.mode === "durable",
+				finalizationReceipt: structuredClone(receipt)
+			};
+			await this.#persistRollbackIntent(pendingEvent);
+			this.#scheduleRollback(recoveryId, receipt.credentialId, receipt.sink, "inject", receipt.mode === "durable", receipt, true);
+			try {
+				this.#onBackgroundError?.(new CustodyError("CREDENTIAL_CHILD_PROCESS_CLEANUP_PENDING", "revoke", "Credential revocation is pending after child process cleanup failure", {
+					cause,
+					details: { recoveryId }
+				}));
+			} catch {}
+		}
+	}
+	async #persistRollbackIntent(event) {
+		for (;;) try {
+			await this.#ledger.appendEvent(event);
+			return;
+		} catch (cause) {
+			try {
+				if ((await this.#ledger.listEvents()).some((existing) => existing.eventId === event.eventId && sameCustodyEvent(existing, event))) return;
+			} catch {}
+			try {
+				this.#onBackgroundError?.(new CustodyError("ROLLBACK_INTENT_PERSISTENCE_FAILED", "record", "Credential rollback intent persistence is retrying", {
+					cause,
+					details: { recoveryId: event.recoveryId }
+				}));
+			} catch {}
+			await new Promise((resolve) => {
+				setTimeout(resolve, this.#ephemeralRevokeRetryMs);
+			});
+		}
+	}
+	#scheduleRollback(recoveryId, credentialId, sinkRecord, failedStage, requiresSink, finalizationReceipt, receiptRecorded = false) {
+		if (this.#pendingTimers.has(recoveryId)) return;
+		const timer = setTimeout(() => {
+			this.#pendingTimers.delete(recoveryId);
+			Promise.resolve().then(async () => {
+				if (receiptRecorded && finalizationReceipt) await this.#abortAndRevoke(finalizationReceipt, `rollback after ${failedStage}`);
+				else await this.#rollback(credentialId, sinkRecord, failedStage, requiresSink);
+			}).then(() => this.#completeRollback(recoveryId, credentialId, sinkRecord?.reference)).then(() => {
+				if (receiptRecorded && finalizationReceipt) this.#leaseInvalidators.delete(finalizationReceipt.receiptId);
+			}).catch((cause) => {
+				try {
+					this.#onBackgroundError?.(cause instanceof CustodyError ? cause : new CustodyError("CUSTODY_ROLLBACK_FAILED", "revoke", "Credential rollback retry failed", { cause }));
+				} catch {} finally {
+					this.#scheduleRollback(recoveryId, credentialId, sinkRecord, failedStage, requiresSink, finalizationReceipt, receiptRecorded);
+				}
+			});
+		}, this.#ephemeralRevokeRetryMs);
+		this.#pendingTimers.set(recoveryId, timer);
+		timer.unref?.();
+	}
+	#scheduleRetirement(recoveryId, receipt, replacementReceiptId) {
+		if (this.#pendingTimers.has(recoveryId)) return;
+		const timer = setTimeout(() => {
+			this.#pendingTimers.delete(recoveryId);
+			this.#ledger.listEvents().then(async (events) => {
+				if (replacementReceiptId && (!events.some((event) => event.receiptId === replacementReceiptId && event.type === "issued") || events.some((event) => event.receiptId === replacementReceiptId && [
+					"revoked",
+					"expired",
+					"replaced"
+				].includes(event.type)))) return;
+				await this.#revokeReceipt(receipt, "replacement retirement retry", "replaced");
+				this.#leaseInvalidators.delete(receipt.receiptId);
+			}).then(() => this.#ledger.appendEvent({
+				...this.#event("retirement-complete", receipt.receiptId),
+				recoveryId
+			})).catch(() => this.#scheduleRetirement(recoveryId, receipt, replacementReceiptId));
+		}, this.#ephemeralRevokeRetryMs);
+		this.#pendingTimers.set(recoveryId, timer);
+		timer.unref?.();
+	}
+	#scheduleReceiptExpiry(receipt, deadline) {
+		if (this.#pendingTimers.has(receipt.receiptId)) return;
+		const delay = Math.min(Math.max(0, deadline - this.#now().getTime()), MAX_TIMER_DELAY_MS);
+		const timer = setTimeout(() => {
+			this.#pendingTimers.delete(receipt.receiptId);
+			if (deadline > this.#now().getTime()) {
+				this.#scheduleReceiptExpiry(receipt, deadline);
+				return;
+			}
+			this.#revokeReceipt(receipt, "restart expiry recovery", "expired").catch(() => this.#scheduleReceiptExpiry(receipt, deadline));
+		}, delay);
+		this.#pendingTimers.set(receipt.receiptId, timer);
+		timer.unref?.();
+	}
+	#scheduleFinalizationTakeover(recoveryId, deadline) {
+		if (this.#pendingTimers.has(recoveryId)) return;
+		const timer = setTimeout(() => {
+			this.#pendingTimers.delete(recoveryId);
+			this.recoverPendingRollbacks().catch((cause) => {
+				try {
+					this.#onBackgroundError?.(cause instanceof CustodyError ? cause : new CustodyError("PENDING_ROLLBACK_RECOVERY_FAILED", "revoke", "Finalization takeover recovery failed", { cause }));
+				} catch {}
+			});
+		}, Math.min(Math.max(0, deadline - this.#now().getTime()), MAX_TIMER_DELAY_MS));
+		this.#pendingTimers.set(recoveryId, timer);
+		timer.unref?.();
+	}
+	async #completeRollback(recoveryId, credentialId, sinkReference) {
+		await this.#ledger.appendEvent({
+			...this.#event("rollback-complete", void 0, sinkReference, "credential rollback completed"),
+			recoveryId,
+			credentialId
+		});
+	}
+	async #appendEventEventually(event) {
+		try {
+			await this.#ledger.appendEvent(event);
+		} catch (cause) {
+			const recoveryId = `event-${event.eventId}`;
+			if (this.#pendingTimers.has(recoveryId)) return;
+			const timer = setTimeout(() => {
+				this.#pendingTimers.delete(recoveryId);
+				this.#appendEventEventually(event).catch(() => void 0);
+			}, this.#ephemeralRevokeRetryMs);
+			this.#pendingTimers.set(recoveryId, timer);
+			try {
+				this.#onBackgroundError?.(new CustodyError("CUSTODY_EVENT_RECORD_FAILED", "record", "Custody terminal event recording is pending retry", { cause }));
+			} catch {}
+		}
+	}
+	async #findReceipt(receiptId) {
+		assertSafeIdentifier(receiptId, "receiptId", "record");
+		const receipt = (await this.#ledger.listReceipts()).find((candidate) => candidate.receiptId === receiptId);
+		if (!receipt) throw new CustodyError("CUSTODY_RECEIPT_NOT_FOUND", "record", "Custody receipt was not found");
+		return receipt;
+	}
+	#event(type, receiptId, sinkReference, reason) {
+		return {
+			eventId: randomUUID(),
+			type,
+			occurredAt: this.#now().toISOString(),
+			...receiptId ? { receiptId } : {},
+			...sinkReference ? { sinkReference } : {},
+			...reason ? { reason: redactCredentialText(reason) } : {}
+		};
+	}
+};
+async function withEnvironmentSecret(material, variableName, operation, bounds) {
+	if (!ENVIRONMENT_VARIABLE.test(variableName)) throw new CustodyError("INVALID_ENVIRONMENT_VARIABLE", "inject", "Environment variable name is invalid");
+	if (bounds?.expiresAt) {
+		parseTimestamp(bounds.expiresAt, "expiresAt", "inject");
+		throw new CustodyError("EXPIRING_ENVIRONMENT_CALLBACK_UNSAFE", "inject", "Expiring credentials require bounded child-process injection");
+	}
+	await withEnvironmentLock(async () => {
+		const existed = Object.hasOwn(process.env, variableName);
+		const previous = process.env[variableName];
+		try {
+			await material.use(async (value) => {
+				process.env[variableName] = value;
+				await operation();
+			});
+		} catch (cause) {
+			if (cause instanceof CustodyError) throw cause;
+			throw new CustodyError("SECRET_OPERATION_FAILED", "inject", "Bounded secret operation failed", { cause });
+		} finally {
+			if (existed) process.env[variableName] = previous;
+			else delete process.env[variableName];
+		}
+	});
+}
+async function runCredentialChildProcess(material, options, bounds) {
+	if (options.trust !== "cooperative-process-group" || !options.command || !ENVIRONMENT_VARIABLE.test(options.environmentVariable)) throw new CustodyError("INVALID_CHILD_PROCESS_OPTIONS", "inject", "Credential child-process options are invalid");
+	if (process.platform === "win32") throw new CustodyError("CREDENTIAL_CHILD_PROCESS_UNSUPPORTED", "inject", "Credential child-process group custody is unavailable on this platform");
+	const timeoutMs = options.timeoutMs ?? 6e4;
+	const maxOutputBytes = options.maxOutputBytes ?? 1024 * 1024;
+	if (!Number.isFinite(timeoutMs) || !Number.isFinite(maxOutputBytes) || timeoutMs <= 0 || timeoutMs > MAX_TIMER_DELAY_MS || maxOutputBytes <= 0) throw new CustodyError("INVALID_CHILD_PROCESS_BOUNDS", "inject", "Credential child-process bounds must be positive");
+	let result;
+	await material.use(async (secret) => {
+		const expiryLimit = bounds?.expiresAt ? parseTimestamp(bounds.expiresAt, "expiresAt", "inject") - Date.now() : Number.POSITIVE_INFINITY;
+		const effectiveTimeout = Math.min(timeoutMs, expiryLimit);
+		if (effectiveTimeout <= 0) throw new CustodyError("CREDENTIAL_EXPIRED", "inject", "Credential expired before child-process launch");
+		const childEnvironment = await withEnvironmentLock(() => ({
+			...process.env,
+			...options.environment,
+			[options.environmentVariable]: secret
+		}));
+		result = await new Promise((resolve, reject) => {
+			const child = spawn(options.command, [...options.args ?? []], {
+				cwd: options.cwd,
+				detached: true,
+				env: childEnvironment,
+				shell: false,
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				]
+			});
+			const stdout = [];
+			const stderr = [];
+			let outputBytes = 0;
+			let outputExceeded = false;
+			let timedOut = false;
+			let settled = false;
+			let escalationTimer;
+			const terminateGroup = (signal) => {
+				if (child.pid) try {
+					process.kill(-child.pid, signal);
+					return;
+				} catch {}
+				child.kill(signal);
+			};
+			const waitForGroupExit = async () => {
+				if (!child.pid) return true;
+				const deadline = Date.now() + 2e3;
+				while (Date.now() < deadline) {
+					try {
+						process.kill(-child.pid, 0);
+					} catch (cause) {
+						if (cause.code === "ESRCH") return true;
+					}
+					await new Promise((next) => setTimeout(next, 10));
+				}
+				return false;
+			};
+			const beginTermination = () => {
+				terminateGroup("SIGTERM");
+				if (!escalationTimer) {
+					escalationTimer = setTimeout(() => {
+						escalationTimer = void 0;
+						terminateGroup("SIGKILL");
+					}, 1e3);
+					escalationTimer.unref?.();
+				}
+			};
+			const timer = setTimeout(() => {
+				timedOut = true;
+				beginTermination();
+			}, effectiveTimeout);
+			timer.unref?.();
+			const capture = (target) => (chunk) => {
+				outputBytes += chunk.length;
+				if (outputBytes > maxOutputBytes) {
+					timedOut = true;
+					outputExceeded = true;
+					target.length = 0;
+					beginTermination();
+					return;
+				}
+				if (outputExceeded) return;
+				target.push(Buffer.from(chunk));
+			};
+			child.stdout.on("data", capture(stdout));
+			child.stderr.on("data", capture(stderr));
+			child.once("error", () => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				if (escalationTimer) clearTimeout(escalationTimer);
+				terminateGroup("SIGKILL");
+				reject(new CustodyError("CREDENTIAL_CHILD_PROCESS_FAILED", "inject", "Credential child process could not start"));
+			});
+			child.once("close", async (exitCode, signal) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				if (escalationTimer) clearTimeout(escalationTimer);
+				terminateGroup("SIGTERM");
+				terminateGroup("SIGKILL");
+				if (!await waitForGroupExit()) {
+					reject(new CustodyError("CREDENTIAL_CHILD_PROCESS_CLEANUP_FAILED", "inject", "Credential child process group cleanup could not be verified"));
+					return;
+				}
+				resolve({
+					exitCode,
+					signal,
+					stdout: outputExceeded ? REDACTED : redactCredentialText(Buffer.concat(stdout).toString("utf8"), [secret]),
+					stderr: outputExceeded ? REDACTED : redactCredentialText(Buffer.concat(stderr).toString("utf8"), [secret]),
+					timedOut
+				});
+			});
+		});
+	});
+	if (!result) throw new CustodyError("CREDENTIAL_CHILD_PROCESS_FAILED", "inject", "Credential child process did not return a result");
+	return result;
+}
+async function verifyCustodyReceiptAttestation(receipt, material, publicKey) {
+	if (receipt.attestation.algorithm !== "Ed25519" || publicKey.type !== "public" || publicKey.asymmetricKeyType !== "ed25519" || !/^[A-Za-z0-9_-]{86}$/.test(receipt.attestation.signature) || Buffer.from(receipt.attestation.signature, "base64url").byteLength !== 64 || Buffer.from(receipt.attestation.signature, "base64url").toString("base64url") !== receipt.attestation.signature) return false;
+	let verified = false;
+	await material.use((plaintext) => {
+		const payload = custodyAttestationPayload(receipt, credentialCommitment(plaintext));
+		try {
+			verified = verify(null, Buffer.from(payload), publicKey, Buffer.from(receipt.attestation.signature, "base64url"));
+		} catch {
+			verified = false;
+		}
+	});
+	return verified;
+}
+function redactCredentialText(input, knownSecrets = []) {
+	let output = input;
+	for (const secret of knownSecrets.filter(Boolean)) output = output.replaceAll(secret, REDACTED);
+	for (const { pattern, replacement } of CREDENTIAL_PATTERNS) output = output.replace(pattern, replacement);
+	return output;
+}
+function redactCredentialValues(value, knownSecrets = []) {
+	if (value instanceof SecretMaterial) return REDACTED;
+	if (typeof value === "string") return redactCredentialText(value, knownSecrets);
+	if (Array.isArray(value)) return value.map((entry) => redactCredentialValues(entry, knownSecrets));
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, entry]) => [redactCredentialText(key, knownSecrets), redactCredentialValues(entry, knownSecrets)]));
+	return value;
+}
+async function sanitizeCustodyCause(cause, materials) {
+	if (!(cause instanceof CustodyError)) return cause;
+	const knownSecrets = [];
+	for (const material of materials) {
+		if (!material || material.destroyed) continue;
+		await material.use((value) => {
+			knownSecrets.push(value);
+		});
+	}
+	return new CustodyError(redactCredentialText(cause.code, knownSecrets) === cause.code ? cause.code : "INVALID_CUSTODY_ERROR_CODE", cause.stage, redactCredentialText(cause.message, knownSecrets), cause.details ? { details: redactCredentialValues(cause.details, knownSecrets) } : void 0);
+}
+function credentialCommitment(plaintext) {
+	return createHash("sha256").update(plaintext).digest("base64url");
+}
+function custodyAttestationPayload(receipt, commitment, identity) {
+	const { attestation, ...unsigned } = receipt;
+	return JSON.stringify(canonicalize({
+		schema: "happyvertical.credential-custody-attestation.v1",
+		receipt: unsigned,
+		attestation: identity ?? {
+			algorithm: attestation.algorithm,
+			attestor: attestation.attestor,
+			keyId: attestation.keyId
+		},
+		credentialCommitment: commitment
+	}));
+}
+function canonicalize(value) {
+	if (Array.isArray(value)) return value.map(canonicalize);
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([key, entry]) => [key, canonicalize(entry)]));
+	return value;
+}
+function sameCustodyEvent(left, right) {
+	return JSON.stringify(canonicalize(left)) === JSON.stringify(canonicalize(right));
+}
+function assertAttribution(attribution) {
+	assertSafeIdentifier(attribution.actor, "attribution.actor", "issue");
+	assertSafeIdentifier(attribution.runtime, "attribution.runtime", "issue");
+	assertSafeIdentifier(attribution.session, "attribution.session", "issue");
+}
+function assertSinkRecord(record, sinkName) {
+	if (record.sinkName !== sinkName) throw new CustodyError("SINK_IDENTITY_MISMATCH", "store", "Secret sink returned a mismatched identity");
+	assertSafeIdentifier(record.sinkName, "sinkName", "store");
+	assertSafeIdentifier(record.reference, "sinkReference", "store");
+	assertSafeIdentifier(record.version, "sinkVersion", "store");
+	if (!Number.isFinite(new Date(record.storedAt).getTime())) throw new CustodyError("INVALID_SINK_TIMESTAMP", "store", "Secret sink returned an invalid timestamp");
+}
+function assertSafeIdentifier(value, field, stage) {
+	if (!SAFE_IDENTIFIER.test(value) || redactCredentialText(value) !== value) throw new CustodyError("UNSAFE_CUSTODY_IDENTIFIER", stage, `Custody ${field} must be a non-secret identifier`);
+}
+function sanitizeMetadata(metadata) {
+	return Object.freeze(Object.fromEntries(Object.entries(metadata ?? {}).map(([key, value]) => {
+		if (redactCredentialText(key) !== key) throw new CustodyError("UNSAFE_CUSTODY_METADATA_KEY", "issue", "Custody metadata key must not contain credential material");
+		return [key, redactCredentialText(value)];
+	})));
+}
+function parseTimestamp(value, field, stage) {
+	const timestamp = new Date(value).getTime();
+	if (!Number.isFinite(timestamp)) throw new CustodyError("INVALID_CUSTODY_TIMESTAMP", stage, `Custody ${field} timestamp is invalid`);
+	return timestamp;
+}
+function sameSinkRecord(left, right) {
+	return left.sinkName === right.sinkName && left.reference === right.reference && left.version === right.version && left.storedAt === right.storedAt;
+}
+function sinkIdentity(record, credentialId) {
+	return [
+		record.sinkName,
+		record.reference,
+		record.version,
+		record.storedAt,
+		credentialId ?? ""
+	].join("\0");
+}
+//#endregion
 //#region src/shared/factory.ts
 /**
 * Type guard for database options
@@ -688,7 +1754,7 @@ function isAzureKeyVaultOptions(opts) {
 * });
 *
 * // Encrypt a secret
-* const envelope = await store.encrypt('tenant-123', 'api-key', 'sk_live_xxx');
+* const envelope = await store.encrypt('tenant-123', 'api-key', 'synthetic-secret');
 *
 * // Decrypt
 * const decrypted = await store.decrypt('tenant-123', envelope);
@@ -711,6 +1777,6 @@ async function getSecretStore(options) {
 /** @internal */
 var PACKAGE_VERSION_INITIALIZED = true;
 //#endregion
-export { AMKUnavailableError, DatabaseSecretStore, DecryptionError, EncryptionError, EnvelopeEncryption, InvalidKeyFormatError, KeyNotFoundError, KeyRotationError, PACKAGE_VERSION_INITIALIZED, SecretError, StoreNotInitializedError, TenantKeyMissingError, getSecretStore, isAWSKMSOptions, isAzureKeyVaultOptions, isDatabaseOptions, isVaultOptions };
+export { AMKUnavailableError, CredentialCustody, CustodyError, DatabaseSecretStore, DecryptionError, Ed25519CustodyReceiptAttestor, EncryptionError, EnvelopeEncryption, InMemoryCustodyLedger, InvalidKeyFormatError, KeyNotFoundError, KeyRotationError, PACKAGE_VERSION_INITIALIZED, SecretError, SecretMaterial, StoreNotInitializedError, TenantKeyMissingError, getSecretStore, isAWSKMSOptions, isAzureKeyVaultOptions, isDatabaseOptions, isVaultOptions, redactCredentialText, redactCredentialValues, runCredentialChildProcess, verifyCustodyReceiptAttestation, withEnvironmentSecret };
 
 //# sourceMappingURL=index.js.map