@whooshbang/contracts 1.0.0-rc.13

package/dist/webhook-signature.js

@@ -0,0 +1,255 @@
+export const DEFAULT_WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS = 300;
+export const MAX_WEBHOOK_SIGNATURES = 2;
+export const MAX_WEBHOOK_SECRETS = 2;
+const runtimeGlobal = globalThis;
+const eventIdentifier = /^evt_[A-Za-z0-9_-]+$/u;
+const canonicalTimestamp = /^(?:0|[1-9][0-9]{0,14})$/u;
+const canonicalAttempt = /^[1-8]$/u;
+const signatureToken = /^([A-Za-z0-9]+),([A-Za-z0-9+/]+={0,2})$/u;
+const canonicalBase64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u;
+function reject(reason) {
+    return { reason, verified: false };
+}
+function collectHeaderValues(headers, wantedName) {
+    const values = [];
+    const runtimeHeaders = headers;
+    if (Array.isArray(runtimeHeaders)) {
+        for (const entry of runtimeHeaders) {
+            if (!Array.isArray(entry) ||
+                entry.length !== 2 ||
+                typeof entry[0] !== "string" ||
+                typeof entry[1] !== "string") {
+                return { status: "malformed" };
+            }
+            if (entry[0].toLowerCase() === wantedName) {
+                values.push(entry[1]);
+            }
+        }
+    }
+    else if (typeof runtimeHeaders === "object" && runtimeHeaders !== null) {
+        for (const [name, rawValue] of Object.entries(runtimeHeaders)) {
+            if (name.toLowerCase() !== wantedName || rawValue === undefined) {
+                continue;
+            }
+            if (typeof rawValue === "string") {
+                values.push(rawValue);
+            }
+            else if (Array.isArray(rawValue) &&
+                rawValue.every((value) => typeof value === "string")) {
+                values.push(...rawValue);
+            }
+            else {
+                return { status: "malformed" };
+            }
+        }
+    }
+    else {
+        return { status: "malformed" };
+    }
+    if (values.length === 0) {
+        return { status: "missing" };
+    }
+    if (values.length !== 1) {
+        return { status: "duplicate" };
+    }
+    const value = values[0];
+    return value === undefined
+        ? { status: "malformed" }
+        : { status: "ok", value };
+}
+function headerFailure(result) {
+    if (result.status === "missing") {
+        return reject("missing_header");
+    }
+    if (result.status === "duplicate") {
+        return reject("duplicate_header");
+    }
+    return reject("malformed_header");
+}
+function decodeCanonicalBase64(value) {
+    if (!canonicalBase64.test(value)) {
+        return undefined;
+    }
+    try {
+        const decoded = atob(value);
+        if (btoa(decoded) !== value) {
+            return undefined;
+        }
+        return Uint8Array.from(decoded, (character) => character.charCodeAt(0));
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseSecret(value) {
+    if (!value.startsWith("whsec_")) {
+        return undefined;
+    }
+    const decoded = decodeCanonicalBase64(value.slice("whsec_".length));
+    return decoded !== undefined &&
+        decoded.byteLength >= 24 &&
+        decoded.byteLength <= 64
+        ? decoded
+        : undefined;
+}
+function parseSignatures(value) {
+    if (value.length === 0 ||
+        value.startsWith(" ") ||
+        value.endsWith(" ") ||
+        value.includes("  ")) {
+        return "malformed_signature";
+    }
+    const tokens = value.split(" ");
+    if (tokens.length > MAX_WEBHOOK_SIGNATURES) {
+        return "too_many_signatures";
+    }
+    const signatures = [];
+    const seen = new Set();
+    for (const token of tokens) {
+        const match = signatureToken.exec(token);
+        const version = match?.[1];
+        const encoded = match?.[2];
+        if (version === undefined || encoded === undefined) {
+            return "malformed_signature";
+        }
+        if (version !== "v1") {
+            return "unsupported_signature_version";
+        }
+        if (seen.has(token)) {
+            return "duplicate_signature";
+        }
+        seen.add(token);
+        const bytes = decodeCanonicalBase64(encoded);
+        if (bytes === undefined || bytes.byteLength !== 32) {
+            return "malformed_signature";
+        }
+        signatures.push({ bytes, encoded });
+    }
+    return signatures;
+}
+function signingBytes(eventId, timestamp, rawBody) {
+    const prefix = new TextEncoder().encode(`${eventId}.${timestamp}.`);
+    const result = new Uint8Array(prefix.byteLength + rawBody.byteLength);
+    result.set(prefix);
+    result.set(rawBody, prefix.byteLength);
+    return result;
+}
+function constantTimeEqual(left, right) {
+    let mismatch = left.byteLength ^ right.byteLength;
+    const length = Math.max(left.byteLength, right.byteLength);
+    for (let index = 0; index < length; index += 1) {
+        mismatch |=
+            (left[index % left.byteLength] ?? 0) ^
+                (right[index % right.byteLength] ?? 0);
+    }
+    return mismatch === 0;
+}
+/**
+ * Verifies the Standard Webhooks V1 signature over the exact request bytes.
+ *
+ * Header entries are accepted as tuples so callers can preserve and reject
+ * duplicate security headers before framework normalization.
+ */
+export async function verifyWebhookSignature(options) {
+    if (!(options.rawBody instanceof Uint8Array)) {
+        return reject("invalid_body");
+    }
+    const runtimeCrypto = options.crypto ?? runtimeGlobal.crypto;
+    if (runtimeCrypto === undefined) {
+        return reject("crypto_unavailable");
+    }
+    const idHeader = collectHeaderValues(options.headers, "webhook-id");
+    if (idHeader.status !== "ok") {
+        return headerFailure(idHeader);
+    }
+    if (idHeader.value.length < 8 ||
+        idHeader.value.length > 128 ||
+        !eventIdentifier.test(idHeader.value)) {
+        return reject("malformed_webhook_id");
+    }
+    const timestampHeader = collectHeaderValues(options.headers, "webhook-timestamp");
+    if (timestampHeader.status !== "ok") {
+        return headerFailure(timestampHeader);
+    }
+    if (!canonicalTimestamp.test(timestampHeader.value)) {
+        return reject("malformed_timestamp");
+    }
+    const timestamp = Number(timestampHeader.value);
+    if (!Number.isSafeInteger(timestamp)) {
+        return reject("malformed_timestamp");
+    }
+    const signatureHeader = collectHeaderValues(options.headers, "webhook-signature");
+    if (signatureHeader.status !== "ok") {
+        return headerFailure(signatureHeader);
+    }
+    const signatures = parseSignatures(signatureHeader.value);
+    if (typeof signatures === "string") {
+        return reject(signatures);
+    }
+    const attemptHeader = collectHeaderValues(options.headers, "webhook-attempt");
+    if (attemptHeader.status !== "ok") {
+        return headerFailure(attemptHeader);
+    }
+    if (!canonicalAttempt.test(attemptHeader.value)) {
+        return reject("malformed_attempt");
+    }
+    const attempt = Number(attemptHeader.value);
+    const tolerance = options.toleranceSeconds ?? DEFAULT_WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS;
+    if (!Number.isSafeInteger(tolerance) ||
+        tolerance < 1 ||
+        tolerance > DEFAULT_WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS) {
+        return reject("invalid_tolerance");
+    }
+    const nowSeconds = options.nowSeconds === undefined
+        ? Math.floor(Date.now() / 1000)
+        : options.nowSeconds;
+    if (!Number.isSafeInteger(nowSeconds) || nowSeconds < 0) {
+        return reject("invalid_clock");
+    }
+    if (Math.abs(nowSeconds - timestamp) > tolerance) {
+        return reject("timestamp_outside_tolerance");
+    }
+    if (!Array.isArray(options.secrets) ||
+        !options.secrets.every((secret) => typeof secret === "string")) {
+        return reject("invalid_secret");
+    }
+    if (options.secrets.length > MAX_WEBHOOK_SECRETS) {
+        return reject("too_many_secrets");
+    }
+    if (options.secrets.length === 0) {
+        return reject("invalid_secret");
+    }
+    if (new Set(options.secrets).size !== options.secrets.length) {
+        return reject("duplicate_secret");
+    }
+    const decodedSecrets = options.secrets.map(parseSecret);
+    if (decodedSecrets.some((secret) => secret === undefined)) {
+        return reject("invalid_secret");
+    }
+    const message = signingBytes(idHeader.value, timestampHeader.value, options.rawBody);
+    let matched = false;
+    try {
+        for (const possibleSecret of decodedSecrets) {
+            if (possibleSecret === undefined) {
+                continue;
+            }
+            const key = await runtimeCrypto.subtle.importKey("raw", Uint8Array.from(possibleSecret), { hash: "SHA-256", name: "HMAC" }, false, ["sign"]);
+            const digest = new Uint8Array(await runtimeCrypto.subtle.sign("HMAC", key, Uint8Array.from(message)));
+            for (const signature of signatures) {
+                matched = constantTimeEqual(digest, signature.bytes) || matched;
+            }
+        }
+    }
+    catch {
+        return reject("crypto_unavailable");
+    }
+    return matched
+        ? {
+            attempt,
+            eventId: idHeader.value,
+            timestamp,
+            verified: true,
+        }
+        : reject("signature_mismatch");
+}
+//# sourceMappingURL=webhook-signature.js.map

package/dist/webhook-signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-signature.js","sourceRoot":"","sources":["../src/webhook-signature.ts"],"names":[],"mappings":"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"}

package/examples/python/verify_webhook.py

@@ -0,0 +1,283 @@
+#!/usr/bin/env python3
+"""Verify WhooshBang Standard Webhooks fixtures with the stdlib only."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import hmac
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+DEFAULT_TOLERANCE_SECONDS = 300
+MAX_SIGNATURES = 2
+MAX_SECRETS = 2
+
+EVENT_IDENTIFIER = re.compile(r"^evt_[A-Za-z0-9_-]+$", re.ASCII)
+CANONICAL_TIMESTAMP = re.compile(r"^(?:0|[1-9][0-9]{0,14})$", re.ASCII)
+CANONICAL_ATTEMPT = re.compile(r"^[1-8]$", re.ASCII)
+SIGNATURE_TOKEN = re.compile(
+    r"^([A-Za-z0-9]+),([A-Za-z0-9+/]+={0,2})$", re.ASCII
+)
+CANONICAL_BASE64 = re.compile(
+    r"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$",
+    re.ASCII,
+)
+
+
+def rejected(reason: str) -> dict[str, Any]:
+    """Return a deliberately redacted verification failure."""
+
+    return {"verified": False, "reason": reason}
+
+
+def single_header(
+    headers: Any, wanted_name: str
+) -> tuple[str | None, str | None]:
+    if not isinstance(headers, list):
+        return None, "malformed_header"
+
+    values: list[str] = []
+    for entry in headers:
+        if (
+            not isinstance(entry, (list, tuple))
+            or len(entry) != 2
+            or not isinstance(entry[0], str)
+            or not isinstance(entry[1], str)
+        ):
+            return None, "malformed_header"
+        if entry[0].lower() == wanted_name:
+            values.append(entry[1])
+
+    if not values:
+        return None, "missing_header"
+    if len(values) != 1:
+        return None, "duplicate_header"
+    return values[0], None
+
+
+def decode_canonical_base64(value: str) -> bytes | None:
+    if CANONICAL_BASE64.fullmatch(value) is None:
+        return None
+    try:
+        decoded = base64.b64decode(value, validate=True)
+    except (ValueError, binascii.Error):
+        return None
+    if base64.b64encode(decoded).decode("ascii") != value:
+        return None
+    return decoded
+
+
+def parse_secret(value: str) -> bytes | None:
+    if not value.startswith("whsec_"):
+        return None
+    decoded = decode_canonical_base64(value[len("whsec_") :])
+    if decoded is None or not 24 <= len(decoded) <= 64:
+        return None
+    return decoded
+
+
+def parse_signatures(value: str) -> tuple[list[bytes] | None, str | None]:
+    if (
+        not value
+        or value.startswith(" ")
+        or value.endswith(" ")
+        or "  " in value
+    ):
+        return None, "malformed_signature"
+
+    tokens = value.split(" ")
+    if len(tokens) > MAX_SIGNATURES:
+        return None, "too_many_signatures"
+
+    seen: set[str] = set()
+    signatures: list[bytes] = []
+    for token in tokens:
+        match = SIGNATURE_TOKEN.fullmatch(token)
+        if match is None:
+            return None, "malformed_signature"
+        version, encoded = match.groups()
+        if version != "v1":
+            return None, "unsupported_signature_version"
+        if token in seen:
+            return None, "duplicate_signature"
+        seen.add(token)
+        decoded = decode_canonical_base64(encoded)
+        if decoded is None or len(decoded) != 32:
+            return None, "malformed_signature"
+        signatures.append(decoded)
+    return signatures, None
+
+
+def is_plain_integer(value: Any) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def verify_webhook(
+    *,
+    raw_body: Any,
+    headers: Any,
+    secrets: Any,
+    now_seconds: Any,
+    tolerance_seconds: Any = DEFAULT_TOLERANCE_SECONDS,
+) -> dict[str, Any]:
+    """Verify one attempt without parsing or re-serializing its JSON body."""
+
+    if not isinstance(raw_body, bytes):
+        return rejected("invalid_body")
+
+    event_id, error = single_header(headers, "webhook-id")
+    if error is not None:
+        return rejected(error)
+    if (
+        event_id is None
+        or not 8 <= len(event_id) <= 128
+        or EVENT_IDENTIFIER.fullmatch(event_id) is None
+    ):
+        return rejected("malformed_webhook_id")
+
+    timestamp_text, error = single_header(headers, "webhook-timestamp")
+    if error is not None:
+        return rejected(error)
+    if (
+        timestamp_text is None
+        or CANONICAL_TIMESTAMP.fullmatch(timestamp_text) is None
+    ):
+        return rejected("malformed_timestamp")
+    timestamp = int(timestamp_text)
+
+    signature_text, error = single_header(headers, "webhook-signature")
+    if error is not None:
+        return rejected(error)
+    if signature_text is None:
+        return rejected("malformed_signature")
+    signatures, error = parse_signatures(signature_text)
+    if error is not None:
+        return rejected(error)
+    if signatures is None:
+        return rejected("malformed_signature")
+
+    attempt_text, error = single_header(headers, "webhook-attempt")
+    if error is not None:
+        return rejected(error)
+    if (
+        attempt_text is None
+        or CANONICAL_ATTEMPT.fullmatch(attempt_text) is None
+    ):
+        return rejected("malformed_attempt")
+    attempt = int(attempt_text)
+
+    if (
+        not is_plain_integer(tolerance_seconds)
+        or not 1 <= tolerance_seconds <= DEFAULT_TOLERANCE_SECONDS
+    ):
+        return rejected("invalid_tolerance")
+    if not is_plain_integer(now_seconds) or now_seconds < 0:
+        return rejected("invalid_clock")
+    if abs(now_seconds - timestamp) > tolerance_seconds:
+        return rejected("timestamp_outside_tolerance")
+
+    if not isinstance(secrets, list) or not all(
+        isinstance(secret, str) for secret in secrets
+    ):
+        return rejected("invalid_secret")
+    if len(secrets) > MAX_SECRETS:
+        return rejected("too_many_secrets")
+    if not secrets:
+        return rejected("invalid_secret")
+    if len(set(secrets)) != len(secrets):
+        return rejected("duplicate_secret")
+    decoded_secrets = [parse_secret(secret) for secret in secrets]
+    if any(secret is None for secret in decoded_secrets):
+        return rejected("invalid_secret")
+
+    signed_bytes = (
+        event_id.encode("ascii")
+        + b"."
+        + timestamp_text.encode("ascii")
+        + b"."
+        + raw_body
+    )
+    matched = False
+    for possible_secret in decoded_secrets:
+        if possible_secret is None:
+            continue
+        digest = hmac.new(
+            possible_secret, signed_bytes, hashlib.sha256
+        ).digest()
+        for signature in signatures:
+            matched = hmac.compare_digest(digest, signature) or matched
+
+    if not matched:
+        return rejected("signature_mismatch")
+    return {
+        "verified": True,
+        "event_id": event_id,
+        "timestamp": timestamp,
+        "attempt": attempt,
+    }
+
+
+def run_vectors(vector_path: Path) -> dict[str, Any]:
+    vector_set = json.loads(vector_path.read_text(encoding="utf-8"))
+    keys = vector_set["synthetic_verification_keys"]
+    bodies = vector_set["raw_bodies"]
+    cases = vector_set["cases"]
+
+    for vector in cases:
+        result = verify_webhook(
+            raw_body=bodies[vector["raw_body"]].encode("utf-8"),
+            headers=[
+                (header["name"], header["value"])
+                for header in vector["headers"]
+            ],
+            secrets=[keys[name] for name in vector["trusted_keys"]],
+            now_seconds=vector["now_seconds"],
+            tolerance_seconds=vector["tolerance_seconds"],
+        )
+        if result != vector["expected"]:
+            return {
+                "status": "fail",
+                "code": "WEBHOOK_VECTOR_MISMATCH",
+                "case_id": vector["id"],
+            }
+
+    return {
+        "status": "pass",
+        "code": "WEBHOOK_VECTORS_OK",
+        "cases": len(cases),
+    }
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        sys.stderr.write(
+            json.dumps(
+                {
+                    "status": "fail",
+                    "code": "WEBHOOK_VECTOR_PATH_REQUIRED",
+                }
+            )
+            + "\n"
+        )
+        return 2
+
+    try:
+        summary = run_vectors(Path(sys.argv[1]))
+    except Exception:
+        summary = {
+            "status": "fail",
+            "code": "WEBHOOK_VECTOR_RUN_FAILED",
+        }
+
+    stream = sys.stdout if summary["status"] == "pass" else sys.stderr
+    stream.write(json.dumps(summary, sort_keys=True) + "\n")
+    return 0 if summary["status"] == "pass" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/fixtures/.gitkeep

@@ -0,0 +1 @@
+