Design a request signing library

Design an AWS SigV4-style HMAC signing library and its verifier: a canonical request that both sides build byte for byte, a derived signing key scoped to date and service, a timestamp window plus replay cache, an allow-list of signed headers, and the canonicalisation bugs that break signatures or open bypasses.

● MediumFREEBy ·Design problem·25 min read·Intermediate → Advanced
request signingSigV4HMACcanonical requestreplay protectionAPI authentication

01Understand the problem

✓What you will learn
  • Build a canonical request so client and server hash exactly the same bytes
  • Derive a scoped signing key so a leaked daily key is not the master secret
  • Bound replay with a timestamp window and a cache of seen signatures
  • Recognise the canonicalisation bugs that cause false rejects and, worse, false accepts
◎Interview radar

What they probe: what exactly is signed and why, how the server rebuilds it, why the body hash is in the signature, how replay is bounded, and what happens when a proxy re-encodes the path. Where candidates slip: signing a JSON object instead of the raw bytes, sorting with localeCompare, decoding a path twice, === on signatures, a timestamp check without a replay story.

A bearer token proves the caller once held a secret. Request signing proves this exact request (method, path, query, chosen headers and body) was made by the holder of the key, recently, and has not been altered in transit or by an intermediary. AWS Signature Version 4 is the reference design; ours is the same shape with our own names so nobody mistakes it for AWS.

  1. Signer.sign(request) adds x-cy-date, x-cy-content-sha256 and an authorization header.
  2. Verifier.verify(request) returns the key id and the list of signed headers, or a typed error.
  3. host, x-cy-date and x-cy-content-sha256 are always signed; the verifier can require more (for example content-type).
  4. Requests older or newer than 5 minutes are refused; a signature is accepted once.
  5. The secret never crosses the wire, and the signing key is derived per day and per service.
Line of the canonical requestExampleRule
MethodPOSTUpper case token as sent
Canonical path/v1/files/q3%20report.pdfEach segment decoded once, re-encoded with RFC 3986 unreserved set
Canonical querydryRun=&tag=a&tag=bPairs decoded, re-encoded, sorted by key then value, byte order
Canonical headerscontent-type:application/pdf (one per line)Lower-case name, trimmed value, inner spaces collapsed, sorted
Signed headerscontent-type;host;x-cy-content-sha256;x-cy-dateThe same names, joined by semicolons
Payload hashhex SHA-256 of the body bytesHash of the exact bytes on the wire

02Interfaces first

The contractts
export const ALGORITHM = "CY1-HMAC-SHA256";
const TERMINATOR = "cy1_request";
const ALWAYS_SIGNED = ["host", "x-cy-content-sha256", "x-cy-date"] as const;

export interface HttpRequestParts {
  method: string;
  path: string;                                // raw path as on the wire: "/v1/files/a%20b"
  query: string;                               // raw query, no "?": "limit=10&after=x"
  headers: Readonly<Record<string, string>>;
  body: Buffer;                                // exact bytes sent, never a re-serialised object
}

export interface Credentials { keyId: string; secret: string }

export type SigErrorCode = "malformed" | "missing_header" | "wrong_scope" | "stale" | "body_mismatch" | "unknown_key" | "bad_signature" | "replayed";
export class SigError extends Error {
  constructor(readonly code: SigErrorCode, message: string) { super(message); this.name = "SigError"; }
}

export interface KeyStore { secretFor(keyId: string): Promise<string | undefined> }
/** Atomic insert with TTL (Redis SET NX EX). False when the key was already present. */
export interface ReplayCache { addIfAbsent(key: string, ttlSec: number): Promise<boolean> }

export interface VerifierConfig {
  service: string;
  maxSkewSec: number;                          // 300
  requiredSigned: readonly string[];           // lower case, beyond ALWAYS_SIGNED
}

export type VerifyResult =
  | { ok: true; keyId: string; signedHeaders: readonly string[] }
  | { ok: false; error: SigError };
iWhy the verifier returns the signed header list

Unsigned headers can be added or changed by anyone on the path. Handing the list back lets the application refuse to act on a header that was not signed, for example an x-tenant-id the client forgot to include in the signature.

03Canonicalisation, key derivation, signer and verifier

Canonical request and key derivationts
import { createHash, createHmac, timingSafeEqual } from "node:crypto";

const sha256Hex = (d: Buffer | string) => createHash("sha256").update(d).digest("hex");
const hmac = (key: Buffer | string, data: string) => createHmac("sha256", key).update(data, "utf8").digest();

/** RFC 3986: only A-Z a-z 0-9 - . _ ~ stay literal; everything else becomes %XX with upper-case hex. */
export function uriEncode(s: string): string {
  return encodeURIComponent(s).replace(/[!'()*]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase());
}

function decodeStrict(s: string): string {
  try { return decodeURIComponent(s); } catch { throw new SigError("malformed", "invalid percent-encoding"); }
}

/** Decode each segment exactly once, then re-encode, so "%7E" and "~" (or "%2f" and "%2F") canonicalise alike. */
export function canonicalPath(path: string): string {
  if (!path.startsWith("/")) throw new SigError("malformed", "path must start with /");
  const segments = path.slice(1).split("/").map(decodeStrict);
  if (segments.some((s) => s === "." || s === "..")) throw new SigError("malformed", "dot segments are not allowed");
  return "/" + segments.map(uriEncode).join("/");
}

export function canonicalQuery(query: string): string {
  if (query === "") return "";
  const pairs = query.split("&").map((kv) => {
    const i = kv.indexOf("=");
    const k = decodeStrict(i === -1 ? kv : kv.slice(0, i));
    if (k === "") throw new SigError("malformed", "empty query parameter name");
    return [uriEncode(k), uriEncode(decodeStrict(i === -1 ? "" : kv.slice(i + 1)))];
  });
  // Plain code-unit comparison: after encoding everything is ASCII, so this is byte order. Never localeCompare.
  pairs.sort(([ak, av], [bk, bv]) => (ak < bk ? -1 : ak > bk ? 1 : av < bv ? -1 : av > bv ? 1 : 0));
  return pairs.map(([k, v]) => k + "=" + v).join("&");
}

function lowerHeaders(h: Readonly<Record<string, string>>): Map<string, string> {
  const m = new Map<string, string>();
  for (const [k, v] of Object.entries(h)) {
    const name = k.toLowerCase();
    if (m.has(name)) throw new SigError("malformed", "duplicate header " + name);
    m.set(name, v);
  }
  return m;
}

export function canonicalRequest(method: string, path: string, query: string, headers: Map<string, string>,
                                 signed: readonly string[], bodyHash: string): string {
  if (!/^[A-Z]{3,10}$/.test(method)) throw new SigError("malformed", "method must be an upper-case token");
  const lines = signed.map((n) => {
    const v = headers.get(n);
    if (v === undefined) throw new SigError("missing_header", n);
    return n + ":" + v.trim().replace(/\s+/g, " ");
  });
  return [method, canonicalPath(path), canonicalQuery(query), lines.join("\n") + "\n", signed.join(";"), bodyHash].join("\n");
}

const stringToSign = (stamp: string, scope: string, canonical: string) => [ALGORITHM, stamp, scope, sha256Hex(canonical)].join("\n");

/** kSigning = HMAC(HMAC(HMAC("CY1" + secret, date), service), "cy1_request"). Cache it per (keyId, date, service). */
export function signingKey(secret: string, date: string, service: string): Buffer {
  return hmac(hmac(hmac("CY1" + secret, date), service), TERMINATOR);
}

/** 2026-11-14T09:30:00.000Z -> 20261114T093000Z */
export function formatStamp(t: Date): string {
  return t.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
}

/** Strict parse with a round trip, so 20260230T093000Z (no 30 February) is refused instead of rolling into March. */
export function parseStamp(s: string): number {
  const m = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/.exec(s);
  if (!m) throw new SigError("malformed", "x-cy-date must look like 20261114T093000Z");
  const ms = Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +m[6]);
  if (!Number.isFinite(ms) || formatStamp(new Date(ms)) !== s) throw new SigError("malformed", "x-cy-date is not a real instant");
  return ms;
}
Signer and verifierts
export class Signer {
  private readonly allow: ReadonlySet<string>;
  constructor(private readonly creds: Credentials, private readonly service: string, signHeaders: readonly string[],
              private readonly now: () => Date = () => new Date()) {
    this.allow = new Set([...ALWAYS_SIGNED, ...signHeaders.map((h) => h.toLowerCase())]);
  }

  /** Returns the full header set to send: the caller's headers plus x-cy-date, x-cy-content-sha256 and authorization. */
  sign(req: HttpRequestParts): Record<string, string> {
    const t = this.now();
    if (Number.isNaN(t.getTime())) throw new Error("clock returned an invalid date");
    const stamp = formatStamp(t);
    const date = stamp.slice(0, 8);
    const bodyHash = sha256Hex(req.body);
    const headers = lowerHeaders(req.headers);
    headers.delete("authorization");
    headers.set("x-cy-date", stamp);
    headers.set("x-cy-content-sha256", bodyHash);
    if (!headers.has("host")) throw new SigError("missing_header", "host");
    const signed = [...headers.keys()].filter((n) => this.allow.has(n)).sort();   // allow-list: user-agent, via, etc. are never signed
    const scope = date + "/" + this.service + "/" + TERMINATOR;
    const canonical = canonicalRequest(req.method, req.path, req.query, headers, signed, bodyHash);
    const sig = hmac(signingKey(this.creds.secret, date, this.service), stringToSign(stamp, scope, canonical)).toString("hex");
    headers.set("authorization", ALGORITHM + " Credential=" + this.creds.keyId + "/" + scope + ", SignedHeaders=" + signed.join(";") + ", Signature=" + sig);
    return Object.fromEntries(headers);
  }
}

const AUTH_RE = /^CY1-HMAC-SHA256 Credential=([A-Za-z0-9]{8,64})\/(\d{8})\/([a-z0-9-]{1,32})\/cy1_request, SignedHeaders=([a-z0-9-]+(?:;[a-z0-9-]+)*), Signature=([0-9a-f]{64})$/;

export class Verifier {
  constructor(private readonly cfg: VerifierConfig, private readonly keys: KeyStore, private readonly replay: ReplayCache,
              private readonly now: () => number = Date.now) {
    if (!Number.isInteger(cfg.maxSkewSec) || cfg.maxSkewSec < 1 || cfg.maxSkewSec > 900) throw new Error("maxSkewSec must be an integer in [1, 900]");
  }

  async verify(req: HttpRequestParts): Promise<VerifyResult> {
    try { return { ok: true, ...(await this.check(req)) }; }
    catch (e) {
      if (e instanceof SigError) return { ok: false, error: e };
      throw e;                                                     // a bug, not a bad request
    }
  }

  private async check(req: HttpRequestParts): Promise<{ keyId: string; signedHeaders: readonly string[] }> {
    const headers = lowerHeaders(req.headers);
    const m = AUTH_RE.exec(headers.get("authorization") ?? "");
    if (!m) throw new SigError("malformed", "authorization header does not parse");
    const [, keyId, scopeDate, service, signedList, givenSig] = m;
    if (service !== this.cfg.service) throw new SigError("wrong_scope", "signed for service " + service);

    const stamp = headers.get("x-cy-date") ?? "";
    const signedAt = parseStamp(stamp);
    if (stamp.slice(0, 8) !== scopeDate) throw new SigError("wrong_scope", "credential date differs from x-cy-date");
    if (Math.abs(this.now() - signedAt) > this.cfg.maxSkewSec * 1000) throw new SigError("stale", "outside the time window");

    const signed = signedList.split(";");
    for (let i = 1; i < signed.length; i++) {
      if (signed[i - 1] >= signed[i]) throw new SigError("malformed", "SignedHeaders must be sorted and unique");
    }
    for (const n of [...ALWAYS_SIGNED, ...this.cfg.requiredSigned]) {
      if (!signed.includes(n)) throw new SigError("missing_header", n + " must be signed");
    }

    const bodyHash = sha256Hex(req.body);                         // recomputed from the bytes, never trusted from the header
    if (headers.get("x-cy-content-sha256") !== bodyHash) throw new SigError("body_mismatch", "body does not match its hash");

    const secret = await this.keys.secretFor(keyId);
    if (secret === undefined) throw new SigError("unknown_key", "unknown key id");
    const canonical = canonicalRequest(req.method, req.path, req.query, headers, signed, bodyHash);
    const scope = scopeDate + "/" + service + "/" + TERMINATOR;
    const expected = hmac(signingKey(secret, scopeDate, service), stringToSign(stamp, scope, canonical));
    if (!timingSafeEqual(expected, Buffer.from(givenSig, "hex"))) throw new SigError("bad_signature", "signature does not match");

    // Only after the signature holds, so garbage cannot fill the cache. The TTL covers the window on both sides.
    if (!(await this.replay.addIfAbsent(keyId + ":" + givenSig, 2 * this.cfg.maxSkewSec))) throw new SigError("replayed", "signature already used");
    return { keyId, signedHeaders: signed };
  }
}
▭On the whiteboard · Design choices4 points
01
what is signed
method, canonical path and query, allow-listed headers, SHA-256 of the raw body, timestamp, scope
02
key
derived per date and service; the long-term secret is only an input to the first HMAC
03
replay
5-minute window on x-cy-date, then SET NX on the signature for 10 minutes
04
compare
timingSafeEqual on two 32-byte buffers; the regex guarantees the hex length

04Canonicalisation bugs and tests

BugSymptomFix
Signing a parsed object, not the bytesKey order or whitespace differs after JSON round trip; random 401sHash the exact body bytes on both sides
Double decoding the path%252F becomes / on one side; signature or router disagreeDecode once per segment, reject invalid encodings
+ treated as space in one placea+b signs as a%20b on one side and a%2Bb on the otherDecode with decodeURIComponent, which leaves + alone, on both sides
localeCompare or case-insensitive sortOrder differs between client and server localesByte-order sort of the encoded strings
Signing every headerA proxy adds via or rewrites user-agent; 401Sign an allow-list; ignore the rest and never trust it
Router decodes differently from the signerSigned /files/a%2Fb routes to /files/a/bRoute on the same canonical form, or reject encoded slashes
Lenient timestamp parsing20260230T... silently becomes 2 MarchStrict regex plus a round-trip check
!A valid signature is not authorisation

The verifier proves who signed and that nothing changed. It does not decide whether that key may delete this bucket. Pass the key id into the authorisation engine and act only on signed headers.

vitestts
import { describe, it, expect } from "vitest";

const creds = { keyId: "AKCY0000EXAMPLE1", secret: "test-secret-do-not-use" };
const T = Date.UTC(2026, 10, 14, 9, 30, 0);

class MemReplay implements ReplayCache {
  private seen = new Set<string>();
  async addIfAbsent(k: string) { if (this.seen.has(k)) return false; this.seen.add(k); return true; }
}
const makeVerifier = (nowMs: number) => new Verifier(
  { service: "files", maxSkewSec: 300, requiredSigned: ["content-type"] },
  { secretFor: async (id) => (id === creds.keyId ? creds.secret : undefined) },
  new MemReplay(), () => nowMs);

const signer = new Signer(creds, "files", ["content-type"], () => new Date(T));
const base: HttpRequestParts = {
  method: "POST", path: "/v1/files/%7Eq3%20report.pdf", query: "tag=b&tag=a&dryRun",
  headers: { Host: "api.example.com", "Content-Type": "application/pdf", "User-Agent": "cli/1.2" },
  body: Buffer.from("%PDF-1.7 ..."),
};
const signedReq = (): HttpRequestParts => ({ ...base, headers: signer.sign(base) });
const code = (r: VerifyResult) => (r.ok ? "ok" : r.error.code);

describe("request signing", () => {
  it("round-trips, even after a proxy normalises the path and reorders the query", async () => {
    const r = { ...signedReq(), path: "/v1/files/~q3%20report.pdf", query: "dryRun&tag=a&tag=b" };
    expect(code(await makeVerifier(T + 1000).verify(r))).toBe("ok");
  });
  it("detects a changed body", async () => {
    expect(code(await makeVerifier(T).verify({ ...signedReq(), body: Buffer.from("%PDF-1.7 evil") }))).toBe("body_mismatch");
  });
  it("detects a changed query value", async () => {
    expect(code(await makeVerifier(T).verify({ ...signedReq(), query: "tag=b&tag=admin&dryRun" }))).toBe("bad_signature");
  });
  it("ignores unsigned headers, which the app must therefore not trust", async () => {
    const r = signedReq();
    expect(code(await makeVerifier(T).verify({ ...r, headers: { ...r.headers, "user-agent": "other" } }))).toBe("ok");
  });
  it("refuses a replay and a stale request", async () => {
    const v = makeVerifier(T);
    const r = signedReq();
    expect(code(await v.verify(r))).toBe("ok");
    expect(code(await v.verify(r))).toBe("replayed");
    expect(code(await makeVerifier(T + 301_000).verify(signedReq()))).toBe("stale");
  });
  it("refuses an impossible date instead of rolling it over", async () => {
    const r = signedReq();
    expect(code(await makeVerifier(T).verify({ ...r, headers: { ...r.headers, "x-cy-date": "20261131T093000Z" } }))).toBe("malformed");
  });
});

05Extensions, follow-ups, how to say it

  • Streaming bodies: for large uploads, sign UNSIGNED-PAYLOAD and rely on TLS, or sign each chunk with a chained signature as SigV4 streaming does.
  • Presigned URLs: move the date, credential, signed headers and signature into the query string with an expiry parameter, and exclude the signature parameter itself from the canonical query.
  • Asymmetric option: HTTP Message Signatures (RFC 9421) standardises the same idea with Ed25519 or ECDSA keys, so the verifier holds no secret.
  • Key rotation: two active keys per client; the key id in the credential picks one, so rotation needs no flag day.
Q1Why derive a signing key per day and service instead of using the secret directly?+

A derived key that leaks from a cache or a service is only good for that service on that day. The long-term secret is only ever an HMAC key at the first step and can stay in a vault.

Q2Why put the body hash in its own header if the verifier recomputes it?+

It lets intermediaries and the verifier reject a mismatched body before running the HMAC, and it is the hook for an UNSIGNED-PAYLOAD mode. The verifier still never trusts the header without recomputing.

Q3Does the timestamp window alone stop replay?+

No. Inside 5 minutes the same request verifies again. For non-idempotent calls you need the seen-signature cache, or an idempotency key the server enforces.

“How to say it in the room

"Both sides build a canonical request: method, path decoded once and re-encoded with the RFC 3986 unreserved set, query pairs encoded and byte-sorted, an allow-list of headers lower-cased and trimmed, and the SHA-256 of the raw body. The string to sign adds the algorithm, timestamp and a date and service scope, and the key is HMAC-derived from the secret per day and service. The verifier rebuilds it from what actually arrived, recomputes the body hash, checks a five-minute window, compares in constant time, and only then records the signature to stop replay. Unsigned headers are handed back as untrusted."

Test yourself

A client signs `?q=a+b`. The server framework decodes the query with form rules before canonicalising. What happens?

Finished this one?
Tick it and it shows as done on the roadmap and the course.