{"id":16074,"library":"http-signature","title":"HTTP Signature","description":"http-signature is a Node.js library providing a reference implementation for Joyent's HTTP Signature scheme. This scheme allows clients and servers to sign and verify HTTP messages to ensure authenticity and integrity. The package's latest version, 1.4.0, was published over two years ago (as of late 2023), indicating a low-cadence or maintenance status, despite high weekly download numbers. While still widely used, it's important to note that this library implements Joyent's specific scheme, which predates and differs from the more recent IETF RFC 9421 \"HTTP Message Signatures\" standard. Other libraries, such as `http-message-signatures`, implement the newer RFC. This package is primarily designed for CommonJS environments and does not natively support ESM imports.","status":"maintenance","version":"1.4.0","language":"javascript","source_language":"en","source_url":"git://github.com/TritonDataCenter/node-http-signature","tags":["javascript","https","request"],"install":[{"cmd":"npm install http-signature","lang":"bash","label":"npm"},{"cmd":"yarn add http-signature","lang":"bash","label":"yarn"},{"cmd":"pnpm add http-signature","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This library is primarily CommonJS-first. While a default import might work in some transpiled ESM environments, the `require` statement accessing the module directly is the most reliable. No explicit ESM support is declared or evident.","wrong":"const httpSignature = require('http-signature').default;","symbol":"httpSignature","correct":"import httpSignature from 'http-signature'"},{"note":"The `sign` function is a method of the default exported `httpSignature` object. Direct named imports are not supported.","wrong":"import { sign } from 'http-signature';","symbol":"sign","correct":"const httpSignature = require('http-signature');\nhttpSignature.sign(req, options);"},{"note":"Like `sign`, `parseRequest` is a method of the default exported `httpSignature` object; it is not a named export.","wrong":"import { parseRequest } from 'http-signature';","symbol":"parseRequest","correct":"const httpSignature = require('http-signature');\nhttpSignature.parseRequest(req);"}],"quickstart":{"code":"const fs = require('fs');\nconst https = require('https');\nconst httpSignature = require('http-signature');\n\n// In a real application, manage keys securely, e.g., via environment variables or a KMS.\n// For this example, create dummy key.pem and cert.pem files.\n// echo '-----BEGIN RSA PRIVATE KEY-----\n// ...your-private-key...\n// -----END RSA PRIVATE KEY-----' > key.pem\n// echo '-----BEGIN CERTIFICATE-----\n// ...your-certificate...\n// -----END CERTIFICATE-----' > cert.pem\n\nconst key = fs.readFileSync('./key.pem', 'ascii');\n\nconst options = {\n  host: 'localhost',\n  port: 8443,\n  path: '/',\n  method: 'GET',\n  headers: {}\n};\n\nconst req = https.request(options, function(res) {\n  console.log('Client received status code:', res.statusCode);\n  res.on('data', (d) => process.stdout.write(d));\n  res.on('end', () => console.log('\\nClient request complete.'));\n});\n\nhttpSignature.sign(req, {\n  key: key,\n  keyId: 'client-key-id',\n  keyPassphrase: process.env.KEY_PASSPHRASE ?? '' // Optional, if key is encrypted\n});\n\nreq.end();\n\n// --- Server-side (for testing the client) ---\nconst serverOptions = {\n  key: fs.readFileSync('./key.pem'),\n  cert: fs.readFileSync('./cert.pem')\n};\n\nhttps.createServer(serverOptions, function (serverReq, serverRes) {\n  let responseCode = 200;\n  try {\n    const parsed = httpSignature.parseRequest(serverReq);\n    // For a real server, 'pub' would come from a trusted source based on parsed.keyId\n    const pub = fs.readFileSync('./cert.pem', 'ascii'); // Using the same cert for simplicity\n\n    if (!httpSignature.verifySignature(parsed, pub)) {\n      responseCode = 401; // Unauthorized\n      console.error('Server: Signature verification failed!');\n    } else {\n      console.log('Server: Signature verified successfully for keyId:', parsed.keyId);\n    }\n  } catch (e) {\n    responseCode = 500;\n    console.error('Server error processing signature:', e.message);\n  }\n\n  serverRes.writeHead(responseCode, { 'Content-Type': 'text/plain' });\n  serverRes.end(responseCode === 200 ? 'Hello from signed server!' : 'Authentication failed.');\n}).listen(8443, () => console.log('Server listening on port 8443...'));","lang":"javascript","description":"Demonstrates both client-side request signing and server-side signature verification using `http-signature` for a basic HTTPS request. It shows how to use `sign`, `parseRequest`, and `verifySignature` functions."},"warnings":[{"fix":"Upgrade `http-signature` to version 1.0.0 or later (e.g., `npm install http-signature@latest`).","message":"Versions of `http-signature` prior to 1.0.0 were vulnerable to timing attacks during signature comparison, potentially allowing attackers to guess signatures character by character. Upgrade to version 1.0.0 or higher to mitigate this vulnerability.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Upgrade `http-signature` to version 0.10.0 or later (e.g., `npm install http-signature@latest`).","message":"Versions prior to 0.10.0 were susceptible to header forgery because HTTP header names were not included in the signed string, allowing an attacker to modify header names and alter the request's meaning without invalidating the signature. Upgrade to version 0.10.0 or higher.","severity":"breaking","affected_versions":"<0.10.0"},{"fix":"Verify the exact HTTP signature specification required by your service. If RFC 9421 is needed, use a compliant library. If integrating with services built on Joyent's original scheme, this library is appropriate.","message":"This library implements Joyent's specific 'HTTP Signature Scheme', which is distinct from the newer IETF RFC 9421 'HTTP Message Signatures' standard. If your application needs to comply with the latest IETF RFC, this library may not be suitable, and you should consider alternatives like `http-message-signatures`.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Assess future-proofing needs for your authentication strategy. Consider migrating to JWT or IETF RFC 9421 compliant message signatures if long-term interoperability or advanced security features (like MLE) are critical for your service.","message":"The underlying 'HTTP Signature Scheme' (in some contexts, e.g., Cybersource's implementation) is being phased out in favor of alternative authentication methods like JSON Web Tokens (JWT) for enhanced features like message-level encryption. While this specific library is not directly deprecated, the broader adoption of HTTP signature schemes might decline.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure correct private/public key pairs are used on client/server, the same signing algorithm is configured, and all signed headers match precisely. Check for payload modifications in transit or significant time differences between client and server.","cause":"The generated signature does not match the one expected by the server, often due to mismatched keys, incorrect algorithms, altered payloads, or clock skew.","error":"Invalid Signature"},{"fix":"Inspect the incoming request's `Authorization` or `Signature` header to ensure it's present, correctly formatted, and adheres to the expected HTTP Signature scheme parameters (keyId, algorithm, headers, signature).","cause":"The `httpSignature.parseRequest()` function returned `undefined` or an incomplete object, indicating an issue parsing the incoming HTTP request's Signature header.","error":"TypeError: Cannot read properties of undefined (reading 'keyId')"},{"fix":"Ensure the client is adding the `Authorization: Signature` header with all required parameters (keyId, algorithm, headers, signature) to the HTTP request before sending it.","cause":"The incoming HTTP request lacks a properly formed 'Authorization: Signature ...' or 'Signature: ...' header as required by the HTTP Signature specification.","error":"Error: Missing or malformed signature header"}],"ecosystem":"npm"}