@johnhenry/http-fields-signatures 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Henry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,174 @@
-# Temporary Holding Version
+# @johnhenry/http-fields-signatures
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Previously published as the unscoped `http-fields-signatures` (0.1.0). This scoped package continues that line at 0.2.0 and depends on `@johnhenry/http-fields`.
+
+[RFC 9421](https://www.rfc-editor.org/rfc/rfc9421.html) **HTTP Message
+Signatures** for JavaScript — sign and verify HTTP requests and responses.
+
+Built on [`http-fields`](https://github.com/johnhenry/http-fields) (RFC
+8941/9651 Structured Field Values) for all header parsing/serialization, and
+on WebCrypto for the cryptography. Runtime-agnostic: Node.js ≥ 20, browsers,
+and edge runtimes with `globalThis.crypto.subtle`.
+
+Validated against the complete RFC 9421 Appendix B test suite: all six
+signature bases are reproduced byte-exactly, the RFC's RSA-PSS and ECDSA
+example signatures verify, and HMAC/Ed25519 signing reproduces the RFC's
+exact signature bytes.
+
+## Installation
+
+```bash
+npm install @johnhenry/http-fields-signatures
+```
+
+## Quick Start
+
+### Signing a request
+
+```javascript
+import { signMessage } from "@johnhenry/http-fields-signatures";
+
+const request = {
+  method: "POST",
+  url: "https://example.com/foo?param=Value&Pet=dog",
+  headers: {
+    Date: "Tue, 20 Apr 2021 02:07:55 GMT",
+    "Content-Type": "application/json",
+  },
+};
+
+const { signatureInput, signature } = await signMessage(request, {
+  alg: "ed25519",
+  key: privateJwk, // JWK, PEM (PKCS#8), or CryptoKey
+  keyid: "my-key",
+  components: ["@method", "@path", "@authority", "content-type"],
+});
+
+request.headers["Signature-Input"] = signatureInput;
+request.headers["Signature"] = signature;
+// Signature-Input: sig1=("@method" "@path" "@authority" "content-type");created=...;keyid="my-key"
+// Signature: sig1=:...base64...:
+```
+
+### Verifying
+
+```javascript
+import { verifyMessage } from "@johnhenry/http-fields-signatures";
+
+const results = await verifyMessage(request, {
+  getKey: ({ keyid }) => ({ alg: "ed25519", key: publicKeys[keyid] }),
+});
+// [{ label: "sig1", verified: true, params: {...}, components: [...] }]
+```
+
+Structural problems (unparseable headers) throw; cryptographic mismatches and
+policy failures (expired signatures, unknown keys) report as
+`{verified: false, reason}` so one bad signature doesn't mask others.
+
+### Signing a response (with request binding)
+
+```javascript
+const response = { status: 200, headers: {...}, request };
+
+await signMessage(response, {
+  alg: "ecdsa-p256-sha256",
+  key: privateJwk,
+  keyid: "my-key",
+  components: [
+    "@status",
+    "content-type",
+    { id: "@method", params: { req: true } }, // bind to the request's method
+  ],
+});
+```
+
+## Supported algorithms (RFC 9421 §3.3)
+
+| Name | WebCrypto |
+| --- | --- |
+| `rsa-pss-sha512` | RSA-PSS, SHA-512, salt 64 |
+| `rsa-v1_5-sha256` | RSASSA-PKCS1-v1_5, SHA-256 |
+| `ecdsa-p256-sha256` | ECDSA P-256, SHA-256 |
+| `ecdsa-p384-sha384` | ECDSA P-384, SHA-384 |
+| `ed25519` | Ed25519 |
+| `hmac-sha256` | HMAC, SHA-256 |
+
+Keys are accepted as **CryptoKey**, **JWK** objects, **PEM** strings (PKCS#8
+or SEC1 private / SPKI public), or raw **Uint8Array** bytes (HMAC).
+
+WebCrypto itself cannot import SEC1 `EC PRIVATE KEY` PEMs (the format RFC
+9421 uses for its P-256 example key), so `importKey` transparently re-wraps
+them: PKCS#8 is just an ASN.1 envelope around the SEC1 payload, so the
+conversion is pure DER re-packaging with no cryptography involved. The
+transcoder is also exported directly as `sec1ToPkcs8(sec1Bytes, namedCurve?)`.
+
+**Encrypted private keys are not supported.** Password-protected PEMs —
+PKCS#8 `ENCRYPTED PRIVATE KEY` (PBES2) or legacy `Proc-Type: 4,ENCRYPTED`
+blocks — require key-derivation cryptography, not byte re-packaging, and
+`importKey` rejects them with a clear error. Decrypt once outside the
+library instead:
+
+```bash
+openssl pkcs8 -topk8 -nocrypt -in encrypted-key.pem -out key.pem
+```
+
+## Covered components
+
+Components are strings or `{id, params}` objects:
+
+- **Derived** (from the message itself): `@method`, `@target-uri`,
+  `@authority`, `@scheme`, `@request-target`, `@path`, `@query`,
+  `@query-param` (`{id: "@query-param", params: {name: "Pet"}}`), `@status`
+- **Fields**: any header name (lowercased), with optional parameters:
+  - `key`: select one dictionary member (`{id: "example-dict", params: {key: "b"}}`)
+  - `sf`: strict structured-field re-serialization (requires the field's type
+    via `options.fieldTypes`)
+  - `bs`: wrap raw value(s) as byte sequences
+  - `req`: take the component from the related request when signing a response
+
+## Lower-level API
+
+```javascript
+import {
+  createSignatureBase, // build the §2.5 signature base string
+  parseSignatureHeaders, // parse Signature-Input / Signature dictionaries
+  signBase, verifyBase, // raw crypto over a base string
+  importKey, ALGORITHMS,
+} from "@johnhenry/http-fields-signatures";
+
+const { base } = createSignatureBase(request, ["@method", "content-type"], {
+  created: 1618884473,
+  keyid: "my-key",
+});
+```
+
+## Messages
+
+Messages are plain objects, so any client/server framework can adapt to them:
+
+```javascript
+// Request:  { method, url, headers }
+// Response: { status, headers, request? }
+```
+
+`headers` may be a plain object (values `string` or `string[]`), an array of
+`[name, value]` entries, or a Fetch-style `Headers` instance.
+
+## Testing
+
+```bash
+npm test
+```
+
+The suite includes the full RFC 9421 Appendix B vectors (B.2.1–B.2.6) plus
+round-trip, tampering, and expiry tests.
+
+## Alternatives
+
+See [COMPARISON.md](COMPARISON.md) for a side-by-side comparison with
+[`http-message-signatures`](https://github.com/dhensby/node-http-message-signatures),
+including how to do the same signing/verifying tasks in each.
+
+## License
+
+MIT

package/base.mjs

@@ -0,0 +1,236 @@
+/**
+ * RFC 9421 signature base construction (§2).
+ *
+ * A "message" is a plain, runtime-agnostic object:
+ *   Request:  { method, url, headers }
+ *   Response: { status, headers, request? }   // request enables ;req params
+ *
+ * `headers` may be a plain object (values: string or string[]), an iterable
+ * of [name, value] entries, or a Fetch-style Headers instance.
+ */
+
+"use strict";
+
+import { parse, serialize } from "@johnhenry/http-fields";
+
+// --- header access ---------------------------------------------------------
+
+const headerEntries = (headers) => {
+  if (!headers) return [];
+  if (typeof headers.entries === "function" && typeof headers.get === "function") {
+    return [...headers.entries()];
+  }
+  if (Array.isArray(headers)) return headers;
+  return Object.entries(headers);
+};
+
+/** All values for a header name (case-insensitive), in order. */
+export const getHeaderValues = (headers, name) => {
+  const lower = name.toLowerCase();
+  const values = [];
+  for (const [key, value] of headerEntries(headers)) {
+    if (String(key).toLowerCase() === lower) {
+      if (Array.isArray(value)) values.push(...value.map(String));
+      else values.push(String(value));
+    }
+  }
+  return values;
+};
+
+// --- component identifiers -------------------------------------------------
+
+/**
+ * Normalize a covered-component spec to {id, params}. Accepts a bare string
+ * ("@method", "content-type") or {id, params} for parameterized components
+ * ({id: "@query-param", params: {name: "Pet"}}).
+ */
+export const normalizeComponent = (component) => {
+  if (typeof component === "string") return { id: component, params: {} };
+  if (component && typeof component.id === "string") {
+    return { id: component.id, params: { ...(component.params || {}) } };
+  }
+  throw new Error("Component must be a string or {id, params} object");
+};
+
+/** Serialize a component identifier as an SFV string item with parameters. */
+export const serializeComponentIdentifier = ({ id, params }) => {
+  return serialize({ value: id.toLowerCase(), parameters: params }, "item");
+};
+
+// --- derived component values (§2.2) ---------------------------------------
+
+const strictEncode = (s) =>
+  encodeURIComponent(s).replace(
+    /[!'()*]/g,
+    (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase()
+  );
+
+const requireUrl = (message) => {
+  if (!message || typeof message.url !== "string") {
+    throw new Error("Message must have an absolute 'url' for this component");
+  }
+  return new URL(message.url);
+};
+
+const deriveValues = (id, params, message) => {
+  const url = () => requireUrl(message);
+  switch (id) {
+    case "@method": {
+      if (typeof message.method !== "string") {
+        throw new Error("Message must have a 'method'");
+      }
+      return [message.method.toUpperCase()];
+    }
+    case "@target-uri":
+      return [url().href];
+    case "@authority": {
+      const u = url();
+      return [u.host.toLowerCase()];
+    }
+    case "@scheme":
+      return [url().protocol.replace(/:$/, "").toLowerCase()];
+    case "@request-target": {
+      const u = url();
+      return [u.pathname + u.search];
+    }
+    case "@path":
+      return [url().pathname];
+    case "@query": {
+      const u = url();
+      return [u.search === "" ? "?" : u.search];
+    }
+    case "@query-param": {
+      if (typeof params.name !== "string") {
+        throw new Error('@query-param requires a "name" parameter');
+      }
+      const u = url();
+      const lines = [];
+      for (const [k, v] of new URLSearchParams(u.search)) {
+        if (strictEncode(k) === params.name) lines.push(strictEncode(v));
+      }
+      if (lines.length === 0) {
+        throw new Error(`Query parameter "${params.name}" not found`);
+      }
+      return lines;
+    }
+    case "@status": {
+      if (!Number.isInteger(message.status)) {
+        throw new Error("Message must have an integer 'status'");
+      }
+      return [String(message.status)];
+    }
+    default:
+      throw new Error(`Unknown derived component: ${id}`);
+  }
+};
+
+// --- field component values (§2.1) -----------------------------------------
+
+const b64FromBytes = (bytes) => {
+  let bin = "";
+  for (const byte of bytes) bin += String.fromCharCode(byte);
+  return btoa(bin);
+};
+
+const fieldValue = (id, params, message, options) => {
+  const values = getHeaderValues(message.headers, id).map((v) =>
+    v.trim().replace(/[ \t]*\r?\n[ \t]*/g, " ")
+  );
+  if (values.length === 0) {
+    throw new Error(`Header field "${id}" not present in message`);
+  }
+
+  if (params.bs === true) {
+    const encoder = new TextEncoder();
+    return values.map((v) => `:${b64FromBytes(encoder.encode(v))}:`).join(", ");
+  }
+
+  if (params.key !== undefined) {
+    if (typeof params.key !== "string") {
+      throw new Error('"key" parameter must be a string');
+    }
+    const dict = parse(values.join(", "), "dictionary");
+    const member = dict[params.key];
+    if (member === undefined) {
+      throw new Error(`Dictionary key "${params.key}" not found in "${id}"`);
+    }
+    if (Array.isArray(member.value)) {
+      return serialize([member], "list");
+    }
+    return serialize({ value: member.value, parameters: member.parameters }, "item");
+  }
+
+  if (params.sf === true) {
+    const type = options?.fieldTypes?.[id];
+    if (!type) {
+      throw new Error(
+        `"sf" parameter requires the field type of "${id}" via options.fieldTypes`
+      );
+    }
+    return serialize(parse(values.join(", "), type), type);
+  }
+
+  if (params.tr === true) {
+    throw new Error("Trailer components (;tr) are not supported");
+  }
+
+  return values.join(", ");
+};
+
+// --- signature base (§2.5) -------------------------------------------------
+
+/**
+ * Build the RFC 9421 signature base.
+ *
+ * @param {object} message - request or response message (see module docs)
+ * @param {Array<string|{id: string, params?: object}>} components
+ * @param {object} signatureParams - created/expires/nonce/alg/keyid/tag, in
+ *   the order they should appear on the wire
+ * @param {{fieldTypes?: Record<string, "list"|"dictionary"|"item">}} [options]
+ * @returns {{base: string, signatureParamsValue: string}} the base string and
+ *   the serialized inner list used in both the base and Signature-Input
+ */
+export const createSignatureBase = (message, components, signatureParams, options) => {
+  const normalized = components.map(normalizeComponent);
+  const lines = [];
+  const seen = new Set();
+
+  for (const component of normalized) {
+    const { params } = component;
+    const id = component.id.toLowerCase();
+
+    let target = message;
+    if (params.req === true) {
+      if (!message.request) {
+        throw new Error('";req" component requires message.request');
+      }
+      target = message.request;
+    }
+
+    const identifier = serializeComponentIdentifier({ id, params });
+    if (seen.has(identifier)) {
+      throw new Error(`Duplicate covered component: ${identifier}`);
+    }
+    seen.add(identifier);
+
+    const values = id.startsWith("@")
+      ? deriveValues(id, params, target)
+      : [fieldValue(id, params, target, options)];
+
+    for (const value of values) {
+      lines.push(`${identifier}: ${value}`);
+    }
+  }
+
+  const innerList = normalized.map(({ id, params }) => ({
+    value: id.toLowerCase(),
+    parameters: params,
+  }));
+  const signatureParamsValue = serialize(
+    [{ value: innerList, parameters: signatureParams || {} }],
+    "list"
+  );
+  lines.push(`"@signature-params": ${signatureParamsValue}`);
+
+  return { base: lines.join("\n"), signatureParamsValue };
+};

package/crypto.mjs

@@ -0,0 +1,215 @@
+/**
+ * RFC 9421 signature algorithms (§3.3) over WebCrypto.
+ *
+ * Keys are accepted as: a CryptoKey, a JWK object, a PEM string (PKCS#8
+ * private or SPKI public), or raw bytes (Uint8Array, HMAC only).
+ */
+
+"use strict";
+
+const subtle = globalThis.crypto?.subtle;
+if (!subtle) {
+  throw new Error("WebCrypto (globalThis.crypto.subtle) is required");
+}
+
+export const ALGORITHMS = {
+  "rsa-pss-sha512": {
+    importParams: { name: "RSA-PSS", hash: "SHA-512" },
+    signParams: { name: "RSA-PSS", saltLength: 64 },
+  },
+  "rsa-v1_5-sha256": {
+    importParams: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+    signParams: { name: "RSASSA-PKCS1-v1_5" },
+  },
+  "ecdsa-p256-sha256": {
+    importParams: { name: "ECDSA", namedCurve: "P-256" },
+    signParams: { name: "ECDSA", hash: "SHA-256" },
+  },
+  "ecdsa-p384-sha384": {
+    importParams: { name: "ECDSA", namedCurve: "P-384" },
+    signParams: { name: "ECDSA", hash: "SHA-384" },
+  },
+  ed25519: {
+    importParams: { name: "Ed25519" },
+    signParams: { name: "Ed25519" },
+  },
+  "hmac-sha256": {
+    importParams: { name: "HMAC", hash: "SHA-256" },
+    signParams: { name: "HMAC" },
+  },
+};
+
+const bytesFromB64 = (b64) => {
+  const bin = atob(b64);
+  const bytes = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+  return bytes;
+};
+
+const pemToBytes = (pem, label) => {
+  const match = pem.match(
+    new RegExp(`-----BEGIN ${label}-----([A-Za-z0-9+/=\\s]+)-----END ${label}-----`)
+  );
+  if (!match) return null;
+  return bytesFromB64(match[1].replace(/\s+/g, ""));
+};
+
+// --- SEC1 → PKCS#8 transcoding ---------------------------------------------
+// WebCrypto cannot import SEC1 "EC PRIVATE KEY" DER (RFC 5915) directly, but
+// PKCS#8 is just an ASN.1 envelope around it:
+//   SEQUENCE { INTEGER 0, SEQUENCE { id-ecPublicKey, curveOID }, OCTET STRING <SEC1> }
+// No cryptography involved — pure DER re-packaging.
+
+const OID_EC_PUBLIC_KEY = [0x06, 0x07, 0x2a, 0x86, 0x48, 0xce, 0x3d, 0x02, 0x01];
+const CURVE_OIDS = {
+  "P-256": [0x06, 0x08, 0x2a, 0x86, 0x48, 0xce, 0x3d, 0x03, 0x01, 0x07],
+  "P-384": [0x06, 0x05, 0x2b, 0x81, 0x04, 0x00, 0x22],
+  "P-521": [0x06, 0x05, 0x2b, 0x81, 0x04, 0x00, 0x23],
+};
+
+const derTlv = (tag, contents) => {
+  const len = contents.length;
+  let header;
+  if (len < 0x80) header = [tag, len];
+  else if (len < 0x100) header = [tag, 0x81, len];
+  else header = [tag, 0x82, len >> 8, len & 0xff];
+  return Uint8Array.from([...header, ...contents]);
+};
+
+// Minimal DER walk over the SEC1 ECPrivateKey to find the [0] curve
+// parameters (an OID), when present.
+const sec1CurveOid = (sec1) => {
+  if (sec1[0] !== 0x30) throw new Error("SEC1 key must start with a SEQUENCE");
+  let offset = 2;
+  if (sec1[1] & 0x80) offset = 2 + (sec1[1] & 0x7f);
+  while (offset < sec1.length) {
+    const tag = sec1[offset];
+    let len = sec1[offset + 1];
+    let headerLen = 2;
+    if (len & 0x80) {
+      const lenBytes = len & 0x7f;
+      len = 0;
+      for (let i = 0; i < lenBytes; i++) len = (len << 8) | sec1[offset + 2 + i];
+      headerLen = 2 + lenBytes;
+    }
+    if (tag === 0xa0) {
+      // [0] explicit: contents are the curve OID TLV
+      return [...sec1.slice(offset + headerLen, offset + headerLen + len)];
+    }
+    offset += headerLen + len;
+  }
+  return null;
+};
+
+/**
+ * Wrap SEC1 "EC PRIVATE KEY" DER bytes in a PKCS#8 envelope so WebCrypto can
+ * import them. The curve is read from the key's [0] parameters when present,
+ * else taken from `namedCurve` ("P-256" | "P-384" | "P-521").
+ * @param {Uint8Array} sec1 - DER bytes of the ECPrivateKey
+ * @param {string} [namedCurve] - fallback curve name
+ * @returns {Uint8Array} PKCS#8 DER bytes
+ */
+export const sec1ToPkcs8 = (sec1, namedCurve) => {
+  const curveOid = sec1CurveOid(sec1) ?? CURVE_OIDS[namedCurve];
+  if (!curveOid) {
+    throw new Error(
+      "SEC1 key has no curve parameters; a namedCurve is required"
+    );
+  }
+  const algorithmId = derTlv(0x30, [...OID_EC_PUBLIC_KEY, ...curveOid]);
+  const version = Uint8Array.from([0x02, 0x01, 0x00]);
+  const privateKey = derTlv(0x04, sec1);
+  return derTlv(0x30, [...version, ...algorithmId, ...privateKey]);
+};
+
+/**
+ * Import key material for an algorithm.
+ * @param {string} alg - RFC 9421 algorithm name (e.g. "ed25519")
+ * @param {CryptoKey|object|string|Uint8Array} material - CryptoKey, JWK,
+ *   PEM (PKCS#8/SPKI), or raw bytes (HMAC)
+ * @param {"sign"|"verify"} usage
+ * @returns {Promise<CryptoKey>}
+ */
+export const importKey = async (alg, material, usage) => {
+  const spec = ALGORITHMS[alg];
+  if (!spec) throw new Error(`Unsupported algorithm: ${alg}`);
+
+  if (material && typeof material === "object" && material.type && material.algorithm) {
+    return material; // already a CryptoKey
+  }
+
+  if (material instanceof Uint8Array) {
+    if (alg !== "hmac-sha256") {
+      throw new Error("Raw byte keys are only supported for hmac-sha256");
+    }
+    return subtle.importKey("raw", material, spec.importParams, false, [
+      "sign",
+      "verify",
+    ]);
+  }
+
+  if (typeof material === "object") {
+    // JWK: private keys carry "d"
+    const usages =
+      alg === "hmac-sha256" ? ["sign", "verify"] : [material.d ? "sign" : "verify"];
+    return subtle.importKey("jwk", material, spec.importParams, false, usages);
+  }
+
+  if (typeof material === "string") {
+    // Encrypted keys are out of scope: decrypting them means PBES2/PBKDF2 key
+    // derivation, not DER re-packaging. Decrypt once with
+    // `openssl pkcs8 -topk8 -nocrypt` and pass the result instead.
+    if (
+      material.includes("ENCRYPTED PRIVATE KEY") ||
+      /Proc-Type:\s*4\s*,\s*ENCRYPTED/.test(material)
+    ) {
+      throw new Error(
+        "Encrypted private keys are not supported; decrypt first, e.g. " +
+          "`openssl pkcs8 -topk8 -nocrypt -in key.pem`"
+      );
+    }
+    const pkcs8 = pemToBytes(material, "PRIVATE KEY");
+    if (pkcs8) {
+      return subtle.importKey("pkcs8", pkcs8, spec.importParams, false, ["sign"]);
+    }
+    const sec1 = pemToBytes(material, "EC PRIVATE KEY");
+    if (sec1) {
+      const wrapped = sec1ToPkcs8(sec1, spec.importParams.namedCurve);
+      return subtle.importKey("pkcs8", wrapped, spec.importParams, false, ["sign"]);
+    }
+    const spki = pemToBytes(material, "PUBLIC KEY");
+    if (spki) {
+      return subtle.importKey("spki", spki, spec.importParams, false, ["verify"]);
+    }
+    throw new Error(
+      "PEM must contain a PKCS#8/SEC1 private key or SPKI PUBLIC KEY block"
+    );
+  }
+
+  throw new Error(`Unsupported key material for ${usage}`);
+};
+
+/**
+ * Sign a signature base with the given algorithm and key.
+ * @returns {Promise<Uint8Array>} raw signature bytes
+ */
+export const signBase = async (alg, key, base) => {
+  const spec = ALGORITHMS[alg];
+  if (!spec) throw new Error(`Unsupported algorithm: ${alg}`);
+  const cryptoKey = await importKey(alg, key, "sign");
+  const data = new TextEncoder().encode(base);
+  const sig = await subtle.sign(spec.signParams, cryptoKey, data);
+  return new Uint8Array(sig);
+};
+
+/**
+ * Verify raw signature bytes over a signature base.
+ * @returns {Promise<boolean>}
+ */
+export const verifyBase = async (alg, key, signature, base) => {
+  const spec = ALGORITHMS[alg];
+  if (!spec) throw new Error(`Unsupported algorithm: ${alg}`);
+  const cryptoKey = await importKey(alg, key, "verify");
+  const data = new TextEncoder().encode(base);
+  return subtle.verify(spec.signParams, cryptoKey, signature, data);
+};

package/index.mjs

@@ -0,0 +1,232 @@
+/**
+ * @johnhenry/http-fields-signatures — RFC 9421 HTTP Message Signatures.
+ *
+ * Built on `@johnhenry/http-fields` (RFC 8941/9651 Structured Field Values) for all
+ * header parsing/serialization, and WebCrypto for the cryptography.
+ */
+
+"use strict";
+
+import { parse, serialize, binary } from "@johnhenry/http-fields";
+import {
+  createSignatureBase,
+  getHeaderValues,
+  normalizeComponent,
+} from "./base.mjs";
+import { ALGORITHMS, importKey, signBase, verifyBase } from "./crypto.mjs";
+
+export { createSignatureBase, getHeaderValues } from "./base.mjs";
+export {
+  ALGORITHMS,
+  importKey,
+  signBase,
+  verifyBase,
+  sec1ToPkcs8,
+} from "./crypto.mjs";
+
+const bytesToB64 = (bytes) => {
+  let bin = "";
+  for (const byte of bytes) bin += String.fromCharCode(byte);
+  return btoa(bin);
+};
+
+const b64ToBytes = (b64) => {
+  const bin = atob(b64);
+  const bytes = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+  return bytes;
+};
+
+/**
+ * Parse `Signature-Input` and `Signature` header values into per-label
+ * entries: {label: {components: [{id, params}], params, signature?}}.
+ * Either argument may be undefined.
+ */
+export const parseSignatureHeaders = (signatureInput, signature) => {
+  const entries = {};
+  if (signatureInput !== undefined) {
+    const dict = parse(signatureInput, "dictionary");
+    for (const [label, member] of Object.entries(dict)) {
+      if (!Array.isArray(member.value)) {
+        throw new Error(`Signature-Input member "${label}" must be an inner list`);
+      }
+      const components = member.value.map((item) => {
+        if (typeof item.value !== "string") {
+          throw new Error("Covered components must be strings");
+        }
+        return { id: item.value, params: item.parameters };
+      });
+      entries[label] = { components, params: member.parameters };
+    }
+  }
+  if (signature !== undefined) {
+    const dict = parse(signature, "dictionary");
+    for (const [label, member] of Object.entries(dict)) {
+      const v = member.value;
+      if (!v || v.type !== "binary") {
+        throw new Error(`Signature member "${label}" must be a byte sequence`);
+      }
+      entries[label] = entries[label] || {};
+      entries[label].signature = b64ToBytes(v.value);
+    }
+  }
+  return entries;
+};
+
+/**
+ * Sign an HTTP message (RFC 9421).
+ *
+ * @param {object} message - {method, url, headers} or {status, headers, request?}
+ * @param {object} options
+ * @param {string} options.alg - algorithm name (see ALGORITHMS)
+ * @param {CryptoKey|object|string|Uint8Array} options.key - signing key
+ * @param {Array<string|{id, params}>} [options.components=[]] - covered components
+ * @param {string} [options.label="sig1"] - signature label
+ * @param {string} [options.keyid]
+ * @param {number} [options.created=now] - unix seconds; pass null to omit
+ * @param {number} [options.expires]
+ * @param {string} [options.nonce]
+ * @param {string} [options.tag]
+ * @param {boolean} [options.includeAlg=false] - include the alg parameter
+ * @param {object} [options.fieldTypes] - field name → SFV type, for ;sf
+ * @returns {Promise<{signatureInput: string, signature: string, base: string,
+ *   label: string}>} header values to add to the message
+ */
+export const signMessage = async (message, options) => {
+  const {
+    alg,
+    key,
+    components = [],
+    label = "sig1",
+    keyid,
+    created = Math.floor(Date.now() / 1000),
+    expires,
+    nonce,
+    tag,
+    includeAlg = false,
+    fieldTypes,
+  } = options;
+
+  if (!ALGORITHMS[alg]) throw new Error(`Unsupported algorithm: ${alg}`);
+
+  // Parameter order follows the RFC 9421 examples: created, expires, alg,
+  // keyid, then nonce/tag
+  const params = {};
+  if (created !== null && created !== undefined) params.created = created;
+  if (expires !== undefined) params.expires = expires;
+  if (includeAlg) params.alg = alg;
+  if (keyid !== undefined) params.keyid = keyid;
+  if (nonce !== undefined) params.nonce = nonce;
+  if (tag !== undefined) params.tag = tag;
+
+  const { base } = createSignatureBase(message, components, params, { fieldTypes });
+  const signatureBytes = await signBase(alg, key, base);
+
+  const inner = components.map(normalizeComponent).map(({ id, params: p }) => ({
+    value: id.toLowerCase(),
+    parameters: p,
+  }));
+  const signatureInput = serialize(
+    { [label]: { value: inner, parameters: params } },
+    "dictionary"
+  );
+  const signature = serialize(
+    { [label]: { value: binary(bytesToB64(signatureBytes)), parameters: {} } },
+    "dictionary"
+  );
+
+  return { signatureInput, signature, base, label };
+};
+
+/**
+ * Verify the signatures on an HTTP message (RFC 9421).
+ *
+ * Reads `Signature-Input`/`Signature` from message.headers unless provided
+ * via options. Structural problems throw; cryptographic mismatch and policy
+ * failures report as verified:false with a reason.
+ *
+ * @param {object} message
+ * @param {object} options
+ * @param {(context: {label: string, keyid?: string, alg?: string}) =>
+ *   (object|Promise<object>)} options.getKey - resolves {alg, key} (or just a
+ *   key when the signature's alg parameter should be trusted) for a signature
+ * @param {string} [options.label] - verify only this label
+ * @param {string} [options.signatureInput] - override header lookup
+ * @param {string} [options.signature] - override header lookup
+ * @param {number} [options.now=now] - unix seconds for expires checking
+ * @param {object} [options.fieldTypes]
+ * @returns {Promise<Array<{label: string, verified: boolean, reason?: string,
+ *   params: object, components: Array<{id, params}>}>>}
+ */
+export const verifyMessage = async (message, options) => {
+  const {
+    getKey,
+    label: onlyLabel,
+    now = Math.floor(Date.now() / 1000),
+    fieldTypes,
+  } = options;
+
+  const signatureInput =
+    options.signatureInput ??
+    getHeaderValues(message.headers, "signature-input").join(", ");
+  const signature =
+    options.signature ?? getHeaderValues(message.headers, "signature").join(", ");
+  if (!signatureInput) throw new Error("No Signature-Input to verify");
+
+  const entries = parseSignatureHeaders(signatureInput, signature || undefined);
+  const results = [];
+
+  for (const [label, entry] of Object.entries(entries)) {
+    if (onlyLabel && label !== onlyLabel) continue;
+    if (!entry.components) {
+      results.push({
+        label,
+        verified: false,
+        reason: "No Signature-Input for this label",
+        params: {},
+        components: [],
+      });
+      continue;
+    }
+    const { components, params } = entry;
+    const result = { label, verified: false, params, components };
+    results.push(result);
+
+    if (!entry.signature) {
+      result.reason = "No Signature value for this label";
+      continue;
+    }
+    if (Number.isInteger(params.expires) && params.expires < now) {
+      result.reason = "Signature expired";
+      continue;
+    }
+
+    const resolved = await getKey({
+      label,
+      keyid: typeof params.keyid === "string" ? params.keyid : undefined,
+      alg: typeof params.alg === "string" ? params.alg : undefined,
+    });
+    if (!resolved) {
+      result.reason = "Key not found";
+      continue;
+    }
+    const alg = resolved.alg ?? params.alg;
+    const key = resolved.key ?? resolved;
+    if (!ALGORITHMS[alg]) {
+      result.reason = `Unsupported algorithm: ${alg}`;
+      continue;
+    }
+
+    const { base } = createSignatureBase(message, components, params, {
+      fieldTypes,
+    });
+    const ok = await verifyBase(alg, key, entry.signature, base);
+    result.verified = ok;
+    if (!ok) result.reason = "Signature mismatch";
+  }
+
+  if (onlyLabel && results.length === 0) {
+    throw new Error(`No signature labeled "${onlyLabel}" found`);
+  }
+  return results;
+};

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@johnhenry/http-fields-signatures",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "RFC 9421 HTTP Message Signatures — sign and verify HTTP requests and responses, built on http-fields (RFC 8941/9651 Structured Field Values) and WebCrypto",
+  "main": "index.mjs",
+  "type": "module",
+  "types": "./types.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types.d.ts",
+      "import": "./index.mjs"
+    }
+  },
+  "scripts": {
+    "test": "node --test test/*.mjs"
+  },
+  "keywords": [
+    "http",
+    "signatures",
+    "message-signatures",
+    "rfc9421",
+    "@johnhenry/http-fields",
+    "structured-fields",
+    "rfc8941",
+    "webcrypto",
+    "signing",
+    "verification",
+    "zero-dependencies"
+  ],
+  "author": "John Henry <john@iamjohnhenry.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johnhenry/http-fields-signatures.git"
+  },
+  "bugs": {
+    "url": "https://github.com/johnhenry/http-fields-signatures/issues"
+  },
+  "homepage": "https://github.com/johnhenry/http-fields-signatures#readme",
+  "files": [
+    "index.mjs",
+    "base.mjs",
+    "crypto.mjs",
+    "types.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=26.0.0"
+  },
+  "dependencies": {
+    "@johnhenry/http-fields": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/types.d.ts

@@ -0,0 +1,174 @@
+// Type definitions for @johnhenry/http-fields-signatures
+// Project: https://github.com/johnhenry/http-fields-signatures
+
+/** HTTP request message (runtime-agnostic). */
+export interface RequestMessage {
+  method: string;
+  /** Absolute URL. */
+  url: string;
+  headers: HeadersLike;
+}
+
+/** HTTP response message. `request` enables `;req`-flagged components. */
+export interface ResponseMessage {
+  status: number;
+  headers: HeadersLike;
+  request?: RequestMessage;
+}
+
+export type Message = RequestMessage | ResponseMessage;
+
+/** Plain object, entries array, or Fetch-style Headers. */
+export type HeadersLike =
+  | Record<string, string | string[]>
+  | Array<[string, string]>
+  | { entries(): IterableIterator<[string, string]>; get(name: string): string | null };
+
+/** Covered component: a bare id or an id with identifier parameters. */
+export type ComponentSpec =
+  | string
+  | {
+      id: string;
+      params?: {
+        /** @query-param: the (re-encoded) parameter name. */
+        name?: string;
+        /** Field: select a dictionary member. */
+        key?: string;
+        /** Field: strict structured-field re-serialization. */
+        sf?: boolean;
+        /** Field: wrap raw value(s) as byte sequences. */
+        bs?: boolean;
+        /** Response signing: take the component from the related request. */
+        req?: boolean;
+      };
+    };
+
+export interface Component {
+  id: string;
+  params: Record<string, unknown>;
+}
+
+/** created/expires/nonce/alg/keyid/tag, serialized in insertion order. */
+export type SignatureParams = Record<string, unknown>;
+
+export type FieldTypes = Record<string, "list" | "dictionary" | "item">;
+
+/** JWK object, PEM string (PKCS#8/SPKI), raw bytes (HMAC), or a CryptoKey. */
+export type KeyMaterial = CryptoKey | object | string | Uint8Array;
+
+export type AlgorithmName =
+  | "rsa-pss-sha512"
+  | "rsa-v1_5-sha256"
+  | "ecdsa-p256-sha256"
+  | "ecdsa-p384-sha384"
+  | "ed25519"
+  | "hmac-sha256";
+
+export declare const ALGORITHMS: Record<
+  AlgorithmName,
+  { importParams: object; signParams: object }
+>;
+
+export declare function createSignatureBase(
+  message: Message,
+  components: ComponentSpec[],
+  signatureParams: SignatureParams,
+  options?: { fieldTypes?: FieldTypes }
+): { base: string; signatureParamsValue: string };
+
+export declare function getHeaderValues(
+  headers: HeadersLike,
+  name: string
+): string[];
+
+/**
+ * Wrap SEC1 "EC PRIVATE KEY" DER bytes in a PKCS#8 envelope so WebCrypto can
+ * import them. Pure ASN.1 re-packaging; no cryptography involved.
+ */
+export declare function sec1ToPkcs8(
+  sec1: Uint8Array,
+  namedCurve?: "P-256" | "P-384" | "P-521"
+): Uint8Array;
+
+export declare function importKey(
+  alg: AlgorithmName,
+  material: KeyMaterial,
+  usage: "sign" | "verify"
+): Promise<CryptoKey>;
+
+export declare function signBase(
+  alg: AlgorithmName,
+  key: KeyMaterial,
+  base: string
+): Promise<Uint8Array>;
+
+export declare function verifyBase(
+  alg: AlgorithmName,
+  key: KeyMaterial,
+  signature: Uint8Array,
+  base: string
+): Promise<boolean>;
+
+export declare function parseSignatureHeaders(
+  signatureInput?: string,
+  signature?: string
+): Record<
+  string,
+  { components?: Component[]; params?: SignatureParams; signature?: Uint8Array }
+>;
+
+export interface SignOptions {
+  alg: AlgorithmName;
+  key: KeyMaterial;
+  components?: ComponentSpec[];
+  label?: string;
+  keyid?: string;
+  /** Unix seconds; defaults to now. Pass null to omit. */
+  created?: number | null;
+  expires?: number;
+  nonce?: string;
+  tag?: string;
+  /** Include the alg parameter in Signature-Input (default false). */
+  includeAlg?: boolean;
+  fieldTypes?: FieldTypes;
+}
+
+export declare function signMessage(
+  message: Message,
+  options: SignOptions
+): Promise<{
+  signatureInput: string;
+  signature: string;
+  base: string;
+  label: string;
+}>;
+
+export interface VerifyResult {
+  label: string;
+  verified: boolean;
+  reason?: string;
+  params: SignatureParams;
+  components: Component[];
+}
+
+export interface VerifyOptions {
+  getKey: (context: {
+    label: string;
+    keyid?: string;
+    alg?: string;
+  }) =>
+    | KeyMaterial
+    | { alg?: AlgorithmName; key: KeyMaterial }
+    | Promise<KeyMaterial | { alg?: AlgorithmName; key: KeyMaterial }>;
+  label?: string;
+  signatureInput?: string;
+  signature?: string;
+  /** Unix seconds used for expires checking; defaults to now. */
+  now?: number;
+  fieldTypes?: FieldTypes;
+}
+
+export declare function verifyMessage(
+  message: Message,
+  options: VerifyOptions
+): Promise<VerifyResult[]>;