@open-everywhere/core 0.1.0

package/agent/webhooks/oe-standard-webhook.ts

@@ -0,0 +1,563 @@
+// ⭐⭐ CATEGORY (b) — A WEBHOOK CONTRACT **WE** DEFINE AND THE CALLER IMPLEMENTS, shipped as one
+// ordinary adapter (OPE-196). Verifier + envelope + normalizer, registered through the same
+// registries any provider bundle uses, with no special-casing anywhere.
+//
+// The organising rule (Tommy, 2026-07-27): every
+// webhook is either **(a)** an adapter that defines the auth scheme, or **(b)** a schema WE define
+// and the caller implements — and (b) are adapters too. This file is (b), the same way `env` is a
+// core credential broker that implements the ordinary broker interface (`agent/adapter-api.ts`).
+//
+// ═══ 🔴🔴 THE INVERSION — WHY A NORMALIZER CAN EXIST HERE WHEN IT CANNOT FOR A BARE SCHEME ═══
+//
+// Three places in this tree assert that a GENERIC scheme can never have a normalizer
+// (`webhooks/source-vocabulary.ts`, `routines/ingress.ts`, `channels/webhooks.ts`), and none of that
+// is retracted: a bare signature scheme says how bytes were signed and NOTHING about what they MEAN,
+// so there is no payload shape and a normalizer would have to invent one.
+//
+// 🔴 THE PREMISE FAILS HERE, AND ONLY HERE, BECAUSE FOR (b) WE DEFINE THE PAYLOAD SHAPE TOO. The
+// sender implements OUR contract — {@link StandardWebhookEnvelope} below — so the normalizer is ours
+// to write and it reads four fields we specified. This is a SOURCE KEY OF ITS OWN with its own
+// verifier, envelope and normalizer, which is exactly what those three comments say the fix would
+// have to be. Registering a bare signature scheme alongside it inherits NONE of that.
+//
+// ═══ THE SIGNING SCHEME: `standard-webhooks`, ADOPTED WHOLE — NOT A NEW ONE ═══
+//
+// https://github.com/standard-webhooks/standard-webhooks (Apache-2.0 spec). Implemented HERE against
+// the spec rather than depended on (`standardwebhooks@1.0.0` has shipped once since 2024-03 and the
+// verification is ~40 lines we want under our own `timingSafeEqual` and `WebhookVerifyFailure`
+// vocabulary regardless — the same call `webhooks/verifier.ts` makes about every scheme).
+//
+//   webhook-id:         <opaque message id>          ← SIGNED, and a REAL delivery nonce
+//   webhook-timestamp:  <unix seconds>               ← SIGNED
+//   webhook-signature:  v1,<base64 sig> [v1,<…> …]   ← space-delimited list, for key rotation
+//
+//   signed content = `${webhook-id}.${webhook-timestamp}.${rawBody}`
+//   signature      = base64( HMAC-SHA256(key, signedContent) )
+//
+// 🔴 WHY IT EARNS ITS PLACE OVER ROLLING OUR OWN — one reason, and it is not familiarity:
+// **`webhook-id` IS COVERED BY THE SIGNATURE**, so it is a nonce a sender cannot forge independently
+// of the body. A scheme with no message id has to synthesise its nonce from the SIGNATURE itself,
+// which collides for two legitimately identical payloads sent in the same unix second — the second
+// is then dropped as a replay it never was. No delivery id ⇒ no honest replay defence.
+//
+// THE TWO REPLAY LAYERS THIS SCHEME ARMS, numbered to match `webhooks/source-vocabulary.ts`, which
+// is the canonical statement of them:
+//   1. `deliveryIdHeader: "webhook-id"` ⇒ `admitTrigger`'s durable delivery dedupe engages
+//      (OPE-201) — the fan-out annoyance bound, TTL-windowed and FAIL-OPEN by design.
+//   2. `signedTimestamp: true` ⇒ `webhooks/gate.ts` keeps our `replayKey` ⇒ the 409 in
+//      `channels/webhooks.ts` fires on a re-POST inside the skew window (`webhooks/replay-dedupe.ts`,
+//      durable + cross-instance) — the real security bound.
+// Same signed id, two independent windows, deliberately.
+//
+// ⭐ THE KEY ENCODING IS THE SPEC'S. The spec describes the secret as *"base64 encoded, prefixed with
+// `whsec_` for easy identification"*, and both reference libraries strip the prefix and base64-DECODE
+// the remainder into the HMAC key (verified against the JavaScript and Python implementations, not
+// inferred from the prose — the spec text never says outright whether the prefix is key material, and
+// getting that wrong breaks every signature silently). {@link mintStandardWebhookSecret} mints that
+// form; {@link standardWebhookKey} reads it.
+//
+// 🔴 THE READ RULE IS TOTAL AND PREFIX-DISCRIMINATED, AND STAYS THAT WAY: `whsec_` ⇒ spec form,
+// anything else ⇒ the secret's own UTF-8 bytes. The second branch is what keeps minting the prefix
+// NON-WIRE-BREAKING — a hook holding a raw `base64url` secret keeps verifying and never has to be
+// rotated. It is NOT a "try both and see which verifies" fallback: that would be a downgrade
+// primitive, which `webhooks/verifier.ts` refuses by design. The discriminator lives in OUR secret,
+// never in the request, so a sender cannot influence which branch runs.
+//
+// What the prefix buys: an off-the-shelf `standard-webhooks` client library works drop-in, and the
+// secret is self-identifying if pasted where it does not belong. What it costs: the shell path grows
+// one line, because the key is BYTES and `openssl dgst -hmac` takes a string. The recipe below is
+// pinned by a frozen golden in `scripts/standard-webhook-test.ts`, so it cannot rot into a
+// plausible-looking lie:
+//
+//   KEY=$(printf '%s' "${SECRET#whsec_}" | base64 -d | od -An -tx1 | tr -d ' \n')
+//   SIG=$(printf '%s.%s.%s' "$ID" "$TS" "$BODY" | openssl dgst -sha256 -mac HMAC -macopt hexkey:"$KEY" -binary | base64)
+//   curl -X POST "$URL" -H "webhook-id: $ID" -H "webhook-timestamp: $TS" \
+//        -H "webhook-signature: v1,$SIG" -H 'content-type: application/json' -d "$BODY"
+//
+// (A hook holding a pre-prefix raw secret keeps the older, shorter form — `openssl dgst -sha256 -hmac
+// "$SECRET"` — which is what the second branch of the key rule means. The reveal page states the rule
+// rather than assuming which kind of secret a reader is holding.)
+//
+// ⚠️ THIS ENTRY DOES NOT BUY EVERY SVIX-COMPATIBLE SENDER. Clerk, Resend, Brex and friends GENERATE
+// the secret, so a hook fed by one is `keyOrigin: "vendor-issued"` and is structurally excluded from
+// the mintable vocabulary (`webhooks/source-vocabulary.ts`) no matter how compatible the crypto is.
+// Receiving from them is a SECOND registry entry of the same wire scheme with a different key origin
+// — a category-(a) bundle, and not this file. What this entry buys is the (b) audience: a customer's
+// own CI, a script, a Jenkins job, anything that can run the four lines above.
+//
+// ═══ THE SCOPE PATH: ROW-DERIVED, AND WHY THAT IS THE RULE HERE AND NOT EVERYWHERE ═══
+//
+// The invariant is NOT "hook-constant, never payload-derived" — that is a wrong overgeneralisation,
+// and a reader applying it would "fix" `routines/github-normalizer.ts`, which correctly derives its
+// entire path from the body. The rule is:
+//
+//   Scope may be derived from the payload ONLY to the extent the VERIFIER makes the sender
+//   authoritative over that namespace.
+//
+// GitHub's signature proves GitHub sent it, and GitHub is authoritative about which repo an event
+// came from. A (b) sender's signature proves possession of THAT HOOK'S KEY and nothing else: it is
+// authoritative over exactly one fact — which hook it is — and over no external namespace. So:
+//
+//   container = the hook's NAME           (TriggerDelivery.source      — from the ROW, never the body)
+//
+// ⭐ AND NOTHING BELOW `container` IS EMITTED AT ALL, NOR ANY STEP ABOVE IT. Authorization is the
+// hook's own declared `readableBy` (`access/read-grant.ts`, evaluated in `routines/event-authz.ts`),
+// so what is left here is the ROUTING path — all a normalizer should ever have owned. `entity`/`sub`
+// steps were available as an OPTIONAL payload-derived narrowing "for matching granularity only" and
+// this adapter declines the option: an entity step buys nothing an `all` clause on `fields` does not,
+// and it is the ONE place a sender could touch the scope path — so declining turns the invariant
+// above from an argument into a structural property, testable by construction. Declining is safe
+// because of the one-way rule in `routines/event-model.ts`: *"a shorter path makes matching COARSER,
+// never wrongly narrower"*.
+//
+// ═══ WHERE THIS FILE LIVES ═══
+//
+// Under `webhooks/` rather than `routines/`, even though two of its three registrations are routing-
+// plane ones, because the import direction in this tree is `webhooks/* → routines/*` and never the
+// reverse (`routines/scheme-name.ts`'s header pins it). Keeping the adapter in ONE module — the shape
+// a provider bundle has — matters more than filing each registration by its registry, and this is the
+// only side that can reach both.
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { registerWebhookVerifier, type WebhookSenderGuidance, type WebhookVerdict, type WebhookVerifier, type WebhookVerifyInput } from "./verifier.js";
+import { webhookMaxSkewSeconds } from "./gate.js";
+import {
+  FIELDS_MAX_KEYS,
+  registerEventNormalizer,
+  type EventNormalizer,
+  type NormalizedEvent,
+  type ScopeStep,
+  type TriggerDelivery,
+} from "../routines/event-model.js";
+
+/** The registry key — the SCHEME, not a hook's name. A (b) hook is `{ source: "my-ci", scheme: this }`. */
+export const OE_STANDARD_WEBHOOK_SCHEME = "oe-standard-webhook";
+
+/** Spec header names, lower-cased (`Headers.get` is case-insensitive; `TriggerDelivery.headers` is
+ *  lower-keyed, so these serve both). */
+export const SW_ID_HEADER = "webhook-id";
+export const SW_TIMESTAMP_HEADER = "webhook-timestamp";
+export const SW_SIGNATURE_HEADER = "webhook-signature";
+
+/** The spec's symmetric-signature version tag. A future scheme bumps THIS, never a header name. */
+export const SW_SIGNATURE_VERSION = "v1";
+
+/** The spec's secret prefix. Its presence — and only its presence — selects the spec's base64 key
+ *  encoding. See {@link standardWebhookKey}. */
+export const SW_SECRET_PREFIX = "whsec_";
+
+/** Unix seconds, digits only. NOT trimmed and NOT `Number()`-coerced before signing, for exactly the
+ *  reason a timestamped scheme always gives: the sender signed the header's VERBATIM bytes, so " 123 " is
+ *  MALFORMED rather than silently normalised into a basestring nobody signed. */
+const TIMESTAMP_RE = /^[0-9]{1,15}$/;
+
+/** A `webhook-id` we will accept. Bounded and punctuation-poor because the value is sender-supplied
+ *  and lands in TWO durable dedupe keys — `webhooks/replay-dedupe.ts`'s (hashed, so shape-safe) and
+ *  `routines/ingress.ts`'s `deliveryDedupeKey`, which joins `source` and the id with UNESCAPED
+ *  colons. Refusing `:` here is what keeps two hooks' deliveries from ever producing one key — the
+ *  cross-source suppression OPE-179 fixed and OPE-198's rejected `ext:<name>` design would have
+ *  re-opened. */
+const MESSAGE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_.\-+=]{0,127}$/;
+
+/**
+ * THE ONE DEFINITION of what this scheme signs: `<id>.<timestamp>.<rawBody>`. Exported so a signer
+ * (a test, the e2e forge, a documented shell snippet) and this verifier can be pinned equal by an
+ * assertion rather than drifting: one definition, never a second spelling of it.
+ */
+export function standardWebhookSignedContent(messageId: string, timestamp: string, rawBody: string): string {
+  return `${messageId}.${timestamp}.${rawBody}`;
+}
+
+/**
+ * The HMAC key bytes for a stored secret. ONE total rule, discriminated on a prefix that lives in
+ * OUR secret and never in the request:
+ *
+ *   • `whsec_<base64>` — the spec's own encoding, and what {@link mintStandardWebhookSecret} now
+ *                        produces. The remainder is base64-decoded.
+ *   • anything else    — the secret's own UTF-8 bytes: every hook minted BEFORE the prefix landed
+ *                        (a raw `base64url` random), and what `openssl dgst -hmac "$SECRET"` uses.
+ *                        This branch is why minting the prefix broke no live sender.
+ *
+ * 🔴 NOT A FALLBACK CHAIN. There is no "decode, and if the signature fails try the raw bytes":
+ * `webhooks/verifier.ts` refuses request-driven scheme selection as a downgrade primitive, and a
+ * secret-driven one would be the same bug with a longer fuse. A `whsec_` secret whose remainder is
+ * not valid base64 yields the bytes base64 decoding produced for it, and the signature simply does
+ * not match — a clean 401, never a coincidental match through the other branch.
+ */
+export function standardWebhookKey(secret: string): Buffer {
+  return secret.startsWith(SW_SECRET_PREFIX) ? Buffer.from(secret.slice(SW_SECRET_PREFIX.length), "base64") : Buffer.from(secret, "utf8");
+}
+
+/**
+ * 33 BYTES, AND THE ODD NUMBER IS DELIBERATE — 33 is a multiple of 3, so its base64 is exactly 44
+ * characters with NO `=` padding at all.
+ *
+ * Padding is where base64 decoders stop agreeing: Go's `StdEncoding` REQUIRES correct padding, the
+ * spec's Python library hand-appends `"=="` to tolerate its absence, and Node's is lenient about
+ * both. A padding-free multiple-of-4 string is the one form ALL of them decode identically with no
+ * special-casing, so the sender's library choice cannot change the key bytes. 32 bytes would encode
+ * to 44 characters plus one `=` and re-open that question for nothing.
+ *
+ * 264 bits, comfortably above the 256 the previous raw mint carried.
+ */
+const SW_SECRET_BYTES = 33;
+
+/**
+ * ⭐ MINT A SECRET IN THE SPEC'S OWN FORM: `whsec_<base64>`, whose base64-decoded remainder IS the
+ * HMAC key ({@link standardWebhookKey}). This is the format an off-the-shelf `standard-webhooks`
+ * client library expects, and the format that makes the value self-identifying if it is pasted
+ * somewhere it does not belong.
+ *
+ * STANDARD base64, not `base64url`, and it is not a preference: the reference libraries decode with
+ * a strict standard-alphabet decoder, so a `-` or `_` would either decode to different bytes or
+ * throw. The `+`/`/` that alphabet brings are harmless here — the secret is copied from a page into a
+ * config field, never into a URL.
+ *
+ * `bytes` is injectable ONLY so a test can pin the encoding against a known vector. Every production
+ * call takes the default and gets fresh randomness.
+ */
+export function mintStandardWebhookSecret(bytes: Buffer = randomBytes(SW_SECRET_BYTES)): string {
+  return SW_SECRET_PREFIX + bytes.toString("base64");
+}
+
+/** The `v1,<base64>` header value one key would produce for this message. Exported for signers. */
+export function standardWebhookSignature(secret: string, messageId: string, timestamp: string, rawBody: string): string {
+  const mac = createHmac("sha256", standardWebhookKey(secret)).update(standardWebhookSignedContent(messageId, timestamp, rawBody), "utf8").digest("base64");
+  return `${SW_SIGNATURE_VERSION},${mac}`;
+}
+
+/**
+ * The durable single-use nonce identity (`webhooks/replay-dedupe.ts`), derived from the SIGNED
+ * message id.
+ *
+ * ⭐ THIS IS THE UPGRADE OVER A SIGNATURE-DERIVED NONCE (`sha256(<source>:<ts>:<signature>)`, which
+ * is what a scheme with no message id is reduced to): it cannot tell two legitimately identical
+ * payloads sent in the same second apart, and drops the second as a replay it never was. A
+ * `webhook-id` is the sender's own idempotency key, covered by
+ * the signature, so it distinguishes messages rather than bytes. The timestamp is deliberately NOT
+ * folded in: re-sending one message id with a fresh timestamp is precisely the replay this is meant
+ * to suppress, and including it would let a re-signer walk around the mark.
+ *
+ * Hashed, like its sibling, so the store holds a fixed-width opaque token rather than a
+ * sender-authored string — and `webhookReplayStoreKey` namespaces it by hook id on top.
+ */
+export function standardWebhookReplayKey(messageId: string): string {
+  return createHash("sha256").update(`${OE_STANDARD_WEBHOOK_SCHEME}:${messageId}`).digest("hex");
+}
+
+/** Length-prechecked constant-time compare — the shape every verifier in this tree uses. */
+function constantTimeEquals(a: string, b: string): boolean {
+  const x = Buffer.from(a);
+  const y = Buffer.from(b);
+  return x.length === y.length && timingSafeEqual(x, y);
+}
+
+/**
+ * WHAT A SENDER MUST SEND — the human half of {@link standardWebhookVerifier}, rendered beside the
+ * secret on the reveal page. Built from the SAME exported constants and the SAME basestring builder
+ * the verifier reads, so the two cannot drift into disagreement; a test asserts each field against
+ * those symbols rather than against a copy of this prose.
+ *
+ * The key-derivation note states the TOTAL rule rather than assuming which form the reader is
+ * holding: a hook minted before the `whsec_` prefix landed still carries a raw secret, and telling
+ * such a reader to base64-decode it would break every signature they made.
+ */
+export function standardWebhookSenderGuidance(): WebhookSenderGuidance {
+  return {
+    headers: [
+      { name: SW_ID_HEADER, value: "<a unique id for this delivery, e.g. msg_01J8Z…>" },
+      { name: SW_TIMESTAMP_HEADER, value: "<unix seconds, digits only, e.g. 1614265330>" },
+      { name: SW_SIGNATURE_HEADER, value: `${SW_SIGNATURE_VERSION},<base64 signature>` },
+    ],
+    signedContent: standardWebhookSignedContent(`<${SW_ID_HEADER}>`, `<${SW_TIMESTAMP_HEADER}>`, "<the raw request body, byte for byte>"),
+    notes: [
+      `This is the Standard Webhooks scheme — any client library for it will do all of the below if you hand it the whole secret.`,
+      `Key bytes: if the secret starts with "${SW_SECRET_PREFIX}", drop that prefix and base64-decode the rest; otherwise use the secret's own text.`,
+      `Signature: HMAC-SHA256, base64-encoded, tagged "${SW_SIGNATURE_VERSION},". You may send several space-separated values while rotating a key — any one that matches is accepted.`,
+      `The timestamp must be within ${webhookMaxSkewSeconds()} seconds of our clock, and it is signed exactly as sent — do not reformat it between signing and sending.`,
+      `Give every delivery a NEW id: an id that has been accepted before is rejected as a replay. Ids are letters, digits and "_.-+=" only.`,
+      `Send the body verbatim. Re-serialising the JSON changes the bytes and the signature will not match.`,
+      // The two-line shell path, on the page rather than only in a manual, because this contract
+      // exists for senders that are a script. Verified against `standardWebhookSignature` by a frozen
+      // golden in `scripts/standard-webhook-test.ts` — a recipe nobody executes is a recipe that rots.
+      `In a shell: KEY=$(printf '%s' "\${SECRET#${SW_SECRET_PREFIX}}" | base64 -d | od -An -tx1 | tr -d ' \\n') ` +
+        `then SIG=$(printf '%s.%s.%s' "$ID" "$TS" "$BODY" | openssl dgst -sha256 -mac HMAC -macopt hexkey:"$KEY" -binary | base64)`,
+    ],
+  };
+}
+
+/**
+ * THE VERIFIER. `keyOrigin: "receiver-minted"` + `keyKind: "shared-secret"` ⇒ `acceptsMintedSecret`
+ * ⇒ this scheme enters `mintableSourceVocabulary` and is chat-creatable, which is the whole point
+ * of the stage.
+ */
+export const standardWebhookVerifier: WebhookVerifier = {
+  source: OE_STANDARD_WEBHOOK_SCHEME,
+  // No `provider` — this is core's own contract and must never be gated by
+  // a deployment's provider selection (which will never contain it).
+  keyKind: "shared-secret",
+  keyOrigin: "receiver-minted",
+  signedTimestamp: true,
+  /** The spec's own secret format — see {@link mintStandardWebhookSecret}. */
+  mintSecret: () => mintStandardWebhookSecret(),
+  senderGuidance: standardWebhookSenderGuidance,
+  verify({ rawBody, headers, keys, nowMs }: WebhookVerifyInput): WebhookVerdict {
+    const messageId = headers.get(SW_ID_HEADER);
+    const timestamp = headers.get(SW_TIMESTAMP_HEADER);
+    const signatureHeader = headers.get(SW_SIGNATURE_HEADER);
+    if (!signatureHeader) return { ok: false, failure: "missing-signature" };
+    // A missing id is `missing-signature`, not a new failure code: the id is COVERED BY the
+    // signature, so a delivery without one has not presented a complete signature. The failure set
+    // is closed on purpose (`webhooks/verifier.ts`) so a 401 can never carry vendor detail.
+    if (messageId === null) return { ok: false, failure: "missing-signature" };
+    if (!MESSAGE_ID_RE.test(messageId)) return { ok: false, failure: "malformed-signature" };
+    if (timestamp === null) return { ok: false, failure: "missing-timestamp" };
+    if (!TIMESTAMP_RE.test(timestamp)) return { ok: false, failure: "malformed-timestamp" };
+    // SKEW BEFORE ANY HMAC — a stale replay must not cost a digest per configured key. The spec
+    // leaves the tolerance unspecified; we reuse `webhookMaxSkewSeconds` (300s, overridable) so this
+    // deployment has ONE skew window rather than a second one to keep in sync.
+    if (Math.abs(nowMs / 1000 - Number(timestamp)) > webhookMaxSkewSeconds()) return { ok: false, failure: "stale-timestamp" };
+
+    // The header carries a SPACE-DELIMITED LIST so a sender mid-rotation can present several. We
+    // accept if ANY listed `v1` signature matches ANY configured key — a sender-side rotation and our
+    // own receiver-side one (`activeSecretRefs`, current-key-first) are independent and both real.
+    // Entries tagged with an unknown version are SKIPPED, not refused: that is what lets the spec add
+    // `v1a` (asymmetric) without every existing receiver breaking.
+    const presented = signatureHeader.split(" ").filter((s) => s.length > 0);
+    if (presented.length === 0) return { ok: false, failure: "malformed-signature" };
+    const v1 = presented.filter((s) => s.startsWith(`${SW_SIGNATURE_VERSION},`));
+    if (v1.length === 0) return { ok: false, failure: "unsupported-scheme" };
+    for (const [i, key] of keys.entries()) {
+      const expected = standardWebhookSignature(key, messageId, timestamp, rawBody);
+      for (const candidate of v1) {
+        // Early exit leaks at most how many keys/signatures were tried, which is not secret. Do not
+        // "fix" this into a constant-time sweep of the cross product.
+        if (constantTimeEquals(candidate, expected)) {
+          return { ok: true, keyIndex: i, replayKey: standardWebhookReplayKey(messageId) };
+        }
+      }
+    }
+    return { ok: false, failure: "signature-mismatch" };
+  },
+};
+
+// ═══ THE ENVELOPE WE DEFINE ════════════════════════════════════════════════════════════════════
+
+/**
+ * ⭐ THE (b) ENVELOPE. FOUR fields, each justified below, and every one of them OPTIONAL except the
+ * first. A sender that can write JSON and run `openssl` can produce it.
+ *
+ * WHY NOT CLOUDEVENTS — rejected, and not on grounds of taste. Two of its four REQUIRED attributes
+ * (`source`, `subject`) are SENDER-DECLARED IDENTITY fields, which is exactly the payload-scope
+ * hazard this adapter's scope rule exists to prevent. Adopting an envelope whose required fields we
+ * would have to actively ignore is worse than defining four fields we mean, and it would leave a
+ * standing invitation for a later reader to "wire up the fields that are already there". CloudEvents
+ * is an INTEROP surface, not an internal contract: if it is ever wanted it arrives as a category-(a)
+ * bundle that translates inbound, where ignoring an attribute is a documented translation rather
+ * than a silent one.
+ *
+ * UNKNOWN FIELDS ARE IGNORED, NEVER REJECTED. A sender that grows its payload must not start 400ing
+ * against a receiver it did not redeploy — and a strict-shape refusal at this layer would be a
+ * second, weaker copy of the size/shape bounds the gate already enforces.
+ */
+export interface StandardWebhookEnvelope {
+  /**
+   * REQUIRED. The event name, verbatim — `"build"`, `"deploy"`, `"alert"`. It is what a filter keys
+   * on first and what the human-readable summary is built from. Required because an envelope with no
+   * event name cannot be routed at all: `normalizedEventDefect` refuses an empty `event`, so
+   * accepting one here would only move the refusal somewhere less legible.
+   */
+  readonly event: string;
+  /** Optional sub-kind — `"failed"`, `"succeeded"`. Present because "the thing" and "what happened
+   *  to it" is the split EVERY vendor payload in this tree already has (`routines/events.ts`), so a
+   *  contract without it pushes every sender into stringly-concatenating one. */
+  readonly action?: string;
+  /**
+   * Optional flat bag of MATCHABLE scalars — `{ status: "failed", branch: "main" }`. This is the
+   * field that makes the envelope useful rather than ceremonial: it is where a sender puts whatever
+   * its own routines need to discriminate on.
+   *
+   * FLAT AND STRING-VALUED BY CONTRACT. Numbers/booleans are coerced (see {@link mergeScalarFields});
+   * objects and arrays are DROPPED rather than stringified, because a filter compares ids exactly and
+   * `"[object Object]"` matching `"[object Object]"` is a match that means nothing. Nesting is not
+   * supported and is not an oversight: the moment a filter can name a path, the match language
+   * becomes a payload-traversal language, which `routines/event-model.ts` refuses by design.
+   *
+   * Its KEYS are the SENDER's, which is why the normalizer declares `matchKeysOpen` — see there for
+   * what that costs.
+   */
+  readonly fields?: Readonly<Record<string, unknown>>;
+  /** Optional ISO-8601 instant, per the SENDER — distinct from our receive time on purpose, so "this
+   *  says the build failed, about a build that finished an hour ago" stays diagnosable. Carried
+   *  verbatim if it parses and dropped if it does not; a malformed clock is not a reason to drop a
+   *  delivery. */
+  readonly occurredAt?: string;
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+/**
+ * Merge the sender's `fields` into an already-seeded map, in insertion order, dropping non-scalars
+ * and stopping at {@link FIELDS_MAX_KEYS}.
+ *
+ * 🔴 THE BUDGET IS OVER THE **MERGED** MAP, NOT OVER THE SENDER'S SLICE OF IT — which is why this
+ * takes the seeded object rather than returning a fresh one. `normalizedEventDefect` treats more
+ * than `FIELDS_MAX_KEYS` as a DEFECT and drops the WHOLE delivery, so a cap counted only over the
+ * sender's own keys leaves room for the reserved ones to push the total over and turn a fat payload
+ * into a silent outage. Truncating is the right failure mode here: an over-eager sender should lose
+ * its 17th field, not its delivery. (Found by the test, not by reading — the first version capped
+ * the slice.)
+ *
+ * FIRST WINS, so the reserved keys seeded by the caller cannot be shadowed.
+ */
+function mergeScalarFields(into: Record<string, string>, raw: unknown): void {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return;
+  for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
+    if (Object.keys(into).length >= FIELDS_MAX_KEYS) break;
+    if (k in into) continue;
+    if (typeof v === "string") into[k] = v;
+    else if (typeof v === "number" && Number.isFinite(v)) into[k] = String(v);
+    else if (typeof v === "boolean") into[k] = String(v);
+    // objects, arrays, null and undefined are DROPPED — see StandardWebhookEnvelope.fields.
+  }
+}
+
+/**
+ * THE SCOPE PATH, built from the DELIVERY'S DECLARED NAME AND NOTHING ELSE. The body is not read
+ * here and there is no parameter through which it could be.
+ *
+ * Exported so a test can assert the property directly rather than inferring it from an end-to-end
+ * fixture: the honest test of "a payload cannot change the scope path" is that the function which
+ * builds the path cannot see a payload.
+ *
+ * ROUTING ONLY (OPE-209). This path is what a routine's scope selector matches; it is NOT an
+ * authorization input for this scheme — see the header. It is single-step and always non-empty,
+ * which is what keeps `checkEventReadGrant`'s `no-scope` refusal reserved for genuinely
+ * unattributable deliveries.
+ */
+export function standardWebhookScope(d: Pick<TriggerDelivery, "source">): ScopeStep[] {
+  return [{ kind: "container", id: d.source }];
+}
+
+/** One-line rendering. Built from the ENVELOPE (attacker-authored), so like every other summary in
+ *  this plane it only ever reaches the model through `access/untrusted.ts`'s fence — and under a
+ *  `trigger-only` posture `redactEvent` replaces it wholesale before that ever happens. */
+function summarize(name: string, event: string, action: string | undefined): string {
+  return `${name}: ${event}${action ? ` (${action})` : ""}`;
+}
+
+export const standardWebhookNormalizer: EventNormalizer = {
+  source: OE_STANDARD_WEBHOOK_SCHEME,
+  // The RESERVED keys — the two the contract itself always emits into `fields`, so a filter on them
+  // is guaranteed meaningful. NOT exhaustive, because `matchKeysOpen` is set: everything else in
+  // `fields` was named by the sender.
+  matchKeys: ["event", "action"],
+  matchKeysOpen: true,
+  // EMPTY, and it is not an omission. `scopeKeys` feeds the mandatory-narrowing rule, which this
+  // source is exempt from (`scopeHookConstant`) because its `source` already names one hook. There
+  // is no payload field that identifies a scope here — that is the entire design.
+  scopeKeys: [],
+  // CONTAINER ONLY. The `tenant` step left this scope path when OPE-209 removed the owner-domain
+  // hop — `standardWebhookScope` emits a container step and nothing above it. `scopeKinds` is
+  // documented as "which scope kinds this source can EVER prove", so listing `tenant` here is a
+  // promise no delivery can keep; the one live consumer happens to bypass it today, which is
+  // precisely why a stale entry would survive unnoticed until something new trusted it.
+  scopeKinds: ["container"],
+  scopeHookConstant: true,
+  // Honestly answered even though nothing reads it (`EventNormalizer.resolvesActor`): a (b) payload
+  // has no actor concept AT ALL — there is no identity system behind it, only a shared secret. A
+  // sender wanting an actor puts one in `fields`, where it is matchable and visibly untrusted.
+  resolvesActor: false,
+  // The spec's signed message id doubles as the delivery id, so `admitTrigger`'s durable dedupe
+  // engages (OPE-201). Same header, same value the verifier signed — never a second, weaker id.
+  deliveryIdHeader: SW_ID_HEADER,
+  normalize(d: TriggerDelivery): NormalizedEvent | null {
+    let payload: unknown;
+    try {
+      payload = JSON.parse(d.body);
+    } catch {
+      return null; // unparseable ⇒ unroutable, and the ingress records its own rejection reason
+    }
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+    const env = payload as Record<string, unknown>;
+    const event = str(env["event"]);
+    // No event name ⇒ NOT MODELLED, which 200s-and-ignores. Deliberately the same answer a GitHub
+    // `ping` gets: a sender probing the endpoint should get a clean ack, not a 4xx it will retry.
+    if (!event) return null;
+    const action = str(env["action"]);
+    const occurredAt = str(env["occurredAt"]);
+    // SEEDED WITH THE RESERVED KEYS, and the merge below is FIRST-WINS — so a sender writing
+    // `fields.event` cannot overwrite the envelope's own. Otherwise a filter on `event` would be
+    // checking a string the sender got to choose twice.
+    const fields: Record<string, string> = { event, ...(action ? { action } : {}) };
+    mergeScalarFields(fields, env["fields"]);
+    return {
+      // Overwritten by `normalizeDelivery`'s stamp with the delivery's declared name; emitted here
+      // so this function is honest standalone and so `normalizedEventDefect` (which runs BEFORE the
+      // stamp) sees a non-empty source.
+      source: d.source,
+      event,
+      ...(action ? { action } : {}),
+      scope: standardWebhookScope(d),
+      fields,
+      ...(d.deliveryId ? { deliveryId: d.deliveryId } : {}),
+      ...(occurredAt && !Number.isNaN(Date.parse(occurredAt)) ? { occurredAt } : {}),
+      summary: summarize(d.source, event, action),
+      // NO `pointer`. There is nothing to re-fetch: a (b) sender is not a system OE holds a
+      // credential for, which is the same fact that makes the read grant below need its own
+      // justification. An absent pointer is what keeps `routines/ingress.ts` out of its hydration arm
+      // entirely rather than having it try and fail.
+    };
+  },
+};
+
+/**
+ * ⭐⭐ WHY THIS CONTRACT CARRIES NO READ GRANT OF ITS OWN, AND WHAT MUST NOT BE REBUILT HERE.
+ * Authorization is the hook's declared `readableBy` (`access/read-grant.ts`), evaluated in
+ * `routines/event-authz.ts`. Four claims, each pinned as prose-that-must-exist by
+ * `scripts/standard-webhook-test.ts` §5 — reword them there as well as here, never delete them.
+ *
+ * 🔴 THE GENERAL JUSTIFICATION FOR EVENT READ GRANTS HAS NO REFERENT FOR A (b) SENDER, so this
+ * contract cannot inherit the vendor-ingress reasoning and `readableBy` is REQUIRED rather than
+ * optional. `routines/event-authz.ts` states the warrant verbatim — *"Event-triggering is a LATENCY
+ * OPTIMISATION ON AN ALREADY-GRANTED POLL."* — on three assumptions: there is a FETCH the trigger is
+ * less informative than; that fetch is authorized by the same grant; an ungated POLL of it already
+ * ships. All three require OE to hold a credential for the source system. A (b) sender is not a
+ * system: no fetch, no poll, nothing the grant could already be granting. The argument does not
+ * weaken here — it has nothing to attach to.
+ *
+ * 🔴 THE OWNING-DOMAIN GRANT THAT USED TO LIVE HERE WAS NOT WRONG ABOUT AUTHORITY — it was wrong
+ * about CARDINALITY. One domain frozen onto a row cannot express the ordinary case (one Notion hook
+ * several domains legitimately read), and in a domainless channel it derived to nothing and refused
+ * every routine forever with no chat-visible signal (OPE-206). A grant with no vocabulary for "these
+ * three" has only "the one" and "everything". Reasoning: design doc §3.1.
+ *
+ * 🔴 THE FRAGILE POINT, RECORDED NOWHERE ELSE. A `domain` entry's authority class is
+ * `memory/config/domains.ts`'s, and `loadDomains` is explicitly a swappable seam — *"the seam a DB/dashboard
+ * would swap behind. Static config for now."* If a dashboard ever lets a non-deployer edit domain
+ * membership, every `domain` grant weakens to whatever authorizes that editor, with NO test going red
+ * because the shape of the check would not change.
+ *
+ * 🔴 AN INGRESS-TIME PERMISSION PROBE (fetch the entity with the domain's credential before allowing
+ * the fire) is dissolved, not deferred. The integrity boundary enforces itself — a triggered fire
+ * acts with the domain's own outbound credential, so a routine that cannot read the entity can do
+ * nothing with it, checked for free at the point of action. A probe would check permission twice,
+ * once expensively and speculatively. What remains is a thin disclosure leak (a domain learns the
+ * entity EXISTS), which `readableBy` is the right place to bound. Reasoning: design doc §2.4, §3.3.
+ */
+
+// Module-load registration — the `routines/github-normalizer.ts` posture:
+// the module that OWNS a contract is the module that arms it, so importing this file is the whole
+// wiring. `channels/webhooks.ts` (the live ingress) imports it for exactly that reason.
+//
+// BOTH, TOGETHER, ON PURPOSE. A verifier without a normalizer is a source that authenticates and can
+// never route; a normalizer without a verifier is a source nothing can authenticate. Keeping the two
+// registrations adjacent is what stops a half-armed adapter from shipping, and
+// `webhooks/source-vocabulary.ts` enforces the pairing at the vocabulary on top of that.
+//
+// TWO REGISTRATIONS AND NO THIRD: the read grant is the hook's own `readableBy` and needs no
+// per-source registration at all (OPE-209 — see the block above for why, and for what not to
+// rebuild).
+registerWebhookVerifier(standardWebhookVerifier);
+registerEventNormalizer(standardWebhookNormalizer);