@interop/http-digest-header 2.3.2

package/LICENSE.md

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2019-2025, 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,93 @@
+# HTTP Digest Header Library _(@interop/http-digest-header)_
+
+[![Node.js CI](https://github.com/interop-alliance/http-digest-header/actions/workflows/main.yml/badge.svg)](https://github.com/interop-alliance/http-digest-header/actions/workflows/main.yml)
+
+> JavaScript library (Node.js, browser and React Native) for creating and verifying Digest headers for HTTP Signatures
+
+## Table of Contents
+
+- [Background](#background)
+- [Install](#install)
+- [Usage](#usage)
+- [Contribute](#contribute)
+- [Commercial Support](#commercial-support)
+- [License](#license)
+
+## Background
+
+**FORKED FROM**: https://github.com/digitalbazaar/http-digest-header to provide
+support for React Native, and add TypeScript types.
+
+* For React Native use: Peer dependency `crypto-expo` is required. 
+
+Originally, this library was implemented based on the `Digest` header as
+mentioned in **[HTTP Signatures IETF draft](https://tools.ietf.org/html/draft-cavage-http-signatures)**.
+
+Since then, the `Digest` header got its own standards-track spec, at
+https://tools.ietf.org/html/draft-ietf-httpbis-digest-headers.
+
+This is a library specifically for creating and verifying the `Digest:` header,
+for use with HTTP Signatures and similar mechanisms.
+
+It's intended to be isomorphic (for use both in the browser and server-side,
+with Node.js).
+
+## Install
+
+- Browsers and Node.js 22+ supported.
+- [Web Crypto API][] required. Older browsers and Node.js 14 must use a
+  polyfill.
+
+To install from `npm`:
+
+```
+npm install @interop/http-digest-header
+```
+
+To install locally (for development):
+
+```
+git clone https://github.com/interop-alliance/http-digest-header.git
+cd http-digest-header
+npm install
+```
+
+## Usage
+
+```js
+import * as httpDigest from '@interop/http-digest-header';
+
+const data = `{"hello": "world"}`;
+
+const headerValue = await httpDigest.
+    createHeaderValue({data, algorithm: 'sha256', useMultihash: false});
+// -> SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
+
+const dataToVerify1 = `{"hello": "world"}`;
+const dataToVerify2 = `{"hello": "planet earth"}`;
+
+const verifyResult = await httpDigest.verifyHeaderValue({data: dataToVerify1, headerValue});
+// -> { verified: true }
+const verifyResult = await httpDigest.verifyHeaderValue({data: dataToVerify2, headerValue});
+// -> { verified: false }
+```
+
+## Contribute
+
+Please follow the existing code style.
+
+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
+
+[BSD-3-Clause](LICENSE.md) © 2019-2025 Digital Bazaar
+
+[Web Crypto API]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API

package/lib/digest-reactnative.js

@@ -0,0 +1,9 @@
+/*!
+ * Copyright (c) 2021-2025 Digital Bazaar, Inc. All rights reserved.
+ */
+import * as Crypto from 'expo-crypto';
+
+export async function sha256(data) {
+  return new Uint8Array(
+    await Crypto.digest(Crypto.CryptoDigestAlgorithm.SHA256, data));
+}

package/lib/digest.js

@@ -0,0 +1,8 @@
+/*!
+ * Copyright (c) 2021-2025 Digital Bazaar, Inc. All rights reserved.
+ */
+const {crypto} = globalThis;
+
+export async function sha256(data) {
+  return new Uint8Array(await crypto.subtle.digest({name: 'SHA-256'}, data));
+}

package/lib/httpDigest.js

@@ -0,0 +1,127 @@
+/*!
+ * Copyright (c) 2019-2025 Digital Bazaar, Inc. All rights reserved.
+ */
+import {base64Encode, base64urlEncode} from './util.js';
+import {sha256} from './digest.js';
+
+/**
+ * Creates a value suitable for the HTTP `Digest` header.
+ *
+ * @param {object} options - The options to use.
+ * @param {string|object|Blob|Uint8Array} [options.data] - The data to be
+ *   hashed (a request or response body).
+ * @param {string} [options.algorithm] - Hash algorithm to use.
+ *   (e.g. 'sha256').
+ * @param {boolean} [options.useMultihash=true] - Whether to encode via
+ *   multihash; if false, the hash will be base64-encoded (non-url).
+ *
+ * @returns {Promise<string>} Resolves to `Digest` header value.
+ */
+export async function createHeaderValue({
+  data, algorithm = 'sha256', useMultihash = true
+} = {}) {
+  const {key, encodedDigest} = await _createHeaderValueComponents({
+    data, algorithm, useMultihash
+  });
+  return `${key}=${encodedDigest}`;
+}
+
+/**
+ * Verifies the HTTP `Digest` header value against the given HTTP body `data`.
+ *
+ * @param {object} options - The options to use.
+ * @param {string|object|Blob|Uint8Array} options.data - The data to be
+ *   verified (a request or response body).
+ * @param {string} options.headerValue - The digest header value to verify
+ *   the data against.
+ *
+ * @returns {Promise<{verified: boolean, error?: Error}>}
+ */
+export async function verifyHeaderValue({data, headerValue}) {
+  try {
+    const {key, algorithm, encodedDigest} = _parseHeaderValue(headerValue);
+    const {encodedDigest: expectedDigest} = await _createHeaderValueComponents({
+      data, algorithm, useMultihash: key === 'mh'
+    });
+    return {verified: encodedDigest === expectedDigest};
+  } catch(error) {
+    return {verified: false, error};
+  }
+}
+
+async function _createHeaderValueComponents({
+  data, algorithm = 'sha256', useMultihash = true
+}) {
+  if(algorithm !== 'sha256') {
+    throw new Error(`Algorithm "${algorithm}" is not supported.`);
+  }
+  const digest = await _getDigest({data, algorithm});
+  if(useMultihash) {
+    return {key: 'mh', encodedDigest: _createMultihash({digest})};
+  }
+  return {key: 'SHA-256', encodedDigest: base64Encode(digest)};
+}
+
+function _createMultihash({digest}) {
+  // format as multihash digest
+  // sha2-256: 0x12, length: 32 (0x20), digest value
+  const mh = new Uint8Array(34);
+  mh[0] = 0x12;
+  mh[1] = 0x20;
+  mh.set(digest, 2);
+  // encode multihash using multibase, base64url: `u`
+  return `u${base64urlEncode(mh)}`;
+}
+
+function _parseHeaderValue(headerValue) {
+  const [key, digestValue] = headerValue.split(/=(.+)/);
+
+  let encodedDigest;
+  let algorithm;
+  if(key === 'mh') {
+    encodedDigest = digestValue;
+
+    // if `encodedDigest` starts with `uEi`, then it is a base64url-encoded
+    // sha-256 multihash
+    if(encodedDigest.startsWith('uEi')) {
+      algorithm = 'sha256';
+    } else {
+      throw new Error(
+        `Only base64url-encoded, sha-256 multihash is supported.`);
+    }
+  } else {
+    // per RFC 9651, the digest value could be a structured field value,
+    // expressed as a base64-encoded byte array wrapped in colons
+    encodedDigest = digestValue?.replace(/^:(.*):$/, '$1');
+
+    algorithm = key.replace('-', '').toLowerCase();
+    if(algorithm !== 'sha256') {
+      throw new Error(`Algorithm "${algorithm}" is not supported.`);
+    }
+  }
+  return {key, algorithm, encodedDigest};
+}
+
+async function _getDigest({data, algorithm}) {
+  data = await _normalizeData(data);
+  if(algorithm === 'sha256') {
+    return sha256(data);
+  }
+  throw new Error(`Algorithm "${algorithm}" is not unsupported.`);
+}
+
+// normalize all inputs to a `Uint8Array` for hashing
+async function _normalizeData(data) {
+  if(data instanceof Uint8Array) {
+    return data;
+  }
+  if(data instanceof Blob) {
+    // `Blob.bytes()` is only available in node.js 22+;
+    // fallback to `Blob.arrayBuffer()`
+    return data?.bytes?.() ?? data.arrayBuffer();
+  }
+  if(typeof data !== 'string') {
+    data = JSON.stringify(data);
+  }
+  return (new TextEncoder()).encode(data);
+}

package/lib/index.js

@@ -0,0 +1,4 @@
+/*!
+ * Copyright (c) 2019-2020 Digital Bazaar, Inc. All rights reserved.
+ */
+export {createHeaderValue, verifyHeaderValue} from './httpDigest.js';

package/lib/util-browser.js

@@ -0,0 +1,19 @@
+/*!
+ * Copyright (c) 2021-2025 Digital Bazaar, Inc. All rights reserved.
+ */
+export function base64Encode(bytes) {
+  if(bytes.toBase64) {
+    return bytes.toBase64();
+  }
+  return btoa(Array.from(bytes, b => String.fromCodePoint(b)).join(''));
+}
+
+export function base64urlEncode(bytes) {
+  if(bytes.toBase64) {
+    return bytes.toBase64({alphabet: 'base64url', omitPadding: true});
+  }
+  return base64Encode(bytes)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replaceAll('=', '');
+}

package/lib/util.js

@@ -0,0 +1,12 @@
+/*!
+ * Copyright (c) 2021-2025 Digital Bazaar, Inc. All rights reserved.
+ */
+export function base64Encode(bytes) {
+  return Buffer.from(bytes.buffer, bytes.offset, bytes.length)
+    .toString('base64');
+}
+
+export function base64urlEncode(bytes) {
+  return Buffer.from(bytes.buffer, bytes.offset, bytes.length)
+    .toString('base64url');
+}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@interop/http-digest-header",
+  "version": "2.3.2",
+  "description": "Minimal isomorphic library (Node.js and browser) for creating and verifying Digest headers for HTTP Signatures",
+  "license": "BSD-3-Clause",
+  "scripts": {
+    "test": "npm run test-node",
+    "test-node": "cross-env NODE_ENV=test mocha --preserve-symlinks -t 10000 --require test/test-mocha.js test/**/*.spec.js",
+    "test-karma": "karma start test/karma.conf.cjs",
+    "coverage": "cross-env NODE_ENV=test c8 npm test",
+    "coverage-ci": "cross-env NODE_ENV=test c8 --reporter=lcovonly --reporter=text-summary --reporter=text npm test",
+    "coverage-report": "c8 report",
+    "build": "tsc",
+    "lint": "eslint ."
+  },
+  "type": "module",
+  "exports": "./lib/index.js",
+  "types": "./types/index.d.ts",
+  "browser": {
+    "./lib/util.js": "./lib/util-browser.js"
+  },
+  "react-native": {
+    "./lib/util.js": "./lib/util-browser.js",
+    "./lib/digest.js": "./lib/digest-reactnative.js"
+  },
+  "files": [
+    "lib/**/*.js",
+    "types/**/*.d.ts"
+  ],
+  "peerDependencies": {
+    "expo-crypto": ">=13"
+  },
+  "peerDependenciesMeta": {
+    "expo-crypto": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "c8": "^10.1.3",
+    "chai": "^4.3.6",
+    "cross-env": "^10.1.0",
+    "eslint": "^8.57.1",
+    "eslint-config-digitalbazaar": "^5.2.0",
+    "eslint-plugin-jsdoc": "^50.8.0",
+    "eslint-plugin-unicorn": "^56.0.1",
+    "karma": "^6.3.20",
+    "karma-chai": "^0.1.0",
+    "karma-chrome-launcher": "^3.1.1",
+    "karma-mocha": "^2.0.1",
+    "karma-mocha-reporter": "^2.2.5",
+    "karma-sourcemap-loader": "^0.3.8",
+    "karma-webpack": "^5.0.0",
+    "mocha": "^11.7.4",
+    "mocha-lcov-reporter": "^1.3.0",
+    "typescript": "^6.0.3",
+    "webpack": "^5.73.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/interop-alliance/http-digest-header"
+  },
+  "keywords": [
+    "http",
+    "signatures",
+    "digest"
+  ],
+  "author": {
+    "name": "Digital Bazaar, Inc.",
+    "email": "support@digitalbazaar.com",
+    "url": "https://digitalbazaar.com/"
+  },
+  "bugs": {
+    "url": "https://github.com/digitalbazaar/http-digest-header/issues"
+  },
+  "homepage": "https://github.com/digitalbazaar/http-digest-header",
+  "engines": {
+    "node": ">=20"
+  },
+  "c8": {
+    "reporter": [
+      "lcov",
+      "text-summary",
+      "text"
+    ]
+  }
+}

package/types/httpDigest.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Creates a value suitable for the HTTP `Digest` header.
+ *
+ * @param {object} options - The options to use.
+ * @param {string|object|Blob|Uint8Array} [options.data] - The data to be
+ *   hashed (a request or response body).
+ * @param {string} [options.algorithm] - Hash algorithm to use.
+ *   (e.g. 'sha256').
+ * @param {boolean} [options.useMultihash=true] - Whether to encode via
+ *   multihash; if false, the hash will be base64-encoded (non-url).
+ *
+ * @returns {Promise<string>} Resolves to `Digest` header value.
+ */
+export function createHeaderValue({ data, algorithm, useMultihash }?: {
+    data?: string | object | Blob | Uint8Array;
+    algorithm?: string;
+    useMultihash?: boolean;
+}): Promise<string>;
+/**
+ * Verifies the HTTP `Digest` header value against the given HTTP body `data`.
+ *
+ * @param {object} options - The options to use.
+ * @param {string|object|Blob|Uint8Array} options.data - The data to be
+ *   verified (a request or response body).
+ * @param {string} options.headerValue - The digest header value to verify
+ *   the data against.
+ *
+ * @returns {Promise<{verified: boolean, error?: Error}>}
+ */
+export function verifyHeaderValue({ data, headerValue }: {
+    data: string | object | Blob | Uint8Array;
+    headerValue: string;
+}): Promise<{
+    verified: boolean;
+    error?: Error;
+}>;

package/types/index.d.ts

@@ -0,0 +1 @@
+export { createHeaderValue, verifyHeaderValue } from "./httpDigest.js";

package/types/lib/httpDigest.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Creates a value suitable for the HTTP `Digest` header.
+ *
+ * @param {object} options - The options to use.
+ * @param {string|object|Blob|Uint8Array} [options.data] - The data to be
+ *   hashed (a request or response body).
+ * @param {string} [options.algorithm] - Hash algorithm to use.
+ *   (e.g. 'sha256').
+ * @param {boolean} [options.useMultihash=true] - Whether to encode via
+ *   multihash; if false, the hash will be base64-encoded (non-url).
+ *
+ * @returns {Promise<string>} Resolves to `Digest` header value.
+ */
+export function createHeaderValue({ data, algorithm, useMultihash }?: {
+    data?: string | object | Blob | Uint8Array;
+    algorithm?: string;
+    useMultihash?: boolean;
+}): Promise<string>;
+/**
+ * Verifies the HTTP `Digest` header value against the given HTTP body `data`.
+ *
+ * @param {object} options - The options to use.
+ * @param {string|object|Blob|Uint8Array} options.data - The data to be
+ *   verified (a request or response body).
+ * @param {string} options.headerValue - The digest header value to verify
+ *   the data against.
+ *
+ * @returns {Promise<{verified: boolean, error?: Error}>}
+ */
+export function verifyHeaderValue({ data, headerValue }: {
+    data: string | object | Blob | Uint8Array;
+    headerValue: string;
+}): Promise<{
+    verified: boolean;
+    error?: Error;
+}>;

package/types/lib/index.d.ts

@@ -0,0 +1 @@
+export { createHeaderValue, verifyHeaderValue } from "./httpDigest.js";

package/types/lib/util.d.ts

@@ -0,0 +1,5 @@
+/*!
+ * Copyright (c) 2021-2025 Digital Bazaar, Inc. All rights reserved.
+ */
+export function base64Encode(bytes: any): any;
+export function base64urlEncode(bytes: any): any;

package/types/util.d.ts

@@ -0,0 +1,5 @@
+/*!
+ * Copyright (c) 2021-2025 Digital Bazaar, Inc. All rights reserved.
+ */
+export function base64Encode(bytes: any): any;
+export function base64urlEncode(bytes: any): any;