@usecontextlayer/secret-cipher 0.5.23

package/dist/index.d.mts

@@ -0,0 +1,53 @@
+//#region lib/cipher.d.ts
+declare const cipherKeyBrand: unique symbol;
+/**
+ * A validated 32-byte (256-bit) master key that wraps each value's per-value
+ * content key. Obtain one only via `parseKey` — the brand makes an unvalidated
+ * byte array fail to type-check as a key.
+ */
+type CipherKey = Uint8Array & {
+  readonly [cipherKeyBrand]: true;
+};
+/**
+ * Parse a 64-hex-char (32-byte) master key. Throws on any other shape — the key
+ * is validated here so `encrypt`/`decrypt` can trust it.
+ */
+declare function parseKey(hex: string): CipherKey;
+/**
+ * True iff `hex` is a valid master-key string (64 hex chars) — the exact shape
+ * `parseKey` accepts. Lets an env boundary validate a key without materializing
+ * one, so the 64-hex contract lives in a single place.
+ */
+declare function isKeyHex(hex: string): boolean;
+/**
+ * A stable, one-way fingerprint of the master key, stamped as the JWE `kid`. It
+ * identifies which key encrypted a value (for a future keychain) without
+ * revealing the key — SHA-256 of the key bytes, truncated.
+ */
+declare function keyId(key: CipherKey): string;
+/**
+ * Envelope-encrypt a value: a fresh random content key encrypts the value
+ * (A256GCM); the master key wraps that content key (A256GCMKW). Returns a
+ * compact JWE (RFC 7516) — self-describing, single string, `kid` in the header.
+ * Keep this wrapper async so validation failures reject through the returned
+ * Promise instead of throwing before a caller can attach a rejection handler.
+ */
+declare function encrypt(plaintext: string, key: CipherKey): Promise<string>;
+/**
+ * Decrypt a compact JWE produced by `encrypt`. Throws on any failure (tampered
+ * ciphertext, wrong key, malformed input) — never returns plaintext on failure.
+ * The alg/enc allowlist pins decryption to exactly what `encrypt` emits, so a
+ * forged JWE using a different scheme (e.g. `alg: "dir"`) is rejected, not
+ * silently unwrapped — defense-in-depth on the crypto boundary.
+ */
+declare function decrypt(jwe: string, key: CipherKey): Promise<string>;
+/**
+ * True iff `value` is a compact JWE in this library's exact envelope format:
+ * five segments with a protected header of `alg: A256GCMKW` + `enc: A256GCM`. A
+ * format marker, NOT an authenticator — it never touches the key or the GCM tag,
+ * so it proves shape, not authenticity. Backfill-only: lets a migration skip
+ * already-encrypted rows. The read path never calls this; it decrypts-or-throws.
+ */
+declare function isSecretCiphertext(value: string): boolean;
+//#endregion
+export { CipherKey, decrypt, encrypt, isKeyHex, isSecretCiphertext, keyId, parseKey };

package/dist/index.mjs

@@ -0,0 +1,81 @@
+import { createHash } from "node:crypto";
+import { CompactEncrypt, compactDecrypt, decodeProtectedHeader } from "jose";
+
+//#region lib/cipher.ts
+const ALG = "A256GCMKW";
+const ENC = "A256GCM";
+const KEY_HEX_PATTERN = /^[0-9a-f]{64}$/i;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: true });
+/**
+* Parse a 64-hex-char (32-byte) master key. Throws on any other shape — the key
+* is validated here so `encrypt`/`decrypt` can trust it.
+*/
+function parseKey(hex) {
+	if (!isKeyHex(hex)) throw new Error("secret-cipher key must be 64 hex chars (32 bytes)");
+	return Uint8Array.from(Buffer.from(hex, "hex"));
+}
+/**
+* True iff `hex` is a valid master-key string (64 hex chars) — the exact shape
+* `parseKey` accepts. Lets an env boundary validate a key without materializing
+* one, so the 64-hex contract lives in a single place.
+*/
+function isKeyHex(hex) {
+	return KEY_HEX_PATTERN.test(hex);
+}
+/**
+* A stable, one-way fingerprint of the master key, stamped as the JWE `kid`. It
+* identifies which key encrypted a value (for a future keychain) without
+* revealing the key — SHA-256 of the key bytes, truncated.
+*/
+function keyId(key) {
+	return createHash("sha256").update(key).digest("hex").slice(0, 16);
+}
+/**
+* Envelope-encrypt a value: a fresh random content key encrypts the value
+* (A256GCM); the master key wraps that content key (A256GCMKW). Returns a
+* compact JWE (RFC 7516) — self-describing, single string, `kid` in the header.
+* Keep this wrapper async so validation failures reject through the returned
+* Promise instead of throwing before a caller can attach a rejection handler.
+*/
+async function encrypt(plaintext, key) {
+	if (!plaintext.isWellFormed()) throw new Error("secret-cipher: refusing to encrypt a non-well-formed string (lone surrogate) — decrypt could not round-trip it");
+	return new CompactEncrypt(encoder.encode(plaintext)).setProtectedHeader({
+		alg: ALG,
+		enc: ENC,
+		kid: keyId(key)
+	}).encrypt(key);
+}
+/**
+* Decrypt a compact JWE produced by `encrypt`. Throws on any failure (tampered
+* ciphertext, wrong key, malformed input) — never returns plaintext on failure.
+* The alg/enc allowlist pins decryption to exactly what `encrypt` emits, so a
+* forged JWE using a different scheme (e.g. `alg: "dir"`) is rejected, not
+* silently unwrapped — defense-in-depth on the crypto boundary.
+*/
+async function decrypt(jwe, key) {
+	const { plaintext } = await compactDecrypt(jwe, key, {
+		contentEncryptionAlgorithms: [ENC],
+		keyManagementAlgorithms: [ALG]
+	});
+	return decoder.decode(plaintext);
+}
+/**
+* True iff `value` is a compact JWE in this library's exact envelope format:
+* five segments with a protected header of `alg: A256GCMKW` + `enc: A256GCM`. A
+* format marker, NOT an authenticator — it never touches the key or the GCM tag,
+* so it proves shape, not authenticity. Backfill-only: lets a migration skip
+* already-encrypted rows. The read path never calls this; it decrypts-or-throws.
+*/
+function isSecretCiphertext(value) {
+	try {
+		if (value.split(".").length !== 5) return false;
+		const header = decodeProtectedHeader(value);
+		return header.alg === ALG && header.enc === ENC;
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+export { decrypt, encrypt, isKeyHex, isSecretCiphertext, keyId, parseKey };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "dependencies": {
+    "jose": "^6.2.3"
+  },
+  "devDependencies": {
+    "fast-check": "^4.8.0",
+    "vitest": "^4.1.10"
+  },
+  "exports": {
+    ".": {
+      "default": "./dist/index.mjs",
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.mjs",
+  "name": "@usecontextlayer/secret-cipher",
+  "private": false,
+  "type": "module",
+  "types": "./dist/index.d.mts",
+  "version": "0.5.23",
+  "scripts": {
+    "build": "npx tsdown",
+    "clean": "rm -rf dist dist-types *.tsbuildinfo",
+    "dev:watch": "npx tsdown --watch",
+    "test": "npx vitest run --config vitest.config.ts",
+    "tsc": "npx tsc -b tsconfig.json"
+  }
+}