feat(core): add salted one-use GCM key wrapping (#18)

Author: kauandotnet

.changeset/quiet-wrappers-simplify.md

@@ -0,0 +1,8 @@
+---
+"@nestm/crypto": minor
+---
+
+Derive a one-use AES-256-GCM wrapping key with HKDF-SHA256 and a fresh 256-bit salt for every new
+local key-ring data key while retaining read-only compatibility with legacy A256GCMKW envelopes.
+Version 2 removes the need for a durable global wrapper-invocation counter and keeps 128-bit
+authentication.

README.md

@@ -304,6 +304,13 @@ The `nmc1` format constrains registered ciphers to a 12-byte nonce so batch encr
 final four bytes for a collision-free operation counter. The cipher/provider contracts are extensible,
 but an algorithm needing a different nonce construction requires a future envelope version.
 
+`AesKeyRingProvider` derives a one-use AES-256-GCM wrapping key from the long-lived key, a fresh
+256-bit random salt, and domain-separated HKDF-SHA256 info bound to the key reference and wrapping
+context. The one-use key makes the format's fixed 96-bit GCM nonce safe without a durable invocation
+counter. New wrappers are 81 bytes (`version || salt || ciphertext || tag`), tagged version 2, and
+report `NESTM-A256GCM-HKDF-SHA256-SALT256-V2`; the 61-byte version 1 `A256GCMKW` wrappers written
+previously stay readable, so no stored key needs rewrapping.
+
 Wrapping-key rotation does not require immediately rewriting every value: keep old keys in the local
 ring as decrypt-only entries, or keep an old named provider in `allowedProviders`. Use `reencrypt()` to
 move one authenticated value to the current route, then retire old material only after verifying no

SECURITY.md

@@ -42,6 +42,13 @@ backup/restore policy, and deciding which data must be encrypted.
   versioned as `nmc1.<protected>.<wrappedKey>.<iv>.<ciphertext>.<tag>`.
 - Wrapped data keys use a configured local AES key-encryption-key ring, RSA-OAEP-SHA256, AWS KMS,
   Google Cloud KMS, or Azure Key Vault/Managed HSM.
+- The local AES key ring derives a one-use AES-256-GCM wrapping key with HKDF-SHA256 from the
+  long-lived key and a fresh 256-bit salt. Domain-separated derivation info binds the version, key
+  reference, and a length-framed digest of the wrapping context. Each one-use key encrypts exactly
+  one 32-byte data key with a fixed 96-bit IV and a 128-bit tag. Salt collision probability replaces
+  the durable global counter previously required to prove direct GCM nonce uniqueness. Envelopes
+  written before this construction remain readable under their `A256GCMKW` algorithm name and
+  version byte.
 - Plaintext data keys are held as `KeyObject` values as early as practical. Temporary byte buffers are
   zeroed best-effort, but JavaScript runtimes cannot guarantee erasure of every copy.
 - No persistent plaintext data-key cache is part of the design.

src/core/aes-key-ring.provider.ts

@@ -1,17 +1,37 @@
 import {
 	createCipheriv,
 	createDecipheriv,
+	createHash,
 	createSecretKey,
 	generateKeySync,
+	hkdfSync,
 	randomBytes,
+	type DecipherGCM,
 	type KeyObject,
 } from "node:crypto";
 import { authenticationFailed, CryptoError, throwIfAborted } from "./errors.js";
 import type { DataKeyContext, DataKeyProvider, GeneratedDataKey, WrappedDataKey } from "./types.js";
 
+/** Salt-derived, one-use AES-256-GCM key wrapping used for new local key-ring writes. */
+export const AES_GCM_HKDF_SHA256_KEY_WRAP = "NESTM-A256GCM-HKDF-SHA256-SALT256-V2";
+/** @deprecated Read-only compatibility for envelopes written before AES_GCM_HKDF_SHA256_KEY_WRAP. */
 export const AES_GCM_KEY_WRAP = "A256GCMKW";
-const WRAP_VERSION = 1;
-const WRAPPED_LENGTH = 1 + 12 + 32 + 16;
+
+const SALTED_WRAP_VERSION = 2;
+const SALT_BYTES = 32;
+const DATA_KEY_BYTES = 32;
+const TAG_BYTES = 16;
+const SALTED_WRAPPED_LENGTH = 1 + SALT_BYTES + DATA_KEY_BYTES + TAG_BYTES;
+const FIXED_WRAP_IV = new Uint8Array(12);
+const KEY_DERIVATION_INFO = "nestm:aes-key-ring:a256gcm-hkdf-sha256-salt256:v2\0";
+const KEY_REFERENCE_CONTEXT = "nestm:aes-key-ring:key-reference:v2\0";
+const WRAPPING_CONTEXT = "nestm:aes-key-ring:wrapping-context:v2\0";
+const WRAP_AUTHENTICATED_DATA = Buffer.concat([
+	Buffer.from("nestm:aes-key-ring:wrapped-data-key:v2\0", "utf8"),
+	Buffer.of(SALTED_WRAP_VERSION),
+]);
+const LEGACY_WRAP_VERSION = 1;
+const LEGACY_WRAPPED_LENGTH = 1 + 12 + 32 + 16;
 
 export interface AesKeyRingProviderOptions {
 	readonly activeKeyId: string;
@@ -42,6 +62,57 @@ function validateKeyId(keyId: string): void {
 	}
 }
 
+function framedDigest(domain: string, value: Uint8Array): Buffer {
+	const length = Buffer.alloc(8);
+	length.writeBigUInt64BE(BigInt(value.byteLength));
+	try {
+		return createHash("sha256").update(domain, "utf8").update(length).update(value).digest();
+	} finally {
+		length.fill(0);
+	}
+}
+
+function deriveOneUseWrappingKey(
+	kek: KeyObject,
+	salt: Uint8Array,
+	keyReference: string,
+	wrappingContext: Uint8Array,
+): Buffer {
+	const reference = Buffer.from(keyReference, "utf8");
+	const referenceDigest = framedDigest(KEY_REFERENCE_CONTEXT, reference);
+	const contextDigest = framedDigest(WRAPPING_CONTEXT, wrappingContext);
+	const info = Buffer.concat([
+		Buffer.from(KEY_DERIVATION_INFO, "utf8"),
+		Buffer.of(SALTED_WRAP_VERSION),
+		referenceDigest,
+		contextDigest,
+	]);
+	try {
+		return Buffer.from(hkdfSync("sha256", kek, salt, info, DATA_KEY_BYTES));
+	} finally {
+		reference.fill(0);
+		referenceDigest.fill(0);
+		contextDigest.fill(0);
+		info.fill(0);
+	}
+}
+
+function decryptDataKey(decipher: DecipherGCM, ciphertext: Uint8Array): KeyObject {
+	const first = decipher.update(ciphertext);
+	let last: Buffer | undefined;
+	let raw: Buffer | undefined;
+	try {
+		last = decipher.final();
+		raw = Buffer.concat([first, last]);
+		if (raw.byteLength !== DATA_KEY_BYTES) throw authenticationFailed();
+		return createSecretKey(raw);
+	} finally {
+		first.fill(0);
+		last?.fill(0);
+		raw?.fill(0);
+	}
+}
+
 export class AesKeyRingProvider implements DataKeyProvider {
 	readonly #activeKeyId: string;
 	readonly #keys: ReadonlyMap<string, KeyObject>;
@@ -63,69 +134,114 @@ export class AesKeyRingProvider implements DataKeyProvider {
 	async generateDataKey(context: DataKeyContext): Promise<GeneratedDataKey> {
 		throwIfAborted(context.signal);
 		const plaintextKey = generateKeySync("aes", { length: 256 });
-		const wrappedKey = this.#wrap(plaintextKey, this.#keys.get(this.#activeKeyId)!, context);
+		const wrappedKey = this.#wrap(
+			plaintextKey,
+			this.#keys.get(this.#activeKeyId)!,
+			this.#activeKeyId,
+			context,
+		);
 		throwIfAborted(context.signal);
 		return Object.freeze({
 			plaintextKey,
 			wrappedKey,
 			keyReference: this.#activeKeyId,
-			wrappingAlgorithm: AES_GCM_KEY_WRAP,
+			wrappingAlgorithm: AES_GCM_HKDF_SHA256_KEY_WRAP,
 		});
 	}
 
 	async unwrapDataKey(dataKey: WrappedDataKey, context: DataKeyContext): Promise<KeyObject> {
 		throwIfAborted(context.signal);
-		if (dataKey.wrappingAlgorithm !== AES_GCM_KEY_WRAP) {
+		if (
+			dataKey.wrappingAlgorithm !== AES_GCM_HKDF_SHA256_KEY_WRAP &&
+			dataKey.wrappingAlgorithm !== AES_GCM_KEY_WRAP
+		) {
 			throw new CryptoError("INVALID_KEY", "The wrapped-key algorithm is unsupported.");
 		}
 		const kek = this.#keys.get(dataKey.keyReference);
 		if (!kek) throw new CryptoError("KEY_NOT_FOUND", "The wrapping key was not found.");
-		if (
-			dataKey.wrappedKey.byteLength !== WRAPPED_LENGTH ||
-			dataKey.wrappedKey[0] !== WRAP_VERSION
-		) {
+		if (dataKey.wrappingAlgorithm === AES_GCM_HKDF_SHA256_KEY_WRAP) {
+			return this.#unwrapSalted(dataKey.wrappedKey, kek, dataKey.keyReference, context);
+		}
+		return this.#unwrapLegacy(dataKey.wrappedKey, kek, context);
+	}
+
+	#unwrapSalted(
+		wrappedKey: Uint8Array,
+		kek: KeyObject,
+		keyReference: string,
+		context: DataKeyContext,
+	): KeyObject {
+		if (wrappedKey.byteLength !== SALTED_WRAPPED_LENGTH || wrappedKey[0] !== SALTED_WRAP_VERSION) {
 			throw authenticationFailed();
 		}
+		const salt = wrappedKey.subarray(1, 1 + SALT_BYTES);
+		const ciphertext = wrappedKey.subarray(1 + SALT_BYTES, 1 + SALT_BYTES + DATA_KEY_BYTES);
+		const tag = wrappedKey.subarray(1 + SALT_BYTES + DATA_KEY_BYTES);
+		let wrappingKey: Buffer | undefined;
 		try {
-			const nonce = dataKey.wrappedKey.subarray(1, 13);
-			const ciphertext = dataKey.wrappedKey.subarray(13, 45);
-			const tag = dataKey.wrappedKey.subarray(45);
+			wrappingKey = deriveOneUseWrappingKey(kek, salt, keyReference, context.wrappingContext);
+			const decipher = createDecipheriv("aes-256-gcm", wrappingKey, FIXED_WRAP_IV, {
+				authTagLength: TAG_BYTES,
+			});
+			decipher.setAAD(WRAP_AUTHENTICATED_DATA, { plaintextLength: DATA_KEY_BYTES });
+			decipher.setAuthTag(tag);
+			return decryptDataKey(decipher, ciphertext);
+		} catch (error: unknown) {
+			if (error instanceof CryptoError) throw error;
+			throw authenticationFailed({ cause: error });
+		} finally {
+			wrappingKey?.fill(0);
+		}
+	}
+
+	#unwrapLegacy(wrappedKey: Uint8Array, kek: KeyObject, context: DataKeyContext): KeyObject {
+		if (wrappedKey.byteLength !== LEGACY_WRAPPED_LENGTH || wrappedKey[0] !== LEGACY_WRAP_VERSION) {
+			throw authenticationFailed();
+		}
+		try {
+			const nonce = wrappedKey.subarray(1, 13);
+			const ciphertext = wrappedKey.subarray(13, 45);
+			const tag = wrappedKey.subarray(45);
 			const decipher = createDecipheriv("aes-256-gcm", kek, nonce, { authTagLength: 16 });
 			decipher.setAAD(context.wrappingContext, { plaintextLength: 32 });
 			decipher.setAuthTag(tag);
-			const first = decipher.update(ciphertext);
-			let last: Buffer | undefined;
-			let raw: Buffer | undefined;
-			try {
-				last = decipher.final();
-				raw = Buffer.concat([first, last]);
-				if (raw.byteLength !== 32) throw authenticationFailed();
-				return createSecretKey(raw);
-			} finally {
-				first.fill(0);
-				last?.fill(0);
-				raw?.fill(0);
-			}
+			return decryptDataKey(decipher, ciphertext);
 		} catch (error: unknown) {
 			if (error instanceof CryptoError) throw error;
 			throw authenticationFailed({ cause: error });
 		}
 	}
 
-	#wrap(key: KeyObject, kek: KeyObject, context: DataKeyContext): Uint8Array {
-		const nonce = randomBytes(12);
+	#wrap(key: KeyObject, kek: KeyObject, keyReference: string, context: DataKeyContext): Uint8Array {
+		const salt = randomBytes(SALT_BYTES);
 		const raw = key.export();
+		let wrappingKey: Buffer | undefined;
+		let ciphertext: Buffer | undefined;
+		let tag: Buffer | undefined;
 		try {
-			const cipher = createCipheriv("aes-256-gcm", kek, nonce, { authTagLength: 16 });
-			cipher.setAAD(context.wrappingContext, { plaintextLength: raw.byteLength });
-			const ciphertext = Buffer.concat([cipher.update(raw), cipher.final()]);
-			const output = new Uint8Array(WRAPPED_LENGTH);
-			output[0] = WRAP_VERSION;
-			output.set(nonce, 1);
-			output.set(ciphertext, 13);
-			output.set(cipher.getAuthTag(), 45);
+			wrappingKey = deriveOneUseWrappingKey(kek, salt, keyReference, context.wrappingContext);
+			const cipher = createCipheriv("aes-256-gcm", wrappingKey, FIXED_WRAP_IV, {
+				authTagLength: TAG_BYTES,
+			});
+			cipher.setAAD(WRAP_AUTHENTICATED_DATA, { plaintextLength: DATA_KEY_BYTES });
+			ciphertext = Buffer.concat([cipher.update(raw), cipher.final()]);
+			if (ciphertext.byteLength !== DATA_KEY_BYTES) {
+				throw new CryptoError("CIPHER_FAILURE", "Key wrapping produced an invalid result.");
+			}
+			tag = cipher.getAuthTag();
+			const output = new Uint8Array(SALTED_WRAPPED_LENGTH);
+			output[0] = SALTED_WRAP_VERSION;
+			output.set(salt, 1);
+			output.set(ciphertext, 1 + SALT_BYTES);
+			output.set(tag, 1 + SALT_BYTES + DATA_KEY_BYTES);
 			return output;
+		} catch (error: unknown) {
+			if (error instanceof CryptoError) throw error;
+			throw new CryptoError("CIPHER_FAILURE", "Key wrapping failed.", { cause: error });
 		} finally {
+			wrappingKey?.fill(0);
+			ciphertext?.fill(0);
+			tag?.fill(0);
 			raw.fill(0);
 		}
 	}

src/core/index.ts

@@ -1,6 +1,7 @@
 export { Aes256GcmCipher, AES_256_GCM } from "./aes-256-gcm.js";
 export {
 	AesKeyRingProvider,
+	AES_GCM_HKDF_SHA256_KEY_WRAP,
 	AES_GCM_KEY_WRAP,
 	type AesKeyRingProviderOptions,
 } from "./aes-key-ring.provider.js";

tests/unit/files-engine.test.ts

@@ -600,10 +600,11 @@ describe("FileCipherEngine", () => {
 		expect(
 			new Set(
 				attempts.map((attempt) =>
-					Buffer.from(attempt.detachedKey.wrappedKey.subarray(1, 13)).toString("hex"),
+					Buffer.from(attempt.detachedKey.wrappedKey.subarray(1, 33)).toString("hex"),
 				),
 			).size,
 		).toBe(3);
+		for (const attempt of attempts) expect(attempt.detachedKey.wrappedKey).toHaveLength(81);
 		expect(
 			new Set(
 				attempts.map((attempt) => Buffer.from(attempt.detachedKey.wrappedKey).toString("hex")),