@open-everywhere/core 0.1.0

package/dist/agent/webhooks/oe-standard-webhook.js

@@ -0,0 +1,498 @@
+// ⭐⭐ 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 } from "./verifier.js";
+import { webhookMaxSkewSeconds } from "./gate.js";
+import { FIELDS_MAX_KEYS, registerEventNormalizer, } 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, timestamp, rawBody) {
+    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) {
+    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 = randomBytes(SW_SECRET_BYTES)) {
+    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, messageId, timestamp, rawBody) {
+    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) {
+    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, b) {
+    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() {
+    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 = {
+    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 }) {
+        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" };
+    },
+};
+function str(v) {
+    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, raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return;
+    for (const [k, v] of Object.entries(raw)) {
+        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) {
+    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, event, action) {
+    return `${name}: ${event}${action ? ` (${action})` : ""}`;
+}
+export const standardWebhookNormalizer = {
+    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) {
+        let payload;
+        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;
+        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 = { 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);
+//# sourceMappingURL=oe-standard-webhook.js.map

package/dist/agent/webhooks/oe-standard-webhook.js.map

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

package/dist/agent/webhooks/reject-audit.d.ts

@@ -0,0 +1,40 @@
+import { type AuditInput } from "../audit/audit.js";
+import type { WebhookRejection } from "./gate.js";
+/** At most ~one rejection row per identity per window. */
+export declare const REJECTION_WINDOW_MS = 60000;
+/** How much of a caller-supplied hook id is preserved in `detail` (the row must stay bounded —
+ *  the whole point is that this input is hostile and unbounded). */
+export declare const REJECTION_ID_MAX_CHARS = 100;
+/** The minimum this module reads off a hook. Widened from `WebhookHook` in OPE-150 so a CHAT-CREATED
+ *  hook gets the SAME per-hook throttle identity a config hook does — its id is host-minted and
+ *  bounded, so it satisfies the "operator-owned, not caller-chosen" property the key rests on
+ *  exactly as a config id does. Collapsing runtime hooks onto the `unknown` bucket instead would
+ *  have let internet scan noise SUPPRESS a real "this hook's secret drifted" 401, which is the
+ *  precise signal this throttle was built to keep legible. `target` is optional (an emit-only
+ *  hook has none — it is emit-only), so the row falls back to the synthetic surface. */
+export interface AuditableHook {
+    readonly id: string;
+    readonly target?: string;
+}
+/** The throttle identity: per-hook for a KNOWN hook (bounded, operator- or host-owned), a single
+ *  constant for anything unknown (unbounded, caller-owned). Status is included either way — there
+ *  are only a handful of them, and a 401 on a real hook is a very different story from a 404 scan. */
+export declare function rejectionThrottleKey(hook: AuditableHook | undefined, status: number): string;
+/** Test seam — drop all in-process suppression counters. */
+export declare function resetRejectionThrottle(): void;
+/** Injectable edges; live defaults are the operational store + appendAudit. */
+export interface RejectionAuditDeps {
+    readonly markSeen?: (org: string, key: string, atIso: string, ttlMs: number) => Promise<boolean>;
+    readonly audit?: (entry: AuditInput) => Promise<void>;
+    readonly now?: () => Date;
+    readonly org?: string;
+}
+/**
+ * Best-effort, THROTTLED audit for a rejected delivery. `hook` may be undefined (unknown id) — in
+ * that case there is no configured target to attribute the row to, so it is logged under a
+ * synthetic workspace/surface (still findable by the length-capped `hookId` in `detail`).
+ *
+ * Returns true when a row was emitted, false when it was suppressed (counted onto the next one).
+ */
+export declare function auditWebhookRejection(id: string, hook: AuditableHook | undefined, rejection: WebhookRejection, deps?: RejectionAuditDeps): Promise<boolean>;
+//# sourceMappingURL=reject-audit.d.ts.map

package/dist/agent/webhooks/reject-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reject-audit.d.ts","sourceRoot":"","sources":["../../../agent/webhooks/reject-audit.ts"],"names":[],"mappings":"AA4BA,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEjE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAGlD,0DAA0D;AAC1D,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C;oEACoE;AACpE,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;;;wFAMwF;AACxF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;sGAEsG;AACtG,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE5F;AAQD,4DAA4D;AAC5D,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAED,+EAA+E;AAC/E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjG,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,SAAS,EAAE,gBAAgB,EAC3B,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,OAAO,CAAC,CA2ClB"}