@flarcos/http-message-signatures

RFC 9421 HTTP Message Signatures and RFC 9530 Content-Digest for Node.js.

Sign and verify HTTP requests with Ed25519 keys. Built for GNAP (RFC 9635) and Open Payments, but works with any HTTP API that requires message signatures.

Install

npm install @flarcos/http-message-signatures

Usage

Sign a request

import { signRequest, computeContentDigest, loadKey } from '@flarcos/http-message-signatures';

const key = loadKey(`-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEI...
-----END PRIVATE KEY-----`);

// For requests with a body, compute Content-Digest first
const body = JSON.stringify({ amount: '100', currency: 'EUR' });
const digest = computeContentDigest(body);

const result = await signRequest({
  key,
  keyId: 'my-key-id',
  method: 'POST',
  url: 'https://api.example.com/payments',
  headers: {
    'Content-Type': 'application/json',
    'Content-Digest': digest,
    'Content-Length': String(Buffer.byteLength(body)),
    'Authorization': 'GNAP my-access-token',
  },
});

// result.headers contains all headers including Signature and Signature-Input
const response = await fetch('https://api.example.com/payments', {
  method: 'POST',
  headers: result.headers,
  body,
});

Verify Content-Digest

import { verifyContentDigest } from '@flarcos/http-message-signatures';

const isValid = verifyContentDigest(responseBody, response.headers['content-digest']);

Key utilities

import { loadKey, exportPublicJwk, jwkThumbprint } from '@flarcos/http-message-signatures';

const key = loadKey(pemString);
const jwk = exportPublicJwk(key);
const thumbprint = jwkThumbprint(jwk); // Use as keyId

API

signRequest(params)

Signs an HTTP request per RFC 9421. Automatically determines covered components based on headers present:

| Header present | Components covered | |---|---| | (always) | @method, @target-uri | | Authorization | authorization | | Content-Digest | content-digest | | Content-Length | content-length | | Content-Type | content-type |

computeContentDigest(body, algorithm?)

Computes RFC 9530 Content-Digest. Default algorithm: sha-256.

verifyContentDigest(body, headerValue)

Verifies a Content-Digest header against a body. Returns boolean.

loadKey(pem)

Loads an Ed25519 private key from PEM string.

exportPublicJwk(privateKey)

Exports the public key as JWK.

jwkThumbprint(jwk)

Computes the JWK Thumbprint (RFC 7638) — useful as a keyId.

Standards

• RFC 9421 — HTTP Message Signatures
• RFC 9530 — Digest Fields (Content-Digest)
• RFC 7638 — JWK Thumbprint
• RFC 9635 — GNAP (uses HTTP Message Signatures)

Related

• @flarcos/kiota-authentication-gnap — GNAP auth provider (uses this package)
• @flarcos/kiota-arazzo — Arazzo workflow SDK

License

Apache-2.0