HTTP Request Signature

Common errors

• TypeError: (0 , _httpRequestSignature.sign) is not a function

  cause Attempting to use ES module `import` syntax in a CommonJS module or an environment not configured for ESM, while the library primarily exports CommonJS modules.
  fix Use the CommonJS `require` syntax: `const { sign } = require('http-request-signature');`

• Error: Unsupported algorithm: [algorithm_name]

  cause The library was called with an `algorithm` parameter other than `ed25519` during `sign` or `verify` operations.
  fix Ensure that `algorithm: 'ed25519'` is explicitly passed in the options object when calling `sign` or `verify`, as this is the only supported algorithm.

• Error: Malformed signature string

  cause The `signature` string provided to the `verify` function does not conform to the expected format of the HTTP Signatures specification (e.g., missing components, incorrect encoding).
  fix Verify that the `signature` header string is correctly formatted according to the HTTP Signatures specification, including `keyId`, `algorithm`, `headers`, and `signature` components, and that it was generated correctly.

Warnings

• breaking The library implements an 'Internet Draft' of the 'Signing HTTP Messages' specification. This draft is subject to change, meaning future revisions of the specification could introduce breaking changes that this unmaintained library will not address, leading to non-compliance.
  Fix: Consider using actively maintained libraries that adhere to finalized or stable versions of cryptographic standards for HTTP message signing. Review the current state of the 'Signing HTTP Messages' specification.
• gotcha This package exclusively supports the `ed25519` cryptographic algorithm. Attempts to use other algorithms will result in an error, limiting its applicability to systems that can specifically accommodate `ed25519` for signing and verification.
  Fix: Ensure your application environment and cryptographic requirements are compatible with the `ed25519` algorithm before integrating this library. If other algorithms are needed, seek an alternative library.
• breaking The `http-request-signature` package is effectively abandoned, with its last update occurring approximately seven years ago and the latest version being 0.0.5. Using an unmaintained library introduces significant security risks, including unpatched vulnerabilities, lack of compatibility with newer Node.js versions, and potential supply chain attack vectors.
  Fix: It is strongly recommended to migrate to a well-maintained, actively developed library for HTTP message signing that adheres to current security best practices and specifications. If continued use is unavoidable, perform a thorough security audit and be prepared to fork and maintain the library yourself.

Install

• npm install http-request-signature npm
• yarn add http-request-signature yarn
• pnpm add http-request-signature pnpm

Imports

• sign
  wrong:

  import { sign } from 'http-request-signature';

  correct:

  const { sign } = require('http-request-signature');

  This library primarily supports CommonJS modules as it targets Node.js versions predating widespread ESM adoption.
• verify
  wrong:

  import { verify } from 'http-request-signature';

  correct:

  const { verify } = require('http-request-signature');

  This library primarily supports CommonJS modules; ESM usage is not officially supported or documented.

Quickstart

Demonstrates how to generate an HTTP request signature using a secret key and then verify the integrity and authenticity of the signed request using the corresponding public key, adhering to the ed25519 algorithm.

const { sign, verify } = require('http-request-signature');

// Example: Signing an HTTP message
const secretKey = '96aa9ec42242a9a62196281045705196a64e12b15e9160bbb630e38385b82700e7876fd5cc3a228dad634816f4ec4b80a258b2a552467e5d26f30003211bc45d';
const publicKey = 'e7876fd5cc3a228dad634816f4ec4b80a258b2a552467e5d26f30003211bc45d'; // In a real scenario, this would be derived from a different key pair

const requestToSign = {
  headers: {
    '(request-target)': 'post /foo',
    date: '2017-09-01T15:04:17.555Z',
    digest: 'SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE='
  },
  keyId: 'primary',
  secretKey: secretKey
};

const signature = sign(requestToSign, { algorithm: 'ed25519' });
console.log('Generated Signature:', signature);

// Example: Verifying an HTTP message
const signedRequestHeaders = {
  '(request-target)': 'post /foo',
  date: '2017-09-01T15:04:17.555Z',
  digest: 'SHA-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=',
  signature: signature // Use the generated signature
};

const verificationResult = verify({
  headers: signedRequestHeaders,
  publicKey: publicKey
}, { algorithm: 'ed25519' });

console.log('Verification Result:', verificationResult);