@coffre/core 0.0.0 → 0.1.0

package/dist/dotenv.js

@@ -0,0 +1,194 @@
+//#region src/dotenv.ts
+const KEY_RE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+function parseDotenv(input) {
+	const entries = [];
+	const problems = [];
+	const seen = /* @__PURE__ */ new Set();
+	const lines = input.split(/\r\n|\n|\r/);
+	for (let index = 0; index < lines.length; index++) {
+		const lineNumber = index + 1;
+		const trimmed = lines[index].trim();
+		if (trimmed === "" || trimmed.startsWith("#")) continue;
+		const withoutExport = trimmed.startsWith("export ") ? trimmed.slice(7).trim() : trimmed;
+		const equals = withoutExport.indexOf("=");
+		if (equals === -1) {
+			problems.push({
+				line: lineNumber,
+				text: trimmed,
+				reason: "no \"=\" on this line"
+			});
+			continue;
+		}
+		const key = withoutExport.slice(0, equals).trim();
+		if (!KEY_RE.test(key)) {
+			problems.push({
+				line: lineNumber,
+				text: key,
+				reason: "key must match ^[A-Za-z_][A-Za-z0-9_]*$"
+			});
+			continue;
+		}
+		let rest = withoutExport.slice(equals + 1).trim();
+		let value;
+		if (rest.startsWith("\"")) {
+			const closing = findClosingQuote(rest, "\"");
+			if (closing === -1) {
+				problems.push({
+					line: lineNumber,
+					text: key,
+					reason: "unterminated double quote (multi-line values are not supported)"
+				});
+				continue;
+			}
+			value = unescapeDoubleQuoted(rest.slice(1, closing));
+			if (trailingIsSignificant(rest.slice(closing + 1))) {
+				problems.push({
+					line: lineNumber,
+					text: key,
+					reason: "unexpected text after the closing quote"
+				});
+				continue;
+			}
+		} else if (rest.startsWith("'")) {
+			const closing = rest.indexOf("'", 1);
+			if (closing === -1) {
+				problems.push({
+					line: lineNumber,
+					text: key,
+					reason: "unterminated single quote (multi-line values are not supported)"
+				});
+				continue;
+			}
+			value = rest.slice(1, closing);
+			if (trailingIsSignificant(rest.slice(closing + 1))) {
+				problems.push({
+					line: lineNumber,
+					text: key,
+					reason: "unexpected text after the closing quote"
+				});
+				continue;
+			}
+		} else {
+			const comment = rest.indexOf(" #");
+			if (comment !== -1) rest = rest.slice(0, comment);
+			value = rest.trim();
+		}
+		if (value.includes("\0")) {
+			problems.push({
+				line: lineNumber,
+				text: key,
+				reason: "value contains a NUL byte, which cannot be passed in an environment"
+			});
+			continue;
+		}
+		if (seen.has(key)) {
+			problems.push({
+				line: lineNumber,
+				text: key,
+				reason: "duplicate key in this file"
+			});
+			continue;
+		}
+		seen.add(key);
+		entries.push({
+			key,
+			value,
+			line: lineNumber
+		});
+	}
+	return {
+		entries,
+		problems
+	};
+}
+/** True when what follows a closing quote is neither whitespace nor a comment. */
+function trailingIsSignificant(rest) {
+	const trimmed = rest.trim();
+	return trimmed !== "" && !trimmed.startsWith("#");
+}
+function findClosingQuote(text, quote) {
+	for (let index = 1; index < text.length; index++) {
+		if (text[index] === "\\") {
+			index++;
+			continue;
+		}
+		if (text[index] === quote) return index;
+	}
+	return -1;
+}
+/**
+* Expand escapes inside a double-quoted value.
+*
+* Deliberately minimal: only the escapes that are necessary. `\n` and `\r`
+* because multi-line values (PEM keys) cannot otherwise be expressed on one
+* line, and `\\` `\"` `\'` because quoting needs them.
+*
+* EVERYTHING ELSE IS PRESERVED VERBATIM, backslash included. The obvious
+* implementation -- returning the character and dropping the backslash for
+* unknown escapes -- silently mangles credentials: `"C:\path\to\file"` came
+* out as `C:path<TAB>ofile`, and `"\d+\w"` as `d+w`. A secrets store that
+* quietly rewrites what you gave it is worse than one that refuses.
+*
+* A value that should contain no interpretation at all belongs in single
+* quotes, which are literal.
+*/
+function unescapeDoubleQuoted(text) {
+	return text.replace(/\\(.)/g, (match, character) => {
+		switch (character) {
+			case "n": return "\n";
+			case "r": return "\r";
+			case "\\":
+			case "\"":
+			case "'": return character;
+			default: return match;
+		}
+	});
+}
+/** Values that read the same unquoted: no spaces, quotes, `#`, `$` or backslashes. */
+const PLAIN_VALUE = /^[A-Za-z0-9_./:@+,=%?-]*$/;
+/**
+* Write entries as a .env file that `parseDotenv` reads back exactly.
+*
+* Plain values stay bare; anything else is single-quoted, which is literal;
+* values holding a quote or a line break are double-quoted with the four
+* escapes the parser knows (`\\`, `\"`, `\n`, `\r`).
+*/
+function formatDotenv(entries) {
+	let out = "";
+	for (const [key, value] of entries) {
+		assertWritable(key, value);
+		out += `${key}=${quoteDotenv(value)}\n`;
+	}
+	return out;
+}
+function assertWritable(key, value) {
+	if (!KEY_RE.test(key)) throw new Error(`${JSON.stringify(key)} is not a valid variable name`);
+	if (value.includes("\0")) throw new Error(`${key} contains a NUL byte`);
+}
+function quoteDotenv(value) {
+	if (PLAIN_VALUE.test(value)) return value;
+	if (!/['\n\r]/.test(value)) return `'${value}'`;
+	return `"${value.replace(/[\\"\n\r]/g, (character) => {
+		switch (character) {
+			case "\n": return "\\n";
+			case "\r": return "\\r";
+			default: return `\\${character}`;
+		}
+	})}"`;
+}
+/**
+* Write entries as POSIX shell `export` statements, for
+* `eval "$(coffre export … --format shell)"`. Single quotes are the only
+* shell quoting with no expansion inside; a single quote itself is written
+* as `'\''`.
+*/
+function formatShellExports(entries) {
+	let out = "";
+	for (const [key, value] of entries) {
+		assertWritable(key, value);
+		out += `export ${key}='${value.replaceAll("'", "'\\''")}'\n`;
+	}
+	return out;
+}
+//#endregion
+export { formatDotenv, formatShellExports, parseDotenv };

package/dist/envelope.d.ts

@@ -0,0 +1,50 @@
+import { d as checkContext, f as encodeAad, l as AAD_VERSION, t as KekRegistry, u as SecretContext } from "./registry-C0NGpxcc.js";
+//#region src/envelope.d.ts
+/**
+ * Current envelope format version. Stored on every row so the format can change
+ * without a bulk re-encryption.
+ */
+export declare const ENVELOPE_VERSION = 1;
+/**
+ * One sealed secret value, exactly as it is stored in `secret_versions`.
+ *
+ * The AAD binding is implemented here, in our own envelope layer, rather than
+ * via a provider "encryption context" feature. That keeps the stored format
+ * portable: moving to a different KMS changes only how `wrappedDek` is produced.
+ */
+export type Envelope = {
+  envelopeVersion: number;
+  kekProvider: string;
+  kekId: string;
+  kekVersion: string;
+  wrappedDek: Buffer;
+  iv: Buffer;
+  authTag: Buffer;
+  ciphertext: Buffer;
+};
+/** The part of an envelope the data key produces: everything but the wrapped key. */
+export type Sealed = Pick<Envelope, 'envelopeVersion' | 'iv' | 'authTag' | 'ciphertext'>;
+/** A fresh data key. One per version, so no key ever encrypts two values. */
+export declare function freshDek(): Buffer;
+/**
+ * Encrypt a secret value under `dek`, bound to `ctx`. Whoever holds the key
+ * encryption key wraps `dek` separately: the vault, in coffre.
+ */
+export declare function encrypt(plaintext: Buffer, ctx: SecretContext, dek: Buffer): Sealed;
+/**
+ * Decrypt with an unwrapped `dek`. Throws if the envelope was sealed for a
+ * different project, environment or secret than `ctx` describes, because
+ * the AAD will not match. This is the property that makes relocating a
+ * ciphertext across environments fail closed.
+ */
+export declare function decrypt(envelope: Sealed, ctx: SecretContext, dek: Buffer): Buffer;
+/**
+ * Encrypt a secret value under a fresh DEK, and wrap that DEK under the
+ * registry's primary KEK: `encrypt` and the wrap in one, where both halves
+ * are in one place.
+ */
+export declare function seal(plaintext: Buffer, ctx: SecretContext, keks: KekRegistry): Promise<Envelope>;
+/** Unwrap the envelope's DEK under the registry and decrypt: `decrypt` and the unwrap in one. */
+export declare function open(envelope: Envelope, ctx: SecretContext, keks: KekRegistry): Promise<Buffer>;
+//#endregion
+export { AAD_VERSION, SecretContext, checkContext, encodeAad };

package/dist/envelope.js

@@ -0,0 +1,83 @@
+import { a as AAD_VERSION, o as checkContext, s as encodeAad } from "./types-Mi7-Tzj9.js";
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+//#region src/envelope.ts
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+/**
+* Current envelope format version. Stored on every row so the format can change
+* without a bulk re-encryption.
+*/
+const ENVELOPE_VERSION = 1;
+/** A fresh data key. One per version, so no key ever encrypts two values. */
+function freshDek() {
+	return randomBytes(32);
+}
+/**
+* Encrypt a secret value under `dek`, bound to `ctx`. Whoever holds the key
+* encryption key wraps `dek` separately: the vault, in coffre.
+*/
+function encrypt(plaintext, ctx, dek) {
+	const iv = randomBytes(IV_BYTES);
+	const cipher = createCipheriv("aes-256-gcm", dek, iv);
+	cipher.setAAD(encodeAad(ctx));
+	const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+	return {
+		envelopeVersion: 1,
+		iv,
+		authTag: cipher.getAuthTag(),
+		ciphertext
+	};
+}
+/**
+* Decrypt with an unwrapped `dek`. Throws if the envelope was sealed for a
+* different project, environment or secret than `ctx` describes, because
+* the AAD will not match. This is the property that makes relocating a
+* ciphertext across environments fail closed.
+*/
+function decrypt(envelope, ctx, dek) {
+	if (envelope.envelopeVersion !== 1) throw new Error(`unsupported envelope version: ${envelope.envelopeVersion}`);
+	if (envelope.iv.length !== IV_BYTES) throw new Error("envelope IV has the wrong length");
+	if (envelope.authTag.length !== TAG_BYTES) throw new Error("envelope auth tag has the wrong length");
+	const decipher = createDecipheriv("aes-256-gcm", dek, envelope.iv);
+	decipher.setAAD(encodeAad(ctx));
+	decipher.setAuthTag(envelope.authTag);
+	return Buffer.concat([decipher.update(envelope.ciphertext), decipher.final()]);
+}
+/**
+* Encrypt a secret value under a fresh DEK, and wrap that DEK under the
+* registry's primary KEK: `encrypt` and the wrap in one, where both halves
+* are in one place.
+*/
+async function seal(plaintext, ctx, keks) {
+	const dek = freshDek();
+	try {
+		const sealed = encrypt(plaintext, ctx, dek);
+		const wrapped = await keks.wrap(dek, ctx);
+		return {
+			...sealed,
+			kekProvider: wrapped.kekProvider,
+			kekId: wrapped.kekId,
+			kekVersion: wrapped.kekVersion,
+			wrappedDek: wrapped.bytes
+		};
+	} finally {
+		dek.fill(0);
+	}
+}
+/** Unwrap the envelope's DEK under the registry and decrypt: `decrypt` and the unwrap in one. */
+async function open(envelope, ctx, keks) {
+	if (envelope.envelopeVersion !== 1) throw new Error(`unsupported envelope version: ${envelope.envelopeVersion}`);
+	const dek = await keks.unwrap({
+		kekProvider: envelope.kekProvider,
+		kekId: envelope.kekId,
+		kekVersion: envelope.kekVersion,
+		bytes: envelope.wrappedDek
+	}, ctx);
+	try {
+		return decrypt(envelope, ctx, dek);
+	} finally {
+		dek.fill(0);
+	}
+}
+//#endregion
+export { AAD_VERSION, ENVELOPE_VERSION, checkContext, decrypt, encodeAad, encrypt, freshDek, open, seal };