@lindorm/aes 0.5.4 → 0.6.0

package/__tests__/jose-jwe.test.ts

@@ -0,0 +1,463 @@
+import { createCipheriv, CipherGCM, randomBytes } from "crypto";
+import { FlattenedEncrypt, flattenedDecrypt } from "jose";
+import { encryptAes, decryptAes } from "../src/utils/private/encryption";
+import { createHmacAuthTag } from "../src/utils/private/data/auth-tag-hmac";
+import { splitContentEncryptionKey } from "../src/utils/private/data/split-content-encryption-key";
+import { toUint8Array } from "./helpers/buffer-utils";
+import {
+  buildProtectedHeader,
+  toFlattenedJWE,
+  fromFlattenedJWE,
+} from "./helpers/jwe-adapter";
+import {
+  RAW_KEY_128,
+  RAW_KEY_192,
+  RAW_KEY_256,
+  RAW_KEY_256_CBC,
+  RAW_KEY_384_CBC,
+  RAW_KEY_512_CBC,
+  KEK_128,
+  KEK_192,
+  KEK_256,
+  createOctKryptos,
+} from "./fixtures/keys";
+
+const PLAINTEXT = "hello jose interop";
+const PLAINTEXT_BYTES = new TextEncoder().encode(PLAINTEXT);
+
+// ---------------------------------------------------------------------------
+// 4.1 dir + AES-GCM Cross-Reference
+// ---------------------------------------------------------------------------
+
+describe("jose JWE interop: dir + AES-GCM", () => {
+  describe.each([
+    { enc: "A128GCM" as const, key: RAW_KEY_128 },
+    { enc: "A192GCM" as const, key: RAW_KEY_192 },
+    { enc: "A256GCM" as const, key: RAW_KEY_256 },
+  ])("dir + $enc", ({ enc, key }) => {
+    test("our encrypt -> jose decrypt", async () => {
+      const kryptos = createOctKryptos(key, "dir", enc);
+      const { headerB64u, aadBuffer } = buildProtectedHeader("dir", enc);
+
+      const record = encryptAes({
+        data: PLAINTEXT,
+        encryption: enc,
+        kryptos,
+        aad: aadBuffer,
+      });
+
+      const jwe = toFlattenedJWE(record, headerB64u);
+      const result = await flattenedDecrypt(jwe, toUint8Array(key));
+
+      expect(Buffer.from(result.plaintext).toString("utf8")).toBe(PLAINTEXT);
+    });
+
+    test("jose encrypt -> our decrypt", async () => {
+      const kryptos = createOctKryptos(key, "dir", enc);
+
+      const jwe = await new FlattenedEncrypt(PLAINTEXT_BYTES)
+        .setProtectedHeader({ alg: "dir", enc })
+        .encrypt(toUint8Array(key));
+
+      const { record, aad } = fromFlattenedJWE(jwe);
+
+      const result = decryptAes({
+        ...record,
+        aad,
+        contentType: "text/plain",
+        kryptos,
+      });
+
+      expect(result).toBe(PLAINTEXT);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4.2 dir + AES-CBC-HMAC Cross-Reference
+// ---------------------------------------------------------------------------
+
+describe("jose JWE interop: dir + AES-CBC-HMAC", () => {
+  describe.each([
+    { enc: "A128CBC-HS256" as const, key: RAW_KEY_256_CBC },
+    { enc: "A192CBC-HS384" as const, key: RAW_KEY_384_CBC },
+    { enc: "A256CBC-HS512" as const, key: RAW_KEY_512_CBC },
+  ])("dir + $enc", ({ enc, key }) => {
+    test("our encrypt -> jose decrypt", async () => {
+      const kryptos = createOctKryptos(key, "dir", enc);
+      const { headerB64u, aadBuffer } = buildProtectedHeader("dir", enc);
+
+      const record = encryptAes({
+        data: PLAINTEXT,
+        encryption: enc,
+        kryptos,
+        aad: aadBuffer,
+      });
+
+      const jwe = toFlattenedJWE(record, headerB64u);
+      const result = await flattenedDecrypt(jwe, toUint8Array(key));
+
+      expect(Buffer.from(result.plaintext).toString("utf8")).toBe(PLAINTEXT);
+    });
+
+    test("jose encrypt -> our decrypt", async () => {
+      const kryptos = createOctKryptos(key, "dir", enc);
+
+      const jwe = await new FlattenedEncrypt(PLAINTEXT_BYTES)
+        .setProtectedHeader({ alg: "dir", enc })
+        .encrypt(toUint8Array(key));
+
+      const { record, aad } = fromFlattenedJWE(jwe);
+
+      const result = decryptAes({
+        ...record,
+        aad,
+        contentType: "text/plain",
+        kryptos,
+      });
+
+      expect(result).toBe(PLAINTEXT);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4.3 A*KW + AES-GCM Cross-Reference
+// ---------------------------------------------------------------------------
+
+describe("jose JWE interop: A*KW + AES-GCM", () => {
+  describe.each([
+    { alg: "A128KW" as const, kek: KEK_128 },
+    { alg: "A192KW" as const, kek: KEK_192 },
+    { alg: "A256KW" as const, kek: KEK_256 },
+  ])("$alg", ({ alg, kek }) => {
+    describe.each([{ enc: "A128GCM" as const }, { enc: "A256GCM" as const }])(
+      "+ $enc",
+      ({ enc }) => {
+        test("our encrypt -> jose decrypt", async () => {
+          const kryptos = createOctKryptos(kek, alg, enc);
+          const { headerB64u, aadBuffer } = buildProtectedHeader(alg, enc);
+
+          const record = encryptAes({
+            data: PLAINTEXT,
+            encryption: enc,
+            kryptos,
+            aad: aadBuffer,
+          });
+
+          const jwe = toFlattenedJWE(record, headerB64u);
+          const result = await flattenedDecrypt(jwe, toUint8Array(kek));
+
+          expect(Buffer.from(result.plaintext).toString("utf8")).toBe(PLAINTEXT);
+        });
+
+        test("jose encrypt -> our decrypt", async () => {
+          const kryptos = createOctKryptos(kek, alg, enc);
+
+          const jwe = await new FlattenedEncrypt(PLAINTEXT_BYTES)
+            .setProtectedHeader({ alg, enc })
+            .encrypt(toUint8Array(kek));
+
+          const { record, aad } = fromFlattenedJWE(jwe);
+
+          const result = decryptAes({
+            ...record,
+            aad,
+            contentType: "text/plain",
+            kryptos,
+          });
+
+          expect(result).toBe(PLAINTEXT);
+        });
+      },
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4.4 A*KW + AES-CBC-HMAC Cross-Reference
+// ---------------------------------------------------------------------------
+
+describe("jose JWE interop: A*KW + AES-CBC-HMAC", () => {
+  describe.each([
+    { alg: "A128KW" as const, enc: "A128CBC-HS256" as const, kek: KEK_128 },
+    { alg: "A192KW" as const, enc: "A192CBC-HS384" as const, kek: KEK_192 },
+    { alg: "A256KW" as const, enc: "A256CBC-HS512" as const, kek: KEK_256 },
+  ])("$alg + $enc", ({ alg, enc, kek }) => {
+    test("our encrypt -> jose decrypt", async () => {
+      const kryptos = createOctKryptos(kek, alg, enc);
+      const { headerB64u, aadBuffer } = buildProtectedHeader(alg, enc);
+
+      const record = encryptAes({
+        data: PLAINTEXT,
+        encryption: enc,
+        kryptos,
+        aad: aadBuffer,
+      });
+
+      const jwe = toFlattenedJWE(record, headerB64u);
+      const result = await flattenedDecrypt(jwe, toUint8Array(kek));
+
+      expect(Buffer.from(result.plaintext).toString("utf8")).toBe(PLAINTEXT);
+    });
+
+    test("jose encrypt -> our decrypt", async () => {
+      const kryptos = createOctKryptos(kek, alg, enc);
+
+      const jwe = await new FlattenedEncrypt(PLAINTEXT_BYTES)
+        .setProtectedHeader({ alg, enc })
+        .encrypt(toUint8Array(kek));
+
+      const { record, aad } = fromFlattenedJWE(jwe);
+
+      const result = decryptAes({
+        ...record,
+        aad,
+        contentType: "text/plain",
+        kryptos,
+      });
+
+      expect(result).toBe(PLAINTEXT);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4.5 A*GCMKW + AES-GCM Cross-Reference
+// ---------------------------------------------------------------------------
+
+describe("jose JWE interop: A*GCMKW + AES-GCM", () => {
+  describe.each([
+    { alg: "A128GCMKW" as const, kek: KEK_128 },
+    { alg: "A256GCMKW" as const, kek: KEK_256 },
+  ])("$alg + A256GCM", ({ alg, kek }) => {
+    const enc = "A256GCM" as const;
+
+    test("jose encrypt -> our decrypt", async () => {
+      const kryptos = createOctKryptos(kek, alg, enc);
+
+      const jwe = await new FlattenedEncrypt(PLAINTEXT_BYTES)
+        .setProtectedHeader({ alg, enc })
+        .encrypt(toUint8Array(kek));
+
+      const { record, aad } = fromFlattenedJWE(jwe);
+
+      const result = decryptAes({
+        ...record,
+        aad,
+        contentType: "text/plain",
+        kryptos,
+      });
+
+      expect(result).toBe(PLAINTEXT);
+    });
+
+    // Our encrypt -> jose decrypt for GCMKW has a circular dependency:
+    // The protected header must contain the key-wrap iv and tag (per RFC 7518 section 4.7),
+    // but the content encryption AAD is computed from the protected header (per RFC 7516
+    // section 5.1 step 14). Our encryptAes() generates the key-wrap params and encrypts
+    // content in a single pass, so we cannot know the final header (and therefore the
+    // correct AAD) before encryption.
+    //
+    // A two-pass approach (encrypt once to get kw params, build header, re-encrypt with
+    // correct AAD) would require exposing the CEK from the first pass, which our API
+    // does not currently support via the public encryptAes interface.
+    //
+    // The jose->ours direction above validates that our decryption is fully compatible.
+    // Byte-level correctness of our GCM key-wrap is separately validated in the
+    // noble-ciphers cross-reference tests.
+    test("our encrypt -> jose decrypt", async () => {
+      const kryptos = createOctKryptos(kek, alg, enc);
+
+      // Perform encryption without AAD first to get the key-wrap parameters
+      const record = encryptAes({
+        data: PLAINTEXT,
+        encryption: enc,
+        kryptos,
+      });
+
+      // Build the protected header including the GCMKW iv and tag
+      const { headerB64u, aadBuffer } = buildProtectedHeader(alg, enc, {
+        iv: record.publicEncryptionIv!,
+        tag: record.publicEncryptionTag!,
+      });
+
+      // Re-encrypt with correct AAD using the same CEK that was wrapped.
+      // We can recover the CEK by unwrapping the encrypted_key.
+      const unwrapKryptos = createOctKryptos(kek, alg, enc);
+      const { contentEncryptionKey } = (
+        await import("../src/utils/private/key-wrap/gcm-key-wrap")
+      ).gcmKeyUnwrap({
+        keyEncryptionKey: kek,
+        kryptos: unwrapKryptos,
+        publicEncryptionIv: record.publicEncryptionIv!,
+        publicEncryptionKey: record.publicEncryptionKey!,
+        publicEncryptionTag: record.publicEncryptionTag!,
+      });
+
+      // Re-encrypt content with the recovered CEK and correct AAD
+      const { encryptionKey } = splitContentEncryptionKey(enc, contentEncryptionKey);
+      const iv = randomBytes(12);
+      const cipher = createCipheriv("aes-256-gcm", encryptionKey, iv, {
+        authTagLength: 16,
+      }) as CipherGCM;
+      cipher.setAAD(aadBuffer);
+
+      const plaintextBuf = Buffer.from(PLAINTEXT, "utf8");
+      const ciphertext = Buffer.concat([cipher.update(plaintextBuf), cipher.final()]);
+      const authTag = cipher.getAuthTag();
+
+      const jwe = {
+        protected: headerB64u,
+        iv: iv.toString("base64url"),
+        ciphertext: ciphertext.toString("base64url"),
+        tag: authTag.toString("base64url"),
+        encrypted_key: record.publicEncryptionKey!.toString("base64url"),
+      };
+
+      const result = await flattenedDecrypt(jwe, toUint8Array(kek));
+      expect(Buffer.from(result.plaintext).toString("utf8")).toBe(PLAINTEXT);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4.6 Deterministic Pinned Tests
+// ---------------------------------------------------------------------------
+//
+// jose v6 does not allow setContentEncryptionKey() with alg: "dir".
+// We use A256KW / A128KW key-wrap algorithms instead, which do allow CEK
+// pinning. This still validates byte-identical ciphertext because the
+// content encryption is the same regardless of the key management algorithm.
+// ---------------------------------------------------------------------------
+
+describe("jose JWE interop: deterministic pinned tests", () => {
+  describe("A256KW + A256GCM", () => {
+    const alg = "A256KW" as const;
+    const enc = "A256GCM" as const;
+    const kek = KEK_256;
+    const cek = Buffer.from(
+      "e1e2e3e4e5e6e7e8e9eaebecedeeeff0f1f2f3f4f5f6f7f8f9fafbfcfdfeff00",
+      "hex",
+    );
+    const iv = Buffer.from("0a0b0c0d0e0f10111213141516", "hex").subarray(0, 12);
+    const plaintextBuf = Buffer.from(PLAINTEXT, "utf8");
+
+    test("byte-identical ciphertext and auth tag", async () => {
+      // jose: encrypt with pinned CEK and IV
+      const jwe = await new FlattenedEncrypt(PLAINTEXT_BYTES)
+        .setProtectedHeader({ alg, enc })
+        .setContentEncryptionKey(toUint8Array(cek))
+        .setInitializationVector(toUint8Array(iv))
+        .encrypt(toUint8Array(kek));
+
+      // The AAD is the ASCII bytes of the base64url-encoded protected header
+      const joseAad = Buffer.from(jwe.protected!, "ascii");
+
+      // Our side: raw createCipheriv with the same CEK, IV, and AAD
+      const cipher = createCipheriv("aes-256-gcm", cek, iv, {
+        authTagLength: 16,
+      }) as CipherGCM;
+      cipher.setAAD(joseAad);
+
+      const ourCiphertext = Buffer.concat([cipher.update(plaintextBuf), cipher.final()]);
+      const ourTag = cipher.getAuthTag();
+
+      const joseCiphertext = Buffer.from(jwe.ciphertext, "base64url");
+      const joseTag = Buffer.from(jwe.tag!, "base64url");
+
+      expect(ourCiphertext.equals(joseCiphertext)).toBe(true);
+      expect(ourTag.equals(joseTag)).toBe(true);
+    });
+
+    test("round-trip with pinned values through decryptAes", async () => {
+      // jose: encrypt with pinned CEK and IV
+      const jwe = await new FlattenedEncrypt(PLAINTEXT_BYTES)
+        .setProtectedHeader({ alg, enc })
+        .setContentEncryptionKey(toUint8Array(cek))
+        .setInitializationVector(toUint8Array(iv))
+        .encrypt(toUint8Array(kek));
+
+      // Parse with our adapter and decrypt
+      const kryptos = createOctKryptos(kek, alg, enc);
+      const { record, aad } = fromFlattenedJWE(jwe);
+
+      const result = decryptAes({
+        ...record,
+        aad,
+        contentType: "text/plain",
+        kryptos,
+      });
+
+      expect(result).toBe(PLAINTEXT);
+    });
+  });
+
+  describe("A128KW + A128CBC-HS256", () => {
+    const alg = "A128KW" as const;
+    const enc = "A128CBC-HS256" as const;
+    const kek = KEK_128;
+    // A128CBC-HS256 CEK is 32 bytes: first 16 = HMAC key, last 16 = AES key
+    const cek = Buffer.from(
+      "a1a2a3a4a5a6a7a8a9aaabacadaeafb0b1b2b3b4b5b6b7b8b9babbbcbdbebfc0",
+      "hex",
+    );
+    const iv = Buffer.alloc(16, 0xdd);
+    const plaintextBuf = Buffer.from(PLAINTEXT, "utf8");
+
+    test("byte-identical ciphertext and auth tag", async () => {
+      // jose: encrypt with pinned CEK and IV
+      const jwe = await new FlattenedEncrypt(PLAINTEXT_BYTES)
+        .setProtectedHeader({ alg, enc })
+        .setContentEncryptionKey(toUint8Array(cek))
+        .setInitializationVector(toUint8Array(iv))
+        .encrypt(toUint8Array(kek));
+
+      const joseAad = Buffer.from(jwe.protected!, "ascii");
+
+      // Split CEK per RFC 7518 Section 5.2
+      const { encryptionKey, hashKey } = splitContentEncryptionKey(enc, cek);
+
+      // Our side: raw createCipheriv (CBC) with same key and IV
+      const cipher = createCipheriv("aes-128-cbc", encryptionKey, iv);
+      const ourCiphertext = Buffer.concat([cipher.update(plaintextBuf), cipher.final()]);
+
+      // HMAC auth tag per RFC 7518 Section 5.2.2.1
+      const ourTag = createHmacAuthTag({
+        aad: joseAad,
+        content: ourCiphertext,
+        encryption: enc,
+        hashKey,
+        initialisationVector: iv,
+      });
+
+      const joseCiphertext = Buffer.from(jwe.ciphertext, "base64url");
+      const joseTag = Buffer.from(jwe.tag!, "base64url");
+
+      expect(ourCiphertext.equals(joseCiphertext)).toBe(true);
+      expect(ourTag.equals(joseTag)).toBe(true);
+    });
+
+    test("round-trip with pinned values through decryptAes", async () => {
+      // jose: encrypt with pinned CEK and IV
+      const jwe = await new FlattenedEncrypt(PLAINTEXT_BYTES)
+        .setProtectedHeader({ alg, enc })
+        .setContentEncryptionKey(toUint8Array(cek))
+        .setInitializationVector(toUint8Array(iv))
+        .encrypt(toUint8Array(kek));
+
+      // Parse with our adapter and decrypt
+      const kryptos = createOctKryptos(kek, alg, enc);
+      const { record, aad } = fromFlattenedJWE(jwe);
+
+      const result = decryptAes({
+        ...record,
+        aad,
+        contentType: "text/plain",
+        kryptos,
+      });
+
+      expect(result).toBe(PLAINTEXT);
+    });
+  });
+});

package/__tests__/noble-ciphers.test.ts

@@ -0,0 +1,208 @@
+import { createCipheriv, randomBytes } from "crypto";
+import { gcm, cbc, aeskw } from "@noble/ciphers/aes";
+import { encryptAes, decryptAes } from "../src/utils/private/encryption";
+import { ecbKeyWrap, ecbKeyUnwrap } from "../src/utils/private/key-wrap/ecb-key-wrap";
+import { toUint8Array, toBuffer } from "./helpers/buffer-utils";
+import {
+  RAW_KEY_128,
+  RAW_KEY_192,
+  RAW_KEY_256,
+  RAW_KEY_256_CBC,
+  RAW_KEY_384_CBC,
+  RAW_KEY_512_CBC,
+  KEK_128,
+  KEK_192,
+  KEK_256,
+  createOctKryptos,
+} from "./fixtures/keys";
+
+const GCM_TAG_LENGTH = 16;
+const GCM_IV_LENGTH = 12;
+const AES_BLOCK_SIZE = 16;
+
+// ---------------------------------------------------------------------------
+// 3.1 AES-GCM Cross-Reference
+// ---------------------------------------------------------------------------
+
+describe("AES-GCM cross-reference with @noble/ciphers", () => {
+  describe.each([
+    { name: "A128GCM", key: RAW_KEY_128, encryption: "A128GCM" as const },
+    { name: "A192GCM", key: RAW_KEY_192, encryption: "A192GCM" as const },
+    { name: "A256GCM", key: RAW_KEY_256, encryption: "A256GCM" as const },
+  ])("$name", ({ key, encryption }) => {
+    const plaintext = "test plaintext";
+
+    test("our encryptAes -> noble gcm decrypt", () => {
+      const kryptos = createOctKryptos(key, "dir", encryption);
+
+      const record = encryptAes({ data: plaintext, encryption, kryptos });
+
+      const iv = toUint8Array(record.initialisationVector);
+      const ciphertext = toUint8Array(record.content);
+      const tag = toUint8Array(record.authTag);
+
+      // noble expects ciphertext || tag concatenated
+      const ciphertextWithTag = new Uint8Array(ciphertext.length + tag.length);
+      ciphertextWithTag.set(ciphertext, 0);
+      ciphertextWithTag.set(tag, ciphertext.length);
+
+      const decrypted = gcm(toUint8Array(key), iv).decrypt(ciphertextWithTag);
+      const result = new TextDecoder().decode(decrypted);
+
+      expect(result).toBe(plaintext);
+    });
+
+    test("noble gcm encrypt -> our decryptAes", () => {
+      const kryptos = createOctKryptos(key, "dir", encryption);
+      const iv = randomBytes(GCM_IV_LENGTH);
+      const plaintextBytes = new TextEncoder().encode(plaintext);
+
+      const encrypted = gcm(toUint8Array(key), toUint8Array(iv)).encrypt(plaintextBytes);
+
+      // noble returns ciphertext || tag (last 16 bytes are the auth tag)
+      const ciphertext = toBuffer(encrypted.slice(0, -GCM_TAG_LENGTH));
+      const authTag = toBuffer(encrypted.slice(-GCM_TAG_LENGTH));
+
+      const result = decryptAes({
+        content: ciphertext,
+        authTag,
+        initialisationVector: iv,
+        encryption,
+        contentType: "text/plain",
+        kryptos,
+      });
+
+      expect(result).toBe(plaintext);
+    });
+
+    test("byte-identical ciphertext with pinned IV", () => {
+      const iv = Buffer.alloc(GCM_IV_LENGTH, 0xab);
+      const plaintextBytes = Buffer.from(plaintext, "utf8");
+
+      // Our side: raw Node.js createCipheriv
+      const cipher = createCipheriv(
+        `aes-${key.length * 8}-gcm` as "aes-128-gcm" | "aes-192-gcm" | "aes-256-gcm",
+        key,
+        iv,
+        { authTagLength: GCM_TAG_LENGTH },
+      );
+      const ourCiphertext = Buffer.concat([
+        cipher.update(plaintextBytes),
+        cipher.final(),
+      ]);
+      const ourTag = cipher.getAuthTag();
+
+      // Noble side
+      const nobleResult = gcm(toUint8Array(key), toUint8Array(iv)).encrypt(
+        toUint8Array(plaintextBytes),
+      );
+      const nobleCiphertext = nobleResult.slice(0, -GCM_TAG_LENGTH);
+      const nobleTag = nobleResult.slice(-GCM_TAG_LENGTH);
+
+      expect(ourCiphertext.equals(toBuffer(nobleCiphertext))).toBe(true);
+      expect(ourTag.equals(toBuffer(nobleTag))).toBe(true);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3.2 AES-KW (RFC 3394) Cross-Reference
+// ---------------------------------------------------------------------------
+
+describe("AES-KW cross-reference with @noble/ciphers", () => {
+  describe.each([
+    { name: "A128KW", kek: KEK_128, algorithm: "A128KW" as const },
+    { name: "A192KW", kek: KEK_192, algorithm: "A192KW" as const },
+    { name: "A256KW", kek: KEK_256, algorithm: "A256KW" as const },
+  ])("$name", ({ kek, algorithm }) => {
+    // CEK to wrap: 32 bytes (suitable for A256GCM)
+    const cek = randomBytes(32);
+
+    test("our ecbKeyWrap -> noble aeskw decrypt", () => {
+      const kryptos = createOctKryptos(kek, algorithm);
+
+      const { publicEncryptionKey } = ecbKeyWrap({
+        contentEncryptionKey: cek,
+        keyEncryptionKey: kek,
+        kryptos,
+      });
+
+      const unwrapped = aeskw(toUint8Array(kek)).decrypt(
+        toUint8Array(publicEncryptionKey),
+      );
+
+      expect(cek.equals(toBuffer(unwrapped))).toBe(true);
+    });
+
+    test("noble aeskw encrypt -> our ecbKeyUnwrap", () => {
+      const kryptos = createOctKryptos(kek, algorithm);
+
+      const wrapped = aeskw(toUint8Array(kek)).encrypt(toUint8Array(cek));
+
+      const { contentEncryptionKey } = ecbKeyUnwrap({
+        keyEncryptionKey: kek,
+        kryptos,
+        publicEncryptionKey: toBuffer(wrapped),
+      });
+
+      expect(cek.equals(contentEncryptionKey)).toBe(true);
+    });
+
+    test("byte-identical wrapped key (deterministic)", () => {
+      const kryptos = createOctKryptos(kek, algorithm);
+
+      const { publicEncryptionKey } = ecbKeyWrap({
+        contentEncryptionKey: cek,
+        keyEncryptionKey: kek,
+        kryptos,
+      });
+
+      const nobleWrapped = aeskw(toUint8Array(kek)).encrypt(toUint8Array(cek));
+
+      expect(publicEncryptionKey.equals(toBuffer(nobleWrapped))).toBe(true);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3.3 AES-CBC Raw Cross-Reference
+// ---------------------------------------------------------------------------
+
+describe("AES-CBC raw cross-reference with @noble/ciphers", () => {
+  describe.each([
+    {
+      name: "A128CBC",
+      // A128CBC-HS256: 32B CEK -> first 16B = HMAC key, last 16B = AES-128-CBC key
+      encKey: RAW_KEY_256_CBC.subarray(16),
+      nodeCipher: "aes-128-cbc" as const,
+    },
+    {
+      name: "A192CBC",
+      // A192CBC-HS384: 48B CEK -> first 24B = HMAC key, last 24B = AES-192-CBC key
+      encKey: RAW_KEY_384_CBC.subarray(24),
+      nodeCipher: "aes-192-cbc" as const,
+    },
+    {
+      name: "A256CBC",
+      // A256CBC-HS512: 64B CEK -> first 32B = HMAC key, last 32B = AES-256-CBC key
+      encKey: RAW_KEY_512_CBC.subarray(32),
+      nodeCipher: "aes-256-cbc" as const,
+    },
+  ])("$name", ({ encKey, nodeCipher }) => {
+    test("byte-identical ciphertext (PKCS7 padding)", () => {
+      const iv = Buffer.alloc(AES_BLOCK_SIZE, 0xcd);
+      const plaintext = Buffer.from("cross-reference CBC test", "utf8");
+
+      // Our side: raw Node.js createCipheriv
+      const cipher = createCipheriv(nodeCipher, encKey, iv);
+      const ourCiphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+
+      // Noble side
+      const nobleCiphertext = cbc(toUint8Array(encKey), toUint8Array(iv)).encrypt(
+        toUint8Array(plaintext),
+      );
+
+      expect(ourCiphertext.equals(toBuffer(nobleCiphertext))).toBe(true);
+    });
+  });
+});

package/dist/classes/AesKit.d.ts

@@ -1,17 +1,19 @@
 import { IKryptos } from "@lindorm/kryptos";
-import { IAesKit } from "../interfaces";
+import { AesOperationOptions, IAesKit } from "../interfaces";
 import { AesContent, AesContentType, AesDecryptionRecord, AesEncryptionRecord, AesKitOptions, SerialisedAesDecryption, SerialisedAesEncryption } from "../types";
+import { PreparedEncryption } from "../types/private";
 export declare class AesKit implements IAesKit {
     private readonly encryption;
     readonly kryptos: IKryptos;
     constructor(options: AesKitOptions);
-    encrypt(data: AesContent, mode?: "encoded"): string;
-    encrypt(data: AesContent, mode: "record"): AesEncryptionRecord;
-    encrypt(data: AesContent, mode: "serialised"): SerialisedAesEncryption;
-    encrypt(data: AesContent, mode: "tokenised"): string;
-    decrypt<T extends AesContent = string>(data: AesDecryptionRecord | SerialisedAesDecryption | string): T;
-    verify(input: string, data: AesDecryptionRecord | SerialisedAesDecryption | string): boolean;
-    assert(input: string, data: AesDecryptionRecord | SerialisedAesDecryption | string): void;
+    encrypt(data: AesContent, mode?: "encoded", options?: AesOperationOptions): string;
+    encrypt(data: AesContent, mode: "record", options?: AesOperationOptions): AesEncryptionRecord;
+    encrypt(data: AesContent, mode: "serialised", options?: AesOperationOptions): SerialisedAesEncryption;
+    encrypt(data: AesContent, mode: "tokenised", options?: AesOperationOptions): string;
+    decrypt<T extends AesContent = string>(data: AesDecryptionRecord | SerialisedAesDecryption | string, options?: AesOperationOptions): T;
+    verify(input: AesContent, data: AesDecryptionRecord | SerialisedAesDecryption | string, options?: AesOperationOptions): boolean;
+    assert(input: AesContent, data: AesDecryptionRecord | SerialisedAesDecryption | string, options?: AesOperationOptions): void;
+    prepareEncryption(): PreparedEncryption;
     static contentType(input: any): AesContentType;
     static isAesTokenised(input: any): input is string;
     static parse(data: AesDecryptionRecord | SerialisedAesDecryption | string): AesDecryptionRecord;