HTTP Signature Header (http-signature-header)

A JavaScript library for creating and verifying HTTP Signature headers

Table of Contents

• Background
• Install
• Usage
• Contribute
• Commercial Support
• License

Background

HTTP Signatures IETF draft

Install

To install locally (for development):

git clone https://github.com/digitalbazaar/http-signature-header.git
cd http-signature-header
npm install

Usage

import {
  createAuthzHeader, createSignatureString
} from '@digitalbazaar/http-signature-header';

const requestOptions = {
  url,
  method: 'POST',
  headers
}
const includeHeaders = ['expires', 'host', '(request-target)'];
const plaintext = createSignatureString({includeHeaders, requestOptions});

const data = new TextEncoder().encode(plaintext);
const signature = base64url.encode(await signer.sign({data}));

const Authorization = createAuthzHeader({
  includeHeaders,
  keyId: signer.id,
  signature
});

Contribute

Please follow the existing code style.

PRs accepted.

If editing the Readme, please conform to the standard-readme specification.

Commercial Support

Commercial support for this library is available upon request from Digital Bazaar: support@digitalbazaar.com

License

BSD-3-Clause © Digital Bazaar

@digitalbazaar/http-signature-header

5.0.1 - 2024-08-08

Changed

• Add package.json license field.
• Test on Node.js 20.x.

5.0.0 - 2022-06-02

Changed

• BREAKING: Convert to module (ESM).
• BREAKING: Require Node.js >=14.
• Update dependencies.
• Lint module.

4.1.0 - 2022-04-13

Changed

• Change from "env" platform detection to util.js with browser override file.
• Update development dependencies.

4.0.1 - 2022-01-11

Changed

• BREAKING: Add node 12 package.json requirement.

Fixed

• Remove unused dependencies.

4.0.0 - 2022-01-11

Changed

• BREAKING: Rename package to @digitalbazaar/http-signature-header.
• BREAKING: Require node 12.x.

3.0.0 - 2022-01-11

Changed

• No changes, renaming mistake. See version 4.x.

2.0.2 - 2021-06-09

Fixed

• Ensure that clock skew is considered when comparing dates.

2.0.1 - 2021-03-02

Added

• A files entry to package.json to remove the dirs test & bin from npm releases.

2.0.0 - 2021-02-25

Fixed

• BREAKING: Pseudo-headers created & expires must be unix time stamps or JavaScript Dates.
• hs2019 does not hash signature string before signing a signature string.

Changed

• BREAKING: Library throws if the signature parameter headers is a zero-length string.
• BREAKING: Library adds default (created) if no signature parameter header is present.
• Validate sigString parameter in the parseSignatureHeader API.

Added

• BREAKING: Support for the Signing HTTP Messages version 12 specification. Note that an updated version is currently being developed.
• BREAKING: Validators for created & expires.
• Tests for parseRequest.
• Tests for headers parameter order.
• Tests for unrecognized parameters in a signature.
• JSDoc strings for library functions and methods.
• BREAKING: Validation is algorithm specific in some cases.
• Test browser support with karma.

1.3.1 - 2019-07-18

Fixed

• Do not use full URL in (request-target).

1.3.0 - 2019-06-29

Added

• Include created and expires in authz header.
• Accept Date objects for parameters and header values.
• Support hs2019.
• Support (key-id) and (algorithm) pseudo headers.

1.2.0 - 2019-03-02

Added

• Enable use of this library in the browser.

Removed

• Remove unnecessary jsprim dependency.

1.1.1 - 2018-07-24

Fixed

• Fix serialization of values for headers that appear multiple times (join using , rather than just ,) per Section 2.3.2 of RFC.

1.1.0 - 2018-05-18

Added

• Expose HttpSignatureError class.

1.0.0 - 2018-05-12

• See git history for changes.