diff --git a/rest/nodejs/src/utils/signature.ts b/rest/nodejs/src/utils/signature.ts index 0bc806d2..76924740 100644 --- a/rest/nodejs/src/utils/signature.ts +++ b/rest/nodejs/src/utils/signature.ts @@ -25,8 +25,10 @@ import { UcpError, ucpErrorResponse } from "./ucp_error"; // This is the Node twin of the Python server's ucp_signing.py: RFC 9421 // signature-base construction with the UCP covered-component set, RFC 9530 // Content-Digest over the raw body bytes (sha-256), ES256 (ECDSA P-256 with -// fixed-width raw r||s signatures, never ASN.1/DER) plus Ed25519, and signer -// key discovery from the UCP-Agent profile's keys[]. Only node:crypto is used; +// fixed-width raw r||s signatures, never ASN.1/DER) plus Ed25519, signer key +// discovery from the UCP-Agent profile's keys[], and WBA-shape (dual-audience) +// signatures: the key component parameter (RFC 9421 Section 2.1.2) for +// signature-agent and the RFC 7638 keyid binding. Only node:crypto is used; // the RFC 8941 structured-field subset is hand-rolled, no new dependencies. // Public keys resolved from a signer profile are cached for this long. @@ -37,6 +39,17 @@ const keyCache = new Map(); // OPTIONAL and the baseline every verifier MUST support is ES256. const ES256_COORD_BYTES = 32; +// RFC 7638 Section 3.2: the required members of each key type, in the +// lexicographic order the thumbprint input uses. +const THUMBPRINT_MEMBERS: Record = { + EC: ["crv", "kty", "x", "y"], + OKP: ["crv", "kty", "x"], + RSA: ["e", "kty", "n"], +}; + +// An RFC 8941 Dictionary member key, at the start of a member. +const SF_KEY = /^[a-z*][a-z0-9_\-.*]*/; + // A signature or profile-resolution failure with UCP wire semantics: the UCP // error code and the HTTP status the spec maps it to. export class SignatureError extends Error { @@ -64,9 +77,18 @@ export type Jwk = { export type SignatureInputMember = { raw: string; components: string[]; + // Each component's key parameter (RFC 9421 Section 2.1.2), or null. + componentKeys: (string | null)[]; + // True when a component carries any parameter other than key, a key on a + // derived component, or a repeated key. + unsupported: boolean; params: Record; }; +// A covered component: a name, or [name, key] for a Dictionary member selected +// with the key parameter (RFC 9421 Section 2.1.2). +export type ComponentId = string | [string, string]; + // Returns the RFC 9530 Content-Digest value (sha-256 over the raw body bytes). export function contentDigest(body: Uint8Array): string { const digest = crypto.createHash("sha256").update(body).digest("base64"); @@ -137,8 +159,9 @@ export function sfSplit(value: string, seps: string): string[] { } // Parses a Signature-Input header into per-label descriptors: the member value -// verbatim (what @signature-params must echo), the unquoted component -// identifiers, and the parameters. Null on malformed input. +// verbatim (what @signature-params must echo), the unquoted component names +// with each one's key parameter, whether any component carries another +// parameter, and the signature parameters. Null on malformed input. export function parseSignatureInput( value: string ): Record | null { @@ -166,11 +189,38 @@ export function parseSignatureInput( const inner = val.slice(1, end); const rest = val.slice(end + 1); const components: string[] = []; + const componentKeys: (string | null)[] = []; + let unsupported = false; for (const tok of sfSplit(inner, " ")) { - if (!tok.startsWith('"') || !tok.endsWith('"') || tok.includes(";")) { + const [name = "", ...componentParams] = sfSplit(tok, ";"); + if (name.length < 2 || !name.startsWith('"') || !name.endsWith('"')) { return null; } - components.push(tok.slice(1, -1)); + let key: string | null = null; + for (const param of componentParams) { + const pEq = param.indexOf("="); + const k = (pEq === -1 ? param : param.slice(0, pEq)).trim(); + const v = pEq === -1 ? "" : param.slice(pEq + 1); + // key selects a Dictionary member of a field (RFC 9421 Section + // 2.1.2): a derived component takes no key (Section 2.2), and a + // repeated key leaves the member ambiguous. + if ( + k === "key" && + key === null && + !name.startsWith('"@') && + v.length >= 2 && + v.startsWith('"') && + v.endsWith('"') + ) { + key = v.slice(1, -1); + } else { + // A parameter this verifier does not implement makes only this + // signature unverifiable, not the whole header (RFC 9421 4.3). + unsupported = true; + } + } + components.push(name.slice(1, -1)); + componentKeys.push(key); } const params: Record = {}; for (const part of sfSplit(rest, ";")) { @@ -178,10 +228,12 @@ export function parseSignatureInput( const pEq = part.indexOf("="); const k = (pEq === -1 ? part : part.slice(0, pEq)).trim(); let v = pEq === -1 ? "" : part.slice(pEq + 1); - if (v.startsWith('"') && v.endsWith('"')) v = v.slice(1, -1); + if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) { + v = v.slice(1, -1); + } params[k] = v; } - out[label] = { raw: val, components, params }; + out[label] = { raw: val, components, componentKeys, unsupported, params }; } return Object.keys(out).length ? out : null; } @@ -211,25 +263,80 @@ export function parseSignature(value: string): Record | null { // Constructs the RFC 9421 signature base. The raw Signature-Input member value // is echoed verbatim on the @signature-params line. Null if any covered // component cannot be resolved for this message. -export function buildSignatureBase( - components: string[], +export function buildSignatureBase( + components: C[], rawParams: string, - resolve: (name: string) => string | undefined | null + resolve: (component: C) => string | undefined | null ): Buffer | null { const lines: string[] = []; - for (const name of components) { - const value = resolve(name); + for (const component of components) { + const value = resolve(component); if (value === undefined || value === null) return null; - lines.push(`"${name}": ${value}`); + const identifier = + typeof component === "string" + ? `"${component}"` + : `"${component[0]}";key="${component[1]}"`; + lines.push(`${identifier}: ${value}`); } lines.push(`"@signature-params": ${rawParams}`); return Buffer.from(lines.join("\n"), "utf-8"); } +// Returns one Dictionary member's value as RFC 9421 Section 2.1.2 signs it: +// the member value with its parameters, serialized without optional +// whitespace, or null when the Dictionary has no such member. As in RFC 8941, +// the last of duplicate members wins. +export function dictionaryMember(value: string, key: string): string | null { + let found: string | null = null; + for (const member of sfSplit(value, ",")) { + const match = SF_KEY.exec(member); + if (!match || match[0] !== key) continue; + const rest = member.slice(match[0].length); + if (rest.startsWith("=")) { + found = rest.slice(1); + } else if (!rest || rest.startsWith(";")) { + found = "?1" + rest; // A member without a value is boolean true. + } + } + const parts = found === null ? [] : sfSplit(found, ";"); + // An empty item, as in sig1=;type=jwks_uri, is not a member value. + if (!parts.length || !parts[0]) return null; + const [item, ...params] = parts; + let serialized = item!; + for (const param of params) { + const pEq = param.indexOf("="); + const k = (pEq === -1 ? param : param.slice(0, pEq)).trim(); + const v = pEq === -1 ? "" : param.slice(pEq + 1).trim(); + serialized += pEq === -1 || v === "?1" ? `;${k}` : `;${k}=${v}`; + } + return serialized; +} + +// Returns the RFC 7638 SHA-256 thumbprint of a JWK, base64url-encoded, or null +// for another key type or a JWK missing a member the thumbprint needs. +export function jwkThumbprint(jwk: Jwk): string | null { + // The profile is signer-published, so kty may be of any type, and a name + // such as "toString" must not resolve through the object prototype. + const kty: unknown = jwk.kty; + const members = + typeof kty === "string" && Object.hasOwn(THUMBPRINT_MEMBERS, kty) + ? THUMBPRINT_MEMBERS[kty] + : undefined; + if (!members || !members.every((m) => typeof jwk[m] === "string")) { + return null; + } + const canonical = JSON.stringify( + Object.fromEntries(members.map((m) => [m, jwk[m]])) + ); + return crypto.createHash("sha256").update(canonical).digest("base64url"); +} + // The components a UCP request signature MUST cover (the verification-side // coverage gate from signatures.md). Coverage keys on header presence, not on -// the method. signature-agent is a WBA-shape component this default-UCP -// verifier does not parse, so it is deliberately outside the gate. +// the method. A WBA-shape (dual-audience) signature covers signature-agent +// with a key parameter naming its own label, e.g. +// "signature-agent";key="sig1"; verifyRequest accepts that form for +// signature-agent only. export function requiredComponents( _method: string, hasQuery: boolean, @@ -241,6 +348,7 @@ export function requiredComponents( if (hasBody) required.push("content-digest", "content-type"); if ("idempotency-key" in headers) required.push("idempotency-key"); if ("ucp-agent" in headers) required.push("ucp-agent"); + if ("signature-agent" in headers) required.push("signature-agent"); return required; } @@ -387,7 +495,14 @@ export function verifyRequest( if (sigCapable(key)) keysByKid.set(key.kid, key); } - const resolve = (name: string): string | undefined => { + const resolve = (name: ComponentId): string | undefined | null => { + if (typeof name !== "string") { + // RFC 9421 Section 2.1.2: the key parameter selects a Dictionary member. + const value = headers[name[0]]; + return typeof value === "string" + ? dictionaryMember(value, name[1]) + : null; + } if (name === "@method") return method.toUpperCase(); if (name === "@authority") return normalizeAuthority(authority); if (name === "@path") return path || "/"; // RFC 9421 2.2.6: empty is "/" @@ -413,7 +528,26 @@ export function verifyRequest( ); continue; } - const missing = required.filter((c) => !desc.components.includes(c)); + if (desc.unsupported) { + lastError = new SignatureError( + "signature_invalid", + 401, + "Signature covers a component parameter other than key" + ); + continue; + } + // A component signed with a key parameter binds one Dictionary member and + // leaves the rest of the field unbound, such as a second digest in + // Content-Digest, so a required component counts only when it is signed + // whole. signature-agent is the exception: signatures.md binds the + // Signature-Input label to the key parameter and the member it selects. + const covers = (name: string, key: string | null) => + desc.components.some( + (c, i) => c === name && (desc.componentKeys[i] ?? null) === key + ); + const missing = required.filter( + (c) => !covers(c, null) && !(c === "signature-agent" && covers(c, label)) + ); if (missing.length) { lastError = new SignatureError( "signature_invalid", @@ -432,7 +566,24 @@ export function verifyRequest( ); continue; } - const base = buildSignatureBase(desc.components, desc.raw, resolve); + // signatures.md, step pre-2a: a WBA-shape signature's keyid MUST be the + // RFC 7638 thumbprint of the key it resolved to. + if (desc.params["tag"] === "web-bot-auth") { + const thumbprint = jwkThumbprint(jwk); + if (thumbprint === null || keyid !== thumbprint) { + lastError = new SignatureError( + "signature_invalid", + 401, + "tag=web-bot-auth requires keyid to be the key's RFC 7638 thumbprint" + ); + continue; + } + } + const components: ComponentId[] = desc.components.map((name, i) => { + const key = desc.componentKeys[i]; + return key === null || key === undefined ? name : [name, key]; + }); + const base = buildSignatureBase(components, desc.raw, resolve); if (base === null) { lastError = new SignatureError( "signature_invalid", diff --git a/rest/nodejs/test/signing.test.ts b/rest/nodejs/test/signing.test.ts index dd102c7a..1da8bdcb 100644 --- a/rest/nodejs/test/signing.test.ts +++ b/rest/nodejs/test/signing.test.ts @@ -18,15 +18,18 @@ import http from "node:http"; import { after, before, test } from "node:test"; import { + type Jwk, SignatureError, assertProfileUrlAllowed, buildSignatureBase, clearKeyCache, contentDigest, contentDigestMatches, + dictionaryMember, extractKeys, fetchSigningKeys, jwkFromPublicKey, + jwkThumbprint, normalizeAuthority, parseSignature, parseSignatureInput, @@ -403,7 +406,7 @@ test("coverage keys on header presence, not on the method", () => { assert.ok(required.includes("idempotency-key")); }); -test("ucp-agent must be covered; signature-agent is out of scope", () => { +test("present ucp-agent and signature-agent headers must both be covered", () => { const required = requiredComponents( "GET", false, @@ -411,7 +414,7 @@ test("ucp-agent must be covered; signature-agent is out of scope", () => { false ); assert.ok(required.includes("ucp-agent")); - assert.ok(!required.includes("signature-agent")); + assert.ok(required.includes("signature-agent")); }); test("a signature carrying an alg parameter is rejected (spec MUST NOT)", () => { @@ -439,6 +442,244 @@ test("a signature carrying an alg parameter is rejected (spec MUST NOT)", () => ); }); +/* Dual-audience signatures from the signatures.md WBA Interop section. */ + +// RFC 7638 thumbprint of RFC_ED25519_JWK; the keyid of the signatures.md +// dual-audience example. +const WBA_KEYID = "poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U"; +const WBA_PROFILE = "https://platform.example/.well-known/ucp"; +const WBA_BODY = Buffer.from('{"line_items":[]}'); +const WBA_COMPONENTS = [ + '"@method"', + '"@authority"', + '"@path"', + '"signature-agent";key="sig1"', + '"ucp-agent"', + '"idempotency-key"', + '"content-digest"', + '"content-type"', +]; + +// Signs the example request over a hand-built RFC 9421 base. +function wbaSigned( + keyid = WBA_KEYID, + components = WBA_COMPONENTS, + headersUpdate: Record = {}, + valuesUpdate: Record = {} +) { + const headers: Record = { + "ucp-agent": `profile="${WBA_PROFILE}"`, + "signature-agent": `sig1="${WBA_PROFILE}";type=jwks_uri`, + "idempotency-key": "550e8400-e29b-41d4-a716-446655440000", + "content-type": "application/json", + "content-digest": contentDigest(WBA_BODY), + ...headersUpdate, + }; + const raw = + `(${components.join(" ")});keyid="${keyid}";created=1738617600;` + + 'expires=1738621200;tag="web-bot-auth"'; + const values: Record = { + '"@method"': "POST", + '"@authority"': "merchant.example.com", + '"@path"': "/checkout-sessions", + // RFC 9421 Section 2.1.2: the value of the sig1 member, not the field. + '"signature-agent";key="sig1"': `"${WBA_PROFILE}";type=jwks_uri`, + '"ucp-agent"': headers["ucp-agent"]!, + '"idempotency-key"': headers["idempotency-key"]!, + '"content-digest"': headers["content-digest"]!, + '"content-type"': headers["content-type"]!, + '"signature-agent"': headers["signature-agent"]!, + ...valuesUpdate, + }; + const base = Buffer.from( + [ + ...components.map((c) => `${c}: ${values[c]}`), + `"@signature-params": ${raw}`, + ].join("\n") + ); + const key = crypto.createPrivateKey({ + key: { ...RFC_ED25519_JWK, d: RFC_ED25519_D }, + format: "jwk", + }); + const sig = crypto.sign(null, base, key).toString("base64"); + headers["signature-input"] = `sig1=${raw}`; + headers["signature"] = `sig1=:${sig}:`; + return headers; +} + +function wbaVerify(headers: Record, kid = WBA_KEYID) { + return verifyRequest( + "POST", + "merchant.example.com", + "/checkout-sessions", + "", + headers, + WBA_BODY, + [{ ...RFC_ED25519_JWK, kid }] + ); +} + +test("RFC 7638 thumbprints match RFC 8037 A.3 and the signatures.md keyid", () => { + assert.equal(jwkThumbprint(RFC_ED25519_JWK), WBA_KEYID); + assert.equal( + jwkThumbprint({ + kty: "OKP", + crv: "Ed25519", + x: "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo", + }), + "kPrK_qmxVWaYVA9wwBF6Iuo3vVzz7TxHCTwXBygrS4k" + ); +}); + +test("the selected Dictionary member is serialized without optional whitespace", () => { + const value = + 'sig2="https://b.example", sig1="https://a.example"; type=jwks_uri'; + assert.equal( + dictionaryMember(value, "sig1"), + '"https://a.example";type=jwks_uri' + ); + assert.equal(dictionaryMember("sig1;a, sig2", "sig1"), "?1;a"); + assert.equal(dictionaryMember(value, "sig3"), null); +}); + +test("a key parameter is kept per component; other parameters are flagged", () => { + const parsed = parseSignatureInput( + 'sig1=("@method" "signature-agent";key="sig1");keyid="k", ' + + 'sig2=("content-type";sf);keyid="k"' + ); + assert.ok(parsed); + assert.deepEqual(parsed["sig1"]?.components, ["@method", "signature-agent"]); + assert.deepEqual(parsed["sig1"]?.componentKeys, [null, "sig1"]); + assert.equal(parsed["sig1"]?.unsupported, false); + assert.equal(parsed["sig2"]?.unsupported, true); +}); + +test("the recommended WBA-shape signature verifies via UCP-Agent keys", () => { + assert.equal(wbaVerify(wbaSigned()), WBA_KEYID); +}); + +test("under tag=web-bot-auth a keyid other than the thumbprint is rejected", () => { + const err = assertSignatureError( + () => wbaVerify(wbaSigned("test-key-ed25519"), "test-key-ed25519"), + "signature_invalid" + ); + assert.match(err.message, /thumbprint/); +}); + +test("a signature that leaves out the present Signature-Agent is rejected", () => { + const components = WBA_COMPONENTS.filter( + (c) => !c.includes("signature-agent") + ); + const err = assertSignatureError( + () => wbaVerify(wbaSigned(WBA_KEYID, components)), + "signature_invalid" + ); + assert.match(err.message, /signature-agent/); +}); + +test("another label's unsupported parameter does not hide a valid signature", () => { + const headers = wbaSigned(); + headers["signature-input"] = + 'sig0=("@method";sf);keyid="x", ' + headers["signature-input"]; + headers["signature"] = "sig0=:AAAA:, " + headers["signature"]; + assert.equal(wbaVerify(headers), WBA_KEYID); +}); + +test("a required component signed as one member does not cover the field", () => { + const cases: Record = { + // The body check finds sha-256 in the unsigned member. + "content-digest": `a=1, ${contentDigest(WBA_BODY)}`, + "idempotency-key": "a=1, b=2", + "ucp-agent": `a=1, profile="${WBA_PROFILE}"`, + }; + for (const [name, value] of Object.entries(cases)) { + const component = `"${name}";key="a"`; + const components = WBA_COMPONENTS.map((c) => + c === `"${name}"` ? component : c + ); + const err = assertSignatureError( + () => + wbaVerify( + wbaSigned( + WBA_KEYID, + components, + { [name]: value }, + { [component]: "1" } + ) + ), + "signature_invalid" + ); + assert.ok(err.message.includes(name), name); + } +}); + +test("signature-agent signed as another label's member is not covered", () => { + const component = '"signature-agent";key="other"'; + const components = WBA_COMPONENTS.map((c) => + c.startsWith('"signature-agent"') ? component : c + ); + const headersUpdate = { + "signature-agent": + `sig1="${WBA_PROFILE}";type=jwks_uri, ` + + 'other="https://agent.example/keys";type=jwks_uri', + }; + const err = assertSignatureError( + () => + wbaVerify( + wbaSigned(WBA_KEYID, components, headersUpdate, { + [component]: '"https://agent.example/keys";type=jwks_uri', + }) + ), + "signature_invalid" + ); + assert.match(err.message, /signature-agent/); +}); + +test("signature-agent signed without a key parameter covers the field", () => { + const components = WBA_COMPONENTS.map((c) => + c.startsWith('"signature-agent"') ? '"signature-agent"' : c + ); + assert.equal(wbaVerify(wbaSigned(WBA_KEYID, components)), WBA_KEYID); +}); + +test("a kty that is not a key type name is a malformed key, not a crash", () => { + for (const kty of ["toString", ["OKP"]]) { + const jwk = { ...RFC_ED25519_JWK, kid: WBA_KEYID, kty } as unknown as Jwk; + assert.equal(jwkThumbprint(jwk), null); + assertSignatureError( + () => + verifyRequest( + "POST", + "merchant.example.com", + "/checkout-sessions", + "", + wbaSigned(), + WBA_BODY, + [jwk] + ), + "signature_invalid" + ); + } +}); + +test("a Dictionary member with an empty item has no value", () => { + assert.equal(dictionaryMember("sig1=;type=jwks_uri", "sig1"), null); +}); + +test("a derived-component key, a repeated key or a lone quote is flagged", () => { + for (const value of [ + 'sig1=("@method";key="a");keyid="k"', + 'sig1=("signature-agent";key="sig1";key="sig2");keyid="k"', + 'sig1=("signature-agent";key=")', + ]) { + assert.equal( + parseSignatureInput(value)?.["sig1"]?.unsupported, + true, + value + ); + } +}); + /* Caller-requested extra covered components beyond the UCP minimum. * * RFC 9421 lets a signer cover any component; the UCP table is the required diff --git a/rest/python/server/ucp_signing.py b/rest/python/server/ucp_signing.py index 371f769f..e18114ac 100644 --- a/rest/python/server/ucp_signing.py +++ b/rest/python/server/ucp_signing.py @@ -22,6 +22,8 @@ * ECDSA P-256 (`ES256`) verification with fixed-width raw `r||s` signatures (RFC 9421 Section 3.3.4) -- never ASN.1/DER -- and Ed25519 (RFC 8032). * Signer public-key discovery from the `UCP-Agent` profile's `signing_keys[]`. +* WBA-shape (dual-audience) signatures: the `key` component parameter (RFC 9421 + Section 2.1.2) for `signature-agent`, and the RFC 7638 `keyid` binding. Only the encoding and canonicalization are implemented here; every cryptographic primitive comes from the `cryptography` package. The module is @@ -32,7 +34,9 @@ import base64 import hashlib import ipaddress +import json import logging +import re import socket import time from urllib.parse import urlsplit @@ -56,6 +60,17 @@ "P-256": ("ES256", 32), } +# RFC 7638 Section 3.2: the required members of each key type, in the +# lexicographic order the thumbprint input uses. +_THUMBPRINT_MEMBERS = { + "EC": ("crv", "kty", "x", "y"), + "OKP": ("crv", "kty", "x"), + "RSA": ("e", "kty", "n"), +} + +# An RFC 8941 Dictionary member key, at the start of a member. +_SF_KEY = re.compile(r"[a-z*][a-z0-9_\-.*]*") + class SignatureError(Exception): """A signature or profile-resolution failure with UCP wire semantics. @@ -185,10 +200,14 @@ def parse_signature_input(value: str) -> dict | None: value: The ``Signature-Input`` header value. Returns: - A mapping ``{label: {"raw", "components", "params"}}`` where ``raw`` is the - member value verbatim (what ``@signature-params`` must echo), ``components`` - are the unquoted component identifiers, and ``params`` maps parameter names - to their unquoted values. None on malformed input. + A mapping ``{label: {"raw", "components", "component_keys", "unsupported", + "params"}}`` where ``raw`` is the member value verbatim (what + ``@signature-params`` must echo), ``components`` are the unquoted component + names, ``component_keys`` holds each component's ``key`` parameter (RFC + 9421 Section 2.1.2) or None, ``unsupported`` is True when a component + carries any other parameter, a key on a derived component or a repeated + key, and ``params`` maps parameter names to their unquoted values. None on + malformed input. """ if not isinstance(value, str) or not value.strip(): @@ -213,19 +232,48 @@ def parse_signature_input(value: str) -> dict | None: inner = val[1:end] rest = val[end + 1 :] components: list[str] = [] + component_keys: list[str | None] = [] + unsupported = False for tok in _sf_split(inner, " "): - if not (tok.startswith('"') and tok.endswith('"')) or ";" in tok: + name, *component_params = _sf_split(tok, ";") + if len(name) < 2 or not (name.startswith('"') and name.endswith('"')): return None - components.append(tok[1:-1]) + key = None + for param in component_params: + k, _, v = param.partition("=") + # key selects a Dictionary member of a field (RFC 9421 Section + # 2.1.2): a derived component takes no key (Section 2.2), and a + # repeated key leaves the member ambiguous. + if ( + k.strip() == "key" + and key is None + and not name.startswith('"@') + and len(v) >= 2 + and v.startswith('"') + and v.endswith('"') + ): + key = v[1:-1] + else: + # A parameter this verifier does not implement makes only this + # signature unverifiable, not the whole header (RFC 9421 4.3). + unsupported = True + components.append(name[1:-1]) + component_keys.append(key) params: dict[str, str] = {} for part in _sf_split(rest, ";"): if not part: continue k, _, v = part.partition("=") - if v.startswith('"') and v.endswith('"'): + if len(v) >= 2 and v.startswith('"') and v.endswith('"'): v = v[1:-1] params[k.strip()] = v - out[label] = {"raw": val, "components": components, "params": params} + out[label] = { + "raw": val, + "components": components, + "component_keys": component_keys, + "unsupported": unsupported, + "params": params, + } return out or None @@ -256,14 +304,16 @@ def parse_signature(value: str) -> dict | None: def build_signature_base( - components: list[str], + components: list, raw_params: str, resolve: "callable", ) -> bytes | None: """Construct the RFC 9421 signature base. Args: - components: The ordered component identifiers to cover. + components: The ordered component identifiers to cover: a name, or a + ``(name, key)`` pair for a Dictionary member selected with the ``key`` + parameter (RFC 9421 Section 2.1.2). raw_params: The ``Signature-Input`` member value verbatim, echoed on the ``@signature-params`` line. resolve: A callable mapping a component identifier to its string value, or @@ -274,15 +324,77 @@ def build_signature_base( """ lines: list[str] = [] - for name in components: - value = resolve(name) + for component in components: + value = resolve(component) if value is None: return None - lines.append(f'"{name}": {value}') + if isinstance(component, tuple): + name, key = component + identifier = f'"{name}";key="{key}"' + else: + identifier = f'"{component}"' + lines.append(f"{identifier}: {value}") lines.append(f'"@signature-params": {raw_params}') return "\n".join(lines).encode("utf-8") +def dictionary_member(value: str, key: str) -> str | None: + """Return one Dictionary member's value as RFC 9421 Section 2.1.2 signs it. + + Args: + value: A field value holding an RFC 8941 Dictionary. + key: The member key the component's ``key`` parameter names. + + Returns: + The member value with its parameters, serialized without optional + whitespace, or None when the Dictionary has no such member. As in RFC 8941, + the last of duplicate members wins. + + """ + found = None + for member in _sf_split(value, ","): + match = _SF_KEY.match(member) + if not match or match.group(0) != key: + continue + rest = member[match.end() :] + if rest.startswith("="): + found = rest[1:] + elif not rest or rest.startswith(";"): + found = "?1" + rest # A member without a value is boolean true. + parts = _sf_split(found, ";") if found is not None else [] + # An empty item, as in sig1=;type=jwks_uri, is not a member value. + if not parts or not parts[0]: + return None + item, *params = parts + serialized = item + for param in params: + k, eq, v = param.partition("=") + k, v = k.strip(), v.strip() + serialized += f";{k}" if not eq or v == "?1" else f";{k}={v}" + return serialized + + +def jwk_thumbprint(jwk: dict) -> str | None: + """Return the RFC 7638 SHA-256 thumbprint of a JWK, base64url-encoded. + + Args: + jwk: A JWK of type EC, OKP or RSA. + + Returns: + The thumbprint, or None for another key type or a JWK missing a member the + thumbprint needs. + + """ + # The profile is signer-published, so kty may be of any type, and an + # unhashable one would raise in the lookup. + kty = jwk.get("kty") + members = _THUMBPRINT_MEMBERS.get(kty) if isinstance(kty, str) else None + if members is None or not all(isinstance(jwk.get(m), str) for m in members): + return None + canonical = json.dumps({m: jwk[m] for m in members}, separators=(",", ":")) + return _b64u_encode(hashlib.sha256(canonical.encode("utf-8")).digest()) + + def required_components( method: str, has_query: bool, @@ -316,12 +428,11 @@ def required_components( required.append("idempotency-key") if "ucp-agent" in headers: required.append("ucp-agent") - # signature-agent is a WBA-shape component (carried with RFC 8941 component - # parameters, e.g. "signature-agent";key="sig1", under tag=web-bot-auth). This - # verifier covers the default-UCP regime only and does not parse WBA-shape - # component parameters, so it does not gate on signature-agent — the coverage - # promise matches what the module can actually verify. WBA-shape support - # (member selection, keyid thumbprint binding) is a documented follow-up. + # A WBA-shape (dual-audience) signature covers signature-agent with a key + # parameter naming its own label, e.g. "signature-agent";key="sig1"; + # verify_request accepts that form for signature-agent only. + if "signature-agent" in headers: + required.append("signature-agent") return required @@ -548,7 +659,12 @@ def verify_request( if isinstance(k, dict) and isinstance(k.get("kid"), str) and _sig_capable(k) } - def resolve(name: str) -> str | None: + def resolve(name) -> str | None: + if isinstance(name, tuple): + # RFC 9421 Section 2.1.2: the key parameter selects a Dictionary member. + field, key = name + value = headers.get(field) + return dictionary_member(value, key) if isinstance(value, str) else None if name == "@method": return method.upper() if name == "@authority": @@ -575,8 +691,26 @@ def resolve(name: str) -> str | None: "Signature-Input MUST NOT carry an 'alg' parameter", ) continue - if not set(required).issubset(desc["components"]): - missing = sorted(set(required) - set(desc["components"])) + if desc["unsupported"]: + last_error = SignatureError( + "signature_invalid", + 401, + "Signature covers a component parameter other than key", + ) + continue + covered = set(zip(desc["components"], desc["component_keys"], strict=True)) + # A component signed with a key parameter binds one Dictionary member and + # leaves the rest of the field unbound, such as a second digest in + # Content-Digest, so a required component counts only when it is signed + # whole. signature-agent is the exception: signatures.md binds the + # Signature-Input label to the key parameter and the member it selects. + missing = sorted( + name + for name in required + if (name, None) not in covered + and not (name == "signature-agent" and (name, label) in covered) + ) + if missing: last_error = SignatureError( "signature_invalid", 401, @@ -590,7 +724,24 @@ def resolve(name: str) -> str | None: "key_not_found", 401, f"No published key with kid={keyid!r}" ) continue - base = build_signature_base(desc["components"], desc["raw"], resolve) + # signatures.md, step pre-2a: a WBA-shape signature's keyid MUST be the + # RFC 7638 thumbprint of the key it resolved to. + if desc["params"].get("tag") == "web-bot-auth": + thumbprint = jwk_thumbprint(jwk) + if thumbprint is None or keyid != thumbprint: + last_error = SignatureError( + "signature_invalid", + 401, + "tag=web-bot-auth requires keyid to be the key's RFC 7638 thumbprint", + ) + continue + components = [ + name if key is None else (name, key) + for name, key in zip( + desc["components"], desc["component_keys"], strict=True + ) + ] + base = build_signature_base(components, desc["raw"], resolve) if base is None: last_error = SignatureError( "signature_invalid", 401, "Unresolvable signed component" diff --git a/rest/python/server/ucp_signing_test.py b/rest/python/server/ucp_signing_test.py index 66e2d153..c46912bc 100644 --- a/rest/python/server/ucp_signing_test.py +++ b/rest/python/server/ucp_signing_test.py @@ -240,6 +240,30 @@ def test_malformed_returns_none(self) -> None: self.assertIsNone(signing.parse_signature_input("not a signature input")) self.assertIsNone(signing.parse_signature("")) + def test_component_key_parameter(self) -> None: + """A key parameter is kept per component; other parameters are flagged.""" + parsed = signing.parse_signature_input( + 'sig1=("@method" "signature-agent";key="sig1");keyid="k", ' + 'sig2=("content-type";sf);keyid="k"' + ) + self.assertEqual( + parsed["sig1"]["components"], ["@method", "signature-agent"] + ) + self.assertEqual(parsed["sig1"]["component_keys"], [None, "sig1"]) + self.assertFalse(parsed["sig1"]["unsupported"]) + self.assertTrue(parsed["sig2"]["unsupported"]) + + def test_key_only_once_on_a_field_as_a_string(self) -> None: + """A derived-component key, a repeated key or a lone quote is flagged.""" + for value in ( + 'sig1=("@method";key="a");keyid="k"', + 'sig1=("signature-agent";key="sig1";key="sig2");keyid="k"', + 'sig1=("signature-agent";key=")', + ): + with self.subTest(value): + parsed = signing.parse_signature_input(value) + self.assertTrue(parsed["sig1"]["unsupported"]) + class CoverageGateTest(absltest.TestCase): """The UCP required-component coverage table.""" @@ -268,19 +292,13 @@ def test_idempotency_key_header_on_get(self) -> None: ) self.assertIn("idempotency-key", required) - def test_ucp_agent_covered_signature_agent_out_of_scope(self) -> None: - """A present ucp-agent header must be covered; signature-agent is not. - - signature-agent is a WBA-shape component (component parameters / - tag=web-bot-auth) that this default-UCP verifier does not parse, so it is - deliberately outside the coverage gate: the module's promise matches what - it can actually verify. - """ + def test_present_ucp_agent_and_signature_agent_must_be_covered(self) -> None: + """Present ucp-agent and signature-agent headers must both be covered.""" required = signing.required_components( "GET", False, {"ucp-agent": "a", "signature-agent": "b"}, False ) self.assertIn("ucp-agent", required) - self.assertNotIn("signature-agent", required) + self.assertIn("signature-agent", required) def test_alg_param_rejected_by_verify_request(self) -> None: """A signature carrying an alg parameter is rejected (spec MUST NOT).""" @@ -307,6 +325,209 @@ def test_alg_param_rejected_by_verify_request(self) -> None: self.assertEqual(ctx.exception.code, "signature_invalid") +# RFC 7638 thumbprint of RFC_ED25519_JWK; the keyid of the signatures.md +# dual-audience example. +WBA_KEYID = "poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U" + + +class WbaShapeTest(absltest.TestCase): + """Dual-audience signatures from the signatures.md WBA Interop section.""" + + PROFILE = "https://platform.example/.well-known/ucp" + BODY = b'{"line_items":[]}' + COMPONENTS = ( + '"@method"', + '"@authority"', + '"@path"', + '"signature-agent";key="sig1"', + '"ucp-agent"', + '"idempotency-key"', + '"content-digest"', + '"content-type"', + ) + + def _signed( + self, + keyid: str = WBA_KEYID, + components: tuple = COMPONENTS, + headers_update: dict | None = None, + values_update: dict | None = None, + ): + """Sign the example request over a hand-built RFC 9421 base.""" + headers = { + "ucp-agent": f'profile="{self.PROFILE}"', + "signature-agent": f'sig1="{self.PROFILE}";type=jwks_uri', + "idempotency-key": "550e8400-e29b-41d4-a716-446655440000", + "content-type": "application/json", + "content-digest": signing.content_digest(self.BODY), + **(headers_update or {}), + } + raw = ( + f'({" ".join(components)});keyid="{keyid}";created=1738617600;' + 'expires=1738621200;tag="web-bot-auth"' + ) + values = { + '"@method"': "POST", + '"@authority"': "merchant.example.com", + '"@path"': "/checkout-sessions", + # RFC 9421 Section 2.1.2: the value of the sig1 member, not the field. + '"signature-agent";key="sig1"': f'"{self.PROFILE}";type=jwks_uri', + '"ucp-agent"': headers["ucp-agent"], + '"idempotency-key"': headers["idempotency-key"], + '"content-digest"': headers["content-digest"], + '"content-type"': headers["content-type"], + '"signature-agent"': headers["signature-agent"], + **(values_update or {}), + } + lines = [f"{c}: {values[c]}" for c in components] + base = "\n".join([*lines, f'"@signature-params": {raw}']).encode() + key = ed25519.Ed25519PrivateKey.from_private_bytes(_b64u(RFC_ED25519_D)) + sig = base64.b64encode(key.sign(base)).decode("ascii") + headers["signature-input"] = f"sig1={raw}" + headers["signature"] = f"sig1=:{sig}:" + return headers + + def _verify(self, headers: dict, kid: str = WBA_KEYID) -> str: + jwk = dict(RFC_ED25519_JWK, kid=kid) + return signing.verify_request( + "POST", + "merchant.example.com", + "/checkout-sessions", + "", + headers, + self.BODY, + [jwk], + ) + + def test_thumbprint_vectors(self) -> None: + """RFC 7638 thumbprints match RFC 8037 A.3 and the signatures.md keyid.""" + self.assertEqual(signing.jwk_thumbprint(RFC_ED25519_JWK), WBA_KEYID) + self.assertEqual( + signing.jwk_thumbprint( + { + "kty": "OKP", + "crv": "Ed25519", + "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo", + } + ), + "kPrK_qmxVWaYVA9wwBF6Iuo3vVzz7TxHCTwXBygrS4k", + ) + + def test_dictionary_member_is_reserialized(self) -> None: + """The selected member is serialized without optional whitespace.""" + value = 'sig2="https://b.example", sig1="https://a.example"; type=jwks_uri' + self.assertEqual( + signing.dictionary_member(value, "sig1"), + '"https://a.example";type=jwks_uri', + ) + self.assertEqual(signing.dictionary_member("sig1;a, sig2", "sig1"), "?1;a") + self.assertIsNone(signing.dictionary_member(value, "sig3")) + + def test_dual_audience_signature_verifies(self) -> None: + """The recommended WBA-shape signature verifies via UCP-Agent keys.""" + self.assertEqual(self._verify(self._signed()), WBA_KEYID) + + def test_web_bot_auth_keyid_must_be_the_thumbprint(self) -> None: + """Under tag=web-bot-auth a keyid other than the thumbprint is rejected.""" + headers = self._signed(keyid="test-key-ed25519") + with self.assertRaises(signing.SignatureError) as ctx: + self._verify(headers, kid="test-key-ed25519") + self.assertEqual(ctx.exception.code, "signature_invalid") + self.assertIn("thumbprint", ctx.exception.message) + + def test_present_signature_agent_must_be_covered(self) -> None: + """A signature that leaves out the present Signature-Agent is rejected.""" + headers = self._signed( + components=tuple(c for c in self.COMPONENTS if "signature-agent" not in c) + ) + with self.assertRaises(signing.SignatureError) as ctx: + self._verify(headers) + self.assertIn("signature-agent", ctx.exception.message) + + def test_unsupported_parameter_skips_only_that_signature(self) -> None: + """Another label's unsupported parameter does not hide a valid signature.""" + headers = self._signed() + headers["signature-input"] = ( + 'sig0=("@method";sf);keyid="x", ' + headers["signature-input"] + ) + headers["signature"] = "sig0=:AAAA:, " + headers["signature"] + self.assertEqual(self._verify(headers), WBA_KEYID) + + def test_required_component_signed_as_one_member_is_not_covered(self) -> None: + """A key parameter on a required component leaves the rest unbound.""" + cases = { + # The body check finds sha-256 in the unsigned member. + "content-digest": f"a=1, {signing.content_digest(self.BODY)}", + "idempotency-key": "a=1, b=2", + "ucp-agent": f'a=1, profile="{self.PROFILE}"', + } + for name, value in cases.items(): + with self.subTest(name): + component = f'"{name}";key="a"' + headers = self._signed( + components=tuple( + component if c == f'"{name}"' else c for c in self.COMPONENTS + ), + headers_update={name: value}, + values_update={component: "1"}, + ) + with self.assertRaises(signing.SignatureError) as ctx: + self._verify(headers) + self.assertEqual(ctx.exception.code, "signature_invalid") + self.assertIn(name, ctx.exception.message) + + def test_signature_agent_member_must_be_the_signature_label(self) -> None: + """signature-agent signed as another label's member is not covered.""" + component = '"signature-agent";key="other"' + headers = self._signed( + components=tuple( + component if c.startswith('"signature-agent"') else c + for c in self.COMPONENTS + ), + headers_update={ + "signature-agent": ( + f'sig1="{self.PROFILE}";type=jwks_uri, ' + 'other="https://agent.example/keys";type=jwks_uri' + ) + }, + values_update={component: '"https://agent.example/keys";type=jwks_uri'}, + ) + with self.assertRaises(signing.SignatureError) as ctx: + self._verify(headers) + self.assertEqual(ctx.exception.code, "signature_invalid") + self.assertIn("signature-agent", ctx.exception.message) + + def test_signature_agent_signed_whole_is_covered(self) -> None: + """signature-agent signed without a key parameter covers the field.""" + headers = self._signed( + components=tuple( + '"signature-agent"' if c.startswith('"signature-agent"') else c + for c in self.COMPONENTS + ) + ) + self.assertEqual(self._verify(headers), WBA_KEYID) + + def test_malformed_kty_is_signature_invalid(self) -> None: + """A kty that is not a string is a malformed key, not a server error.""" + self.assertIsNone(signing.jwk_thumbprint({"kty": ["EC"]})) + jwk = dict(RFC_ED25519_JWK, kid=WBA_KEYID, kty=["OKP"]) + with self.assertRaises(signing.SignatureError) as ctx: + signing.verify_request( + "POST", + "merchant.example.com", + "/checkout-sessions", + "", + self._signed(), + self.BODY, + [jwk], + ) + self.assertEqual(ctx.exception.code, "signature_invalid") + + def test_dictionary_member_with_an_empty_item_is_none(self) -> None: + """A member with no item before its parameters has no value.""" + self.assertIsNone(signing.dictionary_member("sig1=;type=jwks_uri", "sig1")) + + class SsrfGuardTest(absltest.TestCase): """Profile-URL transport and SSRF guards."""