@coffre/core 0.0.0 → 0.1.0

package/dist/kek.d.ts

@@ -0,0 +1,72 @@
+import { a as KekProvider, c as WrappedDek, i as KekCancelledError, n as DEK_BYTES, o as KekUnavailableError, r as KekBadClaimError, s as KeyOperation, t as KekRegistry, u as SecretContext } from "./registry-C0NGpxcc.js";
+//#region src/kek/local.d.ts
+/**
+ * A KEK held in local process memory, loaded from configuration.
+ *
+ * This is the local-development implementation of `KekProvider`. It is a
+ * different implementation of the same interface, not a branch that skips
+ * wrapping: the envelope format, the context binding and the failure modes are
+ * identical to what a remote KMS-backed provider will produce.
+ */
+export declare class LocalKekProvider implements KekProvider {
+  #private;
+  readonly provider = "local";
+  readonly keyId: string;
+  readonly keyVersion: string;
+  constructor(kek: Buffer, keyId: string, keyVersion?: string);
+  /** Build a provider from a base64-encoded 32-byte key, e.g. from an env var. */
+  static fromBase64(encoded: string, keyId: string, keyVersion?: string): LocalKekProvider;
+  /** Generate a fresh random KEK. Used by tests and by the dev seed script. */
+  static generate(keyId: string, keyVersion?: string): LocalKekProvider;
+  wrap(dek: Buffer, ctx: SecretContext, operation?: KeyOperation): Promise<WrappedDek>;
+  unwrap(wrapped: WrappedDek, ctx: SecretContext, operation?: KeyOperation): Promise<Buffer>;
+}
+/** Constant-time buffer comparison, for tests and callers that need it. */
+export declare function equalBytes(a: Buffer, b: Buffer): boolean;
+//#endregion
+//#region src/kek/sigv4.d.ts
+/** An AWS access key, with `sessionToken` when it is temporary (a role's). */
+type AwsCredentials = {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+};
+//#endregion
+//#region src/kek/aws-kms.d.ts
+type AwsKmsOptions = {
+  /**
+   * The key's ARN, `arn:aws:kms:<region>:<account>:key/<id>`. Coffre calls
+   * KMS in that region, and records the ARN on every data key it wraps. Not
+   * an alias, which can come to name another key.
+   */
+  keyArn: string;
+  /**
+   * An access key allowed `kms:Encrypt` and `kms:Decrypt` on it, or a
+   * function that returns one, asked before each call so that it may refresh
+   * (an AWS SDK credential provider is one).
+   */
+  credentials: AwsCredentials | (() => Promise<AwsCredentials>);
+  /** For tests. */
+  fetch?: typeof fetch;
+};
+/** A KEK held in AWS KMS: it never leaves, and coffre asks KMS to wrap and unwrap each data key. */
+export declare function awsKms(options: AwsKmsOptions): KekProvider;
+/**
+ * KMS's JSON API, `Encrypt` and `Decrypt`, signed with SigV4 and no SDK, so
+ * it runs as is on Node and in a Worker. Each call sends the secret's UUIDs
+ * as the encryption context, which KMS binds to the ciphertext and CloudTrail
+ * logs with the call: every decrypt there names the secret it was for, in a
+ * log neither coffre nor whoever runs it can edit.
+ */
+export declare class AwsKmsKekProvider implements KekProvider {
+  #private;
+  readonly provider = "aws-kms";
+  readonly keyId: string;
+  /** KMS keeps its own versions inside each ciphertext, and rotates the key material under the same ARN. */
+  readonly keyVersion = "1";
+  constructor(options: AwsKmsOptions);
+  wrap(dek: Buffer, ctx: SecretContext, operation?: KeyOperation): Promise<WrappedDek>;
+  unwrap(wrapped: WrappedDek, ctx: SecretContext, operation?: KeyOperation): Promise<Buffer>;
+}
+//#endregion
+export { type AwsCredentials, type AwsKmsOptions, DEK_BYTES, KekBadClaimError, KekCancelledError, type KekProvider, KekRegistry, KekUnavailableError, type KeyOperation, type WrappedDek };

package/dist/kek.js

@@ -0,0 +1,486 @@
+import { i as KekUnavailableError, n as KekBadClaimError, o as checkContext, r as KekCancelledError, s as encodeAad, t as DEK_BYTES } from "./types-Mi7-Tzj9.js";
+import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+//#region src/kek/cancellation.ts
+function checkOperation(operation, uncertain = false) {
+	if (operation !== void 0 && (operation.signal.aborted || Date.now() >= operation.deadline)) throw new KekCancelledError(uncertain);
+}
+const signals = /* @__PURE__ */ new WeakMap();
+/**
+* Enforce the deadline even when the caller's signal has not fired yet: one
+* signal for every call of an operation, so its deadline cancels them all at
+* once. With a timer per call, one call's could fire first, free its slot,
+* and start a key queued behind it whose own timer had not fired yet.
+*/
+function operationSignal(operation) {
+	if (operation === void 0) return void 0;
+	checkOperation(operation);
+	let signal = signals.get(operation);
+	if (signal === void 0) {
+		signal = AbortSignal.any([operation.signal, AbortSignal.timeout(Math.max(0, operation.deadline - Date.now()))]);
+		signals.set(operation, signal);
+	}
+	return signal;
+}
+/** Credentials can finish later, but must never send a request after cancellation. */
+function cancellable(work, signal) {
+	if (signal === void 0) return work;
+	return new Promise((resolve, reject) => {
+		const abort = () => {
+			signal.removeEventListener("abort", abort);
+			reject(new KekCancelledError());
+		};
+		if (signal.aborted) abort();
+		else signal.addEventListener("abort", abort, { once: true });
+		work.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+	});
+}
+function delay(ms, signal) {
+	return new Promise((resolve, reject) => {
+		const abort = () => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", abort);
+			reject(new KekCancelledError());
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", abort);
+			resolve();
+		}, ms);
+		if (signal?.aborted) abort();
+		else signal?.addEventListener("abort", abort, { once: true });
+	});
+}
+//#endregion
+//#region src/kek/local.ts
+const IV_BYTES = 12;
+const KEK_BYTES = 32;
+/**
+* A KEK held in local process memory, loaded from configuration.
+*
+* This is the local-development implementation of `KekProvider`. It is a
+* different implementation of the same interface, not a branch that skips
+* wrapping: the envelope format, the context binding and the failure modes are
+* identical to what a remote KMS-backed provider will produce.
+*/
+var LocalKekProvider = class LocalKekProvider {
+	provider = "local";
+	keyId;
+	keyVersion;
+	#kek;
+	constructor(kek, keyId, keyVersion = "1") {
+		if (kek.length !== KEK_BYTES) throw new Error(`local KEK must be ${KEK_BYTES} bytes, got ${kek.length}`);
+		this.#kek = kek;
+		this.keyId = keyId;
+		this.keyVersion = keyVersion;
+	}
+	/** Build a provider from a base64-encoded 32-byte key, e.g. from an env var. */
+	static fromBase64(encoded, keyId, keyVersion = "1") {
+		return new LocalKekProvider(Buffer.from(encoded, "base64"), keyId, keyVersion);
+	}
+	/** Generate a fresh random KEK. Used by tests and by the dev seed script. */
+	static generate(keyId, keyVersion = "1") {
+		return new LocalKekProvider(randomBytes(KEK_BYTES), keyId, keyVersion);
+	}
+	/**
+	* AAD for the wrap operation.
+	*
+	* Binds the wrapped DEK both to the secret it belongs to and to the KEK
+	* identity that produced it, so a wrapped DEK cannot be replayed against a
+	* row claiming a different KEK.
+	*/
+	#wrapAad(ctx) {
+		return Buffer.concat([encodeAad(ctx), Buffer.from(`|${this.provider}|${this.keyId}|${this.keyVersion}`, "utf8")]);
+	}
+	async wrap(dek, ctx, operation) {
+		checkOperation(operation);
+		if (dek.length !== 32) throw new Error(`DEK must be 32 bytes, got ${dek.length}`);
+		const iv = randomBytes(IV_BYTES);
+		const cipher = createCipheriv("aes-256-gcm", this.#kek, iv);
+		cipher.setAAD(this.#wrapAad(ctx));
+		const body = Buffer.concat([cipher.update(dek), cipher.final()]);
+		return {
+			kekProvider: this.provider,
+			kekId: this.keyId,
+			kekVersion: this.keyVersion,
+			bytes: Buffer.concat([
+				iv,
+				cipher.getAuthTag(),
+				body
+			])
+		};
+	}
+	async unwrap(wrapped, ctx, operation) {
+		checkOperation(operation);
+		if (wrapped.kekProvider !== this.provider || wrapped.kekId !== this.keyId) throw new KekBadClaimError(`wrapped DEK is for ${wrapped.kekProvider}:${wrapped.kekId}, not ${this.provider}:${this.keyId}`);
+		if (wrapped.bytes.length !== 60) throw new KekBadClaimError("wrapped DEK has the wrong length");
+		const iv = wrapped.bytes.subarray(0, IV_BYTES);
+		const tag = wrapped.bytes.subarray(IV_BYTES, 28);
+		const body = wrapped.bytes.subarray(28);
+		const decipher = createDecipheriv("aes-256-gcm", this.#kek, iv);
+		decipher.setAAD(this.#wrapAad(ctx));
+		decipher.setAuthTag(tag);
+		let dek;
+		const partial = decipher.update(body);
+		try {
+			dek = Buffer.concat([partial, decipher.final()]);
+		} catch {
+			throw new KekBadClaimError("wrapped DEK does not open under this context");
+		} finally {
+			partial.fill(0);
+		}
+		if (dek.length !== 32) {
+			dek.fill(0);
+			throw new KekBadClaimError("unwrapped DEK has the wrong length");
+		}
+		return dek;
+	}
+};
+/** Constant-time buffer comparison, for tests and callers that need it. */
+function equalBytes(a, b) {
+	return a.length === b.length && timingSafeEqual(a, b);
+}
+//#endregion
+//#region src/kek/registry.ts
+function refOf(provider, keyId) {
+	return `${provider}:${keyId}`;
+}
+/**
+* A set of active KEKs, one of which is primary.
+*
+* New secret versions are always wrapped under the primary. Old versions keep
+* unwrapping under whichever KEK produced them, looked up by the provider and
+* key id stored on their own row. Key rotation and migrating from the local
+* provider to a KMS-backed one are therefore the same operation: add a new KEK,
+* make it primary, leave the old one readable until nothing references it.
+*/
+var KekRegistry = class {
+	#byRef = /* @__PURE__ */ new Map();
+	#primary;
+	constructor(primary, additional = []) {
+		this.#primary = primary;
+		for (const provider of [primary, ...additional]) {
+			const ref = refOf(provider.provider, provider.keyId);
+			if (this.#byRef.has(ref)) throw new Error(`duplicate KEK in registry: ${ref}`);
+			this.#byRef.set(ref, provider);
+		}
+	}
+	get primary() {
+		return this.#primary;
+	}
+	/** Every KEK, the primary first. */
+	get all() {
+		return [...this.#byRef.values()];
+	}
+	/** The KEK a wrapped key names, or undefined when none is configured. */
+	providerOf(wrapped) {
+		return this.#byRef.get(refOf(wrapped.kekProvider, wrapped.kekId));
+	}
+	/** Wrap under the primary KEK. Used for every new secret version. */
+	wrap(dek, ctx, operation) {
+		return this.#primary.wrap(dek, ctx, operation);
+	}
+	/** Unwrap under whichever KEK the row says produced it. */
+	unwrap(wrapped, ctx, operation) {
+		const ref = refOf(wrapped.kekProvider, wrapped.kekId);
+		const provider = this.#byRef.get(ref);
+		if (!provider) throw new Error(`no KEK configured for ${ref}; cannot unwrap`);
+		return provider.unwrap(wrapped, ctx, operation);
+	}
+};
+//#endregion
+//#region src/kek/sigv4.ts
+/**
+* Every header a request signed with AWS Signature Version 4 sends: those
+* given, `host`, `x-amz-date`, the session token if any, and
+* `authorization`, which signs all of them and the body. The path is used as
+* it is, which is right for the only one KMS has, `/`.
+*
+* https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html
+*/
+function signV4(input) {
+	const stamp = input.date.toISOString().replace(/[-:]|\.\d{3}/g, "");
+	const day = stamp.slice(0, 8);
+	const headers = {
+		host: input.url.host,
+		"x-amz-date": stamp
+	};
+	for (const [name, value] of Object.entries(input.headers)) headers[name.toLowerCase()] = value;
+	if (input.credentials.sessionToken) headers["x-amz-security-token"] = input.credentials.sessionToken;
+	const names = Object.keys(headers).sort();
+	const signed = names.join(";");
+	const request = [
+		input.method,
+		input.url.pathname,
+		canonicalQuery(input.url.searchParams),
+		...names.map((name) => `${name}:${headers[name].trim().replace(/\s+/g, " ")}`),
+		"",
+		signed,
+		sha256(input.body)
+	].join("\n");
+	const scope = `${day}/${input.region}/${input.service}/aws4_request`;
+	const toSign = [
+		"AWS4-HMAC-SHA256",
+		stamp,
+		scope,
+		sha256(request)
+	].join("\n");
+	let key = hmac(`AWS4${input.credentials.secretAccessKey}`, day);
+	for (const part of [
+		input.region,
+		input.service,
+		"aws4_request"
+	]) key = hmac(key, part);
+	const signature = createHmac("sha256", key).update(toSign, "utf8").digest("hex");
+	return {
+		...headers,
+		authorization: `AWS4-HMAC-SHA256 Credential=${input.credentials.accessKeyId}/${scope}, SignedHeaders=${signed}, Signature=${signature}`
+	};
+}
+function canonicalQuery(params) {
+	return [...params].map(([name, value]) => [encode(name), encode(value)]).sort(([a, x], [b, y]) => a < b ? -1 : a > b ? 1 : x < y ? -1 : x > y ? 1 : 0).map(([name, value]) => `${name}=${value}`).join("&");
+}
+/** RFC 3986: everything but letters, digits and `-._~` percent-encoded. */
+function encode(text) {
+	return encodeURIComponent(text).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function sha256(text) {
+	return createHash("sha256").update(text, "utf8").digest("hex");
+}
+function hmac(key, text) {
+	return createHmac("sha256", key).update(text, "utf8").digest();
+}
+//#endregion
+//#region src/kek/aws-kms.ts
+const KEY_ARN = /^arn:(aws|aws-cn|aws-us-gov):kms:([a-z0-9-]+):\d{12}:key\/[A-Za-z0-9-]{1,128}$/;
+const ATTEMPTS = 3;
+const TIMEOUT_MS = 5e3;
+/** Calls in flight at once. A Worker opens at most six connections anyway. */
+const CONCURRENCY = 8;
+/** What KMS says when the ciphertext does not open under this key and context: a bad claim, not an outage. */
+const NOT_THIS_KEY = /* @__PURE__ */ new Set(["InvalidCiphertextException", "IncorrectKeyException"]);
+/** A KEK held in AWS KMS: it never leaves, and coffre asks KMS to wrap and unwrap each data key. */
+function awsKms(options) {
+	return new AwsKmsKekProvider(options);
+}
+/**
+* KMS's JSON API, `Encrypt` and `Decrypt`, signed with SigV4 and no SDK, so
+* it runs as is on Node and in a Worker. Each call sends the secret's UUIDs
+* as the encryption context, which KMS binds to the ciphertext and CloudTrail
+* logs with the call: every decrypt there names the secret it was for, in a
+* log neither coffre nor whoever runs it can edit.
+*/
+var AwsKmsKekProvider = class {
+	provider = "aws-kms";
+	keyId;
+	/** KMS keeps its own versions inside each ciphertext, and rotates the key material under the same ARN. */
+	keyVersion = "1";
+	#region;
+	#url;
+	#credentials;
+	#fetch;
+	#slots = new Slots(CONCURRENCY);
+	constructor(options) {
+		const match = KEY_ARN.exec(options.keyArn);
+		if (match === null) throw new Error(`the KMS key must be a key ARN, like arn:aws:kms:eu-west-3:123456789012:key/<id>, not an alias; got "${options.keyArn}"`);
+		const [, partition, region] = match;
+		this.keyId = options.keyArn;
+		this.#region = region;
+		this.#url = new URL(`https://kms.${region}.amazonaws.com${partition === "aws-cn" ? ".cn" : ""}/`);
+		const { credentials } = options;
+		this.#credentials = typeof credentials === "function" ? credentials : async () => credentials;
+		this.#fetch = options.fetch ?? ((input, init) => fetch(input, init));
+	}
+	async wrap(dek, ctx, operation) {
+		if (dek.length !== 32) throw new Error(`DEK must be 32 bytes, got ${dek.length}`);
+		const { CiphertextBlob } = await this.#call("Encrypt", {
+			KeyId: this.keyId,
+			Plaintext: base64(dek),
+			EncryptionContext: encryptionContext(ctx)
+		}, operation);
+		return {
+			kekProvider: this.provider,
+			kekId: this.keyId,
+			kekVersion: this.keyVersion,
+			bytes: Buffer.from(CiphertextBlob, "base64")
+		};
+	}
+	async unwrap(wrapped, ctx, operation) {
+		if (wrapped.kekProvider !== this.provider || wrapped.kekId !== this.keyId) throw new KekBadClaimError(`wrapped DEK is for ${wrapped.kekProvider}:${wrapped.kekId}, not ${this.provider}:${this.keyId}`);
+		const { Plaintext, KeyId } = await this.#call("Decrypt", {
+			KeyId: this.keyId,
+			CiphertextBlob: base64(wrapped.bytes),
+			EncryptionContext: encryptionContext(ctx)
+		}, operation);
+		if (KeyId !== this.keyId) throw new KekUnavailableError(`KMS decrypted under ${KeyId}, not ${this.keyId}`, true);
+		const dek = Buffer.from(Plaintext, "base64");
+		if (dek.length !== 32) {
+			dek.fill(0);
+			throw new KekUnavailableError("unwrapped DEK has the wrong length", true);
+		}
+		return dek;
+	}
+	/**
+	* One KMS call, tried up to three times while KMS throttles, fails on its
+	* side or does not answer. Every failure but a ciphertext that does not
+	* open is a `KekUnavailableError`, retried or not: a key KMS will not use
+	* or credentials it refuses say nothing about the claim either.
+	*/
+	async #call(action, request, operation) {
+		const body = JSON.stringify(request);
+		const signal = operationSignal(operation);
+		return this.#slots.run(async () => {
+			checkOperation(operation);
+			let credentials;
+			try {
+				credentials = await cancellable(this.#credentials(), signal);
+			} catch (error) {
+				if (error instanceof KekCancelledError) throw error;
+				throw new KekUnavailableError(`no AWS credentials for KMS: ${messageOf(error)}`);
+			}
+			let uncertain = false;
+			for (let attempt = 1;; attempt++) {
+				checkOperation(operation, uncertain);
+				if (signal?.aborted) throw new KekCancelledError(uncertain);
+				const answer = await this.#send(action, body, credentials, signal, operation);
+				if ("data" in answer) return answer.data;
+				uncertain ||= answer.uncertain;
+				checkOperation(operation, uncertain);
+				if (signal?.aborted) throw new KekCancelledError(uncertain);
+				if (NOT_THIS_KEY.has(answer.type)) {
+					if (uncertain) throw new KekUnavailableError(`KMS ${action}: ${answer.type} after an unanswered request`, true);
+					throw new KekBadClaimError(`KMS ${action}: ${answer.type}`);
+				}
+				if (!answer.retry || attempt === ATTEMPTS) throw new KekUnavailableError(`KMS ${action} failed${attempt > 1 ? ` ${attempt} times` : ""}: ${answer.failure}`, uncertain);
+				try {
+					await delay(100 * 4 ** (attempt - 1) * (1 + Math.random()), signal);
+				} catch (error) {
+					if (error instanceof KekCancelledError) throw new KekCancelledError(uncertain);
+					throw error;
+				}
+			}
+		}, signal);
+	}
+	async #send(action, body, credentials, signal, operation) {
+		const headers = signV4({
+			method: "POST",
+			url: this.#url,
+			headers: {
+				"content-type": "application/x-amz-json-1.1",
+				"x-amz-target": `TrentService.${action}`
+			},
+			body,
+			region: this.#region,
+			service: "kms",
+			credentials,
+			date: /* @__PURE__ */ new Date()
+		});
+		let response;
+		let text;
+		let sent = false;
+		try {
+			checkOperation(operation);
+			if (signal?.aborted) throw new KekCancelledError();
+			sent = true;
+			response = await this.#fetch(this.#url, {
+				method: "POST",
+				headers,
+				body,
+				signal: AbortSignal.any([AbortSignal.timeout(TIMEOUT_MS), ...signal === void 0 ? [] : [signal]])
+			});
+			text = await response.text();
+		} catch (error) {
+			return {
+				type: "network",
+				failure: messageOf(error),
+				retry: sent,
+				uncertain: sent
+			};
+		}
+		const parsed = parse(text);
+		if (response.ok) {
+			if (parsed !== null && (action === "Encrypt" ? typeof parsed.CiphertextBlob === "string" : typeof parsed.Plaintext === "string")) return { data: parsed };
+			return {
+				type: "malformed",
+				failure: `KMS answered ${response.status} without a result`,
+				retry: true,
+				uncertain: true
+			};
+		}
+		const type = (response.headers.get("x-amzn-errortype") ?? (typeof parsed?.__type === "string" ? parsed.__type : "")).split(":")[0].split("#").pop() || `HTTP ${response.status}`;
+		const message = parsed?.message ?? parsed?.Message;
+		return {
+			type,
+			failure: `${type}${typeof message === "string" ? `, ${message}` : ""}`,
+			uncertain: false,
+			retry: response.status >= 500 || response.status === 429 || type === "ThrottlingException"
+		};
+	}
+};
+/**
+* The secret's UUIDs, as KMS binds them to the ciphertext and CloudTrail
+* shows them. Checked first, so a malformed one never reaches KMS.
+*/
+function encryptionContext(ctx) {
+	checkContext(ctx);
+	return {
+		"coffre:project": ctx.projectId,
+		"coffre:environment": ctx.environmentId,
+		"coffre:secret": ctx.secretId
+	};
+}
+/**
+* Bytes as base64. Through `Buffer.from`, a view of the same memory, because
+* Workers' types declare their own `Buffer` and a bare one loses its
+* `toString(encoding)` to them.
+*/
+function base64(bytes) {
+	return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64");
+}
+function parse(text) {
+	try {
+		const value = JSON.parse(text);
+		return typeof value === "object" && value !== null ? value : null;
+	} catch {
+		return null;
+	}
+}
+function messageOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/** At most `n` calls at once; the rest wait their turn. */
+var Slots = class {
+	#free;
+	#waiting = [];
+	constructor(n) {
+		this.#free = n;
+	}
+	async run(work, signal) {
+		if (signal?.aborted) throw new KekCancelledError();
+		if (this.#free > 0) this.#free--;
+		else await new Promise((resolve, reject) => {
+			const waiting = {
+				start: () => {
+					signal?.removeEventListener("abort", waiting.cancel);
+					resolve();
+				},
+				cancel: () => {
+					const index = this.#waiting.indexOf(waiting);
+					if (index >= 0) this.#waiting.splice(index, 1);
+					signal?.removeEventListener("abort", waiting.cancel);
+					reject(new KekCancelledError());
+				}
+			};
+			this.#waiting.push(waiting);
+			signal?.addEventListener("abort", waiting.cancel, { once: true });
+		});
+		try {
+			if (signal?.aborted) throw new KekCancelledError();
+			return await work();
+		} finally {
+			const next = this.#waiting.shift();
+			if (next) next.start();
+			else this.#free++;
+		}
+	}
+};
+//#endregion
+export { AwsKmsKekProvider, DEK_BYTES, KekBadClaimError, KekCancelledError, KekRegistry, KekUnavailableError, LocalKekProvider, awsKms, equalBytes };

package/dist/registry-C0NGpxcc.d.ts

@@ -0,0 +1,126 @@
+//#region src/context.d.ts
+/**
+ * The binding context for a secret's ciphertext.
+ *
+ * This is the AES-GCM additional authenticated data (AAD). It ties a ciphertext
+ * to exactly one (project, environment, secret) triple, so a ciphertext lifted
+ * out of the `dev` environment row and dropped into the `prod` row fails to
+ * decrypt rather than silently succeeding.
+ *
+ * These are immutable UUIDs, never names. Binding to `project/environment/key`
+ * names would mean that renaming an environment or a secret key makes every
+ * existing ciphertext permanently undecryptable.
+ */
+type SecretContext = {
+  projectId: string;
+  environmentId: string;
+  secretId: string;
+};
+/**
+ * Version prefix for the AAD encoding. If the encoding ever changes, this
+ * changes with it, and old ciphertexts keep decrypting under the old rule.
+ */
+declare const AAD_VERSION = "coffre.aad.v1";
+/** Throw unless every field is a lowercase UUID. */
+declare function checkContext(ctx: SecretContext): void;
+/**
+ * Encode a context into AAD bytes.
+ *
+ * Every field is validated as a UUID first, which is what makes joining with
+ * `|` unambiguous: a UUID cannot contain the separator, so no two distinct
+ * contexts can encode to the same bytes.
+ */
+declare function encodeAad(ctx: SecretContext): Buffer;
+//#endregion
+//#region src/kek/types.d.ts
+/**
+ * A data encryption key wrapped by a key encryption key.
+ *
+ * The provider metadata travels with every wrapped DEK and is stored per row,
+ * never as a single global key id. Rotation and provider migration are then the
+ * same code path: write new rows under the new KEK, keep unwrapping old rows
+ * under the old one.
+ */
+type WrappedDek = {
+  kekProvider: string;
+  kekId: string;
+  kekVersion: string;
+  bytes: Buffer;
+};
+/** One deadline for a batch. Providers must abort and settle their work when its signal fires. */
+type KeyOperation = {
+  deadline: number;
+  signal: AbortSignal;
+};
+/**
+ * The only interface any key encryption key backend must satisfy.
+ *
+ * Two methods. We generate the DEK ourselves with a CSPRNG and use the backend
+ * purely to wrap it, rather than depending on a provider `GenerateDataKey`
+ * primitive -- GCP KMS has no such call, and staying off it is what keeps the
+ * exit plan cheap.
+ *
+ * `ctx` is passed through to the provider deliberately. A remote KEK service
+ * cannot otherwise record *which* secret an unwrap was for, only that some
+ * opaque DEK was unwrapped. AWS KMS logs it in CloudTrail as the encryption
+ * context (`aws-kms.ts`). Scaleway's Audit Trail does not log Key Manager
+ * Decrypt at all, which is why AWS came first.
+ *
+ * `unwrap` throws `KekUnavailableError` when the service cannot answer, and
+ * `KekBadClaimError` when the wrapped DEK does not open under `ctx`. Other
+ * errors are unexpected faults; the vault records them and fails the call.
+ */
+interface KekProvider {
+  readonly provider: string;
+  readonly keyId: string;
+  readonly keyVersion: string;
+  wrap(dek: Buffer, ctx: SecretContext, operation?: KeyOperation): Promise<WrappedDek>;
+  unwrap(wrapped: WrappedDek, ctx: SecretContext, operation?: KeyOperation): Promise<Buffer>;
+}
+/** Length of the data encryption keys we generate, in bytes (AES-256). */
+declare const DEK_BYTES = 32;
+/**
+ * The key service could not answer: it is down, throttling past the
+ * retries, or refusing coffre's own credentials. Nothing is known about the
+ * wrapped key, so the vault fails the call instead of refusing it.
+ */
+declare class KekUnavailableError extends Error {
+  readonly name: string;
+  readonly uncertain: boolean;
+  constructor(message: string, uncertain?: boolean);
+}
+/** No more work may start. A request already sent may have been accepted by KMS. */
+declare class KekCancelledError extends KekUnavailableError {
+  readonly name = "KekCancelledError";
+  constructor(uncertain?: boolean);
+}
+/** The ciphertext does not open under the claimed key and context. */
+declare class KekBadClaimError extends Error {
+  readonly name = "KekBadClaimError";
+}
+//#endregion
+//#region src/kek/registry.d.ts
+/**
+ * A set of active KEKs, one of which is primary.
+ *
+ * New secret versions are always wrapped under the primary. Old versions keep
+ * unwrapping under whichever KEK produced them, looked up by the provider and
+ * key id stored on their own row. Key rotation and migrating from the local
+ * provider to a KMS-backed one are therefore the same operation: add a new KEK,
+ * make it primary, leave the old one readable until nothing references it.
+ */
+declare class KekRegistry {
+  #private;
+  constructor(primary: KekProvider, additional?: readonly KekProvider[]);
+  get primary(): KekProvider;
+  /** Every KEK, the primary first. */
+  get all(): KekProvider[];
+  /** The KEK a wrapped key names, or undefined when none is configured. */
+  providerOf(wrapped: Pick<WrappedDek, 'kekProvider' | 'kekId'>): KekProvider | undefined;
+  /** Wrap under the primary KEK. Used for every new secret version. */
+  wrap(dek: Buffer, ctx: SecretContext, operation?: KeyOperation): Promise<WrappedDek>;
+  /** Unwrap under whichever KEK the row says produced it. */
+  unwrap(wrapped: WrappedDek, ctx: SecretContext, operation?: KeyOperation): Promise<Buffer>;
+}
+//#endregion
+export { KekProvider as a, WrappedDek as c, checkContext as d, encodeAad as f, KekCancelledError as i, AAD_VERSION as l, DEK_BYTES as n, KekUnavailableError as o, KekBadClaimError as r, KeyOperation as s, KekRegistry as t, SecretContext as u };