Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

feat(webhooks): add linear verification scheme (#947)

kai-jmib19d2e024fc0
diff --git a/plugins/web-ui/src/webhooks.ts b/plugins/web-ui/src/webhooks.ts
index 8953f36d8..aecafe30b 100644
--- a/plugins/web-ui/src/webhooks.ts
+++ b/plugins/web-ui/src/webhooks.ts
@@ -24,7 +24,7 @@ export interface WebhookView {
url: string;
}
-type WebhookScheme = "hmac-sha256" | "github" | "slack" | "stripe";
+type WebhookScheme = "hmac-sha256" | "github" | "slack" | "stripe" | "linear";
const WEBHOOK_SCHEMES: Array<{ value: WebhookScheme; label: string; guidance: string }> = [
{
@@ -47,6 +47,11 @@ const WEBHOOK_SCHEMES: Array<{ value: WebhookScheme; label: string; guidance: st
label: "Stripe",
guidance: "Use the endpoint signing secret shown by Stripe for this destination.",
},
+ {
+ value: "linear",
+ label: "Linear",
+ guidance: "Use the webhook signing secret shown by Linear. Payloads older than one minute are rejected.",
+ },
];
let webhookList: WebhookView[] = [];
diff --git a/src/types.ts b/src/types.ts
index 767d799a1..e36833eb4 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -252,25 +252,7 @@ export interface Cron extends TriggerBase {
}
interface WebhookVerification {
- scheme: "hmac-sha256" | "github" | "slack" | "stripe";
- secret?: string;
-}
-
-interface WebhookFilter {
- path: string;
- in: string[];
-}
-
-export interface Webhook extends TriggerBase {
- action: string;
- verification: WebhookVerification;
- filters?: WebhookFilter[];
- lastDeliveryId?: string;
- lastError?: string;
-}
-
-interface WebhookVerification {
- scheme: "hmac-sha256" | "github" | "slack" | "stripe";
+ scheme: "hmac-sha256" | "github" | "slack" | "stripe" | "linear";
secret?: string;
}
diff --git a/src/webhooks/verifiers.ts b/src/webhooks/verifiers.ts
index 6db3cb2e3..95b843c33 100644
--- a/src/webhooks/verifiers.ts
+++ b/src/webhooks/verifiers.ts
@@ -108,7 +108,36 @@ const hmacSha256: Verifier = {
},
};
-const VERIFIERS: Record<WebhookScheme, Verifier> = { github, slack, stripe, "hmac-sha256": hmacSha256 };
+const LINEAR_TS_TOLERANCE_MS = 60 * 1000;
+
+const linear: Verifier = {
+ verify({ secret, headers, rawBody }) {
+ if (!secret) return false;
+ const sig = header(headers, "linear-signature");
+ if (!sig) return false;
+ if (!constantTimeEqual(sig, hmacHex(secret, rawBody))) return false;
+ let body: unknown;
+ try {
+ body = JSON.parse(rawBody);
+ } catch {
+ return false;
+ }
+ if (
+ !isObj(body) ||
+ Array.isArray(body) ||
+ typeof body.webhookTimestamp !== "number" ||
+ !Number.isFinite(body.webhookTimestamp)
+ ) {
+ return false;
+ }
+ return Math.abs(Date.now() - body.webhookTimestamp) <= LINEAR_TS_TOLERANCE_MS;
+ },
+ deliveryId({ rawBody }) {
+ return bodyHash(rawBody);
+ },
+};
+
+const VERIFIERS: Record<WebhookScheme, Verifier> = { github, slack, stripe, linear, "hmac-sha256": hmacSha256 };
export type WebhookScheme = Webhook["verification"]["scheme"];
diff --git a/test/webhook-receiver.test.ts b/test/webhook-receiver.test.ts
index 15fb4d285..9d411787a 100644
--- a/test/webhook-receiver.test.ts
+++ b/test/webhook-receiver.test.ts
@@ -291,3 +291,35 @@ test("a third-party principal destination with accepted consent delivers to the
assert.equal(pending[0]?.destination.target, "U2");
assert.equal(pending[0]?.text, "DID-THE-WORK");
});
+
+test("linear rejects signed untimed deliveries without firing a turn", async () => {
+ const { webhooks, calls, receiver } = harness();
+ const wh = await webhooks.create({
+ ownerScopeId: scopeId("personal", "U1"),
+ owner: "U1",
+ createdBy: "U1",
+ action: "triage",
+ verification: { scheme: "linear", secret: SECRET },
+ });
+ for (const rawBody of [
+ "not json",
+ JSON.stringify({ action: "create" }),
+ JSON.stringify({ webhookTimestamp: null }),
+ ]) {
+ const out = await receiver.deliver(wh.id, {
+ rawBody,
+ headers: { "linear-signature": createHmac("sha256", SECRET).update(rawBody).digest("hex") },
+ });
+ assert.equal(out.status, 401);
+ }
+ await flush();
+ assert.equal(calls.length, 0);
+ const rawBody = JSON.stringify({ action: "create", webhookTimestamp: Date.now() });
+ const out = await receiver.deliver(wh.id, {
+ rawBody,
+ headers: { "linear-signature": createHmac("sha256", SECRET).update(rawBody).digest("hex") },
+ });
+ assert.equal(out.status, 202);
+ await flush();
+ assert.equal(calls.length, 1);
+});
diff --git a/test/webhook-verifiers.test.ts b/test/webhook-verifiers.test.ts
index f2343f626..ef483160f 100644
--- a/test/webhook-verifiers.test.ts
+++ b/test/webhook-verifiers.test.ts
@@ -127,6 +127,64 @@ test("hmac-sha256 dedup key is the signed body, ignoring the unsigned x-delivery
);
});
+test("linear verifier accepts a valid linear-signature and rejects a forged one", () => {
+ const v = getVerifier("linear")!;
+ const rawBody = JSON.stringify({ action: "create", type: "Issue", webhookTimestamp: Date.now() });
+ const good = { secret: SECRET, headers: { "linear-signature": hmac(rawBody) }, rawBody };
+ assert.equal(v.verify(good), true);
+ assert.equal(v.verify({ ...good, rawBody: rawBody + "x" }), false);
+ assert.equal(v.verify({ ...good, headers: { "linear-signature": hmac(rawBody + "x") } }), false);
+ assert.equal(v.verify({ ...good, secret: undefined }), false);
+ assert.equal(v.verify({ ...good, headers: {} }), false);
+});
+
+test("linear verifier rejects signed payloads without a finite numeric timestamp", () => {
+ const v = getVerifier("linear")!;
+ for (const rawBody of [
+ "not json",
+ "null",
+ "[]",
+ "42",
+ '"text"',
+ JSON.stringify({ action: "create" }),
+ JSON.stringify({ webhookTimestamp: String(Date.now()) }),
+ JSON.stringify({ webhookTimestamp: null }),
+ JSON.stringify({ webhookTimestamp: true }),
+ JSON.stringify({ webhookTimestamp: {} }),
+ JSON.stringify({ webhookTimestamp: [] }),
+ '{"webhookTimestamp":1e400}',
+ ]) {
+ assert.equal(v.verify({ secret: SECRET, headers: { "linear-signature": hmac(rawBody) }, rawBody }), false, rawBody);
+ }
+});
+
+test("linear verifier enforces the one-minute window in both directions", (t) => {
+ const now = 1_800_000_000_000;
+ t.mock.method(Date, "now", () => now);
+ const v = getVerifier("linear")!;
+ for (const offset of [0, -60_000, 60_000, -60_001, 60_001]) {
+ const rawBody = JSON.stringify({ webhookTimestamp: now + offset });
+ assert.equal(
+ v.verify({ secret: SECRET, headers: { "linear-signature": hmac(rawBody) }, rawBody }),
+ Math.abs(offset) <= 60_000,
+ `offset ${offset}`,
+ );
+ }
+});
+
+test("linear dedup key is the signed body, ignoring the unsigned linear-delivery header", () => {
+ const v = getVerifier("linear")!;
+ const rawBody = JSON.stringify({ action: "create", webhookTimestamp: 1 });
+ assert.equal(
+ v.deliveryId({ headers: { "linear-delivery": "a" }, rawBody }),
+ v.deliveryId({ headers: { "linear-delivery": "b" }, rawBody }),
+ );
+ assert.notEqual(
+ v.deliveryId({ headers: {}, rawBody }),
+ v.deliveryId({ headers: {}, rawBody: JSON.stringify({ action: "update", webhookTimestamp: 1 }) }),
+ );
+});
+
test("an unknown scheme has no verifier", () => {
assert.equal(getVerifier("paypal"), null);
assert.equal(getVerifier("none"), null);