@desplega.ai/agent-swarm 2.3.0 → 2.4.0

package/src/http/core.ts

@@ -47,6 +47,14 @@ import { refreshSecretScrubberCache, registerSensitiveKeyName } from "../utils/s
 import { resolveHttpRequestAuth } from "./auth";
 import { generateOpenApiSpec, SCALAR_HTML } from "./openapi";
 import { findRoute, isPublicRoute, route, runtimeInstanceHeader } from "./route-def";
+import {
+  canReadSession,
+  pathSessionDenial,
+  readableByFor,
+  resolveSessionActor,
+  SESSION_READ_DENIED,
+  userAgentIdentityDenial,
+} from "./session-access";
 import {
   agentWithCapacity,
   duplicateGuardedQueryKey,
@@ -503,6 +511,15 @@ export async function handleCore(
     setRequestAuth(req, auth);
   }
 
+  // A user token never gains agent identity from X-Agent-ID, on /mcp, /api/poll
+  // or any worker-header route.
+  const routeDef = findRoute(req.method, pathSegments);
+  const agentIdentityDenial = await userAgentIdentityDenial(req, routeDef, pathSegments);
+  if (agentIdentityDenial) {
+    jsonError(res, agentIdentityDenial, 403);
+    return true;
+  }
+
   if (auth?.kind === "agent") {
     const query = parseQueryParams(req.url || "");
     const duplicate = duplicateGuardedQueryKey(query);
@@ -565,7 +582,7 @@ export async function handleCore(
   if (auth?.kind === "user" && isRbacEnabled()) {
     const grant = await getUserGrant(auth.userId);
     if (!grant.grantsAll) {
-      const def = findRoute(req.method, pathSegments);
+      const def = routeDef;
       const decision = decideAdmission({
         method: req.method ?? "",
         rbac: def?.rbac,
@@ -585,6 +602,16 @@ export async function handleCore(
     }
   }
 
+  // Session access for every route keyed by a task or steering message, before
+  // its handler reads or changes anything (the route's `session` posture).
+  if (routeDef?.session) {
+    const sessionDenial = await pathSessionDenial(req, myAgentId, routeDef, pathSegments);
+    if (sessionDenial) {
+      jsonError(res, sessionDenial, 403);
+      return true;
+    }
+  }
+
   // POST /internal/reload-config — re-read swarm_config into process.env and re-init integrations
   if (req.method === "POST" && req.url === "/internal/reload-config") {
     try {
@@ -662,7 +689,14 @@ export async function handleCore(
     const queryParams = parseQueryParams(req.url || "");
     const taskId = queryParams.get("taskId");
 
+    // A user token naming an agent in X-Agent-ID still reads only its sessions.
+    const sessionActor = await resolveSessionActor(req, myAgentId);
     if (taskId) {
+      if (!(await canReadSession(req, myAgentId, taskId))) {
+        res.writeHead(403, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: SESSION_READ_DENIED }));
+        return true;
+      }
       // Check if specific task is cancelled
       const task = await getTaskById(taskId);
       if (task && task.status === "cancelled") {
@@ -687,7 +721,10 @@ export async function handleCore(
     }
 
     // No taskId - return all recently cancelled tasks for this agent
-    const cancelledTasks = await getRecentlyCancelledTasksForAgent(myAgentId);
+    const cancelledTasks = await getRecentlyCancelledTasksForAgent(
+      myAgentId,
+      readableByFor(sessionActor),
+    );
     res.writeHead(200, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ cancelled: cancelledTasks }));
     return true;

package/src/http/events.ts

@@ -13,7 +13,8 @@ import {
   EventStatusSchema,
   SwarmEventSchema,
 } from "../types";
-import { route } from "./route-def";
+import { bodyListTask, bodyTask, route } from "./route-def";
+import { readableByFor, resolveSessionActor } from "./session-access";
 import { jsonError } from "./utils";
 
 // ─── Route Definitions ───────────────────────────────────────────────────────
@@ -36,6 +37,7 @@ const createEventRoute = route({
   method: "post",
   path: "/api/events",
   pattern: ["api", "events"],
+  session: bodyTask("taskId"),
   summary: "Store a single event",
   tags: ["Events"],
   body: eventBodySchema,
@@ -53,6 +55,7 @@ const createEventsBatchRoute = route({
   method: "post",
   path: "/api/events/batch",
   pattern: ["api", "events", "batch"],
+  session: bodyListTask("events", "taskId"),
   summary: "Store multiple events in a batch",
   tags: ["Events"],
   body: z.object({
@@ -153,7 +156,7 @@ export async function handleEvents(
   res: ServerResponse,
   pathSegments: string[],
   queryParams: URLSearchParams,
-  _myAgentId: string | undefined,
+  myAgentId: string | undefined,
 ): Promise<boolean> {
   // Match batch BEFORE generic /api/events (POST)
   if (createEventsBatchRoute.match(req.method, pathSegments)) {
@@ -252,6 +255,7 @@ export async function handleEvents(
       limit: parsed.query.limit ?? 100,
       events: eventFilter,
       latestPerDataField: latestPerDataField ? { events: latestEvents, dataFields } : undefined,
+      readableBy: readableByFor(await resolveSessionActor(req, myAgentId)),
     });
     getEventsRoute.respond(
       res,

package/src/http/favorite-owner.ts

@@ -16,7 +16,7 @@ export type FavoriteOwner = {
  */
 export const DASHBOARD_USER_HEADER = "x-swarm-user-id";
 
-function dashboardUserIdHeader(req: IncomingMessage): string | null {
+export function dashboardUserIdHeader(req: IncomingMessage): string | null {
   const raw = req.headers[DASHBOARD_USER_HEADER];
   const value = (Array.isArray(raw) ? raw[0] : raw)?.trim();
   return value ? value : null;

package/src/http/fs.ts

@@ -15,6 +15,7 @@ import { getCurrentRequestAuth } from "../utils/request-auth-context";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { requestPrincipal } from "./request-principal";
 import { route } from "./route-def";
+import { canReadSession, SESSION_READ_DENIED } from "./session-access";
 import { BODY_TOO_LARGE, enforceContentLengthCap, jsonError } from "./utils";
 
 // Upload wall-clock past which the provider round-trip is worth a log line.
@@ -126,6 +127,7 @@ const listTaskFilesRoute = route({
   method: "get",
   path: "/api/fs/tasks/{taskId}/files",
   pattern: ["api", "fs", "tasks", null, "files"],
+  session: { taskParam: "taskId" },
   summary: "List task file attachments",
   tags: ["FS"],
   params: taskParams,
@@ -142,6 +144,7 @@ const uploadTaskFileRoute = route({
   method: "post",
   path: "/api/fs/tasks/{taskId}/files",
   pattern: ["api", "fs", "tasks", null, "files"],
+  session: { taskParam: "taskId" },
   summary: "Upload a binary task file attachment",
   description:
     "Accepts a raw binary request body. Pass the display/path name as the `name` query parameter.",
@@ -163,6 +166,7 @@ const getTaskFileRoute = route({
   method: "get",
   path: "/api/fs/tasks/{taskId}/files/{attachmentId}",
   pattern: ["api", "fs", "tasks", null, "files", null],
+  session: { taskParam: "taskId" },
   summary: "Get task file attachment metadata",
   tags: ["FS"],
   params: attachmentParams,
@@ -176,6 +180,7 @@ const downloadTaskFileRoute = route({
   method: "get",
   path: "/api/fs/tasks/{taskId}/files/{attachmentId}/raw",
   pattern: ["api", "fs", "tasks", null, "files", null, "raw"],
+  session: { taskParam: "taskId" },
   summary: "Download raw task file bytes",
   description: "Streams raw bytes. File content is not secret-scrubbed.",
   tags: ["FS"],
@@ -193,6 +198,7 @@ const signedUrlTaskFileRoute = route({
   method: "get",
   path: "/api/fs/tasks/{taskId}/files/{attachmentId}/signed-url",
   pattern: ["api", "fs", "tasks", null, "files", null, "signed-url"],
+  session: { taskParam: "taskId" },
   summary: "Create a provider signed GET URL for a task file",
   tags: ["FS"],
   params: attachmentParams,
@@ -208,6 +214,7 @@ const deleteTaskFileRoute = route({
   method: "delete",
   path: "/api/fs/tasks/{taskId}/files/{attachmentId}",
   pattern: ["api", "fs", "tasks", null, "files", null],
+  session: { taskParam: "taskId" },
   summary: "Delete a task file attachment",
   tags: ["FS"],
   params: attachmentParams,
@@ -263,7 +270,13 @@ export async function handleFs(
   if (downloadTaskFileRoute.match(req.method, pathSegments)) {
     const parsed = await downloadTaskFileRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
-    const attachment = await findAttachment(parsed.params.taskId, parsed.params.attachmentId, res);
+    const attachment = await findAttachment(
+      req,
+      myAgentId,
+      parsed.params.taskId,
+      parsed.params.attachmentId,
+      res,
+    );
     if (!attachment) return true;
     return sendDownload(res, attachment);
   }
@@ -271,7 +284,13 @@ export async function handleFs(
   if (signedUrlTaskFileRoute.match(req.method, pathSegments)) {
     const parsed = await signedUrlTaskFileRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
-    const attachment = await findAttachment(parsed.params.taskId, parsed.params.attachmentId, res);
+    const attachment = await findAttachment(
+      req,
+      myAgentId,
+      parsed.params.taskId,
+      parsed.params.attachmentId,
+      res,
+    );
     if (!attachment) return true;
     return sendSignedUrl(res, attachment, parsed.query.expiresIn);
   }
@@ -279,7 +298,13 @@ export async function handleFs(
   if (getTaskFileRoute.match(req.method, pathSegments)) {
     const parsed = await getTaskFileRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
-    const attachment = await findAttachment(parsed.params.taskId, parsed.params.attachmentId, res);
+    const attachment = await findAttachment(
+      req,
+      myAgentId,
+      parsed.params.taskId,
+      parsed.params.attachmentId,
+      res,
+    );
     if (!attachment) return true;
     getTaskFileRoute.respond(res, 200, attachment);
     return true;
@@ -313,6 +338,10 @@ export async function handleFs(
     const parsed = await listTaskFilesRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
     if (!(await getTaskById(parsed.params.taskId))) return notFound(res, "Task not found");
+    if (!(await canReadSession(req, myAgentId, parsed.params.taskId))) {
+      jsonError(res, SESSION_READ_DENIED, 403);
+      return true;
+    }
     listTaskFilesRoute.respond(res, 200, {
       attachments: await getTaskAttachments(parsed.params.taskId),
     });
@@ -493,6 +522,8 @@ function backingProviderId(attachment: TaskAttachment): string | null {
 }
 
 async function findAttachment(
+  req: IncomingMessage,
+  myAgentId: string | undefined,
   taskId: string,
   attachmentId: string,
   res: ServerResponse,
@@ -501,6 +532,10 @@ async function findAttachment(
     notFound(res, "Task not found");
     return null;
   }
+  if (!(await canReadSession(req, myAgentId, taskId))) {
+    jsonError(res, SESSION_READ_DENIED, 403);
+    return null;
+  }
   const attachment = (await getTaskAttachments(taskId)).find((item) => item.id === attachmentId);
   if (!attachment) {
     notFound(res, "Attachment not found");

package/src/http/index.ts

@@ -116,6 +116,7 @@ import { handlePagesPublic } from "./pages-public";
 import { handlePoll } from "./poll";
 import { handlePricing } from "./pricing";
 import { handlePromptTemplates } from "./prompt-templates";
+import { handleRanking } from "./ranking";
 import { handleRealtimeAsset, handleRealtimeTicket } from "./realtime";
 import { handleRepos } from "./repos";
 import { handleRooms } from "./rooms";
@@ -403,10 +404,11 @@ const httpServer = createHttpServer(async (req, res) => {
         () => handleExtensions(req, res, pathSegments, queryParams, myAgentId),
         () => handleFavorites(req, res, pathSegments, queryParams, myAgentId),
         () => handleUsers(req, res, pathSegments, queryParams),
-        () => handleSessions(req, res, pathSegments, queryParams),
+        () => handleSessions(req, res, pathSegments, queryParams, myAgentId),
         () => handleInboxState(req, res, pathSegments, queryParams),
         () => handleTelemetryUi(req, res, pathSegments, queryParams, myAgentId),
         () => handleUsedBy(req, res, pathSegments, queryParams, myAgentId),
+        () => handleRanking(req, res, pathSegments, queryParams),
         () => handleFleetBenchmark(req, res, pathSegments, queryParams),
         () => handleTaskTemplates(req, res, pathSegments, queryParams),
         () => handleMcp(req, res, transports, transportActivity, mcpSessionAgents),

package/src/http/memory.ts

@@ -44,7 +44,7 @@ import { AgentMemorySchema, AgentMemoryScopeSchema, AgentMemorySourceSchema } fr
 import { getRequestAuth } from "../utils/request-auth-context";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { rejectGuest } from "./request-principal";
-import { route } from "./route-def";
+import { bodyTask, route } from "./route-def";
 import { jsonError, parseQueryParams } from "./utils";
 
 // ─── Response Schemas ────────────────────────────────────────────────────────
@@ -68,6 +68,7 @@ const indexMemory = route({
   method: "post",
   path: "/api/memory/index",
   pattern: ["api", "memory", "index"],
+  session: bodyTask("sourceTaskId"),
   summary: "Ingest content into memory system (async embedding)",
   tags: ["Memory"],
   // The gate only bites when the key that lands on the rows (here, `sourcePath`) sits under a
@@ -687,6 +688,7 @@ const rateMemory = route({
   method: "post",
   path: "/api/memory/rate",
   pattern: ["api", "memory", "rate"],
+  session: { none: "worker-only: it needs X-Agent-ID, which a user token cannot send" },
   summary: "Submit RatingEvents to update memory usefulness posteriors",
   tags: ["Memory"],
   auth: { apiKey: true, agentId: true },

package/src/http/ranking.ts

@@ -0,0 +1,367 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import { getDbClient, upsertSwarmConfig } from "../be/db";
+import {
+  buildListing,
+  mintRankingClaim,
+  PUBLIC_RANKING_ENABLED_KEY,
+  RANKING_CATEGORIES,
+  rankingEntryFile,
+  rankingFormSchema,
+  rankingLeaveUrl,
+  rankingPrUrl,
+  readTelemetryRanking,
+  TELEMETRY_RANKING_KEY,
+  type TelemetryRanking,
+} from "../ranking/telemetry-ranking";
+import { isTelemetryEnabled, telemetry } from "../telemetry";
+import { isEnvFlagEnabled } from "../utils/env-flag";
+import {
+  ORG_IDENTITY_KEYS,
+  type OrgIdentityStatus,
+  orgIdentityStatus,
+} from "../utils/org-identity";
+import { ensureConfigAdmin } from "./config";
+import { scheduleIntegrationsReload } from "./core";
+import { route } from "./route-def";
+import { globalConfig, telemetryProxyEndpoint } from "./used-by";
+
+// ─── Schemas ─────────────────────────────────────────────────────────────────
+
+const ListingSchema = z.object({
+  v: z.literal(1),
+  claim: z.string(),
+  name: z.string(),
+  domain: z.string(),
+  category: z.enum(RANKING_CATEGORIES),
+  subcategory: z.string().nullable(),
+  description: z.string().nullable(),
+  sourceCodeUrl: z.string().nullable(),
+  updatedAt: z.string(),
+});
+
+const RankingStateSchema = z.object({
+  eligible: z.boolean(),
+  missing: z.array(z.enum(ORG_IDENTITY_KEYS)),
+  telemetryOn: z.boolean(),
+  enabled: z.boolean(),
+  /** The org identity the listing would copy. */
+  name: z.string().nullable(),
+  domain: z.string().nullable(),
+  listing: ListingSchema.nullable(),
+  /** False when the stored listing was built for another website: a new PR is needed. */
+  listingMatchesDomain: z.boolean(),
+  fileJson: z.string().nullable(),
+  prUrl: z.string().nullable(),
+  verifyUrl: z.string().nullable(),
+});
+export type RankingState = z.infer<typeof RankingStateSchema>;
+
+const OptInResponseSchema = z.object({
+  domain: z.string(),
+  claim: z.string(),
+  listing: ListingSchema,
+  fileJson: z.string(),
+  prUrl: z.string(),
+  verifyUrl: z.string(),
+});
+
+const OptOutResponseSchema = z.object({
+  enabled: z.literal(false),
+  leaveUrl: z.string().nullable(),
+});
+
+// ─── Route Definitions ───────────────────────────────────────────────────────
+
+const getRanking = route({
+  method: "get",
+  path: "/api/ranking",
+  pattern: ["api", "ranking"],
+  summary: "Public ranking state",
+  description:
+    "Whether this install can join the public agent-swarm.dev ranking (telemetry on, organization name and website set), whether it is opted in, and its stored listing. The listing carries the private ranking claim, so only a config admin can read it.",
+  tags: ["Telemetry"],
+  responses: {
+    200: { description: "Ranking state", schema: RankingStateSchema },
+    401: { description: "Unauthorized" },
+    403: { description: "Only a config admin can read the ranking state" },
+  },
+  rbac: { permission: "config.write.any" },
+});
+
+const optIn = route({
+  method: "post",
+  path: "/api/ranking/opt-in",
+  pattern: ["api", "ranking", "opt-in"],
+  summary: "Opt this install into the public ranking",
+  description:
+    "Builds the telemetry_ranking listing from the organization name and website plus the chosen category, stores it, turns PUBLIC_RANKING_ENABLED on and sends ranking.opted_in. The install is ranked only after a ranking PR with the returned file is merged into desplega-ai/agent-swarm.",
+  tags: ["Telemetry"],
+  body: rankingFormSchema,
+  responses: {
+    200: { description: "Opted in", schema: OptInResponseSchema },
+    400: { description: "A listing field is invalid" },
+    401: { description: "Unauthorized" },
+    403: { description: "Only a config admin can opt in" },
+    409: {
+      description:
+        "telemetry_off: telemetry is off or the install has no ID. org_identity_missing: the organization name or website is not set (`missing` lists which).",
+    },
+  },
+  rbac: { permission: "config.write.any" },
+});
+
+const optOut = route({
+  method: "post",
+  path: "/api/ranking/opt-out",
+  pattern: ["api", "ranking", "opt-out"],
+  summary: "Leave the public ranking",
+  description:
+    "Turns PUBLIC_RANKING_ENABLED off and sends ranking.opted_out, so workers stop sending ranking.usage. Returns the GitHub page that deletes the ranking entry.",
+  tags: ["Telemetry"],
+  responses: {
+    200: { description: "Opted out", schema: OptOutResponseSchema },
+    401: { description: "Unauthorized" },
+    403: { description: "Only a config admin can opt out" },
+  },
+  rbac: { permission: "config.write.any" },
+});
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+const RANKING_CONFIG_KEYS = new Set<string>([...ORG_IDENTITY_KEYS, PUBLIC_RANKING_ENABLED_KEY]);
+
+/**
+ * The org identity from global config. `changed` carries a value just written
+ * or deleted, since `globalConfig` falls back to `process.env`, which the
+ * debounced reload has not updated yet.
+ */
+async function currentIdentity(changed?: {
+  key: string;
+  value: string | null;
+}): Promise<OrgIdentityStatus> {
+  const read = async (key: string) =>
+    changed?.key === key ? changed.value : await globalConfig(key);
+  return orgIdentityStatus({
+    SWARM_ORG_NAME: await read("SWARM_ORG_NAME"),
+    SWARM_ORG_WEBSITE: await read("SWARM_ORG_WEBSITE"),
+  });
+}
+
+async function storedListing(): Promise<TelemetryRanking | null> {
+  return readTelemetryRanking(await globalConfig(TELEMETRY_RANKING_KEY));
+}
+
+async function rankingEnabled(): Promise<boolean> {
+  const raw = await globalConfig(PUBLIC_RANKING_ENABLED_KEY);
+  return isEnvFlagEnabled(PUBLIC_RANKING_ENABLED_KEY, false, {
+    [PUBLIC_RANKING_ENABLED_KEY]: raw,
+  });
+}
+
+async function telemetryReady(): Promise<boolean> {
+  return isTelemetryEnabled() && Boolean(await globalConfig("telemetry_installation_id"));
+}
+
+async function verifyUrl(listing: Pick<TelemetryRanking, "domain" | "claim">): Promise<string> {
+  const params = new URLSearchParams({ domain: listing.domain, claim: listing.claim });
+  return `${await telemetryProxyEndpoint("/v1/ranking/verify")}?${params.toString()}`;
+}
+
+async function setEnabled(enabled: boolean): Promise<void> {
+  await upsertSwarmConfig({
+    scope: "global",
+    key: PUBLIC_RANKING_ENABLED_KEY,
+    value: String(enabled),
+  });
+}
+
+function emitOptedIn(listing: TelemetryRanking): void {
+  telemetry.ranking(
+    "opted_in",
+    { listing: JSON.stringify(listing) },
+    { orgName: listing.name, orgWebsite: listing.domain },
+  );
+}
+
+function emitOptedOut(domain: string): void {
+  telemetry.ranking("opted_out", { domain });
+}
+
+export async function buildRankingState(): Promise<RankingState> {
+  const [identity, listing, enabled, telemetryOn] = await Promise.all([
+    currentIdentity(),
+    storedListing(),
+    rankingEnabled(),
+    telemetryReady(),
+  ]);
+  const listingMatchesDomain = Boolean(listing && listing.domain === identity.website);
+  const current = listingMatchesDomain ? listing : null;
+  return {
+    eligible: telemetryOn && identity.ok,
+    missing: identity.missing,
+    telemetryOn,
+    enabled: enabled && listingMatchesDomain,
+    name: identity.name,
+    domain: identity.website,
+    listing,
+    listingMatchesDomain,
+    fileJson: current ? rankingEntryFile(current) : null,
+    prUrl: current ? rankingPrUrl(current) : null,
+    verifyUrl: current ? await verifyUrl(current) : null,
+  };
+}
+
+/**
+ * Keep the listing in step with the org identity after a global config write.
+ * A renamed org rebuilds the listing with the same claim and re-sends it; a
+ * cleared or placeholder name, a changed or cleared website, or the setting
+ * turned off by hand opts the install out.
+ */
+export async function syncRankingAfterConfigChange(
+  key: string,
+  value: string | null,
+): Promise<void> {
+  if (!RANKING_CONFIG_KEYS.has(key)) return;
+  const listing = await storedListing();
+  if (!listing) return;
+  if (key === PUBLIC_RANKING_ENABLED_KEY) {
+    if (!isEnvFlagEnabled(key, false, { [key]: value ?? undefined })) {
+      emitOptedOut(listing.domain);
+    }
+    return;
+  }
+  if (!(await rankingEnabled())) return;
+
+  const identity = await currentIdentity({ key, value });
+  let rebuilt: TelemetryRanking | null = null;
+  if (identity.ok && identity.website === listing.domain) {
+    if (identity.name === listing.name) return;
+    try {
+      rebuilt = buildListing(identity, listing, listing.claim);
+    } catch {
+      // A name the listing cannot carry (over 60 characters) leaves the ranking.
+    }
+  }
+  if (!rebuilt) {
+    await setEnabled(false);
+    emitOptedOut(listing.domain);
+    return;
+  }
+  await upsertSwarmConfig({
+    scope: "global",
+    key: TELEMETRY_RANKING_KEY,
+    value: JSON.stringify(rebuilt),
+  });
+  emitOptedIn(rebuilt);
+}
+
+function conflict(res: ServerResponse, body: Record<string, unknown>): void {
+  res.writeHead(409, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+
+// ─── Handler ─────────────────────────────────────────────────────────────────
+
+export async function handleRanking(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+): Promise<boolean> {
+  if (getRanking.match(req.method, pathSegments)) {
+    const parsed = await getRanking.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    // The state carries the claim and the PR that proves ownership of the listing.
+    if (!(await ensureConfigAdmin(req, res, "config.write.any"))) return true;
+    getRanking.respond(res, 200, await buildRankingState());
+    return true;
+  }
+
+  if (optIn.match(req.method, pathSegments)) {
+    const parsed = await optIn.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!(await ensureConfigAdmin(req, res, "config.write.any"))) return true;
+
+    if (!(await telemetryReady())) {
+      conflict(res, {
+        error: "telemetry_off",
+        message: "Turn telemetry on first: the ranking counts tokens from telemetry.",
+      });
+      return true;
+    }
+    const identity = await currentIdentity();
+    if (!identity.ok || !identity.website) {
+      conflict(res, {
+        error: "org_identity_missing",
+        message: "Set the organization name and website first",
+        missing: identity.missing,
+      });
+      return true;
+    }
+
+    const website = identity.website;
+    const db = getDbClient();
+    // Read the stored claim under the write lock: two concurrent first opt-ins
+    // must return the same claim, or the one merged into community/ranking is lost.
+    const built = await db.transaction(async () => {
+      const stored = await storedListing();
+      const claim = stored?.domain === website ? stored.claim : mintRankingClaim();
+      let listing: TelemetryRanking;
+      try {
+        listing = buildListing(identity, parsed.body, claim);
+      } catch (error) {
+        return { ok: false as const, error };
+      }
+      await upsertSwarmConfig({
+        scope: "global",
+        key: TELEMETRY_RANKING_KEY,
+        value: JSON.stringify(listing),
+      });
+      await setEnabled(true);
+      db.afterCommit(() => emitOptedIn(listing));
+      return { ok: true as const, listing };
+    });
+    if (!built.ok) {
+      const issue = built.error instanceof z.ZodError ? built.error.issues[0] : undefined;
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          error: issue
+            ? `Invalid ${issue.path.join(".") || "listing"}: ${issue.message}`
+            : "Invalid listing",
+        }),
+      );
+      return true;
+    }
+    const { listing } = built;
+    scheduleIntegrationsReload();
+
+    optIn.respond(res, 200, {
+      domain: listing.domain,
+      claim: listing.claim,
+      listing,
+      fileJson: rankingEntryFile(listing),
+      prUrl: rankingPrUrl(listing),
+      verifyUrl: await verifyUrl(listing),
+    });
+    return true;
+  }
+
+  if (optOut.match(req.method, pathSegments)) {
+    const parsed = await optOut.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!(await ensureConfigAdmin(req, res, "config.write.any"))) return true;
+    const listing = await storedListing();
+    await setEnabled(false);
+    if (listing) emitOptedOut(listing.domain);
+    scheduleIntegrationsReload();
+    optOut.respond(res, 200, {
+      enabled: false,
+      leaveUrl: listing ? rankingLeaveUrl(listing.domain) : null,
+    });
+    return true;
+  }
+
+  return false;
+}