@interop/minimal-cipher 7.0.0

package/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2019-2020, Digital Bazaar, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,220 @@
+# Minimal Cipher _(@interop/minimal-cipher)_
+
+Minimal encryption/decryption [JWE](https://tools.ietf.org/html/rfc7516)
+library, secure algs only, browser-compatible.
+
+## Table of Contents
+
+- [Security](#security)
+- [Background](#background)
+- [Install](#install)
+- [Usage](#usage)
+- [Contribute](#contribute)
+- [Commercial Support](#commercial-support)
+- [License](#license)
+
+## Security
+
+TBD
+
+## Background
+
+Every version of this library will only offer at most two algorithms for
+encryption/decryption: a recommended algorithm and a FIPS-compliant algorithm.
+The encryption API will expect the user to specify "recommended" or "fips" as
+the version of the algorithm to use, defaulting to "recommended".
+
+In the event that the FIPS-compliant algorithm is the same as the recommended
+one in a given version of this library, then that particular version will use
+the same algorithm regardless of the user specified "version".
+
+This version of the library will use "XChaCha20-Poly1305" as the "recommended"
+version and 256-bit "AES-GCM" as the FIPS-compliant version.
+
+Note: XSalsa20-Poly1305 is an AE (Authenticated Encryption) algorithm, not an
+AEAD (Authenticated Encryption and Associated Data) algorithm, making it
+incompatible with the current requirements for a
+[JWE (JOSE Web Encryption)](https://tools.ietf.org/html/rfc7516) `protected`
+clear text header.
+
+This library's API requires an interface for Key Encryption Key (KEKs). This
+enables key material that is protected from exfiltration to be used via HSM/SSM
+APIs, including Web KMS (TODO: citation needed).
+
+## Install
+
+This software requires and supports maintained recent versions of Node.js and
+browsers. Updates may remove support for older unmaintained platform versions.
+Please use dependency version lock files and testing to ensure compatibility
+with this software.
+
+To install from NPM:
+
+https://www.npmjs.com/package/@interop/minimal-cipher
+
+```sh
+npm install @interop/minimal-cipher
+```
+
+To install locally (for development):
+
+```sh
+git clone https://github.com/interop-alliance/minimal-cipher.git
+cd minimal-cipher
+pnpm install
+```
+
+This library is written in TypeScript and built with `tsc`. Common scripts:
+
+```sh
+pnpm run build         # type-check and build to dist/
+pnpm run lint          # lint src and test
+pnpm run test:node     # run the Node test suite (vitest)
+pnpm run test:browser  # run the browser smoke test (playwright)
+```
+
+## Usage
+
+Pick a Cipher interface (`recommended` or `fips`) and create an instance:
+
+```js
+import { Cipher } from '@interop/minimal-cipher'
+
+const cipher = new Cipher() // by default {version: 'recommended'}
+```
+
+### Encrypting
+
+To encrypt something (to create a cipher, serialized as a JWE JSON document),
+you will need:
+
+- Some data to encrypt (a string, an object, a stream)
+- Keys (called Key Agreement Keys, or KAKs for short)
+
+(You'll also need a `keyResolver`, more about that later.)
+
+First, assemble your Key Agreement public keys (you'll be encrypting with them,
+and the intended recipient will use the corresponding private keys to decrypt).
+
+Put together a list of `recipients` (essentially, you're listing the `id`s of
+public/private key pairs that will be used to encrypt/decrypt the message):
+
+```js
+// Retrieve them from config, a ledger, registry or back channel
+const keyAgreementKey = await fetchFromSomewhere()
+
+// or derive them from an existing Ed25519 signing key
+import { X25519KeyAgreementKey2020 } from '@digitalbazaar/x25519-key-agreement-key-2020'
+import { Ed25519VerificationKey2020 } from '@digitalbazaar/ed25519-verification-key-2020'
+const keyPair = await Ed25519VerificationKey2020.generate()
+
+const keyAgreementKey = X25519KeyPair.fromEd25519VerificationKey2020({
+  keyPair
+})
+// If the source key pair didn't have a controller set, don't forget to set one:
+keyAgreementKey.controller = did // The controller's DID
+keyAgreementKey.id = `${did}#${keyAgreementKey.fingerprint()}`
+
+// or derive them from an authentication key extracted from DID Document
+const didDoc = await veresDriver.get({ did })
+const authnKey = didDoc.getVerificationMethod({
+  proofPurpose: 'authentication'
+})
+const edKeyPair = await Ed25519VerificationKey2020.from(authnKey)
+const keyPair = X25519KeyPair.fromEd25519VerificationKey2020({ keyPair })
+
+const recipient = {
+  header: {
+    kid: keyAgreementKey.id,
+    alg: 'ECDH-ES+A256KW'
+  }
+}
+
+const recipients = [recipient]
+```
+
+You'll also need a `keyResolver`. Notice that `recipients` lists only key IDs,
+not the keys themselves. A `keyResolver` is a function that accepts a key ID and
+resolves to the public key corresponding to it.
+
+Some example resolvers:
+
+```js
+// Basic hardcoded key resolver; you already have the key material
+const publicKeyNode = {
+  '@context': 'https://w3id.org/security/suites/x25519-2020/v1',
+  id: keyAgreementKey.id,
+  type: 'X25519KeyAgreementKey2020',
+  publicKeyMultibase: keyAgreementKey.publicKeyMultibase
+}
+const keyResolver = async () => publicKeyNode
+```
+
+```js
+// A more advanced resolver based on DID doc authentication keys
+const keyResolver = async ({ id }) => {
+  // Use veres driver to fetch the authn key directly
+  const keyPair = await Ed25519VerificationKey2020.from(
+    await veresDriver.get({ did: id })
+  )
+  // Convert authn key to key agreement key
+  return X25519KeyPair.fromEd25519VerificationKey2020({ keyPair })
+}
+```
+
+```js
+// Using did-veres-one driver as a resolver for did:v1:nym: DID keys
+// TODO: Implement this
+```
+
+```js
+// Using the did:key method driver as a key resolver
+```
+
+Create the JWE:
+
+```js
+// To encrypt a string or a Uint8Array
+const data = 'plain text'
+const jweDoc = await cipher.encrypt({ data, recipients, keyResolver })
+
+// To encrypt an object
+const obj = { key: 'value' }
+const jweDoc = await cipher.encryptObject({ obj, recipients, keyResolver })
+```
+
+### Decrypting
+
+Decrypt a JWE JSON Document, using a private `keyAgreementKey`:
+
+```js
+const data = await cipher.decrypt({ jwe, keyAgreementKey })
+
+const object = await cipher.decryptObject({ jwe, keyAgreementKey })
+```
+
+TODO: Describe the required KEK API: // `id`, `algorithm`,
+`wrapKey({unwrappedKey})`, and `unwrapKey({wrappedKey})`
+
+## Contribute
+
+See
+[the contribute file](https://github.com/digitalbazaar/bedrock/blob/master/CONTRIBUTING.md)!
+
+PRs accepted.
+
+If editing the README, please conform to the
+[standard-readme](https://github.com/RichardLitt/standard-readme) specification.
+
+## Commercial Support
+
+Commercial support for this library is available upon request from Digital
+Bazaar: support@digitalbazaar.com
+
+## License
+
+[New BSD License (3-clause)](LICENSE) © Digital Bazaar
+
+[Streams API]: https://developer.mozilla.org/en-US/docs/Web/API/Streams_API
+[Web Crypto API]:
+  https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API

package/dist/Cipher.d.ts

@@ -0,0 +1,210 @@
+import { DecryptTransformer } from './DecryptTransformer.js';
+import { EncryptTransformer } from './EncryptTransformer.js';
+import type { CipherAlgorithm, EphemeralKeyPair, JWE, KeyAgreementAlgorithm, KeyAgreementKey, KeyResolver, Recipient } from './types.js';
+interface EncryptOptions {
+    data?: Uint8Array | string;
+    recipients: Recipient[];
+    keyResolver: KeyResolver;
+}
+interface EncryptObjectOptions {
+    obj: object;
+    recipients: Recipient[];
+    keyResolver: KeyResolver;
+}
+interface CreateEncryptOptions {
+    recipients: Recipient[];
+    keyResolver: KeyResolver;
+    chunkSize?: number;
+}
+export declare class Cipher {
+    version: string;
+    cipher: CipherAlgorithm;
+    keyAgreement: KeyAgreementAlgorithm;
+    /**
+     * Creates a new Cipher instance that can be used to encrypt or decrypt
+     * data. A version must be supplied for encrypting data; the version
+     * indicates whether a FIPS-compliant algorithm or the latest recommended
+     * algorithm will be used.
+     *
+     * @param {string} [version='recommended'] - `fips` to use a FIPS-compliant
+     *   algorithm, `recommended` to use the latest recommended algorithm when
+     *   encrypting.
+     *
+     * @returns {Cipher} A Cipher used to encrypt and decrypt data.
+     */
+    constructor({ version }?: {
+        version?: string;
+    });
+    /**
+     * Creates a TransformStream that will encrypt some data for one or more
+     * recipients and output a stream of chunks, each containing an object
+     * with the property `jwe` with a JWE value.
+     *
+     * A list of recipients must be given in the `recipients` array, identified
+     * by key agreement keys. An ephemeral ECDH key will be generated and used to
+     * derive shared KEKs that will wrap a randomly generated CEK. Each recipient
+     * in the `recipients` array will be updated to include the generated
+     * ephemeral ECDH key.
+     *
+     * @param {object} options - The options for the stream.
+     * @param {Array} options.recipients - An array of recipients for the
+     *   encrypted content.
+     * @param {Function} options.keyResolver - A function that returns a Promise
+     *   that resolves a key ID to a DH public key.
+     * @param {number} [options.chunkSize=1048576] - The size, in bytes,
+     *   of the chunks to break the incoming data into.
+     *
+     * @returns {Promise<TransformStream>} Resolves to a TransformStream.
+     */
+    createEncryptStream({ recipients, keyResolver, chunkSize }: CreateEncryptOptions): Promise<TransformStream>;
+    /**
+     * Creates a TransformStream that will decrypt one or more chunks, each one
+     * that is an object with a `jwe` property that has a JWE as a value. The
+     * stream will output chunks of Uint8Arrays consisting of the decrypted
+     * data from each chunk.
+     *
+     * The only JWEs currently supported use an `alg` of `ECDH-ES+A256KW` and
+     * `enc` of `A256GCM` or `XC20P`. These parameters refer to data that has been
+     * encrypted using a 256-bit AES-GCM or XChaCha20Poly1305 content encryption
+     * key (CEK) that has been wrapped using a 256-bit AES-KW key encryption key
+     * (KEK) generated via a shared secret between an ephemeral ECDH key and a
+     * static ECDH key (ECDH-ES).
+     *
+     * @param {object} options - Options for createDecryptStream.
+     * @param {object} options.keyAgreementKey - A key agreement key API with
+     *   `id` and deriveSecret`.
+     *
+     * @returns {Promise<TransformStream>} Resolves to the TransformStream.
+     */
+    createDecryptStream({ keyAgreementKey }: {
+        keyAgreementKey: KeyAgreementKey;
+    }): Promise<TransformStream>;
+    /**
+     * Encrypts some data for one or more recipients and outputs a JWE. The
+     * data to encrypt can be given as a Uint8Array or a string.
+     *
+     * A list of recipients must be given in the `recipients` array, identified
+     * by key agreement keys. An ephemeral ECDH key will be generated and used to
+     * derive shared KEKs that will wrap a randomly generated CEK. Each recipient
+     * in the `recipients` array will be updated to include the generated
+     * ephemeral ECDH key.
+     *
+     * @param {object} options - Options for encrypt.
+     * @param {Uint8Array|string} [options.data] - The data to encrypt.
+     * @param {Array} options.recipients - An array of recipients for the\
+     *   encrypted content.
+     * @param {Function} options.keyResolver - A function that returns a Promise
+     *   that resolves a key ID to a DH public key.
+     *
+     * @returns {Promise<object>} Resolves to a JWE.
+     */
+    encrypt({ data, recipients, keyResolver }: EncryptOptions): Promise<JWE>;
+    /**
+     * Encrypts an object. The object will be serialized to JSON and passed
+     * to `encrypt`. See `encrypt` for other parameters.
+     *
+     * @param {object} options - Options to use.
+     * @param {object} options.obj - The object to encrypt.
+     * @param {object} options.rest - The other options to be passed to encrypt.
+     *
+     * @returns {Promise<object>} Resolves to a JWE.
+     */
+    encryptObject({ obj, ...rest }: EncryptObjectOptions): Promise<JWE>;
+    /**
+     * Decrypts a single JWE.
+     *
+     * The only JWEs currently supported use an `alg` of `ECDH-ES+A256KW` and
+     * `enc` of `A256GCM` or `XC20P`. These parameters refer to data that has been
+     * encrypted using a 256-bit AES-GCM or XChaCha20Poly1305 content encryption
+     * key (CEK) that has been wrapped using a 256-bit AES-KW key encryption key
+     * (KEK) generated via a shared secret between an ephemeral ECDH key and a
+     * static ECDH key (ECDH-ES).
+     *
+     * Note: This version also supports decrypting data that was encrypted using
+     * `C20P` (ChaCha20Poly1305) for backwards compatibility.
+     *
+     * @param {object} options - Options for decrypt.
+     * @param {object} options.jwe - The JWE to decrypt.
+     * @param {object} options.keyAgreementKey - A key agreement key API with
+     *   `id` and `deriveSecret`.
+     *
+     * @returns {Promise<Uint8Array>} - Resolves to the decrypted data
+     *   or `null` if the decryption failed.
+     */
+    decrypt({ jwe, keyAgreementKey }: {
+        jwe: JWE;
+        keyAgreementKey: KeyAgreementKey;
+    }): Promise<Uint8Array | null>;
+    /**
+     * Decrypts a JWE that must contain an encrypted object. This method will
+     * call `decrypt` and then `JSON.parse` the resulting decrypted UTF-8 data.
+     *
+     * @param {object} options - Options.
+     * @param {object} options.jwe - The JWE to decrypt.
+     * @param {object} options.keyAgreementKey - A key agreement key API with
+     *   `id` and `deriveSecret`.
+     *
+     * @returns {Promise<object>} - Resolves to the decrypted object or `null`
+     *   if the decryption failed.
+     */
+    decryptObject({ jwe, keyAgreementKey }: {
+        jwe: JWE;
+        keyAgreementKey: KeyAgreementKey;
+    }): Promise<object | null>;
+    /**
+     * Creates an EncryptTransformer that can be used to encrypt one or more
+     * chunks of data.
+     *
+     * A list of recipients must be given in the `recipients` array, identified
+     * by key agreement keys. An ephemeral ECDH key will be generated and used to
+     * derive shared KEKs that will wrap a randomly generated CEK. Each recipient
+     * in the `recipients` array will be updated to include the generated
+     * ephemeral ECDH key.
+     *
+     * @param {object} options - Options for the transformer.
+     * @param {Array} options.recipients - An array of recipients for the
+     *   encrypted content.
+     * @param {Function} options.keyResolver - A function that returns
+     *   a Promise that resolves a key ID to a DH public key.
+     * @param {number} [options.chunkSize=1048576] - The size, in bytes, of the
+     *   chunks to break the incoming data into (only applies if returning a
+     *   stream).
+     *
+     * @returns {Promise<EncryptTransformer>} - Resolves to an EncryptTransformer.
+     */
+    createEncryptTransformer({ recipients, keyResolver, chunkSize }: CreateEncryptOptions): Promise<EncryptTransformer>;
+    /**
+     * Creates a DecryptTransformer.
+     *
+     * @param {object} options - Options to use.
+     * @param {object} options.keyAgreementKey - A key agreement key API with
+     *   `id` and `deriveSecret`.
+     *
+     * @returns {Promise<DecryptTransformer>} - Resolves to a DecryptTransformer.
+     */
+    createDecryptTransformer({ keyAgreementKey }: {
+        keyAgreementKey: KeyAgreementKey;
+    }): Promise<DecryptTransformer>;
+    /**
+     * Creates a JWE recipient using the given inputs.
+     *
+     * @see https://tools.ietf.org/html/rfc7516#section-4
+     *
+     * @param {object} options - Options to use.
+     * @param {object} options.recipient - A recipient with a header with a
+     *   kid and alg.
+     * @param {object} options.ephemeralKeyPair - An ephemeral key pair.
+     * @param {object} options.cek - A content encryption key.
+     * @param {Function} options.keyResolver - A function that can resolve keys.
+     *
+     * @returns {Promise<object>} A JWE recipient object.
+     */
+    _createRecipient({ recipient, ephemeralKeyPair, cek, keyResolver }: {
+        recipient: Recipient;
+        ephemeralKeyPair: EphemeralKeyPair;
+        cek: Uint8Array;
+        keyResolver: KeyResolver;
+    }): Promise<Recipient>;
+}
+export {};
+//# sourceMappingURL=Cipher.d.ts.map

package/dist/Cipher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cipher.d.ts","sourceRoot":"","sources":["../src/Cipher.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAE5D,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAChB,GAAG,EACH,qBAAqB,EACrB,eAAe,EACf,WAAW,EACX,SAAS,EACV,MAAM,YAAY,CAAA;AAInB,UAAU,cAAc;IACtB,IAAI,CAAC,EAAE,UAAU,GAAG,MAAM,CAAA;IAC1B,UAAU,EAAE,SAAS,EAAE,CAAA;IACvB,WAAW,EAAE,WAAW,CAAA;CACzB;AAED,UAAU,oBAAoB;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,SAAS,EAAE,CAAA;IACvB,WAAW,EAAE,WAAW,CAAA;CACzB;AAED,UAAU,oBAAoB;IAC5B,UAAU,EAAE,SAAS,EAAE,CAAA;IACvB,WAAW,EAAE,WAAW,CAAA;IACxB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,qBAAa,MAAM;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,eAAe,CAAA;IACvB,YAAY,EAAE,qBAAqB,CAAA;IAEnC;;;;;;;;;;;OAWG;gBACS,EAAE,OAAuB,EAAE,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO;IAiBlE;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,mBAAmB,CAAC,EACxB,UAAU,EACV,WAAW,EACX,SAAS,EACV,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC;IASlD;;;;;;;;;;;;;;;;;;OAkBG;IACG,mBAAmB,CAAC,EACxB,eAAe,EAChB,EAAE;QACD,eAAe,EAAE,eAAe,CAAA;KACjC,GAAG,OAAO,CAAC,eAAe,CAAC;IAK5B;;;;;;;;;;;;;;;;;;OAkBG;IACG,OAAO,CAAC,EACZ,IAAI,EACJ,UAAU,EACV,WAAW,EACZ,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC;IAehC;;;;;;;;;OASG;IACG,aAAa,CAAC,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,EAAE,oBAAoB,GAAG,OAAO,CAAC,GAAG,CAAC;IAOzE;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,OAAO,CAAC,EACZ,GAAG,EACH,eAAe,EAChB,EAAE;QACD,GAAG,EAAE,GAAG,CAAA;QACR,eAAe,EAAE,eAAe,CAAA;KACjC,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAK9B;;;;;;;;;;;OAWG;IACG,aAAa,CAAC,EAClB,GAAG,EACH,eAAe,EAChB,EAAE;QACD,GAAG,EAAE,GAAG,CAAA;QACR,eAAe,EAAE,eAAe,CAAA;KACjC,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAS1B;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,wBAAwB,CAAC,EAC7B,UAAU,EACV,WAAW,EACX,SAAS,EACV,EAAE,oBAAoB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA4CrD;;;;;;;;OAQG;IACG,wBAAwB,CAAC,EAC7B,eAAe,EAChB,EAAE;QACD,eAAe,EAAE,eAAe,CAAA;KACjC,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAO/B;;;;;;;;;;;;;OAaG;IACG,gBAAgB,CAAC,EACrB,SAAS,EACT,gBAAgB,EAChB,GAAG,EACH,WAAW,EACZ,EAAE;QACD,SAAS,EAAE,SAAS,CAAA;QACpB,gBAAgB,EAAE,gBAAgB,CAAA;QAClC,GAAG,EAAE,UAAU,CAAA;QACf,WAAW,EAAE,WAAW,CAAA;KACzB,GAAG,OAAO,CAAC,SAAS,CAAC;CAwCvB"}