@fgv/ts-extras 5.1.0-24 → 5.1.0-26

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

@@ -40,4 +40,6 @@ export { keyPairAlgorithmParams } from './keyPairAlgorithmParams';
 // 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';
 //# sourceMappingURL=index.browser.js.map

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

@@ -1 +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","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"]}
+{"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","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"]}

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

@@ -40,4 +40,6 @@ export { keyPairAlgorithmParams } from './keyPairAlgorithmParams';
 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';
 //# sourceMappingURL=index.js.map

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

@@ -1 +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","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"]}
+{"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","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"]}

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

@@ -58,6 +58,14 @@ export const keyPairAlgorithmParams = {
         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

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

@@ -1 +1 @@
-{"version":3,"file":"keyPairAlgorithmParams.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/keyPairAlgorithmParams.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;AA2CZ;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAgE;IACjG,YAAY,EAAE;QACZ,WAAW,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE;QACnD,eAAe,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE;QACvD,aAAa,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC;QACjC,eAAe,EAAE,CAAC,QAAQ,CAAC;KAC5B;IACD,eAAe,EAAE;QACf,WAAW,EAAE;YACX,IAAI,EAAE,UAAU;YAChB,aAAa,EAAE,IAAI;YACnB,cAAc,EAAE,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YAClD,IAAI,EAAE,SAAS;SAChB;QACD,eAAe,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;QACtD,aAAa,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC;QACrC,eAAe,EAAE,CAAC,SAAS,CAAC;KAC7B;IACD,WAAW,EAAE;QACX,WAAW,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE;QAClD,eAAe,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE;QACtD,wEAAwE;QACxE,2EAA2E;QAC3E,aAAa,EAAE,CAAC,WAAW,EAAE,YAAY,CAAC;QAC1C,qEAAqE;QACrE,2DAA2D;QAC3D,eAAe,EAAE,EAAE;KACpB;IACD,OAAO,EAAE;QACP,WAAW,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;QAChC,eAAe,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;QACpC,aAAa,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC;QACjC,eAAe,EAAE,CAAC,QAAQ,CAAC;KAC5B;CACF,CAAC","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 { KeyPairAlgorithm } from './model';\n\n/**\n * WebCrypto parameters for a single {@link CryptoUtils.KeyPairAlgorithm}.\n * Implementations of {@link CryptoUtils.ICryptoProvider} use this table to\n * translate the small public algorithm enum into the WebCrypto algorithm\n * objects and key-usage arrays expected by `crypto.subtle`.\n * @public\n */\nexport interface IKeyPairAlgorithmParams {\n  /**\n   * Algorithm parameters for `crypto.subtle.generateKey`. Always an asymmetric\n   * variant — these algorithms produce a `CryptoKeyPair`, not a single key.\n   * The literal `{ name: 'Ed25519' }` member covers WebCrypto's Secure-Curves\n   * Ed25519 algorithm, which takes only a `name`; using a literal rather than\n   * the base `Algorithm` keeps the union closed to the algorithms this table\n   * supports.\n   */\n  readonly generateKey: RsaHashedKeyGenParams | EcKeyGenParams | { readonly name: 'Ed25519' };\n\n  /**\n   * Algorithm parameters for `crypto.subtle.importKey('jwk', ...)` when\n   * importing the public half of a keypair. The literal `{ name: 'Ed25519' }`\n   * member covers Ed25519 imports, which take only a `name`; using a literal\n   * rather than the base `Algorithm` keeps the union closed to the algorithms\n   * this table supports.\n   */\n  readonly importPublicKey: RsaHashedImportParams | EcKeyImportParams | { readonly name: 'Ed25519' };\n\n  /**\n   * Default key usages for the generated `CryptoKeyPair`. Both halves receive\n   * the usages WebCrypto considers valid for their role; the platform filters.\n   */\n  readonly keyPairUsages: ReadonlyArray<KeyUsage>;\n\n  /**\n   * Key usages applied when re-importing only the public key.\n   */\n  readonly publicKeyUsages: ReadonlyArray<KeyUsage>;\n}\n\n/**\n * Lookup table from {@link CryptoUtils.KeyPairAlgorithm} to the WebCrypto\n * parameters needed to drive `crypto.subtle`. Shared between every\n * {@link CryptoUtils.ICryptoProvider} implementation since both Node and\n * browser providers speak the same WebCrypto API. Exposed for downstream\n * provider implementations (e.g. browser-side providers in `@fgv/ts-web-extras`).\n * @public\n */\nexport const keyPairAlgorithmParams: Readonly<Record<KeyPairAlgorithm, IKeyPairAlgorithmParams>> = {\n  'ecdsa-p256': {\n    generateKey: { name: 'ECDSA', namedCurve: 'P-256' },\n    importPublicKey: { name: 'ECDSA', namedCurve: 'P-256' },\n    keyPairUsages: ['sign', 'verify'],\n    publicKeyUsages: ['verify']\n  },\n  'rsa-oaep-2048': {\n    generateKey: {\n      name: 'RSA-OAEP',\n      modulusLength: 2048,\n      publicExponent: new Uint8Array([0x01, 0x00, 0x01]),\n      hash: 'SHA-256'\n    },\n    importPublicKey: { name: 'RSA-OAEP', hash: 'SHA-256' },\n    keyPairUsages: ['encrypt', 'decrypt'],\n    publicKeyUsages: ['encrypt']\n  },\n  'ecdh-p256': {\n    generateKey: { name: 'ECDH', namedCurve: 'P-256' },\n    importPublicKey: { name: 'ECDH', namedCurve: 'P-256' },\n    // WebCrypto filters per-role: the private key takes both derive usages,\n    // and the public key gets [] since an ECDH public key alone cannot derive.\n    keyPairUsages: ['deriveKey', 'deriveBits'],\n    // Importing only the recipient's public key — empty usages because a\n    // standalone ECDH public key has no derivation capability.\n    publicKeyUsages: []\n  },\n  ed25519: {\n    generateKey: { name: 'Ed25519' },\n    importPublicKey: { name: 'Ed25519' },\n    keyPairUsages: ['sign', 'verify'],\n    publicKeyUsages: ['verify']\n  }\n};\n"]}
+{"version":3,"file":"keyPairAlgorithmParams.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/keyPairAlgorithmParams.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;AAmDZ;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAgE;IACjG,YAAY,EAAE;QACZ,WAAW,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE;QACnD,eAAe,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE;QACvD,aAAa,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC;QACjC,eAAe,EAAE,CAAC,QAAQ,CAAC;KAC5B;IACD,eAAe,EAAE;QACf,WAAW,EAAE;YACX,IAAI,EAAE,UAAU;YAChB,aAAa,EAAE,IAAI;YACnB,cAAc,EAAE,IAAI,UAAU,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YAClD,IAAI,EAAE,SAAS;SAChB;QACD,eAAe,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE;QACtD,aAAa,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC;QACrC,eAAe,EAAE,CAAC,SAAS,CAAC;KAC7B;IACD,WAAW,EAAE;QACX,WAAW,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE;QAClD,eAAe,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE;QACtD,wEAAwE;QACxE,2EAA2E;QAC3E,aAAa,EAAE,CAAC,WAAW,EAAE,YAAY,CAAC;QAC1C,qEAAqE;QACrE,2DAA2D;QAC3D,eAAe,EAAE,EAAE;KACpB;IACD,OAAO,EAAE;QACP,WAAW,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;QAChC,eAAe,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;QACpC,aAAa,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC;QACjC,eAAe,EAAE,CAAC,QAAQ,CAAC;KAC5B;IACD,MAAM,EAAE;QACN,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC/B,eAAe,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QACnC,wEAAwE;QACxE,6EAA6E;QAC7E,aAAa,EAAE,CAAC,WAAW,EAAE,YAAY,CAAC;QAC1C,eAAe,EAAE,EAAE;KACpB;CACF,CAAC","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 { KeyPairAlgorithm } from './model';\n\n/**\n * WebCrypto parameters for a single {@link CryptoUtils.KeyPairAlgorithm}.\n * Implementations of {@link CryptoUtils.ICryptoProvider} use this table to\n * translate the small public algorithm enum into the WebCrypto algorithm\n * objects and key-usage arrays expected by `crypto.subtle`.\n * @public\n */\nexport interface IKeyPairAlgorithmParams {\n  /**\n   * Algorithm parameters for `crypto.subtle.generateKey`. Always an asymmetric\n   * variant — these algorithms produce a `CryptoKeyPair`, not a single key.\n   * The literal `{ name: 'Ed25519' }` member covers WebCrypto's Secure-Curves\n   * Ed25519 algorithm; `{ name: 'X25519' }` covers the X25519 key-agreement\n   * algorithm. Both take only a `name`; using literals rather than the base\n   * `Algorithm` keeps the union closed to the algorithms this table supports.\n   */\n  readonly generateKey:\n    | RsaHashedKeyGenParams\n    | EcKeyGenParams\n    | { readonly name: 'Ed25519' }\n    | { readonly name: 'X25519' };\n\n  /**\n   * Algorithm parameters for `crypto.subtle.importKey('jwk', ...)` when\n   * importing the public half of a keypair. The literal `{ name: 'Ed25519' }`\n   * member covers Ed25519 imports; `{ name: 'X25519' }` covers X25519 imports.\n   * Both take only a `name`; using literals rather than the base `Algorithm`\n   * keeps the union closed to the algorithms this table supports.\n   */\n  readonly importPublicKey:\n    | RsaHashedImportParams\n    | EcKeyImportParams\n    | { readonly name: 'Ed25519' }\n    | { readonly name: 'X25519' };\n\n  /**\n   * Default key usages for the generated `CryptoKeyPair`. Both halves receive\n   * the usages WebCrypto considers valid for their role; the platform filters.\n   */\n  readonly keyPairUsages: ReadonlyArray<KeyUsage>;\n\n  /**\n   * Key usages applied when re-importing only the public key.\n   */\n  readonly publicKeyUsages: ReadonlyArray<KeyUsage>;\n}\n\n/**\n * Lookup table from {@link CryptoUtils.KeyPairAlgorithm} to the WebCrypto\n * parameters needed to drive `crypto.subtle`. Shared between every\n * {@link CryptoUtils.ICryptoProvider} implementation since both Node and\n * browser providers speak the same WebCrypto API. Exposed for downstream\n * provider implementations (e.g. browser-side providers in `@fgv/ts-web-extras`).\n * @public\n */\nexport const keyPairAlgorithmParams: Readonly<Record<KeyPairAlgorithm, IKeyPairAlgorithmParams>> = {\n  'ecdsa-p256': {\n    generateKey: { name: 'ECDSA', namedCurve: 'P-256' },\n    importPublicKey: { name: 'ECDSA', namedCurve: 'P-256' },\n    keyPairUsages: ['sign', 'verify'],\n    publicKeyUsages: ['verify']\n  },\n  'rsa-oaep-2048': {\n    generateKey: {\n      name: 'RSA-OAEP',\n      modulusLength: 2048,\n      publicExponent: new Uint8Array([0x01, 0x00, 0x01]),\n      hash: 'SHA-256'\n    },\n    importPublicKey: { name: 'RSA-OAEP', hash: 'SHA-256' },\n    keyPairUsages: ['encrypt', 'decrypt'],\n    publicKeyUsages: ['encrypt']\n  },\n  'ecdh-p256': {\n    generateKey: { name: 'ECDH', namedCurve: 'P-256' },\n    importPublicKey: { name: 'ECDH', namedCurve: 'P-256' },\n    // WebCrypto filters per-role: the private key takes both derive usages,\n    // and the public key gets [] since an ECDH public key alone cannot derive.\n    keyPairUsages: ['deriveKey', 'deriveBits'],\n    // Importing only the recipient's public key — empty usages because a\n    // standalone ECDH public key has no derivation capability.\n    publicKeyUsages: []\n  },\n  ed25519: {\n    generateKey: { name: 'Ed25519' },\n    importPublicKey: { name: 'Ed25519' },\n    keyPairUsages: ['sign', 'verify'],\n    publicKeyUsages: ['verify']\n  },\n  x25519: {\n    generateKey: { name: 'X25519' },\n    importPublicKey: { name: 'X25519' },\n    // WebCrypto filters per-role: the private key takes both derive usages,\n    // the public key gets [] since a standalone X25519 public key cannot derive.\n    keyPairUsages: ['deriveKey', 'deriveBits'],\n    publicKeyUsages: []\n  }\n};\n"]}

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

@@ -27,7 +27,8 @@ export const allKeyPairAlgorithms = [
     'ecdsa-p256',
     'rsa-oaep-2048',
     'ecdh-p256',
-    'ed25519'
+    'ed25519',
+    'x25519'
 ];
 // ============================================================================
 // Detection Helper

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

@@ -1 +1 @@
-{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/model.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;AAKZ,OAAO,KAAK,SAAS,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,CAAC;AAgIrB;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAoC;IACnE,YAAY;IACZ,eAAe;IACf,WAAW;IACX,SAAS;CACV,CAAC;AAmVF,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAa;IAC3C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,GAAG,GAAG,IAA+B,CAAC;IAC5C,OAAO,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,qBAAqB,CAAC;AACxD,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\nimport { JsonValue } from '@fgv/ts-json-base';\nimport { Result, Uuid } from '@fgv/ts-utils';\n\nimport * as Constants from './constants';\nexport { Constants };\n\n// ============================================================================\n// Encryption Types\n// ============================================================================\n\n/**\n * Supported encryption algorithms.\n * @public\n */\nexport type EncryptionAlgorithm = typeof Constants.DEFAULT_ALGORITHM;\n\n/**\n * Format version for encrypted files.\n * @public\n */\nexport type EncryptedFileFormat = typeof Constants.ENCRYPTED_FILE_FORMAT;\n\n/**\n * Named secret for encryption/decryption.\n * @public\n */\nexport interface INamedSecret {\n  /**\n   * Unique name for this secret (referenced in encrypted files).\n   */\n  readonly name: string;\n\n  /**\n   * The actual secret key (32 bytes for AES-256).\n   */\n  readonly key: Uint8Array;\n}\n\n/**\n * Result of an encryption operation.\n * @public\n */\nexport interface IEncryptionResult {\n  /**\n   * Initialization vector used for encryption (12 bytes for GCM).\n   */\n  readonly iv: Uint8Array;\n\n  /**\n   * Authentication tag from GCM mode (16 bytes).\n   */\n  readonly authTag: Uint8Array;\n\n  /**\n   * The encrypted data.\n   */\n  readonly encryptedData: Uint8Array;\n}\n\n/**\n * Asymmetric keypair algorithms supported by the crypto provider.\n * - `'ecdsa-p256'`: ECDSA over the P-256 curve, for signing.\n * - `'rsa-oaep-2048'`: RSA-OAEP, 2048-bit modulus with SHA-256, for encryption.\n * - `'ecdh-p256'`: ECDH over the P-256 curve, for key agreement\n *   (e.g. as the recipient keypair in\n *   {@link CryptoUtils.ICryptoProvider.wrapBytes | wrapBytes} /\n *   {@link CryptoUtils.ICryptoProvider.unwrapBytes | unwrapBytes}).\n * - `'ed25519'`: EdDSA over the Edwards25519 curve, for signing.\n *   Deterministic — the per-signature nonce is derived from the private key\n *   and message rather than sampled randomly, eliminating the random-nonce\n *   reuse risk that ECDSA carries. Distinct from X25519 (key agreement over\n *   the Montgomery form, Curve25519).\n * @public\n */\nexport type KeyPairAlgorithm = 'ecdsa-p256' | 'rsa-oaep-2048' | 'ecdh-p256' | 'ed25519';\n\n/**\n * Caller-supplied HKDF parameters that domain-separate one\n * {@link CryptoUtils.ICryptoProvider.wrapBytes | wrapBytes} call from another.\n * Two wraps that share recipient but differ on `salt` or `info` derive distinct\n * wrap keys, so callers should pick values that bind the wrap to its\n * application context (e.g. a content hash for `salt` and a secret name for\n * `info`).\n *\n * Both fields are required; pass an empty `Uint8Array` if the caller has no\n * value to bind on a given axis. Silent defaulting would hide protocol\n * mistakes, so the API does not pick defaults.\n * @public\n */\nexport interface IWrapBytesOptions {\n  /**\n   * HKDF salt. Domain-separates this wrap from others in different contexts.\n   * Caller picks; common choices include a content hash, document id, channel\n   * id, etc.\n   */\n  readonly salt: Uint8Array;\n\n  /**\n   * HKDF info. Further binds the derived key to a specific use within the\n   * calling application. Caller picks; common choices include a secret name,\n   * message type, or version tag.\n   */\n  readonly info: Uint8Array;\n}\n\n/**\n * Output of {@link CryptoUtils.ICryptoProvider.wrapBytes | wrapBytes}. The\n * shape is JSON-serializable so it can travel directly over the wire or be\n * persisted as-is.\n * @public\n */\nexport interface IWrappedBytes {\n  /**\n   * Sender's ephemeral ECDH P-256 public key as a JSON Web Key. The matching\n   * ephemeral private key is dropped after the shared-secret derive.\n   */\n  readonly ephemeralPublicKey: JsonWebKey;\n\n  /**\n   * AES-GCM nonce, base64-encoded. 12 bytes (96 bits) — the standard AES-GCM\n   * nonce length.\n   */\n  readonly nonce: string;\n\n  /**\n   * AES-GCM ciphertext concatenated with the 16-byte authentication tag,\n   * base64-encoded. Tampering with either the nonce or the ciphertext causes\n   * unwrap to fail GCM authentication.\n   */\n  readonly ciphertext: string;\n}\n\n/**\n * All valid key pair algorithms.\n * @public\n */\nexport const allKeyPairAlgorithms: ReadonlyArray<KeyPairAlgorithm> = [\n  'ecdsa-p256',\n  'rsa-oaep-2048',\n  'ecdh-p256',\n  'ed25519'\n];\n\n/**\n * Supported key derivation functions.\n * @public\n */\nexport type KeyDerivationFunction = 'pbkdf2';\n\n/**\n * Key derivation parameters stored in encrypted files.\n * Allows decryption with password without needing to know the original salt/iterations.\n * @public\n */\nexport interface IKeyDerivationParams {\n  /**\n   * Key derivation function used.\n   */\n  readonly kdf: KeyDerivationFunction;\n\n  /**\n   * Base64-encoded salt used for key derivation.\n   */\n  readonly salt: string;\n\n  /**\n   * Number of iterations used for key derivation.\n   */\n  readonly iterations: number;\n}\n\n/**\n * Generic encrypted file format.\n * This is the JSON structure stored in encrypted files.\n * @typeParam TMetadata - Type of optional unencrypted metadata\n * @public\n */\nexport interface IEncryptedFile<TMetadata = JsonValue> {\n  /**\n   * Format identifier for versioning.\n   */\n  readonly format: EncryptedFileFormat;\n\n  /**\n   * Name of the secret required to decrypt (references INamedSecret.name).\n   */\n  readonly secretName: string;\n\n  /**\n   * Algorithm used for encryption.\n   */\n  readonly algorithm: EncryptionAlgorithm;\n\n  /**\n   * Base64-encoded initialization vector.\n   */\n  readonly iv: string;\n\n  /**\n   * Base64-encoded authentication tag (for GCM mode).\n   */\n  readonly authTag: string;\n\n  /**\n   * Base64-encoded encrypted data (JSON string when decrypted).\n   */\n  readonly encryptedData: string;\n\n  /**\n   * Optional unencrypted metadata for display/filtering.\n   */\n  readonly metadata?: TMetadata;\n\n  /**\n   * Optional key derivation parameters.\n   * If present, allows decryption using a password with these parameters.\n   * If absent, a pre-derived key must be provided.\n   */\n  readonly keyDerivation?: IKeyDerivationParams;\n}\n\n// ============================================================================\n// Crypto Provider Interface\n// ============================================================================\n\n/**\n * Crypto provider interface for cross-platform encryption.\n * Implementations provided for Node.js (crypto module) and browser (Web Crypto API).\n * @public\n */\nexport interface ICryptoProvider {\n  /**\n   * Encrypts plaintext using AES-256-GCM.\n   * @param plaintext - UTF-8 string to encrypt\n   * @param key - 32-byte encryption key\n   * @returns Success with encryption result, or Failure with error\n   */\n  encrypt(plaintext: string, key: Uint8Array): Promise<Result<IEncryptionResult>>;\n\n  /**\n   * Decrypts ciphertext using AES-256-GCM.\n   * @param encryptedData - Encrypted bytes\n   * @param key - 32-byte decryption key\n   * @param iv - Initialization vector (12 bytes)\n   * @param authTag - GCM authentication tag (16 bytes)\n   * @returns Success with decrypted UTF-8 string, or Failure with error\n   */\n  decrypt(\n    encryptedData: Uint8Array,\n    key: Uint8Array,\n    iv: Uint8Array,\n    authTag: Uint8Array\n  ): Promise<Result<string>>;\n\n  /**\n   * Generates a random 32-byte key suitable for AES-256.\n   * @returns Success with generated key, or Failure with error\n   */\n  generateKey(): Promise<Result<Uint8Array>>;\n\n  /**\n   * Derives a key from a password using PBKDF2.\n   * @param password - Password string\n   * @param salt - Salt bytes (should be at least 16 bytes)\n   * @param iterations - Number of iterations (recommend 100000+)\n   * @returns Success with derived 32-byte key, or Failure with error\n   */\n  deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;\n\n  /**\n   * Computes a SHA-256 hash of the given data.\n   * @param data - UTF-8 string to hash\n   * @returns Success with hex-encoded hash string, or Failure with error\n   */\n  sha256(data: string): Promise<Result<string>>;\n\n  // ============================================================================\n  // Platform Utility Methods\n  // ============================================================================\n\n  /**\n   * Generates cryptographically secure random bytes.\n   * @param length - Number of bytes to generate\n   * @returns Success with random bytes, or Failure with error\n   */\n  generateRandomBytes(length: number): Result<Uint8Array>;\n\n  /**\n   * Generates a cryptographically random UUIDv4 using the provider's\n   * underlying source of randomness. The default Node and browser\n   * implementations delegate to `globalThis.crypto.randomUUID`;\n   * deterministic providers (e.g. test stubs) may override to produce\n   * reproducible values.\n   * @returns Success with a canonical UUID, or Failure with error.\n   */\n  generateUuid(): Result<Uuid>;\n\n  /**\n   * Encodes binary data to base64 string.\n   * @param data - Binary data to encode\n   * @returns Base64-encoded string\n   */\n  toBase64(data: Uint8Array): string;\n\n  /**\n   * Decodes base64 string to binary data.\n   * @param base64 - Base64-encoded string\n   * @returns Success with decoded bytes, or Failure if invalid base64\n   */\n  fromBase64(base64: string): Result<Uint8Array>;\n\n  // ============================================================================\n  // Asymmetric Key Operations\n  // ============================================================================\n\n  /**\n   * Generates a new asymmetric keypair for the requested algorithm.\n   * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm | algorithm} to use.\n   * @param extractable - Whether the resulting `CryptoKey` objects may be exported.\n   * Set `false` on backends that store `CryptoKey` references directly (e.g.\n   * IndexedDB). Set `true` when the private key must round-trip through JWK or\n   * PKCS#8 (e.g. encrypted-file backends).\n   * @returns Success with the generated `CryptoKeyPair`, or Failure with error context.\n   */\n  generateKeyPair(algorithm: KeyPairAlgorithm, extractable: boolean): Promise<Result<CryptoKeyPair>>;\n\n  /**\n   * Exports the public half of a keypair as a JSON Web Key.\n   * @param publicKey - The public `CryptoKey` to export. Must be an `extractable`\n   * key generated for an asymmetric algorithm.\n   * @returns Success with the JWK, or Failure with error context.\n   */\n  exportPublicKeyJwk(publicKey: CryptoKey): Promise<Result<JsonWebKey>>;\n\n  /**\n   * Re-imports a public-key JWK as a `CryptoKey` usable for verification or\n   * encryption (depending on algorithm).\n   * @param jwk - The JSON Web Key produced by {@link CryptoUtils.ICryptoProvider.exportPublicKeyJwk | exportPublicKeyJwk}.\n   * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm | algorithm} the\n   * key was generated for. Determines the import parameters and key usages.\n   * @returns Success with the imported public `CryptoKey`, or Failure with error context.\n   */\n  importPublicKeyJwk(jwk: JsonWebKey, algorithm: KeyPairAlgorithm): Promise<Result<CryptoKey>>;\n\n  /**\n   * Wraps `plaintext` for delivery to the holder of the private key paired\n   * with `recipientPublicKey`. Uses ECIES with ECDH P-256, HKDF-SHA256, and\n   * AES-GCM-256.\n   *\n   * Generates a fresh ephemeral keypair per call; the ephemeral private key\n   * is discarded after the shared-secret derive. Only the recipient (with the\n   * matching private key) and the same HKDF parameters can recover\n   * `plaintext`.\n   *\n   * Empty `plaintext` is permitted; the resulting wrap contains only the\n   * 16-byte GCM authentication tag and round-trips back to an empty\n   * `Uint8Array`.\n   * @param plaintext - The bytes to wrap. Any length supported by AES-GCM\n   * (in practice, well below 2^39 - 256 bits).\n   * @param recipientPublicKey - The recipient's ECDH P-256 public `CryptoKey`.\n   * Must have algorithm name `'ECDH'` and named curve `'P-256'`; mismatched\n   * algorithm or curve yields a `Failure` with error context.\n   * @param options - HKDF parameters; see {@link CryptoUtils.IWrapBytesOptions | IWrapBytesOptions}.\n   * @returns `Success` with the wrapped payload, or `Failure` with error context.\n   */\n  wrapBytes(\n    plaintext: Uint8Array,\n    recipientPublicKey: CryptoKey,\n    options: IWrapBytesOptions\n  ): Promise<Result<IWrappedBytes>>;\n\n  /**\n   * Inverse of {@link CryptoUtils.ICryptoProvider.wrapBytes | wrapBytes}.\n   * Recovers the original `plaintext` from a wrapped payload using the\n   * recipient's private key.\n   *\n   * Returns a `Failure` (never throws) on any of:\n   * - Tampered nonce or ciphertext (AES-GCM authentication fails)\n   * - Wrong private key (different shared secret derives a different wrap key)\n   * - Wrong HKDF parameters (different wrap key)\n   * - Malformed `ephemeralPublicKey` JWK\n   * - Malformed base64 in `nonce` or `ciphertext`\n   * @param wrapped - The wrapped payload produced by `wrapBytes`.\n   * @param recipientPrivateKey - The recipient's ECDH P-256 private\n   * `CryptoKey`. Must have algorithm name `'ECDH'` and named curve `'P-256'`,\n   * and key usages including `'deriveKey'` or `'deriveBits'`.\n   * @param options - The same HKDF parameters used at wrap time.\n   * @returns `Success` with the original `plaintext`, or `Failure` with error context.\n   */\n  unwrapBytes(\n    wrapped: IWrappedBytes,\n    recipientPrivateKey: CryptoKey,\n    options: IWrapBytesOptions\n  ): Promise<Result<Uint8Array>>;\n}\n\n// ============================================================================\n// Encryption Provider Interface\n// ============================================================================\n\n/**\n * High-level interface for encrypting JSON content by secret name.\n *\n * This abstraction unifies two common encryption workflows:\n * - **KeyStore**: looks up the named secret and crypto provider from the vault\n * - **DirectEncryptionProvider**: uses a pre-supplied key and crypto provider,\n *   optionally bound to a specific secret name for safety\n *\n * Callers that need to encrypt (e.g. `EditableCollection.save()`) depend on\n * this interface rather than on `KeyStore` directly, allowing mix-and-match.\n *\n * @public\n */\nexport interface IEncryptionProvider {\n  /**\n   * Encrypts JSON content under a named secret.\n   *\n   * @param secretName - Name of the secret to encrypt with\n   * @param content - JSON-safe content to encrypt\n   * @param metadata - Optional unencrypted metadata to include in the encrypted file\n   * @returns Success with encrypted file structure, or Failure with error context\n   */\n  encryptByName<TMetadata = JsonValue>(\n    secretName: string,\n    content: JsonValue,\n    metadata?: TMetadata\n  ): Promise<Result<IEncryptedFile<TMetadata>>>;\n}\n\n// ============================================================================\n// Encryption Configuration\n// ============================================================================\n\n/**\n * Behavior when an encrypted file cannot be decrypted.\n * @public\n */\nexport type EncryptedFileErrorMode =\n  | 'fail' // Return failure, abort loading\n  | 'skip' // Skip file silently, continue loading others\n  | 'warn'; // Log warning, skip file, continue loading\n\n/**\n * Function type for dynamic secret retrieval.\n * @public\n */\nexport type SecretProvider = (secretName: string) => Promise<Result<Uint8Array>>;\n\n/**\n * Configuration for encrypted file handling during loading.\n * @public\n */\nexport interface IEncryptionConfig {\n  /**\n   * Named secrets available for decryption.\n   */\n  readonly secrets?: ReadonlyArray<INamedSecret>;\n\n  /**\n   * Alternative: dynamic secret provider function.\n   * Called when a secret is not found in the secrets array.\n   */\n  readonly secretProvider?: SecretProvider;\n\n  /**\n   * Crypto provider implementation (Node.js or browser).\n   */\n  readonly cryptoProvider: ICryptoProvider;\n\n  /**\n   * Behavior when decryption key is missing (default: 'fail').\n   */\n  readonly onMissingKey?: EncryptedFileErrorMode;\n\n  /**\n   * Behavior when decryption fails (default: 'fail').\n   */\n  readonly onDecryptionError?: EncryptedFileErrorMode;\n}\n\n// ============================================================================\n// Detection Helper\n// ============================================================================\n\n/**\n * Checks if a JSON object appears to be an encrypted file.\n * Uses the format field as a discriminator.\n * @param json - JSON object to check\n * @returns true if the object has the encrypted file format field\n * @public\n */\nexport function isEncryptedFile(json: unknown): boolean {\n  if (typeof json !== 'object' || json === null) {\n    return false;\n  }\n  const obj = json as Record<string, unknown>;\n  return obj.format === Constants.ENCRYPTED_FILE_FORMAT;\n}\n"]}
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/model.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;AAKZ,OAAO,KAAK,SAAS,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,CAAC;AAoIrB;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAoC;IACnE,YAAY;IACZ,eAAe;IACf,WAAW;IACX,SAAS;IACT,QAAQ;CACT,CAAC;AAmWF,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAa;IAC3C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,GAAG,GAAG,IAA+B,CAAC;IAC5C,OAAO,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,qBAAqB,CAAC;AACxD,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\nimport { JsonValue } from '@fgv/ts-json-base';\nimport { Result, Uuid } from '@fgv/ts-utils';\n\nimport * as Constants from './constants';\nexport { Constants };\n\n// ============================================================================\n// Encryption Types\n// ============================================================================\n\n/**\n * Supported encryption algorithms.\n * @public\n */\nexport type EncryptionAlgorithm = typeof Constants.DEFAULT_ALGORITHM;\n\n/**\n * Format version for encrypted files.\n * @public\n */\nexport type EncryptedFileFormat = typeof Constants.ENCRYPTED_FILE_FORMAT;\n\n/**\n * Named secret for encryption/decryption.\n * @public\n */\nexport interface INamedSecret {\n  /**\n   * Unique name for this secret (referenced in encrypted files).\n   */\n  readonly name: string;\n\n  /**\n   * The actual secret key (32 bytes for AES-256).\n   */\n  readonly key: Uint8Array;\n}\n\n/**\n * Result of an encryption operation.\n * @public\n */\nexport interface IEncryptionResult {\n  /**\n   * Initialization vector used for encryption (12 bytes for GCM).\n   */\n  readonly iv: Uint8Array;\n\n  /**\n   * Authentication tag from GCM mode (16 bytes).\n   */\n  readonly authTag: Uint8Array;\n\n  /**\n   * The encrypted data.\n   */\n  readonly encryptedData: Uint8Array;\n}\n\n/**\n * Asymmetric keypair algorithms supported by the crypto provider.\n * - `'ecdsa-p256'`: ECDSA over the P-256 curve, for signing.\n * - `'rsa-oaep-2048'`: RSA-OAEP, 2048-bit modulus with SHA-256, for encryption.\n * - `'ecdh-p256'`: ECDH over the P-256 curve, for key agreement\n *   (e.g. as the recipient keypair in\n *   {@link CryptoUtils.ICryptoProvider.wrapBytes | wrapBytes} /\n *   {@link CryptoUtils.ICryptoProvider.unwrapBytes | unwrapBytes}).\n * - `'ed25519'`: EdDSA over the Edwards25519 curve, for signing.\n *   Deterministic — the per-signature nonce is derived from the private key\n *   and message rather than sampled randomly, eliminating the random-nonce\n *   reuse risk that ECDSA carries. Distinct from X25519 (key agreement over\n *   the Montgomery form, Curve25519).\n * - `'x25519'`: Diffie-Hellman key agreement over the Montgomery form of\n *   Curve25519. Key-agreement only — use `deriveBits`/`deriveKey` to produce\n *   a shared secret from one party's private key and the peer's public key.\n *   Distinct from Ed25519 (which uses the twisted-Edwards form for signing).\n * @public\n */\nexport type KeyPairAlgorithm = 'ecdsa-p256' | 'rsa-oaep-2048' | 'ecdh-p256' | 'ed25519' | 'x25519';\n\n/**\n * Caller-supplied HKDF parameters that domain-separate one\n * {@link CryptoUtils.ICryptoProvider.wrapBytes | wrapBytes} call from another.\n * Two wraps that share recipient but differ on `salt` or `info` derive distinct\n * wrap keys, so callers should pick values that bind the wrap to its\n * application context (e.g. a content hash for `salt` and a secret name for\n * `info`).\n *\n * Both fields are required; pass an empty `Uint8Array` if the caller has no\n * value to bind on a given axis. Silent defaulting would hide protocol\n * mistakes, so the API does not pick defaults.\n * @public\n */\nexport interface IWrapBytesOptions {\n  /**\n   * HKDF salt. Domain-separates this wrap from others in different contexts.\n   * Caller picks; common choices include a content hash, document id, channel\n   * id, etc.\n   */\n  readonly salt: Uint8Array;\n\n  /**\n   * HKDF info. Further binds the derived key to a specific use within the\n   * calling application. Caller picks; common choices include a secret name,\n   * message type, or version tag.\n   */\n  readonly info: Uint8Array;\n}\n\n/**\n * Output of {@link CryptoUtils.ICryptoProvider.wrapBytes | wrapBytes}. The\n * shape is JSON-serializable so it can travel directly over the wire or be\n * persisted as-is.\n * @public\n */\nexport interface IWrappedBytes {\n  /**\n   * Sender's ephemeral ECDH P-256 public key as a JSON Web Key. The matching\n   * ephemeral private key is dropped after the shared-secret derive.\n   */\n  readonly ephemeralPublicKey: JsonWebKey;\n\n  /**\n   * AES-GCM nonce, base64-encoded. 12 bytes (96 bits) — the standard AES-GCM\n   * nonce length.\n   */\n  readonly nonce: string;\n\n  /**\n   * AES-GCM ciphertext concatenated with the 16-byte authentication tag,\n   * base64-encoded. Tampering with either the nonce or the ciphertext causes\n   * unwrap to fail GCM authentication.\n   */\n  readonly ciphertext: string;\n}\n\n/**\n * All valid key pair algorithms.\n * @public\n */\nexport const allKeyPairAlgorithms: ReadonlyArray<KeyPairAlgorithm> = [\n  'ecdsa-p256',\n  'rsa-oaep-2048',\n  'ecdh-p256',\n  'ed25519',\n  'x25519'\n];\n\n/**\n * Supported key derivation functions.\n * @public\n */\nexport type KeyDerivationFunction = 'pbkdf2';\n\n/**\n * Key derivation parameters stored in encrypted files.\n * Allows decryption with password without needing to know the original salt/iterations.\n * @public\n */\nexport interface IKeyDerivationParams {\n  /**\n   * Key derivation function used.\n   */\n  readonly kdf: KeyDerivationFunction;\n\n  /**\n   * Base64-encoded salt used for key derivation.\n   */\n  readonly salt: string;\n\n  /**\n   * Number of iterations used for key derivation.\n   */\n  readonly iterations: number;\n}\n\n/**\n * Generic encrypted file format.\n * This is the JSON structure stored in encrypted files.\n * @typeParam TMetadata - Type of optional unencrypted metadata\n * @public\n */\nexport interface IEncryptedFile<TMetadata = JsonValue> {\n  /**\n   * Format identifier for versioning.\n   */\n  readonly format: EncryptedFileFormat;\n\n  /**\n   * Name of the secret required to decrypt (references INamedSecret.name).\n   */\n  readonly secretName: string;\n\n  /**\n   * Algorithm used for encryption.\n   */\n  readonly algorithm: EncryptionAlgorithm;\n\n  /**\n   * Base64-encoded initialization vector.\n   */\n  readonly iv: string;\n\n  /**\n   * Base64-encoded authentication tag (for GCM mode).\n   */\n  readonly authTag: string;\n\n  /**\n   * Base64-encoded encrypted data (JSON string when decrypted).\n   */\n  readonly encryptedData: string;\n\n  /**\n   * Optional unencrypted metadata for display/filtering.\n   */\n  readonly metadata?: TMetadata;\n\n  /**\n   * Optional key derivation parameters.\n   * If present, allows decryption using a password with these parameters.\n   * If absent, a pre-derived key must be provided.\n   */\n  readonly keyDerivation?: IKeyDerivationParams;\n}\n\n// ============================================================================\n// Crypto Provider Interface\n// ============================================================================\n\n/**\n * Crypto provider interface for cross-platform encryption.\n * Implementations provided for Node.js (crypto module) and browser (Web Crypto API).\n * @public\n */\nexport interface ICryptoProvider {\n  /**\n   * Encrypts plaintext using AES-256-GCM.\n   * @param plaintext - UTF-8 string to encrypt\n   * @param key - 32-byte encryption key\n   * @returns Success with encryption result, or Failure with error\n   */\n  encrypt(plaintext: string, key: Uint8Array): Promise<Result<IEncryptionResult>>;\n\n  /**\n   * Decrypts ciphertext using AES-256-GCM.\n   * @param encryptedData - Encrypted bytes\n   * @param key - 32-byte decryption key\n   * @param iv - Initialization vector (12 bytes)\n   * @param authTag - GCM authentication tag (16 bytes)\n   * @returns Success with decrypted UTF-8 string, or Failure with error\n   */\n  decrypt(\n    encryptedData: Uint8Array,\n    key: Uint8Array,\n    iv: Uint8Array,\n    authTag: Uint8Array\n  ): Promise<Result<string>>;\n\n  /**\n   * Generates a random 32-byte key suitable for AES-256.\n   * @returns Success with generated key, or Failure with error\n   */\n  generateKey(): Promise<Result<Uint8Array>>;\n\n  /**\n   * Derives a key from a password using PBKDF2.\n   * @param password - Password string\n   * @param salt - Salt bytes (should be at least 16 bytes)\n   * @param iterations - Number of iterations (recommend 100000+)\n   * @returns Success with derived 32-byte key, or Failure with error\n   */\n  deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;\n\n  /**\n   * Computes a SHA-256 hash of the given data.\n   * @param data - UTF-8 string to hash\n   * @returns Success with hex-encoded hash string, or Failure with error\n   */\n  sha256(data: string): Promise<Result<string>>;\n\n  // ============================================================================\n  // Platform Utility Methods\n  // ============================================================================\n\n  /**\n   * Generates cryptographically secure random bytes.\n   * @param length - Number of bytes to generate\n   * @returns Success with random bytes, or Failure with error\n   */\n  generateRandomBytes(length: number): Result<Uint8Array>;\n\n  /**\n   * Generates a cryptographically random UUIDv4 using the provider's\n   * underlying source of randomness. The default Node and browser\n   * implementations delegate to `globalThis.crypto.randomUUID`;\n   * deterministic providers (e.g. test stubs) may override to produce\n   * reproducible values.\n   * @returns Success with a canonical UUID, or Failure with error.\n   */\n  generateUuid(): Result<Uuid>;\n\n  /**\n   * Encodes binary data to base64 string.\n   * @param data - Binary data to encode\n   * @returns Base64-encoded string\n   */\n  toBase64(data: Uint8Array): string;\n\n  /**\n   * Decodes base64 string to binary data.\n   * @param base64 - Base64-encoded string\n   * @returns Success with decoded bytes, or Failure if invalid base64\n   */\n  fromBase64(base64: string): Result<Uint8Array>;\n\n  // ============================================================================\n  // Asymmetric Key Operations\n  // ============================================================================\n\n  /**\n   * Generates a new asymmetric keypair for the requested algorithm.\n   * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm | algorithm} to use.\n   * @param extractable - Whether the resulting `CryptoKey` objects may be exported.\n   * Set `false` on backends that store `CryptoKey` references directly (e.g.\n   * IndexedDB). Set `true` when the private key must round-trip through JWK or\n   * PKCS#8 (e.g. encrypted-file backends).\n   * @returns Success with the generated `CryptoKeyPair`, or Failure with error context.\n   */\n  generateKeyPair(algorithm: KeyPairAlgorithm, extractable: boolean): Promise<Result<CryptoKeyPair>>;\n\n  /**\n   * Exports the public half of a keypair as a JSON Web Key.\n   * @param publicKey - The public `CryptoKey` to export. Must be an `extractable`\n   * key generated for an asymmetric algorithm.\n   * @returns Success with the JWK, or Failure with error context.\n   */\n  exportPublicKeyJwk(publicKey: CryptoKey): Promise<Result<JsonWebKey>>;\n\n  /**\n   * Re-imports a public-key JWK as a `CryptoKey` usable for verification or\n   * encryption (depending on algorithm).\n   * @param jwk - The JSON Web Key produced by {@link CryptoUtils.ICryptoProvider.exportPublicKeyJwk | exportPublicKeyJwk}.\n   * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm | algorithm} the\n   * key was generated for. Determines the import parameters and key usages.\n   * @returns Success with the imported public `CryptoKey`, or Failure with error context.\n   */\n  importPublicKeyJwk(jwk: JsonWebKey, algorithm: KeyPairAlgorithm): Promise<Result<CryptoKey>>;\n\n  /**\n   * Exports a public `CryptoKey` as a DER-encoded SPKI (SubjectPublicKeyInfo) blob.\n   * SPKI is the standard algorithm-agnostic format for public key storage and transport.\n   * @param publicKey - The `CryptoKey` to export. Must have `key.type === 'public'`.\n   * @returns `Success` with the raw SPKI bytes, or `Failure` with error context.\n   */\n  exportPublicKeySpki(publicKey: CryptoKey): Promise<Result<Uint8Array>>;\n\n  /**\n   * Imports a public key from a DER-encoded SPKI blob.\n   * @param spkiBytes - The raw SPKI bytes produced by {@link CryptoUtils.ICryptoProvider.exportPublicKeySpki | exportPublicKeySpki}.\n   * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm | algorithm} the key was generated for.\n   * @returns `Success` with the imported public `CryptoKey`, or `Failure` with error context.\n   */\n  importPublicKeySpki(spkiBytes: Uint8Array, algorithm: KeyPairAlgorithm): Promise<Result<CryptoKey>>;\n\n  /**\n   * Wraps `plaintext` for delivery to the holder of the private key paired\n   * with `recipientPublicKey`. Uses ECIES with ECDH P-256, HKDF-SHA256, and\n   * AES-GCM-256.\n   *\n   * Generates a fresh ephemeral keypair per call; the ephemeral private key\n   * is discarded after the shared-secret derive. Only the recipient (with the\n   * matching private key) and the same HKDF parameters can recover\n   * `plaintext`.\n   *\n   * Empty `plaintext` is permitted; the resulting wrap contains only the\n   * 16-byte GCM authentication tag and round-trips back to an empty\n   * `Uint8Array`.\n   * @param plaintext - The bytes to wrap. Any length supported by AES-GCM\n   * (in practice, well below 2^39 - 256 bits).\n   * @param recipientPublicKey - The recipient's ECDH P-256 public `CryptoKey`.\n   * Must have algorithm name `'ECDH'` and named curve `'P-256'`; mismatched\n   * algorithm or curve yields a `Failure` with error context.\n   * @param options - HKDF parameters; see {@link CryptoUtils.IWrapBytesOptions | IWrapBytesOptions}.\n   * @returns `Success` with the wrapped payload, or `Failure` with error context.\n   */\n  wrapBytes(\n    plaintext: Uint8Array,\n    recipientPublicKey: CryptoKey,\n    options: IWrapBytesOptions\n  ): Promise<Result<IWrappedBytes>>;\n\n  /**\n   * Inverse of {@link CryptoUtils.ICryptoProvider.wrapBytes | wrapBytes}.\n   * Recovers the original `plaintext` from a wrapped payload using the\n   * recipient's private key.\n   *\n   * Returns a `Failure` (never throws) on any of:\n   * - Tampered nonce or ciphertext (AES-GCM authentication fails)\n   * - Wrong private key (different shared secret derives a different wrap key)\n   * - Wrong HKDF parameters (different wrap key)\n   * - Malformed `ephemeralPublicKey` JWK\n   * - Malformed base64 in `nonce` or `ciphertext`\n   * @param wrapped - The wrapped payload produced by `wrapBytes`.\n   * @param recipientPrivateKey - The recipient's ECDH P-256 private\n   * `CryptoKey`. Must have algorithm name `'ECDH'` and named curve `'P-256'`,\n   * and key usages including `'deriveKey'` or `'deriveBits'`.\n   * @param options - The same HKDF parameters used at wrap time.\n   * @returns `Success` with the original `plaintext`, or `Failure` with error context.\n   */\n  unwrapBytes(\n    wrapped: IWrappedBytes,\n    recipientPrivateKey: CryptoKey,\n    options: IWrapBytesOptions\n  ): Promise<Result<Uint8Array>>;\n}\n\n// ============================================================================\n// Encryption Provider Interface\n// ============================================================================\n\n/**\n * High-level interface for encrypting JSON content by secret name.\n *\n * This abstraction unifies two common encryption workflows:\n * - **KeyStore**: looks up the named secret and crypto provider from the vault\n * - **DirectEncryptionProvider**: uses a pre-supplied key and crypto provider,\n *   optionally bound to a specific secret name for safety\n *\n * Callers that need to encrypt (e.g. `EditableCollection.save()`) depend on\n * this interface rather than on `KeyStore` directly, allowing mix-and-match.\n *\n * @public\n */\nexport interface IEncryptionProvider {\n  /**\n   * Encrypts JSON content under a named secret.\n   *\n   * @param secretName - Name of the secret to encrypt with\n   * @param content - JSON-safe content to encrypt\n   * @param metadata - Optional unencrypted metadata to include in the encrypted file\n   * @returns Success with encrypted file structure, or Failure with error context\n   */\n  encryptByName<TMetadata = JsonValue>(\n    secretName: string,\n    content: JsonValue,\n    metadata?: TMetadata\n  ): Promise<Result<IEncryptedFile<TMetadata>>>;\n}\n\n// ============================================================================\n// Encryption Configuration\n// ============================================================================\n\n/**\n * Behavior when an encrypted file cannot be decrypted.\n * @public\n */\nexport type EncryptedFileErrorMode =\n  | 'fail' // Return failure, abort loading\n  | 'skip' // Skip file silently, continue loading others\n  | 'warn'; // Log warning, skip file, continue loading\n\n/**\n * Function type for dynamic secret retrieval.\n * @public\n */\nexport type SecretProvider = (secretName: string) => Promise<Result<Uint8Array>>;\n\n/**\n * Configuration for encrypted file handling during loading.\n * @public\n */\nexport interface IEncryptionConfig {\n  /**\n   * Named secrets available for decryption.\n   */\n  readonly secrets?: ReadonlyArray<INamedSecret>;\n\n  /**\n   * Alternative: dynamic secret provider function.\n   * Called when a secret is not found in the secrets array.\n   */\n  readonly secretProvider?: SecretProvider;\n\n  /**\n   * Crypto provider implementation (Node.js or browser).\n   */\n  readonly cryptoProvider: ICryptoProvider;\n\n  /**\n   * Behavior when decryption key is missing (default: 'fail').\n   */\n  readonly onMissingKey?: EncryptedFileErrorMode;\n\n  /**\n   * Behavior when decryption fails (default: 'fail').\n   */\n  readonly onDecryptionError?: EncryptedFileErrorMode;\n}\n\n// ============================================================================\n// Detection Helper\n// ============================================================================\n\n/**\n * Checks if a JSON object appears to be an encrypted file.\n * Uses the format field as a discriminator.\n * @param json - JSON object to check\n * @returns true if the object has the encrypted file format field\n * @public\n */\nexport function isEncryptedFile(json: unknown): boolean {\n  if (typeof json !== 'object' || json === null) {\n    return false;\n  }\n  const obj = json as Record<string, unknown>;\n  return obj.format === Constants.ENCRYPTED_FILE_FORMAT;\n}\n"]}

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

@@ -224,6 +224,31 @@ export class NodeCryptoProvider {
         const result = await captureAsyncResult(() => crypto.webcrypto.subtle.importKey('jwk', jwk, params.importPublicKey, true, params.publicKeyUsages));
         return result.withErrorFormat((e) => `Failed to import ${algorithm} public key from JWK: ${e}`);
     }
+    /**
+     * Exports a public `CryptoKey` as a DER-encoded SPKI blob.
+     * @param publicKey - The public `CryptoKey` to export.
+     * @returns `Success` with the raw SPKI bytes, or `Failure` with error context.
+     */
+    async exportPublicKeySpki(publicKey) {
+        if (publicKey.type !== 'public') {
+            return fail(`exportPublicKeySpki requires a public CryptoKey, got '${publicKey.type}'`);
+        }
+        const result = await captureAsyncResult(() => crypto.webcrypto.subtle.exportKey('spki', publicKey));
+        return result
+            .withErrorFormat((e) => `exportPublicKeySpki: failed to export key: ${e}`)
+            .onSuccess((buf) => succeed(new Uint8Array(buf)));
+    }
+    /**
+     * Imports a public key from a DER-encoded SPKI blob.
+     * @param spkiBytes - The raw SPKI bytes.
+     * @param algorithm - The algorithm the key was generated for.
+     * @returns `Success` with the imported public `CryptoKey`, or `Failure` with error context.
+     */
+    async importPublicKeySpki(spkiBytes, algorithm) {
+        const params = keyPairAlgorithmParams[algorithm];
+        const result = await captureAsyncResult(() => crypto.webcrypto.subtle.importKey('spki', spkiBytes, params.importPublicKey, true, [...params.publicKeyUsages]));
+        return result.withErrorFormat((e) => `importPublicKeySpki: failed to import ${algorithm} public key from SPKI: ${e}`);
+    }
     /**
      * Wraps `plaintext` for the holder of `recipientPublicKey` using
      * ECIES (ECDH P-256 + HKDF-SHA256 + AES-GCM-256). See

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

@@ -1 +1 @@
-{"version":3,"file":"nodeCryptoProvider.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/nodeCryptoProvider.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 * as crypto from 'crypto';\nimport {\n  captureAsyncResult,\n  captureResult,\n  fail,\n  Failure,\n  generateUuid,\n  Result,\n  succeed,\n  Success,\n  Uuid\n} from '@fgv/ts-utils';\nimport * as Constants from './constants';\nimport { keyPairAlgorithmParams } from './keyPairAlgorithmParams';\nimport {\n  ICryptoProvider,\n  IEncryptionResult,\n  IWrapBytesOptions,\n  IWrappedBytes,\n  KeyPairAlgorithm\n} from './model';\n\n/**\n * Node.js implementation of {@link CryptoUtils.ICryptoProvider} using the built-in crypto module.\n * Uses AES-256-GCM for authenticated encryption.\n * @public\n */\nexport class NodeCryptoProvider implements ICryptoProvider {\n  /**\n   * Encrypts plaintext using AES-256-GCM.\n   * @param plaintext - UTF-8 string to encrypt\n   * @param key - 32-byte encryption key\n   * @returns `Success` with encryption result, or `Failure` with an error.\n   */\n  public async encrypt(plaintext: string, key: Uint8Array): Promise<Result<IEncryptionResult>> {\n    return captureResult(() => {\n      if (key.length !== Constants.AES_256_KEY_SIZE) {\n        throw new Error(`Key must be ${Constants.AES_256_KEY_SIZE} bytes, got ${key.length}`);\n      }\n\n      // Generate random IV\n      const iv = crypto.randomBytes(Constants.GCM_IV_SIZE);\n\n      // Create cipher\n      const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);\n\n      // Encrypt\n      const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);\n\n      // Get auth tag\n      const authTag = cipher.getAuthTag();\n\n      return {\n        iv: new Uint8Array(iv),\n        authTag: new Uint8Array(authTag),\n        encryptedData: new Uint8Array(encrypted)\n      };\n    });\n  }\n\n  /**\n   * Decrypts ciphertext using AES-256-GCM.\n   * @param encryptedData - Encrypted bytes\n   * @param key - 32-byte decryption key\n   * @param iv - Initialization vector (12 bytes)\n   * @param authTag - GCM authentication tag (16 bytes)\n   * @returns `Success` with decrypted UTF-8 string, or `Failure` with an error.\n   */\n  public async decrypt(\n    encryptedData: Uint8Array,\n    key: Uint8Array,\n    iv: Uint8Array,\n    authTag: Uint8Array\n  ): Promise<Result<string>> {\n    if (key.length !== Constants.AES_256_KEY_SIZE) {\n      return fail(`Key must be ${Constants.AES_256_KEY_SIZE} bytes, got ${key.length}`);\n    }\n    if (iv.length !== Constants.GCM_IV_SIZE) {\n      return fail(`IV must be ${Constants.GCM_IV_SIZE} bytes, got ${iv.length}`);\n    }\n    if (authTag.length !== Constants.GCM_AUTH_TAG_SIZE) {\n      return fail(`Auth tag must be ${Constants.GCM_AUTH_TAG_SIZE} bytes, got ${authTag.length}`);\n    }\n\n    return captureResult(() => {\n      // Create decipher\n      const decipher = crypto.createDecipheriv('aes-256-gcm', Buffer.from(key), Buffer.from(iv));\n\n      // Set auth tag\n      decipher.setAuthTag(Buffer.from(authTag));\n\n      // Decrypt\n      const decrypted = Buffer.concat([decipher.update(Buffer.from(encryptedData)), decipher.final()]);\n\n      return decrypted.toString('utf8');\n    }).withErrorFormat((e) => `Decryption failed: ${e}`);\n  }\n\n  /**\n   * Generates a random 32-byte key suitable for AES-256.\n   * @returns `Success` with generated key, or `Failure` with an error.\n   */\n  public async generateKey(): Promise<Result<Uint8Array>> {\n    return captureResult(() => {\n      const key = crypto.randomBytes(Constants.AES_256_KEY_SIZE);\n      return new Uint8Array(key);\n    });\n  }\n\n  /**\n   * Derives a key from a password using PBKDF2.\n   * @param password - Password string\n   * @param salt - Salt bytes (should be at least 16 bytes)\n   * @param iterations - Number of iterations (recommend 100000+)\n   * @returns `Success` with derived 32-byte key, or `Failure` with an error.\n   */\n  public async deriveKey(\n    password: string,\n    salt: Uint8Array,\n    iterations: number\n  ): Promise<Result<Uint8Array>> {\n    if (iterations < 1) {\n      return fail('Iterations must be at least 1');\n    }\n    if (salt.length < 8) {\n      return fail('Salt should be at least 8 bytes');\n    }\n\n    return new Promise((resolve) => {\n      crypto.pbkdf2(\n        password,\n        Buffer.from(salt),\n        iterations,\n        Constants.AES_256_KEY_SIZE,\n        'sha256',\n        (err, derivedKey) => {\n          /* c8 ignore next 3 - PBKDF2 internal errors are hard to trigger with valid parameters */\n          if (err) {\n            resolve(fail(`Key derivation failed: ${err.message}`));\n          } else {\n            resolve(succeed(new Uint8Array(derivedKey)));\n          }\n        }\n      );\n    });\n  }\n\n  /**\n   * Computes a SHA-256 hash of the given data.\n   * @param data - UTF-8 string to hash\n   * @returns `Success` with hex-encoded hash string, or `Failure` with an error.\n   */\n  public async sha256(data: string): Promise<Result<string>> {\n    return captureResult(() => {\n      const hash = crypto.createHash('sha256');\n      hash.update(data, 'utf8');\n      return hash.digest('hex');\n    });\n  }\n\n  // ============================================================================\n  // Platform Utility Methods\n  // ============================================================================\n\n  /**\n   * Generates cryptographically secure random bytes.\n   * @param length - Number of bytes to generate\n   * @returns Success with random bytes, or Failure with error\n   */\n  public generateRandomBytes(length: number): Result<Uint8Array> {\n    if (length < 1) {\n      return Failure.with('Length must be at least 1');\n    }\n    return captureResult(() => new Uint8Array(crypto.randomBytes(length)));\n  }\n\n  /**\n   * Generates a cryptographically random UUIDv4 via the platform Web Crypto API.\n   * @returns `Success` with the generated UUID, or `Failure` if the runtime\n   * does not expose `globalThis.crypto.randomUUID`.\n   */\n  public generateUuid(): Result<Uuid> {\n    return captureResult(() => generateUuid());\n  }\n\n  /**\n   * Encodes binary data to base64 string.\n   * @param data - Binary data to encode\n   * @returns Base64-encoded string\n   */\n  public toBase64(data: Uint8Array): string {\n    return Buffer.from(data).toString('base64');\n  }\n\n  /**\n   * Decodes base64 string to binary data.\n   * @param base64 - Base64-encoded string\n   * @returns Success with decoded bytes, or Failure if invalid base64\n   */\n  public fromBase64(base64: string): Result<Uint8Array> {\n    // Check for obviously invalid characters\n    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(base64)) {\n      return Failure.with('Invalid base64 string');\n    }\n    return Success.with(new Uint8Array(Buffer.from(base64, 'base64')));\n  }\n\n  // ============================================================================\n  // Asymmetric Key Operations\n  // ============================================================================\n\n  /**\n   * Generates a new asymmetric keypair using Node's WebCrypto.\n   * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm | algorithm} to use.\n   * @param extractable - Whether the resulting keys may be exported.\n   * @returns `Success` with the generated `CryptoKeyPair`, or `Failure` with an error.\n   */\n  public async generateKeyPair(\n    algorithm: KeyPairAlgorithm,\n    extractable: boolean\n  ): Promise<Result<CryptoKeyPair>> {\n    const params = keyPairAlgorithmParams[algorithm];\n    // Widening upcast to `AlgorithmIdentifier` steers TS to subtle.generateKey's\n    // broad overload, which accepts the Ed25519 `{ name: 'Ed25519' }` shape and\n    // returns `CryptoKey | CryptoKeyPair`. The narrowing back to `CryptoKeyPair`\n    // is a runtime check via the `in` operator, not a type assertion.\n    const result = await captureAsyncResult(async () => {\n      const generated = await crypto.webcrypto.subtle.generateKey(\n        params.generateKey as AlgorithmIdentifier,\n        extractable,\n        [...params.keyPairUsages]\n      );\n      if ('privateKey' in generated && 'publicKey' in generated) {\n        return generated;\n      }\n      /* c8 ignore next - unreachable: every entry in keyPairAlgorithmParams produces a keypair */\n      throw new Error(`${algorithm} unexpectedly produced a single CryptoKey`);\n    });\n    return result.withErrorFormat((e) => `Failed to generate ${algorithm} keypair: ${e}`);\n  }\n\n  /**\n   * Exports a public `CryptoKey` as a JSON Web Key.\n   * @remarks\n   * Rejects non-public keys at runtime. WebCrypto's `exportKey('jwk', ...)`\n   * does not enforce public-vs-private; without this guard a caller that\n   * passed an extractable private key would receive its private fields\n   * (`d`, `p`, `q`, ...) as JWK, defeating the method's name.\n   * @param publicKey - Extractable public key to export.\n   * @returns `Success` with the JWK, or `Failure` if not a public key or if export fails.\n   */\n  public async exportPublicKeyJwk(publicKey: CryptoKey): Promise<Result<JsonWebKey>> {\n    if (publicKey.type !== 'public') {\n      return fail(`exportPublicKeyJwk requires a public CryptoKey, got '${publicKey.type}'`);\n    }\n    const result = await captureAsyncResult(() => crypto.webcrypto.subtle.exportKey('jwk', publicKey));\n    return result.withErrorFormat((e) => `Failed to export public key as JWK: ${e}`);\n  }\n\n  /**\n   * Imports a public-key JWK as a `CryptoKey` for the requested algorithm.\n   * @param jwk - The JSON Web Key produced by a prior export.\n   * @param algorithm - The algorithm the key was generated for.\n   * @returns `Success` with the imported public `CryptoKey`, or `Failure` with an error.\n   */\n  public async importPublicKeyJwk(jwk: JsonWebKey, algorithm: KeyPairAlgorithm): Promise<Result<CryptoKey>> {\n    const params = keyPairAlgorithmParams[algorithm];\n    const result = await captureAsyncResult(() =>\n      crypto.webcrypto.subtle.importKey('jwk', jwk, params.importPublicKey, true, params.publicKeyUsages)\n    );\n    return result.withErrorFormat((e) => `Failed to import ${algorithm} public key from JWK: ${e}`);\n  }\n\n  /**\n   * Wraps `plaintext` for the holder of `recipientPublicKey` using\n   * ECIES (ECDH P-256 + HKDF-SHA256 + AES-GCM-256). See\n   * {@link CryptoUtils.ICryptoProvider.wrapBytes | ICryptoProvider.wrapBytes}.\n   * @param plaintext - The bytes to wrap.\n   * @param recipientPublicKey - The recipient's ECDH P-256 public `CryptoKey`.\n   * @param options - HKDF salt and info; see {@link CryptoUtils.IWrapBytesOptions | IWrapBytesOptions}.\n   * @returns `Success` with the wrapped payload, or `Failure` with an error.\n   */\n  public async wrapBytes(\n    plaintext: Uint8Array,\n    recipientPublicKey: CryptoKey,\n    options: IWrapBytesOptions\n  ): Promise<Result<IWrappedBytes>> {\n    const recipientCheck = checkEcdhP256(recipientPublicKey, 'public', 'recipient public key');\n    if (recipientCheck.isFailure()) {\n      return fail(`wrapBytes failed: ${recipientCheck.message}`);\n    }\n    const subtle = crypto.webcrypto.subtle;\n    const result = await captureAsyncResult(async () => {\n      const ephemeral = (await subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, [\n        'deriveKey'\n      ])) as CryptoKeyPair;\n      const hkdfBase = await subtle.deriveKey(\n        { name: 'ECDH', public: recipientPublicKey },\n        ephemeral.privateKey,\n        { name: 'HKDF' },\n        false,\n        ['deriveKey']\n      );\n      const wrapKey = await subtle.deriveKey(\n        { name: 'HKDF', salt: options.salt, info: options.info, hash: 'SHA-256' },\n        hkdfBase,\n        { name: 'AES-GCM', length: 256 },\n        false,\n        ['encrypt']\n      );\n      const nonce = crypto.randomBytes(Constants.GCM_IV_SIZE);\n      const ctBuf = await subtle.encrypt({ name: 'AES-GCM', iv: nonce }, wrapKey, plaintext);\n      const ephemeralPublicKey = await subtle.exportKey('jwk', ephemeral.publicKey);\n      return {\n        ephemeralPublicKey,\n        nonce: this.toBase64(nonce),\n        ciphertext: this.toBase64(new Uint8Array(ctBuf))\n      };\n    });\n    return result.withErrorFormat((e) => `wrapBytes failed: ${e}`);\n  }\n\n  /**\n   * Unwraps a payload produced by `wrapBytes` using the recipient's private\n   * key. See {@link CryptoUtils.ICryptoProvider.unwrapBytes | ICryptoProvider.unwrapBytes}.\n   * @param wrapped - The wrapped payload.\n   * @param recipientPrivateKey - The recipient's ECDH P-256 private `CryptoKey`.\n   * @param options - HKDF salt and info matching the wrap call.\n   * @returns `Success` with the original `plaintext`, or `Failure` with an error.\n   */\n  public async unwrapBytes(\n    wrapped: IWrappedBytes,\n    recipientPrivateKey: CryptoKey,\n    options: IWrapBytesOptions\n  ): Promise<Result<Uint8Array>> {\n    const recipientCheck = checkEcdhP256(recipientPrivateKey, 'private', 'recipient private key');\n    if (recipientCheck.isFailure()) {\n      return fail(`unwrapBytes failed: ${recipientCheck.message}`);\n    }\n    const nonceResult = this.fromBase64(wrapped.nonce);\n    if (nonceResult.isFailure()) {\n      return fail(`unwrapBytes failed: nonce: ${nonceResult.message}`);\n    }\n    if (nonceResult.value.length !== Constants.GCM_IV_SIZE) {\n      return fail(\n        `unwrapBytes failed: nonce must be ${Constants.GCM_IV_SIZE} bytes (got ${nonceResult.value.length})`\n      );\n    }\n    const ciphertextResult = this.fromBase64(wrapped.ciphertext);\n    if (ciphertextResult.isFailure()) {\n      return fail(`unwrapBytes failed: ciphertext: ${ciphertextResult.message}`);\n    }\n    if (ciphertextResult.value.length < Constants.GCM_AUTH_TAG_SIZE) {\n      return fail(\n        `unwrapBytes failed: ciphertext must be at least ${Constants.GCM_AUTH_TAG_SIZE} bytes (got ${ciphertextResult.value.length})`\n      );\n    }\n    const subtle = crypto.webcrypto.subtle;\n    const result = await captureAsyncResult(async () => {\n      const ephemeralPub = await subtle.importKey(\n        'jwk',\n        wrapped.ephemeralPublicKey,\n        { name: 'ECDH', namedCurve: 'P-256' },\n        false,\n        []\n      );\n      const hkdfBase = await subtle.deriveKey(\n        { name: 'ECDH', public: ephemeralPub },\n        recipientPrivateKey,\n        { name: 'HKDF' },\n        false,\n        ['deriveKey']\n      );\n      const wrapKey = await subtle.deriveKey(\n        { name: 'HKDF', salt: options.salt, info: options.info, hash: 'SHA-256' },\n        hkdfBase,\n        { name: 'AES-GCM', length: 256 },\n        false,\n        ['decrypt']\n      );\n      const ptBuf = await subtle.decrypt(\n        { name: 'AES-GCM', iv: nonceResult.value },\n        wrapKey,\n        ciphertextResult.value\n      );\n      return new Uint8Array(ptBuf);\n    });\n    return result.withErrorFormat((e) => `unwrapBytes failed: ${e}`);\n  }\n}\n\n/**\n * Verifies that `key` is an ECDH P-256 `CryptoKey` of the expected `keyType`\n * (public or private). Used by the wrap/unwrap methods to surface a clean\n * `Failure` instead of letting the WebCrypto deriveKey call throw a less\n * informative error later in the pipeline. Key usages are intentionally not\n * checked here: WebCrypto already produces a specific error if `deriveKey` is\n * not in `usages`, and `deriveBits` is an equally valid alternative usage that\n * an explicit check would have to track.\n * @param key - The CryptoKey to validate.\n * @param keyType - The required `key.type` ('public' for wrap, 'private' for unwrap).\n * @param label - Human-readable role label included in the failure message.\n * @returns `Success` with the key (unchanged) when the algorithm, curve, and\n * type all match; otherwise `Failure` with `<label> must be ECDH P-256 (...)`.\n */\nfunction checkEcdhP256(key: CryptoKey, keyType: 'public' | 'private', label: string): Result<CryptoKey> {\n  if (key.algorithm.name !== 'ECDH') {\n    return fail(`${label} must be ECDH P-256 (got algorithm '${key.algorithm.name}')`);\n  }\n  const namedCurve = (key.algorithm as EcKeyAlgorithm).namedCurve;\n  if (namedCurve !== 'P-256') {\n    return fail(`${label} must be ECDH P-256 (got curve '${namedCurve}')`);\n  }\n  if (key.type !== keyType) {\n    return fail(`${label} must be a ${keyType} CryptoKey (got '${key.type}')`);\n  }\n  return succeed(key);\n}\n\n/**\n * Singleton instance of {@link CryptoUtils.NodeCryptoProvider}.\n * @public\n */\nexport const nodeCryptoProvider: NodeCryptoProvider = new NodeCryptoProvider();\n"]}
+{"version":3,"file":"nodeCryptoProvider.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/nodeCryptoProvider.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 * as crypto from 'crypto';\nimport {\n  captureAsyncResult,\n  captureResult,\n  fail,\n  Failure,\n  generateUuid,\n  Result,\n  succeed,\n  Success,\n  Uuid\n} from '@fgv/ts-utils';\nimport * as Constants from './constants';\nimport { keyPairAlgorithmParams } from './keyPairAlgorithmParams';\nimport {\n  ICryptoProvider,\n  IEncryptionResult,\n  IWrapBytesOptions,\n  IWrappedBytes,\n  KeyPairAlgorithm\n} from './model';\n\n/**\n * Node.js implementation of {@link CryptoUtils.ICryptoProvider} using the built-in crypto module.\n * Uses AES-256-GCM for authenticated encryption.\n * @public\n */\nexport class NodeCryptoProvider implements ICryptoProvider {\n  /**\n   * Encrypts plaintext using AES-256-GCM.\n   * @param plaintext - UTF-8 string to encrypt\n   * @param key - 32-byte encryption key\n   * @returns `Success` with encryption result, or `Failure` with an error.\n   */\n  public async encrypt(plaintext: string, key: Uint8Array): Promise<Result<IEncryptionResult>> {\n    return captureResult(() => {\n      if (key.length !== Constants.AES_256_KEY_SIZE) {\n        throw new Error(`Key must be ${Constants.AES_256_KEY_SIZE} bytes, got ${key.length}`);\n      }\n\n      // Generate random IV\n      const iv = crypto.randomBytes(Constants.GCM_IV_SIZE);\n\n      // Create cipher\n      const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);\n\n      // Encrypt\n      const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);\n\n      // Get auth tag\n      const authTag = cipher.getAuthTag();\n\n      return {\n        iv: new Uint8Array(iv),\n        authTag: new Uint8Array(authTag),\n        encryptedData: new Uint8Array(encrypted)\n      };\n    });\n  }\n\n  /**\n   * Decrypts ciphertext using AES-256-GCM.\n   * @param encryptedData - Encrypted bytes\n   * @param key - 32-byte decryption key\n   * @param iv - Initialization vector (12 bytes)\n   * @param authTag - GCM authentication tag (16 bytes)\n   * @returns `Success` with decrypted UTF-8 string, or `Failure` with an error.\n   */\n  public async decrypt(\n    encryptedData: Uint8Array,\n    key: Uint8Array,\n    iv: Uint8Array,\n    authTag: Uint8Array\n  ): Promise<Result<string>> {\n    if (key.length !== Constants.AES_256_KEY_SIZE) {\n      return fail(`Key must be ${Constants.AES_256_KEY_SIZE} bytes, got ${key.length}`);\n    }\n    if (iv.length !== Constants.GCM_IV_SIZE) {\n      return fail(`IV must be ${Constants.GCM_IV_SIZE} bytes, got ${iv.length}`);\n    }\n    if (authTag.length !== Constants.GCM_AUTH_TAG_SIZE) {\n      return fail(`Auth tag must be ${Constants.GCM_AUTH_TAG_SIZE} bytes, got ${authTag.length}`);\n    }\n\n    return captureResult(() => {\n      // Create decipher\n      const decipher = crypto.createDecipheriv('aes-256-gcm', Buffer.from(key), Buffer.from(iv));\n\n      // Set auth tag\n      decipher.setAuthTag(Buffer.from(authTag));\n\n      // Decrypt\n      const decrypted = Buffer.concat([decipher.update(Buffer.from(encryptedData)), decipher.final()]);\n\n      return decrypted.toString('utf8');\n    }).withErrorFormat((e) => `Decryption failed: ${e}`);\n  }\n\n  /**\n   * Generates a random 32-byte key suitable for AES-256.\n   * @returns `Success` with generated key, or `Failure` with an error.\n   */\n  public async generateKey(): Promise<Result<Uint8Array>> {\n    return captureResult(() => {\n      const key = crypto.randomBytes(Constants.AES_256_KEY_SIZE);\n      return new Uint8Array(key);\n    });\n  }\n\n  /**\n   * Derives a key from a password using PBKDF2.\n   * @param password - Password string\n   * @param salt - Salt bytes (should be at least 16 bytes)\n   * @param iterations - Number of iterations (recommend 100000+)\n   * @returns `Success` with derived 32-byte key, or `Failure` with an error.\n   */\n  public async deriveKey(\n    password: string,\n    salt: Uint8Array,\n    iterations: number\n  ): Promise<Result<Uint8Array>> {\n    if (iterations < 1) {\n      return fail('Iterations must be at least 1');\n    }\n    if (salt.length < 8) {\n      return fail('Salt should be at least 8 bytes');\n    }\n\n    return new Promise((resolve) => {\n      crypto.pbkdf2(\n        password,\n        Buffer.from(salt),\n        iterations,\n        Constants.AES_256_KEY_SIZE,\n        'sha256',\n        (err, derivedKey) => {\n          /* c8 ignore next 3 - PBKDF2 internal errors are hard to trigger with valid parameters */\n          if (err) {\n            resolve(fail(`Key derivation failed: ${err.message}`));\n          } else {\n            resolve(succeed(new Uint8Array(derivedKey)));\n          }\n        }\n      );\n    });\n  }\n\n  /**\n   * Computes a SHA-256 hash of the given data.\n   * @param data - UTF-8 string to hash\n   * @returns `Success` with hex-encoded hash string, or `Failure` with an error.\n   */\n  public async sha256(data: string): Promise<Result<string>> {\n    return captureResult(() => {\n      const hash = crypto.createHash('sha256');\n      hash.update(data, 'utf8');\n      return hash.digest('hex');\n    });\n  }\n\n  // ============================================================================\n  // Platform Utility Methods\n  // ============================================================================\n\n  /**\n   * Generates cryptographically secure random bytes.\n   * @param length - Number of bytes to generate\n   * @returns Success with random bytes, or Failure with error\n   */\n  public generateRandomBytes(length: number): Result<Uint8Array> {\n    if (length < 1) {\n      return Failure.with('Length must be at least 1');\n    }\n    return captureResult(() => new Uint8Array(crypto.randomBytes(length)));\n  }\n\n  /**\n   * Generates a cryptographically random UUIDv4 via the platform Web Crypto API.\n   * @returns `Success` with the generated UUID, or `Failure` if the runtime\n   * does not expose `globalThis.crypto.randomUUID`.\n   */\n  public generateUuid(): Result<Uuid> {\n    return captureResult(() => generateUuid());\n  }\n\n  /**\n   * Encodes binary data to base64 string.\n   * @param data - Binary data to encode\n   * @returns Base64-encoded string\n   */\n  public toBase64(data: Uint8Array): string {\n    return Buffer.from(data).toString('base64');\n  }\n\n  /**\n   * Decodes base64 string to binary data.\n   * @param base64 - Base64-encoded string\n   * @returns Success with decoded bytes, or Failure if invalid base64\n   */\n  public fromBase64(base64: string): Result<Uint8Array> {\n    // Check for obviously invalid characters\n    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(base64)) {\n      return Failure.with('Invalid base64 string');\n    }\n    return Success.with(new Uint8Array(Buffer.from(base64, 'base64')));\n  }\n\n  // ============================================================================\n  // Asymmetric Key Operations\n  // ============================================================================\n\n  /**\n   * Generates a new asymmetric keypair using Node's WebCrypto.\n   * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm | algorithm} to use.\n   * @param extractable - Whether the resulting keys may be exported.\n   * @returns `Success` with the generated `CryptoKeyPair`, or `Failure` with an error.\n   */\n  public async generateKeyPair(\n    algorithm: KeyPairAlgorithm,\n    extractable: boolean\n  ): Promise<Result<CryptoKeyPair>> {\n    const params = keyPairAlgorithmParams[algorithm];\n    // Widening upcast to `AlgorithmIdentifier` steers TS to subtle.generateKey's\n    // broad overload, which accepts the Ed25519 `{ name: 'Ed25519' }` shape and\n    // returns `CryptoKey | CryptoKeyPair`. The narrowing back to `CryptoKeyPair`\n    // is a runtime check via the `in` operator, not a type assertion.\n    const result = await captureAsyncResult(async () => {\n      const generated = await crypto.webcrypto.subtle.generateKey(\n        params.generateKey as AlgorithmIdentifier,\n        extractable,\n        [...params.keyPairUsages]\n      );\n      if ('privateKey' in generated && 'publicKey' in generated) {\n        return generated;\n      }\n      /* c8 ignore next - unreachable: every entry in keyPairAlgorithmParams produces a keypair */\n      throw new Error(`${algorithm} unexpectedly produced a single CryptoKey`);\n    });\n    return result.withErrorFormat((e) => `Failed to generate ${algorithm} keypair: ${e}`);\n  }\n\n  /**\n   * Exports a public `CryptoKey` as a JSON Web Key.\n   * @remarks\n   * Rejects non-public keys at runtime. WebCrypto's `exportKey('jwk', ...)`\n   * does not enforce public-vs-private; without this guard a caller that\n   * passed an extractable private key would receive its private fields\n   * (`d`, `p`, `q`, ...) as JWK, defeating the method's name.\n   * @param publicKey - Extractable public key to export.\n   * @returns `Success` with the JWK, or `Failure` if not a public key or if export fails.\n   */\n  public async exportPublicKeyJwk(publicKey: CryptoKey): Promise<Result<JsonWebKey>> {\n    if (publicKey.type !== 'public') {\n      return fail(`exportPublicKeyJwk requires a public CryptoKey, got '${publicKey.type}'`);\n    }\n    const result = await captureAsyncResult(() => crypto.webcrypto.subtle.exportKey('jwk', publicKey));\n    return result.withErrorFormat((e) => `Failed to export public key as JWK: ${e}`);\n  }\n\n  /**\n   * Imports a public-key JWK as a `CryptoKey` for the requested algorithm.\n   * @param jwk - The JSON Web Key produced by a prior export.\n   * @param algorithm - The algorithm the key was generated for.\n   * @returns `Success` with the imported public `CryptoKey`, or `Failure` with an error.\n   */\n  public async importPublicKeyJwk(jwk: JsonWebKey, algorithm: KeyPairAlgorithm): Promise<Result<CryptoKey>> {\n    const params = keyPairAlgorithmParams[algorithm];\n    const result = await captureAsyncResult(() =>\n      crypto.webcrypto.subtle.importKey('jwk', jwk, params.importPublicKey, true, params.publicKeyUsages)\n    );\n    return result.withErrorFormat((e) => `Failed to import ${algorithm} public key from JWK: ${e}`);\n  }\n\n  /**\n   * Exports a public `CryptoKey` as a DER-encoded SPKI blob.\n   * @param publicKey - The public `CryptoKey` to export.\n   * @returns `Success` with the raw SPKI bytes, or `Failure` with error context.\n   */\n  public async exportPublicKeySpki(publicKey: CryptoKey): Promise<Result<Uint8Array>> {\n    if (publicKey.type !== 'public') {\n      return fail(`exportPublicKeySpki requires a public CryptoKey, got '${publicKey.type}'`);\n    }\n    const result = await captureAsyncResult(() => crypto.webcrypto.subtle.exportKey('spki', publicKey));\n    return result\n      .withErrorFormat((e) => `exportPublicKeySpki: failed to export key: ${e}`)\n      .onSuccess((buf) => succeed(new Uint8Array(buf)));\n  }\n\n  /**\n   * Imports a public key from a DER-encoded SPKI blob.\n   * @param spkiBytes - The raw SPKI bytes.\n   * @param algorithm - The algorithm the key was generated for.\n   * @returns `Success` with the imported public `CryptoKey`, or `Failure` with error context.\n   */\n  public async importPublicKeySpki(\n    spkiBytes: Uint8Array,\n    algorithm: KeyPairAlgorithm\n  ): Promise<Result<CryptoKey>> {\n    const params = keyPairAlgorithmParams[algorithm];\n    const result = await captureAsyncResult(() =>\n      crypto.webcrypto.subtle.importKey(\n        'spki',\n        spkiBytes,\n        params.importPublicKey as AlgorithmIdentifier,\n        true,\n        [...params.publicKeyUsages]\n      )\n    );\n    return result.withErrorFormat(\n      (e) => `importPublicKeySpki: failed to import ${algorithm} public key from SPKI: ${e}`\n    );\n  }\n\n  /**\n   * Wraps `plaintext` for the holder of `recipientPublicKey` using\n   * ECIES (ECDH P-256 + HKDF-SHA256 + AES-GCM-256). See\n   * {@link CryptoUtils.ICryptoProvider.wrapBytes | ICryptoProvider.wrapBytes}.\n   * @param plaintext - The bytes to wrap.\n   * @param recipientPublicKey - The recipient's ECDH P-256 public `CryptoKey`.\n   * @param options - HKDF salt and info; see {@link CryptoUtils.IWrapBytesOptions | IWrapBytesOptions}.\n   * @returns `Success` with the wrapped payload, or `Failure` with an error.\n   */\n  public async wrapBytes(\n    plaintext: Uint8Array,\n    recipientPublicKey: CryptoKey,\n    options: IWrapBytesOptions\n  ): Promise<Result<IWrappedBytes>> {\n    const recipientCheck = checkEcdhP256(recipientPublicKey, 'public', 'recipient public key');\n    if (recipientCheck.isFailure()) {\n      return fail(`wrapBytes failed: ${recipientCheck.message}`);\n    }\n    const subtle = crypto.webcrypto.subtle;\n    const result = await captureAsyncResult(async () => {\n      const ephemeral = (await subtle.generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, [\n        'deriveKey'\n      ])) as CryptoKeyPair;\n      const hkdfBase = await subtle.deriveKey(\n        { name: 'ECDH', public: recipientPublicKey },\n        ephemeral.privateKey,\n        { name: 'HKDF' },\n        false,\n        ['deriveKey']\n      );\n      const wrapKey = await subtle.deriveKey(\n        { name: 'HKDF', salt: options.salt, info: options.info, hash: 'SHA-256' },\n        hkdfBase,\n        { name: 'AES-GCM', length: 256 },\n        false,\n        ['encrypt']\n      );\n      const nonce = crypto.randomBytes(Constants.GCM_IV_SIZE);\n      const ctBuf = await subtle.encrypt({ name: 'AES-GCM', iv: nonce }, wrapKey, plaintext);\n      const ephemeralPublicKey = await subtle.exportKey('jwk', ephemeral.publicKey);\n      return {\n        ephemeralPublicKey,\n        nonce: this.toBase64(nonce),\n        ciphertext: this.toBase64(new Uint8Array(ctBuf))\n      };\n    });\n    return result.withErrorFormat((e) => `wrapBytes failed: ${e}`);\n  }\n\n  /**\n   * Unwraps a payload produced by `wrapBytes` using the recipient's private\n   * key. See {@link CryptoUtils.ICryptoProvider.unwrapBytes | ICryptoProvider.unwrapBytes}.\n   * @param wrapped - The wrapped payload.\n   * @param recipientPrivateKey - The recipient's ECDH P-256 private `CryptoKey`.\n   * @param options - HKDF salt and info matching the wrap call.\n   * @returns `Success` with the original `plaintext`, or `Failure` with an error.\n   */\n  public async unwrapBytes(\n    wrapped: IWrappedBytes,\n    recipientPrivateKey: CryptoKey,\n    options: IWrapBytesOptions\n  ): Promise<Result<Uint8Array>> {\n    const recipientCheck = checkEcdhP256(recipientPrivateKey, 'private', 'recipient private key');\n    if (recipientCheck.isFailure()) {\n      return fail(`unwrapBytes failed: ${recipientCheck.message}`);\n    }\n    const nonceResult = this.fromBase64(wrapped.nonce);\n    if (nonceResult.isFailure()) {\n      return fail(`unwrapBytes failed: nonce: ${nonceResult.message}`);\n    }\n    if (nonceResult.value.length !== Constants.GCM_IV_SIZE) {\n      return fail(\n        `unwrapBytes failed: nonce must be ${Constants.GCM_IV_SIZE} bytes (got ${nonceResult.value.length})`\n      );\n    }\n    const ciphertextResult = this.fromBase64(wrapped.ciphertext);\n    if (ciphertextResult.isFailure()) {\n      return fail(`unwrapBytes failed: ciphertext: ${ciphertextResult.message}`);\n    }\n    if (ciphertextResult.value.length < Constants.GCM_AUTH_TAG_SIZE) {\n      return fail(\n        `unwrapBytes failed: ciphertext must be at least ${Constants.GCM_AUTH_TAG_SIZE} bytes (got ${ciphertextResult.value.length})`\n      );\n    }\n    const subtle = crypto.webcrypto.subtle;\n    const result = await captureAsyncResult(async () => {\n      const ephemeralPub = await subtle.importKey(\n        'jwk',\n        wrapped.ephemeralPublicKey,\n        { name: 'ECDH', namedCurve: 'P-256' },\n        false,\n        []\n      );\n      const hkdfBase = await subtle.deriveKey(\n        { name: 'ECDH', public: ephemeralPub },\n        recipientPrivateKey,\n        { name: 'HKDF' },\n        false,\n        ['deriveKey']\n      );\n      const wrapKey = await subtle.deriveKey(\n        { name: 'HKDF', salt: options.salt, info: options.info, hash: 'SHA-256' },\n        hkdfBase,\n        { name: 'AES-GCM', length: 256 },\n        false,\n        ['decrypt']\n      );\n      const ptBuf = await subtle.decrypt(\n        { name: 'AES-GCM', iv: nonceResult.value },\n        wrapKey,\n        ciphertextResult.value\n      );\n      return new Uint8Array(ptBuf);\n    });\n    return result.withErrorFormat((e) => `unwrapBytes failed: ${e}`);\n  }\n}\n\n/**\n * Verifies that `key` is an ECDH P-256 `CryptoKey` of the expected `keyType`\n * (public or private). Used by the wrap/unwrap methods to surface a clean\n * `Failure` instead of letting the WebCrypto deriveKey call throw a less\n * informative error later in the pipeline. Key usages are intentionally not\n * checked here: WebCrypto already produces a specific error if `deriveKey` is\n * not in `usages`, and `deriveBits` is an equally valid alternative usage that\n * an explicit check would have to track.\n * @param key - The CryptoKey to validate.\n * @param keyType - The required `key.type` ('public' for wrap, 'private' for unwrap).\n * @param label - Human-readable role label included in the failure message.\n * @returns `Success` with the key (unchanged) when the algorithm, curve, and\n * type all match; otherwise `Failure` with `<label> must be ECDH P-256 (...)`.\n */\nfunction checkEcdhP256(key: CryptoKey, keyType: 'public' | 'private', label: string): Result<CryptoKey> {\n  if (key.algorithm.name !== 'ECDH') {\n    return fail(`${label} must be ECDH P-256 (got algorithm '${key.algorithm.name}')`);\n  }\n  const namedCurve = (key.algorithm as EcKeyAlgorithm).namedCurve;\n  if (namedCurve !== 'P-256') {\n    return fail(`${label} must be ECDH P-256 (got curve '${namedCurve}')`);\n  }\n  if (key.type !== keyType) {\n    return fail(`${label} must be a ${keyType} CryptoKey (got '${key.type}')`);\n  }\n  return succeed(key);\n}\n\n/**\n * Singleton instance of {@link CryptoUtils.NodeCryptoProvider}.\n * @public\n */\nexport const nodeCryptoProvider: NodeCryptoProvider = new NodeCryptoProvider();\n"]}

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

@@ -0,0 +1,130 @@
+// 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 { fail, succeed } from '@fgv/ts-utils';
+/**
+ * Encodes a `Uint8Array` as a multibase base64url (no-padding) string.
+ *
+ * The multibase prefix `'m'` identifies the encoding as RFC 4648 base64url
+ * without padding. The body uses base64url alphabet: `+` → `-`, `/` → `_`,
+ * and trailing `=` padding is stripped.
+ *
+ * @param data - The binary data to encode.
+ * @returns A multibase-prefixed base64url string (`'m' + base64url-no-pad`).
+ * @public
+ */
+export function multibaseBase64UrlEncode(data) {
+    let base64;
+    if (typeof Buffer !== 'undefined') {
+        base64 = Buffer.from(data).toString('base64');
+        /* c8 ignore start - browser-only: btoa path not available in Node tests */
+    }
+    else {
+        let binary = '';
+        for (let i = 0; i < data.length; i++) {
+            binary += String.fromCharCode(data[i]);
+        }
+        base64 = btoa(binary);
+    }
+    /* c8 ignore stop */
+    // Convert to base64url: + → -, / → _, strip = padding
+    const base64url = base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+    return 'm' + base64url;
+}
+/**
+ * Decodes a multibase base64url (no-padding) string back to a `Uint8Array`.
+ *
+ * Validates that the first character is `'m'` (the multibase prefix for
+ * RFC 4648 base64url without padding), then decodes the remaining body.
+ *
+ * @param encoded - A multibase-prefixed base64url string.
+ * @returns `Success` with the decoded bytes, or `Failure` with error context.
+ * @public
+ */
+export function multibaseBase64UrlDecode(encoded) {
+    var _a;
+    if (!encoded.startsWith('m')) {
+        return fail(`multibaseBase64UrlDecode: invalid multibase prefix '${(_a = encoded[0]) !== null && _a !== void 0 ? _a : '(empty)'}' — expected 'm' (base64url)`);
+    }
+    const body = encoded.slice(1);
+    if (!/^[A-Za-z0-9_-]*$/.test(body) || body.length % 4 === 1) {
+        return fail(`multibaseBase64UrlDecode: malformed base64url body`);
+    }
+    // Convert base64url back to standard base64 and restore padding
+    const base64 = body.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);
+    try {
+        let bytes;
+        if (typeof Buffer !== 'undefined') {
+            bytes = new Uint8Array(Buffer.from(padded, 'base64'));
+            /* c8 ignore start - browser-only: atob path not available in Node tests */
+        }
+        else {
+            const binary = atob(padded);
+            bytes = new Uint8Array(binary.length);
+            for (let i = 0; i < binary.length; i++) {
+                bytes[i] = binary.charCodeAt(i);
+            }
+        }
+        /* c8 ignore stop */
+        return succeed(bytes);
+        /* c8 ignore next 3 - defensive: regex validation above prevents invalid chars from reaching here */
+    }
+    catch (_b) {
+        return fail(`multibaseBase64UrlDecode: malformed base64url body`);
+    }
+}
+/**
+ * Exports a public `CryptoKey` as a multibase base64url-encoded SPKI blob.
+ *
+ * The SPKI (SubjectPublicKeyInfo) format is the standard DER-encoded structure
+ * for public keys defined in RFC 5280, RFC 5480, and RFC 8410. It is
+ * algorithm-agnostic and suitable for storage and transmission.
+ *
+ * @param key - The `CryptoKey` to export. Must have `key.type === 'public'`.
+ * @param provider - The {@link CryptoUtils.ICryptoProvider} to use for the export operation.
+ * @returns `Success` with the multibase SPKI string, or `Failure` with error context.
+ * @public
+ */
+export async function exportPublicKeyAsMultibaseSpki(key, provider) {
+    return (await provider.exportPublicKeySpki(key))
+        .withErrorFormat((e) => `exportPublicKeyAsMultibaseSpki: ${e}`)
+        .onSuccess((buf) => succeed(multibaseBase64UrlEncode(buf)));
+}
+/**
+ * Imports a public key from a multibase base64url-encoded SPKI blob.
+ *
+ * Decodes the multibase prefix, decodes the base64url body, then uses
+ * the provider to import the key with the algorithm parameters from
+ * {@link CryptoUtils.keyPairAlgorithmParams}.
+ *
+ * @param encoded - A multibase SPKI string produced by {@link CryptoUtils.exportPublicKeyAsMultibaseSpki}.
+ * @param algorithm - The {@link CryptoUtils.KeyPairAlgorithm} the key was generated for.
+ * @param provider - The {@link CryptoUtils.ICryptoProvider} to use for the import operation.
+ * @returns `Success` with the imported public `CryptoKey`, or `Failure` with error context.
+ * @public
+ */
+export async function importPublicKeyFromMultibaseSpki(encoded, algorithm, provider) {
+    const decodeResult = multibaseBase64UrlDecode(encoded);
+    if (decodeResult.isFailure()) {
+        return fail(`importPublicKeyFromMultibaseSpki: ${decodeResult.message}`);
+    }
+    return (await provider.importPublicKeySpki(decodeResult.value, algorithm)).withErrorFormat((e) => `importPublicKeyFromMultibaseSpki: ${e}`);
+}
+//# sourceMappingURL=spkiHelpers.js.map

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

@@ -0,0 +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 } from './model';\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  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  const base64url = base64.replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '');\n  return 'm' + base64url;\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  const body = encoded.slice(1);\n  if (!/^[A-Za-z0-9_-]*$/.test(body) || body.length % 4 === 1) {\n    return fail(`multibaseBase64UrlDecode: malformed base64url body`);\n  }\n  // Convert base64url back to standard base64 and restore padding\n  const base64 = body.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: regex validation above prevents invalid chars from reaching here */\n  } catch {\n    return fail(`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<string>> {\n  return (await provider.exportPublicKeySpki(key))\n    .withErrorFormat((e) => `exportPublicKeyAsMultibaseSpki: ${e}`)\n    .onSuccess((buf) => succeed(multibaseBase64UrlEncode(buf)));\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 * @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"]}