@edgehero/pi-dispatch-receiver 0.1.0

package/src/verify-azure.mjs

@@ -0,0 +1,109 @@
+/**
+ * The Azure DevOps trust boundary.
+ *
+ * WHAT AZURE CANNOT DO, stated first because everything here follows from it: Service Hooks offer no HMAC.
+ * The only authentication a subscription can carry is HTTP Basic credentials or a static custom header. A
+ * bare credential proves the sender knew a secret and COVERS NO BYTES -- it says nothing about whether the
+ * body arrived as it was sent.
+ *
+ * So `CONST-HMAC-OVER-RAW-BODY` is satisfied here in one half and not the other, and this is not a new
+ * class of exception: it is exactly GitLab's `token` mode, which that entry already admits BY NAME. What
+ * does NOT vary, and is preserved exactly, is the ordering the whole downstream depends on -- raw bytes,
+ * then verify, then parse -- and the refusal to let the request choose which mechanism it faces.
+ *
+ * TWO CONSEQUENCES AN OPERATOR HAS TO KNOW ABOUT, both documented rather than papered over:
+ *
+ *   - The DELIVERY ID IS IN THE BODY. Azure sends no delivery-id header at all, so the dedup key
+ *     (`REQ-DEDUP-BY-DELIVERY-GUID`) is read from the verified payload. `verify-gitlab.mjs` explicitly
+ *     REFUSES to do this -- it 400s rather than synthesise a key from payload content -- and that refusal
+ *     is right for a forge that HAS a header and wrong for one that has none. The distinction is the
+ *     difference between an exception and an erosion, so it is written down rather than inferred. Note the
+ *     ordering is unaffected: the id is read inside `onVerified`, after the credential check.
+ *   - There is NO REPLAY WINDOW. GitLab pairs its dedup with a signed 5-minute timestamp precisely because
+ *     dedup is retention-bounded. Azure signs no timestamp and no body, so a captured delivery replays as
+ *     new paid work once the job key ages out, and there is no second line of defence. `OQ-015` records it.
+ *
+ * HTTPS is the operator's obligation and the docs say so: over plain HTTP the credential is on the wire in
+ * base64, which is not encryption.
+ */
+
+import { timingSafeEqual } from "node:crypto";
+import { isJsonContentType, readRawBody, respond } from "./http-body.mjs";
+
+const MAX_BODY_BYTES = 2 * 1024 * 1024;
+
+/**
+ * Constant-time string compare. Length is leaked (it always is, by the early return), but the CONTENT is
+ * not: a byte-by-byte `===` on a secret is a timing oracle, and this is the only thing standing between a
+ * stranger and a paid job on this forge.
+ */
+export function secretEquals(a, b) {
+	const left = Buffer.from(String(a ?? ""), "utf8");
+	const right = Buffer.from(String(b ?? ""), "utf8");
+	if (left.length !== right.length) return false;
+	return timingSafeEqual(left, right);
+}
+
+/**
+ * Whether the request carries the configured credential.
+ *
+ * `mode` is chosen by the operator when they create the subscription, never negotiated from the request:
+ *   - `basic`  -- `Authorization: Basic base64(user:pass)`, compared against the whole configured string.
+ *   - `header` -- a custom header name and value, for deployments fronted by something that consumes the
+ *                 Authorization header before pi-dispatch sees it.
+ *
+ * A delivery presenting the wrong mechanism's credential is refused even when that credential is correct:
+ * a sender able to choose which gate it faces chooses the weakest available one.
+ */
+export function credentialOk({ mode, secret, headerName }, headers) {
+	if (mode === "basic") {
+		const raw = headers?.authorization;
+		if (typeof raw !== "string" || !raw.startsWith("Basic ")) return false;
+		return secretEquals(raw.slice("Basic ".length).trim(), secret);
+	}
+	if (mode === "header") {
+		const raw = headers?.[String(headerName ?? "").toLowerCase()];
+		return typeof raw === "string" && secretEquals(raw, secret);
+	}
+	return false;
+}
+
+/**
+ * Wrap `onVerified({ rawBody }, res)` so it only ever runs for an authenticated delivery.
+ *
+ * The preamble mirrors the other two verifiers exactly -- method, content type, declared length, bounded
+ * read, then the credential check -- because that ordering is the part every downstream gate depends on
+ * and it must not vary per forge.
+ */
+export function makeAzureVerifiedHandler({ mode, secret, headerName = null }, onVerified) {
+	return async function handler(req, res) {
+		try {
+			if (req.method !== "POST") return respond(res, 405, { error: "method-not-allowed" });
+			if (!isJsonContentType(req.headers["content-type"])) return respond(res, 415, { error: "unsupported-media-type" });
+
+			const declared = Number(req.headers["content-length"] ?? NaN);
+			if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) return respond(res, 413, { error: "payload-too-large" });
+
+			let buf;
+			try {
+				buf = await readRawBody(req, MAX_BODY_BYTES);
+			} catch (err) {
+				if (err?.code === "E_PAYLOAD_TOO_LARGE") return respond(res, 413, { error: "payload-too-large" });
+				throw err;
+			}
+			const rawBody = buf.toString("utf8");
+
+			// The credential is checked against the RAW bytes having already been read and NOT yet parsed --
+			// the same ordering the HMAC forges use. It buys less here (the credential covers no bytes), but
+			// the property it does buy is real: no field of an unauthenticated body is ever read.
+			if (!credentialOk({ mode, secret, headerName }, req.headers)) {
+				return respond(res, 401, { error: "unauthorized" });
+			}
+
+			return await onVerified({ rawBody }, res);
+		} catch (err) {
+			process.stderr.write(`${JSON.stringify({ event: "azure_verify_handler_error", reason: err?.message })}\n`);
+			if (!res.headersSent) respond(res, 500, { error: "internal" });
+		}
+	};
+}

package/src/verify-gitlab.mjs

@@ -0,0 +1,193 @@
+/**
+ * The GitLab trust boundary (issue #42), the counterpart of verify.mjs. Nothing downstream -- not the
+ * access-level gate, not the label predicate, not the enqueue -- means anything unless this ran first and
+ * said yes: every one of them reads fields from a body somebody has to have authenticated
+ * (CONST-HMAC-OVER-RAW-BODY).
+ *
+ * GitLab offers TWO mechanisms, and which one a deployment gets depends on its version:
+ *
+ *   - `signature` -- a real HMAC-SHA256, `webhook-signature: v1,<base64>`, over the Standard Webhooks
+ *     message `{webhook-id}.{webhook-timestamp}.{raw body}`. Available from GitLab 19.0 (GA 19.1).
+ *   - `token` -- `X-Gitlab-Token` compared against a shared secret. Available on every version, and
+ *     STRICTLY WEAKER: it proves the sender knew a secret, and says nothing about whether the body
+ *     arrived as it was sent. It is offered because most self-hosted instances cannot do better yet, not
+ *     because it is adequate.
+ *
+ * The mode is DECLARED in config and verified exactly, never negotiated from what the request happens to
+ * carry. That is the whole reason it is a config field: a handler that accepted whichever header showed up
+ * would let the sender choose which gate it faced, and an attacker would choose the weaker one every time.
+ * A delivery arriving without the declared mode's header is refused, even when the other one is present
+ * and correct.
+ *
+ * Raw-body-then-verify-then-parse holds exactly as in verify.mjs: `readRawBody` returns bytes, the HMAC is
+ * computed over those bytes, and `onVerified` gets the string. Nothing calls JSON.parse before the 401.
+ */
+
+import { createHmac, timingSafeEqual, createHash } from "node:crypto";
+import { isJsonContentType, readRawBody, respond } from "./http-body.mjs";
+
+/**
+ * Standard Webhooks' replay window. The dedup layer already refuses a repeated delivery id, but that
+ * guarantee is RETENTION-bounded (REQ-DEDUP-BY-DELIVERY-GUID states this explicitly): once the job key
+ * ages out, a captured delivery replays as new work and is billed. The timestamp is the unbounded half of
+ * that defence, so it is checked here rather than left to the queue.
+ *
+ * Five minutes is the spec's tolerance and is generous next to any plausible clock skew between a forge
+ * and its own webhook target.
+ */
+const TIMESTAMP_TOLERANCE_MS = 5 * 60 * 1000;
+
+/** The signing token's documented wrapper: `whsec_` then the base64 of the actual key. */
+const SIGNING_TOKEN_PREFIX = "whsec_";
+
+/**
+ * Build the verified GitLab handler. `mode` is `"signature"` or `"token"`; `secret` is the signing token
+ * (signature mode) or the shared secret token (token mode).
+ *
+ * `onVerified` receives `({ rawBody, headers, event, delivery }, res)` only after verification -- the same
+ * shape verify.mjs passes, so the receiver's two arms differ in how a delivery is trusted and not in what
+ * a trusted delivery looks like.
+ */
+export function makeGitLabVerifiedHandler({ mode, secret, bodyLimit = 2 * 1024 * 1024, now = () => Date.now() }, onVerified) {
+	if (mode !== "signature" && mode !== "token") {
+		throw new Error(`gitlab webhook mode must be "signature" or "token" (got ${JSON.stringify(mode)})`);
+	}
+	if (typeof secret !== "string" || secret === "") {
+		throw new Error("gitlab webhook verification requires a non-empty secret");
+	}
+	const key = mode === "signature" ? decodeSigningToken(secret) : null;
+
+	return async function gitlabVerifiedHandler(req, res) {
+		let delivery;
+		try {
+			if (req.method !== "POST") {
+				return respond(res, 405, { error: "method not allowed" });
+			}
+			if (!isJsonContentType(req.headers["content-type"])) {
+				return respond(res, 415, { error: "unsupported media type" });
+			}
+
+			const event = req.headers["x-gitlab-event"];
+			if (!event) {
+				return respond(res, 400, { error: "missing gitlab event header" });
+			}
+
+			// The delivery id is stable across GitLab's own retries, which is exactly the property dedup
+			// needs (REQ-DEDUP-BY-DELIVERY-GUID). `webhook-id` is the Standard Webhooks name (19.0+);
+			// `Idempotency-Key` is the same value under its original name (17.4+).
+			//
+			// An instance too old for either is REFUSED rather than served on a synthesised key. A key
+			// derived from the payload -- object id plus action, say -- is not stable across a retry that
+			// changes nothing an operator can see, so it would dedup some redeliveries and bill for the
+			// rest. Naming the minimum version is a message; a weaker key would be a silent second charge.
+			delivery = req.headers["webhook-id"] ?? req.headers["idempotency-key"];
+			if (!delivery) {
+				return respond(res, 400, {
+					error: "missing delivery id",
+					detail: "no webhook-id or Idempotency-Key header; pi-dispatch needs GitLab 17.4 or later to dedup redeliveries",
+				});
+			}
+
+			const declaredLength = Number(req.headers["content-length"]);
+			if (Number.isFinite(declaredLength) && declaredLength > bodyLimit) {
+				req.destroy();
+				return respond(res, 413, { error: "payload too large" });
+			}
+
+			let buf;
+			try {
+				buf = await readRawBody(req, bodyLimit);
+			} catch (err) {
+				if (err && err.code === "E_PAYLOAD_TOO_LARGE") {
+					return respond(res, 413, { error: "payload too large" });
+				}
+				throw err;
+			}
+			const raw = buf.toString("utf8");
+
+			const verdict =
+				mode === "signature"
+					? verifySignature({ key, headers: req.headers, raw, nowMs: now() })
+					: verifyToken(secret, req.headers["x-gitlab-token"]);
+			if (!verdict.ok) {
+				return respond(res, verdict.status ?? 401, { error: verdict.error });
+			}
+
+			await onVerified({ rawBody: raw, headers: req.headers, event, delivery }, res);
+		} catch {
+			// Stable id only: never the secret, the body, or a stack that may carry PII.
+			process.stderr.write(`${JSON.stringify({ event: "gitlab_verify_handler_error", delivery: delivery ?? null })}\n`);
+			if (!res.headersSent) {
+				respond(res, 500, { error: "internal error" });
+			}
+		}
+	};
+}
+
+/**
+ * `whsec_<base64>` -> the raw key bytes. Refused at CONSTRUCTION, not per request: a signing token this
+ * cannot decode can never verify anything, so the process must not come up believing it has a gate.
+ */
+export function decodeSigningToken(token) {
+	const body = token.startsWith(SIGNING_TOKEN_PREFIX) ? token.slice(SIGNING_TOKEN_PREFIX.length) : token;
+	const key = Buffer.from(body, "base64");
+	if (key.length === 0) {
+		throw new Error("gitlab signing token did not base64-decode to any key bytes");
+	}
+	return key;
+}
+
+/**
+ * Verify `webhook-signature` over the Standard Webhooks message. Returns `{ ok: true }` or
+ * `{ ok: false, error, status }`.
+ *
+ * The signed message is `{webhook-id}.{webhook-timestamp}.{body}` -- the id and timestamp are INSIDE the
+ * MAC, which is what makes the timestamp trustworthy enough to enforce a replay window against. Checking
+ * a timestamp that was not covered by the signature would be theatre.
+ *
+ * The header may carry several space-separated signatures (key rotation). Every `v1,` entry is tried, and
+ * each compare is timing-safe; an unknown version prefix is skipped rather than treated as a match.
+ */
+export function verifySignature({ key, headers, raw, nowMs }) {
+	const header = headers["webhook-signature"];
+	const id = headers["webhook-id"];
+	const timestamp = headers["webhook-timestamp"];
+	if (!header || !id || !timestamp) {
+		return { ok: false, error: "missing signature" };
+	}
+
+	const sentMs = Number(timestamp) * 1000;
+	if (!Number.isFinite(sentMs) || Math.abs(nowMs - sentMs) > TIMESTAMP_TOLERANCE_MS) {
+		// Outside the window the signature is still valid -- which is the point. A captured delivery stays
+		// cryptographically good forever, so age is the only thing that can refuse a replay once the
+		// queue's dedup key has aged out.
+		return { ok: false, error: "stale or invalid timestamp" };
+	}
+
+	const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${raw}`, "utf8").digest();
+	for (const candidate of String(header).split(" ")) {
+		const [version, value] = candidate.split(",");
+		if (version !== "v1" || !value) continue;
+		const got = Buffer.from(value, "base64");
+		if (got.length === expected.length && timingSafeEqual(got, expected)) {
+			return { ok: true };
+		}
+	}
+	return { ok: false, error: "invalid signature" };
+}
+
+/**
+ * Compare `X-Gitlab-Token` against the configured secret in constant time.
+ *
+ * Both sides are hashed first so the comparands are always 32 bytes: `timingSafeEqual` throws on a length
+ * mismatch, and the obvious guard -- return early when the lengths differ -- turns the secret's LENGTH
+ * into a timing oracle. Hashing removes length from the comparison entirely.
+ */
+export function verifyToken(secret, presented) {
+	if (typeof presented !== "string" || presented === "") {
+		return { ok: false, error: "missing token" };
+	}
+	const a = createHash("sha256").update(presented, "utf8").digest();
+	const b = createHash("sha256").update(secret, "utf8").digest();
+	return timingSafeEqual(a, b) ? { ok: true } : { ok: false, error: "invalid token" };
+}

package/src/verify.mjs

@@ -0,0 +1,98 @@
+/**
+ * Webhook signature verification -- the trust boundary every downstream gate depends on.
+ *
+ * CONST-HMAC-OVER-RAW-BODY: the raw request bytes are verified against `X-Hub-Signature-256`
+ * with `crypto.timingSafeEqual` BEFORE any parse. `@octokit/webhooks` owns that comparison
+ * internally, so this module delegates to `Webhooks#verify` and never hand-rolls HMAC nor
+ * compares signatures with `===`. A signature computed over different bytes than were sent
+ * fails verification, and such a request is rejected 401 before a single field is read.
+ *
+ * node:http, not express: `express.json()` consumes the stream and re-serializes the body, so
+ * the bytes handed to an HMAC check are no longer the bytes GitHub signed -- verification then
+ * either always fails or gets quietly stripped to make things work. A hand-rolled node:http
+ * handler reads the raw stream once and verifies those exact bytes. This also owns its own
+ * status codes, which `createNodeMiddleware` cannot: its 400 is hardcoded and its options
+ * expose only `{ timeout, path, log }`, so a 400->401 remap is impossible through it.
+ *
+ * Status map: 405 non-POST · 415 non-JSON content type · 401 missing or invalid signature ·
+ * 400 missing GitHub event/delivery headers · 413 body over limit · 500 unexpected throw.
+ */
+
+import { Webhooks } from "@octokit/webhooks";
+import { isJsonContentType, readRawBody, respond } from "./http-body.mjs";
+
+/**
+ * Thin wrapper delegating to `webhooks.verify(rawBody, signature)`. `rawBody` is the raw UTF-8
+ * request body as a string and `signature` is the `X-Hub-Signature-256` header value. Returns a
+ * Promise<boolean>; the timing-safe HMAC comparison lives inside `@octokit/webhooks`.
+ */
+export async function verifySignature(webhooks, rawBody, signature) {
+	return webhooks.verify(rawBody, signature);
+}
+
+/**
+ * Build a `node:http` request handler that verifies GitHub's HMAC over the raw body and hands a
+ * verified request off to `onVerified`. The `Webhooks` instance is constructed once, at factory
+ * time, so the secret is captured in the closure and never re-read per request.
+ *
+ * `onVerified` receives `({ rawBody, headers, event, delivery }, res)` only after a good signature.
+ * It owns the parse, the trigger filter, the enqueue, and the final response (D4's contract); if it
+ * writes no response, that is D4's concern -- this handler's job ends at a successful verify.
+ */
+export function makeVerifiedHandler({ secret, bodyLimit = 2 * 1024 * 1024 }, onVerified) {
+	const webhooks = new Webhooks({ secret });
+
+	return async function verifiedHandler(req, res) {
+		let delivery;
+		try {
+			if (req.method !== "POST") {
+				return respond(res, 405, { error: "method not allowed" });
+			}
+
+			if (!isJsonContentType(req.headers["content-type"])) {
+				return respond(res, 415, { error: "unsupported media type" });
+			}
+
+			const signature = req.headers["x-hub-signature-256"];
+			if (!signature) {
+				return respond(res, 401, { error: "missing signature" });
+			}
+
+			const event = req.headers["x-github-event"];
+			delivery = req.headers["x-github-delivery"];
+			if (!event || !delivery) {
+				return respond(res, 400, { error: "missing github event headers" });
+			}
+
+			const declaredLength = Number(req.headers["content-length"]);
+			if (Number.isFinite(declaredLength) && declaredLength > bodyLimit) {
+				req.destroy();
+				return respond(res, 413, { error: "payload too large" });
+			}
+
+			let buf;
+			try {
+				buf = await readRawBody(req, bodyLimit);
+			} catch (err) {
+				if (err && err.code === "E_PAYLOAD_TOO_LARGE") {
+					return respond(res, 413, { error: "payload too large" });
+				}
+				throw err;
+			}
+
+			const raw = buf.toString("utf8");
+			const ok = await verifySignature(webhooks, raw, signature);
+			if (!ok) {
+				return respond(res, 401, { error: "invalid signature" });
+			}
+
+			await onVerified({ rawBody: raw, headers: req.headers, event, delivery }, res);
+		} catch {
+			// Stable id only: never the secret, the body, or a stack that may carry PII.
+			process.stderr.write(`${JSON.stringify({ event: "verify_handler_error", delivery: delivery ?? null })}\n`);
+			if (!res.headersSent) {
+				respond(res, 500, { error: "internal error" });
+			}
+		}
+	};
+}