@plosson/agentio 0.7.5 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plosson/agentio",
-  "version": "0.7.5",
+  "version": "0.8.0",
   "description": "CLI for LLM agents to interact with communication and tracking services",
   "type": "module",
   "license": "MIT",

package/src/server/http.test.ts

@@ -173,9 +173,10 @@ describe('handleRequest — /health adversarial paths', () => {
     expect(res.status).toBe(404);
   });
 
-  test('GET / (root) → 404', async () => {
+  test('GET / (root) → 200 setup page (login form)', async () => {
     const res = await dispatch(req('/'));
-    expect(res.status).toBe(404);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toBe('text/html; charset=utf-8');
   });
 });
 

package/src/server/http.ts

@@ -1,6 +1,7 @@
 import { handleMcpRequest } from './mcp-http';
 import type { OAuthStore } from './oauth-store';
 import { requireBearer, routeOAuth } from './oauth';
+import { routeSetup } from './setup-page';
 
 /**
  * Context passed to every fetch handler invocation. Built once at boot in
@@ -35,6 +36,11 @@ export async function handleRequest(
     return jsonResponse({ ok: true });
   }
 
+  // Root setup page — operator-facing UI (API-key gated) for picking
+  // profiles and generating the MCP URL.
+  const setupResponse = await routeSetup(req, ctx);
+  if (setupResponse) return setupResponse;
+
   // OAuth metadata + endpoints (Phase 3c onward).
   const oauthResponse = await routeOAuth(req, ctx);
   if (oauthResponse) return oauthResponse;

package/src/server/setup-page.test.ts

@@ -0,0 +1,325 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, mock, test } from 'bun:test';
+import { createHmac } from 'crypto';
+
+/**
+ * Tests for the operator-facing setup page at `/`. Covers:
+ *   - unauthenticated GET renders the login form
+ *   - POST credential validation (bad key → 401; good key → 302 + Set-Cookie)
+ *   - cookie attributes (HttpOnly, SameSite, Path, Max-Age; Secure only on https)
+ *   - HMAC-cookie authentication: valid cookie → profiles page; stale cookie → login form
+ *   - only services with ≥1 configured profile appear on the page
+ *   - embedded JSON payload escapes `<` to avoid `</script>` injection
+ *
+ * The page calls `listProfiles()` from ../config/config-manager, which reads
+ * the real ~/.config/agentio/config.json. Bun caches `os.homedir()` at
+ * process start, so HOME overrides don't work here — instead we use
+ * `mock.module` to replace `listProfiles` with a controllable stub.
+ */
+
+const API_KEY = 'srv_test_setup_page_api_key';
+const COOKIE_NAME = 'agentio_setup';
+const COOKIE_MAGIC = 'agentio-setup-v1';
+
+function expectedCookieValue(apiKey: string): string {
+  return createHmac('sha256', apiKey).update(COOKIE_MAGIC).digest('base64url');
+}
+
+interface FakeProfile {
+  service: string;
+  profiles: { name: string; readOnly?: boolean }[];
+}
+
+// Mutable container the mock consults on each call.
+let currentProfiles: FakeProfile[] = [];
+
+function setProfiles(fixture: Record<string, string[]>): void {
+  currentProfiles = Object.entries(fixture).map(([service, names]) => ({
+    service,
+    profiles: names.map((n) => ({ name: n })),
+  }));
+}
+
+type HandleRequest = (typeof import('./http'))['handleRequest'];
+type CreateOAuthStore = (typeof import('./oauth-store'))['createOAuthStore'];
+type ServerContext = import('./http').ServerContext;
+
+let handleRequest: HandleRequest;
+let createOAuthStore: CreateOAuthStore;
+let ctx: ServerContext;
+
+beforeAll(async () => {
+  // Load the real config-manager first so we can preserve every export
+  // other modules in the graph depend on (CONFIG_DIR, loadConfig, etc.),
+  // then override ONLY listProfiles with a controllable stub. This has
+  // to happen BEFORE the module-under-test is imported — once './http'
+  // loads, the dependency is bound.
+  const realConfig = await import('../config/config-manager');
+  mock.module('../config/config-manager', () => ({
+    ...realConfig,
+    listProfiles: async (service?: string) => {
+      if (service) {
+        return currentProfiles.filter((s) => s.service === service);
+      }
+      return currentProfiles;
+    },
+  }));
+
+  ({ handleRequest } = await import('./http'));
+  ({ createOAuthStore } = await import('./oauth-store'));
+  ctx = {
+    apiKey: API_KEY,
+    oauthStore: createOAuthStore({ save: async () => {} }),
+  };
+});
+
+beforeEach(() => {
+  currentProfiles = [];
+});
+
+afterEach(() => {
+  currentProfiles = [];
+});
+
+function req(
+  method: string,
+  path: string,
+  init: { cookie?: string; xfProto?: string; body?: string; contentType?: string } = {}
+): Request {
+  const headers = new Headers();
+  if (init.cookie) headers.set('cookie', init.cookie);
+  if (init.xfProto) headers.set('x-forwarded-proto', init.xfProto);
+  if (init.contentType) headers.set('content-type', init.contentType);
+  return new Request(`http://localhost:9999${path}`, {
+    method,
+    headers,
+    body: init.body,
+  });
+}
+
+function formBody(fields: Record<string, string>): string {
+  return new URLSearchParams(fields).toString();
+}
+
+const FORM = 'application/x-www-form-urlencoded';
+
+/* ------------------------------------------------------------------ */
+/* unauthenticated GET                                                 */
+/* ------------------------------------------------------------------ */
+
+describe('GET / — unauthenticated', () => {
+  test('renders HTML login form with 200', async () => {
+    const res = await handleRequest(req('GET', '/'), ctx);
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toBe('text/html; charset=utf-8');
+    const html = await res.text();
+    expect(html).toContain('<title>agentio MCP setup</title>');
+    expect(html).toContain('name="api_key"');
+    expect(html).toContain('type="password"');
+    expect(html).toContain('action="/"');
+  });
+
+  test('does NOT set a cookie on the login form render', async () => {
+    const res = await handleRequest(req('GET', '/'), ctx);
+    expect(res.headers.get('set-cookie')).toBeNull();
+  });
+
+  test('does NOT leak profile data to an unauthenticated caller', async () => {
+    setProfiles({ gmail: ['work-secret', 'personal-secret'] });
+    const res = await handleRequest(req('GET', '/'), ctx);
+    const html = await res.text();
+    expect(html).not.toContain('work-secret');
+    expect(html).not.toContain('personal-secret');
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* POST login                                                          */
+/* ------------------------------------------------------------------ */
+
+describe('POST / — login', () => {
+  test('missing api_key → 401 with error message, no cookie', async () => {
+    const res = await handleRequest(
+      req('POST', '/', { contentType: FORM, body: formBody({}) }),
+      ctx
+    );
+    expect(res.status).toBe(401);
+    expect(await res.text()).toContain('Invalid API key');
+    expect(res.headers.get('set-cookie')).toBeNull();
+  });
+
+  test('wrong api_key → 401 with error message, no cookie', async () => {
+    const res = await handleRequest(
+      req('POST', '/', {
+        contentType: FORM,
+        body: formBody({ api_key: 'not-the-right-key' }),
+      }),
+      ctx
+    );
+    expect(res.status).toBe(401);
+    expect(await res.text()).toContain('Invalid API key');
+    expect(res.headers.get('set-cookie')).toBeNull();
+  });
+
+  test('correct api_key → 302 to /, sets cookie with expected attributes', async () => {
+    const res = await handleRequest(
+      req('POST', '/', {
+        contentType: FORM,
+        body: formBody({ api_key: API_KEY }),
+      }),
+      ctx
+    );
+    expect(res.status).toBe(302);
+    expect(res.headers.get('location')).toBe('/');
+
+    const setCookie = res.headers.get('set-cookie');
+    expect(setCookie).not.toBeNull();
+    expect(setCookie).toContain(`${COOKIE_NAME}=`);
+    expect(setCookie).toContain('HttpOnly');
+    expect(setCookie).toContain('SameSite=Strict');
+    expect(setCookie).toContain('Path=/');
+    expect(setCookie).toMatch(/Max-Age=\d+/);
+
+    // Cookie value is deterministic HMAC(apiKey, magic).
+    expect(setCookie).toContain(expectedCookieValue(API_KEY));
+  });
+
+  test('Secure flag added when x-forwarded-proto=https', async () => {
+    const res = await handleRequest(
+      req('POST', '/', {
+        contentType: FORM,
+        xfProto: 'https',
+        body: formBody({ api_key: API_KEY }),
+      }),
+      ctx
+    );
+    expect(res.headers.get('set-cookie')).toContain('Secure');
+  });
+
+  test('Secure flag NOT added on plain http', async () => {
+    const res = await handleRequest(
+      req('POST', '/', {
+        contentType: FORM,
+        body: formBody({ api_key: API_KEY }),
+      }),
+      ctx
+    );
+    expect(res.headers.get('set-cookie')).not.toContain('Secure');
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* authenticated GET                                                   */
+/* ------------------------------------------------------------------ */
+
+describe('GET / — authenticated (valid cookie)', () => {
+  const validCookie = () => `${COOKIE_NAME}=${expectedCookieValue(API_KEY)}`;
+
+  test('valid cookie → renders the profiles page', async () => {
+    setProfiles({ gmail: ['work'] });
+    const res = await handleRequest(
+      req('GET', '/', { cookie: validCookie() }),
+      ctx
+    );
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    expect(html).toContain('MCP URL');
+    expect(html).toContain('Claude Code command');
+    expect(html).toContain('type="checkbox"');
+  });
+
+  test('only services with ≥1 profile appear (empty services hidden)', async () => {
+    setProfiles({
+      gmail: ['work', 'personal'],
+      slack: ['team'],
+      jira: [], // empty — should NOT render a section
+    });
+    const res = await handleRequest(
+      req('GET', '/', { cookie: validCookie() }),
+      ctx
+    );
+    const html = await res.text();
+    expect(html).toContain('<h2>gmail</h2>');
+    expect(html).toContain('value="gmail:work"');
+    expect(html).toContain('value="gmail:personal"');
+    expect(html).toContain('<h2>slack</h2>');
+    expect(html).toContain('value="slack:team"');
+    expect(html).not.toContain('<h2>jira</h2>');
+  });
+
+  test('no configured profiles → empty-state message, no checkboxes', async () => {
+    setProfiles({});
+    const res = await handleRequest(
+      req('GET', '/', { cookie: validCookie() }),
+      ctx
+    );
+    const html = await res.text();
+    expect(html).toContain('No profiles configured');
+    expect(html).not.toContain('type="checkbox"');
+  });
+
+  test('embedded JSON does not contain `</` that would close the script tag', async () => {
+    setProfiles({ gmail: ['work'] });
+    const res = await handleRequest(
+      req('GET', '/', { cookie: validCookie() }),
+      ctx
+    );
+    const html = await res.text();
+    const marker = 'id="page-data"';
+    const scriptIdx = html.indexOf(marker);
+    expect(scriptIdx).toBeGreaterThan(-1);
+    const open = html.indexOf('>', scriptIdx) + 1;
+    const close = html.indexOf('</script>', open);
+    const dataJson = html.slice(open, close);
+    // No `</` inside the JSON — that's what the `\\u003c` escape guarantees.
+    expect(dataJson).not.toContain('</');
+    // The data block IS the JSON payload with origin set.
+    expect(JSON.parse(dataJson)).toEqual({ origin: 'http://localhost:9999' });
+  });
+
+  test('stale cookie (HMAC of a different api key) → renders login form', async () => {
+    setProfiles({ gmail: ['work'] });
+    const staleCookie = `${COOKIE_NAME}=${expectedCookieValue('some-old-key')}`;
+    const res = await handleRequest(
+      req('GET', '/', { cookie: staleCookie }),
+      ctx
+    );
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    expect(html).toContain('name="api_key"');
+    expect(html).not.toContain('MCP URL');
+  });
+
+  test('malformed cookie header does not crash', async () => {
+    const res = await handleRequest(
+      req('GET', '/', { cookie: 'garbage;;===;' }),
+      ctx
+    );
+    expect(res.status).toBe(200);
+    expect(await res.text()).toContain('name="api_key"');
+  });
+
+  test('origin reflects x-forwarded-host/proto (behind a proxy)', async () => {
+    setProfiles({ gmail: ['work'] });
+    const headers = new Headers();
+    headers.set('cookie', validCookie());
+    headers.set('x-forwarded-proto', 'https');
+    headers.set('x-forwarded-host', 'mcp.example.com');
+    const res = await handleRequest(
+      new Request('http://localhost:9999/', { method: 'GET', headers }),
+      ctx
+    );
+    const html = await res.text();
+    expect(html).toContain('{"origin":"https://mcp.example.com"}');
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* method dispatch                                                     */
+/* ------------------------------------------------------------------ */
+
+describe('method dispatch at /', () => {
+  test('DELETE / falls through to 404 (not handled by setup page)', async () => {
+    const res = await handleRequest(req('DELETE', '/'), ctx);
+    expect(res.status).toBe(404);
+  });
+});

package/src/server/setup-page.ts

@@ -0,0 +1,365 @@
+/**
+ * Setup page served at `/` — lets an operator (who holds the API key) pick
+ * services/profiles and generate the MCP URL + `claude mcp add` snippet.
+ *
+ * Auth model: a small login form asks for the API key, then we set an
+ * HttpOnly cookie whose value is HMAC(apiKey, magic). Every request
+ * re-derives that HMAC and compares. If the key rotates, old cookies
+ * stop validating — no session store needed.
+ */
+
+import { createHmac } from 'crypto';
+
+import { listProfiles } from '../config/config-manager';
+import type { ServerContext } from './http';
+import { constantTimeEquals, getRequestOrigin } from './oauth';
+
+const COOKIE_NAME = 'agentio_setup';
+const COOKIE_MAGIC = 'agentio-setup-v1';
+const COOKIE_MAX_AGE_SECONDS = 60 * 60 * 12; // 12h
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function signApiKey(apiKey: string): string {
+  return createHmac('sha256', apiKey).update(COOKIE_MAGIC).digest('base64url');
+}
+
+function parseCookies(header: string | null): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!header) return out;
+  for (const part of header.split(';')) {
+    const [name, ...rest] = part.trim().split('=');
+    if (!name) continue;
+    try {
+      out[name] = decodeURIComponent(rest.join('='));
+    } catch {
+      out[name] = rest.join('=');
+    }
+  }
+  return out;
+}
+
+function isAuthenticated(req: Request, ctx: ServerContext): boolean {
+  const cookies = parseCookies(req.headers.get('cookie'));
+  const token = cookies[COOKIE_NAME];
+  if (!token) return false;
+  return constantTimeEquals(token, signApiKey(ctx.apiKey));
+}
+
+function isHttps(req: Request): boolean {
+  const forwarded = req.headers.get('forwarded');
+  if (forwarded && /proto=https/i.test(forwarded)) return true;
+  const xfp = req.headers.get('x-forwarded-proto');
+  if (xfp && xfp.toLowerCase() === 'https') return true;
+  return new URL(req.url).protocol === 'https:';
+}
+
+function buildCookieHeader(value: string, secure: boolean): string {
+  const parts = [
+    `${COOKIE_NAME}=${encodeURIComponent(value)}`,
+    'HttpOnly',
+    'SameSite=Strict',
+    'Path=/',
+    `Max-Age=${COOKIE_MAX_AGE_SECONDS}`,
+  ];
+  if (secure) parts.push('Secure');
+  return parts.join('; ');
+}
+
+/* ------------------------------------------------------------------ */
+/* HTML                                                                */
+/* ------------------------------------------------------------------ */
+
+const BASE_CSS = `
+:root { color-scheme: light dark; }
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+  max-width: 640px;
+  margin: 6vh auto;
+  padding: 0 24px;
+  line-height: 1.5;
+}
+h1 { font-size: 1.4rem; margin-bottom: 0.4rem; }
+h2 {
+  font-size: 0.85rem;
+  margin: 0 0 0.5rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: #666;
+}
+.meta { color: #666; font-size: 0.9rem; margin-bottom: 1.5rem; }
+.meta code { font-size: 0.85rem; }
+form { display: flex; flex-direction: column; gap: 0.75rem; }
+label { font-weight: 600; }
+input[type=password], input[type=text], textarea {
+  padding: 0.6rem 0.75rem;
+  font-size: 0.95rem;
+  font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  border: 1px solid #888;
+  border-radius: 6px;
+  width: 100%;
+  box-sizing: border-box;
+  background: transparent;
+  color: inherit;
+}
+textarea { resize: vertical; }
+button {
+  padding: 0.6rem 1rem;
+  font-size: 1rem;
+  font-weight: 600;
+  background: #2563eb;
+  color: white;
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+}
+button:hover { background: #1d4ed8; }
+.error {
+  background: #fee;
+  color: #900;
+  padding: 0.6rem 0.75rem;
+  border-radius: 6px;
+  border: 1px solid #fcc;
+  margin: 0;
+}
+`;
+
+const PROFILES_CSS = `
+.services { display: flex; flex-direction: column; gap: 0.8rem; }
+section.service {
+  border: 1px solid #ddd;
+  border-radius: 6px;
+  padding: 0.6rem 0.9rem;
+}
+label.profile {
+  display: block;
+  font-weight: normal;
+  padding: 0.15rem 0;
+  font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  font-size: 0.9rem;
+  cursor: pointer;
+}
+label.profile input { margin-right: 0.5rem; }
+.output { display: flex; flex-direction: column; gap: 0.4rem; margin-top: 1.4rem; }
+.output label { font-weight: 600; font-size: 0.9rem; }
+.output .row { display: flex; gap: 0.5rem; }
+.output .row input, .output .row textarea { flex: 1; }
+.output button {
+  align-self: flex-start;
+  font-size: 0.85rem;
+  padding: 0.5rem 0.9rem;
+}
+@media (prefers-color-scheme: dark) {
+  section.service { border-color: #444; }
+  input[type=password], input[type=text], textarea { border-color: #555; }
+}
+`;
+
+function loginFormHtml(errorMessage?: string): string {
+  const errorBlock = errorMessage
+    ? `<p class="error">${escapeHtml(errorMessage)}</p>`
+    : '';
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>agentio MCP setup</title>
+<style>${BASE_CSS}</style>
+</head>
+<body>
+<h1>agentio MCP setup</h1>
+<p class="meta">Enter your agentio API key to continue.</p>
+${errorBlock}
+<form method="post" action="/">
+  <label for="api_key">agentio API key</label>
+  <input id="api_key" name="api_key" type="password" autocomplete="off" autofocus required>
+  <button type="submit">Continue</button>
+</form>
+</body>
+</html>`;
+}
+
+interface ServiceProfileList {
+  service: string;
+  profiles: string[];
+}
+
+function profilesPageHtml(origin: string, configured: ServiceProfileList[]): string {
+  const dataJson = JSON.stringify({ origin }).replace(/</g, '\\u003c');
+
+  const sectionsHtml = configured
+    .map((s) => {
+      const items = s.profiles
+        .map((p) => {
+          const value = `${s.service}:${p}`;
+          return `    <label class="profile"><input type="checkbox" name="sp" value="${escapeHtml(
+            value
+          )}"> ${escapeHtml(p)}</label>`;
+        })
+        .join('\n');
+      return `  <section class="service">
+    <h2>${escapeHtml(s.service)}</h2>
+${items}
+  </section>`;
+    })
+    .join('\n');
+
+  const emptyMessage =
+    configured.length === 0
+      ? `<p class="meta">No profiles configured yet. Add some with <code>agentio &lt;service&gt; profile add</code> in the CLI that owns this server.</p>`
+      : '';
+
+  const body =
+    configured.length === 0
+      ? emptyMessage
+      : `<div class="services">
+${sectionsHtml}
+</div>
+<div class="output">
+  <label for="url">MCP URL</label>
+  <div class="row"><input id="url" type="text" readonly></div>
+  <button id="copy-url" type="button">Copy URL</button>
+</div>
+<div class="output">
+  <label for="snippet">Claude Code command</label>
+  <div class="row"><textarea id="snippet" readonly rows="2"></textarea></div>
+  <button id="copy-snippet" type="button">Copy command</button>
+</div>`;
+
+  const script =
+    configured.length === 0
+      ? ''
+      : `<script id="page-data" type="application/json">${dataJson}</script>
+<script>
+(function() {
+  const data = JSON.parse(document.getElementById('page-data').textContent);
+  const urlEl = document.getElementById('url');
+  const snipEl = document.getElementById('snippet');
+  const boxes = document.querySelectorAll('input[type=checkbox][name=sp]');
+
+  function recompute() {
+    const selected = Array.from(boxes).filter(b => b.checked).map(b => b.value);
+    const base = data.origin + '/mcp';
+    const url = selected.length
+      ? base + '?services=' + encodeURIComponent(selected.join(','))
+      : base;
+    urlEl.value = url;
+    snipEl.value = 'claude mcp add --scope local --transport http agentio "' + url + '"';
+  }
+
+  boxes.forEach(b => b.addEventListener('change', recompute));
+  recompute();
+
+  function wireCopy(btnId, targetId) {
+    const btn = document.getElementById(btnId);
+    btn.addEventListener('click', async () => {
+      const target = document.getElementById(targetId);
+      try {
+        await navigator.clipboard.writeText(target.value);
+      } catch {
+        target.select();
+        document.execCommand && document.execCommand('copy');
+      }
+      const old = btn.textContent;
+      btn.textContent = 'Copied!';
+      setTimeout(() => { btn.textContent = old; }, 1200);
+    });
+  }
+  wireCopy('copy-url', 'url');
+  wireCopy('copy-snippet', 'snippet');
+})();
+</script>`;
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>agentio MCP setup</title>
+<style>${BASE_CSS}${PROFILES_CSS}</style>
+</head>
+<body>
+<h1>agentio MCP setup</h1>
+<p class="meta">Tick the profiles to expose, then copy the MCP URL or the <code>claude mcp add</code> command.</p>
+${body}
+${script}
+</body>
+</html>`;
+}
+
+/* ------------------------------------------------------------------ */
+/* handlers                                                            */
+/* ------------------------------------------------------------------ */
+
+async function handleSetupGet(
+  req: Request,
+  ctx: ServerContext
+): Promise<Response> {
+  if (!isAuthenticated(req, ctx)) {
+    return new Response(loginFormHtml(), {
+      status: 200,
+      headers: { 'content-type': 'text/html; charset=utf-8' },
+    });
+  }
+
+  const origin = getRequestOrigin(req);
+  const all = await listProfiles();
+  const configured: ServiceProfileList[] = all
+    .filter((s) => s.profiles.length > 0)
+    .map((s) => ({
+      service: s.service,
+      profiles: s.profiles.map((p) => p.name),
+    }));
+
+  return new Response(profilesPageHtml(origin, configured), {
+    status: 200,
+    headers: { 'content-type': 'text/html; charset=utf-8' },
+  });
+}
+
+async function handleSetupPost(
+  req: Request,
+  ctx: ServerContext
+): Promise<Response> {
+  let form: URLSearchParams;
+  try {
+    const body = await req.text();
+    form = new URLSearchParams(body);
+  } catch {
+    return new Response(loginFormHtml('Could not read form body.'), {
+      status: 400,
+      headers: { 'content-type': 'text/html; charset=utf-8' },
+    });
+  }
+
+  const apiKey = form.get('api_key') ?? '';
+  if (!apiKey || !constantTimeEquals(apiKey, ctx.apiKey)) {
+    return new Response(loginFormHtml('Invalid API key.'), {
+      status: 401,
+      headers: { 'content-type': 'text/html; charset=utf-8' },
+    });
+  }
+
+  const cookie = buildCookieHeader(signApiKey(ctx.apiKey), isHttps(req));
+  return new Response(null, {
+    status: 302,
+    headers: { location: '/', 'set-cookie': cookie },
+  });
+}
+
+export async function routeSetup(
+  req: Request,
+  ctx: ServerContext
+): Promise<Response | null> {
+  const url = new URL(req.url);
+  if (url.pathname !== '/') return null;
+  if (req.method === 'GET') return handleSetupGet(req, ctx);
+  if (req.method === 'POST') return handleSetupPost(req, ctx);
+  return null;
+}