@dwk/http-signatures 0.1.0-beta.0

package/src/digest.ts

@@ -0,0 +1,156 @@
+/**
+ * Body integrity headers.
+ *
+ * - `Content-Digest` (RFC 9530) — a structured-field dictionary whose values
+ *   are byte sequences, e.g. `sha-256=:<base64>:`.
+ * - `Digest` (the legacy RFC 3230 field much of the fediverse still sends),
+ *   e.g. `SHA-256=<base64>`.
+ *
+ * Including a digest in the covered component set is how body tampering is
+ * caught: the signature covers the digest header value, and recomputing the
+ * digest over the received body proves that value still describes the body.
+ */
+
+import { base64ToBytes, bytesToBase64 } from "./base64";
+import { parseByteSequenceDictionary, SfParseError } from "./sf";
+
+/** Hash algorithms supported for digests. */
+export type DigestAlgorithm = "sha-256" | "sha-512";
+
+const SUBTLE_HASH: Record<DigestAlgorithm, string> = {
+  "sha-256": "SHA-256",
+  "sha-512": "SHA-512",
+};
+
+function toBytes(body: Uint8Array | string): Uint8Array {
+  return typeof body === "string" ? new TextEncoder().encode(body) : body;
+}
+
+async function hashBytes(
+  body: Uint8Array | string,
+  alg: DigestAlgorithm,
+): Promise<Uint8Array> {
+  const digest = await crypto.subtle.digest(SUBTLE_HASH[alg], toBytes(body));
+  return new Uint8Array(digest);
+}
+
+async function hash(
+  body: Uint8Array | string,
+  alg: DigestAlgorithm,
+): Promise<string> {
+  return bytesToBase64(await hashBytes(body, alg));
+}
+
+/**
+ * Compute the RFC 9530 `Content-Digest` field value for `body`, e.g.
+ * `sha-256=:<base64>:`. The result is meant to be set as the `content-digest`
+ * header and listed among the covered components before signing.
+ */
+export async function createContentDigest(
+  body: Uint8Array | string,
+  alg: DigestAlgorithm = "sha-256",
+): Promise<string> {
+  return `${alg}=:${await hash(body, alg)}:`;
+}
+
+/**
+ * Compute the legacy RFC 3230 `Digest` field value for `body`, e.g.
+ * `SHA-256=<base64>` — the spelling fediverse peers expect on the `Digest`
+ * header alongside a `draft-cavage` signature.
+ */
+export async function createDigest(
+  body: Uint8Array | string,
+  alg: DigestAlgorithm = "sha-256",
+): Promise<string> {
+  return `${alg.toUpperCase()}=${await hash(body, alg)}`;
+}
+
+/** A reason a digest header failed to verify, or `null` when it matched. */
+export type DigestRejection =
+  | "digest_missing"
+  | "digest_unsupported"
+  | "digest_mismatch";
+
+/**
+ * Verify a received `Content-Digest` field value against `body`. The field is
+ * an RFC 8941 Dictionary of Byte Sequences (RFC 9530 §2), so it is parsed with
+ * the strict structured-fields parser rather than split by hand: a malformed
+ * value — including a lone uppercase algorithm key, which is not a valid sf-key
+ * — fails closed as `digest_mismatch`. Per RFC 9530 §3, entries whose algorithm
+ * the verifier does not support are ignored; every supported entry must match,
+ * and at least one supported entry must be present (otherwise the value is
+ * rejected as `digest_unsupported`).
+ */
+export async function verifyContentDigest(
+  headerValue: string | null | undefined,
+  body: Uint8Array | string,
+): Promise<DigestRejection | null> {
+  if (!headerValue) return "digest_missing";
+  let dict: Map<string, Uint8Array>;
+  try {
+    dict = parseByteSequenceDictionary(headerValue);
+  } catch (err) {
+    if (err instanceof SfParseError) return "digest_mismatch";
+    throw err;
+  }
+  let sawSupported = false;
+  for (const [key, received] of dict) {
+    if (!(key in SUBTLE_HASH)) continue;
+    const alg = key as DigestAlgorithm;
+    if (!constantTimeEqualBytes(received, await hashBytes(body, alg))) {
+      return "digest_mismatch";
+    }
+    sawSupported = true;
+  }
+  return sawSupported ? null : "digest_unsupported";
+}
+
+/**
+ * Verify a received legacy `Digest` field value (`SHA-256=<base64>`, no colon
+ * wrapping) against `body`.
+ */
+export async function verifyDigest(
+  headerValue: string | null | undefined,
+  body: Uint8Array | string,
+): Promise<DigestRejection | null> {
+  if (!headerValue) return "digest_missing";
+  let sawSupported = false;
+  for (const entry of headerValue.split(",")) {
+    const eq = entry.indexOf("=");
+    if (eq < 0) continue;
+    const alg = entry.slice(0, eq).trim().toLowerCase() as DigestAlgorithm;
+    if (!(alg in SUBTLE_HASH)) continue;
+    const value = entry.slice(eq + 1).trim();
+    if (!constantTimeEqualBase64(value, await hash(body, alg))) {
+      return "digest_mismatch";
+    }
+    sawSupported = true;
+  }
+  return sawSupported ? null : "digest_unsupported";
+}
+
+/** Compare two byte arrays in length-constant time. */
+function constantTimeEqualBytes(x: Uint8Array, y: Uint8Array): boolean {
+  if (x.length !== y.length) return false;
+  let diff = 0;
+  for (let i = 0; i < x.length; i++) {
+    diff |= x[i]! ^ y[i]!;
+  }
+  return diff === 0;
+}
+
+/**
+ * Compare two base64 strings by their decoded bytes in length-constant time.
+ * A malformed encoding compares unequal rather than throwing.
+ */
+function constantTimeEqualBase64(a: string, b: string): boolean {
+  let x: Uint8Array;
+  let y: Uint8Array;
+  try {
+    x = base64ToBytes(a);
+    y = base64ToBytes(b);
+  } catch {
+    return false;
+  }
+  return constantTimeEqualBytes(x, y);
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+/**
+ * `@dwk/http-signatures` — HTTP Message Signatures (RFC 9421), with the legacy
+ * `draft-cavage-http-signatures` profile for fediverse interop.
+ *
+ * A pure, runtime-agnostic library: a request reduced to plain data (method,
+ * URL, headers) plus a resolved {@link CryptoKey} goes in, a signing result or a
+ * {@link VerifyResult} comes out. It performs no I/O beyond Web Crypto, holds no
+ * state, and needs no Cloudflare bindings, so it unit-tests without a Workers
+ * runtime.
+ *
+ * It is **protocol-agnostic** — it knows nothing about ActivityPub, IndieWeb, or
+ * Solid. Key resolution (fetching an actor's public key, caching it) is the
+ * caller's responsibility, supplied as a {@link KeyResolver}. Mirroring the
+ * `@dwk/dpop` hardening posture, only asymmetric algorithms from an explicit
+ * allow-list are accepted — never `none` or HMAC — and a resolved key is
+ * validated against the claimed algorithm (RSA modulus floor, EC curve) before
+ * any signature is checked.
+ *
+ * @see spec/packages/http-signatures.md
+ * @packageDocumentation
+ */
+
+export { signMessage, type SignParams } from "./sign";
+export { verifyMessage, type VerifyParams } from "./verify";
+
+export type { KeyResolver } from "./rfc9421";
+
+export {
+  createContentDigest,
+  createDigest,
+  verifyContentDigest,
+  verifyDigest,
+  type DigestAlgorithm,
+  type DigestRejection,
+} from "./digest";
+
+export { isSupportedAlgorithm } from "./algorithms";
+
+export type {
+  HttpMessage,
+  SignatureAlgorithm,
+  SignatureProfile,
+  SignatureFailureReason,
+  VerifyResult,
+} from "./types";

package/src/rfc9421.ts

@@ -0,0 +1,280 @@
+/**
+ * The RFC 9421 wire profile: the `Signature-Input` / `Signature`
+ * structured-field pair, the signature base of §2.5, and the `@signature-params`
+ * line.
+ */
+
+import {
+  deriveAlgFromKey,
+  isSupportedAlgorithm,
+  signBytes,
+  validateKey,
+  verifyBytes,
+} from "./algorithms";
+import { bytesToBase64, utf8 } from "./base64";
+import { deriveComponentValue, derivationContext } from "./components";
+import {
+  parseSignatureHeader,
+  parseSignatureInput,
+  serializeString,
+  type SfBareItem,
+} from "./sf";
+import type {
+  HttpMessage,
+  SignatureAlgorithm,
+  SignatureFailureReason,
+  VerifyResult,
+} from "./types";
+
+/** Resolved signing inputs for the RFC 9421 profile. */
+export interface Rfc9421SignParams {
+  key: CryptoKey;
+  keyId: string;
+  alg: SignatureAlgorithm;
+  components: string[];
+  created: number;
+  expires?: number;
+  nonce?: string;
+  tag?: string;
+  label: string;
+}
+
+/** Build the `@signature-params` value (inner list plus its parameters). */
+function signatureParamsValue(params: Rfc9421SignParams): string {
+  const items = params.components.map(serializeString).join(" ");
+  let out = `(${items});created=${params.created}`;
+  if (params.expires !== undefined) out += `;expires=${params.expires}`;
+  out += `;keyid=${serializeString(params.keyId)}`;
+  out += `;alg=${serializeString(params.alg)}`;
+  if (params.nonce !== undefined)
+    out += `;nonce=${serializeString(params.nonce)}`;
+  if (params.tag !== undefined) out += `;tag=${serializeString(params.tag)}`;
+  return out;
+}
+
+/** Build the signature base over `lines` and the `@signature-params` value. */
+function signatureBase(lines: string[], sigParams: string): string {
+  return [...lines, `"@signature-params": ${sigParams}`].join("\n");
+}
+
+/**
+ * Sign `message` under the RFC 9421 profile. Returns the `Signature-Input` and
+ * `Signature` headers to merge into the request. Throws if a covered component
+ * is absent from the message or the URL cannot be parsed — both signer bugs.
+ */
+export async function signRfc9421(
+  message: HttpMessage,
+  params: Rfc9421SignParams,
+): Promise<Record<string, string>> {
+  const ctx = derivationContext(message);
+  if (ctx === null)
+    throw new Error("http-signatures: message.url is not a valid URL");
+  const sigParams = signatureParamsValue(params);
+  const lines: string[] = [];
+  // RFC 9421 §2: each component identifier MUST occur only once in the covered
+  // component list. A repeated identifier is a signer bug — reject it loudly.
+  const seen = new Set<string>();
+  for (const name of params.components) {
+    const id = name.toLowerCase();
+    if (seen.has(id)) {
+      throw new Error(
+        `http-signatures: duplicate covered component "${name}" (RFC 9421 §2)`,
+      );
+    }
+    seen.add(id);
+    const value = deriveComponentValue(ctx, name);
+    if (value === null) {
+      throw new Error(
+        `http-signatures: covered component "${name}" is missing from the message`,
+      );
+    }
+    lines.push(`${serializeString(name)}: ${value}`);
+  }
+  const signature = await signBytes(
+    params.key,
+    params.alg,
+    utf8(signatureBase(lines, sigParams)),
+  );
+  return {
+    "Signature-Input": `${params.label}=${sigParams}`,
+    Signature: `${params.label}=:${bytesToBase64(new Uint8Array(signature))}:`,
+  };
+}
+
+/** Resolves a public key (and optionally the algorithm it dictates) for verification. */
+export type KeyResolver = (params: {
+  keyId: string | null;
+  alg: SignatureAlgorithm | null;
+}) => Promise<CryptoKey | null> | (CryptoKey | null);
+
+/** Parameters for verifying an RFC 9421 signature. */
+export interface Rfc9421VerifyParams {
+  resolveKey: KeyResolver;
+  /** Which labelled signature to verify; required when the message carries more than one. */
+  label?: string;
+  /** Component identifiers that MUST be covered (e.g. `@method`, `date`). */
+  requiredComponents?: string[];
+  /** Require a `created` parameter to be present. */
+  requireCreated?: boolean;
+  /** Current time, epoch seconds. Defaults to `Date.now()`. */
+  now?: number;
+  /** Allowed clock skew, in seconds, for `created`/`expires`. Defaults to 300. */
+  toleranceSeconds?: number;
+}
+
+function paramMap(
+  params: Array<[string, SfBareItem]>,
+): Map<string, SfBareItem> {
+  const map = new Map<string, SfBareItem>();
+  for (const [k, v] of params) map.set(k, v);
+  return map;
+}
+
+function getHeader(message: HttpMessage, name: string): string | null {
+  const lower = name.toLowerCase();
+  for (const [k, v] of Object.entries(message.headers)) {
+    if (k.toLowerCase() === lower) return Array.isArray(v) ? v.join(", ") : v;
+  }
+  return null;
+}
+
+function fail(reason: SignatureFailureReason): VerifyResult {
+  return { valid: false, profile: "rfc9421", reason };
+}
+
+const DEFAULT_TOLERANCE_SECONDS = 300;
+
+/**
+ * Verify an RFC 9421 signature on `message`. Never throws — every failure is a
+ * `{ valid: false, reason }` with a stable {@link SignatureFailureReason}.
+ */
+export async function verifyRfc9421(
+  message: HttpMessage,
+  params: Rfc9421VerifyParams,
+): Promise<VerifyResult> {
+  const inputHeader = getHeader(message, "signature-input");
+  const sigHeader = getHeader(message, "signature");
+  if (inputHeader === null || sigHeader === null)
+    return fail("signature_missing");
+
+  let inputs: ReturnType<typeof parseSignatureInput>;
+  let signatures: ReturnType<typeof parseSignatureHeader>;
+  try {
+    inputs = parseSignatureInput(inputHeader);
+  } catch {
+    return fail("signature_input_malformed");
+  }
+  try {
+    signatures = parseSignatureHeader(sigHeader);
+  } catch {
+    return fail("signature_malformed");
+  }
+
+  // Choose the label to verify.
+  let label = params.label;
+  if (label === undefined) {
+    if (inputs.size === 0) return fail("label_missing");
+    if (inputs.size > 1) return fail("label_ambiguous");
+    label = [...inputs.keys()][0]!;
+  }
+  const input = inputs.get(label);
+  if (input === undefined) return fail("label_missing");
+  const signature = signatures.get(label);
+  if (signature === undefined) return fail("signature_missing");
+
+  const sigParams = paramMap(input.params);
+  // RFC 9421 §2.3: `alg` is OPTIONAL. When present it must be allow-listed;
+  // when absent the algorithm is derived from the resolved key below.
+  const algRaw = sigParams.get("alg");
+  let alg: SignatureAlgorithm | null = null;
+  if (algRaw !== undefined) {
+    if (typeof algRaw !== "string" || !isSupportedAlgorithm(algRaw)) {
+      return fail("alg_unsupported");
+    }
+    alg = algRaw;
+  }
+  const keyIdRaw = sigParams.get("keyid");
+  const keyId = typeof keyIdRaw === "string" ? keyIdRaw : null;
+  if (keyId === null) return fail("keyid_missing");
+
+  // created / expires window.
+  const now = params.now ?? Math.floor(Date.now() / 1000);
+  const tolerance = params.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+  let created: number | undefined;
+  if (sigParams.has("created")) {
+    const c = sigParams.get("created");
+    if (typeof c !== "number" || !Number.isInteger(c))
+      return fail("created_invalid");
+    created = c;
+    if (c > now + tolerance) return fail("signature_future");
+  } else if (params.requireCreated) {
+    return fail("created_required");
+  }
+  let expires: number | undefined;
+  if (sigParams.has("expires")) {
+    const e = sigParams.get("expires");
+    if (typeof e !== "number" || !Number.isInteger(e))
+      return fail("expires_invalid");
+    expires = e;
+    if (now > e + tolerance) return fail("signature_expired");
+  }
+  // RFC 9421 §2.3: `expires` MUST NOT precede `created`.
+  if (created !== undefined && expires !== undefined && expires < created) {
+    return fail("expires_invalid");
+  }
+
+  const coveredComponents = input.items.map((item) => String(item.value));
+
+  // Required-component policy.
+  if (params.requiredComponents) {
+    const covered = new Set(coveredComponents.map((c) => c.toLowerCase()));
+    for (const required of params.requiredComponents) {
+      if (!covered.has(required.toLowerCase()))
+        return fail("required_component_missing");
+    }
+  }
+
+  // Rebuild the signature base from the named components.
+  const ctx = derivationContext(message);
+  if (ctx === null) return fail("covered_component_missing");
+  const lines: string[] = [];
+  // RFC 9421 §2 / §2.5: each component identifier (name plus its serialized
+  // parameters) MUST occur only once; a repeated identifier is malformed.
+  const seen = new Set<string>();
+  for (const item of input.items) {
+    if (item.params.length > 0 || typeof item.value !== "string") {
+      return fail("components_malformed");
+    }
+    const id = item.value.toLowerCase();
+    if (seen.has(id)) return fail("components_malformed");
+    seen.add(id);
+    const value = deriveComponentValue(ctx, item.value);
+    if (value === null) return fail("covered_component_missing");
+    lines.push(`${item.raw}: ${value}`);
+  }
+  const base = [...lines, `"@signature-params": ${input.raw}`].join("\n");
+
+  // Resolve and validate the key, then verify. When `alg` was omitted, derive
+  // it from the resolved key's type (RFC 9421 §2.3).
+  const key = await params.resolveKey({ keyId, alg });
+  if (key === null) return fail("key_unresolved");
+  if (alg === null) {
+    alg = deriveAlgFromKey(key);
+    if (alg === null) return fail("alg_unsupported");
+  }
+  const rejection = validateKey(key, alg);
+  if (rejection !== null) return fail(rejection);
+
+  const ok = await verifyBytes(key, alg, signature, utf8(base));
+  if (!ok) return fail("signature_invalid");
+
+  return {
+    valid: true,
+    profile: "rfc9421",
+    label,
+    keyId,
+    coveredComponents,
+    created,
+    expires,
+  };
+}