@fgv/ts-extras 5.1.0-40 → 5.1.0-41

package/dist/packlets/crypto-utils/spkiHelpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"spkiHelpers.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/spkiHelpers.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\nimport { Result, fail, succeed } from '@fgv/ts-utils';\nimport { ICryptoProvider, KeyPairAlgorithm, MultibaseSpkiPublicKey } from './model';\n\n/**\n * Shared shape check for a base64url (no-padding) body: only base64url alphabet\n * characters (`A-Z`, `a-z`, `0-9`, `-`, `_`) and a length that is never `% 4 === 1`\n * (an impossible base64 remainder). Factored so the decoder and the\n * {@link isValidMultibaseSpkiPublicKey} guard agree on exactly one rule.\n */\nfunction isBase64UrlNoPadBody(body: string): boolean {\n  return /^[A-Za-z0-9_-]*$/.test(body) && body.length % 4 !== 1;\n}\n\n/**\n * Encodes a `Uint8Array` as a base64url (no-padding) string (RFC 4648 §5).\n *\n * The body uses the base64url alphabet (`+` → `-`, `/` → `_`) and trailing `=`\n * padding is stripped. This is the bare primitive with no multibase prefix; use\n * {@link CryptoUtils.multibaseBase64UrlEncode} when a multibase-`'m'`-prefixed value is required.\n *\n * @param data - The binary data to encode.\n * @returns The base64url-no-pad string.\n * @public\n */\nexport function base64UrlNoPadEncode(data: Uint8Array): string {\n  let base64: string;\n  if (typeof Buffer !== 'undefined') {\n    base64 = Buffer.from(data).toString('base64');\n    /* c8 ignore start - browser-only: btoa path not available in Node tests */\n  } else {\n    let binary = '';\n    for (let i = 0; i < data.length; i++) {\n      binary += String.fromCharCode(data[i]);\n    }\n    base64 = btoa(binary);\n  }\n  /* c8 ignore stop */\n  // Convert to base64url: + → -, / → _, strip = padding\n  return base64.replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '');\n}\n\n/**\n * Decodes a base64url (no-padding) string (RFC 4648 §5) back to a `Uint8Array`.\n *\n * This is the bare primitive with no multibase prefix; use\n * {@link CryptoUtils.multibaseBase64UrlDecode} to decode a multibase-`'m'`-prefixed value.\n *\n * @param encoded - The base64url-no-pad body to decode.\n * @returns `Success` with the decoded bytes, or `Failure` with error context.\n * @public\n */\nexport function base64UrlNoPadDecode(encoded: string): Result<Uint8Array> {\n  if (!isBase64UrlNoPadBody(encoded)) {\n    return fail(`base64UrlNoPadDecode: malformed base64url body`);\n  }\n  // Convert base64url back to standard base64 and restore padding\n  const base64 = encoded.replace(/-/g, '+').replace(/_/g, '/');\n  const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);\n  try {\n    let bytes: Uint8Array;\n    if (typeof Buffer !== 'undefined') {\n      bytes = new Uint8Array(Buffer.from(padded, 'base64'));\n      /* c8 ignore start - browser-only: atob path not available in Node tests */\n    } else {\n      const binary = atob(padded);\n      bytes = new Uint8Array(binary.length);\n      for (let i = 0; i < binary.length; i++) {\n        bytes[i] = binary.charCodeAt(i);\n      }\n    }\n    /* c8 ignore stop */\n    return succeed(bytes);\n    /* c8 ignore next 3 - defensive: shape check above prevents invalid chars from reaching here */\n  } catch {\n    return fail(`base64UrlNoPadDecode: malformed base64url body`);\n  }\n}\n\n/**\n * The structural *shape* of a {@link CryptoUtils.MultibaseSpkiPublicKey}: the\n * multibase `'m'` prefix followed by a non-empty base64url-no-pad body\n * (`A-Z`, `a-z`, `0-9`, `-`, `_`).\n *\n * This is a shape prefilter, not full validation: it does not decode the DER\n * SPKI or verify the key material or algorithm (that happens in\n * {@link CryptoUtils.importPublicKeyFromMultibaseSpki}). The authoritative guard\n * is {@link CryptoUtils.isValidMultibaseSpkiPublicKey}, which enforces this\n * pattern **and** additionally rejects a body whose length is an impossible\n * base64 remainder. Exposed for callers that need the pattern directly (e.g. a\n * JSON-schema `pattern` field); prefer the guard/converter for validation.\n *\n * @public\n */\nexport const MultibaseSpkiPublicKeyRegExp: RegExp = /^m[A-Za-z0-9_-]+$/;\n\n/**\n * Type guard for {@link CryptoUtils.MultibaseSpkiPublicKey}: a string matching\n * {@link CryptoUtils.MultibaseSpkiPublicKeyRegExp} (multibase `'m'` prefix + a\n * non-empty base64url-no-pad body) whose body also satisfies the base64url-no-pad\n * length rule shared with {@link CryptoUtils.base64UrlNoPadDecode}. This is a\n * structural *shape* check, not full validation — it does not decode the DER SPKI\n * or verify the key material/algorithm (a malformed-but-well-shaped string fails\n * later, with clear context, in {@link CryptoUtils.importPublicKeyFromMultibaseSpki}).\n *\n * @param value - The value to test.\n * @returns `true` if `value` is a well-formed multibase SPKI public key string.\n * @public\n */\nexport function isValidMultibaseSpkiPublicKey(value: unknown): value is MultibaseSpkiPublicKey {\n  return (\n    typeof value === 'string' &&\n    MultibaseSpkiPublicKeyRegExp.test(value) &&\n    isBase64UrlNoPadBody(value.slice(1))\n  );\n}\n\n/**\n * Encodes a `Uint8Array` as a multibase base64url (no-padding) string.\n *\n * The multibase prefix `'m'` identifies the encoding as RFC 4648 base64url\n * without padding. The body uses base64url alphabet: `+` → `-`, `/` → `_`,\n * and trailing `=` padding is stripped.\n *\n * @param data - The binary data to encode.\n * @returns A multibase-prefixed base64url string (`'m' + base64url-no-pad`).\n * @public\n */\nexport function multibaseBase64UrlEncode(data: Uint8Array): string {\n  return 'm' + base64UrlNoPadEncode(data);\n}\n\n/**\n * Decodes a multibase base64url (no-padding) string back to a `Uint8Array`.\n *\n * Validates that the first character is `'m'` (the multibase prefix for\n * RFC 4648 base64url without padding), then decodes the remaining body.\n *\n * @param encoded - A multibase-prefixed base64url string.\n * @returns `Success` with the decoded bytes, or `Failure` with error context.\n * @public\n */\nexport function multibaseBase64UrlDecode(encoded: string): Result<Uint8Array> {\n  if (!encoded.startsWith('m')) {\n    return fail(\n      `multibaseBase64UrlDecode: invalid multibase prefix '${\n        encoded[0] ?? '(empty)'\n      }' — expected 'm' (base64url)`\n    );\n  }\n  // Intentionally pin the exact original message (the delegate has a single failure\n  // mode) to keep this established public function byte-for-byte behavior-preserving\n  // after the extract-and-delegate refactor — do not \"fix\" this into composing the\n  // delegate's message without updating the delegation-equivalence tests.\n  return base64UrlNoPadDecode(encoded.slice(1)).withErrorFormat(\n    () => `multibaseBase64UrlDecode: malformed base64url body`\n  );\n}\n\n/**\n * Exports a public `CryptoKey` as a multibase base64url-encoded SPKI blob.\n *\n * The SPKI (SubjectPublicKeyInfo) format is the standard DER-encoded structure\n * for public keys defined in RFC 5280, RFC 5480, and RFC 8410. It is\n * algorithm-agnostic and suitable for storage and transmission.\n *\n * @param key - The `CryptoKey` to export. Must have `key.type === 'public'`.\n * @param provider - The {@link CryptoUtils.ICryptoProvider} to use for the export operation.\n * @returns `Success` with the multibase SPKI string, or `Failure` with error context.\n * @public\n */\nexport async function exportPublicKeyAsMultibaseSpki(\n  key: CryptoKey,\n  provider: ICryptoProvider\n): Promise<Result<MultibaseSpkiPublicKey>> {\n  return (await provider.exportPublicKeySpki(key))\n    .withErrorFormat((e) => `exportPublicKeyAsMultibaseSpki: ${e}`)\n    .onSuccess((buf) =>\n      // The output is a freshly-built valid multibase SPKI string (`'m'` prefix +\n      // base64url-no-pad body), so brand it at the construction site — no re-validation needed.\n      succeed(multibaseBase64UrlEncode(buf) as MultibaseSpkiPublicKey)\n    );\n}\n\n/**\n * Imports a public key from a multibase base64url-encoded SPKI blob.\n *\n * Decodes the multibase prefix, decodes the base64url body, then uses\n * the provider to import the key with the algorithm parameters from\n * {@link CryptoUtils.keyPairAlgorithmParams}.\n *\n * Accepts a plain `string` (not only a branded {@link CryptoUtils.MultibaseSpkiPublicKey}),\n * so callers holding an unbranded value read from storage or the wire can import\n * it directly; a malformed value fails with error context rather than throwing.\n *\n * @param encoded - A multibase SPKI string produced by {@link CryptoUtils.exportPublicKeyAsMultibaseSpki}.\n * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm} the key was generated for.\n * @param provider - The {@link CryptoUtils.ICryptoProvider} to use for the import operation.\n * @returns `Success` with the imported public `CryptoKey`, or `Failure` with error context.\n * @public\n */\nexport async function importPublicKeyFromMultibaseSpki(\n  encoded: string,\n  algorithm: KeyPairAlgorithm,\n  provider: ICryptoProvider\n): Promise<Result<CryptoKey>> {\n  const decodeResult = multibaseBase64UrlDecode(encoded);\n  if (decodeResult.isFailure()) {\n    return fail(`importPublicKeyFromMultibaseSpki: ${decodeResult.message}`);\n  }\n  return (await provider.importPublicKeySpki(decodeResult.value, algorithm)).withErrorFormat(\n    (e) => `importPublicKeyFromMultibaseSpki: ${e}`\n  );\n}\n"]}
+{"version":3,"file":"spkiHelpers.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/spkiHelpers.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\nimport { Result, fail, succeed } from '@fgv/ts-utils';\nimport { ICryptoProvider, KeyPairAlgorithm, MultibaseSpkiPublicKey } from './model';\n\n/**\n * Shared shape check for a base64url (no-padding) body: only base64url alphabet\n * characters (`A-Z`, `a-z`, `0-9`, `-`, `_`) and a length that is never `% 4 === 1`\n * (an impossible base64 remainder). Factored so the decoder and the\n * {@link isValidMultibaseSpkiPublicKey} guard agree on exactly one rule.\n */\nfunction isBase64UrlNoPadBody(body: string): boolean {\n  return /^[A-Za-z0-9_-]*$/.test(body) && body.length % 4 !== 1;\n}\n\n/**\n * Encodes a `Uint8Array` as a base64url (no-padding) string (RFC 4648 §5).\n *\n * The body uses the base64url alphabet (`+` → `-`, `/` → `_`) and trailing `=`\n * padding is stripped. This is the bare primitive with no multibase prefix; use\n * {@link CryptoUtils.multibaseBase64UrlEncode} when a multibase-`'m'`-prefixed value is required.\n *\n * @param data - The binary data to encode.\n * @returns The base64url-no-pad string.\n * @public\n */\nexport function base64UrlNoPadEncode(data: Uint8Array): string {\n  let base64: string;\n  if (typeof Buffer !== 'undefined') {\n    base64 = Buffer.from(data).toString('base64');\n    /* c8 ignore start - browser-only: btoa path not available in Node tests */\n  } else {\n    let binary = '';\n    for (let i = 0; i < data.length; i++) {\n      binary += String.fromCharCode(data[i]);\n    }\n    base64 = btoa(binary);\n  }\n  /* c8 ignore stop */\n  // Convert to base64url: + → -, / → _, strip = padding\n  return base64.replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '');\n}\n\n/**\n * Decodes a base64url (no-padding) string (RFC 4648 §5) back to a `Uint8Array`.\n *\n * This is the bare primitive with no multibase prefix; use\n * {@link CryptoUtils.multibaseBase64UrlDecode} to decode a multibase-`'m'`-prefixed value.\n *\n * @param encoded - The base64url-no-pad body to decode.\n * @returns `Success` with the decoded bytes, or `Failure` with error context.\n * @public\n */\nexport function base64UrlNoPadDecode(encoded: string): Result<Uint8Array> {\n  if (!isBase64UrlNoPadBody(encoded)) {\n    return fail(`base64UrlNoPadDecode: malformed base64url body`);\n  }\n  // Convert base64url back to standard base64 and restore padding\n  const base64 = encoded.replace(/-/g, '+').replace(/_/g, '/');\n  const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);\n  try {\n    let bytes: Uint8Array;\n    if (typeof Buffer !== 'undefined') {\n      bytes = new Uint8Array(Buffer.from(padded, 'base64'));\n      /* c8 ignore start - browser-only: atob path not available in Node tests */\n    } else {\n      const binary = atob(padded);\n      bytes = new Uint8Array(binary.length);\n      for (let i = 0; i < binary.length; i++) {\n        bytes[i] = binary.charCodeAt(i);\n      }\n    }\n    /* c8 ignore stop */\n    return succeed(bytes);\n    /* c8 ignore next 3 - defensive: shape check above prevents invalid chars from reaching here */\n  } catch {\n    return fail(`base64UrlNoPadDecode: malformed base64url body`);\n  }\n}\n\n/**\n * The structural *shape* of a {@link CryptoUtils.MultibaseSpkiPublicKey}: the\n * multibase `'m'` prefix followed by a non-empty base64url-no-pad body\n * (`A-Z`, `a-z`, `0-9`, `-`, `_`).\n *\n * This is a shape prefilter, not full validation: it does not decode the DER\n * SPKI or verify the key material or algorithm (that happens in\n * {@link CryptoUtils.importPublicKeyFromMultibaseSpki}). The authoritative guard\n * is {@link CryptoUtils.isValidMultibaseSpkiPublicKey}, which enforces this\n * pattern **and** additionally rejects a body whose length is an impossible\n * base64 remainder. Exposed for callers that need the pattern directly (e.g. a\n * JSON-schema `pattern` field); prefer the guard/converter for validation.\n *\n * @public\n */\nexport const MultibaseSpkiPublicKeyRegExp: RegExp = /^m[A-Za-z0-9_-]+$/;\n\n/**\n * Type guard for {@link CryptoUtils.MultibaseSpkiPublicKey}: a string matching\n * {@link CryptoUtils.MultibaseSpkiPublicKeyRegExp} (multibase `'m'` prefix + a\n * non-empty base64url-no-pad body) whose body also satisfies the base64url-no-pad\n * length rule shared with {@link CryptoUtils.base64UrlNoPadDecode}. This is a\n * structural *shape* check, not full validation — it does not decode the DER SPKI\n * or verify the key material/algorithm (a malformed-but-well-shaped string fails\n * later, with clear context, in {@link CryptoUtils.importPublicKeyFromMultibaseSpki}).\n *\n * @param value - The value to test.\n * @returns `true` if `value` is a well-formed multibase SPKI public key string.\n * @public\n */\nexport function isValidMultibaseSpkiPublicKey(value: unknown): value is MultibaseSpkiPublicKey {\n  return (\n    typeof value === 'string' &&\n    MultibaseSpkiPublicKeyRegExp.test(value) &&\n    isBase64UrlNoPadBody(value.slice(1))\n  );\n}\n\n/**\n * Encodes a `Uint8Array` as a multibase base64url (no-padding) string.\n *\n * The multibase prefix `'m'` identifies the encoding as RFC 4648 base64url\n * without padding. The body uses base64url alphabet: `+` → `-`, `/` → `_`,\n * and trailing `=` padding is stripped.\n *\n * @param data - The binary data to encode.\n * @returns A multibase-prefixed base64url string (`'m' + base64url-no-pad`).\n * @public\n */\nexport function multibaseBase64UrlEncode(data: Uint8Array): string {\n  return 'm' + base64UrlNoPadEncode(data);\n}\n\n/**\n * Decodes a multibase base64url (no-padding) string back to a `Uint8Array`.\n *\n * Validates that the first character is `'m'` (the multibase prefix for\n * RFC 4648 base64url without padding), then decodes the remaining body.\n *\n * @param encoded - A multibase-prefixed base64url string.\n * @returns `Success` with the decoded bytes, or `Failure` with error context.\n * @public\n */\nexport function multibaseBase64UrlDecode(encoded: string): Result<Uint8Array> {\n  if (!encoded.startsWith('m')) {\n    return fail(\n      `multibaseBase64UrlDecode: invalid multibase prefix '${\n        encoded[0] ?? '(empty)'\n      }' — expected 'm' (base64url)`\n    );\n  }\n  // Intentionally pin the exact original message (the delegate has a single failure\n  // mode) to keep this established public function byte-for-byte behavior-preserving\n  // after the extract-and-delegate refactor — do not \"fix\" this into composing the\n  // delegate's message without updating the delegation-equivalence tests.\n  return base64UrlNoPadDecode(encoded.slice(1)).withErrorFormat(\n    () => `multibaseBase64UrlDecode: malformed base64url body`\n  );\n}\n\n/**\n * Exports a public `CryptoKey` as a multibase base64url-encoded SPKI blob.\n *\n * The SPKI (SubjectPublicKeyInfo) format is the standard DER-encoded structure\n * for public keys defined in RFC 5280, RFC 5480, and RFC 8410. It is\n * algorithm-agnostic and suitable for storage and transmission.\n *\n * @param key - The `CryptoKey` to export. Must have `key.type === 'public'`.\n * @param provider - The {@link CryptoUtils.ICryptoProvider} to use for the export operation.\n * @returns `Success` with the multibase SPKI string, or `Failure` with error context.\n * @public\n */\nexport async function exportPublicKeyAsMultibaseSpki(\n  key: CryptoKey,\n  provider: ICryptoProvider\n): Promise<Result<MultibaseSpkiPublicKey>> {\n  return (await provider.exportPublicKeySpki(key))\n    .withErrorFormat((e) => `exportPublicKeyAsMultibaseSpki: ${e}`)\n    .onSuccess((buf) =>\n      // The output is a freshly-built valid multibase SPKI string (`'m'` prefix +\n      // base64url-no-pad body), so brand it at the construction site — no re-validation needed.\n      succeed(multibaseBase64UrlEncode(buf) as MultibaseSpkiPublicKey)\n    );\n}\n\n/**\n * Imports a public key from a multibase base64url-encoded SPKI blob.\n *\n * Decodes the multibase prefix, decodes the base64url body, then uses\n * the provider to import the key with the algorithm parameters from\n * {@link CryptoUtils.keyPairAlgorithmParams}.\n *\n * Accepts a plain `string` (not only a branded {@link CryptoUtils.MultibaseSpkiPublicKey}),\n * so callers holding an unbranded value read from storage or the wire can import\n * it directly; a malformed value fails with error context rather than throwing.\n *\n * @param encoded - A multibase SPKI string produced by {@link CryptoUtils.exportPublicKeyAsMultibaseSpki}.\n * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm} the key was generated for.\n * @param provider - The {@link CryptoUtils.ICryptoProvider} to use for the import operation.\n * @returns `Success` with the imported public `CryptoKey`, or `Failure` with error context.\n * @public\n */\nexport async function importPublicKeyFromMultibaseSpki(\n  encoded: string,\n  algorithm: KeyPairAlgorithm,\n  provider: ICryptoProvider\n): Promise<Result<CryptoKey>> {\n  const decodeResult = multibaseBase64UrlDecode(encoded);\n  if (decodeResult.isFailure()) {\n    return fail(`importPublicKeyFromMultibaseSpki: ${decodeResult.message}`);\n  }\n  return (await provider.importPublicKeySpki(decodeResult.value, algorithm)).withErrorFormat(\n    (e) => `importPublicKeyFromMultibaseSpki: ${e}`\n  );\n}\n\n// DER prefix for an X25519 SubjectPublicKeyInfo: SEQUENCE { SEQUENCE { OID id-X25519 }, BIT STRING }.\n// SEQUENCE(42) / SEQUENCE(5) / OID 1.3.101.110 (id-X25519) / BIT STRING(33, 0 unused bits).\nconst _X25519_SPKI_PREFIX: ReadonlyArray<number> = [\n  0x30, 0x2a, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x6e, 0x03, 0x21, 0x00\n];\nconst _X25519_SPKI_LENGTH: number = _X25519_SPKI_PREFIX.length + 32;\n\n/**\n * Strips the fixed DER prefix from an X25519 SubjectPublicKeyInfo blob, returning the raw\n * 32-byte public key.\n *\n * An X25519 SPKI is always exactly 44 bytes: a fixed 12-byte prefix (SEQUENCE / AlgorithmIdentifier\n * with OID 1.3.101.110 / BIT STRING) followed by the 32-byte raw key. Use this to convert a\n * SPKI-held recipient public key into the raw form accepted by {@link HpkeProvider.openBase}'s\n * `recipientPublicKey` parameter.\n *\n * @param spki - The DER-encoded X25519 SubjectPublicKeyInfo bytes.\n * @returns `Success` with the raw 32-byte public key, or `Failure` if `spki` is not a\n *   well-formed 44-byte X25519 SPKI blob.\n * @public\n */\nexport function spkiToRawX25519(spki: Uint8Array): Result<Uint8Array> {\n  if (spki.length !== _X25519_SPKI_LENGTH) {\n    return fail(`spkiToRawX25519: expected ${_X25519_SPKI_LENGTH} bytes, got ${spki.length}`);\n  }\n  for (let i = 0; i < _X25519_SPKI_PREFIX.length; i++) {\n    if (spki[i] !== _X25519_SPKI_PREFIX[i]) {\n      return fail(`spkiToRawX25519: byte ${i} does not match the expected X25519 SPKI prefix`);\n    }\n  }\n  return succeed(spki.slice(_X25519_SPKI_PREFIX.length));\n}\n"]}

package/dist/ts-extras.d.ts

@@ -381,6 +381,12 @@ declare const allKeyPairAlgorithms: ReadonlyArray<KeyPairAlgorithm>;
  */
 declare const allKeyStoreAsymmetricSecretTypes: ReadonlyArray<KeyStoreAsymmetricSecretType>;
 
+/**
+ * All recognized key store format versions (readable by the current library).
+ * @public
+ */
+declare const allKeyStoreFormats: ReadonlyArray<KeyStoreFormat>;
+
 /**
  * All valid key store secret types.
  * @public
@@ -730,6 +736,7 @@ declare namespace CryptoUtils {
         MultibaseSpkiPublicKeyRegExp,
         multibaseBase64UrlDecode,
         multibaseBase64UrlEncode,
+        spkiToRawX25519,
         HpkeProvider,
         IHpkeSealResult,
         isEncryptedFile,
@@ -738,6 +745,7 @@ declare namespace CryptoUtils {
         EncryptedFileFormat,
         INamedSecret,
         IEncryptionResult,
+        IEncryptBytesResult,
         KeyPairAlgorithm,
         IWrapBytesOptions,
         IWrappedBytes,
@@ -1435,15 +1443,23 @@ declare class HpkeProvider {
      *
      * @param recipientPrivateKey - Recipient's X25519 private `CryptoKey`
      *   (`algorithm.name === 'X25519'`, `type === 'private'`, `usages` includes `'deriveBits'`).
-     *   **Must be extractable** (`extractable: true`) — the recipient's public key bytes
-     *   are recovered from the JWK `x` field during Decap.
+     *   **Must be extractable** (`extractable: true`) only when `recipientPublicKey` is not
+     *   supplied — the recipient's public key bytes are then recovered from the JWK `x` field
+     *   during Decap. When `recipientPublicKey` is supplied, `recipientPrivateKey` may be
+     *   non-extractable.
      * @param info - Context-binding bytes. Must exactly match `info` from `sealBase`.
      * @param aad - Must exactly match `aad` from `sealBase`.
      * @param enc - The encapsulated key from `sealBase` — exactly 32 bytes.
      * @param ciphertext - The ciphertext from `sealBase` — `plaintext.length + 16` bytes.
+     * @param recipientPublicKey - Optional raw 32-byte X25519 public key matching
+     *   `recipientPrivateKey` (`pkRm` in RFC 9180 §4.1). Public material — supplying it lets
+     *   Decap build `kem_context` without exporting `recipientPrivateKey` to JWK, so
+     *   `recipientPrivateKey` no longer needs to be extractable. A mismatched value only breaks
+     *   the caller's own decryption (AEAD authentication fails) — it cannot be used to attack
+     *   another party's ciphertext.
      * @returns `Success` with decrypted plaintext bytes, or `Failure` with error context.
      */
-    openBase(recipientPrivateKey: CryptoKey, info: Uint8Array, aad: Uint8Array, enc: Uint8Array, ciphertext: Uint8Array): Promise<Result<Uint8Array>>;
+    openBase(recipientPrivateKey: CryptoKey, info: Uint8Array, aad: Uint8Array, enc: Uint8Array, ciphertext: Uint8Array, recipientPublicKey?: Uint8Array): Promise<Result<Uint8Array>>;
     /**
      * HKDF-SHA256 key derivation (RFC 5869). Extract-then-Expand using SHA-256.
      *
@@ -1508,6 +1524,28 @@ declare interface IAddKeyPairOptions {
      * downgrading.
      */
     readonly extractable?: boolean;
+    /**
+     * Opt in to private-key escrow. When `true`, an encrypted copy of the
+     * private key (as a JWK) is carried inside the vault entry
+     * (`escrowedPrivateKeyJwk`), enabling cross-device recovery from the vault
+     * file plus the master password alone via
+     * `getKeyPair(name, { rehydrate: true })`.
+     *
+     * Orthogonal to `extractable`: the escrow copy is always captured (the
+     * transient keypair is generated extractable so it can be exported to JWK),
+     * while the LIVE stored key's extractability still follows the normal rule
+     * (`extractable` override, else the backend default). So escrow does not
+     * change how extractable the day-to-day key is — only whether a recovery
+     * copy is retained in the vault.
+     *
+     * @defaultValue false — no escrow copy is written (today's behavior).
+     *
+     * SECURITY: escrow makes the master password the sole gate protecting a
+     * private key that would otherwise be unrecoverable from the vault. Use a
+     * strong KDF (Argon2id-derived or high-iteration PBKDF2) for escrow-bearing
+     * stores. See the {@link CryptoUtils.KeyStore.KeyStore} class docs.
+     */
+    readonly escrow?: boolean;
 }
 
 /**
@@ -2681,6 +2719,68 @@ declare interface ICryptoProvider {
      * @returns Success with decrypted UTF-8 string, or Failure with error
      */
     decrypt(encryptedData: Uint8Array, key: Uint8Array, iv: Uint8Array, authTag: Uint8Array): Promise<Result<string>>;
+    /**
+     * Encrypts raw bytes using AES-256-GCM with a **caller-supplied nonce** and
+     * optional additional authenticated data (AAD).
+     *
+     * This is the raw-byte sibling of {@link CryptoUtils.ICryptoProvider.encrypt | encrypt}.
+     * Unlike `encrypt`, it takes and returns `Uint8Array` (no UTF-8 coding), the
+     * caller owns the nonce (rather than the provider generating one), and it
+     * binds optional `aad` into the GCM authentication. Use it when you need to
+     * bind context (e.g. an actor id, key version, or row kind) into the
+     * authentication so a wrapped secret cannot be replayed across
+     * users/versions/kinds, or when you manage nonces yourself.
+     *
+     * @remarks
+     * **⚠️ NONCE UNIQUENESS IS THE CALLER'S RESPONSIBILITY AND IS CRITICAL.**
+     * Because the caller supplies the nonce, this primitive cannot guarantee
+     * uniqueness. Reusing a `(key, nonce)` pair for two different messages is
+     * **catastrophic** for AES-GCM: it breaks confidentiality (the XOR of the two
+     * plaintexts leaks) AND authentication (the GCM authentication key can be
+     * recovered, letting an attacker forge tags for arbitrary messages under that
+     * key). The caller MUST use a unique nonce for every message encrypted under a
+     * given key — draw it from {@link CryptoUtils.ICryptoProvider.generateRandomBytes | generateRandomBytes(12)}
+     * (12 random bytes has negligible collision probability well within a single
+     * key's message budget) or from a strictly-increasing counter. Never hardcode
+     * a nonce and never reuse one.
+     *
+     * @param key - 32-byte AES-256 key. Wrong lengths fail with error context.
+     * @param nonce - 12-byte (96-bit) GCM nonce. MUST be unique per message under
+     * `key` (see the nonce-uniqueness warning above). Wrong lengths fail with
+     * error context.
+     * @param plaintext - The bytes to encrypt. Empty plaintext is permitted and
+     * round-trips (GCM produces a valid tag over zero-length plaintext).
+     * @param aad - Optional additional authenticated data bound into the GCM tag
+     * but NOT encrypted. If provided at encrypt time, the identical bytes must be
+     * supplied to `decryptBytes` or decryption fails authentication. Absent means
+     * no AAD.
+     * @returns `Success` with the {@link CryptoUtils.IEncryptBytesResult | ciphertext and 16-byte auth tag},
+     * or `Failure` with error context.
+     */
+    encryptBytes(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Promise<Result<IEncryptBytesResult>>;
+    /**
+     * Decrypts raw bytes produced by
+     * {@link CryptoUtils.ICryptoProvider.encryptBytes | encryptBytes} using
+     * AES-256-GCM. The inverse of `encryptBytes`: the `ciphertext` and `authTag`
+     * from an `encryptBytes` result, together with the same `key`, `nonce`, and
+     * `aad`, recover the original plaintext.
+     *
+     * Fails (never throws) on any authentication failure: a tampered ciphertext
+     * or tag, the wrong key or nonce, or an `aad` that differs from the one used
+     * at encrypt time. AES-GCM authentication is fail-closed — a mismatched `aad`
+     * fails exactly as a tampered ciphertext does.
+     *
+     * @param key - 32-byte AES-256 key (the same key used to encrypt).
+     * @param nonce - 12-byte (96-bit) GCM nonce (the same nonce used to encrypt).
+     * @param ciphertext - The ciphertext from the `encryptBytes` result.
+     * @param authTag - The 16-byte (128-bit) GCM authentication tag from the
+     * `encryptBytes` result.
+     * @param aad - The identical additional authenticated data supplied at encrypt
+     * time (or absent if none was supplied). A mismatch fails authentication.
+     * @returns `Success` with the decrypted plaintext bytes, or `Failure` with
+     * error context (including all authentication failures).
+     */
+    decryptBytes(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, authTag: Uint8Array, aad?: Uint8Array): Promise<Result<Uint8Array>>;
     /**
      * Generates a random 32-byte key suitable for AES-256.
      * @returns Success with generated key, or Failure with error
@@ -2905,6 +3005,34 @@ declare interface IDirectEncryptionProviderParams {
     readonly boundSecretName?: string;
 }
 
+/**
+ * Result of a raw-byte AES-256-GCM encryption via
+ * {@link CryptoUtils.ICryptoProvider.encryptBytes | encryptBytes}. The
+ * authentication tag is returned separately from the ciphertext, mirroring the
+ * separated-tag convention of {@link CryptoUtils.IEncryptionResult}. The exact
+ * byte layout is:
+ * - `ciphertext`: the AES-GCM ciphertext, byte-for-byte the same length as the
+ *   input plaintext (GCM is a stream cipher — no padding). Empty plaintext
+ *   yields an empty `ciphertext`.
+ * - `authTag`: the 16-byte (128-bit) GCM authentication tag, computed over the
+ *   ciphertext, the nonce, and any `aad`.
+ *
+ * The caller persists both fields alongside the (caller-owned) nonce and feeds
+ * them back to {@link CryptoUtils.ICryptoProvider.decryptBytes | decryptBytes}.
+ * @public
+ */
+declare interface IEncryptBytesResult {
+    /**
+     * The AES-256-GCM ciphertext. Same length as the input plaintext (no tag
+     * appended — the tag is carried separately in the `authTag` field).
+     */
+    readonly ciphertext: Uint8Array;
+    /**
+     * The 16-byte (128-bit) GCM authentication tag.
+     */
+    readonly authTag: Uint8Array;
+}
+
 /**
  * Generic encrypted file format.
  * This is the JSON structure stored in encrypted files.
@@ -3278,6 +3406,26 @@ declare interface IGenerateJsonCompletionResult<T> {
     readonly response: IAiCompletionResponse;
 }
 
+/**
+ * Options for retrieving an asymmetric keypair via {@link CryptoUtils.KeyStore.KeyStore.getKeyPair}.
+ * @public
+ */
+declare interface IGetKeyPairOptions {
+    /**
+     * Opt in to escrow rehydration. When `true` AND no private-key blob exists
+     * under the entry's storage `id` AND the entry carries an
+     * `escrowedPrivateKeyJwk`, the escrowed JWK is imported (non-extractable
+     * where the backend supports it) and stored under the entry's `id` before
+     * being returned — filling a gap on a fresh device from the recovered vault.
+     *
+     * Fill-a-gap only: an existing storage blob is never overwritten. When a
+     * blob is present it is loaded as usual and the escrow copy is ignored.
+     *
+     * @defaultValue false — today's behavior: load from storage or fail.
+     */
+    readonly rehydrate?: boolean;
+}
+
 /**
  * Provider-specific config for gpt-image-1.
  * @public
@@ -3453,6 +3601,21 @@ declare interface IKeyStoreAsymmetricEntry {
      * The public key as a JSON Web Key.
      */
     readonly publicKeyJwk: JsonWebKey;
+    /**
+     * Optional escrowed copy of the private key, as a JSON Web Key. Present only
+     * when the entry was created with `addKeyPair(name, { escrow: true })`.
+     *
+     * This is an opt-in cross-device recovery affordance: the private key is
+     * carried inside the vault's AES-GCM ciphertext (same custody class as
+     * `publicKeyJwk`), so a recovered vault plus the master password can
+     * reconstitute the signing/decryption identity on a fresh device via
+     * `getKeyPair(name, { rehydrate: true })`.
+     *
+     * SECURITY: when present, the master password becomes the sole gate
+     * protecting this private key. Use a strong KDF for escrow-bearing stores.
+     * See the {@link CryptoUtils.KeyStore.KeyStore} class docs.
+     */
+    readonly escrowedPrivateKeyJwk?: JsonWebKey;
     /**
      * Optional description for this entry.
      */
@@ -3491,6 +3654,12 @@ declare interface IKeyStoreAsymmetricEntryJson {
      * The public key as a JSON Web Key.
      */
     readonly publicKeyJwk: JsonWebKey;
+    /**
+     * Optional escrowed copy of the private key, as a JSON Web Key. Present only
+     * on `'keystore-v2'` vaults whose entry was created with escrow enabled. A
+     * v1 vault omits the field; a v2 reader treats its absence as "no escrow".
+     */
+    readonly escrowedPrivateKeyJwk?: JsonWebKey;
     /**
      * Optional description.
      */
@@ -4604,6 +4773,7 @@ declare namespace KeyStore {
         allKeyPairAlgorithms,
         KeyPairAlgorithm,
         KeyStoreFormat,
+        allKeyStoreFormats,
         KEYSTORE_FORMAT,
         DEFAULT_KEYSTORE_ITERATIONS,
         MIN_SALT_LENGTH,
@@ -4635,6 +4805,7 @@ declare namespace KeyStore {
         IAddSecretFromPasswordResult,
         IAddSecretFromPasswordArgon2idOptions,
         IAddKeyPairOptions,
+        IGetKeyPairOptions,
         IAddKeyPairResult,
         IRemoveSecretResult,
         IPrivateKeyStorage
@@ -4670,6 +4841,20 @@ declare namespace KeyStore {
  * const encryptionConfig = keystore2.getEncryptionConfig().orThrow();
  * ```
  *
+ * @remarks
+ * SECURITY — private-key escrow. By default an asymmetric keypair's private
+ * key lives only in the per-device {@link CryptoUtils.KeyStore.IPrivateKeyStorage}
+ * backend; the vault carries only the public JWK, so a vault recovered on a new
+ * device reconstitutes with no private keys (a lost device is a lost identity).
+ * `addKeyPair(name, { escrow: true })` opts into carrying an encrypted private-key
+ * copy inside the vault ciphertext, so the vault file plus the master password can
+ * recover the identity on a fresh device via `getKeyPair(name, { rehydrate: true })`.
+ *
+ * When escrow is used, **the master password becomes the sole gate** protecting a
+ * private signing/decryption key that was previously unrecoverable from the vault.
+ * Configure escrow-bearing stores with a strong KDF — an Argon2id-derived master
+ * key or a high-iteration PBKDF2 count — and treat the vault file accordingly.
+ *
  * @public
  */
 declare class KeyStore_2 implements IEncryptionProvider {
@@ -4776,6 +4961,12 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * Gets a secret by name. Returns the {@link CryptoUtils.KeyStore.IKeyStoreEntry | discriminated union}
      * — callers must check `entry.type` before accessing `key`/`id` since asymmetric
      * entries carry no raw key material.
+     *
+     * SECURITY: for an escrow-enabled asymmetric-keypair entry the returned object
+     * carries `escrowedPrivateKeyJwk` in cleartext (same custody class as
+     * `publicKeyJwk`, gated by the same unlock) — do not log or serialize a
+     * `getSecret()` result casually.
+     *
      * @param name - Name of the secret
      * @returns Success with secret entry, Failure if not found or locked
      * @public
@@ -4962,12 +5153,23 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * the keystore never caches private `CryptoKey` references between calls.
      * The public key is re-imported from the vault's JWK so callers always
      * receive a `CryptoKey` rather than the JWK form.
+     *
+     * With `options.rehydrate: true`, if the storage backend holds no blob for
+     * the entry's `id` and the entry carries an `escrowedPrivateKeyJwk` (see
+     * `addKeyPair(name, { escrow: true })`), the escrowed JWK is imported and
+     * stored under the entry's `id` before being returned — recovering the
+     * private key on a fresh device from the vault plus master password. This is
+     * fill-a-gap only: an existing storage blob is never overwritten.
+     *
      * @param name - Name of the entry
+     * @param options - Optional {@link CryptoUtils.KeyStore.IGetKeyPairOptions}
+     * (currently the `rehydrate` escrow-recovery flag).
      * @returns Success with `{ publicKey, privateKey }`, Failure if not found,
-     * locked, wrong type, no provider, or storage load failed.
+     * locked, wrong type, no provider, or storage load (and any escrow
+     * rehydration) failed.
      * @public
      */
-    getKeyPair(name: string): Promise<Result<{
+    getKeyPair(name: string, options?: IGetKeyPairOptions): Promise<Result<{
         publicKey: CryptoKey;
         privateKey: CryptoKey;
     }>>;
@@ -5053,6 +5255,40 @@ declare class KeyStore_2 implements IEncryptionProvider {
      * @returns A warning string if storage cleanup failed, otherwise undefined.
      */
     private _releaseEntryResources;
+    /**
+     * Exports the transient extractable private `CryptoKey` to a JWK for escrow,
+     * via WebCrypto's `exportKey('jwk', ...)` (cross-runtime through
+     * `globalThis.crypto.subtle`). The result is carried in the vault entry — the
+     * same custody class as the public JWK — and is never returned from a public
+     * method nor logged.
+     */
+    private _exportPrivateKeyJwk;
+    /**
+     * Re-imports an escrowed private-key JWK as a `CryptoKey` for `algorithm`
+     * with the requested extractability. The WebCrypto JWK-import descriptor is
+     * shared between the public and private halves for every supported algorithm,
+     * so `IKeyPairAlgorithmParams.importPublicKey` is reused; the private/public
+     * distinction is carried by the requested usages (see
+     * {@link KeyStore._privateKeyUsagesFor}). Cross-runtime through
+     * `globalThis.crypto.subtle`.
+     */
+    private _importEscrowedPrivateKey;
+    /**
+     * Loads the private key for `entry` from storage, or — when
+     * `options.rehydrate` is set, storage holds no blob, and the entry carries an
+     * escrowed JWK — imports the escrowed key, persists it under the entry's `id`
+     * (fill-a-gap; never overwrites an existing blob), and returns it.
+     */
+    private _loadOrRehydratePrivateKey;
+    /**
+     * Computes the key usages to request when importing an escrowed private JWK.
+     * Mirrors `EncryptedFilePrivateKeyStorage`: intersect the algorithm's private
+     * usages (its keypair usages minus the public-only ones) with the JWK's
+     * recorded `key_ops` so we request exactly the operations the stored key
+     * supports; fall back to the algorithm's private usages when `key_ops` is
+     * absent.
+     */
+    private static _privateKeyUsagesFor;
     /**
      * Constant-time byte comparison. Returns false immediately for length
      * mismatch (length is not secret); for equal-length inputs, walks the full
@@ -5069,7 +5305,7 @@ declare class KeyStore_2 implements IEncryptionProvider {
 }
 
 /**
- * Current format version constant.
+ * Current format version constant. New vaults are written as `'keystore-v2'`.
  * @public
  */
 declare const KEYSTORE_FORMAT: KeyStoreFormat;
@@ -5107,9 +5343,15 @@ declare const keystoreFile: Converter<IKeyStoreFile>;
 
 /**
  * Format version for key store files.
+ *
+ * - `'keystore-v1'`: the original format (no private-key escrow).
+ * - `'keystore-v2'`: adds the optional `escrowedPrivateKeyJwk` field on
+ *   asymmetric-keypair entries. A strict superset of v1 — the field is
+ *   optional, so a v2 reader opens a v1 vault with no special-casing, and a
+ *   v1 vault opened and re-saved is silently upgraded to v2.
  * @public
  */
-declare type KeyStoreFormat = 'keystore-v1';
+declare type KeyStoreFormat = 'keystore-v1' | 'keystore-v2';
 
 /**
  * Converter for {@link CryptoUtils.KeyStore.KeyStoreFormat | key store format} version.
@@ -5447,6 +5689,30 @@ declare class NodeCryptoProvider implements ICryptoProvider {
      * @returns `Success` with decrypted UTF-8 string, or `Failure` with an error.
      */
     decrypt(encryptedData: Uint8Array, key: Uint8Array, iv: Uint8Array, authTag: Uint8Array): Promise<Result<string>>;
+    /**
+     * Encrypts raw bytes using AES-256-GCM with a caller-supplied nonce and
+     * optional AAD. See {@link CryptoUtils.ICryptoProvider.encryptBytes | ICryptoProvider.encryptBytes}
+     * — in particular the caller's responsibility to use a unique `nonce` per
+     * message under a given `key`.
+     * @param key - 32-byte AES-256 key.
+     * @param nonce - 12-byte GCM nonce (must be unique per message under `key`).
+     * @param plaintext - The bytes to encrypt (empty permitted).
+     * @param aad - Optional additional authenticated data bound into the tag.
+     * @returns `Success` with the ciphertext and 16-byte auth tag, or `Failure` with an error.
+     */
+    encryptBytes(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Promise<Result<IEncryptBytesResult>>;
+    /**
+     * Decrypts raw bytes produced by {@link NodeCryptoProvider.encryptBytes} using
+     * AES-256-GCM. See {@link CryptoUtils.ICryptoProvider.decryptBytes | ICryptoProvider.decryptBytes}.
+     * Fails (never throws) on any authentication failure, including a mismatched `aad`.
+     * @param key - 32-byte AES-256 key.
+     * @param nonce - 12-byte GCM nonce (the same one used to encrypt).
+     * @param ciphertext - The ciphertext from the `encryptBytes` result.
+     * @param authTag - The 16-byte GCM auth tag from the `encryptBytes` result.
+     * @param aad - The identical AAD supplied at encrypt time (or absent).
+     * @returns `Success` with the decrypted plaintext bytes, or `Failure` with an error.
+     */
+    decryptBytes(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, authTag: Uint8Array, aad?: Uint8Array): Promise<Result<Uint8Array>>;
     /**
      * Generates a random 32-byte key suitable for AES-256.
      * @returns `Success` with generated key, or `Failure` with an error.
@@ -5956,6 +6222,22 @@ declare type SecretProvider = (secretName: string) => Promise<Result<Uint8Array>
  */
 declare const SMART_JSON_PROMPT_HINT: string;
 
+/**
+ * Strips the fixed DER prefix from an X25519 SubjectPublicKeyInfo blob, returning the raw
+ * 32-byte public key.
+ *
+ * An X25519 SPKI is always exactly 44 bytes: a fixed 12-byte prefix (SEQUENCE / AlgorithmIdentifier
+ * with OID 1.3.101.110 / BIT STRING) followed by the 32-byte raw key. Use this to convert a
+ * SPKI-held recipient public key into the raw form accepted by {@link HpkeProvider.openBase}'s
+ * `recipientPublicKey` parameter.
+ *
+ * @param spki - The DER-encoded X25519 SubjectPublicKeyInfo bytes.
+ * @returns `Success` with the raw 32-byte public key, or `Failure` if `spki` is not a
+ *   well-formed 44-byte X25519 SPKI blob.
+ * @public
+ */
+declare function spkiToRawX25519(spki: Uint8Array): Result<Uint8Array>;
+
 /**
  * Whether a provider declares any embedding capability at all.
  *

package/lib/packlets/crypto-utils/hpkeProvider.d.ts

@@ -93,15 +93,23 @@ export declare class HpkeProvider {
      *
      * @param recipientPrivateKey - Recipient's X25519 private `CryptoKey`
      *   (`algorithm.name === 'X25519'`, `type === 'private'`, `usages` includes `'deriveBits'`).
-     *   **Must be extractable** (`extractable: true`) — the recipient's public key bytes
-     *   are recovered from the JWK `x` field during Decap.
+     *   **Must be extractable** (`extractable: true`) only when `recipientPublicKey` is not
+     *   supplied — the recipient's public key bytes are then recovered from the JWK `x` field
+     *   during Decap. When `recipientPublicKey` is supplied, `recipientPrivateKey` may be
+     *   non-extractable.
      * @param info - Context-binding bytes. Must exactly match `info` from `sealBase`.
      * @param aad - Must exactly match `aad` from `sealBase`.
      * @param enc - The encapsulated key from `sealBase` — exactly 32 bytes.
      * @param ciphertext - The ciphertext from `sealBase` — `plaintext.length + 16` bytes.
+     * @param recipientPublicKey - Optional raw 32-byte X25519 public key matching
+     *   `recipientPrivateKey` (`pkRm` in RFC 9180 §4.1). Public material — supplying it lets
+     *   Decap build `kem_context` without exporting `recipientPrivateKey` to JWK, so
+     *   `recipientPrivateKey` no longer needs to be extractable. A mismatched value only breaks
+     *   the caller's own decryption (AEAD authentication fails) — it cannot be used to attack
+     *   another party's ciphertext.
      * @returns `Success` with decrypted plaintext bytes, or `Failure` with error context.
      */
-    openBase(recipientPrivateKey: CryptoKey, info: Uint8Array, aad: Uint8Array, enc: Uint8Array, ciphertext: Uint8Array): Promise<Result<Uint8Array>>;
+    openBase(recipientPrivateKey: CryptoKey, info: Uint8Array, aad: Uint8Array, enc: Uint8Array, ciphertext: Uint8Array, recipientPublicKey?: Uint8Array): Promise<Result<Uint8Array>>;
     /**
      * HKDF-SHA256 key derivation (RFC 5869). Extract-then-Expand using SHA-256.
      *

package/lib/packlets/crypto-utils/hpkeProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hpkeProvider.d.ts","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/hpkeProvider.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,MAAM,EAAoD,MAAM,eAAe,CAAC;AAoOzF;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IAEzB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC,OAAO;IAIP;;;;;;;OAOG;WACW,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;IAIhE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,QAAQ,CACnB,kBAAkB,EAAE,SAAS,EAC7B,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IAenC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACU,QAAQ,CACnB,mBAAmB,EAAE,SAAS,EAC9B,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,UAAU,EACf,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAuB9B;;;;;;;;;;;;;OAaG;IACU,IAAI,CACf,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAQ9B;;;;;;;;OAQG;WACW,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,UAAU;IAIjE;;;;;;;;;OASG;WACW,cAAc,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAAC,eAAe,CAAC;CAY5E"}
+{"version":3,"file":"hpkeProvider.d.ts","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/hpkeProvider.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,MAAM,EAAoD,MAAM,eAAe,CAAC;AA+OzF;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IAEzB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC,OAAO;IAIP;;;;;;;OAOG;WACW,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;IAIhE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,QAAQ,CACnB,kBAAkB,EAAE,SAAS,EAC7B,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IAenC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACU,QAAQ,CACnB,mBAAmB,EAAE,SAAS,EAC9B,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,UAAU,EACf,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,UAAU,EACtB,kBAAkB,CAAC,EAAE,UAAU,GAC9B,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IA4B9B;;;;;;;;;;;;;OAaG;IACU,IAAI,CACf,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAQ9B;;;;;;;;OAQG;WACW,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,UAAU;IAIjE;;;;;;;;;OASG;WACW,cAAc,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAAC,eAAe,CAAC;CAY5E"}

package/lib/packlets/crypto-utils/hpkeProvider.js

@@ -141,17 +141,28 @@ async function _kemEncap(subtle, recipientPublicKey) {
 }
 // RFC 9180 §4.1 DHKEM Decap — deserializes enc, DH with recipient privkey,
 // derives same shared_secret via ExtractAndExpand.
-// Requires recipientPrivateKey to be extractable (JWK export needed for pkRm).
-async function _kemDecap(subtle, enc, recipientPrivateKey) {
+// The DH step (deriveBits) works on a non-extractable recipientPrivateKey. Recovering the
+// recipient's own public key bytes (pkRm) for kem_context normally requires a JWK export, which
+// in turn requires recipientPrivateKey to be extractable — UNLESS the caller supplies pkRm
+// directly (raw 32-byte X25519 public key), in which case no JWK export happens and
+// recipientPrivateKey may be non-extractable.
+async function _kemDecap(subtle, enc, recipientPrivateKey, recipientPublicKey) {
     const pkE = await subtle.importKey('raw', _toBufferView(enc), { name: 'X25519' }, true, []);
     const dh = new Uint8Array(await subtle.deriveBits({ name: 'X25519', public: pkE }, recipientPrivateKey, 256));
-    // Recover recipient's own public key from JWK x field (base64url-encoded raw X25519 public key).
-    const jwk = (await subtle.exportKey('jwk', recipientPrivateKey));
-    /* c8 ignore next 3 - defensive: X25519 JWK always has an x field; unreachable via public API */
-    if (!jwk.x) {
-        throw new Error('HPKE Decap: failed to extract public key bytes from recipient private key JWK');
+    let pkRm;
+    if (recipientPublicKey !== undefined) {
+        // Caller-supplied; length already validated in openBase.
+        pkRm = recipientPublicKey;
+    }
+    else {
+        // Recover recipient's own public key from JWK x field (base64url-encoded raw X25519 public key).
+        const jwk = (await subtle.exportKey('jwk', recipientPrivateKey));
+        /* c8 ignore next 3 - defensive: X25519 JWK always has an x field; unreachable via public API */
+        if (!jwk.x) {
+            throw new Error('HPKE Decap: failed to extract public key bytes from recipient private key JWK');
+        }
+        pkRm = _base64UrlDecode(jwk.x);
     }
-    const pkRm = _base64UrlDecode(jwk.x);
     const kemContext = _concat(enc, pkRm);
     const eaePrk = await _labeledExtract(subtle, _KEM_SUITE_ID, new Uint8Array(0), 'eae_prk', dh);
     return _labeledExpand(subtle, _KEM_SUITE_ID, eaePrk, 'shared_secret', kemContext, _N_SECRET);
@@ -255,23 +266,34 @@ class HpkeProvider {
      *
      * @param recipientPrivateKey - Recipient's X25519 private `CryptoKey`
      *   (`algorithm.name === 'X25519'`, `type === 'private'`, `usages` includes `'deriveBits'`).
-     *   **Must be extractable** (`extractable: true`) — the recipient's public key bytes
-     *   are recovered from the JWK `x` field during Decap.
+     *   **Must be extractable** (`extractable: true`) only when `recipientPublicKey` is not
+     *   supplied — the recipient's public key bytes are then recovered from the JWK `x` field
+     *   during Decap. When `recipientPublicKey` is supplied, `recipientPrivateKey` may be
+     *   non-extractable.
      * @param info - Context-binding bytes. Must exactly match `info` from `sealBase`.
      * @param aad - Must exactly match `aad` from `sealBase`.
      * @param enc - The encapsulated key from `sealBase` — exactly 32 bytes.
      * @param ciphertext - The ciphertext from `sealBase` — `plaintext.length + 16` bytes.
+     * @param recipientPublicKey - Optional raw 32-byte X25519 public key matching
+     *   `recipientPrivateKey` (`pkRm` in RFC 9180 §4.1). Public material — supplying it lets
+     *   Decap build `kem_context` without exporting `recipientPrivateKey` to JWK, so
+     *   `recipientPrivateKey` no longer needs to be extractable. A mismatched value only breaks
+     *   the caller's own decryption (AEAD authentication fails) — it cannot be used to attack
+     *   another party's ciphertext.
      * @returns `Success` with decrypted plaintext bytes, or `Failure` with error context.
      */
-    async openBase(recipientPrivateKey, info, aad, enc, ciphertext) {
+    async openBase(recipientPrivateKey, info, aad, enc, ciphertext, recipientPublicKey) {
         if (enc.length !== _N_PK) {
             return (0, ts_utils_1.fail)(`HPKE openBase: enc must be ${_N_PK} bytes, got ${enc.length}`);
         }
         if (ciphertext.length < _N_T) {
             return (0, ts_utils_1.fail)(`HPKE openBase: ciphertext too short (minimum ${_N_T} bytes for auth tag, got ${ciphertext.length})`);
         }
+        if (recipientPublicKey !== undefined && recipientPublicKey.length !== _N_PK) {
+            return (0, ts_utils_1.fail)(`HPKE openBase: recipientPublicKey must be ${_N_PK} bytes, got ${recipientPublicKey.length}`);
+        }
         const result = await (0, ts_utils_1.captureAsyncResult)(async () => {
-            const sharedSecret = await _kemDecap(this._subtle, enc, recipientPrivateKey);
+            const sharedSecret = await _kemDecap(this._subtle, enc, recipientPrivateKey, recipientPublicKey);
             const { key, baseNonce } = await _keyScheduleBase(this._subtle, sharedSecret, info);
             const aesKey = await this._subtle.importKey('raw', key, { name: 'AES-GCM' }, false, ['decrypt']);
             const pt = await this._subtle.decrypt({ name: 'AES-GCM', iv: baseNonce, additionalData: _toBufferView(aad) }, aesKey, _toBufferView(ciphertext));