Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.mdx
index 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.
+
```bash
LINEAR_AGENT_ACCESS_TOKEN=lin_api_... # posts Agent Activities and creates proactive sessions
LINEAR_WEBHOOK_SECRET=... # verifies Linear-Signature
@@ -63,7 +65,7 @@ https://<deployment>/eve/v1/linear
For 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 messages
diff --git a/packages/eve/src/public/channels/linear/linearChannel.test.ts b/packages/eve/src/public/channels/linear/linearChannel.test.ts
index 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.ts
index 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.ts
index 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.ts
index 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;