@openparachute/agent 0.1.0

package/web/ui/src/lib/auth.test.ts

@@ -0,0 +1,139 @@
+/**
+ * auth.ts unit tests. Today's surface is the localStorage / sessionStorage
+ * key migration from the paraclaw-era prefix to `parachute-agent.*`. Existing
+ * 0.0.x operators have cached discovery + DCR client_id + tokens under the
+ * old prefix; without migration their first reload after upgrading to
+ * 0.1.0 silently re-runs OAuth + leaves a stale client row on the hub.
+ *
+ * Tracked in parachute-agent#108. The migration is meant to be called once
+ * at SPA bootstrap (in main.tsx) before anything else touches storage.
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { migrateLegacyAuthKeys } from './auth.ts';
+
+// jsdom's Storage in this vitest config doesn't reliably expose the full
+// Storage prototype methods (the `--localstorage-file` warning at runtime
+// hints the underlying impl is a partial). Install a Map-backed fake on
+// the global so the migration helper sees a real-feeling Storage surface.
+function makeStorageFake(): Storage {
+  const m = new Map<string, string>();
+  return {
+    get length() {
+      return m.size;
+    },
+    key(i: number): string | null {
+      return Array.from(m.keys())[i] ?? null;
+    },
+    getItem(k: string): string | null {
+      return m.has(k) ? (m.get(k) as string) : null;
+    },
+    setItem(k: string, v: string): void {
+      m.set(k, String(v));
+    },
+    removeItem(k: string): void {
+      m.delete(k);
+    },
+    clear(): void {
+      m.clear();
+    },
+  };
+}
+
+beforeEach(() => {
+  vi.stubGlobal('localStorage', makeStorageFake());
+  vi.stubGlobal('sessionStorage', makeStorageFake());
+});
+
+describe('migrateLegacyAuthKeys', () => {
+  it('migrates the static localStorage keys (discovery + setup wizard)', () => {
+    localStorage.setItem('paraclaw.discovery', '{"hubOrigin":"http://hub"}');
+    localStorage.setItem('paraclaw.setupWizard.v2', '{"furthestStep":"prereqs"}');
+
+    migrateLegacyAuthKeys();
+
+    expect(localStorage.getItem('parachute-agent.discovery')).toBe('{"hubOrigin":"http://hub"}');
+    expect(localStorage.getItem('parachute-agent.setupWizard.v2')).toBe('{"furthestStep":"prereqs"}');
+    expect(localStorage.getItem('paraclaw.discovery')).toBeNull();
+    expect(localStorage.getItem('paraclaw.setupWizard.v2')).toBeNull();
+  });
+
+  it('migrates the in-flight OAuth flow key from sessionStorage', () => {
+    sessionStorage.setItem('paraclaw.flow', '{"verifier":"v","state":"s"}');
+
+    migrateLegacyAuthKeys();
+
+    expect(sessionStorage.getItem('parachute-agent.flow')).toBe('{"verifier":"v","state":"s"}');
+    expect(sessionStorage.getItem('paraclaw.flow')).toBeNull();
+  });
+
+  it('migrates per-hub-origin client + tokens keys, preserving the suffix', () => {
+    localStorage.setItem('paraclaw.client.http://hub-a', '{"client_id":"a"}');
+    localStorage.setItem('paraclaw.client.http://hub-b', '{"client_id":"b"}');
+    localStorage.setItem('paraclaw.tokens.http://hub-a', '{"access_token":"t-a"}');
+    localStorage.setItem('paraclaw.tokens.http://hub-b', '{"access_token":"t-b"}');
+
+    migrateLegacyAuthKeys();
+
+    expect(localStorage.getItem('parachute-agent.client.http://hub-a')).toBe('{"client_id":"a"}');
+    expect(localStorage.getItem('parachute-agent.client.http://hub-b')).toBe('{"client_id":"b"}');
+    expect(localStorage.getItem('parachute-agent.tokens.http://hub-a')).toBe('{"access_token":"t-a"}');
+    expect(localStorage.getItem('parachute-agent.tokens.http://hub-b')).toBe('{"access_token":"t-b"}');
+    expect(localStorage.getItem('paraclaw.client.http://hub-a')).toBeNull();
+    expect(localStorage.getItem('paraclaw.tokens.http://hub-b')).toBeNull();
+  });
+
+  it('is a no-op when no legacy keys exist (fresh install)', () => {
+    localStorage.setItem('parachute-agent.discovery', '{"hubOrigin":"http://hub"}');
+
+    migrateLegacyAuthKeys();
+
+    expect(localStorage.getItem('parachute-agent.discovery')).toBe('{"hubOrigin":"http://hub"}');
+    expect(localStorage.length).toBe(1);
+  });
+
+  it('is idempotent — repeated calls leave already-migrated state untouched', () => {
+    localStorage.setItem('paraclaw.discovery', '{"hubOrigin":"http://hub"}');
+    localStorage.setItem('paraclaw.tokens.http://hub', '{"access_token":"t"}');
+
+    migrateLegacyAuthKeys();
+    migrateLegacyAuthKeys();
+
+    // Spreading a Storage fake enumerates its method properties, not the
+    // stored data — so a snapshot-equality check would pass regardless of
+    // behavior. Assert the post-state explicitly: legacy keys gone, new
+    // keys hold the original values, and storage holds exactly the two
+    // migrated entries (no orphans, no duplicates).
+    expect(localStorage.getItem('paraclaw.discovery')).toBeNull();
+    expect(localStorage.getItem('paraclaw.tokens.http://hub')).toBeNull();
+    expect(localStorage.getItem('parachute-agent.discovery')).toBe('{"hubOrigin":"http://hub"}');
+    expect(localStorage.getItem('parachute-agent.tokens.http://hub')).toBe('{"access_token":"t"}');
+    expect(localStorage.length).toBe(2);
+  });
+
+  it('drops the stale legacy key when both old and new exist (new wins)', () => {
+    // This shape only happens if something wrote the legacy key after a
+    // prior migration ran — extremely unlikely in production, but the
+    // helper has to be deterministic about which value survives.
+    localStorage.setItem('paraclaw.discovery', '{"hubOrigin":"http://stale"}');
+    localStorage.setItem('parachute-agent.discovery', '{"hubOrigin":"http://current"}');
+
+    migrateLegacyAuthKeys();
+
+    expect(localStorage.getItem('parachute-agent.discovery')).toBe('{"hubOrigin":"http://current"}');
+    expect(localStorage.getItem('paraclaw.discovery')).toBeNull();
+  });
+
+  it('does not touch unrelated paraclaw-prefixed keys outside the OAuth surface', () => {
+    // Defensive: if some other module ever uses a `paraclaw.foo` key, the
+    // OAuth migration shouldn't sweep it. Only the four documented prefixes
+    // and two static keys move.
+    localStorage.setItem('paraclaw.unrelated', 'keep-me');
+    localStorage.setItem('paraclaw.discovery', '{"hubOrigin":"http://hub"}');
+
+    migrateLegacyAuthKeys();
+
+    expect(localStorage.getItem('paraclaw.unrelated')).toBe('keep-me');
+    expect(localStorage.getItem('parachute-agent.discovery')).toBe('{"hubOrigin":"http://hub"}');
+  });
+});

package/web/ui/src/lib/auth.ts

@@ -0,0 +1,348 @@
+/**
+ * OAuth 2.0 client for the Parachute Agent web UI. The hub is the authorization
+ * server (parachute-patterns/patterns/hub-as-issuer.md):
+ *
+ *   1. GET  /api/discovery           — returns `{ hubOrigin }` so the bundle
+ *                                       doesn't bake the origin in.
+ *   2. POST <hub>/oauth/register      — RFC 7591 DCR; we cache the client_id
+ *                                       in localStorage keyed by hub origin.
+ *   3. GET  <hub>/oauth/authorize     — PKCE-S256, redirect-back.
+ *   4. <app>/oauth/callback           — code + state; we exchange for tokens.
+ *   5. POST <hub>/oauth/token         — authorization_code, then refresh_token
+ *                                       on 401 from /api/* before re-login.
+ *
+ * Scopes: `agent:admin agent:write vault:read vault:write`. `agent:admin` is
+ * required for /api/secrets writes + the setup wizard install-channel
+ * step; `agent:write` is the bar for /api/approvals decisions and
+ * /api/sessions/:id/close. The vault scopes anticipate the vault tokens-API
+ * REST endpoint (paraclaw#4 companion vault issue); today the server still
+ * shells out, but minting the user JWT with vault:* now means no re-consent
+ * later.
+ *
+ * Existing users with cached tokens that lack a newly-required scope will
+ * hit 403 with a body like `requires the X scope`. The api.ts wrapper
+ * detects that shape and triggers re-auth (clearTokens + beginLogin) so
+ * upgrades don't strand users behind a manual `localStorage.clear()`.
+ * (paraclaw#33)
+ */
+interface DiscoveryResponse {
+  hubOrigin: string;
+}
+
+interface ClientRecord {
+  client_id: string;
+}
+
+interface TokenSet {
+  access_token: string;
+  refresh_token: string;
+  expires_at: number; // epoch seconds
+}
+
+interface FlowState {
+  verifier: string;
+  state: string;
+  redirect_uri: string;
+  hub_origin: string;
+}
+
+const REQUESTED_SCOPES = "agent:admin agent:write vault:read vault:write";
+const DISCOVERY_KEY = "parachute-agent.discovery";
+const FLOW_KEY = "parachute-agent.flow";
+
+function clientKey(hubOrigin: string): string {
+  return `parachute-agent.client.${hubOrigin}`;
+}
+function tokensKey(hubOrigin: string): string {
+  return `parachute-agent.tokens.${hubOrigin}`;
+}
+
+/**
+ * One-shot migration of the OAuth localStorage / sessionStorage keys from
+ * the paraclaw-era prefix (`paraclaw.*`) to the post-rename prefix
+ * (`parachute-agent.*`). Idempotent — safe to call on every bootstrap.
+ *
+ * Without this, an existing operator hitting 0.1.0 would lose their
+ * cached discovery, registered client_id, and tokens, and get bounced to
+ * the hub for a fresh consent. The DCR client_id is one-shot per origin,
+ * so re-registering would also leave a stale client row on the hub.
+ *
+ * The static keys are migrated by name. The per-hub-origin keys
+ * (`paraclaw.client.<origin>`, `paraclaw.tokens.<origin>`) are
+ * pattern-scanned because we don't know the operator's hub origin until
+ * after we've already read DISCOVERY_KEY — which has its own migration.
+ *
+ * Tracked in parachute-agent#108. Keep this through 0.2.0 then drop;
+ * by then every operator who's going to migrate has hit the SPA at
+ * least once.
+ */
+export function migrateLegacyAuthKeys(): void {
+  if (typeof localStorage === "undefined") return;
+  migrateOneKey(localStorage, "paraclaw.discovery", "parachute-agent.discovery");
+  migrateOneKey(localStorage, "paraclaw.setupWizard.v2", "parachute-agent.setupWizard.v2");
+  migratePrefix(localStorage, "paraclaw.client.", "parachute-agent.client.");
+  migratePrefix(localStorage, "paraclaw.tokens.", "parachute-agent.tokens.");
+  if (typeof sessionStorage !== "undefined") {
+    migrateOneKey(sessionStorage, "paraclaw.flow", "parachute-agent.flow");
+  }
+}
+
+function migrateOneKey(storage: Storage, oldKey: string, newKey: string): void {
+  const oldVal = storage.getItem(oldKey);
+  if (oldVal === null) return;
+  // If both exist (rare — only happens if migration ran, then old was
+  // re-set somehow), the new one wins as the already-migrated truth.
+  if (storage.getItem(newKey) === null) {
+    storage.setItem(newKey, oldVal);
+  }
+  storage.removeItem(oldKey);
+}
+
+function migratePrefix(storage: Storage, oldPrefix: string, newPrefix: string): void {
+  // Snapshot keys before mutating — iterating Object.keys while removing
+  // is implementation-defined.
+  const stale: string[] = [];
+  for (let i = 0; i < storage.length; i++) {
+    const k = storage.key(i);
+    if (k && k.startsWith(oldPrefix)) stale.push(k);
+  }
+  for (const oldKey of stale) {
+    const suffix = oldKey.slice(oldPrefix.length);
+    migrateOneKey(storage, oldKey, `${newPrefix}${suffix}`);
+  }
+}
+
+function readJson<T>(storage: Storage, key: string): T | null {
+  const raw = storage.getItem(key);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    storage.removeItem(key);
+    return null;
+  }
+}
+
+function writeJson(storage: Storage, key: string, value: unknown): void {
+  storage.setItem(key, JSON.stringify(value));
+}
+
+function getRedirectUri(): string {
+  // Vite's BASE_URL has a trailing slash (`/` or `/agent/`), so the join
+  // yields `http://host/oauth/callback` or `http://host/agent/oauth/callback`.
+  return `${window.location.origin}${import.meta.env.BASE_URL}oauth/callback`;
+}
+
+async function getDiscovery(): Promise<DiscoveryResponse> {
+  const cached = readJson<DiscoveryResponse>(localStorage, DISCOVERY_KEY);
+  if (cached) return cached;
+  // Fetch raw — discovery is unauthenticated, and routing it through the API
+  // wrapper would create a bootstrap dep cycle (api ↔ auth). Mount-aware:
+  // BASE_URL prepended so the request hits parachute-agent under /agent/ on
+  // tailnet rather than the hub origin's root (which 404s on /api/discovery).
+  const url = `${import.meta.env.BASE_URL.replace(/\/$/, "")}/api/discovery`;
+  const res = await fetch(url, { headers: { accept: "application/json" } });
+  if (!res.ok) throw new Error(`${url} failed: ${res.status}`);
+  const fresh = (await res.json()) as DiscoveryResponse;
+  writeJson(localStorage, DISCOVERY_KEY, fresh);
+  return fresh;
+}
+
+async function ensureClient(hubOrigin: string): Promise<string> {
+  const cached = readJson<ClientRecord>(localStorage, clientKey(hubOrigin));
+  if (cached?.client_id) return cached.client_id;
+  const redirectUri = getRedirectUri();
+  const res = await fetch(`${hubOrigin}/oauth/register`, {
+    method: "POST",
+    headers: { "content-type": "application/json", accept: "application/json" },
+    body: JSON.stringify({
+      redirect_uris: [redirectUri],
+      scope: REQUESTED_SCOPES,
+      client_name: "Parachute Agent web UI",
+      token_endpoint_auth_method: "none",
+    }),
+  });
+  if (!res.ok) {
+    throw new Error(`hub /oauth/register failed: ${res.status} ${await res.text()}`);
+  }
+  const body = (await res.json()) as { client_id: string };
+  writeJson(localStorage, clientKey(hubOrigin), { client_id: body.client_id });
+  return body.client_id;
+}
+
+function randomBytes(n: number): Uint8Array {
+  const out = new Uint8Array(n);
+  crypto.getRandomValues(out);
+  return out;
+}
+
+function base64UrlEncode(bytes: Uint8Array): string {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+async function sha256(input: string): Promise<Uint8Array> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+  return new Uint8Array(digest);
+}
+
+async function makePkcePair(): Promise<{ verifier: string; challenge: string }> {
+  const verifier = base64UrlEncode(randomBytes(32));
+  const challenge = base64UrlEncode(await sha256(verifier));
+  return { verifier, challenge };
+}
+
+/**
+ * Kick off the OAuth dance. Top-level navigation; never returns.
+ *
+ * `extraScopes` lets a caller request narrow per-vault scopes
+ * (`vault:<name>:admin`) on top of `REQUESTED_SCOPES`. The vault detail
+ * page (paraclaw#38 Phase 3) uses this when the operator's existing JWT
+ * doesn't carry admin for the targeted vault — re-running the OAuth flow
+ * with the narrow scope appended produces a JWT that does, without
+ * widening every other operator's grant. Duplicates are de-duped so the
+ * hub's consent screen doesn't show the same scope twice.
+ */
+export async function beginLogin(extraScopes: string[] = []): Promise<never> {
+  const { hubOrigin } = await getDiscovery();
+  const clientId = await ensureClient(hubOrigin);
+  const { verifier, challenge } = await makePkcePair();
+  const state = base64UrlEncode(randomBytes(16));
+  const redirectUri = getRedirectUri();
+  const flow: FlowState = {
+    verifier,
+    state,
+    redirect_uri: redirectUri,
+    hub_origin: hubOrigin,
+  };
+  writeJson(sessionStorage, FLOW_KEY, flow);
+  const scopes = new Set(REQUESTED_SCOPES.split(/\s+/).filter(Boolean));
+  for (const s of extraScopes) {
+    const trimmed = s.trim();
+    if (trimmed) scopes.add(trimmed);
+  }
+  const u = new URL(`${hubOrigin}/oauth/authorize`);
+  u.searchParams.set("client_id", clientId);
+  u.searchParams.set("redirect_uri", redirectUri);
+  u.searchParams.set("response_type", "code");
+  u.searchParams.set("scope", Array.from(scopes).join(" "));
+  u.searchParams.set("code_challenge", challenge);
+  u.searchParams.set("code_challenge_method", "S256");
+  u.searchParams.set("state", state);
+  window.location.replace(u.toString());
+  // Block until navigation actually happens — callers expect this never
+  // returns control.
+  return new Promise<never>(() => {});
+}
+
+/**
+ * Exchange `code` for tokens. Throws on any failure (state mismatch, hub
+ * error, missing flow). Callers should catch + show the error and offer a
+ * retry that calls beginLogin().
+ */
+export async function handleCallback(params: URLSearchParams): Promise<void> {
+  const flow = readJson<FlowState>(sessionStorage, FLOW_KEY);
+  if (!flow) throw new Error("no in-flight OAuth flow — restart sign-in");
+  sessionStorage.removeItem(FLOW_KEY);
+  const err = params.get("error");
+  if (err) {
+    throw new Error(`hub returned OAuth error: ${err} — ${params.get("error_description") ?? ""}`);
+  }
+  const code = params.get("code");
+  const state = params.get("state");
+  if (!code || !state) throw new Error("hub callback missing code or state");
+  if (state !== flow.state) throw new Error("OAuth state mismatch — possible CSRF");
+  const clientId = readJson<ClientRecord>(localStorage, clientKey(flow.hub_origin))?.client_id;
+  if (!clientId) throw new Error("client registration missing — restart sign-in");
+  const tokens = await postToken(flow.hub_origin, {
+    grant_type: "authorization_code",
+    code,
+    client_id: clientId,
+    redirect_uri: flow.redirect_uri,
+    code_verifier: flow.verifier,
+  });
+  storeTokens(flow.hub_origin, tokens);
+}
+
+async function postToken(
+  hubOrigin: string,
+  form: Record<string, string>,
+): Promise<{ access_token: string; refresh_token: string; expires_in: number }> {
+  const body = new URLSearchParams();
+  for (const [k, v] of Object.entries(form)) body.set(k, v);
+  const res = await fetch(`${hubOrigin}/oauth/token`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/x-www-form-urlencoded",
+      accept: "application/json",
+    },
+    body: body.toString(),
+  });
+  if (!res.ok) {
+    const txt = await res.text();
+    throw new Error(`hub /oauth/token failed: ${res.status} ${txt}`);
+  }
+  return (await res.json()) as { access_token: string; refresh_token: string; expires_in: number };
+}
+
+function storeTokens(
+  hubOrigin: string,
+  t: { access_token: string; refresh_token: string; expires_in: number },
+): void {
+  const expires_at = Math.floor(Date.now() / 1000) + t.expires_in;
+  const ts: TokenSet = {
+    access_token: t.access_token,
+    refresh_token: t.refresh_token,
+    expires_at,
+  };
+  writeJson(localStorage, tokensKey(hubOrigin), ts);
+}
+
+function readTokens(hubOrigin: string): TokenSet | null {
+  return readJson<TokenSet>(localStorage, tokensKey(hubOrigin));
+}
+
+/**
+ * Returns the current access token if we have one for the cached hub
+ * origin, regardless of expiry — the API wrapper handles 401-refresh. If
+ * we don't even have discovery yet, returns null (caller should prompt
+ * login).
+ */
+export function getAccessToken(): string | null {
+  const disc = readJson<DiscoveryResponse>(localStorage, DISCOVERY_KEY);
+  if (!disc) return null;
+  return readTokens(disc.hubOrigin)?.access_token ?? null;
+}
+
+/**
+ * Refresh the access token using the stored refresh token. Returns the
+ * new access token, or null if refresh isn't possible (no refresh, hub
+ * rejected). Caller should fall back to beginLogin() on null.
+ */
+export async function refreshAccessToken(): Promise<string | null> {
+  const disc = readJson<DiscoveryResponse>(localStorage, DISCOVERY_KEY);
+  if (!disc) return null;
+  const tokens = readTokens(disc.hubOrigin);
+  if (!tokens?.refresh_token) return null;
+  const clientId = readJson<ClientRecord>(localStorage, clientKey(disc.hubOrigin))?.client_id;
+  if (!clientId) return null;
+  try {
+    const fresh = await postToken(disc.hubOrigin, {
+      grant_type: "refresh_token",
+      refresh_token: tokens.refresh_token,
+      client_id: clientId,
+    });
+    storeTokens(disc.hubOrigin, fresh);
+    return fresh.access_token;
+  } catch {
+    return null;
+  }
+}
+
+/** Drop tokens; keeps discovery + client_id (DCR is one-shot per origin). */
+export function clearTokens(): void {
+  const disc = readJson<DiscoveryResponse>(localStorage, DISCOVERY_KEY);
+  if (!disc) return;
+  localStorage.removeItem(tokensKey(disc.hubOrigin));
+}

package/web/ui/src/lib/channel-adapters.ts

@@ -0,0 +1,136 @@
+/**
+ * Channel adapter descriptors.
+ *
+ * The /channels/new page and the setup wizard both need the same handful of
+ * facts about each supported adapter: how to validate a bot token, what the
+ * platform_id looks like, what to ask the operator for, and where to send
+ * them for token-procurement docs. This table is the single source of those
+ * facts so a new adapter (slack, whatsapp, …) lands as a one-file addition,
+ * not a sprawl of switch statements across components.
+ *
+ * Two arrays:
+ *   SUPPORTED_ADAPTERS   — currently installable on the trunk install
+ *   COMING_SOON_ADAPTERS — visible in the picker as "coming soon" affordances
+ *                          per design 2026-04-30 §"adapter parity"
+ *
+ * If you add a row here you also need to extend the wire-channel + validator
+ * routes server-side; the descriptor is the *UI* contract, not the schema.
+ */
+import {
+  testDiscordToken,
+  testTelegramToken,
+  type DiscordIdentity,
+  type TelegramIdentity,
+} from './api.ts';
+
+export type ChannelAdapter = 'discord' | 'telegram';
+
+export interface ResolvedIdentity {
+  /** Bot's user id at the upstream platform, normalized to string. */
+  id: string;
+  /** Bot's @-handle / username for "DM @<bot>" copy. */
+  username: string;
+}
+
+/**
+ * What the operator needs to provide on the new-channel page in addition to
+ * the bot token. Today only Telegram has a non-empty list (the operator's
+ * own user id is needed because Telegram DMs are chat-routed).
+ */
+export interface OperatorInputField {
+  key: 'operatorUserId';
+  label: string;
+  hint: string;
+  /** Where to send the operator to find this value, if anywhere. */
+  helpHref?: string;
+  /** Pattern for client-side validation (kept loose; server is the gate). */
+  pattern: RegExp;
+}
+
+export interface ChannelAdapterDescriptor {
+  key: ChannelAdapter;
+  label: string;
+  blurb: string;
+  /** Path on the upstream platform's API the validator hits — for display copy. */
+  upstreamProbePath: string;
+  /** Where the operator gets the bot token. */
+  tokenHelp: { title: string; href: string };
+  /** Validate a token; throws on rejection. The body in the throw carries the user-facing error. */
+  validate: (token: string) => Promise<ResolvedIdentity>;
+  /** Adapter-specific extra fields the wiring step needs from the operator. */
+  operatorFields: OperatorInputField[];
+  /**
+   * Build the messaging-group `platform_id` shown as a preview before wiring.
+   * `botUserId` is the validate() id; `operatorUserId` is from operatorFields.
+   */
+  platformIdPreview: (args: { botUserId: string | null; operatorUserId: string | null }) => string;
+  /**
+   * The id that gets POST-ed to /groups/:folder/wire-channel as `botUserId`.
+   * Discord uses the bot's snowflake (DMs are addressee-routed). Telegram
+   * uses the OPERATOR's user id (DMs are chat-routed). Both ride the same
+   * wire field name — the server's wire-channel.ts knows which one is which
+   * based on `channelType`.
+   */
+  wireIdFor: (args: { botUserId: string | null; operatorUserId: string | null }) => string | null;
+}
+
+export interface ComingSoonAdapter {
+  key: string;
+  label: string;
+  blurb: string;
+}
+
+export const SUPPORTED_ADAPTERS: ChannelAdapterDescriptor[] = [
+  {
+    key: 'telegram',
+    label: 'Telegram',
+    blurb: 'Easiest first run — BotFather + @userinfobot, ~1 minute.',
+    upstreamProbePath: '/getMe',
+    tokenHelp: { title: '@BotFather → /newbot', href: 'https://t.me/BotFather' },
+    validate: async (token: string): Promise<ResolvedIdentity> => {
+      const r: { identity: TelegramIdentity } = await testTelegramToken(token);
+      return { id: String(r.identity.id), username: r.identity.username };
+    },
+    operatorFields: [
+      {
+        key: 'operatorUserId',
+        label: 'Telegram admin user ID',
+        hint:
+          'The user this bot serves — usually you. Telegram routes DMs by chat id (= your user id); ' +
+          'this is the user whose DMs reach your agent. New here? DM @userinfobot to get your ID.',
+        helpHref: 'https://t.me/userinfobot',
+        pattern: /^[0-9]+$/,
+      },
+    ],
+    platformIdPreview: ({ operatorUserId }) =>
+      `telegram:${operatorUserId ?? '(no user id)'}`,
+    wireIdFor: ({ operatorUserId }) => operatorUserId,
+  },
+  {
+    key: 'discord',
+    label: 'Discord',
+    blurb: 'DM your bot or @-mention it in a server.',
+    upstreamProbePath: '/users/@me',
+    tokenHelp: {
+      title: 'Discord developer portal → Bot → Token',
+      href: 'https://discord.com/developers/applications',
+    },
+    validate: async (token: string): Promise<ResolvedIdentity> => {
+      const r: { identity: DiscordIdentity } = await testDiscordToken(token);
+      return { id: r.identity.id, username: r.identity.username };
+    },
+    operatorFields: [],
+    platformIdPreview: ({ botUserId }) => `discord:@me:${botUserId ?? '(no bot id)'}`,
+    wireIdFor: ({ botUserId }) => botUserId,
+  },
+];
+
+export const COMING_SOON_ADAPTERS: ComingSoonAdapter[] = [
+  { key: 'slack', label: 'Slack', blurb: 'Workspace bot — coming soon.' },
+  { key: 'whatsapp', label: 'WhatsApp', blurb: 'Cloud API — coming soon.' },
+  { key: 'teams', label: 'Microsoft Teams', blurb: 'Coming soon.' },
+];
+
+export function findAdapter(key: string): ChannelAdapterDescriptor | null {
+  return SUPPORTED_ADAPTERS.find((a) => a.key === key) ?? null;
+}

package/web/ui/src/main.tsx

@@ -0,0 +1,19 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { BrowserRouter } from "react-router-dom";
+import { App } from "./App.tsx";
+import { migrateLegacyAuthKeys } from "./lib/auth.ts";
+import "./styles.css";
+
+migrateLegacyAuthKeys();
+
+const root = document.getElementById("root");
+if (!root) throw new Error("#root not found");
+
+createRoot(root).render(
+  <StrictMode>
+    <BrowserRouter basename={import.meta.env.BASE_URL.replace(/\/$/, "")}>
+      <App />
+    </BrowserRouter>
+  </StrictMode>,
+);