@desplega.ai/agent-swarm 1.20.0 → 1.51.2

package/src/linear/webhook.ts

@@ -0,0 +1,104 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import {
+  handleAgentSessionEvent,
+  handleAgentSessionPrompted,
+  handleIssueDelete,
+  handleIssueUpdate,
+} from "./sync";
+
+// In-memory dedup set for Linear-Delivery header
+const recentDeliveries = new Map<string, number>(); // deliveryId -> timestamp
+const DEDUP_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+function cleanupDeliveries(): void {
+  const cutoff = Date.now() - DEDUP_TTL_MS;
+  for (const [id, ts] of recentDeliveries) {
+    if (ts < cutoff) recentDeliveries.delete(id);
+  }
+}
+
+/** Exported for testing — not part of the public API */
+export function _getRecentDeliveries(): Map<string, number> {
+  return recentDeliveries;
+}
+
+/** Exported for testing — not part of the public API */
+export function _clearRecentDeliveries(): void {
+  recentDeliveries.clear();
+}
+
+export function verifyLinearWebhook(rawBody: string, signature: string, secret: string): boolean {
+  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
+  try {
+    return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+  } catch {
+    return false;
+  }
+}
+
+async function processWebhookEvent(
+  event: Record<string, unknown>,
+  deliveryId?: string,
+): Promise<void> {
+  const { type, action } = event;
+
+  // Handle AgentSession events (Linear Agent SDK)
+  if (type === "AgentSessionEvent" || type === "AgentSession") {
+    if (action === "prompted") {
+      await handleAgentSessionPrompted(event);
+      return;
+    }
+    await handleAgentSessionEvent(event);
+    return;
+  }
+
+  // Handle Issue events
+  if (type === "Issue") {
+    if (action === "update") {
+      await handleIssueUpdate(event, deliveryId);
+    } else if (action === "remove") {
+      await handleIssueDelete(event);
+    }
+    return;
+  }
+}
+
+export async function handleLinearWebhook(
+  rawBody: string,
+  headers: Record<string, string | undefined>,
+): Promise<{ status: number; body: unknown }> {
+  const signingSecret = process.env.LINEAR_SIGNING_SECRET;
+  if (!signingSecret) {
+    return { status: 503, body: { error: "Linear webhook not configured" } };
+  }
+
+  // 1. Verify signature
+  const signature = headers["linear-signature"] ?? headers["x-linear-signature"];
+  if (!signature || !verifyLinearWebhook(rawBody, signature, signingSecret)) {
+    return { status: 401, body: { error: "Invalid signature" } };
+  }
+
+  // 2. Dedup via Linear-Delivery header
+  cleanupDeliveries();
+  const deliveryId = headers["linear-delivery"];
+  if (deliveryId) {
+    if (recentDeliveries.has(deliveryId)) {
+      return { status: 200, body: { status: "duplicate" } };
+    }
+    recentDeliveries.set(deliveryId, Date.now());
+  }
+
+  // 3. Parse and dispatch
+  const event = JSON.parse(rawBody) as Record<string, unknown>;
+
+  // Fire-and-forget for heavy work
+  processWebhookEvent(event, deliveryId ?? undefined).catch((err) => {
+    console.error("[Linear Webhook] Error processing event:", err, {
+      type: event.type,
+      action: event.action,
+      deliveryId,
+    });
+  });
+
+  return { status: 200, body: { status: "accepted" } };
+}

package/src/oauth/README.md

@@ -0,0 +1,66 @@
+# Generic OAuth Module
+
+Provider-agnostic OAuth 2.0 + PKCE wrapper used by tracker integrations (Linear, and any future providers).
+
+## Database Tables
+
+### `oauth_apps`
+
+One row per provider. Stores the OAuth application configuration.
+
+| Column | Description |
+|--------|-------------|
+| `provider` | Unique key (e.g. `"linear"`) |
+| `clientId` | OAuth client ID |
+| `clientSecret` | OAuth client secret (encrypted at rest is recommended for production) |
+| `authorizeUrl` | Provider's authorization endpoint |
+| `tokenUrl` | Provider's token exchange endpoint |
+| `redirectUri` | Callback URL registered with the provider |
+| `scopes` | Comma-separated list of granted scopes |
+| `metadata` | JSON blob for provider-specific extras |
+
+### `oauth_tokens`
+
+One row per provider. Stores the current access/refresh tokens.
+
+| Column | Description |
+|--------|-------------|
+| `provider` | Foreign key to `oauth_apps.provider` |
+| `accessToken` | Current access token |
+| `refreshToken` | Refresh token (nullable, depends on provider) |
+| `expiresAt` | ISO 8601 expiry timestamp |
+| `scope` | Scopes granted by the token exchange |
+
+## How It Works
+
+1. **`buildAuthorizationUrl(config)`** generates a PKCE-protected authorization URL and stores the code verifier in an in-memory map keyed by a random `state` parameter. Entries expire after 10 minutes.
+2. The user visits the URL and authorizes the app.
+3. The provider redirects to the callback with `code` and `state`.
+4. **`exchangeCode(config, code, state)`** looks up the pending state, sends the code + code verifier to the token endpoint, and persists the resulting tokens via `storeOAuthTokens()`.
+5. **`refreshAccessToken(config, refreshToken)`** exchanges a refresh token for a new access token and persists the result.
+
+## Adding a New OAuth Provider
+
+1. Define an `OAuthProviderConfig` with the provider's endpoints and scopes:
+   ```ts
+   const config: OAuthProviderConfig = {
+     provider: "jira",
+     clientId: process.env.JIRA_CLIENT_ID!,
+     clientSecret: process.env.JIRA_CLIENT_SECRET!,
+     authorizeUrl: "https://auth.atlassian.com/authorize",
+     tokenUrl: "https://auth.atlassian.com/oauth/token",
+     redirectUri: "http://localhost:3013/api/trackers/jira/callback",
+     scopes: ["read:jira-work", "write:jira-work"],
+     extraParams: { audience: "api.atlassian.com" }, // optional
+   };
+   ```
+2. Register HTTP routes for `/authorize` (calls `buildAuthorizationUrl`) and `/callback` (calls `exchangeCode`).
+3. Use `getOAuthTokens("jira")` to retrieve stored tokens when making API calls.
+4. Optionally call `refreshAccessToken()` when `isTokenExpiringSoon()` returns true.
+
+## In-Memory Pending State
+
+PKCE code verifiers are stored in-memory (not in the database) with a 10-minute TTL. This means:
+- The OAuth flow must complete within 10 minutes of starting.
+- If the server restarts mid-flow, the user must restart the authorization.
+- Expired entries are cleaned up lazily on the next `buildAuthorizationUrl` call.

package/src/oauth/index.ts

@@ -0,0 +1,6 @@
+export {
+  buildAuthorizationUrl,
+  exchangeCode,
+  type OAuthProviderConfig,
+  refreshAccessToken,
+} from "./wrapper";

package/src/oauth/wrapper.ts

@@ -0,0 +1,204 @@
+import * as oauth from "oauth4webapi";
+import { storeOAuthTokens } from "../be/db-queries/oauth";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface OAuthProviderConfig {
+  provider: string;
+  clientId: string;
+  clientSecret: string;
+  authorizeUrl: string;
+  tokenUrl: string;
+  redirectUri: string;
+  scopes: string[];
+  /** Extra query params appended to the authorization URL (e.g. { actor: "app" } for Linear) */
+  extraParams?: Record<string, string>;
+}
+
+interface PendingState {
+  codeVerifier: string;
+  config: OAuthProviderConfig;
+  createdAt: number;
+}
+
+// ─── In-memory pending state (PKCE code verifiers keyed by state) ────────────
+
+const STATE_TTL_MS = 10 * 60 * 1000; // 10 minutes
+const pendingStates = new Map<string, PendingState>();
+
+/** Remove expired entries from the pending state map */
+function cleanupExpiredStates(): void {
+  const now = Date.now();
+  for (const [key, entry] of pendingStates) {
+    if (now - entry.createdAt > STATE_TTL_MS) {
+      pendingStates.delete(key);
+    }
+  }
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Build an OAuth 2.0 authorization URL with PKCE (S256).
+ * Stores the pending state + code verifier in-memory for later exchange.
+ */
+export async function buildAuthorizationUrl(
+  config: OAuthProviderConfig,
+): Promise<{ url: string; state: string; codeVerifier: string }> {
+  cleanupExpiredStates();
+
+  const state = oauth.generateRandomState();
+  const codeVerifier = oauth.generateRandomCodeVerifier();
+  const codeChallenge = await oauth.calculatePKCECodeChallenge(codeVerifier);
+
+  pendingStates.set(state, {
+    codeVerifier,
+    config,
+    createdAt: Date.now(),
+  });
+
+  const url = new URL(config.authorizeUrl);
+  url.searchParams.set("client_id", config.clientId);
+  url.searchParams.set("redirect_uri", config.redirectUri);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("scope", config.scopes.join(","));
+  url.searchParams.set("state", state);
+  url.searchParams.set("code_challenge", codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+
+  // Append provider-specific extra params (e.g. actor=app for Linear)
+  if (config.extraParams) {
+    for (const [key, value] of Object.entries(config.extraParams)) {
+      url.searchParams.set(key, value);
+    }
+  }
+
+  return { url: url.toString(), state, codeVerifier };
+}
+
+/**
+ * Exchange an authorization code for tokens.
+ * Validates the state against our pending map, calls the token endpoint,
+ * and persists tokens via storeOAuthTokens().
+ */
+export async function exchangeCode(
+  config: OAuthProviderConfig,
+  code: string,
+  state: string,
+): Promise<{ accessToken: string; refreshToken?: string; expiresIn?: number; scope?: string }> {
+  const pending = pendingStates.get(state);
+  if (!pending) {
+    throw new Error("Invalid or expired OAuth state");
+  }
+  pendingStates.delete(state);
+
+  const { codeVerifier } = pending;
+
+  // Build token request manually — Linear doesn't use standard OAuth discovery
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    client_id: config.clientId,
+    client_secret: config.clientSecret,
+    redirect_uri: config.redirectUri,
+    code,
+    code_verifier: codeVerifier,
+  });
+
+  const response = await fetch(config.tokenUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString(),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Token exchange failed (${response.status}): ${errorText}`);
+  }
+
+  const data = (await response.json()) as {
+    access_token: string;
+    token_type: string;
+    expires_in?: number;
+    scope?: string;
+    refresh_token?: string;
+  };
+
+  // Persist tokens
+  const expiresAt = data.expires_in
+    ? new Date(Date.now() + data.expires_in * 1000).toISOString()
+    : new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(); // default 24h
+
+  storeOAuthTokens(config.provider, {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token ?? null,
+    expiresAt,
+    scope: data.scope ?? null,
+  });
+
+  return {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token,
+    expiresIn: data.expires_in,
+    scope: data.scope,
+  };
+}
+
+/**
+ * Refresh an access token using a stored refresh token.
+ * Persists the new tokens via storeOAuthTokens().
+ */
+export async function refreshAccessToken(
+  config: OAuthProviderConfig,
+  refreshToken: string,
+): Promise<{ accessToken: string; refreshToken?: string; expiresIn?: number }> {
+  const body = new URLSearchParams({
+    grant_type: "refresh_token",
+    client_id: config.clientId,
+    client_secret: config.clientSecret,
+    refresh_token: refreshToken,
+  });
+
+  const response = await fetch(config.tokenUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString(),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Token refresh failed (${response.status}): ${errorText}`);
+  }
+
+  const data = (await response.json()) as {
+    access_token: string;
+    token_type: string;
+    expires_in?: number;
+    refresh_token?: string;
+  };
+
+  const expiresAt = data.expires_in
+    ? new Date(Date.now() + data.expires_in * 1000).toISOString()
+    : new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString();
+
+  storeOAuthTokens(config.provider, {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token ?? null,
+    expiresAt,
+  });
+
+  return {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token,
+    expiresIn: data.expires_in,
+  };
+}
+
+// ─── Test helpers (exported for unit tests only) ─────────────────────────────
+
+export function _getPendingState(state: string): PendingState | undefined {
+  return pendingStates.get(state);
+}
+
+export function _clearPendingStates(): void {
+  pendingStates.clear();
+}