@tearleads/client-sdk 0.0.0-stage → 0.1.13

package/internal/crypto/blobEnvelopeV2.d.ts

@@ -0,0 +1,38 @@
+export declare const BLOB_ENCRYPTED_BYTES_FORMAT = "tearleads.blob.bytes";
+export declare const BLOB_ENCRYPTED_BYTES_VERSION = 2;
+type BlobBytes = Uint8Array<ArrayBuffer>;
+export declare const BLOB_CHUNK_SIZE_BYTES: number;
+export declare const MAX_BLOB_CHUNK_COUNT = 10000;
+export interface BlobEnvelopeV2Header {
+    readonly blobId: string;
+    readonly byteLength: number;
+    readonly chunkCount: number;
+    readonly chunkSize: number;
+    readonly contentKeyEpoch: number;
+    readonly contentRecordId: string;
+    readonly encryptionSuite: string;
+    readonly format: typeof BLOB_ENCRYPTED_BYTES_FORMAT;
+    readonly iv: string;
+    readonly metadataHash: string;
+    readonly nonceDomainHash: string;
+    readonly version: typeof BLOB_ENCRYPTED_BYTES_VERSION;
+}
+export declare const BLOB_ENVELOPE_MAGIC_BYTES: BlobBytes;
+export declare const BLOB_ENVELOPE_PREFIX_BYTES: number;
+export declare function normalizeBlobChunkSize(chunkSize: number): number;
+export declare function computeBlobChunkCount(plaintextByteLength: number, chunkSize: number): number;
+export declare function blobChunkPlaintextByteLength(input: {
+    readonly chunkCount: number;
+    readonly chunkIndex: number;
+    readonly chunkSize: number;
+    readonly plaintextByteLength: number;
+}): number;
+export declare function encodeBlobEnvelopeV2Header(header: BlobEnvelopeV2Header): BlobBytes;
+export declare function computeBlobEncryptedByteLength(input: {
+    readonly chunkCount: number;
+    readonly headerByteLength: number;
+    readonly plaintextByteLength: number;
+}): number;
+export declare function deriveBlobChunkIv(baseIv: Uint8Array, chunkIndex: number): BlobBytes;
+export declare function joinBlobPartBytes(headerBytes: Uint8Array | null, ciphertext: Uint8Array): BlobBytes;
+export {};

package/internal/crypto/blobEnvelopeV2.js

@@ -0,0 +1,100 @@
+import { BlobEnvelopeError } from "./blobEnvelopeError.js";
+import { serializeKeyingCanonicalJson } from "./keying/canonical.js";
+import { AES_GCM_IV_BYTES, AES_GCM_TAG_BYTES } from "./symmetric.js";
+export const BLOB_ENCRYPTED_BYTES_FORMAT = "tearleads.blob.bytes";
+export const BLOB_ENCRYPTED_BYTES_VERSION = 2;
+const BLOB_ENCRYPTED_BYTES_MAGIC = "tearleads.blob.bytes.v2";
+const TEXT_ENCODER = new TextEncoder();
+const HEADER_LENGTH_BYTES = 4;
+export const BLOB_CHUNK_SIZE_BYTES = 5 * 1024 * 1024;
+export const MAX_BLOB_CHUNK_COUNT = 10_000;
+export const BLOB_ENVELOPE_MAGIC_BYTES = TEXT_ENCODER.encode(BLOB_ENCRYPTED_BYTES_MAGIC);
+export const BLOB_ENVELOPE_PREFIX_BYTES = BLOB_ENVELOPE_MAGIC_BYTES.byteLength + HEADER_LENGTH_BYTES;
+function assertSafeLength(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new BlobEnvelopeError(`${label} must be a non-negative safe integer`);
+    }
+}
+export function normalizeBlobChunkSize(chunkSize) {
+    if (chunkSize !== BLOB_CHUNK_SIZE_BYTES) {
+        throw new BlobEnvelopeError("Blob chunk size must be exactly 5 MiB");
+    }
+    return chunkSize;
+}
+export function computeBlobChunkCount(plaintextByteLength, chunkSize) {
+    assertSafeLength(plaintextByteLength, "Blob plaintext byte length");
+    normalizeBlobChunkSize(chunkSize);
+    const chunkCount = Math.max(1, Math.ceil(plaintextByteLength / chunkSize));
+    if (chunkCount > MAX_BLOB_CHUNK_COUNT) {
+        throw new BlobEnvelopeError("Blob chunk count exceeds the multipart upload limit");
+    }
+    return chunkCount;
+}
+export function blobChunkPlaintextByteLength(input) {
+    if (!Number.isInteger(input.chunkIndex) ||
+        input.chunkIndex < 0 ||
+        input.chunkIndex >= input.chunkCount) {
+        throw new BlobEnvelopeError("Blob chunk index is out of range");
+    }
+    if (input.chunkIndex < input.chunkCount - 1) {
+        return input.chunkSize;
+    }
+    return input.plaintextByteLength - input.chunkSize * (input.chunkCount - 1);
+}
+export function encodeBlobEnvelopeV2Header(header) {
+    const headerBytes = TEXT_ENCODER.encode(serializeKeyingCanonicalJson({
+        blobId: header.blobId,
+        byteLength: header.byteLength,
+        chunkCount: header.chunkCount,
+        chunkSize: header.chunkSize,
+        contentKeyEpoch: header.contentKeyEpoch,
+        contentRecordId: header.contentRecordId,
+        encryptionSuite: header.encryptionSuite,
+        format: header.format,
+        iv: header.iv,
+        metadataHash: header.metadataHash,
+        nonceDomainHash: header.nonceDomainHash,
+        version: header.version,
+    }));
+    if (headerBytes.byteLength > 0xffff_ffff) {
+        throw new BlobEnvelopeError("Blob envelope header is too large");
+    }
+    const encoded = new Uint8Array(BLOB_ENVELOPE_PREFIX_BYTES + headerBytes.byteLength);
+    encoded.set(BLOB_ENVELOPE_MAGIC_BYTES);
+    new DataView(encoded.buffer).setUint32(BLOB_ENVELOPE_MAGIC_BYTES.byteLength, headerBytes.byteLength);
+    encoded.set(headerBytes, BLOB_ENVELOPE_PREFIX_BYTES);
+    return encoded;
+}
+export function computeBlobEncryptedByteLength(input) {
+    const encryptedByteLength = input.headerByteLength +
+        input.plaintextByteLength +
+        input.chunkCount * AES_GCM_TAG_BYTES;
+    assertSafeLength(encryptedByteLength, "Blob encrypted byte length");
+    return encryptedByteLength;
+}
+export function deriveBlobChunkIv(baseIv, chunkIndex) {
+    if (baseIv.byteLength !== AES_GCM_IV_BYTES) {
+        throw new BlobEnvelopeError("Blob base IV must be 12 bytes");
+    }
+    if (!Number.isInteger(chunkIndex) ||
+        chunkIndex < 0 ||
+        chunkIndex > 0xffff_ffff) {
+        throw new BlobEnvelopeError("Blob chunk index exceeds the AES-GCM nonce space");
+    }
+    const iv = new Uint8Array(baseIv);
+    iv[8] = (iv[8] ?? 0) ^ ((chunkIndex >>> 24) & 0xff);
+    iv[9] = (iv[9] ?? 0) ^ ((chunkIndex >>> 16) & 0xff);
+    iv[10] = (iv[10] ?? 0) ^ ((chunkIndex >>> 8) & 0xff);
+    iv[11] = (iv[11] ?? 0) ^ (chunkIndex & 0xff);
+    return iv;
+}
+export function joinBlobPartBytes(headerBytes, ciphertext) {
+    if (!headerBytes) {
+        return new Uint8Array(ciphertext);
+    }
+    const part = new Uint8Array(headerBytes.byteLength + ciphertext.byteLength);
+    part.set(headerBytes);
+    part.set(ciphertext, headerBytes.byteLength);
+    return part;
+}
+//# sourceMappingURL=blobEnvelopeV2.js.map

package/internal/crypto/blobEnvelopeV2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blobEnvelopeV2.js","sourceRoot":"","sources":["blobEnvelopeV2.ts"],"names":[],"mappings":"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","sourcesContent":["import { BlobEnvelopeError } from \"./blobEnvelopeError\";\nimport { serializeKeyingCanonicalJson } from \"./keying/canonical\";\nimport type { KeyingCanonicalJson } from \"./keying/types\";\nimport { AES_GCM_IV_BYTES, AES_GCM_TAG_BYTES } from \"./symmetric\";\n\nexport const BLOB_ENCRYPTED_BYTES_FORMAT = \"tearleads.blob.bytes\";\nexport const BLOB_ENCRYPTED_BYTES_VERSION = 2;\nconst BLOB_ENCRYPTED_BYTES_MAGIC = \"tearleads.blob.bytes.v2\";\nconst TEXT_ENCODER = new TextEncoder();\ntype BlobBytes = Uint8Array<ArrayBuffer>;\n\nconst HEADER_LENGTH_BYTES = 4;\nexport const BLOB_CHUNK_SIZE_BYTES = 5 * 1024 * 1024;\nexport const MAX_BLOB_CHUNK_COUNT = 10_000;\n\nexport interface BlobEnvelopeV2Header {\n  readonly blobId: string;\n  readonly byteLength: number;\n  readonly chunkCount: number;\n  readonly chunkSize: number;\n  readonly contentKeyEpoch: number;\n  readonly contentRecordId: string;\n  readonly encryptionSuite: string;\n  readonly format: typeof BLOB_ENCRYPTED_BYTES_FORMAT;\n  readonly iv: string;\n  readonly metadataHash: string;\n  readonly nonceDomainHash: string;\n  readonly version: typeof BLOB_ENCRYPTED_BYTES_VERSION;\n}\n\nexport const BLOB_ENVELOPE_MAGIC_BYTES: BlobBytes = TEXT_ENCODER.encode(\n  BLOB_ENCRYPTED_BYTES_MAGIC,\n);\nexport const BLOB_ENVELOPE_PREFIX_BYTES =\n  BLOB_ENVELOPE_MAGIC_BYTES.byteLength + HEADER_LENGTH_BYTES;\n\nfunction assertSafeLength(value: number, label: string): void {\n  if (!Number.isSafeInteger(value) || value < 0) {\n    throw new BlobEnvelopeError(`${label} must be a non-negative safe integer`);\n  }\n}\n\nexport function normalizeBlobChunkSize(chunkSize: number): number {\n  if (chunkSize !== BLOB_CHUNK_SIZE_BYTES) {\n    throw new BlobEnvelopeError(\"Blob chunk size must be exactly 5 MiB\");\n  }\n  return chunkSize;\n}\n\nexport function computeBlobChunkCount(\n  plaintextByteLength: number,\n  chunkSize: number,\n): number {\n  assertSafeLength(plaintextByteLength, \"Blob plaintext byte length\");\n  normalizeBlobChunkSize(chunkSize);\n  const chunkCount = Math.max(1, Math.ceil(plaintextByteLength / chunkSize));\n  if (chunkCount > MAX_BLOB_CHUNK_COUNT) {\n    throw new BlobEnvelopeError(\n      \"Blob chunk count exceeds the multipart upload limit\",\n    );\n  }\n  return chunkCount;\n}\n\nexport function blobChunkPlaintextByteLength(input: {\n  readonly chunkCount: number;\n  readonly chunkIndex: number;\n  readonly chunkSize: number;\n  readonly plaintextByteLength: number;\n}): number {\n  if (\n    !Number.isInteger(input.chunkIndex) ||\n    input.chunkIndex < 0 ||\n    input.chunkIndex >= input.chunkCount\n  ) {\n    throw new BlobEnvelopeError(\"Blob chunk index is out of range\");\n  }\n  if (input.chunkIndex < input.chunkCount - 1) {\n    return input.chunkSize;\n  }\n  return input.plaintextByteLength - input.chunkSize * (input.chunkCount - 1);\n}\n\nexport function encodeBlobEnvelopeV2Header(\n  header: BlobEnvelopeV2Header,\n): BlobBytes {\n  const headerBytes = TEXT_ENCODER.encode(\n    serializeKeyingCanonicalJson({\n      blobId: header.blobId,\n      byteLength: header.byteLength,\n      chunkCount: header.chunkCount,\n      chunkSize: header.chunkSize,\n      contentKeyEpoch: header.contentKeyEpoch,\n      contentRecordId: header.contentRecordId,\n      encryptionSuite: header.encryptionSuite,\n      format: header.format,\n      iv: header.iv,\n      metadataHash: header.metadataHash,\n      nonceDomainHash: header.nonceDomainHash,\n      version: header.version,\n    } satisfies Record<string, KeyingCanonicalJson>),\n  );\n  if (headerBytes.byteLength > 0xffff_ffff) {\n    throw new BlobEnvelopeError(\"Blob envelope header is too large\");\n  }\n\n  const encoded = new Uint8Array(\n    BLOB_ENVELOPE_PREFIX_BYTES + headerBytes.byteLength,\n  );\n  encoded.set(BLOB_ENVELOPE_MAGIC_BYTES);\n  new DataView(encoded.buffer).setUint32(\n    BLOB_ENVELOPE_MAGIC_BYTES.byteLength,\n    headerBytes.byteLength,\n  );\n  encoded.set(headerBytes, BLOB_ENVELOPE_PREFIX_BYTES);\n  return encoded;\n}\n\nexport function computeBlobEncryptedByteLength(input: {\n  readonly chunkCount: number;\n  readonly headerByteLength: number;\n  readonly plaintextByteLength: number;\n}): number {\n  const encryptedByteLength =\n    input.headerByteLength +\n    input.plaintextByteLength +\n    input.chunkCount * AES_GCM_TAG_BYTES;\n  assertSafeLength(encryptedByteLength, \"Blob encrypted byte length\");\n  return encryptedByteLength;\n}\n\nexport function deriveBlobChunkIv(\n  baseIv: Uint8Array,\n  chunkIndex: number,\n): BlobBytes {\n  if (baseIv.byteLength !== AES_GCM_IV_BYTES) {\n    throw new BlobEnvelopeError(\"Blob base IV must be 12 bytes\");\n  }\n  if (\n    !Number.isInteger(chunkIndex) ||\n    chunkIndex < 0 ||\n    chunkIndex > 0xffff_ffff\n  ) {\n    throw new BlobEnvelopeError(\n      \"Blob chunk index exceeds the AES-GCM nonce space\",\n    );\n  }\n\n  const iv = new Uint8Array(baseIv);\n  iv[8] = (iv[8] ?? 0) ^ ((chunkIndex >>> 24) & 0xff);\n  iv[9] = (iv[9] ?? 0) ^ ((chunkIndex >>> 16) & 0xff);\n  iv[10] = (iv[10] ?? 0) ^ ((chunkIndex >>> 8) & 0xff);\n  iv[11] = (iv[11] ?? 0) ^ (chunkIndex & 0xff);\n  return iv;\n}\n\nexport function joinBlobPartBytes(\n  headerBytes: Uint8Array | null,\n  ciphertext: Uint8Array,\n): BlobBytes {\n  if (!headerBytes) {\n    return new Uint8Array(ciphertext);\n  }\n  const part = new Uint8Array(headerBytes.byteLength + ciphertext.byteLength);\n  part.set(headerBytes);\n  part.set(ciphertext, headerBytes.byteLength);\n  return part;\n}\n"]}

package/internal/crypto/canonicalOrdering.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Code-unit string order. Every hash, root, and signed encoding in this package
+ * sorts with this comparator so that two runtimes with different locales
+ * produce byte-identical canonical forms. `localeCompare` and `Intl.Collator`
+ * are banned from hash-adjacent code by `scripts/checks/lintCanonicalOrdering.ts`.
+ */
+export declare function compareCanonicalStrings(left: string, right: string): number;

package/internal/crypto/canonicalOrdering.js

@@ -0,0 +1,10 @@
+/**
+ * Code-unit string order. Every hash, root, and signed encoding in this package
+ * sorts with this comparator so that two runtimes with different locales
+ * produce byte-identical canonical forms. `localeCompare` and `Intl.Collator`
+ * are banned from hash-adjacent code by `scripts/checks/lintCanonicalOrdering.ts`.
+ */
+export function compareCanonicalStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+//# sourceMappingURL=canonicalOrdering.js.map

package/internal/crypto/canonicalOrdering.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalOrdering.js","sourceRoot":"","sources":["canonicalOrdering.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAY,EAAE,KAAa;IACjE,OAAO,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClD,CAAC","sourcesContent":["/**\n * Code-unit string order. Every hash, root, and signed encoding in this package\n * sorts with this comparator so that two runtimes with different locales\n * produce byte-identical canonical forms. `localeCompare` and `Intl.Collator`\n * are banned from hash-adjacent code by `scripts/checks/lintCanonicalOrdering.ts`.\n */\nexport function compareCanonicalStrings(left: string, right: string): number {\n  return left < right ? -1 : left > right ? 1 : 0;\n}\n"]}

package/internal/crypto/challenge.d.ts

@@ -0,0 +1,16 @@
+export declare const AUTH_CHALLENGE_BYTES = 32;
+export declare const AUTH_CHALLENGE_HEX_LENGTH: number;
+export declare const CHALLENGE_TTL_SECONDS = 60;
+export declare function generateChallenge(length?: number): Uint8Array;
+/**
+ * The canonical `scheme://host[:port]` a login challenge is signed for. Both
+ * sides derive it themselves: the client from the API it means to reach, the
+ * API from its own public origin, so a challenge relayed from another API was
+ * signed for the wrong origin and never verifies (#2365 finding 25).
+ */
+export declare function canonicalAuthOrigin(value: string): string;
+export declare function authChallengeSigningBytes(input: {
+    apiOrigin: string;
+    challengeHex: string;
+    fingerprint: string;
+}): Uint8Array;

package/internal/crypto/challenge.js

@@ -0,0 +1,53 @@
+import { randomBytes } from "@noble/post-quantum/utils.js";
+import { serializeKeyingCanonicalJson } from "./keying.js";
+const TEXT_ENCODER = new TextEncoder();
+export const AUTH_CHALLENGE_BYTES = 32;
+export const AUTH_CHALLENGE_HEX_LENGTH = AUTH_CHALLENGE_BYTES * 2;
+export const CHALLENGE_TTL_SECONDS = 60;
+export function generateChallenge(length = AUTH_CHALLENGE_BYTES) {
+    if (!Number.isInteger(length) || length <= 0) {
+        throw new Error("Challenge length must be a positive integer");
+    }
+    return randomBytes(length);
+}
+/**
+ * The canonical `scheme://host[:port]` a login challenge is signed for. Both
+ * sides derive it themselves: the client from the API it means to reach, the
+ * API from its own public origin, so a challenge relayed from another API was
+ * signed for the wrong origin and never verifies (#2365 finding 25).
+ */
+export function canonicalAuthOrigin(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error("Authentication origin must be an absolute URL");
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error("Authentication origin must use http or https");
+    }
+    return url.origin;
+}
+export function authChallengeSigningBytes(input) {
+    if (canonicalAuthOrigin(input.apiOrigin) !== input.apiOrigin) {
+        throw new Error("Authentication origin must be canonical");
+    }
+    if (!/^[0-9a-f]{64}$/.test(input.fingerprint)) {
+        throw new Error("Authentication fingerprint must be a SHA-256 hex string");
+    }
+    if (typeof input.challengeHex !== "string" ||
+        input.challengeHex.length !== AUTH_CHALLENGE_HEX_LENGTH ||
+        !/^[0-9a-f]+$/.test(input.challengeHex)) {
+        throw new Error("Authentication challenge must be canonical hex");
+    }
+    return TEXT_ENCODER.encode(serializeKeyingCanonicalJson({
+        domain: "tearleads.auth.challenge.v2",
+        payload: {
+            apiOrigin: input.apiOrigin,
+            challenge: input.challengeHex,
+            fingerprint: input.fingerprint,
+        },
+    }));
+}
+//# sourceMappingURL=challenge.js.map

package/internal/crypto/challenge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"challenge.js","sourceRoot":"","sources":["challenge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC3D,OAAO,EAAE,4BAA4B,EAAE,MAAM,UAAU,CAAC;AAExD,MAAM,YAAY,GAAG,IAAI,WAAW,EAAE,CAAC;AAEvC,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AACvC,MAAM,CAAC,MAAM,yBAAyB,GAAG,oBAAoB,GAAG,CAAC,CAAC;AAClE,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAExC,MAAM,UAAU,iBAAiB,CAAC,MAAM,GAAG,oBAAoB;IAC7D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;IAED,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,KAIzC;IACC,IAAI,mBAAmB,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,KAAK,CAAC,SAAS,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IACD,IACE,OAAO,KAAK,CAAC,YAAY,KAAK,QAAQ;QACtC,KAAK,CAAC,YAAY,CAAC,MAAM,KAAK,yBAAyB;QACvD,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,EACvC,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,CAAC;IAED,OAAO,YAAY,CAAC,MAAM,CACxB,4BAA4B,CAAC;QAC3B,MAAM,EAAE,6BAA6B;QACrC,OAAO,EAAE;YACP,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,SAAS,EAAE,KAAK,CAAC,YAAY;YAC7B,WAAW,EAAE,KAAK,CAAC,WAAW;SAC/B;KACF,CAAC,CACH,CAAC;AACJ,CAAC","sourcesContent":["import { randomBytes } from \"@noble/post-quantum/utils.js\";\nimport { serializeKeyingCanonicalJson } from \"./keying\";\n\nconst TEXT_ENCODER = new TextEncoder();\n\nexport const AUTH_CHALLENGE_BYTES = 32;\nexport const AUTH_CHALLENGE_HEX_LENGTH = AUTH_CHALLENGE_BYTES * 2;\nexport const CHALLENGE_TTL_SECONDS = 60;\n\nexport function generateChallenge(length = AUTH_CHALLENGE_BYTES): Uint8Array {\n  if (!Number.isInteger(length) || length <= 0) {\n    throw new Error(\"Challenge length must be a positive integer\");\n  }\n\n  return randomBytes(length);\n}\n\n/**\n * The canonical `scheme://host[:port]` a login challenge is signed for. Both\n * sides derive it themselves: the client from the API it means to reach, the\n * API from its own public origin, so a challenge relayed from another API was\n * signed for the wrong origin and never verifies (#2365 finding 25).\n */\nexport function canonicalAuthOrigin(value: string): string {\n  let url: URL;\n  try {\n    url = new URL(value);\n  } catch {\n    throw new Error(\"Authentication origin must be an absolute URL\");\n  }\n  if (url.protocol !== \"https:\" && url.protocol !== \"http:\") {\n    throw new Error(\"Authentication origin must use http or https\");\n  }\n  return url.origin;\n}\n\nexport function authChallengeSigningBytes(input: {\n  apiOrigin: string;\n  challengeHex: string;\n  fingerprint: string;\n}): Uint8Array {\n  if (canonicalAuthOrigin(input.apiOrigin) !== input.apiOrigin) {\n    throw new Error(\"Authentication origin must be canonical\");\n  }\n  if (!/^[0-9a-f]{64}$/.test(input.fingerprint)) {\n    throw new Error(\"Authentication fingerprint must be a SHA-256 hex string\");\n  }\n  if (\n    typeof input.challengeHex !== \"string\" ||\n    input.challengeHex.length !== AUTH_CHALLENGE_HEX_LENGTH ||\n    !/^[0-9a-f]+$/.test(input.challengeHex)\n  ) {\n    throw new Error(\"Authentication challenge must be canonical hex\");\n  }\n\n  return TEXT_ENCODER.encode(\n    serializeKeyingCanonicalJson({\n      domain: \"tearleads.auth.challenge.v2\",\n      payload: {\n        apiOrigin: input.apiOrigin,\n        challenge: input.challengeHex,\n        fingerprint: input.fingerprint,\n      },\n    }),\n  );\n}\n"]}

package/internal/crypto/contentKeyEnvelope.d.ts

@@ -0,0 +1,48 @@
+import { type SymmetricCiphertext } from "./symmetric.js";
+export declare class ContentKeyEnvelopeError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Where an envelope came from; a submission is held to the published shape. */
+export type ContentKeyEnvelopeOrigin = "stored" | "submission";
+/** The object an envelope wraps a content key for. */
+export type ContentKeyEnvelopeKind = "Blob" | "Document";
+/** What a content-key wrap is bound to: its object, key epoch and target. */
+export interface ContentKeyWrapBinding {
+    readonly kind: ContentKeyEnvelopeKind;
+    /** The document id, or the blob id for an attachment key. */
+    readonly objectId: string;
+    readonly contentKeyEpoch: number;
+    readonly containerId: string;
+    readonly containerKeyEpochId: string;
+}
+/** Seal a content key to one target's container KEK, bound to its object. */
+export declare function wrapContentKey(contentKey: Uint8Array, containerKek: Uint8Array, binding: ContentKeyWrapBinding): Promise<SymmetricCiphertext>;
+/** Open a content-key wrap; it fails unless the binding matches its sealing. */
+export declare function unwrapContentKey(wrapped: SymmetricCiphertext, containerKek: Uint8Array, binding: ContentKeyWrapBinding): Promise<Uint8Array>;
+/** Checks public envelope structure only; authentication still requires the KEK. */
+export declare function decodeContentKeyEnvelope(input: {
+    readonly envelope: {
+        readonly wrappedKey: string;
+        readonly wrappingMetadata?: unknown;
+    };
+    readonly kind: ContentKeyEnvelopeKind;
+    /**
+     * The two modes differ in exactly one respect: `submission` requires the
+     * metadata to carry `suite` and `iv` and nothing else, while `stored`
+     * ignores an unrecognized extra key so a newer writer's envelope never
+     * becomes unreadable. Every other check — the suite, and the canonical
+     * base64 encoding and byte length of the IV and wrapped key — is applied
+     * identically, so a submission that passes is always readable later.
+     *
+     * `stored` is nonetheless stricter than simply decoding the base64, which
+     * is what the client did before. That is deliberate and does not reopen the
+     * lockout: the IV and key sizes are fixed by the suite, so a row that fails
+     * them is malformed rather than newer, and a canonical encoding is what
+     * makes comparing wrapped keys as strings — how a retained wrap is
+     * recognized — mean comparing the bytes.
+     */
+    readonly origin: ContentKeyEnvelopeOrigin;
+}): {
+    readonly iv: Uint8Array;
+    readonly ciphertext: Uint8Array;
+};

package/internal/crypto/contentKeyEnvelope.js

@@ -0,0 +1,96 @@
+import { base64ToBytes, bytesToBase64 } from "../encoding/index.js";
+import { isPlainObject } from "../validators/isPlainObject.js";
+import { serializeKeyingCanonicalJson } from "./keying/canonical.js";
+import { assertExactKeys } from "./keying/shared.js";
+import { BLOB_CONTENT_KEY_WRAP_SUITE, DOCUMENT_CONTENT_KEY_WRAP_SUITE, } from "./keying/types.js";
+import { AES_256_KEY_BYTES, AES_GCM_IV_BYTES, AES_GCM_TAG_BYTES, decryptWithDek, encryptWithDek, } from "./symmetric.js";
+const TEXT_ENCODER = new TextEncoder();
+export class ContentKeyEnvelopeError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ContentKeyEnvelopeError";
+    }
+}
+function decodeFixedBase64(value, size, label) {
+    if (value.length !== 4 * Math.ceil(size / 3)) {
+        throw new ContentKeyEnvelopeError(`${label} has an invalid encoded length`);
+    }
+    let bytes;
+    try {
+        bytes = base64ToBytes(value);
+    }
+    catch (error) {
+        throw new ContentKeyEnvelopeError(`${label} must use canonical base64`, {
+            cause: error,
+        });
+    }
+    if (bytes.length !== size || bytesToBase64(bytes) !== value) {
+        throw new ContentKeyEnvelopeError(`${label} must encode exactly ${size} bytes in canonical base64`);
+    }
+    return bytes;
+}
+/**
+ * The suite is derived from the kind rather than accepted alongside it, so a
+ * caller cannot pair one kind's label with the other's suite. The target hash
+ * covers neither the wrapped key nor its metadata; the wrap's authenticated
+ * data binds the envelope to its object instead.
+ */
+const CONTENT_KEY_WRAP_SUITES = {
+    Blob: BLOB_CONTENT_KEY_WRAP_SUITE,
+    Document: DOCUMENT_CONTENT_KEY_WRAP_SUITE,
+};
+/**
+ * Authenticated data for a content-key wrap. Blob and document keys are
+ * sealed to the same container KEK, so without it a server could serve one
+ * object's wrap in another's bundle, or at another epoch or target, and it
+ * would still open.
+ */
+function contentKeyWrapAssociatedData(binding) {
+    return TEXT_ENCODER.encode(serializeKeyingCanonicalJson({
+        domain: "tearleads.content-key-wrap.aad",
+        payload: {
+            version: 1,
+            suite: CONTENT_KEY_WRAP_SUITES[binding.kind],
+            objectId: binding.objectId,
+            contentKeyEpoch: binding.contentKeyEpoch,
+            containerId: binding.containerId,
+            containerKeyEpochId: binding.containerKeyEpochId,
+        },
+    }));
+}
+/** Seal a content key to one target's container KEK, bound to its object. */
+export function wrapContentKey(contentKey, containerKek, binding) {
+    return encryptWithDek(contentKey, containerKek, contentKeyWrapAssociatedData(binding));
+}
+/** Open a content-key wrap; it fails unless the binding matches its sealing. */
+export function unwrapContentKey(wrapped, containerKek, binding) {
+    return decryptWithDek(wrapped, containerKek, contentKeyWrapAssociatedData(binding));
+}
+/** Checks public envelope structure only; authentication still requires the KEK. */
+export function decodeContentKeyEnvelope(input) {
+    const label = `${input.kind} content-key target`;
+    const raw = input.envelope.wrappingMetadata;
+    if (!isPlainObject(raw)) {
+        throw new ContentKeyEnvelopeError(`${label} is missing wrap metadata`);
+    }
+    if (input.origin === "submission") {
+        try {
+            assertExactKeys(raw, ["iv", "suite"], label);
+        }
+        catch (error) {
+            throw new ContentKeyEnvelopeError(`${label} metadata must contain exactly suite and iv`, { cause: error });
+        }
+    }
+    if (Reflect.get(raw, "suite") !== CONTENT_KEY_WRAP_SUITES[input.kind]) {
+        throw new ContentKeyEnvelopeError(`${label} uses an unknown suite`);
+    }
+    const iv = Reflect.get(raw, "iv");
+    if (typeof iv !== "string") {
+        throw new ContentKeyEnvelopeError(`${label} is missing an IV`);
+    }
+    return {
+        iv: decodeFixedBase64(iv, AES_GCM_IV_BYTES, `${label} IV`),
+        ciphertext: decodeFixedBase64(input.envelope.wrappedKey, AES_256_KEY_BYTES + AES_GCM_TAG_BYTES, `${label} wrapped key`),
+    };
+}
+//# sourceMappingURL=contentKeyEnvelope.js.map

package/internal/crypto/contentKeyEnvelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contentKeyEnvelope.js","sourceRoot":"","sources":["contentKeyEnvelope.ts"],"names":[],"mappings":"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","sourcesContent":["import { base64ToBytes, bytesToBase64 } from \"@tearleads/encoding\";\nimport { isPlainObject } from \"@tearleads/validators/isPlainObject\";\nimport { serializeKeyingCanonicalJson } from \"./keying/canonical\";\nimport { assertExactKeys } from \"./keying/shared\";\nimport {\n  BLOB_CONTENT_KEY_WRAP_SUITE,\n  DOCUMENT_CONTENT_KEY_WRAP_SUITE,\n} from \"./keying/types\";\nimport {\n  AES_256_KEY_BYTES,\n  AES_GCM_IV_BYTES,\n  AES_GCM_TAG_BYTES,\n  decryptWithDek,\n  encryptWithDek,\n  type SymmetricCiphertext,\n} from \"./symmetric\";\n\nconst TEXT_ENCODER = new TextEncoder();\n\nexport class ContentKeyEnvelopeError extends Error {\n  constructor(message: string, options?: ErrorOptions) {\n    super(message, options);\n    this.name = \"ContentKeyEnvelopeError\";\n  }\n}\n\nfunction decodeFixedBase64(\n  value: string,\n  size: number,\n  label: string,\n): Uint8Array {\n  if (value.length !== 4 * Math.ceil(size / 3)) {\n    throw new ContentKeyEnvelopeError(`${label} has an invalid encoded length`);\n  }\n  let bytes: Uint8Array;\n  try {\n    bytes = base64ToBytes(value);\n  } catch (error) {\n    throw new ContentKeyEnvelopeError(`${label} must use canonical base64`, {\n      cause: error,\n    });\n  }\n  if (bytes.length !== size || bytesToBase64(bytes) !== value) {\n    throw new ContentKeyEnvelopeError(\n      `${label} must encode exactly ${size} bytes in canonical base64`,\n    );\n  }\n  return bytes;\n}\n\n/** Where an envelope came from; a submission is held to the published shape. */\nexport type ContentKeyEnvelopeOrigin = \"stored\" | \"submission\";\n\n/** The object an envelope wraps a content key for. */\nexport type ContentKeyEnvelopeKind = \"Blob\" | \"Document\";\n\n/**\n * The suite is derived from the kind rather than accepted alongside it, so a\n * caller cannot pair one kind's label with the other's suite. The target hash\n * covers neither the wrapped key nor its metadata; the wrap's authenticated\n * data binds the envelope to its object instead.\n */\nconst CONTENT_KEY_WRAP_SUITES = {\n  Blob: BLOB_CONTENT_KEY_WRAP_SUITE,\n  Document: DOCUMENT_CONTENT_KEY_WRAP_SUITE,\n} as const;\n\n/** What a content-key wrap is bound to: its object, key epoch and target. */\nexport interface ContentKeyWrapBinding {\n  readonly kind: ContentKeyEnvelopeKind;\n  /** The document id, or the blob id for an attachment key. */\n  readonly objectId: string;\n  readonly contentKeyEpoch: number;\n  readonly containerId: string;\n  readonly containerKeyEpochId: string;\n}\n\n/**\n * Authenticated data for a content-key wrap. Blob and document keys are\n * sealed to the same container KEK, so without it a server could serve one\n * object's wrap in another's bundle, or at another epoch or target, and it\n * would still open.\n */\nfunction contentKeyWrapAssociatedData(\n  binding: ContentKeyWrapBinding,\n): Uint8Array<ArrayBuffer> {\n  return TEXT_ENCODER.encode(\n    serializeKeyingCanonicalJson({\n      domain: \"tearleads.content-key-wrap.aad\",\n      payload: {\n        version: 1,\n        suite: CONTENT_KEY_WRAP_SUITES[binding.kind],\n        objectId: binding.objectId,\n        contentKeyEpoch: binding.contentKeyEpoch,\n        containerId: binding.containerId,\n        containerKeyEpochId: binding.containerKeyEpochId,\n      },\n    }),\n  );\n}\n\n/** Seal a content key to one target's container KEK, bound to its object. */\nexport function wrapContentKey(\n  contentKey: Uint8Array,\n  containerKek: Uint8Array,\n  binding: ContentKeyWrapBinding,\n): Promise<SymmetricCiphertext> {\n  return encryptWithDek(\n    contentKey,\n    containerKek,\n    contentKeyWrapAssociatedData(binding),\n  );\n}\n\n/** Open a content-key wrap; it fails unless the binding matches its sealing. */\nexport function unwrapContentKey(\n  wrapped: SymmetricCiphertext,\n  containerKek: Uint8Array,\n  binding: ContentKeyWrapBinding,\n): Promise<Uint8Array> {\n  return decryptWithDek(\n    wrapped,\n    containerKek,\n    contentKeyWrapAssociatedData(binding),\n  );\n}\n\n/** Checks public envelope structure only; authentication still requires the KEK. */\nexport function decodeContentKeyEnvelope(input: {\n  readonly envelope: {\n    readonly wrappedKey: string;\n    readonly wrappingMetadata?: unknown;\n  };\n  readonly kind: ContentKeyEnvelopeKind;\n  /**\n   * The two modes differ in exactly one respect: `submission` requires the\n   * metadata to carry `suite` and `iv` and nothing else, while `stored`\n   * ignores an unrecognized extra key so a newer writer's envelope never\n   * becomes unreadable. Every other check — the suite, and the canonical\n   * base64 encoding and byte length of the IV and wrapped key — is applied\n   * identically, so a submission that passes is always readable later.\n   *\n   * `stored` is nonetheless stricter than simply decoding the base64, which\n   * is what the client did before. That is deliberate and does not reopen the\n   * lockout: the IV and key sizes are fixed by the suite, so a row that fails\n   * them is malformed rather than newer, and a canonical encoding is what\n   * makes comparing wrapped keys as strings — how a retained wrap is\n   * recognized — mean comparing the bytes.\n   */\n  readonly origin: ContentKeyEnvelopeOrigin;\n}): { readonly iv: Uint8Array; readonly ciphertext: Uint8Array } {\n  const label = `${input.kind} content-key target`;\n  const raw = input.envelope.wrappingMetadata;\n  if (!isPlainObject(raw)) {\n    throw new ContentKeyEnvelopeError(`${label} is missing wrap metadata`);\n  }\n  if (input.origin === \"submission\") {\n    try {\n      assertExactKeys(raw, [\"iv\", \"suite\"], label);\n    } catch (error) {\n      throw new ContentKeyEnvelopeError(\n        `${label} metadata must contain exactly suite and iv`,\n        { cause: error },\n      );\n    }\n  }\n  if (Reflect.get(raw, \"suite\") !== CONTENT_KEY_WRAP_SUITES[input.kind]) {\n    throw new ContentKeyEnvelopeError(`${label} uses an unknown suite`);\n  }\n  const iv = Reflect.get(raw, \"iv\");\n  if (typeof iv !== \"string\") {\n    throw new ContentKeyEnvelopeError(`${label} is missing an IV`);\n  }\n  return {\n    iv: decodeFixedBase64(iv, AES_GCM_IV_BYTES, `${label} IV`),\n    ciphertext: decodeFixedBase64(\n      input.envelope.wrappedKey,\n      AES_256_KEY_BYTES + AES_GCM_TAG_BYTES,\n      `${label} wrapped key`,\n    ),\n  };\n}\n"]}

package/internal/crypto/encapsulation/decryptAsRecipient.d.ts

@@ -0,0 +1,6 @@
+import type { EncryptedEnvelope } from "./types.js";
+/**
+ * Decrypt an envelope using a recipient's ML-KEM secret key.
+ * Finds the matching recipient entry by key fingerprint lookup.
+ */
+export declare function decryptAsRecipient(envelope: EncryptedEnvelope, secretKey: Uint8Array): Promise<Uint8Array<ArrayBuffer>>;

package/internal/crypto/encapsulation/decryptAsRecipient.js

@@ -0,0 +1,44 @@
+import { ml_kem1024 } from "@noble/post-quantum/ml-kem.js";
+import { toFingerprint } from "../fingerprint.js";
+import { AES_256_KEY_BYTES, AES_GCM_IV_BYTES, AES_GCM_TAG_BYTES, } from "../symmetric.js";
+import { ML_KEM1024_CIPHERTEXT_BYTES, ML_KEM1024_PUBLIC_KEY_BYTES, ML_KEM1024_SECRET_KEY_BYTES, } from "./generateKeyPair.js";
+/** ML-KEM-1024 secret key layout: dk_pke (1536 bytes) || ek_pke (1568 bytes) || H(ek) || z */
+const ML_KEM1024_PK_OFFSET = 1536;
+/**
+ * Decrypt an envelope using a recipient's ML-KEM secret key.
+ * Finds the matching recipient entry by key fingerprint lookup.
+ */
+export async function decryptAsRecipient(envelope, secretKey) {
+    if (secretKey.length !== ML_KEM1024_SECRET_KEY_BYTES) {
+        throw new Error("ML-KEM-1024 secret key has invalid length");
+    }
+    if (envelope.iv.length !== AES_GCM_IV_BYTES) {
+        throw new Error("Encrypted envelope IV has invalid length");
+    }
+    if (envelope.ciphertext.length < AES_GCM_TAG_BYTES) {
+        throw new Error("Encrypted envelope ciphertext is too short");
+    }
+    const publicKey = secretKey.slice(ML_KEM1024_PK_OFFSET, ML_KEM1024_PK_OFFSET + ML_KEM1024_PUBLIC_KEY_BYTES);
+    const keyFingerprint = await toFingerprint(publicKey);
+    const recipient = envelope.recipients.find((r) => r.keyFingerprint === keyFingerprint);
+    if (!recipient) {
+        throw new Error("No matching recipient entry found for this secret key");
+    }
+    const { kemCipherText, wrappedKey } = recipient;
+    if (kemCipherText.length !== ML_KEM1024_CIPHERTEXT_BYTES) {
+        throw new Error("Recipient KEM ciphertext has invalid length");
+    }
+    if (wrappedKey.length < AES_GCM_TAG_BYTES) {
+        throw new Error("Wrapped payload key ciphertext is too short");
+    }
+    const sharedSecret = ml_kem1024.decapsulate(kemCipherText, secretKey);
+    const wrappingKey = await crypto.subtle.importKey("raw", sharedSecret.slice(), "AES-GCM", false, ["decrypt"]);
+    const wrappedKeyIv = kemCipherText.slice(0, AES_GCM_IV_BYTES);
+    const payloadKey = new Uint8Array(await crypto.subtle.decrypt({ name: "AES-GCM", iv: wrappedKeyIv }, wrappingKey, wrappedKey.slice()));
+    if (payloadKey.length !== AES_256_KEY_BYTES) {
+        throw new Error("Wrapped payload key has invalid length");
+    }
+    const aesKey = await crypto.subtle.importKey("raw", payloadKey.slice(), "AES-GCM", false, ["decrypt"]);
+    return new Uint8Array(await crypto.subtle.decrypt({ name: "AES-GCM", iv: envelope.iv.slice() }, aesKey, envelope.ciphertext.slice()));
+}
+//# sourceMappingURL=decryptAsRecipient.js.map

package/internal/crypto/encapsulation/decryptAsRecipient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decryptAsRecipient.js","sourceRoot":"","sources":["decryptAsRecipient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,2BAA2B,EAC3B,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC;AAG3B,8FAA8F;AAC9F,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAElC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,QAA2B,EAC3B,SAAqB;IAErB,IAAI,SAAS,CAAC,MAAM,KAAK,2BAA2B,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,QAAQ,CAAC,EAAE,CAAC,MAAM,KAAK,gBAAgB,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IACD,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;QACnD,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;IAED,MAAM,SAAS,GAAG,SAAS,CAAC,KAAK,CAC/B,oBAAoB,EACpB,oBAAoB,GAAG,2BAA2B,CACnD,CAAC;IACF,MAAM,cAAc,GAAG,MAAM,aAAa,CAAC,SAAS,CAAC,CAAC;IAEtD,MAAM,SAAS,GAAG,QAAQ,CAAC,UAAU,CAAC,IAAI,CACxC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,cAAc,KAAK,cAAc,CAC3C,CAAC;IAEF,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IAED,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,GAAG,SAAS,CAAC;IAChD,IAAI,aAAa,CAAC,MAAM,KAAK,2BAA2B,EAAE,CAAC;QACzD,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,GAAG,iBAAiB,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,YAAY,GAAG,UAAU,CAAC,WAAW,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IAEtE,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CAC/C,KAAK,EACL,YAAY,CAAC,KAAK,EAAE,EACpB,SAAS,EACT,KAAK,EACL,CAAC,SAAS,CAAC,CACZ,CAAC;IACF,MAAM,YAAY,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC;IAC9D,MAAM,UAAU,GAAG,IAAI,UAAU,CAC/B,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,CACzB,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,YAAY,EAAE,EACrC,WAAW,EACX,UAAU,CAAC,KAAK,EAAE,CACnB,CACF,CAAC;IACF,IAAI,UAAU,CAAC,MAAM,KAAK,iBAAiB,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAC5D,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CAC1C,KAAK,EACL,UAAU,CAAC,KAAK,EAAE,EAClB,SAAS,EACT,KAAK,EACL,CAAC,SAAS,CAAC,CACZ,CAAC;IACF,OAAO,IAAI,UAAU,CACnB,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,CACzB,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,EAC5C,MAAM,EACN,QAAQ,CAAC,UAAU,CAAC,KAAK,EAAE,CAC5B,CACF,CAAC;AACJ,CAAC","sourcesContent":["import { ml_kem1024 } from \"@noble/post-quantum/ml-kem.js\";\nimport { toFingerprint } from \"../fingerprint\";\nimport {\n  AES_256_KEY_BYTES,\n  AES_GCM_IV_BYTES,\n  AES_GCM_TAG_BYTES,\n} from \"../symmetric\";\nimport {\n  ML_KEM1024_CIPHERTEXT_BYTES,\n  ML_KEM1024_PUBLIC_KEY_BYTES,\n  ML_KEM1024_SECRET_KEY_BYTES,\n} from \"./generateKeyPair\";\nimport type { EncryptedEnvelope } from \"./types\";\n\n/** ML-KEM-1024 secret key layout: dk_pke (1536 bytes) || ek_pke (1568 bytes) || H(ek) || z */\nconst ML_KEM1024_PK_OFFSET = 1536;\n\n/**\n * Decrypt an envelope using a recipient's ML-KEM secret key.\n * Finds the matching recipient entry by key fingerprint lookup.\n */\nexport async function decryptAsRecipient(\n  envelope: EncryptedEnvelope,\n  secretKey: Uint8Array,\n): Promise<Uint8Array<ArrayBuffer>> {\n  if (secretKey.length !== ML_KEM1024_SECRET_KEY_BYTES) {\n    throw new Error(\"ML-KEM-1024 secret key has invalid length\");\n  }\n  if (envelope.iv.length !== AES_GCM_IV_BYTES) {\n    throw new Error(\"Encrypted envelope IV has invalid length\");\n  }\n  if (envelope.ciphertext.length < AES_GCM_TAG_BYTES) {\n    throw new Error(\"Encrypted envelope ciphertext is too short\");\n  }\n\n  const publicKey = secretKey.slice(\n    ML_KEM1024_PK_OFFSET,\n    ML_KEM1024_PK_OFFSET + ML_KEM1024_PUBLIC_KEY_BYTES,\n  );\n  const keyFingerprint = await toFingerprint(publicKey);\n\n  const recipient = envelope.recipients.find(\n    (r) => r.keyFingerprint === keyFingerprint,\n  );\n\n  if (!recipient) {\n    throw new Error(\"No matching recipient entry found for this secret key\");\n  }\n\n  const { kemCipherText, wrappedKey } = recipient;\n  if (kemCipherText.length !== ML_KEM1024_CIPHERTEXT_BYTES) {\n    throw new Error(\"Recipient KEM ciphertext has invalid length\");\n  }\n  if (wrappedKey.length < AES_GCM_TAG_BYTES) {\n    throw new Error(\"Wrapped payload key ciphertext is too short\");\n  }\n\n  const sharedSecret = ml_kem1024.decapsulate(kemCipherText, secretKey);\n\n  const wrappingKey = await crypto.subtle.importKey(\n    \"raw\",\n    sharedSecret.slice(),\n    \"AES-GCM\",\n    false,\n    [\"decrypt\"],\n  );\n  const wrappedKeyIv = kemCipherText.slice(0, AES_GCM_IV_BYTES);\n  const payloadKey = new Uint8Array(\n    await crypto.subtle.decrypt(\n      { name: \"AES-GCM\", iv: wrappedKeyIv },\n      wrappingKey,\n      wrappedKey.slice(),\n    ),\n  );\n  if (payloadKey.length !== AES_256_KEY_BYTES) {\n    throw new Error(\"Wrapped payload key has invalid length\");\n  }\n\n  const aesKey = await crypto.subtle.importKey(\n    \"raw\",\n    payloadKey.slice(),\n    \"AES-GCM\",\n    false,\n    [\"decrypt\"],\n  );\n  return new Uint8Array(\n    await crypto.subtle.decrypt(\n      { name: \"AES-GCM\", iv: envelope.iv.slice() },\n      aesKey,\n      envelope.ciphertext.slice(),\n    ),\n  );\n}\n"]}

package/internal/crypto/encapsulation/encryptForRecipients.d.ts

@@ -0,0 +1,6 @@
+import type { EncryptedEnvelope } from "./types.js";
+/**
+ * Encrypt a payload so that multiple recipients can each independently decrypt it.
+ * Uses ML-KEM-1024 (FIPS 203) for key encapsulation and AES-256-GCM for payload encryption.
+ */
+export declare function encryptForRecipients(plaintext: Uint8Array, recipientPublicKeys: Uint8Array[]): Promise<EncryptedEnvelope>;

package/internal/crypto/encapsulation/encryptForRecipients.js

@@ -0,0 +1,15 @@
+import { AES_256_KEY_BYTES, AES_GCM_IV_BYTES } from "../symmetric.js";
+import { wrapDekForRecipients } from "./wrapDek.js";
+/**
+ * Encrypt a payload so that multiple recipients can each independently decrypt it.
+ * Uses ML-KEM-1024 (FIPS 203) for key encapsulation and AES-256-GCM for payload encryption.
+ */
+export async function encryptForRecipients(plaintext, recipientPublicKeys) {
+    const payloadKey = crypto.getRandomValues(new Uint8Array(AES_256_KEY_BYTES));
+    const iv = crypto.getRandomValues(new Uint8Array(AES_GCM_IV_BYTES));
+    const aesKey = await crypto.subtle.importKey("raw", payloadKey, "AES-GCM", false, ["encrypt"]);
+    const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv }, aesKey, plaintext.slice()));
+    const recipients = await wrapDekForRecipients(payloadKey, recipientPublicKeys);
+    return { iv, ciphertext, recipients };
+}
+//# sourceMappingURL=encryptForRecipients.js.map

package/internal/crypto/encapsulation/encryptForRecipients.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryptForRecipients.js","sourceRoot":"","sources":["encryptForRecipients.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAEjD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,SAAqB,EACrB,mBAAiC;IAEjC,MAAM,UAAU,GAAG,MAAM,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAC7E,MAAM,EAAE,GAAG,MAAM,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAEpE,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CAC1C,KAAK,EACL,UAAU,EACV,SAAS,EACT,KAAK,EACL,CAAC,SAAS,CAAC,CACZ,CAAC;IACF,MAAM,UAAU,GAAG,IAAI,UAAU,CAC/B,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,CACzB,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,EACvB,MAAM,EACN,SAAS,CAAC,KAAK,EAAE,CAClB,CACF,CAAC;IAEF,MAAM,UAAU,GAAG,MAAM,oBAAoB,CAC3C,UAAU,EACV,mBAAmB,CACpB,CAAC;IAEF,OAAO,EAAE,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;AACxC,CAAC","sourcesContent":["import { AES_256_KEY_BYTES, AES_GCM_IV_BYTES } from \"../symmetric\";\nimport type { EncryptedEnvelope } from \"./types\";\nimport { wrapDekForRecipients } from \"./wrapDek\";\n\n/**\n * Encrypt a payload so that multiple recipients can each independently decrypt it.\n * Uses ML-KEM-1024 (FIPS 203) for key encapsulation and AES-256-GCM for payload encryption.\n */\nexport async function encryptForRecipients(\n  plaintext: Uint8Array,\n  recipientPublicKeys: Uint8Array[],\n): Promise<EncryptedEnvelope> {\n  const payloadKey = crypto.getRandomValues(new Uint8Array(AES_256_KEY_BYTES));\n  const iv = crypto.getRandomValues(new Uint8Array(AES_GCM_IV_BYTES));\n\n  const aesKey = await crypto.subtle.importKey(\n    \"raw\",\n    payloadKey,\n    \"AES-GCM\",\n    false,\n    [\"encrypt\"],\n  );\n  const ciphertext = new Uint8Array(\n    await crypto.subtle.encrypt(\n      { name: \"AES-GCM\", iv },\n      aesKey,\n      plaintext.slice(),\n    ),\n  );\n\n  const recipients = await wrapDekForRecipients(\n    payloadKey,\n    recipientPublicKeys,\n  );\n\n  return { iv, ciphertext, recipients };\n}\n"]}

package/internal/crypto/encapsulation/generateKeyPair.d.ts

@@ -0,0 +1,10 @@
+export declare const ML_KEM1024_PUBLIC_KEY_BYTES = 1568;
+export declare const ML_KEM1024_SECRET_KEY_BYTES = 3168;
+export declare const ML_KEM1024_CIPHERTEXT_BYTES = 1568;
+export declare const ML_KEM1024_SEED_BYTES = 64;
+export interface EncapsulationKeyPair {
+    readonly publicKey: Uint8Array;
+    readonly secretKey: Uint8Array;
+}
+export declare function generateKemKeyPair(seed: Uint8Array): EncapsulationKeyPair;
+export declare function generateKemSeedAndKeyPair(): EncapsulationKeyPair;

package/internal/crypto/encapsulation/generateKeyPair.js

@@ -0,0 +1,17 @@
+import { ml_kem1024 } from "@noble/post-quantum/ml-kem.js";
+import { randomBytes } from "@noble/post-quantum/utils.js";
+export const ML_KEM1024_PUBLIC_KEY_BYTES = 1568;
+export const ML_KEM1024_SECRET_KEY_BYTES = 3168;
+export const ML_KEM1024_CIPHERTEXT_BYTES = 1568;
+export const ML_KEM1024_SEED_BYTES = 64;
+// ML-KEM-1024 provides Level 5 security of NIST's Post-Quantum Cryptography standardization (FIPS 203).
+export function generateKemKeyPair(seed) {
+    if (seed.length !== ML_KEM1024_SEED_BYTES) {
+        throw new Error("ML-KEM-1024 seed must be 64 bytes");
+    }
+    return ml_kem1024.keygen(seed);
+}
+export function generateKemSeedAndKeyPair() {
+    return generateKemKeyPair(randomBytes(ML_KEM1024_SEED_BYTES));
+}
+//# sourceMappingURL=generateKeyPair.js.map

package/internal/crypto/encapsulation/generateKeyPair.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateKeyPair.js","sourceRoot":"","sources":["generateKeyPair.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAE3D,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC;AAChD,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC;AAChD,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC;AAChD,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAOxC,wGAAwG;AACxG,MAAM,UAAU,kBAAkB,CAAC,IAAgB;IACjD,IAAI,IAAI,CAAC,MAAM,KAAK,qBAAqB,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvD,CAAC;IAED,OAAO,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,yBAAyB;IACvC,OAAO,kBAAkB,CAAC,WAAW,CAAC,qBAAqB,CAAC,CAAC,CAAC;AAChE,CAAC","sourcesContent":["import { ml_kem1024 } from \"@noble/post-quantum/ml-kem.js\";\nimport { randomBytes } from \"@noble/post-quantum/utils.js\";\n\nexport const ML_KEM1024_PUBLIC_KEY_BYTES = 1568;\nexport const ML_KEM1024_SECRET_KEY_BYTES = 3168;\nexport const ML_KEM1024_CIPHERTEXT_BYTES = 1568;\nexport const ML_KEM1024_SEED_BYTES = 64;\n\nexport interface EncapsulationKeyPair {\n  readonly publicKey: Uint8Array;\n  readonly secretKey: Uint8Array;\n}\n\n// ML-KEM-1024 provides Level 5 security of NIST's Post-Quantum Cryptography standardization (FIPS 203).\nexport function generateKemKeyPair(seed: Uint8Array): EncapsulationKeyPair {\n  if (seed.length !== ML_KEM1024_SEED_BYTES) {\n    throw new Error(\"ML-KEM-1024 seed must be 64 bytes\");\n  }\n\n  return ml_kem1024.keygen(seed);\n}\n\nexport function generateKemSeedAndKeyPair(): EncapsulationKeyPair {\n  return generateKemKeyPair(randomBytes(ML_KEM1024_SEED_BYTES));\n}\n"]}

package/internal/crypto/encapsulation/types.d.ts

@@ -0,0 +1,10 @@
+export type EncryptedEnvelope = {
+    iv: Uint8Array;
+    ciphertext: Uint8Array;
+    recipients: RecipientEntry[];
+};
+export type RecipientEntry = {
+    keyFingerprint: string;
+    kemCipherText: Uint8Array;
+    wrappedKey: Uint8Array;
+};

package/internal/crypto/encapsulation/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/internal/crypto/encapsulation/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"","sourcesContent":["export type EncryptedEnvelope = {\n  iv: Uint8Array;\n  ciphertext: Uint8Array;\n  recipients: RecipientEntry[];\n};\n\nexport type RecipientEntry = {\n  keyFingerprint: string;\n  kemCipherText: Uint8Array;\n  wrappedKey: Uint8Array;\n};\n"]}

package/internal/crypto/encapsulation/unwrapDek.d.ts

@@ -0,0 +1,6 @@
+import type { RecipientEntry } from "./types.js";
+/**
+ * Unwrap a DEK from a set of recipient entries using a recipient's ML-KEM secret key.
+ * Finds the matching recipient entry by key fingerprint lookup.
+ */
+export declare function unwrapDek(recipients: RecipientEntry[], secretKey: Uint8Array): Promise<Uint8Array>;