@dwk/http-signatures 0.1.0-beta.0

package/src/sf.ts

@@ -0,0 +1,246 @@
+/**
+ * A focused RFC 8941 structured-fields parser, scoped to the two fields HTTP
+ * Message Signatures use: `Signature-Input` (a Dictionary of Inner Lists with
+ * parameters) and `Signature` (a Dictionary of Byte Sequences).
+ *
+ * It is intentionally not a general structured-fields implementation. Parsing
+ * is strict — anything malformed throws {@link SfParseError}, which the callers
+ * turn into a verification failure rather than guessing at the sender's intent.
+ */
+
+/** A structured-fields bare item value, as the native JS shape we use it as. */
+export type SfBareItem = string | number | boolean | Uint8Array;
+
+/** One member of an `Signature-Input` inner list (a covered-component id). */
+export interface SfInnerItem {
+  /** Exact source text of the item (bare item plus its parameters). */
+  raw: string;
+  /** The bare item, a string for every component identifier we accept. */
+  value: SfBareItem;
+  /** Item parameters, in source order. */
+  params: Array<[string, SfBareItem]>;
+}
+
+/** A parsed `Signature-Input` dictionary member. */
+export interface SfSignatureInput {
+  /** Exact source text of the member value (inner list plus its parameters). */
+  raw: string;
+  items: SfInnerItem[];
+  params: Array<[string, SfBareItem]>;
+}
+
+/** Thrown on any malformed structured-field input. */
+export class SfParseError extends Error {}
+
+const KEY_START = /[a-z*]/;
+const KEY_CHAR = /[a-z0-9_*.-]/;
+const TOKEN_START = /[a-zA-Z*]/;
+const TOKEN_CHAR = /[a-zA-Z0-9:/!#$%&'*+\-.^_`|~]/;
+
+class Reader {
+  pos = 0;
+  constructor(readonly input: string) {}
+
+  get done(): boolean {
+    return this.pos >= this.input.length;
+  }
+  peek(): string {
+    return this.input[this.pos] ?? "";
+  }
+  next(): string {
+    const c = this.input[this.pos] ?? "";
+    this.pos++;
+    return c;
+  }
+  expect(c: string): void {
+    if (this.next() !== c) throw new SfParseError(`expected ${c}`);
+  }
+  skipSP(): void {
+    while (this.peek() === " ") this.pos++;
+  }
+  skipOWS(): void {
+    while (this.peek() === " " || this.peek() === "\t") this.pos++;
+  }
+}
+
+function parseKey(r: Reader): string {
+  if (!KEY_START.test(r.peek())) throw new SfParseError("invalid key");
+  let key = r.next();
+  while (!r.done && KEY_CHAR.test(r.peek())) key += r.next();
+  return key;
+}
+
+function parseString(r: Reader): string {
+  r.expect('"');
+  let out = "";
+  for (;;) {
+    if (r.done) throw new SfParseError("unterminated string");
+    const c = r.next();
+    if (c === "\\") {
+      const esc = r.next();
+      if (esc !== '"' && esc !== "\\") throw new SfParseError("bad escape");
+      out += esc;
+    } else if (c === '"') {
+      return out;
+    } else {
+      const code = c.charCodeAt(0);
+      if (code < 0x20 || code >= 0x7f)
+        throw new SfParseError("bad string char");
+      out += c;
+    }
+  }
+}
+
+function parseToken(r: Reader): string {
+  let tok = r.next();
+  while (!r.done && TOKEN_CHAR.test(r.peek())) tok += r.next();
+  return tok;
+}
+
+function parseNumber(r: Reader): number {
+  let s = "";
+  if (r.peek() === "-") s += r.next();
+  while (!r.done && /[0-9.]/.test(r.peek())) s += r.next();
+  const n = Number(s);
+  if (!Number.isFinite(n)) throw new SfParseError("invalid number");
+  return n;
+}
+
+function parseByteSequence(r: Reader): Uint8Array {
+  r.expect(":");
+  let b64 = "";
+  while (!r.done && r.peek() !== ":") b64 += r.next();
+  r.expect(":");
+  try {
+    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;
+  } catch {
+    throw new SfParseError("invalid byte sequence");
+  }
+}
+
+function parseBareItem(r: Reader): SfBareItem {
+  const c = r.peek();
+  if (c === '"') return parseString(r);
+  if (c === ":") return parseByteSequence(r);
+  if (c === "?") {
+    r.next();
+    const b = r.next();
+    if (b === "0") return false;
+    if (b === "1") return true;
+    throw new SfParseError("invalid boolean");
+  }
+  if (c === "-" || /[0-9]/.test(c)) return parseNumber(r);
+  if (TOKEN_START.test(c)) return parseToken(r);
+  throw new SfParseError("invalid bare item");
+}
+
+function parseParameters(r: Reader): Array<[string, SfBareItem]> {
+  const params: Array<[string, SfBareItem]> = [];
+  while (r.peek() === ";") {
+    r.next();
+    r.skipSP();
+    const key = parseKey(r);
+    let value: SfBareItem = true;
+    if (r.peek() === "=") {
+      r.next();
+      value = parseBareItem(r);
+    }
+    params.push([key, value]);
+  }
+  return params;
+}
+
+function parseInnerList(r: Reader): {
+  items: SfInnerItem[];
+  params: Array<[string, SfBareItem]>;
+} {
+  r.expect("(");
+  const items: SfInnerItem[] = [];
+  for (;;) {
+    r.skipSP();
+    if (r.peek() === ")") {
+      r.next();
+      break;
+    }
+    if (r.done) throw new SfParseError("unterminated inner list");
+    const start = r.pos;
+    const value = parseBareItem(r);
+    const params = parseParameters(r);
+    items.push({ raw: r.input.slice(start, r.pos), value, params });
+  }
+  const params = parseParameters(r);
+  return { items, params };
+}
+
+/**
+ * Parse a `Signature-Input` header into its labelled inner lists, preserving
+ * for each member the exact source text of its value (the `@signature-params`
+ * value the base must reproduce byte-for-byte).
+ */
+export function parseSignatureInput(
+  input: string,
+): Map<string, SfSignatureInput> {
+  const r = new Reader(input);
+  const out = new Map<string, SfSignatureInput>();
+  r.skipOWS();
+  if (r.done) throw new SfParseError("empty dictionary");
+  for (;;) {
+    const key = parseKey(r);
+    if (r.peek() !== "=")
+      throw new SfParseError("dictionary member needs a value");
+    r.next();
+    if (r.peek() !== "(")
+      throw new SfParseError("signature-input value must be an inner list");
+    const start = r.pos;
+    const { items, params } = parseInnerList(r);
+    out.set(key, { raw: r.input.slice(start, r.pos), items, params });
+    r.skipOWS();
+    if (r.done) break;
+    r.expect(",");
+    r.skipOWS();
+  }
+  return out;
+}
+
+/**
+ * Parse an RFC 8941 Dictionary whose member values are Byte Sequences — the
+ * shape shared by the `Signature` header and the RFC 9530 `Content-Digest` /
+ * `Want-Content-Digest` fields. Member parameters are accepted and discarded.
+ * Keys follow sf-key rules (lowercase only), so an uppercase key is a parse
+ * error rather than something silently lowercased.
+ */
+export function parseByteSequenceDictionary(
+  input: string,
+): Map<string, Uint8Array> {
+  const r = new Reader(input);
+  const out = new Map<string, Uint8Array>();
+  r.skipOWS();
+  if (r.done) throw new SfParseError("empty dictionary");
+  for (;;) {
+    const key = parseKey(r);
+    if (r.peek() !== "=")
+      throw new SfParseError("dictionary member needs a value");
+    r.next();
+    const bytes = parseByteSequence(r);
+    parseParameters(r);
+    out.set(key, bytes);
+    r.skipOWS();
+    if (r.done) break;
+    r.expect(",");
+    r.skipOWS();
+  }
+  return out;
+}
+
+/** Parse a `Signature` header into its labelled byte sequences. */
+export function parseSignatureHeader(input: string): Map<string, Uint8Array> {
+  return parseByteSequenceDictionary(input);
+}
+
+/** Serialize an sf-string: double-quoted with `"` and `\` escaped. */
+export function serializeString(value: string): string {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}

package/src/sign.ts

@@ -0,0 +1,79 @@
+/**
+ * The unified signing entry point. Dispatches on the wire profile and returns
+ * the header(s) to merge into the outbound request.
+ */
+
+import { signCavage } from "./cavage";
+import { signRfc9421 } from "./rfc9421";
+import type {
+  HttpMessage,
+  SignatureAlgorithm,
+  SignatureProfile,
+} from "./types";
+
+/** Inputs for {@link signMessage}. */
+export interface SignParams {
+  /** Wire profile. Defaults to `"rfc9421"`. */
+  profile?: SignatureProfile;
+  /** The private {@link CryptoKey}, imported by the caller for `alg`. */
+  key: CryptoKey;
+  /** The `keyid` advertised so the verifier can resolve the public half. */
+  keyId: string;
+  /** Signature algorithm; must be in the allow-list. */
+  alg: SignatureAlgorithm;
+  /**
+   * Covered components, in signing order. For `"rfc9421"`: derived names like
+   * `@method`, `@target-uri`, `@authority`, plus lowercase header names. For
+   * `"cavage"`: `(request-target)`, `(created)`, `(expires)`, and lowercase
+   * header names.
+   */
+  components: string[];
+  /** Signature creation time, epoch seconds. Defaults to now. */
+  created?: number;
+  /** Signature expiry, epoch seconds. Omitted when absent. */
+  expires?: number;
+  /** Anti-replay nonce (RFC 9421 only). */
+  nonce?: string;
+  /** Application tag (RFC 9421 only). */
+  tag?: string;
+  /** Signature label (RFC 9421 only). Defaults to `"sig1"`. */
+  label?: string;
+  /** Override "now" for the `created` default, epoch seconds (deterministic tests). */
+  now?: number;
+}
+
+/**
+ * Sign `message`, returning the headers to add to the request. The caller is
+ * responsible for having already set (and listed among `components`) any
+ * `content-digest` / `digest` header it wants covered — see
+ * {@link createContentDigest} / {@link createDigest}.
+ *
+ * @returns A map of header name → value (RFC 9421: `Signature-Input` and
+ *   `Signature`; cavage: a single `Signature`).
+ */
+export function signMessage(
+  message: HttpMessage,
+  params: SignParams,
+): Promise<Record<string, string>> {
+  if (params.profile === "cavage") {
+    return signCavage(message, {
+      key: params.key,
+      keyId: params.keyId,
+      alg: params.alg,
+      components: params.components,
+      created: params.created,
+      expires: params.expires,
+    });
+  }
+  return signRfc9421(message, {
+    key: params.key,
+    keyId: params.keyId,
+    alg: params.alg,
+    components: params.components,
+    created: params.created ?? params.now ?? Math.floor(Date.now() / 1000),
+    expires: params.expires,
+    nonce: params.nonce,
+    tag: params.tag,
+    label: params.label ?? "sig1",
+  });
+}

package/src/types.ts

@@ -0,0 +1,94 @@
+/**
+ * Shared plain-data types for {@link signMessage} and {@link verifyMessage}.
+ *
+ * The library never touches a live HTTP object: a request (or response) is
+ * described by its method, URL, and header values, so it unit-tests under Node
+ * with no Workers runtime.
+ */
+
+/**
+ * Asymmetric signature algorithms this library accepts, named by their RFC 9421
+ * §3.3 registry identifiers.
+ *
+ * Symmetric (`hmac-sha256`) and unsigned (`none`) algorithms are deliberately
+ * excluded: an HTTP message signature must be made by the sender's private key
+ * whose public half the verifier resolves out of band.
+ */
+export type SignatureAlgorithm =
+  | "rsa-pss-sha512"
+  | "rsa-v1_5-sha256"
+  | "ecdsa-p256-sha256"
+  | "ecdsa-p384-sha384"
+  | "ed25519";
+
+/**
+ * Wire profile.
+ *
+ * - `"rfc9421"` — the modern `Signature-Input` / `Signature` structured-field
+ *   pair (RFC 9421).
+ * - `"cavage"` — the legacy single `Signature` header from
+ *   `draft-cavage-http-signatures`, still emitted across the fediverse.
+ */
+export type SignatureProfile = "rfc9421" | "cavage";
+
+/**
+ * A request (or response) reduced to the facts a signature is computed over.
+ *
+ * `headers` keys are matched case-insensitively; a value array models a field
+ * that appears multiple times (its values are joined with `", "` per RFC 9421
+ * §2.1).
+ */
+export interface HttpMessage {
+  /** HTTP method, e.g. `"POST"`. */
+  method: string;
+  /** Absolute request URI, e.g. `"https://example.com/inbox"`. */
+  url: string;
+  /** Header field values, keyed by (case-insensitive) field name. */
+  headers: Record<string, string | string[]>;
+}
+
+/** Stable, locale-independent failure codes returned in {@link VerifyResult.reason}. */
+export type SignatureFailureReason =
+  | "signature_missing"
+  | "signature_input_malformed"
+  | "signature_malformed"
+  | "label_ambiguous"
+  | "label_missing"
+  | "components_malformed"
+  | "alg_unsupported"
+  | "keyid_missing"
+  | "key_unresolved"
+  | "key_alg_mismatch"
+  | "key_too_small"
+  | "key_invalid"
+  | "covered_component_missing"
+  | "required_component_missing"
+  | "created_invalid"
+  | "created_required"
+  | "signature_expired"
+  | "signature_future"
+  | "expires_invalid"
+  | "signature_invalid"
+  | "digest_missing"
+  | "digest_unsupported"
+  | "digest_mismatch";
+
+/** Result of verifying an HTTP message signature. */
+export interface VerifyResult {
+  /** Whether the signature is valid. */
+  valid: boolean;
+  /** The profile the signature was read under, when one could be identified. */
+  profile?: SignatureProfile;
+  /** The signature label that was verified (RFC 9421 only). */
+  label?: string;
+  /** The `keyid` the signature claimed (so the caller can audit the principal). */
+  keyId?: string;
+  /** The covered-component identifiers, in signing order. */
+  coveredComponents?: string[];
+  /** The signature's `created` time (epoch seconds), if present. */
+  created?: number;
+  /** The signature's `expires` time (epoch seconds), if present. */
+  expires?: number;
+  /** Stable failure code (see {@link SignatureFailureReason}) when `valid` is false. */
+  reason?: SignatureFailureReason;
+}

package/src/verify.ts

@@ -0,0 +1,102 @@
+/**
+ * The unified verification entry point. Auto-detects the wire profile (unless
+ * one is forced), verifies the signature, and — when a body is supplied —
+ * checks any covered `content-digest` / `digest` against it so body tampering
+ * is caught alongside header tampering.
+ */
+
+import { verifyCavage } from "./cavage";
+import { verifyContentDigest, verifyDigest } from "./digest";
+import { verifyRfc9421, type KeyResolver } from "./rfc9421";
+import type { HttpMessage, SignatureProfile, VerifyResult } from "./types";
+
+/** Inputs for {@link verifyMessage}. */
+export interface VerifyParams {
+  /** Resolves the public {@link CryptoKey} for a `keyid` (and, when known, `alg`). */
+  resolveKey: KeyResolver;
+  /** Force a profile. When omitted, it is detected from the present headers. */
+  profile?: SignatureProfile;
+  /** Which labelled signature to verify (RFC 9421); required if more than one. */
+  label?: string;
+  /** Component identifiers that MUST be covered (e.g. `@method`, `date`, `content-digest`). */
+  requiredComponents?: string[];
+  /** Require a `created` parameter (RFC 9421). */
+  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;
+  /**
+   * The received body. When provided and a digest component is covered, the
+   * corresponding `content-digest` / `digest` header is recomputed over it; a
+   * mismatch fails verification with a `digest_*` reason.
+   */
+  body?: Uint8Array | string;
+}
+
+function hasHeader(message: HttpMessage, name: string): boolean {
+  const lower = name.toLowerCase();
+  return Object.keys(message.headers).some((k) => k.toLowerCase() === lower);
+}
+
+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;
+}
+
+/**
+ * Verify the HTTP message signature on `message`. Never throws — every failure
+ * is `{ valid: false, reason }` with a stable {@link SignatureFailureReason}.
+ */
+export async function verifyMessage(
+  message: HttpMessage,
+  params: VerifyParams,
+): Promise<VerifyResult> {
+  const profile: SignatureProfile =
+    params.profile ??
+    (hasHeader(message, "signature-input") ? "rfc9421" : "cavage");
+
+  const result =
+    profile === "rfc9421"
+      ? await verifyRfc9421(message, {
+          resolveKey: params.resolveKey,
+          label: params.label,
+          requiredComponents: params.requiredComponents,
+          requireCreated: params.requireCreated,
+          now: params.now,
+          toleranceSeconds: params.toleranceSeconds,
+        })
+      : await verifyCavage(message, {
+          resolveKey: params.resolveKey,
+          requiredComponents: params.requiredComponents,
+          now: params.now,
+          toleranceSeconds: params.toleranceSeconds,
+        });
+
+  if (!result.valid || params.body === undefined) return result;
+
+  // Body integrity: only when a digest component was actually covered.
+  const covered = new Set(
+    (result.coveredComponents ?? []).map((c) => c.toLowerCase()),
+  );
+  if (covered.has("content-digest")) {
+    const rejection = await verifyContentDigest(
+      getHeader(message, "content-digest"),
+      params.body,
+    );
+    if (rejection !== null)
+      return { ...result, valid: false, reason: rejection };
+  } else if (covered.has("digest")) {
+    const rejection = await verifyDigest(
+      getHeader(message, "digest"),
+      params.body,
+    );
+    if (rejection !== null)
+      return { ...result, valid: false, reason: rejection };
+  }
+
+  return result;
+}