@desplega.ai/agent-swarm 1.70.0 → 1.71.1

package/src/http/route-def.ts

@@ -60,6 +60,25 @@ interface RouteHandle<TParams, TQuery, TBody> {
 /** Global registry — populated at import time, read by OpenAPI generator */
 export const routeRegistry: RouteDef[] = [];
 
+/**
+ * Check whether a request targets a route declared (via the `route()` factory)
+ * with `auth: { apiKey: false }` — i.e. one that opts out of the API-key
+ * bearer check. Handler files must use the `route()` factory for this to take
+ * effect; unknown paths fail closed (auth required).
+ */
+export function isPublicRoute(method: string | undefined, pathSegments: string[]): boolean {
+  for (const def of routeRegistry) {
+    if (def.auth?.apiKey === false) {
+      if (
+        matchRoute(method, pathSegments, def.method.toUpperCase(), def.pattern, def.exact ?? true)
+      ) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
 // ─── Factory ─────────────────────────────────────────────────────────────────
 
 export function route<

package/src/http/trackers/index.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { handleJiraTracker } from "./jira";
 import { handleLinearTracker } from "./linear";
 
 export async function handleTrackers(
@@ -6,5 +7,17 @@ export async function handleTrackers(
   res: ServerResponse,
   pathSegments: string[],
 ): Promise<boolean> {
+  // Provider-specific dispatch based on the third path segment
+  // (e.g. "api", "trackers", "<provider>", ...).
+  if (pathSegments[0] === "api" && pathSegments[1] === "trackers") {
+    if (pathSegments[2] === "jira") {
+      return await handleJiraTracker(req, res, pathSegments);
+    }
+    if (pathSegments[2] === "linear") {
+      return await handleLinearTracker(req, res, pathSegments);
+    }
+  }
+  // Fallback: try Linear (preserves existing behavior for any path that
+  // somehow falls through without an explicit provider segment).
   return await handleLinearTracker(req, res, pathSegments);
 }

package/src/http/trackers/jira.ts

@@ -0,0 +1,395 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import { deleteOAuthTokens, getOAuthTokens } from "../../be/db-queries/oauth";
+import { isJiraEnabled } from "../../jira/app";
+import { clearJiraMetadata, getJiraMetadata } from "../../jira/metadata";
+import { getJiraAuthorizationUrl, handleJiraCallback } from "../../jira/oauth";
+import { handleJiraWebhook } from "../../jira/webhook";
+import { deleteJiraWebhook, registerJiraWebhook } from "../../jira/webhook-lifecycle";
+import { route } from "../route-def";
+import { deriveApiBaseUrl, parseQueryParams } from "../utils";
+
+const MANUAL_WEBHOOK_INSTRUCTIONS =
+  "See docs-site/.../guides/jira-integration.mdx for manual webhook registration steps.";
+
+// ─── Route Definitions ───────────────────────────────────────────────────────
+
+const jiraAuthorize = route({
+  method: "get",
+  path: "/api/trackers/jira/authorize",
+  pattern: ["api", "trackers", "jira", "authorize"],
+  summary: "Redirect to Atlassian OAuth consent screen",
+  tags: ["Trackers"],
+  auth: { apiKey: false },
+  responses: {
+    302: { description: "Redirect to Atlassian OAuth" },
+    500: { description: "Failed to generate authorization URL" },
+    503: { description: "Jira integration not configured" },
+  },
+});
+
+const jiraCallback = route({
+  method: "get",
+  path: "/api/trackers/jira/callback",
+  pattern: ["api", "trackers", "jira", "callback"],
+  summary: "Handle Jira OAuth callback (resolves cloudId via accessible-resources)",
+  tags: ["Trackers"],
+  auth: { apiKey: false },
+  query: z.object({
+    code: z.string(),
+    state: z.string(),
+  }),
+  responses: {
+    200: { description: "OAuth complete" },
+    400: { description: "Invalid state or code" },
+    500: { description: "Token exchange or accessible-resources fetch failed" },
+  },
+});
+
+const jiraStatus = route({
+  method: "get",
+  path: "/api/trackers/jira/status",
+  pattern: ["api", "trackers", "jira", "status"],
+  summary:
+    "Jira connection status, cloudId/siteUrl, token expiry, expected webhook URL, scope/token-config flags",
+  tags: ["Trackers"],
+  responses: {
+    200: { description: "Connection status" },
+    503: { description: "Jira integration not configured" },
+  },
+});
+
+const jiraWebhook = route({
+  method: "post",
+  path: "/api/trackers/jira/webhook/{token}",
+  pattern: ["api", "trackers", "jira", "webhook", null],
+  summary:
+    "Receive Jira webhook events (URL-token authenticated). Phase 2 stub — Phase 3 fills in dispatch.",
+  tags: ["Trackers"],
+  auth: { apiKey: false },
+  params: z.object({ token: z.string() }),
+  responses: {
+    200: { description: "Event accepted" },
+    401: { description: "Invalid URL token" },
+    503: { description: "Jira webhook handler not configured" },
+  },
+});
+
+// Admin: register a new dynamic webhook with Atlassian. apiKey is required
+// (route-factory default). The registered URL embeds JIRA_WEBHOOK_TOKEN so
+// inbound deliveries can be authenticated.
+const jiraWebhookRegister = route({
+  method: "post",
+  path: "/api/trackers/jira/webhook-register",
+  pattern: ["api", "trackers", "jira", "webhook-register"],
+  summary: "Register a Jira dynamic webhook (admin only)",
+  tags: ["Trackers"],
+  body: z.object({
+    jqlFilter: z.string().min(1),
+  }),
+  responses: {
+    200: { description: "Webhook registered" },
+    400: { description: "Invalid jqlFilter" },
+    503: { description: "Jira not connected or JIRA_WEBHOOK_TOKEN missing" },
+  },
+});
+
+// Admin: delete a dynamic webhook from Atlassian and remove from local
+// metadata. apiKey is required (route-factory default).
+const jiraWebhookDelete = route({
+  method: "delete",
+  path: "/api/trackers/jira/webhook/{id}",
+  pattern: ["api", "trackers", "jira", "webhook", null],
+  summary: "Delete a Jira dynamic webhook (admin only)",
+  tags: ["Trackers"],
+  params: z.object({
+    id: z.coerce.number().int().positive(),
+  }),
+  responses: {
+    200: { description: "Webhook deleted" },
+    400: { description: "Invalid webhook id" },
+    503: { description: "Jira not connected" },
+  },
+});
+
+// Admin: full disconnect — delete all registered Atlassian webhooks, drop
+// stored OAuth tokens, and clear cloudId/siteUrl/webhookIds metadata. Atlassian
+// 3LO has no public token revocation endpoint, so the OAuth grant itself must
+// be revoked by the user via id.atlassian.com → Connected apps.
+const jiraDisconnect = route({
+  method: "delete",
+  path: "/api/trackers/jira/disconnect",
+  pattern: ["api", "trackers", "jira", "disconnect"],
+  summary: "Fully disconnect Jira: delete all webhooks, drop tokens, clear metadata",
+  tags: ["Trackers"],
+  responses: {
+    200: { description: "Disconnected" },
+    503: { description: "Jira not configured" },
+  },
+});
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function getWebhookUrl(req: IncomingMessage): string {
+  const token = process.env.JIRA_WEBHOOK_TOKEN ?? "<unset>";
+  return `${deriveApiBaseUrl(req)}/api/trackers/jira/webhook/${token}`;
+}
+
+function getRedirectUri(req: IncomingMessage): string {
+  return `${deriveApiBaseUrl(req)}/api/trackers/jira/callback`;
+}
+
+// ─── Handler ─────────────────────────────────────────────────────────────────
+
+export async function handleJiraTracker(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+): Promise<boolean> {
+  // GET /api/trackers/jira/authorize — redirect to Atlassian OAuth consent
+  if (jiraAuthorize.match(req.method, pathSegments)) {
+    if (!isJiraEnabled()) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Jira integration not configured" }));
+      return true;
+    }
+
+    try {
+      const url = await getJiraAuthorizationUrl();
+      if (!url) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Failed to generate authorization URL" }));
+        return true;
+      }
+
+      res.writeHead(302, { Location: url });
+      res.end();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error("[Jira] Failed to generate authorization URL:", message);
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Failed to generate authorization URL" }));
+    }
+    return true;
+  }
+
+  // GET /api/trackers/jira/callback — handle OAuth callback from Atlassian
+  if (jiraCallback.match(req.method, pathSegments)) {
+    const queryParams = parseQueryParams(req.url || "");
+    const parsed = await jiraCallback.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true; // parse() already sent 400
+
+    const { code, state } = parsed.query;
+
+    try {
+      await handleJiraCallback(code, state);
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end(`<!DOCTYPE html>
+<html>
+<head><title>Jira Connected</title></head>
+<body style="font-family: system-ui; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0;">
+  <div style="text-align: center;">
+    <h1>Jira Connected</h1>
+    <p>OAuth authorization complete. You can close this window.</p>
+  </div>
+</body>
+</html>`);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error("[Jira] OAuth callback failed:", message);
+
+      if (message.includes("Invalid or expired OAuth state")) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Invalid or expired OAuth state" }));
+      } else {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "OAuth callback failed", details: message }));
+      }
+    }
+    return true;
+  }
+
+  // GET /api/trackers/jira/status — connection status (works even when not connected)
+  if (jiraStatus.match(req.method, pathSegments)) {
+    if (!isJiraEnabled()) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Jira integration not configured" }));
+      return true;
+    }
+
+    const tokens = getOAuthTokens("jira");
+    const meta = getJiraMetadata();
+    const scope = tokens?.scope ?? null;
+    // Atlassian returns scopes space-separated in the token response.
+    const scopeList = scope ? scope.split(/[\s,]+/).filter(Boolean) : [];
+
+    const hasManageWebhookScope = scopeList.includes("manage:jira-webhook");
+
+    const status: Record<string, unknown> = {
+      provider: "jira",
+      connected: !!tokens,
+      cloudId: meta.cloudId ?? null,
+      siteUrl: meta.siteUrl ?? null,
+      tokenExpiresAt: tokens?.expiresAt ?? null,
+      scope,
+      hasManageWebhookScope,
+      webhookTokenConfigured: Boolean(process.env.JIRA_WEBHOOK_TOKEN),
+      webhookUrl: getWebhookUrl(req),
+      redirectUri: getRedirectUri(req),
+      webhookIds: meta.webhookIds ?? [],
+    };
+
+    // Phase 5: surface manual-webhook instructions when the OAuth grant
+    // doesn't include `manage:jira-webhook` (admin must register webhooks
+    // manually in the Atlassian UI).
+    if (!hasManageWebhookScope) {
+      status.manualWebhookInstructions = MANUAL_WEBHOOK_INSTRUCTIONS;
+    }
+
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(status));
+    return true;
+  }
+
+  // POST /api/trackers/jira/webhook/:token — receive Jira dynamic-webhook events.
+  //
+  // Atlassian does not HMAC-sign OAuth 3LO dynamic webhooks (errata I8); we
+  // authenticate via a URL-path token compared with `JIRA_WEBHOOK_TOKEN`.
+  if (jiraWebhook.match(req.method, pathSegments)) {
+    // Path token sits at index 4 of the matched segments
+    // (["api","trackers","jira","webhook", null]). Use the route parser so
+    // we go through the same Zod path-param plumbing the rest of the route
+    // file uses.
+    const queryParams = parseQueryParams(req.url || "");
+    const parsed = await jiraWebhook.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true; // 400 already sent
+
+    // Read raw body using the same chunk-assembly pattern as
+    // src/http/trackers/linear.ts:166-171 — we don't trust the framework to
+    // hand us a parsed body for webhook routes.
+    const chunks: Buffer[] = [];
+    for await (const chunk of req) {
+      chunks.push(chunk);
+    }
+    const rawBody = Buffer.concat(chunks).toString();
+
+    const result = await handleJiraWebhook(parsed.params.token, rawBody);
+
+    // 401 with empty body — no info leak about valid-vs-missing token.
+    if (result.status === 401) {
+      res.writeHead(401);
+      res.end();
+      return true;
+    }
+
+    res.writeHead(result.status, { "Content-Type": "application/json" });
+    res.end(typeof result.body === "string" ? result.body : JSON.stringify(result.body));
+    return true;
+  }
+
+  // POST /api/trackers/jira/webhook-register — admin: register a dynamic webhook.
+  if (jiraWebhookRegister.match(req.method, pathSegments)) {
+    if (!isJiraEnabled()) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Jira integration not configured" }));
+      return true;
+    }
+    if (!process.env.JIRA_WEBHOOK_TOKEN) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "JIRA_WEBHOOK_TOKEN is not set" }));
+      return true;
+    }
+
+    const queryParams = parseQueryParams(req.url || "");
+    const parsed = await jiraWebhookRegister.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    try {
+      const result = await registerJiraWebhook(parsed.body.jqlFilter);
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(result));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error("[Jira] Webhook register failed:", message);
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Webhook registration failed", details: message }));
+    }
+    return true;
+  }
+
+  // DELETE /api/trackers/jira/webhook/:id — admin: delete a dynamic webhook.
+  // Note: this pattern overlaps the POST /webhook/:token path; the matcher
+  // disambiguates by HTTP method.
+  if (jiraWebhookDelete.match(req.method, pathSegments)) {
+    if (!isJiraEnabled()) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Jira integration not configured" }));
+      return true;
+    }
+
+    const queryParams = parseQueryParams(req.url || "");
+    const parsed = await jiraWebhookDelete.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    try {
+      await deleteJiraWebhook(parsed.params.id);
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ deleted: true, webhookId: parsed.params.id }));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`[Jira] Webhook delete failed (id=${parsed.params.id}):`, message);
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Webhook delete failed", details: message }));
+    }
+    return true;
+  }
+
+  // DELETE /api/trackers/jira/disconnect — full cleanup.
+  if (jiraDisconnect.match(req.method, pathSegments)) {
+    if (!isJiraEnabled()) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Jira integration not configured" }));
+      return true;
+    }
+
+    const meta = getJiraMetadata();
+    const ids = (meta.webhookIds ?? []).map((entry) => entry.id);
+
+    let webhooksDeleted = 0;
+    const webhookFailures: Array<{ id: number; error: string }> = [];
+    for (const id of ids) {
+      try {
+        await deleteJiraWebhook(id);
+        webhooksDeleted++;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[Jira] Disconnect: webhook delete failed (id=${id}): ${message}`);
+        webhookFailures.push({ id, error: message });
+      }
+    }
+
+    deleteOAuthTokens("jira");
+    clearJiraMetadata();
+
+    console.log(
+      `[Jira] Disconnected: ${webhooksDeleted}/${ids.length} webhooks deleted, tokens cleared, metadata reset`,
+    );
+
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({
+        disconnected: true,
+        webhooksDeleted,
+        webhooksTotal: ids.length,
+        webhookFailures,
+        // Atlassian 3LO has no token revocation endpoint — surface this so
+        // the UI can prompt the user to revoke the grant manually if desired.
+        revokeNote:
+          "Atlassian OAuth grants must be revoked manually at https://id.atlassian.com/manage/connected-apps if you want to fully sever the consent.",
+      }),
+    );
+    return true;
+  }
+
+  return false;
+}

package/src/http/trackers/linear.ts

@@ -1,11 +1,15 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
-import { getOAuthTokens } from "../../be/db-queries/oauth";
+import { deleteOAuthTokens, getOAuthTokens } from "../../be/db-queries/oauth";
 import { isLinearEnabled } from "../../linear/app";
-import { getLinearAuthorizationUrl, handleLinearCallback } from "../../linear/oauth";
+import {
+  getLinearAuthorizationUrl,
+  handleLinearCallback,
+  revokeLinearToken,
+} from "../../linear/oauth";
 import { handleLinearWebhook } from "../../linear/webhook";
 import { route } from "../route-def";
-import { parseQueryParams } from "../utils";
+import { deriveApiBaseUrl, parseQueryParams } from "../utils";
 
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
@@ -67,6 +71,21 @@ const linearWebhook = route({
   },
 });
 
+// Admin: full disconnect — best-effort revoke the OAuth grant with Linear,
+// then drop stored tokens. Linear webhooks are configured globally on the
+// OAuth app (not per-tenant), so no per-tenant webhook delete is needed.
+const linearDisconnect = route({
+  method: "delete",
+  path: "/api/trackers/linear/disconnect",
+  pattern: ["api", "trackers", "linear", "disconnect"],
+  summary: "Fully disconnect Linear: revoke OAuth grant + drop tokens",
+  tags: ["Trackers"],
+  responses: {
+    200: { description: "Disconnected" },
+    503: { description: "Linear not configured" },
+  },
+});
+
 // ─── Handler ─────────────────────────────────────────────────────────────────
 
 export async function handleLinearTracker(
@@ -146,7 +165,7 @@ export async function handleLinearTracker(
     }
 
     const tokens = getOAuthTokens("linear");
-    const baseUrl = process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
+    const baseUrl = deriveApiBaseUrl(req);
 
     const status = {
       provider: "linear",
@@ -154,6 +173,7 @@ export async function handleLinearTracker(
       tokenExpiry: tokens?.expiresAt ?? null,
       scope: tokens?.scope ?? null,
       webhookUrl: `${baseUrl}/api/trackers/linear/webhook`,
+      redirectUri: `${baseUrl}/api/trackers/linear/callback`,
     };
 
     res.writeHead(200, { "Content-Type": "application/json" });
@@ -183,5 +203,28 @@ export async function handleLinearTracker(
     return true;
   }
 
+  // DELETE /api/trackers/linear/disconnect — full cleanup.
+  if (linearDisconnect.match(req.method, pathSegments)) {
+    if (!isLinearEnabled()) {
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Linear integration not configured" }));
+      return true;
+    }
+
+    const tokens = getOAuthTokens("linear");
+    let revoked = false;
+    if (tokens?.accessToken) {
+      revoked = await revokeLinearToken(tokens.accessToken);
+    }
+
+    deleteOAuthTokens("linear");
+
+    console.log(`[Linear] Disconnected: revoke=${revoked}, tokens cleared`);
+
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ disconnected: true, revoked }));
+    return true;
+  }
+
   return false;
 }

package/src/http/utils.ts

@@ -57,6 +57,33 @@ export function jsonError(res: ServerResponse, error: string, status = 400) {
   res.end(JSON.stringify({ error }));
 }
 
+/**
+ * Derive the API base URL for outbound-facing values (webhook URLs, OAuth
+ * redirect URIs). Returns a URL with no trailing slash.
+ *
+ * Resolution order:
+ *   1. `MCP_BASE_URL` env (canonical)
+ *   2. Inbound request host — `X-Forwarded-Proto`/`X-Forwarded-Host` if behind
+ *      a proxy/tunnel (ngrok), else `Host` header. Lets the URL stay correct
+ *      when MCP_BASE_URL is unset and the API is reached via an arbitrary
+ *      external hostname.
+ *   3. `http://localhost:<PORT>` fallback
+ */
+export function deriveApiBaseUrl(req: IncomingMessage): string {
+  const envBase = process.env.MCP_BASE_URL?.trim();
+  if (envBase) return envBase.replace(/\/+$/, "");
+
+  const fwdProtoRaw = req.headers["x-forwarded-proto"];
+  const fwdHostRaw = req.headers["x-forwarded-host"];
+  const fwdProto = Array.isArray(fwdProtoRaw) ? fwdProtoRaw[0] : fwdProtoRaw;
+  const fwdHost = Array.isArray(fwdHostRaw) ? fwdHostRaw[0] : fwdHostRaw;
+  const proto = fwdProto?.split(",")[0]?.trim() || "http";
+  const host = fwdHost?.split(",")[0]?.trim() || req.headers.host;
+
+  if (host) return `${proto}://${host}`;
+  return `http://localhost:${process.env.PORT || "3013"}`;
+}
+
 /**
  * Match a route pattern against HTTP method and path segments.
  *