@lindorm/aes 0.5.5 → 0.6.1

package/__tests__/INTEROP-RESULTS.md

@@ -0,0 +1,66 @@
+# AES Interop Test Results
+
+## Summary
+
+All 59 interop tests pass. Zero divergences found between `@lindorm/aes`,
+`@noble/ciphers`, and `jose`.
+
+| Suite         | Tests  | Pass   | Fail  | Skip  |
+| ------------- | ------ | ------ | ----- | ----- |
+| noble-ciphers | 21     | 21     | 0     | 0     |
+| jose-jwe      | 38     | 38     | 0     | 0     |
+| **Total**     | **59** | **59** | **0** | **0** |
+
+## noble/ciphers Primitive Tests
+
+| Primitive         | Key Sizes     | Direction                      | Result |
+| ----------------- | ------------- | ------------------------------ | ------ |
+| AES-GCM           | 128, 192, 256 | ours → noble                   | PASS   |
+| AES-GCM           | 128, 192, 256 | noble → ours                   | PASS   |
+| AES-GCM           | 128, 192, 256 | byte-identical (pinned IV)     | PASS   |
+| AES-KW (RFC 3394) | 128, 192, 256 | ours → noble                   | PASS   |
+| AES-KW (RFC 3394) | 128, 192, 256 | noble → ours                   | PASS   |
+| AES-KW (RFC 3394) | 128, 192, 256 | byte-identical (deterministic) | PASS   |
+| AES-CBC (raw)     | 128, 192, 256 | byte-identical (PKCS7)         | PASS   |
+
+## jose JWE Tests
+
+| Algorithm              | Encryption                                  | Direction   | Result |
+| ---------------------- | ------------------------------------------- | ----------- | ------ |
+| dir                    | A128GCM, A192GCM, A256GCM                   | ours → jose | PASS   |
+| dir                    | A128GCM, A192GCM, A256GCM                   | jose → ours | PASS   |
+| dir                    | A128CBC-HS256, A192CBC-HS384, A256CBC-HS512 | ours → jose | PASS   |
+| dir                    | A128CBC-HS256, A192CBC-HS384, A256CBC-HS512 | jose → ours | PASS   |
+| A128KW, A192KW, A256KW | A128GCM, A256GCM                            | ours → jose | PASS   |
+| A128KW, A192KW, A256KW | A128GCM, A256GCM                            | jose → ours | PASS   |
+| A128KW, A192KW, A256KW | A128CBC-HS256, A192CBC-HS384, A256CBC-HS512 | ours → jose | PASS   |
+| A128KW, A192KW, A256KW | A128CBC-HS256, A192CBC-HS384, A256CBC-HS512 | jose → ours | PASS   |
+| A128GCMKW, A256GCMKW   | A256GCM                                     | ours → jose | PASS   |
+| A128GCMKW, A256GCMKW   | A256GCM                                     | jose → ours | PASS   |
+| Pinned deterministic   | A256GCM (byte-identical)                    | comparison  | PASS   |
+| Pinned deterministic   | A256GCM (round-trip)                        | comparison  | PASS   |
+| Pinned deterministic   | A128CBC-HS256 (byte-identical)              | comparison  | PASS   |
+| Pinned deterministic   | A128CBC-HS256 (round-trip)                  | comparison  | PASS   |
+
+## Validated RFC Compliance
+
+- **RFC 7516** (JWE): AAD computation, flattened serialization format
+- **RFC 7518** (JWA): AES-GCM, AES-CBC-HMAC-SHA2, AES Key Wrap, AES-GCM Key Wrap
+- **RFC 3394**: AES Key Wrap (deterministic, AIV verification)
+
+## Notes
+
+- GCMKW "ours → jose" direction uses a two-pass approach due to the circular
+  dependency between key-wrap params and JWE AAD. Content is re-encrypted with
+  the correct AAD after extracting key-wrap params from the first pass.
+- jose v6 rejects `setContentEncryptionKey()` with `alg: "dir"`, so deterministic
+  pinned tests use A\*KW algorithms instead. Content encryption is identical
+  regardless of key management algorithm.
+- `@noble/ciphers` GCM returns ciphertext with auth tag appended (last 16 bytes).
+  Tests correctly split/concatenate when converting between formats.
+
+## Environment
+
+- Node.js >= 24.4.0
+- `@noble/ciphers` ^1.2.1
+- `jose` ^6.1.3

package/__tests__/esm-smoke.test.ts

@@ -0,0 +1,15 @@
+import { gcm, cbc, aeskw } from "@noble/ciphers/aes";
+import { FlattenedEncrypt, flattenedDecrypt } from "jose";
+
+describe("ESM import smoke test", () => {
+  test("should import @noble/ciphers", () => {
+    expect(gcm).toBeDefined();
+    expect(cbc).toBeDefined();
+    expect(aeskw).toBeDefined();
+  });
+
+  test("should import jose", () => {
+    expect(FlattenedEncrypt).toBeDefined();
+    expect(flattenedDecrypt).toBeDefined();
+  });
+});

package/__tests__/fixtures/keys.ts

@@ -0,0 +1,60 @@
+import { randomUUID } from "crypto";
+import {
+  Kryptos,
+  KryptosAlgorithm,
+  KryptosEncryption,
+  KryptosKit,
+} from "@lindorm/kryptos";
+
+// Fixed raw symmetric keys for dir mode (CEK = key)
+export const RAW_KEY_128 = Buffer.from("000102030405060708090a0b0c0d0e0f", "hex");
+export const RAW_KEY_192 = Buffer.from(
+  "000102030405060708090a0b0c0d0e0f1011121314151617",
+  "hex",
+);
+export const RAW_KEY_256 = Buffer.from(
+  "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
+  "hex",
+);
+
+// CBC-HMAC composite keys (double-length: half for HMAC, half for AES-CBC)
+export const RAW_KEY_256_CBC = Buffer.from(
+  "202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f",
+  "hex",
+);
+export const RAW_KEY_384_CBC = Buffer.from(
+  "404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5d5e5f606162636465666768696a6b6c6d6e6f",
+  "hex",
+);
+export const RAW_KEY_512_CBC = Buffer.from(
+  "808182838485868788898a8b8c8d8e8f909192939495969798999a9b9c9d9e9fa0a1a2a3a4a5a6a7a8a9aaabacadaeafb0b1b2b3b4b5b6b7b8b9babbbcbdbebf",
+  "hex",
+);
+
+// Key Encryption Keys for KW modes
+export const KEK_128 = Buffer.from("c0c1c2c3c4c5c6c7c8c9cacbcccdcecf", "hex");
+export const KEK_192 = Buffer.from(
+  "d0d1d2d3d4d5d6d7d8d9dadbdcdddedfe0e1e2e3e4e5e6e7",
+  "hex",
+);
+export const KEK_256 = Buffer.from(
+  "f0f1f2f3f4f5f6f7f8f9fafbfcfdfefff0f1f2f3f4f5f6f7f8f9fafbfcfdfeff",
+  "hex",
+);
+
+/**
+ * Helper to create a Kryptos oct key from raw bytes.
+ */
+export const createOctKryptos = (
+  raw: Buffer,
+  algorithm: KryptosAlgorithm,
+  encryption?: KryptosEncryption,
+): Kryptos =>
+  KryptosKit.from.der({
+    id: randomUUID(),
+    algorithm,
+    encryption,
+    privateKey: raw,
+    type: "oct",
+    use: "enc",
+  });

package/__tests__/helpers/buffer-utils.ts

@@ -0,0 +1,11 @@
+/**
+ * Convert Buffer to Uint8Array (zero-copy view).
+ */
+export const toUint8Array = (buf: Buffer): Uint8Array =>
+  new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+
+/**
+ * Convert Uint8Array to Buffer (zero-copy view).
+ */
+export const toBuffer = (arr: Uint8Array): Buffer =>
+  Buffer.from(arr.buffer, arr.byteOffset, arr.byteLength);

package/__tests__/helpers/index.ts

@@ -0,0 +1,2 @@
+export * from "./buffer-utils";
+export * from "./jwe-adapter";

package/__tests__/helpers/jwe-adapter.ts

@@ -0,0 +1,117 @@
+import type { FlattenedJWE } from "jose";
+import type { AesDecryptionRecord } from "../../src/types/aes-decryption-data";
+import type { AesEncryptionRecord } from "../../src/types/aes-encryption-data";
+
+/**
+ * Build a JWE protected header JSON string, its base64url encoding,
+ * and the AAD buffer (ASCII bytes of the base64url-encoded header).
+ *
+ * Per RFC 7516 section 5.1 step 14, the JWE AAD is the ASCII representation
+ * of the base64url-encoded protected header.
+ *
+ * For A*GCMKW algorithms, the key-wrap iv and tag go into the protected header
+ * per RFC 7518 section 4.7.
+ */
+export const buildProtectedHeader = (
+  algorithm: string,
+  encryption: string,
+  gcmkwParams?: { iv: Buffer; tag: Buffer },
+): {
+  headerJson: string;
+  headerB64u: string;
+  aadBuffer: Buffer;
+} => {
+  const header: Record<string, string> = { alg: algorithm, enc: encryption };
+
+  if (gcmkwParams) {
+    header.iv = gcmkwParams.iv.toString("base64url");
+    header.tag = gcmkwParams.tag.toString("base64url");
+  }
+
+  const headerJson = JSON.stringify(header);
+  const headerB64u = Buffer.from(headerJson, "utf8").toString("base64url");
+  const aadBuffer = Buffer.from(headerB64u, "ascii");
+
+  return { headerJson, headerB64u, aadBuffer };
+};
+
+/**
+ * Convert our AesEncryptionRecord to a jose FlattenedJWE object.
+ *
+ * Field mapping:
+ *   - protected:      base64url-encoded protected header (passed in)
+ *   - iv:             base64url of record.initialisationVector
+ *   - ciphertext:     base64url of record.content
+ *   - tag:            base64url of record.authTag
+ *   - encrypted_key:  base64url of record.publicEncryptionKey (absent for dir)
+ */
+export const toFlattenedJWE = (
+  record: AesEncryptionRecord,
+  headerB64u: string,
+): FlattenedJWE => {
+  const jwe: FlattenedJWE = {
+    protected: headerB64u,
+    iv: record.initialisationVector.toString("base64url"),
+    ciphertext: record.content.toString("base64url"),
+    tag: record.authTag.toString("base64url"),
+  };
+
+  if (record.publicEncryptionKey) {
+    jwe.encrypted_key = record.publicEncryptionKey.toString("base64url");
+  }
+
+  return jwe;
+};
+
+/**
+ * Convert a jose FlattenedJWE back to our AesDecryptionRecord + the AAD buffer.
+ *
+ * Parses the protected header to extract algorithm, encryption, and optional
+ * GCMKW parameters (iv, tag for key-wrap).
+ *
+ * Field mapping (inverse of toFlattenedJWE):
+ *   - content:              Buffer from base64url ciphertext
+ *   - initialisationVector: Buffer from base64url iv
+ *   - authTag:              Buffer from base64url tag
+ *   - publicEncryptionKey:  Buffer from base64url encrypted_key (undefined for dir)
+ *   - publicEncryptionIv:   Buffer from protected header iv param (GCMKW only)
+ *   - publicEncryptionTag:  Buffer from protected header tag param (GCMKW only)
+ *   - encryption:           enc value from protected header
+ *   - algorithm:            alg value from protected header
+ */
+export const fromFlattenedJWE = (
+  jwe: FlattenedJWE,
+): {
+  record: AesDecryptionRecord;
+  aad: Buffer;
+} => {
+  if (!jwe.protected) {
+    throw new Error("FlattenedJWE missing protected header");
+  }
+  if (!jwe.iv) {
+    throw new Error("FlattenedJWE missing iv");
+  }
+  if (!jwe.tag) {
+    throw new Error("FlattenedJWE missing tag");
+  }
+
+  const headerJson = Buffer.from(jwe.protected, "base64url").toString("utf8");
+  const header = JSON.parse(headerJson) as Record<string, string>;
+
+  const aad = Buffer.from(jwe.protected, "ascii");
+
+  const record: AesDecryptionRecord = {
+    algorithm: header.alg as AesDecryptionRecord["algorithm"],
+    encryption: header.enc as AesDecryptionRecord["encryption"],
+    content: Buffer.from(jwe.ciphertext, "base64url"),
+    initialisationVector: Buffer.from(jwe.iv, "base64url"),
+    authTag: Buffer.from(jwe.tag, "base64url"),
+    publicEncryptionKey: jwe.encrypted_key
+      ? Buffer.from(jwe.encrypted_key, "base64url")
+      : undefined,
+    publicEncryptionIv: header.iv ? Buffer.from(header.iv, "base64url") : undefined,
+    publicEncryptionTag: header.tag ? Buffer.from(header.tag, "base64url") : undefined,
+  };
+
+  return { record, aad };
+};