@bedrock/record-cipher 1.0.0

package/LICENSE.md

@@ -0,0 +1,115 @@
+Bedrock Non-Commercial License v1.0
+===================================
+
+Copyright (c) 2011-2016 Digital Bazaar, Inc.
+All rights reserved.
+
+Summary
+=======
+
+This license allows the licensee to use Bedrock and its software modules
+for non-commercial purposes such as self-study, research, personal
+projects, or for evaluation purposes. If the licensee uses Bedrock
+directly or indirectly to generate revenue, or to provide products or
+services to more than 500 people (users), the licensee must immediately
+obtain a non-profit or commercial license.
+
+Examples
+========
+
+These are examples of cases that are allowed by this license:
+
+* The licensee is an individual that creates Bedrock-dependent software for
+  personal use only.
+* The licensee is an individual or group of students/researchers that uses
+  Bedrock to experiment with an idea for a non-commercial project.
+* The licensee is a startup company that prototypes a Bedrock-dependent
+  product before they have cash flow and will be testing the prototype
+  software with less than 500 users. The service will not generate revenue
+  of any kind.
+* The licensee is a for-profit organization that creates a product or
+  service that is used by less than 500 users and is built with or
+  integrates with Bedrock. The service must be exclusively provided for free
+  and no parent, subsidiary, agent, or affiliate organization may profit
+  from its use.
+
+These cases require a non-profit or commercial license:
+
+* The licensee is a non-profit that receives funding to create and/or run a
+  Bedrock-dependent service.
+* The licensee is a startup company with Bedrock-dependent software that is
+  funded by another organization.
+* The licensee is a startup company that is going into production with
+  Bedrock-dependent software.
+* The licensee has more than 500 users using a Bedrock-dependent service
+  either directly or indirectly.
+* The licensee is a medium to large organization that builds or integrates a
+  commercial product or service with Bedrock.
+
+THE LICENSE
+===========
+
+This section and all subsequent sections of this document constitute the
+agreement between the licensee and Digital Bazaar, Inc.
+
+DEFINITIONS
+===========
+
+* Product - The Bedrock software and any modules associated with Bedrock
+where Digital Bazaar, Inc. owns the copyright.
+
+CONDITIONS
+==========
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted for NON-COMMERCIAL PURPOSES as long as the
+following conditions are met:
+
+1. Any use of the Product must not generate revenue for the licensee or
+   any parent, subsidiary, agent, or affiliate of the licensee. Use of
+   Product includes, but is not limited to, interacting with any of the
+   licensee's Product-dependent products or services over a network.
+
+2. The aggregate number of individual people (users) of the licensee's
+   products or services that use Product must be less than 500.
+
+3. Redistributions of source code must retain the above copyright notice
+   intact, this list of conditions and the following disclaimer.
+
+4. Redistributions in binary form must reproduce the above copyright
+   notice, this license and the following disclaimer in the documentation and
+   on a web page available via interactive use and/or other materials
+   provided with the distribution.
+
+5. Neither the name of the copyright holder, the names of its
+   contributors, nor any trademarks held by the copyright holder may be used
+   to endorse or promote products or services built using the Product without
+   specific prior written permission.
+
+6. Any modifications are clearly outlined in release documentation and are
+   specifically mentioned as not being a part of an official Product release.
+   No additional restrictions to this license may be made when distributing
+   modifications.
+
+7. For the avoidance of doubt, this license prohibits sublicensing of the
+   Product.
+
+8. Any breach of this license by licensee must be resolved within 30 days.
+   Failure to do so results in the termination of this license.
+
+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.
+
+To obtain a non-profit or commercial license for Product, please contact
+Digital Bazaar, Inc. at the following email address:
+
+Digital Bazaar <support@digitalbazaar.com>

package/README.md

@@ -0,0 +1,3 @@
+# bedrock-record-cipher
+
+Record ciphering for Bedrock Applications

package/lib/RecordCipher.js

@@ -0,0 +1,309 @@
+/*!
+ * Copyright (c) 2019-2026 Digital Bazaar, Inc.
+ */
+import * as bedrock from '@bedrock/core';
+import {decode, encode} from 'cborg';
+import {generalDecrypt, GeneralEncrypt} from 'jose';
+
+const {util: {BedrockError}} = bedrock;
+
+const TEXT_ENCODER = new TextEncoder();
+const TEXT_DECODER = new TextDecoder();
+
+/* Multikey registry IDs and encoded header values
+aes-256 | 0xa2 | 256-bit AES symmetric key
+*/
+const SUPPORTED_KEK_TYPES = new Map([
+  ['aes-256', {header: new Uint8Array([0xa2, 0x01]), size: 32}]
+]);
+
+export class RecordCipher {
+  constructor({currentKekId, keks, encoding} = {}) {
+    this.keks = keks;
+    this.encoding = encoding;
+    this.setCurrentKek({id: currentKekId});
+  }
+
+  /**
+   * Decrypts `encryptedSecrets`, if found, in a record.
+   *
+   * @param {object} options - The options to use.
+   * @param {object} options.record - The record with optional
+   *   `encryptedSecrets` to decrypt.
+   *
+   * @returns {Promise<object>} An object with `secrets` instead of
+   *   `encryptedSecrets`.
+   */
+  async decryptRecordSecrets({record} = {}) {
+    if(record.encryptedSecrets === undefined) {
+      // nothing to decrypt, return early
+      return record;
+    }
+
+    try {
+      // decrypt secrets
+      const {encryptedSecrets, ...rest} = record;
+      const {kekId, jwe, encoding = this.encoding} = encryptedSecrets;
+      const secretKey = await this.getKek({id: kekId});
+      const {plaintext} = await generalDecrypt(jwe, secretKey);
+      const secrets = encoding === 'cbor' ?
+        _cborDecodeSecrets(plaintext) : _jsonDecodeSecrets(plaintext);
+
+      // new record object w/decrypted secrets
+      return {...rest, secrets};
+    } catch(cause) {
+      throw new BedrockError('Could not decrypt record secrets.', {
+        name: 'OperationError',
+        cause,
+        details: {
+          public: true,
+          httpStatusCode: 500
+        }
+      });
+    }
+  }
+
+  /**
+   * Encrypts `secrets`, if found, in a record.
+   *
+   * @param {object} options - The options to use.
+   * @param {object} options.record - The record with optional `secrets` to
+   *   encrypt.
+   *
+   * @returns {Promise<object>} An object with `encryptedSecrets` instead of
+   *   `secrets`.
+   */
+  async encryptRecordSecrets({record} = {}) {
+    if(record.encryptedSecrets !== undefined) {
+      // should not happen; bad call
+      throw new Error(
+        'Could not encrypt record secrets; secrets already encrypted.');
+    }
+
+    try {
+      // get current wrap key ID
+      const {currentKekId: kekId, encoding} = this;
+      if(!kekId) {
+        // no KEK config; return early
+        return record;
+      }
+
+      // encrypt secrets
+      const {secrets, ...nonSecrets} = record;
+      const plaintext = encoding === 'cbor' ?
+        _cborEncodeSecrets(secrets) : _jsonEncodeSecrets(secrets);
+      const secretKey = await this.getKek({id: kekId});
+      const jwe = await new GeneralEncrypt(plaintext)
+        .setProtectedHeader({enc: 'A256GCM'})
+        .addRecipient(secretKey)
+        .setUnprotectedHeader({alg: 'A256KW', kid: kekId})
+        .encrypt();
+
+      // return new record w/encrypted secrets
+      return {
+        ...nonSecrets,
+        encryptedSecrets: {kekId, jwe, encoding}
+      };
+    } catch(cause) {
+      throw new BedrockError('Could not encrypt record secrets.', {
+        name: 'OperationError',
+        cause,
+        details: {
+          public: true,
+          httpStatusCode: 500
+        }
+      });
+    }
+  }
+
+  addKek({id, secretKey, secretKeyMultibase} = {}) {
+    if(this.keks.has(id)) {
+      throw new BedrockError(`Key encryption key "${id}" already set.`, {
+        name: 'ConstraintsError',
+        details: {
+          public: true,
+          httpStatusCode: 409
+        }
+      });
+    }
+    if(secretKey) {
+      this.keks.set(id, secretKey);
+    } else {
+      this.keks.set(id, _loadKek(secretKeyMultibase));
+    }
+  }
+
+  async getKek({id} = {}) {
+    const secretKey = this.keks.get(id);
+    if(secretKey) {
+      return secretKey;
+    }
+    throw new BedrockError(`Key encryption key "${id}" not found.`, {
+      name: 'NotFoundError',
+      details: {
+        public: true,
+        httpStatusCode: 400
+      }
+    });
+  }
+
+  isSecretsEncryptionEnabled() {
+    return this.currentKekId !== null;
+  }
+
+  setCurrentKek({id} = {}) {
+    if(id !== null) {
+      // ensure secret key exists
+      if(!this.keks.has(id)) {
+        throw new BedrockError(`Key encryption key "${id}" not found.`, {
+          name: 'NotFoundError',
+          details: {
+            public: true,
+            httpStatusCode: 400
+          }
+        });
+      }
+    }
+    this.currentKekId = id;
+  }
+
+  /**
+   * Creates a `RecordCipher` instance for encrypting and/or decrypting
+   * record `secrets`. The default encoding mode for the `secrets` is `cbor`,
+   * which supports any binary subfields present in `secrets`. The encoding
+   * can alternatively be set to `json` for backwards compatiblity with
+   * modules that previously encoded using JSON, not CBOR.
+   *
+   * @param {object} options - The options to use.
+   * @param {string} [options.currentKekId] - The ID of the KEK to use for
+   *   new encryptions; may be set to `null` to disable encryption; if not
+   *   set, it will be automatically set to the first KEK ID in the `keks`
+   *   array if it is not empty (otherwise it will be set to `null`).
+   * @param {Array} [options.keks=[]] - An array of objects, each with an `id`
+   *   `id` value for a KEK to use for encryption and decryption as well as its
+   *   `secretKeyMultibase` including a base64url-encoded AES-256 key value.
+   * @param {string} [options.encoding='cbor'] - The encoding to use for the
+   *   values found in `secrets`; either `cbor` or `json`, `cbor` supports
+   *   binary values and `json` does not and is only provided for backwards
+   *   compatibility and should not be used with new applications).
+   *
+   * @returns {Promise<RecordCipher>} A new RecordCipher instance based on
+   *   the given options; if `currentKekId` is specified as `null` then this
+   *   instance will return `false` from `isSecretsEncryptionEnabled()`.
+   */
+  static async create({currentKekId, keks = [], encoding = 'cbor'} = {}) {
+    if(!(currentKekId === undefined || currentKekId === null ||
+      typeof currentKekId !== 'string')) {
+      throw new TypeError('"currentKekId" must be a string or null.');
+    }
+    if(!Array.isArray(keks)) {
+      throw new TypeError('"keks" must be an array.');
+    }
+    if(!(encoding === 'cbor' || encoding === 'json')) {
+      throw new Error('"encoding" must be "cbor" or "json".');
+    }
+
+    const recordCipher = new RecordCipher({
+      currentKekId: null, keks: new Map(), encoding
+    });
+
+    // add all KEKs in `keks`
+    let firstId;
+    for(const key of keks) {
+      if(!(key.id && typeof key.id === 'string')) {
+        throw new BedrockError(
+          'Invalid key encryption key configuration; ' +
+          'key "id" must be a string.', {
+            name: 'DataError',
+            details: {
+              public: true,
+              httpStatusCode: 400
+            }
+          });
+      }
+      if(firstId === undefined) {
+        firstId = key.id;
+      }
+      recordCipher.addKek(key);
+    }
+
+    if(currentKekId !== null) {
+      recordCipher.setCurrentKek({id: currentKekId ?? firstId ?? null});
+    }
+
+    return recordCipher;
+  }
+}
+
+function _cborDecodeSecrets(plaintext) {
+  const decoded = decode(plaintext);
+  // convert Uint8Arrays to Buffers for compatibility
+  for(const [key, value] of Object.entries(decoded)) {
+    decoded[key] = value instanceof Uint8Array ? Buffer.from(value) : value;
+  }
+  return decoded;
+}
+
+function _cborEncodeSecrets(secrets) {
+  return encode(secrets);
+}
+
+function _jsonDecodeSecrets(plaintext) {
+  return JSON.parse(TEXT_DECODER.decode(plaintext));
+}
+
+function _jsonEncodeSecrets(secrets) {
+  const obj = secrets instanceof Map ?
+    Object.fromEntries(secrets.entries()) : secrets;
+  return TEXT_ENCODER.encode(JSON.stringify(obj));
+}
+
+function _loadKek(secretKeyMultibase) {
+  if(!secretKeyMultibase?.startsWith('u')) {
+    throw new BedrockError(
+      'Unsupported multibase header; ' +
+      '"u" for base64url-encoding must be used.', {
+        name: 'NotSupportedError',
+        details: {
+          public: true,
+          httpStatusCode: 400
+        }
+      });
+  }
+
+  // check multikey header
+  let keyType;
+  let secretKey;
+  const multikey = Buffer.from(secretKeyMultibase.slice(1), 'base64url');
+  for(const [type, {header, size}] of SUPPORTED_KEK_TYPES) {
+    if(multikey[0] === header[0] && multikey[1] === header[1]) {
+      keyType = type;
+      if(multikey.length !== (2 + size)) {
+        // intentionally do not report what was detected because a
+        // misconfigured secret could have its first two bytes revealed
+        throw new BedrockError(
+          'Incorrect multikey size or invalid multikey header.', {
+            name: 'DataError',
+            details: {
+              public: true,
+              httpStatusCode: 400
+            }
+          });
+      }
+      secretKey = multikey.subarray(2);
+      break;
+    }
+  }
+  if(keyType === undefined) {
+    throw new BedrockError(
+      'Unsupported multikey type; only AES-256 is supported.', {
+        name: 'NotSupportedError',
+        details: {
+          public: true,
+          httpStatusCode: 400
+        }
+      });
+  }
+
+  return secretKey;
+}

package/lib/index.js

@@ -0,0 +1,4 @@
+/*!
+ * Copyright (c) 2019-2026 Digital Bazaar, Inc.
+ */
+export {RecordCipher} from './RecordCipher.js';

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@bedrock/record-cipher",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Bedrock Record Cipher",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "main": "./lib/index.js",
+  "files": [
+    "lib/**/*.js"
+  ],
+  "scripts": {
+    "lint": "eslint ."
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/digitalbazaar/bedrock-record-cipher"
+  },
+  "author": {
+    "name": "Digital Bazaar, Inc.",
+    "email": "support@digitalbazaar.com",
+    "url": "https://digitalbazaar.com"
+  },
+  "bugs": {
+    "url": "https://github.com/digitalbazaar/bedrock-record-cipher/issues"
+  },
+  "homepage": "https://github.com/digitalbazaar/bedrock-record-cipher",
+  "dependencies": {
+    "cborg": "^5.0.1",
+    "jose": "^6.2.2"
+  },
+  "peerDependencies": {
+    "@bedrock/core": "^6.3.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "eslint": "^8.57.1",
+    "eslint-config-digitalbazaar": "^5.2.0",
+    "eslint-plugin-jsdoc": "^50.6.3",
+    "eslint-plugin-unicorn": "^56.0.1",
+    "jsdoc": "^4.0.4",
+    "jsdoc-to-markdown": "^9.1.1"
+  }
+}