The Open Framework for Building Agents
fix(eve): expose Linear webhook timestamp skew (#1733)
vercel-gh-bot-5[bot]53c05ffbbefa
diff --git a/.changeset/quiet-ravens-retry.md b/.changeset/quiet-ravens-retry.mdnew file mode 100644index 000000000..592164c92--- /dev/null+++ b/.changeset/quiet-ravens-retry.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Allow Linear channels to configure the accepted webhook timestamp skew for retry deliveries.diff --git a/docs/channels/linear.mdx b/docs/channels/linear.mdxindex ff6038905..0129aa29d 100644--- a/docs/channels/linear.mdx+++ b/docs/channels/linear.mdx@@ -48,6 +48,8 @@ export default linearChannel({});```+Direct webhook verification accepts timestamps within 60 seconds by default, as Linear recommends. Set `maxSkewMs` to a larger number of milliseconds only when you intentionally accept delayed retries. Use the narrowest window that fits your retry policy.+```bashLINEAR_AGENT_ACCESS_TOKEN=lin_api_... # posts Agent Activities and creates proactive sessionsLINEAR_WEBHOOK_SECRET=... # verifies Linear-Signature@@ -63,7 +65,7 @@ https://<deployment>/eve/v1/linearFor Linear's agent surface, configure the OAuth authorize URL with `actor=app` and grant the app scopes that let it appear as an agent in Linear, including `app:assignable` and `app:mentionable`. Subscribe to the `AgentSessionEvent` webhook category so Linear sends `created` events when the agent is delegated or mentioned and `prompted` events when the user continues the session.-Linear sends webhook signatures in `Linear-Signature`; eve verifies the HMAC over the raw body and rejects stale `webhookTimestamp` values. If a trusted gateway verifies Linear before the request reaches eve, pass `credentials.webhookVerifier` instead of a webhook secret.+Linear sends webhook signatures in `Linear-Signature`; eve verifies the HMAC over the raw body and rejects stale `webhookTimestamp` values. If a trusted gateway verifies Linear before the request reaches eve, pass `credentials.webhookVerifier` instead of a webhook secret. Your custom verifier must enforce its timestamp policy because `maxSkewMs` does not apply.## How the channel handles messagesdiff --git a/packages/eve/src/public/channels/linear/linearChannel.test.ts b/packages/eve/src/public/channels/linear/linearChannel.test.tsindex 5eece9699..f4efb36ec 100644--- a/packages/eve/src/public/channels/linear/linearChannel.test.ts+++ b/packages/eve/src/public/channels/linear/linearChannel.test.ts@@ -181,6 +181,19 @@ describe("linearChannel inbound Agent Session events", () => {});});+ it("accepts signed retries within a configured timestamp skew", async () => {+ const channel = linearChannel({+ credentials: { webhookSecret: SECRET },+ maxSkewMs: 5 * 60_000,+ });+ const request = signedRequest(sessionPayload({ webhookTimestamp: Date.now() - 2 * 60_000 }));++ const { response, send } = await firePost(channel, request);++ expect(response.status).toBe(200);+ expect(send).toHaveBeenCalledTimes(1);+ });+it("delivers prompted values as messages for the harness to resolve", async () => {const channel = linearChannel({ credentials: { webhookSecret: SECRET } });const { send } = await firePost(diff --git a/packages/eve/src/public/channels/linear/linearChannel.ts b/packages/eve/src/public/channels/linear/linearChannel.tsindex 8abc71003..22bd075e0 100644--- a/packages/eve/src/public/channels/linear/linearChannel.ts+++ b/packages/eve/src/public/channels/linear/linearChannel.ts@@ -172,6 +172,8 @@ export interface LinearChannelConfig {readonly api?: LinearApiOptions;readonly credentials?: LinearChannelCredentials;readonly events?: LinearChannelEvents;+ /** Max allowed webhook timestamp skew in milliseconds. Defaults to 60 seconds. */+ readonly maxSkewMs?: number;readonly route?: string;/** Inbound Agent Session hook. Defaults to dispatching `created` and `prompted` events. */@@ -225,7 +227,7 @@ export function linearChannel(config: LinearChannelConfig = {}): LinearChannel {POST<LinearChannelState>(config.route ?? LINEAR_CHANNEL_DEFAULT_ROUTE,async (req, { from, waitUntil }) => {- const body = await verifyInbound(req, config.credentials);+ const body = await verifyInbound(req, config.credentials, config.maxSkewMs);if (body === null) return new Response("unauthorized", { status: 401 });let event;@@ -424,9 +426,11 @@ function initialLinearState(): LinearChannelState {async function verifyInbound(req: Request,credentials: LinearChannelCredentials | undefined,+ maxSkewMs: number | undefined,): Promise<string | null> {try {return await verifyLinearRequest(req, {+ maxSkewMs,webhookSecret: credentials?.webhookSecret,webhookVerifier: credentials?.webhookVerifier,});diff --git a/packages/eve/src/public/channels/linear/verify.test.ts b/packages/eve/src/public/channels/linear/verify.test.tsindex 4b14cb883..43a3906fe 100644--- a/packages/eve/src/public/channels/linear/verify.test.ts+++ b/packages/eve/src/public/channels/linear/verify.test.ts@@ -62,6 +62,17 @@ describe("verifyLinearRequest", () => {);});+ it.each([Number.NaN, Number.POSITIVE_INFINITY, -1])(+ "rejects invalid maxSkewMs values (%s)",+ async (maxSkewMs) => {+ const req = signedRequest();++ await expect(verifyLinearRequest(req, { maxSkewMs, webhookSecret: SECRET })).rejects.toThrow(+ "maxSkewMs must be a non-negative finite number",+ );+ },+ );+it("uses webhookVerifier instead of HMAC when supplied", async () => {const req = signedRequest({ secret: "wrong-secret" });diff --git a/packages/eve/src/public/channels/linear/verify.ts b/packages/eve/src/public/channels/linear/verify.tsindex cf09b6955..befcde317 100644--- a/packages/eve/src/public/channels/linear/verify.ts+++ b/packages/eve/src/public/channels/linear/verify.ts@@ -64,6 +64,10 @@ export function signLinearWebhookBody(body: string, secret: string): string {}function verifyWebhookTimestamp(body: string, maxSkewMs: number): void {+ if (!Number.isFinite(maxSkewMs) || maxSkewMs < 0) {+ throw new Error("linearChannel: maxSkewMs must be a non-negative finite number.");+ }+let parsed: unknown;try {parsed = JSON.parse(body) as unknown;