@dwk/http-signatures 0.1.0-beta.0

package/src/algorithms.ts

@@ -0,0 +1,168 @@
+/**
+ * Algorithm allow-list and the Web Crypto primitives that back it.
+ *
+ * Mirrors the `@dwk/dpop` hardening posture: asymmetric algorithms only, an
+ * explicit allow-list (no `none`, no HMAC), and the resolved key is validated
+ * against the claimed algorithm — RSA moduli below 2048 bits and curve
+ * mismatches are rejected before any signature is checked.
+ */
+
+import type { SignatureAlgorithm } from "./types";
+
+// Structural shapes for Web Crypto algorithm parameters. We avoid the DOM lib
+// names (RsaPssParams, EcdsaParams, …) because @cloudflare/workers-types does
+// not declare them; these objects are accepted structurally by crypto.subtle.
+interface ImportAlg {
+  name: string;
+  namedCurve?: string;
+  hash?: string;
+}
+interface SignVerifyAlg {
+  name: string;
+  hash?: string;
+  saltLength?: number;
+}
+
+interface AlgSpec {
+  /** Web Crypto key algorithm name the resolved key must report. */
+  keyName: string;
+  /** For EC algorithms, the curve the resolved key must use. */
+  expectedCurve?: string;
+  /** Whether the key type is RSA (so the 2048-bit floor applies). */
+  rsa: boolean;
+  importParams: ImportAlg;
+  signParams: SignVerifyAlg;
+}
+
+const ALGS: Record<SignatureAlgorithm, AlgSpec> = {
+  "rsa-pss-sha512": {
+    keyName: "RSA-PSS",
+    rsa: true,
+    importParams: { name: "RSA-PSS", hash: "SHA-512" },
+    signParams: { name: "RSA-PSS", saltLength: 64 },
+  },
+  "rsa-v1_5-sha256": {
+    keyName: "RSASSA-PKCS1-v1_5",
+    rsa: true,
+    importParams: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+    signParams: { name: "RSASSA-PKCS1-v1_5" },
+  },
+  "ecdsa-p256-sha256": {
+    keyName: "ECDSA",
+    expectedCurve: "P-256",
+    rsa: false,
+    importParams: { name: "ECDSA", namedCurve: "P-256" },
+    signParams: { name: "ECDSA", hash: "SHA-256" },
+  },
+  "ecdsa-p384-sha384": {
+    keyName: "ECDSA",
+    expectedCurve: "P-384",
+    rsa: false,
+    importParams: { name: "ECDSA", namedCurve: "P-384" },
+    signParams: { name: "ECDSA", hash: "SHA-384" },
+  },
+  ed25519: {
+    keyName: "Ed25519",
+    rsa: false,
+    importParams: { name: "Ed25519" },
+    signParams: { name: "Ed25519" },
+  },
+};
+
+/** Minimum accepted RSA modulus size, in bits. */
+const MIN_RSA_KEY_BITS = 2048;
+
+/** Whether `alg` is in the allow-list. */
+export function isSupportedAlgorithm(alg: string): alg is SignatureAlgorithm {
+  return Object.prototype.hasOwnProperty.call(ALGS, alg);
+}
+
+/** The reasons {@link validateKey} can reject a key, or `null` when it is sound. */
+export type KeyRejection = "key_alg_mismatch" | "key_too_small";
+
+// The subset of CryptoKey.algorithm members we inspect. Declared structurally
+// for the same reason as the param shapes above.
+interface KeyAlgorithm {
+  name: string;
+  modulusLength?: number;
+  namedCurve?: string;
+}
+
+/**
+ * Validate that a resolved {@link CryptoKey} matches the claimed algorithm:
+ * the key's algorithm name and EC curve must line up, and RSA moduli must meet
+ * the {@link MIN_RSA_KEY_BITS} floor. Returns `null` when the key is acceptable.
+ */
+export function validateKey(
+  key: CryptoKey,
+  alg: SignatureAlgorithm,
+): KeyRejection | null {
+  const spec = ALGS[alg];
+  const keyAlg = key.algorithm as KeyAlgorithm;
+  if (keyAlg.name !== spec.keyName) {
+    return "key_alg_mismatch";
+  }
+  if (spec.expectedCurve && keyAlg.namedCurve !== spec.expectedCurve) {
+    return "key_alg_mismatch";
+  }
+  if (
+    spec.rsa &&
+    typeof keyAlg.modulusLength === "number" &&
+    keyAlg.modulusLength < MIN_RSA_KEY_BITS
+  ) {
+    return "key_too_small";
+  }
+  return null;
+}
+
+/**
+ * Derive the signature algorithm implied by a resolved key's type. Used when a
+ * signature omits its algorithm (RFC 9421 `alg` is OPTIONAL; the legacy
+ * `hs2019` token is intentionally key-derived). Returns `null` for a key type
+ * outside the allow-list.
+ */
+export function deriveAlgFromKey(key: CryptoKey): SignatureAlgorithm | null {
+  const a = key.algorithm as KeyAlgorithm;
+  switch (a.name) {
+    case "RSA-PSS":
+      return "rsa-pss-sha512";
+    case "RSASSA-PKCS1-v1_5":
+      return "rsa-v1_5-sha256";
+    case "ECDSA":
+      return a.namedCurve === "P-384"
+        ? "ecdsa-p384-sha384"
+        : "ecdsa-p256-sha256";
+    case "Ed25519":
+      return "ed25519";
+    default:
+      return null;
+  }
+}
+
+/** Sign `data` with `key` under `alg`. */
+export function signBytes(
+  key: CryptoKey,
+  alg: SignatureAlgorithm,
+  data: Uint8Array,
+): Promise<ArrayBuffer> {
+  return crypto.subtle.sign(ALGS[alg].signParams, key, data);
+}
+
+/** Verify `signature` over `data` with `key` under `alg`. Never throws. */
+export async function verifyBytes(
+  key: CryptoKey,
+  alg: SignatureAlgorithm,
+  signature: Uint8Array,
+  data: Uint8Array,
+): Promise<boolean> {
+  try {
+    return await crypto.subtle.verify(
+      ALGS[alg].signParams,
+      key,
+      signature,
+      data,
+    );
+  } catch {
+    return false;
+  }
+}

package/src/base64.ts

@@ -0,0 +1,25 @@
+/** Base64 (standard, padded) <-> bytes, plus base64url helpers. */
+
+/** Decode standard padded base64 to bytes. Throws on invalid input. */
+export function base64ToBytes(b64: string): Uint8Array {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+/** Encode bytes as standard padded base64. */
+export function bytesToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+
+/** Encode a UTF-8 string to bytes. */
+export function utf8(input: string): Uint8Array {
+  return new TextEncoder().encode(input);
+}

package/src/cavage.ts

@@ -0,0 +1,292 @@
+/**
+ * The legacy `draft-cavage-http-signatures` "Signature" profile that much of
+ * the fediverse still emits. A single `Signature` header carries the `keyId`,
+ * `algorithm`, the space-separated `headers` list, and the base64 `signature`;
+ * the signing string is the `headers` components joined by newlines, where
+ * `(request-target)`, `(created)`, and `(expires)` are pseudo-headers.
+ */
+
+import {
+  deriveAlgFromKey,
+  isSupportedAlgorithm,
+  signBytes,
+  validateKey,
+  verifyBytes,
+} from "./algorithms";
+import { base64ToBytes, bytesToBase64, utf8 } from "./base64";
+import { derivationContext, type DerivationContext } from "./components";
+import type { KeyResolver } from "./rfc9421";
+import type {
+  HttpMessage,
+  SignatureAlgorithm,
+  SignatureFailureReason,
+  VerifyResult,
+} from "./types";
+
+/** Map our algorithm identifiers to a `draft-cavage` `algorithm` token. */
+const CAVAGE_TOKEN: Record<SignatureAlgorithm, string> = {
+  "rsa-v1_5-sha256": "rsa-sha256",
+  "rsa-pss-sha512": "hs2019",
+  "ecdsa-p256-sha256": "ecdsa-sha256",
+  "ecdsa-p384-sha384": "ecdsa-sha384",
+  ed25519: "ed25519",
+};
+
+/** Map a `draft-cavage` `algorithm` token to our identifier, or `null` for `hs2019`. */
+function tokenToAlg(token: string): SignatureAlgorithm | "derive" | null {
+  switch (token.toLowerCase()) {
+    case "rsa-sha256":
+      return "rsa-v1_5-sha256";
+    case "ecdsa-sha256":
+      return "ecdsa-p256-sha256";
+    case "ecdsa-sha384":
+      return "ecdsa-p384-sha384";
+    case "ed25519":
+      return "ed25519";
+    case "hs2019":
+      return "derive";
+    default:
+      return null;
+  }
+}
+
+/** Build the `draft-cavage` signing string, or report the first missing component. */
+function buildSigningString(
+  ctx: DerivationContext,
+  components: string[],
+  times: { created?: number; expires?: number },
+): { string: string } | { missing: string } {
+  const lines: string[] = [];
+  for (const raw of components) {
+    const name = raw.toLowerCase();
+    let value: string | null;
+    if (name === "(request-target)") {
+      value = `${ctx.message.method.toLowerCase()} ${ctx.url.pathname}${ctx.url.search}`;
+    } else if (name === "(created)") {
+      value = times.created === undefined ? null : String(times.created);
+    } else if (name === "(expires)") {
+      value = times.expires === undefined ? null : String(times.expires);
+    } else {
+      value = ctx.headers.get(name) ?? null;
+    }
+    if (value === null) return { missing: name };
+    lines.push(`${name}: ${value}`);
+  }
+  return { string: lines.join("\n") };
+}
+
+/** Resolved signing inputs for the `draft-cavage` profile. */
+export interface CavageSignParams {
+  key: CryptoKey;
+  keyId: string;
+  alg: SignatureAlgorithm;
+  /** Cavage-style component names, e.g. `["(request-target)", "host", "date", "digest"]`. */
+  components: string[];
+  created?: number;
+  expires?: number;
+}
+
+/**
+ * Sign `message` under the `draft-cavage` profile. Returns the single
+ * `Signature` header to merge into the request. Throws if a covered component
+ * is absent — a signer bug.
+ */
+export async function signCavage(
+  message: HttpMessage,
+  params: CavageSignParams,
+): Promise<Record<string, string>> {
+  const ctx = derivationContext(message);
+  if (ctx === null)
+    throw new Error("http-signatures: message.url is not a valid URL");
+  const built = buildSigningString(ctx, params.components, {
+    created: params.created,
+    expires: params.expires,
+  });
+  if ("missing" in built) {
+    throw new Error(
+      `http-signatures: covered component "${built.missing}" is missing from the message`,
+    );
+  }
+  const signature = await signBytes(params.key, params.alg, utf8(built.string));
+  const parts = [
+    `keyId="${params.keyId}"`,
+    `algorithm="${CAVAGE_TOKEN[params.alg]}"`,
+    `headers="${params.components.map((c) => c.toLowerCase()).join(" ")}"`,
+    `signature="${bytesToBase64(new Uint8Array(signature))}"`,
+  ];
+  if (params.created !== undefined) parts.push(`created=${params.created}`);
+  if (params.expires !== undefined) parts.push(`expires=${params.expires}`);
+  return { Signature: parts.join(",") };
+}
+
+/** Parse a `draft-cavage` `Signature` header into its named members. */
+function parseCavageHeader(value: string): Map<string, string> {
+  const out = new Map<string, string>();
+  let i = 0;
+  while (i < value.length) {
+    while (
+      i < value.length &&
+      (value[i] === " " || value[i] === "," || value[i] === "\t")
+    )
+      i++;
+    const eq = value.indexOf("=", i);
+    if (eq < 0) break;
+    const key = value.slice(i, eq).trim();
+    i = eq + 1;
+    let raw: string;
+    if (value[i] === '"') {
+      i++;
+      let s = "";
+      while (i < value.length && value[i] !== '"') {
+        if (value[i] === "\\" && i + 1 < value.length) i++;
+        s += value[i];
+        i++;
+      }
+      i++; // closing quote
+      raw = s;
+    } else {
+      let j = i;
+      while (j < value.length && value[j] !== ",") j++;
+      raw = value.slice(i, j).trim();
+      i = j;
+    }
+    if (key) out.set(key.toLowerCase(), raw);
+  }
+  return out;
+}
+
+/** Parameters for verifying a `draft-cavage` signature. */
+export interface CavageVerifyParams {
+  resolveKey: KeyResolver;
+  requiredComponents?: string[];
+  now?: number;
+  toleranceSeconds?: number;
+}
+
+const DEFAULT_TOLERANCE_SECONDS = 300;
+
+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: "cavage", reason };
+}
+
+function parseIntegerParam(raw: string | undefined): number | null | undefined {
+  if (raw === undefined) return undefined;
+  const n = Number(raw);
+  return Number.isInteger(n) ? n : null;
+}
+
+/**
+ * Verify a `draft-cavage` signature on `message`. Never throws — failures are
+ * returned as `{ valid: false, reason }`.
+ */
+export async function verifyCavage(
+  message: HttpMessage,
+  params: CavageVerifyParams,
+): Promise<VerifyResult> {
+  const header = getHeader(message, "signature");
+  if (header === null) return fail("signature_missing");
+
+  const fields = parseCavageHeader(header);
+  const sigB64 = fields.get("signature");
+  if (sigB64 === undefined) return fail("signature_malformed");
+  let signature: Uint8Array;
+  try {
+    signature = base64ToBytes(sigB64);
+  } catch {
+    return fail("signature_malformed");
+  }
+
+  const keyId = fields.get("keyid") ?? null;
+  if (keyId === null) return fail("keyid_missing");
+
+  const token = fields.get("algorithm");
+  const createdRaw = parseIntegerParam(fields.get("created"));
+  if (createdRaw === null) return fail("created_invalid");
+  const expiresRaw = parseIntegerParam(fields.get("expires"));
+  if (expiresRaw === null) return fail("expires_invalid");
+
+  // Default covered-component list when no explicit `headers` is sent.
+  // draft-cavage-12 §2.1.6 specifies the default is `(created)` unconditionally.
+  // We deliberately diverge: when `created` is absent we fall back to `date`,
+  // matching the older "Signing HTTP Messages" rule that essentially every
+  // fediverse peer implements. In practice senders always send an explicit
+  // `headers`, so this branch is rarely reached; the divergence only affects
+  // the (non-conforming) case of a signature with neither `headers` nor
+  // `created`, where interop with real-world peers beats spec-literalism.
+  const headersList = fields.get("headers");
+  const components = headersList
+    ? headersList.split(/\s+/).filter(Boolean)
+    : createdRaw !== undefined
+      ? ["(created)"]
+      : ["date"];
+
+  // Resolve the algorithm. `hs2019` (and a missing token) defer to the key type.
+  let alg: SignatureAlgorithm | null = null;
+  if (token !== undefined) {
+    const mapped = tokenToAlg(token);
+    if (mapped === null) return fail("alg_unsupported");
+    if (mapped !== "derive") alg = mapped;
+  }
+
+  const key = await params.resolveKey({ keyId, alg });
+  if (key === null) return fail("key_unresolved");
+  if (alg === null) {
+    alg = deriveAlgFromKey(key);
+    if (alg === null || !isSupportedAlgorithm(alg))
+      return fail("alg_unsupported");
+  }
+  const rejection = validateKey(key, alg);
+  if (rejection !== null) return fail(rejection);
+
+  // created / expires window.
+  const now = params.now ?? Math.floor(Date.now() / 1000);
+  const tolerance = params.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+  if (createdRaw !== undefined && createdRaw > now + tolerance)
+    return fail("signature_future");
+  if (expiresRaw !== undefined && now > expiresRaw + tolerance)
+    return fail("signature_expired");
+  // RFC 9421 §2.3 / draft-cavage: `expires` MUST NOT precede `created`.
+  if (
+    createdRaw !== undefined &&
+    expiresRaw !== undefined &&
+    expiresRaw < createdRaw
+  )
+    return fail("expires_invalid");
+
+  // Required-component policy.
+  if (params.requiredComponents) {
+    const covered = new Set(components.map((c) => c.toLowerCase()));
+    for (const required of params.requiredComponents) {
+      if (!covered.has(required.toLowerCase()))
+        return fail("required_component_missing");
+    }
+  }
+
+  const ctx = derivationContext(message);
+  if (ctx === null) return fail("covered_component_missing");
+  const built = buildSigningString(ctx, components, {
+    created: createdRaw,
+    expires: expiresRaw,
+  });
+  if ("missing" in built) return fail("covered_component_missing");
+
+  const ok = await verifyBytes(key, alg, signature, utf8(built.string));
+  if (!ok) return fail("signature_invalid");
+
+  return {
+    valid: true,
+    profile: "cavage",
+    keyId,
+    coveredComponents: components,
+    created: createdRaw,
+    expires: expiresRaw,
+  };
+}

package/src/components.ts

@@ -0,0 +1,79 @@
+/**
+ * Covered-component value derivation (RFC 9421 §2.1–2.2), shared by the
+ * signature-base builder and the verifier.
+ *
+ * Supports the derived components needed for request signing — `@method`,
+ * `@target-uri`, `@authority`, `@scheme`, `@request-target`, `@path`,
+ * `@query` — and any HTTP header field (matched case-insensitively, with
+ * multiple field lines folded into one `", "`-joined value per §2.1).
+ * Component parameters (`;sf`, `;key`, `;bs`, `@query-param`, …) are not
+ * supported and are reported by the caller as malformed.
+ */
+
+import type { HttpMessage } from "./types";
+
+/** Build a case-insensitive view of the message's header values, OWS-trimmed. */
+function headerMap(headers: HttpMessage["headers"]): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const [name, value] of Object.entries(headers)) {
+    // RFC 9421 §2.1: strip leading/trailing OWS from each field value and join
+    // multiple values with ", ". Internal whitespace is preserved verbatim —
+    // collapsing it would change the signed value and break verification.
+    const joined = Array.isArray(value)
+      ? value.map((v) => v.trim()).join(", ")
+      : value.trim();
+    map.set(name.toLowerCase(), joined);
+  }
+  return map;
+}
+
+export interface DerivationContext {
+  message: HttpMessage;
+  url: URL;
+  headers: Map<string, string>;
+}
+
+/** Parse the message URL once and capture a normalized header view. */
+export function derivationContext(
+  message: HttpMessage,
+): DerivationContext | null {
+  let url: URL;
+  try {
+    url = new URL(message.url);
+  } catch {
+    return null;
+  }
+  return { message, url, headers: headerMap(message.headers) };
+}
+
+/**
+ * Derive the value of a single covered component. Returns `null` when the
+ * component is unsupported (a `@`-derived name we do not implement) or absent
+ * (a header the message does not carry).
+ */
+export function deriveComponentValue(
+  ctx: DerivationContext,
+  name: string,
+): string | null {
+  if (name.startsWith("@")) {
+    switch (name) {
+      case "@method":
+        return ctx.message.method.toUpperCase();
+      case "@target-uri":
+        return ctx.url.href;
+      case "@authority":
+        return ctx.url.host.toLowerCase();
+      case "@scheme":
+        return ctx.url.protocol.replace(/:$/, "").toLowerCase();
+      case "@request-target":
+        return `${ctx.url.pathname}${ctx.url.search}`;
+      case "@path":
+        return ctx.url.pathname;
+      case "@query":
+        return ctx.url.search === "" ? "?" : ctx.url.search;
+      default:
+        return null;
+    }
+  }
+  return ctx.headers.get(name.toLowerCase()) ?? null;
+}