@open-everywhere/provider-github 0.0.0-stage → 0.1.1

package/agent/channels/github-webhook-verifier.ts

@@ -0,0 +1,56 @@
+// GitHub's webhook signature scheme, as a registry entry (OPE-164) — what lets a GENERIC hook
+// (`POST /webhooks/<id>`) declare `source: "github"` and be verified exactly the way GitHub signs,
+// instead of GitHub being expected to adopt our scheme (which it never will).
+//
+// ZERO NEW CRYPTO. The digest itself is core's `verifyGithubSignature` (routines/events.ts, through
+// the adapter-api barrel) — the same function the native github webhook route has always used, so
+// there is one implementation of GitHub's scheme in the tree, not two that can drift.
+//
+// THE SCHEME (https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries):
+//   X-Hub-Signature-256: sha256=<hex>   HMAC-SHA256 of the RAW body under the webhook secret.
+// `X-Hub-Signature` (SHA-1) is legacy and deliberately NOT accepted — accepting it would be a
+// downgrade a sender could choose.
+//
+// 🔴 `signedTimestamp: false` — GitHub signs NOTHING but the body. A captured delivery replays
+// forever. That is GitHub's scheme, not a gap we can close in the verifier; it is declared here
+// so it lands on the reviewed UNDEFENDED_REPLAY_SOURCES allowlist (webhook-verifier-test.ts)
+// rather than being an unwritten fact. It is also exactly why resolution is by DECLARED source:
+// with a weaker verifier registered alongside a timestamped one, letting the REQUEST choose the
+// scheme would be a live downgrade primitive.
+//
+// NOTE this entry changes NO existing route. The native github webhook path keeps its own inline
+// gate; registering here only makes the scheme available to the generic ingress.
+
+import { verifyGithubSignature, type WebhookVerifier } from "@open-everywhere/core/agent/adapter-api.js";
+
+/** The registry key — what a generic hook declares as its `source` to be verified as GitHub. */
+export const GITHUB_WEBHOOK_SOURCE = "github";
+
+const GITHUB_SIGNATURE_HEADER = "x-hub-signature-256";
+
+export const githubWebhookVerifier: WebhookVerifier = {
+  source: GITHUB_WEBHOOK_SOURCE,
+  // Provider-owned ⇒ routed through admitProviderRegistration: de-select the github bundle and
+  // this row never lands, so a `source: "github"` hook 401s instead of silently using another
+  // scheme.
+  provider: "github",
+  keyKind: "shared-secret",
+  // `keyOrigin: "receiver-minted"` (OPE-186) — GitHub's webhook secret is a value the person
+  // CREATING the webhook types into GitHub's own form, not one GitHub generates and hands back:
+  // *"Setting a webhook secret allows you to ensure that POST requests sent to the payload URL are
+  // from GitHub … you can create a random string"* (the same docs page linked above). That is what
+  // makes `source: "github"` legal for a CHAT-MINTED hook, whose key is an OE-minted random secret
+  // the approver pastes into that form. Sourced to GitHub's docs, not to anything in this tree.
+  keyOrigin: "receiver-minted",
+  signedTimestamp: false,
+  verify({ rawBody, headers, keys }) {
+    const signature = headers.get(GITHUB_SIGNATURE_HEADER);
+    if (!signature) return { ok: false, failure: "missing-signature" };
+    for (const [i, key] of keys.entries()) {
+      // Ordered, current-first: a match at i>0 is a rotation overlap and the gate audits it.
+      // GitHub documents no overlap window of its own, so `keys[]` is how an operator gets one.
+      if (verifyGithubSignature(key, rawBody, signature)) return { ok: true, keyIndex: i };
+    }
+    return { ok: false, failure: "signature-mismatch" };
+  },
+};