@fgv/ts-extras 5.1.0-3 → 5.1.0-30

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

@@ -0,0 +1 @@
+{"version":3,"file":"converters.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/converters.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2024 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 { Converters as JsonConverters, JsonValue } from '@fgv/ts-json-base';\nimport { Converter, Converters, fail, succeed } from '@fgv/ts-utils';\nimport * as Constants from './constants';\nimport {\n  EncryptedFileErrorMode,\n  EncryptedFileFormat,\n  EncryptionAlgorithm,\n  IArgon2idKeyDerivationParams,\n  IEncryptedFile,\n  IKeyDerivationParams,\n  INamedSecret,\n  IPbkdf2KeyDerivationParams,\n  KeyDerivationFunction\n} from './model';\n\n// ============================================================================\n// Base Converters\n// ============================================================================\n\n/**\n * Converter for {@link CryptoUtils.EncryptionAlgorithm | encryption algorithm} values.\n * @public\n */\nexport const encryptionAlgorithm: Converter<EncryptionAlgorithm> =\n  Converters.enumeratedValue<EncryptionAlgorithm>([Constants.DEFAULT_ALGORITHM]);\n\n/**\n * Converter for {@link CryptoUtils.EncryptedFileFormat | encrypted file format} version.\n * @public\n */\nexport const encryptedFileFormat: Converter<EncryptedFileFormat> = Converters.enumeratedValue([\n  Constants.ENCRYPTED_FILE_FORMAT\n]);\n\n/**\n * Converter for {@link CryptoUtils.EncryptedFileErrorMode | encrypted file error mode}.\n * @public\n */\nexport const encryptedFileErrorMode: Converter<EncryptedFileErrorMode> =\n  Converters.enumeratedValue<EncryptedFileErrorMode>(['fail', 'skip', 'warn']);\n\n/**\n * Converter for {@link CryptoUtils.KeyDerivationFunction | key derivation function} type.\n * @public\n */\nexport const keyDerivationFunction: Converter<KeyDerivationFunction> =\n  Converters.enumeratedValue<KeyDerivationFunction>(['pbkdf2', 'argon2id']);\n\n/**\n * Converter for {@link CryptoUtils.IPbkdf2KeyDerivationParams | PBKDF2 key derivation parameters}.\n * @public\n */\nexport const pbkdf2KeyDerivationParams: Converter<IPbkdf2KeyDerivationParams> =\n  Converters.object<IPbkdf2KeyDerivationParams>({\n    kdf: Converters.enumeratedValue<'pbkdf2'>(['pbkdf2']),\n    salt: Converters.string,\n    iterations: Converters.number\n  });\n\n/**\n * Converter for {@link CryptoUtils.IArgon2idKeyDerivationParams | Argon2id key derivation parameters}.\n * @public\n */\nexport const argon2idKeyDerivationParams: Converter<IArgon2idKeyDerivationParams> =\n  Converters.object<IArgon2idKeyDerivationParams>({\n    kdf: Converters.enumeratedValue<'argon2id'>(['argon2id']),\n    salt: Converters.string,\n    memoryKiB: Converters.number,\n    iterations: Converters.number,\n    parallelism: Converters.number\n  });\n\n/**\n * Converter for {@link CryptoUtils.IKeyDerivationParams | key derivation parameters}.\n * Handles both PBKDF2 and Argon2id discriminated union arms.\n * @public\n */\nexport const keyDerivationParams: Converter<IKeyDerivationParams> = Converters.oneOf<IKeyDerivationParams>([\n  pbkdf2KeyDerivationParams,\n  argon2idKeyDerivationParams\n]);\n\n/**\n * Converter for base64 strings (validates format).\n * @public\n */\nexport const base64String: Converter<string> = Converters.string.withConstraint((value) => {\n  // Basic base64 validation - check for valid characters and padding\n  const base64Regex = /^[A-Za-z0-9+/]*={0,2}$/;\n  if (!base64Regex.test(value)) {\n    return fail('Invalid base64 encoding');\n  }\n  return succeed(value);\n});\n\n// ============================================================================\n// Uint8Array Converter\n// ============================================================================\n\n/**\n * Converter which converts a base64 string to a Uint8Array.\n * @public\n */\nexport const uint8ArrayFromBase64: Converter<Uint8Array> = Converters.string.map((base64) => {\n  try {\n    // Use Buffer in Node.js environment, atob in browser\n    if (typeof Buffer !== 'undefined') {\n      return succeed(Uint8Array.from(Buffer.from(base64, 'base64')));\n    }\n    /* c8 ignore start - Browser-only fallback cannot be tested in Node.js environment */\n    const binaryString = atob(base64);\n    const bytes = new Uint8Array(binaryString.length);\n    for (let i = 0; i < binaryString.length; i++) {\n      bytes[i] = binaryString.charCodeAt(i);\n    }\n    return succeed(bytes);\n  } catch (e) {\n    // This catch is for browser's atob() which throws on invalid base64\n    // Node's Buffer.from() doesn't throw, it ignores invalid characters\n    const message = e instanceof Error ? e.message : String(e);\n    return fail(`Invalid base64: ${message}`);\n  }\n  /* c8 ignore stop */\n});\n\n// ============================================================================\n// Named Secret Converter\n// ============================================================================\n\n/**\n * Converter for {@link CryptoUtils.INamedSecret | named secret} from JSON representation.\n * Expects key as base64 string in JSON, converts to Uint8Array.\n * @public\n */\nexport const namedSecret: Converter<INamedSecret> = Converters.object<INamedSecret>({\n  name: Converters.string,\n  key: uint8ArrayFromBase64\n});\n\n// ============================================================================\n// Encrypted File Converter Factory\n// ============================================================================\n\n/**\n * Base encrypted file structure without metadata typing.\n * Used internally by the converter factory.\n */\ninterface IBaseEncryptedFile {\n  readonly format: EncryptedFileFormat;\n  readonly secretName: string;\n  readonly algorithm: EncryptionAlgorithm;\n  readonly iv: string;\n  readonly authTag: string;\n  readonly encryptedData: string;\n  readonly keyDerivation?: IKeyDerivationParams;\n  readonly metadata?: JsonValue;\n}\n\n/**\n * Base converter for encrypted file structure (without typed metadata).\n */\nconst baseEncryptedFileConverter: Converter<IBaseEncryptedFile> = Converters.object<IBaseEncryptedFile>(\n  {\n    format: encryptedFileFormat,\n    secretName: Converters.string,\n    algorithm: encryptionAlgorithm,\n    iv: base64String,\n    authTag: base64String,\n    encryptedData: base64String,\n    keyDerivation: keyDerivationParams,\n    metadata: JsonConverters.jsonValue\n  },\n  { optionalFields: ['keyDerivation', 'metadata'] }\n);\n\n/**\n * Creates a converter for {@link CryptoUtils.IEncryptedFile | encrypted files} with optional typed metadata.\n * @typeParam TMetadata - Type of optional unencrypted metadata\n * @param metadataConverter - Optional converter for validating metadata field\n * @returns A converter that validates and converts encrypted file structures\n * @public\n */\nexport function createEncryptedFileConverter<TMetadata = JsonValue>(\n  metadataConverter?: Converter<TMetadata>\n): Converter<IEncryptedFile<TMetadata>> {\n  return Converters.generic<IEncryptedFile<TMetadata>>((from: unknown) => {\n    // First validate base structure\n    const baseResult = baseEncryptedFileConverter.convert(from);\n    if (baseResult.isFailure()) {\n      return fail(baseResult.message);\n    }\n\n    const base = baseResult.value;\n\n    // Validate metadata with specific converter if provided and metadata exists\n    if (metadataConverter !== undefined && base.metadata !== undefined) {\n      const metaResult = metadataConverter.convert(base.metadata);\n      if (metaResult.isFailure()) {\n        return fail(`Invalid metadata: ${metaResult.message}`);\n      }\n      return succeed({\n        ...base,\n        metadata: metaResult.value\n      } as IEncryptedFile<TMetadata>);\n    }\n\n    // Return as-is (metadata is either undefined or untyped JsonValue)\n    return succeed(base as IEncryptedFile<TMetadata>);\n  });\n}\n\n/**\n * Default converter for encrypted files without typed metadata.\n * @public\n */\nexport const encryptedFile: Converter<IEncryptedFile> = createEncryptedFileConverter();\n"]}

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

@@ -0,0 +1 @@
+{"version":3,"file":"directEncryptionProvider.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/directEncryptionProvider.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY;AAGZ,OAAO,EAAU,IAAI,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AA0BtD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,wBAAwB;IAKnC,YAAoB,MAAuC;QACzD,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,cAAc,CAAC;QAC7C,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC;QACvB,IAAI,CAAC,gBAAgB,GAAG,MAAM,CAAC,eAAe,CAAC;IACjD,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,MAAM,CAAC,MAAuC;QAC1D,IAAI,MAAM,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC,gCAAgC,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,OAAO,CAAC,IAAI,wBAAwB,CAAC,MAAM,CAAC,CAAC,CAAC;IACvD,CAAC;IAED;;;OAGG;IACH,IAAW,eAAe;QACxB,OAAO,IAAI,CAAC,gBAAgB,CAAC;IAC/B,CAAC;IAED;;OAEG;IACI,KAAK,CAAC,aAAa,CACxB,UAAkB,EAClB,OAAkB,EAClB,QAAoB;QAEpB,IAAI,IAAI,CAAC,gBAAgB,KAAK,SAAS,IAAI,UAAU,KAAK,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAChF,OAAO,IAAI,CACT,oCAAoC,UAAU,+BAA+B,IAAI,CAAC,gBAAgB,GAAG,CACtG,CAAC;QACJ,CAAC;QAED,OAAO,mBAAmB,CAAC;YACzB,OAAO;YACP,UAAU;YACV,GAAG,EAAE,IAAI,CAAC,IAAI;YACd,cAAc,EAAE,IAAI,CAAC,eAAe;YACpC,QAAQ;SACT,CAAC,CAAC;IACL,CAAC;CACF","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 { JsonValue } from '@fgv/ts-json-base';\nimport { Result, fail, succeed } from '@fgv/ts-utils';\nimport { createEncryptedFile } from './encryptedFile';\nimport { ICryptoProvider, IEncryptedFile, IEncryptionProvider } from './model';\n\n/**\n * Parameters for creating a {@link DirectEncryptionProvider}.\n * @public\n */\nexport interface IDirectEncryptionProviderParams {\n  /**\n   * The crypto provider to use for encryption operations.\n   */\n  readonly cryptoProvider: ICryptoProvider;\n\n  /**\n   * The encryption key (32 bytes for AES-256).\n   */\n  readonly key: Uint8Array;\n\n  /**\n   * Optional bound secret name.\n   * When set, `encryptByName` will fail if called with a different name.\n   * When unset, any secret name is accepted.\n   */\n  readonly boundSecretName?: string;\n}\n\n/**\n * An {@link IEncryptionProvider} that uses a pre-supplied key and crypto provider.\n *\n * This is useful when you have the raw encryption key from an external source\n * (e.g. a `SecretProvider` callback, password derivation, or a one-shot\n * operation) and don't want to open a full KeyStore.\n *\n * Optionally bound to a specific secret name for safety: if a `boundSecretName`\n * is provided, calls to `encryptByName` with a different name will fail.\n *\n * @example\n * ```typescript\n * const provider = DirectEncryptionProvider.create({\n *   cryptoProvider: nodeCryptoProvider,\n *   key: myKey,\n *   boundSecretName: 'my-collection'\n * }).orThrow();\n *\n * const encrypted = await provider.encryptByName('my-collection', jsonContent);\n * ```\n *\n * @public\n */\nexport class DirectEncryptionProvider implements IEncryptionProvider {\n  private readonly _cryptoProvider: ICryptoProvider;\n  private readonly _key: Uint8Array;\n  private readonly _boundSecretName: string | undefined;\n\n  private constructor(params: IDirectEncryptionProviderParams) {\n    this._cryptoProvider = params.cryptoProvider;\n    this._key = params.key;\n    this._boundSecretName = params.boundSecretName;\n  }\n\n  /**\n   * Creates a new DirectEncryptionProvider.\n   * @param params - Provider configuration\n   * @returns Success with provider, or Failure if parameters are invalid\n   * @public\n   */\n  public static create(params: IDirectEncryptionProviderParams): Result<DirectEncryptionProvider> {\n    if (params.key.length === 0) {\n      return fail('Encryption key cannot be empty');\n    }\n    return succeed(new DirectEncryptionProvider(params));\n  }\n\n  /**\n   * The secret name this provider is bound to, if any.\n   * @public\n   */\n  public get boundSecretName(): string | undefined {\n    return this._boundSecretName;\n  }\n\n  /**\n   * {@inheritDoc IEncryptionProvider.encryptByName}\n   */\n  public async encryptByName<TMetadata = JsonValue>(\n    secretName: string,\n    content: JsonValue,\n    metadata?: TMetadata\n  ): Promise<Result<IEncryptedFile<TMetadata>>> {\n    if (this._boundSecretName !== undefined && secretName !== this._boundSecretName) {\n      return fail(\n        `Secret name mismatch: requested '${secretName}' but provider is bound to '${this._boundSecretName}'`\n      );\n    }\n\n    return createEncryptedFile({\n      content,\n      secretName,\n      key: this._key,\n      cryptoProvider: this._cryptoProvider,\n      metadata\n    });\n  }\n}\n"]}

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

@@ -0,0 +1 @@
+{"version":3,"file":"encryptedFile.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/encryptedFile.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2024 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 { JsonValue } from '@fgv/ts-json-base';\nimport { captureResult, Converter, fail, Result, succeed } from '@fgv/ts-utils';\nimport * as Constants from './constants';\nimport { createEncryptedFileConverter } from './converters';\nimport { ICryptoProvider, IEncryptedFile, IKeyDerivationParams, isEncryptedFile } from './model';\n\n// ============================================================================\n// Base64 Utilities\n// ============================================================================\n\n/**\n * Encodes a `Uint8Array` to a base64 string.\n * @param bytes - Bytes to encode\n * @returns Base64 string\n * @public\n */\n/* c8 ignore start - Browser-only fallback cannot be tested in Node.js environment */\nexport function toBase64(bytes: Uint8Array): string {\n  if (typeof Buffer !== 'undefined') {\n    return Buffer.from(bytes).toString('base64');\n  }\n  // Browser fallback\n  let binary = '';\n  for (let i = 0; i < bytes.length; i++) {\n    binary += String.fromCharCode(bytes[i]);\n  }\n  return btoa(binary);\n}\n/* c8 ignore stop */\n\n/**\n * Decodes a base64 string to a `Uint8Array`.\n * @param base64 - Base64 string to decode\n * @returns Decoded bytes\n * @public\n */\n/* c8 ignore start - Browser-only fallback cannot be tested in Node.js environment */\nexport function fromBase64(base64: string): Uint8Array {\n  if (typeof Buffer !== 'undefined') {\n    return new Uint8Array(Buffer.from(base64, 'base64'));\n  }\n  // Browser fallback\n  const binary = atob(base64);\n  const bytes = new Uint8Array(binary.length);\n  for (let i = 0; i < binary.length; i++) {\n    bytes[i] = binary.charCodeAt(i);\n  }\n  return bytes;\n}\n/* c8 ignore stop */\n\n// ============================================================================\n// Create Encrypted File Parameters\n// ============================================================================\n\n/**\n * Parameters for creating an {@link CryptoUtils.IEncryptedFile | encrypted file}.\n * @typeParam TMetadata - Type of optional unencrypted metadata\n * @public\n */\nexport interface ICreateEncryptedFileParams<TMetadata = JsonValue> {\n  /**\n   * The JSON content to encrypt.\n   */\n  readonly content: JsonValue;\n\n  /**\n   * Name of the secret used for encryption.\n   */\n  readonly secretName: string;\n\n  /**\n   * The encryption key (32 bytes for AES-256).\n   */\n  readonly key: Uint8Array;\n\n  /**\n   * {@link CryptoUtils.ICryptoProvider | Crypto provider} to use for encryption.\n   */\n  readonly cryptoProvider: ICryptoProvider;\n\n  /**\n   * Optional metadata to include unencrypted.\n   */\n  readonly metadata?: TMetadata;\n\n  /**\n   * Optional converter to validate metadata before including.\n   * If provided, metadata will be validated before encryption.\n   */\n  readonly metadataConverter?: Converter<TMetadata>;\n\n  /**\n   * Optional {@link CryptoUtils.IKeyDerivationParams | key derivation parameters}.\n   * If provided, stores the salt and iterations used to derive the key from a password.\n   * This allows decryption using only a password (the salt/iterations are read from the file).\n   */\n  readonly keyDerivation?: IKeyDerivationParams;\n}\n\n// ============================================================================\n// Encryption Functions\n// ============================================================================\n\n/**\n * Creates an {@link CryptoUtils.IEncryptedFile | encrypted file} from JSON content.\n * @typeParam TMetadata - Type of optional unencrypted metadata\n * @param params - Encryption parameters\n * @returns `Success` with encrypted file structure, or `Failure` with an error.\n * @public\n */\nexport async function createEncryptedFile<TMetadata = JsonValue>(\n  params: ICreateEncryptedFileParams<TMetadata>\n): Promise<Result<IEncryptedFile<TMetadata>>> {\n  const { content, secretName, key, metadata, metadataConverter, keyDerivation, cryptoProvider } = params;\n\n  // Validate metadata if converter provided\n  /* c8 ignore next 6 - metadata validation path exercised via higher-level tests */\n  if (metadata !== undefined && metadataConverter !== undefined) {\n    const metadataResult = metadataConverter.convert(metadata);\n    if (metadataResult.isFailure()) {\n      return fail(`Invalid metadata: ${metadataResult.message}`);\n    }\n  }\n\n  // Serialize content to JSON string\n  const jsonResult = captureResult(() => JSON.stringify(content));\n  if (jsonResult.isFailure()) {\n    return fail(`Failed to serialize content: ${jsonResult.message}`);\n  }\n\n  // Encrypt the JSON string\n  const encryptResult = await cryptoProvider.encrypt(jsonResult.value, key);\n  if (encryptResult.isFailure()) {\n    return fail(`Encryption failed: ${encryptResult.message}`);\n  }\n\n  const { iv, authTag, encryptedData } = encryptResult.value;\n\n  // Build the encrypted file structure\n  const encryptedFile: IEncryptedFile<TMetadata> = {\n    format: Constants.ENCRYPTED_FILE_FORMAT,\n    secretName,\n    algorithm: Constants.DEFAULT_ALGORITHM,\n    iv: toBase64(iv),\n    authTag: toBase64(authTag),\n    encryptedData: toBase64(encryptedData),\n    ...(metadata !== undefined ? { metadata } : {}),\n    ...(keyDerivation !== undefined ? { keyDerivation } : {})\n  };\n\n  return succeed(encryptedFile);\n}\n\n// ============================================================================\n// Decryption Functions\n// ============================================================================\n\n/**\n * Decrypts an {@link CryptoUtils.IEncryptedFile | encrypted file} and returns the JSON content.\n * @typeParam TPayload - Expected type of decrypted content\n * @param file - The encrypted file structure\n * @param key - The decryption key (32 bytes for AES-256)\n * @param cryptoProvider - {@link CryptoUtils.ICryptoProvider | Crypto provider} to use for decryption\n * @param payloadConverter - Optional converter to validate and convert decrypted content\n * @returns `Success` with decrypted content, or `Failure` with an error.\n * @public\n */\nexport async function decryptFile<TPayload extends JsonValue = JsonValue>(\n  file: IEncryptedFile<unknown>,\n  key: Uint8Array,\n  cryptoProvider: ICryptoProvider,\n  payloadConverter?: Converter<TPayload>\n): Promise<Result<TPayload>> {\n  // Decode base64 values\n  const iv = fromBase64(file.iv);\n  const authTag = fromBase64(file.authTag);\n  const encryptedData = fromBase64(file.encryptedData);\n\n  // Decrypt\n  const decryptResult = await cryptoProvider.decrypt(encryptedData, key, iv, authTag);\n  if (decryptResult.isFailure()) {\n    return fail(decryptResult.message);\n  }\n\n  // Parse JSON\n  const parseResult = captureResult(() => JSON.parse(decryptResult.value) as TPayload).withErrorFormat(\n    (e) => `Failed to parse decrypted content as JSON: ${e}`\n  );\n\n  /* c8 ignore next 3 - JSON parse failure only occurs with corrupted encrypted data */\n  if (parseResult.isFailure()) {\n    return parseResult;\n  }\n\n  // Validate with converter if provided\n  /* c8 ignore next 3 - payload converter path exercised via higher-level tests */\n  if (payloadConverter !== undefined) {\n    return payloadConverter.convert(parseResult.value);\n  }\n\n  return parseResult;\n}\n\n/**\n * Attempts to parse and decrypt a JSON object as an {@link CryptoUtils.IEncryptedFile | encrypted file}.\n * @typeParam TPayload - Expected type of decrypted content\n * @typeParam TMetadata - Type of optional unencrypted metadata\n * @param json - JSON object that may be an encrypted file\n * @param key - The decryption key (32 bytes for AES-256)\n * @param cryptoProvider - {@link CryptoUtils.ICryptoProvider | Crypto provider} to use for decryption\n * @param payloadConverter - Optional converter to validate and convert decrypted content\n * @param metadataConverter - Optional converter to validate metadata before decryption\n * @returns `Success` with decrypted content, or `Failure` with an error (including if not encrypted)\n * @public\n */\nexport async function tryDecryptFile<TPayload extends JsonValue = JsonValue, TMetadata = JsonValue>(\n  json: JsonValue,\n  key: Uint8Array,\n  cryptoProvider: ICryptoProvider,\n  payloadConverter?: Converter<TPayload>,\n  metadataConverter?: Converter<TMetadata>\n): Promise<Result<TPayload>> {\n  // Check if it's an encrypted file\n  if (!isEncryptedFile(json)) {\n    return fail('Not an encrypted file');\n  }\n\n  // Validate and convert to typed encrypted file\n  const fileConverter = createEncryptedFileConverter(metadataConverter);\n  const fileResult = fileConverter.convert(json);\n  if (fileResult.isFailure()) {\n    return fail(`Invalid encrypted file format: ${fileResult.message}`);\n  }\n\n  return decryptFile(fileResult.value, key, cryptoProvider, payloadConverter);\n}\n"]}

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

@@ -0,0 +1,333 @@
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+import { captureAsyncResult, captureResult, fail, succeed } from '@fgv/ts-utils';
+// ---- Internal constants ----
+// "HPKE-v1" (7 bytes) — RFC 9180 domain separator prefix
+const _HPKE_VERSION = new Uint8Array([0x48, 0x50, 0x4b, 0x45, 0x2d, 0x76, 0x31]);
+// suite_id = "HPKE" || I2OSP(KEM_ID=0x0020, 2) || I2OSP(KDF_ID=0x0001, 2) || I2OSP(AEAD_ID=0x0002, 2)
+// Used in key schedule LabeledExtract/LabeledExpand calls.
+const _SUITE_ID = new Uint8Array([
+    0x48, 0x50, 0x4b, 0x45, 0x00, 0x20, 0x00, 0x01, 0x00, 0x02
+]);
+// kem_suite_id = "KEM" || I2OSP(KEM_ID=0x0020, 2)
+// Used in DHKEM-internal LabeledExtract/LabeledExpand calls.
+const _KEM_SUITE_ID = new Uint8Array([0x4b, 0x45, 0x4d, 0x00, 0x20]);
+const _N_SECRET = 32; // Nsecret: KEM shared-secret output length
+const _N_PK = 32; // Npk: X25519 public key (raw) length — also the enc length
+const _N_K = 32; // Nk: AES-256-GCM key length
+const _N_N = 12; // Nn: AES-256-GCM nonce length
+const _N_T = 16; // Nt: AES-256-GCM authentication tag length
+const _MODE_BASE = 0x00; // RFC 9180 mode_base
+// ---- Internal helpers ----
+// These are NOT exported. Per design D7, only the five public operations are public surface.
+// Copies any Uint8Array into a fresh Uint8Array<ArrayBuffer>.
+// Required to satisfy TypeScript's strict BufferSource typing for Web Crypto API calls —
+// subtle.* rejects Uint8Array<ArrayBufferLike> but accepts Uint8Array<ArrayBuffer>.
+// Pattern follows browserCryptoProvider.ts toBufferView.
+function _toBufferView(arr) {
+    const buffer = new ArrayBuffer(arr.byteLength);
+    const view = new Uint8Array(buffer);
+    view.set(arr);
+    return view;
+}
+function _concat(...arrays) {
+    const total = arrays.reduce((n, a) => n + a.length, 0);
+    const buffer = new ArrayBuffer(total);
+    const out = new Uint8Array(buffer);
+    let offset = 0;
+    for (const a of arrays) {
+        out.set(a, offset);
+        offset += a.length;
+    }
+    return out;
+}
+function _i2osp(value, length) {
+    const buffer = new ArrayBuffer(length);
+    const out = new Uint8Array(buffer);
+    for (let i = length - 1; i >= 0; i--) {
+        out[i] = value % 256;
+        value = Math.floor(value / 256);
+    }
+    return out;
+}
+// Decodes a base64url-encoded string to Uint8Array<ArrayBuffer>.
+// Uses `atob` (global in Node 18+ and all modern browsers; no import needed).
+function _base64UrlDecode(s) {
+    const base64 = s.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);
+    const binary = atob(padded);
+    const buffer = new ArrayBuffer(binary.length);
+    const out = new Uint8Array(buffer);
+    for (let i = 0; i < binary.length; i++) {
+        out[i] = binary.charCodeAt(i);
+    }
+    return out;
+}
+// HMAC-SHA256(key, data) — the underlying primitive for HKDF.
+async function _hmacSha256(subtle, key, data) {
+    const hmacKey = await subtle.importKey('raw', _toBufferView(key), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    return new Uint8Array(await subtle.sign('HMAC', hmacKey, _toBufferView(data)));
+}
+// RFC 5869 HKDF-Extract(salt, IKM) = HMAC-SHA256(key=salt, msg=IKM).
+// If salt is empty (length 0), uses 32 zero bytes per RFC 5869 §2.2.
+async function _hkdfExtract(subtle, salt, ikm) {
+    const effectiveSalt = salt.length === 0 ? new Uint8Array(32) : salt;
+    return _hmacSha256(subtle, effectiveSalt, ikm);
+}
+// RFC 5869 HKDF-Expand(PRK, info, L) — iterative HMAC expansion.
+async function _hkdfExpand(subtle, prk, info, length) {
+    if (length > 255 * 32) {
+        throw new Error(`HKDF-Expand: requested length ${length} exceeds maximum 8160 bytes (255 * HashLen)`);
+    }
+    const n = Math.ceil(length / 32);
+    const buffer = new ArrayBuffer(length);
+    const okm = new Uint8Array(buffer);
+    let prev = new Uint8Array(new ArrayBuffer(0));
+    let offset = 0;
+    for (let i = 1; i <= n; i++) {
+        prev = await _hmacSha256(subtle, prk, _concat(prev, info, new Uint8Array([i])));
+        const toCopy = Math.min(32, length - offset);
+        okm.set(prev.subarray(0, toCopy), offset);
+        offset += toCopy;
+    }
+    return okm;
+}
+// RFC 9180 §4 LabeledExtract — HKDF-Extract with HPKE-v1 domain label.
+// labeled_ikm = "HPKE-v1" || suite_id || label || ikm
+// Extract(salt, labeled_ikm)
+async function _labeledExtract(subtle, suiteId, salt, label, ikm) {
+    const labeledIkm = _concat(_HPKE_VERSION, suiteId, new TextEncoder().encode(label), ikm);
+    return _hkdfExtract(subtle, salt, labeledIkm);
+}
+// RFC 9180 §4 LabeledExpand — HKDF-Expand with HPKE-v1 domain label.
+// labeled_info = I2OSP(L, 2) || "HPKE-v1" || suite_id || label || info
+// Expand(prk, labeled_info, L)
+async function _labeledExpand(subtle, suiteId, prk, label, info, length) {
+    const labeledInfo = _concat(_i2osp(length, 2), _HPKE_VERSION, suiteId, new TextEncoder().encode(label), info);
+    return _hkdfExpand(subtle, prk, labeledInfo, length);
+}
+// RFC 9180 §4.1 DHKEM Encap — generates ephemeral keypair, DH with recipient pubkey,
+// derives shared_secret via ExtractAndExpand.
+// NOTE: uses label "eae_prk" (not "dh") per RFC 9180 §4.1 ExtractAndExpand.
+async function _kemEncap(subtle, recipientPublicKey) {
+    const ephemeral = (await subtle.generateKey({ name: 'X25519' }, true, ['deriveBits']));
+    const enc = new Uint8Array(await subtle.exportKey('raw', ephemeral.publicKey));
+    const dh = new Uint8Array(await subtle.deriveBits({ name: 'X25519', public: recipientPublicKey }, ephemeral.privateKey, 256));
+    const pkRm = new Uint8Array(await subtle.exportKey('raw', recipientPublicKey));
+    const kemContext = _concat(enc, pkRm);
+    const eaePrk = await _labeledExtract(subtle, _KEM_SUITE_ID, new Uint8Array(0), 'eae_prk', dh);
+    const sharedSecret = await _labeledExpand(subtle, _KEM_SUITE_ID, eaePrk, 'shared_secret', kemContext, _N_SECRET);
+    return { sharedSecret, enc };
+}
+// 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) {
+    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');
+    }
+    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);
+}
+// RFC 9180 §5 KeySchedule (base mode, psk = b"", psk_id = b"").
+async function _keyScheduleBase(subtle, sharedSecret, info) {
+    const empty = new Uint8Array(0);
+    const pskIdHash = await _labeledExtract(subtle, _SUITE_ID, empty, 'psk_id_hash', empty);
+    const infoHash = await _labeledExtract(subtle, _SUITE_ID, empty, 'info_hash', info);
+    const ksContext = _concat(new Uint8Array([_MODE_BASE]), pskIdHash, infoHash);
+    const prk = await _labeledExtract(subtle, _SUITE_ID, sharedSecret, 'secret', empty);
+    const key = await _labeledExpand(subtle, _SUITE_ID, prk, 'key', ksContext, _N_K);
+    const baseNonce = await _labeledExpand(subtle, _SUITE_ID, prk, 'base_nonce', ksContext, _N_N);
+    return { key, baseNonce };
+}
+// ---- Public class ----
+/**
+ * HPKE base mode (RFC 9180) — `DHKEM(X25519, HKDF-SHA256) + HKDF-SHA256 + AES-256-GCM`.
+ *
+ * Class-based provider that captures a `SubtleCrypto` instance at construction,
+ * matching the existing `NodeCryptoProvider` / `BrowserCryptoProvider` / `KeyStore`
+ * factory pattern used throughout `@fgv/ts-extras/crypto-utils`.
+ *
+ * **Node.js usage:**
+ * ```typescript
+ * import * as crypto from 'crypto';
+ * const hpke = HpkeProvider.create(crypto.webcrypto.subtle).orThrow();
+ * ```
+ *
+ * **Browser usage:**
+ * ```typescript
+ * const hpke = HpkeProvider.create(globalThis.crypto.subtle).orThrow();
+ * ```
+ *
+ * **Runtime requirements:** Node.js 20+ (X25519 in `crypto.webcrypto`);
+ * Chrome 113+, Safari 16.4+, Firefox 118+ (X25519 added to Web Crypto in 2023).
+ * @public
+ */
+export class HpkeProvider {
+    constructor(subtle) {
+        this._subtle = subtle;
+    }
+    /**
+     * Creates an `HpkeProvider` bound to the given `SubtleCrypto` instance.
+     *
+     * @param subtle - Web Crypto SubtleCrypto instance.
+     *   Node.js: `(await import('crypto')).webcrypto.subtle`.
+     *   Browser: `globalThis.crypto.subtle`.
+     * @returns `Success` with the provider, or `Failure` if construction fails.
+     */
+    static create(subtle) {
+        return captureResult(() => new HpkeProvider(subtle));
+    }
+    /**
+     * HPKE base-mode seal (sender side). RFC 9180 §6.1.
+     *
+     * Generates a fresh ephemeral X25519 keypair, runs DHKEM Encap to produce a
+     * shared secret and `enc` (32-byte raw ephemeral public key), derives the AEAD
+     * key and nonce deterministically via the RFC 9180 key schedule, then encrypts
+     * `plaintext` with AES-256-GCM.
+     *
+     * @param recipientPublicKey - Recipient's X25519 public `CryptoKey`
+     *   (`algorithm.name === 'X25519'`, `type === 'public'`, **`extractable: true`**).
+     *   Must be extractable — DHKEM Encap calls `exportKey('raw', ...)` on this key to
+     *   build the KEM shared-secret context. Keys imported with `extractable: false` will
+     *   cause this method to return a `Failure`.
+     * @param info - Context-binding bytes. **Load-bearing — no default.**
+     *   Binds this ciphertext to a specific application context, preventing replay
+     *   across different contexts sharing the same recipient keypair.
+     *   Use `new TextEncoder().encode('myapp/v1/use-case\x00' + contextId)` pattern.
+     *   Never pass an empty array in production: empty `info` provides no context binding.
+     * @param aad - Additional authenticated data. Integrity-protected but not encrypted.
+     *   `new Uint8Array(0)` is valid when no AAD is needed.
+     * @param plaintext - Bytes to encrypt. `new Uint8Array(0)` is valid.
+     * @returns `Success` with `{ enc, ciphertext }`, or `Failure` with error context.
+     */
+    async sealBase(recipientPublicKey, info, aad, plaintext) {
+        const result = await captureAsyncResult(async () => {
+            const { sharedSecret, enc } = await _kemEncap(this._subtle, recipientPublicKey);
+            const { key, baseNonce } = await _keyScheduleBase(this._subtle, sharedSecret, info);
+            const aesKey = await this._subtle.importKey('raw', key, { name: 'AES-GCM' }, false, ['encrypt']);
+            const ct = await this._subtle.encrypt({ name: 'AES-GCM', iv: baseNonce, additionalData: _toBufferView(aad) }, aesKey, _toBufferView(plaintext));
+            return { enc, ciphertext: new Uint8Array(ct) };
+        });
+        return result.withErrorFormat((e) => `HPKE sealBase failed: ${e}`);
+    }
+    /**
+     * HPKE base-mode open (recipient side). RFC 9180 §6.1.
+     *
+     * Decapsulates `enc` using the recipient's X25519 private key, derives the same
+     * AEAD key and nonce from the shared secret and `info`, then authenticates and
+     * decrypts `ciphertext` with AES-256-GCM.
+     *
+     * Returns `Failure` on any of:
+     * - Wrong private key (different DH output → different key derivation)
+     * - Wrong `info` (different key schedule context → different AEAD key)
+     * - Wrong `aad` (AES-GCM authentication fails)
+     * - Tampered `ciphertext` or `enc` (authentication fails or DH fails)
+     * - `enc` not exactly 32 bytes
+     * - `ciphertext` shorter than 16 bytes (no room for authentication tag)
+     *
+     * @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.
+     * @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.
+     * @returns `Success` with decrypted plaintext bytes, or `Failure` with error context.
+     */
+    async openBase(recipientPrivateKey, info, aad, enc, ciphertext) {
+        if (enc.length !== _N_PK) {
+            return fail(`HPKE openBase: enc must be ${_N_PK} bytes, got ${enc.length}`);
+        }
+        if (ciphertext.length < _N_T) {
+            return fail(`HPKE openBase: ciphertext too short (minimum ${_N_T} bytes for auth tag, got ${ciphertext.length})`);
+        }
+        const result = await captureAsyncResult(async () => {
+            const sharedSecret = await _kemDecap(this._subtle, enc, recipientPrivateKey);
+            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));
+            return new Uint8Array(pt);
+        });
+        return result.withErrorFormat((e) => `HPKE openBase failed: ${e}`);
+    }
+    /**
+     * HKDF-SHA256 key derivation (RFC 5869). Extract-then-Expand using SHA-256.
+     *
+     * This is raw RFC 5869 HKDF — it does **not** use RFC 9180's labeled variants.
+     * The HPKE key schedule internally uses labeled HKDF; this method is the unlabeled
+     * version for callers that need standalone key derivation.
+     *
+     * @param secret - Input keying material (IKM). Any length.
+     * @param salt - Optional salt. Use `new Uint8Array(0)` if no salt is available
+     *   (RFC 5869: 32 zero bytes are used internally when salt is empty).
+     * @param info - Context / application-binding bytes. Any length.
+     * @param length - Number of output bytes to derive. Maximum 8160 bytes (255 × 32).
+     * @returns `Success` with derived bytes, or `Failure` with error context.
+     */
+    async hkdf(secret, salt, info, length) {
+        const result = await captureAsyncResult(async () => {
+            const prk = await _hkdfExtract(this._subtle, salt, secret);
+            return _hkdfExpand(this._subtle, prk, info, length);
+        });
+        return result.withErrorFormat((e) => `HKDF failed: ${e}`);
+    }
+    /**
+     * Encodes an {@link IHpkeSealResult} as a single contiguous byte array for wire transport.
+     *
+     * Format: `enc` (32 bytes, fixed) || `ciphertext` (variable length).
+     * The 32-byte `enc` length is fixed for X25519; the split point is unambiguous.
+     *
+     * @param result - The output of {@link HpkeProvider.sealBase}.
+     * @returns Concatenated bytes: `enc || ciphertext`.
+     */
+    static encodeEnvelope(result) {
+        return _concat(result.enc, result.ciphertext);
+    }
+    /**
+     * Decodes an envelope produced by {@link HpkeProvider.encodeEnvelope}.
+     *
+     * Validates that the buffer is at least 48 bytes (32-byte enc + 16-byte minimum
+     * ciphertext containing the AES-GCM auth tag; zero-length plaintext is the minimum
+     * meaningful case).
+     *
+     * @param envelope - Envelope bytes from `encodeEnvelope`.
+     * @returns `Success` with `{ enc, ciphertext }`, or `Failure` if malformed.
+     */
+    static decodeEnvelope(envelope) {
+        const minLen = _N_PK + _N_T;
+        if (envelope.length < minLen) {
+            return fail(`HPKE decodeEnvelope: envelope too short (minimum ${minLen} bytes, got ${envelope.length})`);
+        }
+        return succeed({
+            enc: envelope.slice(0, _N_PK),
+            ciphertext: envelope.slice(_N_PK)
+        });
+    }
+}
+//# sourceMappingURL=hpkeProvider.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hpkeProvider.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/hpkeProvider.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, captureAsyncResult, captureResult, fail, succeed } from '@fgv/ts-utils';\n\n// ---- Internal constants ----\n\n// \"HPKE-v1\" (7 bytes) — RFC 9180 domain separator prefix\nconst _HPKE_VERSION: Uint8Array<ArrayBuffer> = new Uint8Array([0x48, 0x50, 0x4b, 0x45, 0x2d, 0x76, 0x31]);\n\n// suite_id = \"HPKE\" || I2OSP(KEM_ID=0x0020, 2) || I2OSP(KDF_ID=0x0001, 2) || I2OSP(AEAD_ID=0x0002, 2)\n// Used in key schedule LabeledExtract/LabeledExpand calls.\nconst _SUITE_ID: Uint8Array<ArrayBuffer> = new Uint8Array([\n  0x48, 0x50, 0x4b, 0x45, 0x00, 0x20, 0x00, 0x01, 0x00, 0x02\n]);\n\n// kem_suite_id = \"KEM\" || I2OSP(KEM_ID=0x0020, 2)\n// Used in DHKEM-internal LabeledExtract/LabeledExpand calls.\nconst _KEM_SUITE_ID: Uint8Array<ArrayBuffer> = new Uint8Array([0x4b, 0x45, 0x4d, 0x00, 0x20]);\n\nconst _N_SECRET: number = 32; // Nsecret: KEM shared-secret output length\nconst _N_PK: number = 32; // Npk: X25519 public key (raw) length — also the enc length\nconst _N_K: number = 32; // Nk: AES-256-GCM key length\nconst _N_N: number = 12; // Nn: AES-256-GCM nonce length\nconst _N_T: number = 16; // Nt: AES-256-GCM authentication tag length\nconst _MODE_BASE: number = 0x00; // RFC 9180 mode_base\n\n// ---- Internal helpers ----\n// These are NOT exported. Per design D7, only the five public operations are public surface.\n\n// Copies any Uint8Array into a fresh Uint8Array<ArrayBuffer>.\n// Required to satisfy TypeScript's strict BufferSource typing for Web Crypto API calls —\n// subtle.* rejects Uint8Array<ArrayBufferLike> but accepts Uint8Array<ArrayBuffer>.\n// Pattern follows browserCryptoProvider.ts toBufferView.\nfunction _toBufferView(arr: Uint8Array): Uint8Array<ArrayBuffer> {\n  const buffer = new ArrayBuffer(arr.byteLength);\n  const view = new Uint8Array(buffer);\n  view.set(arr);\n  return view;\n}\n\nfunction _concat(...arrays: Uint8Array[]): Uint8Array<ArrayBuffer> {\n  const total = arrays.reduce((n, a) => n + a.length, 0);\n  const buffer = new ArrayBuffer(total);\n  const out = new Uint8Array(buffer);\n  let offset = 0;\n  for (const a of arrays) {\n    out.set(a, offset);\n    offset += a.length;\n  }\n  return out;\n}\n\nfunction _i2osp(value: number, length: number): Uint8Array<ArrayBuffer> {\n  const buffer = new ArrayBuffer(length);\n  const out = new Uint8Array(buffer);\n  for (let i = length - 1; i >= 0; i--) {\n    out[i] = value % 256;\n    value = Math.floor(value / 256);\n  }\n  return out;\n}\n\n// Decodes a base64url-encoded string to Uint8Array<ArrayBuffer>.\n// Uses `atob` (global in Node 18+ and all modern browsers; no import needed).\nfunction _base64UrlDecode(s: string): Uint8Array<ArrayBuffer> {\n  const base64 = s.replace(/-/g, '+').replace(/_/g, '/');\n  const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);\n  const binary = atob(padded);\n  const buffer = new ArrayBuffer(binary.length);\n  const out = new Uint8Array(buffer);\n  for (let i = 0; i < binary.length; i++) {\n    out[i] = binary.charCodeAt(i);\n  }\n  return out;\n}\n\n// HMAC-SHA256(key, data) — the underlying primitive for HKDF.\nasync function _hmacSha256(\n  subtle: SubtleCrypto,\n  key: Uint8Array,\n  data: Uint8Array\n): Promise<Uint8Array<ArrayBuffer>> {\n  const hmacKey = await subtle.importKey(\n    'raw',\n    _toBufferView(key),\n    { name: 'HMAC', hash: 'SHA-256' },\n    false,\n    ['sign']\n  );\n  return new Uint8Array(await subtle.sign('HMAC', hmacKey, _toBufferView(data)));\n}\n\n// RFC 5869 HKDF-Extract(salt, IKM) = HMAC-SHA256(key=salt, msg=IKM).\n// If salt is empty (length 0), uses 32 zero bytes per RFC 5869 §2.2.\nasync function _hkdfExtract(\n  subtle: SubtleCrypto,\n  salt: Uint8Array,\n  ikm: Uint8Array\n): Promise<Uint8Array<ArrayBuffer>> {\n  const effectiveSalt = salt.length === 0 ? new Uint8Array(32) : salt;\n  return _hmacSha256(subtle, effectiveSalt, ikm);\n}\n\n// RFC 5869 HKDF-Expand(PRK, info, L) — iterative HMAC expansion.\nasync function _hkdfExpand(\n  subtle: SubtleCrypto,\n  prk: Uint8Array,\n  info: Uint8Array,\n  length: number\n): Promise<Uint8Array<ArrayBuffer>> {\n  if (length > 255 * 32) {\n    throw new Error(`HKDF-Expand: requested length ${length} exceeds maximum 8160 bytes (255 * HashLen)`);\n  }\n  const n = Math.ceil(length / 32);\n  const buffer = new ArrayBuffer(length);\n  const okm = new Uint8Array(buffer);\n  let prev: Uint8Array<ArrayBuffer> = new Uint8Array(new ArrayBuffer(0));\n  let offset = 0;\n  for (let i = 1; i <= n; i++) {\n    prev = await _hmacSha256(subtle, prk, _concat(prev, info, new Uint8Array([i])));\n    const toCopy = Math.min(32, length - offset);\n    okm.set(prev.subarray(0, toCopy), offset);\n    offset += toCopy;\n  }\n  return okm;\n}\n\n// RFC 9180 §4 LabeledExtract — HKDF-Extract with HPKE-v1 domain label.\n// labeled_ikm = \"HPKE-v1\" || suite_id || label || ikm\n// Extract(salt, labeled_ikm)\nasync function _labeledExtract(\n  subtle: SubtleCrypto,\n  suiteId: Uint8Array,\n  salt: Uint8Array,\n  label: string,\n  ikm: Uint8Array\n): Promise<Uint8Array<ArrayBuffer>> {\n  const labeledIkm = _concat(_HPKE_VERSION, suiteId, new TextEncoder().encode(label), ikm);\n  return _hkdfExtract(subtle, salt, labeledIkm);\n}\n\n// RFC 9180 §4 LabeledExpand — HKDF-Expand with HPKE-v1 domain label.\n// labeled_info = I2OSP(L, 2) || \"HPKE-v1\" || suite_id || label || info\n// Expand(prk, labeled_info, L)\nasync function _labeledExpand(\n  subtle: SubtleCrypto,\n  suiteId: Uint8Array,\n  prk: Uint8Array,\n  label: string,\n  info: Uint8Array,\n  length: number\n): Promise<Uint8Array<ArrayBuffer>> {\n  const labeledInfo = _concat(\n    _i2osp(length, 2),\n    _HPKE_VERSION,\n    suiteId,\n    new TextEncoder().encode(label),\n    info\n  );\n  return _hkdfExpand(subtle, prk, labeledInfo, length);\n}\n\n// RFC 9180 §4.1 DHKEM Encap — generates ephemeral keypair, DH with recipient pubkey,\n// derives shared_secret via ExtractAndExpand.\n// NOTE: uses label \"eae_prk\" (not \"dh\") per RFC 9180 §4.1 ExtractAndExpand.\nasync function _kemEncap(\n  subtle: SubtleCrypto,\n  recipientPublicKey: CryptoKey\n): Promise<{ sharedSecret: Uint8Array<ArrayBuffer>; enc: Uint8Array<ArrayBuffer> }> {\n  const ephemeral = (await subtle.generateKey({ name: 'X25519' }, true, ['deriveBits'])) as CryptoKeyPair;\n  const enc = new Uint8Array(await subtle.exportKey('raw', ephemeral.publicKey));\n  const dh = new Uint8Array(\n    await subtle.deriveBits({ name: 'X25519', public: recipientPublicKey }, ephemeral.privateKey, 256)\n  );\n  const pkRm = new Uint8Array(await subtle.exportKey('raw', recipientPublicKey));\n  const kemContext = _concat(enc, pkRm);\n  const eaePrk = await _labeledExtract(subtle, _KEM_SUITE_ID, new Uint8Array(0), 'eae_prk', dh);\n  const sharedSecret = await _labeledExpand(\n    subtle,\n    _KEM_SUITE_ID,\n    eaePrk,\n    'shared_secret',\n    kemContext,\n    _N_SECRET\n  );\n  return { sharedSecret, enc };\n}\n\n// RFC 9180 §4.1 DHKEM Decap — deserializes enc, DH with recipient privkey,\n// derives same shared_secret via ExtractAndExpand.\n// Requires recipientPrivateKey to be extractable (JWK export needed for pkRm).\nasync function _kemDecap(\n  subtle: SubtleCrypto,\n  enc: Uint8Array,\n  recipientPrivateKey: CryptoKey\n): Promise<Uint8Array<ArrayBuffer>> {\n  const pkE = await subtle.importKey('raw', _toBufferView(enc), { name: 'X25519' }, true, []);\n  const dh = new Uint8Array(\n    await subtle.deriveBits({ name: 'X25519', public: pkE }, recipientPrivateKey, 256)\n  );\n  // Recover recipient's own public key from JWK x field (base64url-encoded raw X25519 public key).\n  const jwk = (await subtle.exportKey('jwk', recipientPrivateKey)) as JsonWebKey;\n  /* c8 ignore next 3 - defensive: X25519 JWK always has an x field; unreachable via public API */\n  if (!jwk.x) {\n    throw new Error('HPKE Decap: failed to extract public key bytes from recipient private key JWK');\n  }\n  const pkRm = _base64UrlDecode(jwk.x);\n  const kemContext = _concat(enc, pkRm);\n  const eaePrk = await _labeledExtract(subtle, _KEM_SUITE_ID, new Uint8Array(0), 'eae_prk', dh);\n  return _labeledExpand(subtle, _KEM_SUITE_ID, eaePrk, 'shared_secret', kemContext, _N_SECRET);\n}\n\n// RFC 9180 §5 KeySchedule (base mode, psk = b\"\", psk_id = b\"\").\nasync function _keyScheduleBase(\n  subtle: SubtleCrypto,\n  sharedSecret: Uint8Array,\n  info: Uint8Array\n): Promise<{ key: Uint8Array<ArrayBuffer>; baseNonce: Uint8Array<ArrayBuffer> }> {\n  const empty = new Uint8Array(0);\n  const pskIdHash = await _labeledExtract(subtle, _SUITE_ID, empty, 'psk_id_hash', empty);\n  const infoHash = await _labeledExtract(subtle, _SUITE_ID, empty, 'info_hash', info);\n  const ksContext = _concat(new Uint8Array([_MODE_BASE]), pskIdHash, infoHash);\n  const prk = await _labeledExtract(subtle, _SUITE_ID, sharedSecret, 'secret', empty);\n  const key = await _labeledExpand(subtle, _SUITE_ID, prk, 'key', ksContext, _N_K);\n  const baseNonce = await _labeledExpand(subtle, _SUITE_ID, prk, 'base_nonce', ksContext, _N_N);\n  return { key, baseNonce };\n}\n\n// ---- Public types ----\n\n/**\n * Output of {@link HpkeProvider.sealBase}.\n *\n * The `ciphertext` field includes the 16-byte AES-256-GCM authentication tag\n * appended by Web Crypto's `encrypt()` operation: `length = plaintext.length + 16`.\n * @public\n */\nexport interface IHpkeSealResult {\n  /**\n   * Encapsulated key — 32-byte raw X25519 ephemeral public key (`enc` in RFC 9180).\n   * Must be transmitted to the recipient alongside `ciphertext`.\n   */\n  readonly enc: Uint8Array;\n\n  /**\n   * AES-256-GCM ciphertext with the 16-byte authentication tag appended.\n   * Length = `plaintext.length + 16`.\n   */\n  readonly ciphertext: Uint8Array;\n}\n\n// ---- Public class ----\n\n/**\n * HPKE base mode (RFC 9180) — `DHKEM(X25519, HKDF-SHA256) + HKDF-SHA256 + AES-256-GCM`.\n *\n * Class-based provider that captures a `SubtleCrypto` instance at construction,\n * matching the existing `NodeCryptoProvider` / `BrowserCryptoProvider` / `KeyStore`\n * factory pattern used throughout `@fgv/ts-extras/crypto-utils`.\n *\n * **Node.js usage:**\n * ```typescript\n * import * as crypto from 'crypto';\n * const hpke = HpkeProvider.create(crypto.webcrypto.subtle).orThrow();\n * ```\n *\n * **Browser usage:**\n * ```typescript\n * const hpke = HpkeProvider.create(globalThis.crypto.subtle).orThrow();\n * ```\n *\n * **Runtime requirements:** Node.js 20+ (X25519 in `crypto.webcrypto`);\n * Chrome 113+, Safari 16.4+, Firefox 118+ (X25519 added to Web Crypto in 2023).\n * @public\n */\nexport class HpkeProvider {\n  private readonly _subtle: SubtleCrypto;\n\n  private constructor(subtle: SubtleCrypto) {\n    this._subtle = subtle;\n  }\n\n  /**\n   * Creates an `HpkeProvider` bound to the given `SubtleCrypto` instance.\n   *\n   * @param subtle - Web Crypto SubtleCrypto instance.\n   *   Node.js: `(await import('crypto')).webcrypto.subtle`.\n   *   Browser: `globalThis.crypto.subtle`.\n   * @returns `Success` with the provider, or `Failure` if construction fails.\n   */\n  public static create(subtle: SubtleCrypto): Result<HpkeProvider> {\n    return captureResult(() => new HpkeProvider(subtle));\n  }\n\n  /**\n   * HPKE base-mode seal (sender side). RFC 9180 §6.1.\n   *\n   * Generates a fresh ephemeral X25519 keypair, runs DHKEM Encap to produce a\n   * shared secret and `enc` (32-byte raw ephemeral public key), derives the AEAD\n   * key and nonce deterministically via the RFC 9180 key schedule, then encrypts\n   * `plaintext` with AES-256-GCM.\n   *\n   * @param recipientPublicKey - Recipient's X25519 public `CryptoKey`\n   *   (`algorithm.name === 'X25519'`, `type === 'public'`, **`extractable: true`**).\n   *   Must be extractable — DHKEM Encap calls `exportKey('raw', ...)` on this key to\n   *   build the KEM shared-secret context. Keys imported with `extractable: false` will\n   *   cause this method to return a `Failure`.\n   * @param info - Context-binding bytes. **Load-bearing — no default.**\n   *   Binds this ciphertext to a specific application context, preventing replay\n   *   across different contexts sharing the same recipient keypair.\n   *   Use `new TextEncoder().encode('myapp/v1/use-case\\x00' + contextId)` pattern.\n   *   Never pass an empty array in production: empty `info` provides no context binding.\n   * @param aad - Additional authenticated data. Integrity-protected but not encrypted.\n   *   `new Uint8Array(0)` is valid when no AAD is needed.\n   * @param plaintext - Bytes to encrypt. `new Uint8Array(0)` is valid.\n   * @returns `Success` with `{ enc, ciphertext }`, or `Failure` with error context.\n   */\n  public async sealBase(\n    recipientPublicKey: CryptoKey,\n    info: Uint8Array,\n    aad: Uint8Array,\n    plaintext: Uint8Array\n  ): Promise<Result<IHpkeSealResult>> {\n    const result = await captureAsyncResult(async () => {\n      const { sharedSecret, enc } = await _kemEncap(this._subtle, recipientPublicKey);\n      const { key, baseNonce } = await _keyScheduleBase(this._subtle, sharedSecret, info);\n      const aesKey = await this._subtle.importKey('raw', key, { name: 'AES-GCM' }, false, ['encrypt']);\n      const ct = await this._subtle.encrypt(\n        { name: 'AES-GCM', iv: baseNonce, additionalData: _toBufferView(aad) },\n        aesKey,\n        _toBufferView(plaintext)\n      );\n      return { enc, ciphertext: new Uint8Array(ct) };\n    });\n    return result.withErrorFormat((e: string) => `HPKE sealBase failed: ${e}`);\n  }\n\n  /**\n   * HPKE base-mode open (recipient side). RFC 9180 §6.1.\n   *\n   * Decapsulates `enc` using the recipient's X25519 private key, derives the same\n   * AEAD key and nonce from the shared secret and `info`, then authenticates and\n   * decrypts `ciphertext` with AES-256-GCM.\n   *\n   * Returns `Failure` on any of:\n   * - Wrong private key (different DH output → different key derivation)\n   * - Wrong `info` (different key schedule context → different AEAD key)\n   * - Wrong `aad` (AES-GCM authentication fails)\n   * - Tampered `ciphertext` or `enc` (authentication fails or DH fails)\n   * - `enc` not exactly 32 bytes\n   * - `ciphertext` shorter than 16 bytes (no room for authentication tag)\n   *\n   * @param recipientPrivateKey - Recipient's X25519 private `CryptoKey`\n   *   (`algorithm.name === 'X25519'`, `type === 'private'`, `usages` includes `'deriveBits'`).\n   *   **Must be extractable** (`extractable: true`) — the recipient's public key bytes\n   *   are recovered from the JWK `x` field during Decap.\n   * @param info - Context-binding bytes. Must exactly match `info` from `sealBase`.\n   * @param aad - Must exactly match `aad` from `sealBase`.\n   * @param enc - The encapsulated key from `sealBase` — exactly 32 bytes.\n   * @param ciphertext - The ciphertext from `sealBase` — `plaintext.length + 16` bytes.\n   * @returns `Success` with decrypted plaintext bytes, or `Failure` with error context.\n   */\n  public async openBase(\n    recipientPrivateKey: CryptoKey,\n    info: Uint8Array,\n    aad: Uint8Array,\n    enc: Uint8Array,\n    ciphertext: Uint8Array\n  ): Promise<Result<Uint8Array>> {\n    if (enc.length !== _N_PK) {\n      return fail(`HPKE openBase: enc must be ${_N_PK} bytes, got ${enc.length}`);\n    }\n    if (ciphertext.length < _N_T) {\n      return fail(\n        `HPKE openBase: ciphertext too short (minimum ${_N_T} bytes for auth tag, got ${ciphertext.length})`\n      );\n    }\n    const result = await captureAsyncResult(async () => {\n      const sharedSecret = await _kemDecap(this._subtle, enc, recipientPrivateKey);\n      const { key, baseNonce } = await _keyScheduleBase(this._subtle, sharedSecret, info);\n      const aesKey = await this._subtle.importKey('raw', key, { name: 'AES-GCM' }, false, ['decrypt']);\n      const pt = await this._subtle.decrypt(\n        { name: 'AES-GCM', iv: baseNonce, additionalData: _toBufferView(aad) },\n        aesKey,\n        _toBufferView(ciphertext)\n      );\n      return new Uint8Array(pt);\n    });\n    return result.withErrorFormat((e: string) => `HPKE openBase failed: ${e}`);\n  }\n\n  /**\n   * HKDF-SHA256 key derivation (RFC 5869). Extract-then-Expand using SHA-256.\n   *\n   * This is raw RFC 5869 HKDF — it does **not** use RFC 9180's labeled variants.\n   * The HPKE key schedule internally uses labeled HKDF; this method is the unlabeled\n   * version for callers that need standalone key derivation.\n   *\n   * @param secret - Input keying material (IKM). Any length.\n   * @param salt - Optional salt. Use `new Uint8Array(0)` if no salt is available\n   *   (RFC 5869: 32 zero bytes are used internally when salt is empty).\n   * @param info - Context / application-binding bytes. Any length.\n   * @param length - Number of output bytes to derive. Maximum 8160 bytes (255 × 32).\n   * @returns `Success` with derived bytes, or `Failure` with error context.\n   */\n  public async hkdf(\n    secret: Uint8Array,\n    salt: Uint8Array,\n    info: Uint8Array,\n    length: number\n  ): Promise<Result<Uint8Array>> {\n    const result = await captureAsyncResult(async () => {\n      const prk = await _hkdfExtract(this._subtle, salt, secret);\n      return _hkdfExpand(this._subtle, prk, info, length);\n    });\n    return result.withErrorFormat((e: string) => `HKDF failed: ${e}`);\n  }\n\n  /**\n   * Encodes an {@link IHpkeSealResult} as a single contiguous byte array for wire transport.\n   *\n   * Format: `enc` (32 bytes, fixed) || `ciphertext` (variable length).\n   * The 32-byte `enc` length is fixed for X25519; the split point is unambiguous.\n   *\n   * @param result - The output of {@link HpkeProvider.sealBase}.\n   * @returns Concatenated bytes: `enc || ciphertext`.\n   */\n  public static encodeEnvelope(result: IHpkeSealResult): Uint8Array {\n    return _concat(result.enc, result.ciphertext);\n  }\n\n  /**\n   * Decodes an envelope produced by {@link HpkeProvider.encodeEnvelope}.\n   *\n   * Validates that the buffer is at least 48 bytes (32-byte enc + 16-byte minimum\n   * ciphertext containing the AES-GCM auth tag; zero-length plaintext is the minimum\n   * meaningful case).\n   *\n   * @param envelope - Envelope bytes from `encodeEnvelope`.\n   * @returns `Success` with `{ enc, ciphertext }`, or `Failure` if malformed.\n   */\n  public static decodeEnvelope(envelope: Uint8Array): Result<IHpkeSealResult> {\n    const minLen = _N_PK + _N_T;\n    if (envelope.length < minLen) {\n      return fail(\n        `HPKE decodeEnvelope: envelope too short (minimum ${minLen} bytes, got ${envelope.length})`\n      );\n    }\n    return succeed({\n      enc: envelope.slice(0, _N_PK),\n      ciphertext: envelope.slice(_N_PK)\n    });\n  }\n}\n"]}

package/dist/packlets/crypto-utils/index.browser.js

@@ -34,8 +34,15 @@ import * as Converters from './converters';
 export { Converters };
 // Direct encryption provider
 export { DirectEncryptionProvider } from './directEncryptionProvider';
+// WebCrypto parameter table for asymmetric keypair algorithms
+export { keyPairAlgorithmParams } from './keyPairAlgorithmParams';
 // Note: NodeCryptoProvider is NOT exported in browser version
 // Use BrowserCryptoProvider from @fgv/ts-web-extras instead
 // Encrypted file helpers
 export { createEncryptedFile, decryptFile, fromBase64, toBase64, tryDecryptFile } from './encryptedFile';
+// Multibase/SPKI helpers
+export { exportPublicKeyAsMultibaseSpki, importPublicKeyFromMultibaseSpki, multibaseBase64UrlDecode, multibaseBase64UrlEncode } from './spkiHelpers';
+// HPKE base mode (RFC 9180) — DHKEM(X25519, HKDF-SHA256) + HKDF-SHA256 + AES-256-GCM
+// hpkeProvider.ts has no Node-specific imports and is safe in the browser entry point.
+export { HpkeProvider } from './hpkeProvider';
 //# sourceMappingURL=index.browser.js.map

package/dist/packlets/crypto-utils/index.browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.browser.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/index.browser.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY;AAEZ;;;;GAIG;AAEH,iCAAiC;AACjC,cAAc,SAAS,CAAC;AAExB,YAAY;AACZ,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,WAAW,EACZ,MAAM,aAAa,CAAC;AAErB,qBAAqB;AACrB,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,CAAC;AAEpB,uBAAuB;AACvB,OAAO,KAAK,UAAU,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,6BAA6B;AAC7B,OAAO,EAAE,wBAAwB,EAAmC,MAAM,4BAA4B,CAAC;AAEvG,8DAA8D;AAC9D,OAAO,EAA2B,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAE3F,8DAA8D;AAC9D,4DAA4D;AAE5D,yBAAyB;AACzB,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,UAAU,EAEV,QAAQ,EACR,cAAc,EACf,MAAM,iBAAiB,CAAC;AAEzB,yBAAyB;AACzB,OAAO,EACL,8BAA8B,EAC9B,gCAAgC,EAChC,wBAAwB,EACxB,wBAAwB,EACzB,MAAM,eAAe,CAAC;AAEvB,qFAAqF;AACrF,uFAAuF;AACvF,OAAO,EAAE,YAAY,EAAmB,MAAM,gBAAgB,CAAC","sourcesContent":["// Copyright (c) 2024 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\n/**\n * Crypto utilities for encrypted file handling and key management (browser version).\n * Note: For browser crypto provider, use \\@fgv/ts-web-extras.\n * @packageDocumentation\n */\n\n// Re-export all types from model\nexport * from './model';\n\n// Constants\nexport {\n  AES_256_KEY_SIZE,\n  DEFAULT_ALGORITHM,\n  ENCRYPTED_FILE_FORMAT,\n  GCM_AUTH_TAG_SIZE,\n  GCM_IV_SIZE\n} from './constants';\n\n// KeyStore namespace\nimport * as KeyStore from './keystore';\nexport { KeyStore };\n\n// Converters namespace\nimport * as Converters from './converters';\nexport { Converters };\n\n// Direct encryption provider\nexport { DirectEncryptionProvider, IDirectEncryptionProviderParams } from './directEncryptionProvider';\n\n// WebCrypto parameter table for asymmetric keypair algorithms\nexport { IKeyPairAlgorithmParams, keyPairAlgorithmParams } from './keyPairAlgorithmParams';\n\n// Note: NodeCryptoProvider is NOT exported in browser version\n// Use BrowserCryptoProvider from @fgv/ts-web-extras instead\n\n// Encrypted file helpers\nexport {\n  createEncryptedFile,\n  decryptFile,\n  fromBase64,\n  ICreateEncryptedFileParams,\n  toBase64,\n  tryDecryptFile\n} from './encryptedFile';\n\n// Multibase/SPKI helpers\nexport {\n  exportPublicKeyAsMultibaseSpki,\n  importPublicKeyFromMultibaseSpki,\n  multibaseBase64UrlDecode,\n  multibaseBase64UrlEncode\n} from './spkiHelpers';\n\n// HPKE base mode (RFC 9180) — DHKEM(X25519, HKDF-SHA256) + HKDF-SHA256 + AES-256-GCM\n// hpkeProvider.ts has no Node-specific imports and is safe in the browser entry point.\nexport { HpkeProvider, IHpkeSealResult } from './hpkeProvider';\n"]}

package/dist/packlets/crypto-utils/index.js

@@ -34,8 +34,14 @@ import * as Converters from './converters';
 export { Converters };
 // Direct encryption provider
 export { DirectEncryptionProvider } from './directEncryptionProvider';
+// WebCrypto parameter table for asymmetric keypair algorithms
+export { keyPairAlgorithmParams } from './keyPairAlgorithmParams';
 // Node.js crypto provider (Node.js environment only)
 export { NodeCryptoProvider, nodeCryptoProvider } from './nodeCryptoProvider';
 // Encrypted file helpers
 export { createEncryptedFile, decryptFile, fromBase64, toBase64, tryDecryptFile } from './encryptedFile';
+// Multibase/SPKI helpers
+export { exportPublicKeyAsMultibaseSpki, importPublicKeyFromMultibaseSpki, multibaseBase64UrlDecode, multibaseBase64UrlEncode } from './spkiHelpers';
+// HPKE base mode (RFC 9180) — DHKEM(X25519, HKDF-SHA256) + HKDF-SHA256 + AES-256-GCM
+export { HpkeProvider } from './hpkeProvider';
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/index.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY;AAEZ;;;GAGG;AAEH,iCAAiC;AACjC,cAAc,SAAS,CAAC;AAExB,YAAY;AACZ,OAAO,KAAK,SAAS,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,qBAAqB;AACrB,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,CAAC;AAEpB,uBAAuB;AACvB,OAAO,KAAK,UAAU,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,6BAA6B;AAC7B,OAAO,EAAE,wBAAwB,EAAmC,MAAM,4BAA4B,CAAC;AAEvG,8DAA8D;AAC9D,OAAO,EAA2B,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAE3F,qDAAqD;AACrD,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE9E,yBAAyB;AACzB,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,UAAU,EAEV,QAAQ,EACR,cAAc,EACf,MAAM,iBAAiB,CAAC;AAEzB,yBAAyB;AACzB,OAAO,EACL,8BAA8B,EAC9B,gCAAgC,EAChC,wBAAwB,EACxB,wBAAwB,EACzB,MAAM,eAAe,CAAC;AAEvB,qFAAqF;AACrF,OAAO,EAAE,YAAY,EAAmB,MAAM,gBAAgB,CAAC","sourcesContent":["// Copyright (c) 2024 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\n/**\n * Crypto utilities for encrypted file handling and key management.\n * @packageDocumentation\n */\n\n// Re-export all types from model\nexport * from './model';\n\n// Constants\nimport * as Constants from './constants';\nexport { Constants };\n\n// KeyStore namespace\nimport * as KeyStore from './keystore';\nexport { KeyStore };\n\n// Converters namespace\nimport * as Converters from './converters';\nexport { Converters };\n\n// Direct encryption provider\nexport { DirectEncryptionProvider, IDirectEncryptionProviderParams } from './directEncryptionProvider';\n\n// WebCrypto parameter table for asymmetric keypair algorithms\nexport { IKeyPairAlgorithmParams, keyPairAlgorithmParams } from './keyPairAlgorithmParams';\n\n// Node.js crypto provider (Node.js environment only)\nexport { NodeCryptoProvider, nodeCryptoProvider } from './nodeCryptoProvider';\n\n// Encrypted file helpers\nexport {\n  createEncryptedFile,\n  decryptFile,\n  fromBase64,\n  ICreateEncryptedFileParams,\n  toBase64,\n  tryDecryptFile\n} from './encryptedFile';\n\n// Multibase/SPKI helpers\nexport {\n  exportPublicKeyAsMultibaseSpki,\n  importPublicKeyFromMultibaseSpki,\n  multibaseBase64UrlDecode,\n  multibaseBase64UrlEncode\n} from './spkiHelpers';\n\n// HPKE base mode (RFC 9180) — DHKEM(X25519, HKDF-SHA256) + HKDF-SHA256 + AES-256-GCM\nexport { HpkeProvider, IHpkeSealResult } from './hpkeProvider';\n"]}

package/dist/packlets/crypto-utils/keyPairAlgorithmParams.js

@@ -0,0 +1,71 @@
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+/**
+ * Lookup table from {@link CryptoUtils.KeyPairAlgorithm} to the WebCrypto
+ * parameters needed to drive `crypto.subtle`. Shared between every
+ * {@link CryptoUtils.ICryptoProvider} implementation since both Node and
+ * browser providers speak the same WebCrypto API. Exposed for downstream
+ * provider implementations (e.g. browser-side providers in `@fgv/ts-web-extras`).
+ * @public
+ */
+export const keyPairAlgorithmParams = {
+    'ecdsa-p256': {
+        generateKey: { name: 'ECDSA', namedCurve: 'P-256' },
+        importPublicKey: { name: 'ECDSA', namedCurve: 'P-256' },
+        keyPairUsages: ['sign', 'verify'],
+        publicKeyUsages: ['verify']
+    },
+    'rsa-oaep-2048': {
+        generateKey: {
+            name: 'RSA-OAEP',
+            modulusLength: 2048,
+            publicExponent: new Uint8Array([0x01, 0x00, 0x01]),
+            hash: 'SHA-256'
+        },
+        importPublicKey: { name: 'RSA-OAEP', hash: 'SHA-256' },
+        keyPairUsages: ['encrypt', 'decrypt'],
+        publicKeyUsages: ['encrypt']
+    },
+    'ecdh-p256': {
+        generateKey: { name: 'ECDH', namedCurve: 'P-256' },
+        importPublicKey: { name: 'ECDH', namedCurve: 'P-256' },
+        // WebCrypto filters per-role: the private key takes both derive usages,
+        // and the public key gets [] since an ECDH public key alone cannot derive.
+        keyPairUsages: ['deriveKey', 'deriveBits'],
+        // Importing only the recipient's public key — empty usages because a
+        // standalone ECDH public key has no derivation capability.
+        publicKeyUsages: []
+    },
+    ed25519: {
+        generateKey: { name: 'Ed25519' },
+        importPublicKey: { name: 'Ed25519' },
+        keyPairUsages: ['sign', 'verify'],
+        publicKeyUsages: ['verify']
+    },
+    x25519: {
+        generateKey: { name: 'X25519' },
+        importPublicKey: { name: 'X25519' },
+        // WebCrypto filters per-role: the private key takes both derive usages,
+        // the public key gets [] since a standalone X25519 public key cannot derive.
+        keyPairUsages: ['deriveKey', 'deriveBits'],
+        publicKeyUsages: []
+    }
+};
+//# sourceMappingURL=keyPairAlgorithmParams.js.map