@openparachute/agent 0.1.2 → 0.2.0

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

@@ -1,405 +0,0 @@
-/**
- * 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.
- *
- * Bootstrap scopes: `agent:admin agent: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 agent SPA is self-contained — vault is one
- * per-agent-group action, not the SPA's identity, so vault scopes are
- * NOT requested at bootstrap. Per-vault flows extend with `extraScopes`
- * on `beginLogin([\`vault:\${name}:admin\`])` (see line 199-200) — this is
- * the paraclaw#56 re-consent pattern, request-on-demand. (paraclaw#136)
- *
- * Vault listing for pickers reads `/.well-known/parachute.json` (public,
- * no scope needed); per-vault token-API access enforces `vault:<name>:admin`
- * on the vault side regardless of what the bootstrap JWT carries.
- *
- * 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;
-  /**
-   * The redirect_uri the client_id was registered with. Hub-side, the
-   * DCR row is bound to the original redirect_uri — sending an authorize
-   * request with a different redirect_uri (e.g. after a mount-path
-   * change like `/claw/` → `/agent/`) fails the hub's redirect_uri
-   * check and the operator sees a hub error instead of the consent
-   * screen. Stash this alongside the client_id so bootstrap can detect
-   * the mismatch and re-register a fresh client_id with the new path.
-   * (paraclaw#138)
-   */
-  redirect_uri: 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;
-}
-
-export const REQUESTED_SCOPES = "agent:admin agent: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;
-}
-
-export async function ensureClient(hubOrigin: string): Promise<string> {
-  const redirectUri = getRedirectUri();
-  const cached = readJson<ClientRecord>(localStorage, clientKey(hubOrigin));
-  // Cache hit only if BOTH client_id is present AND the cached
-  // redirect_uri matches the current bootstrap's redirect_uri. A mismatch
-  // means the SPA's mount path changed (e.g. `/claw/` → `/agent/`) and
-  // the hub-side DCR row is bound to the old redirect_uri — re-using the
-  // stale client_id would fail the hub's redirect_uri check on
-  // /oauth/authorize. Treat as cache-miss → re-register a fresh client.
-  // Records written before this guard landed lack `redirect_uri`; treat
-  // those as miss so the migration self-heals. (paraclaw#138)
-  if (cached?.client_id && cached.redirect_uri === redirectUri) {
-    return cached.client_id;
-  }
-  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,
-    redirect_uri: redirectUri,
-  });
-  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 u = buildAuthorizeUrl({
-    hubOrigin,
-    clientId,
-    redirectUri,
-    challenge,
-    state,
-    extraScopes,
-  });
-  window.location.replace(u.toString());
-  // Block until navigation actually happens — callers expect this never
-  // returns control.
-  return new Promise<never>(() => {});
-}
-
-/**
- * Build the `/oauth/authorize` URL. Pure — no side effects, no storage
- * reads, no network. Exported so tests can pin the scope string and the
- * extraScopes append behavior without mocking `window.location.replace`.
- *
- * `extraScopes` are appended after `REQUESTED_SCOPES` and de-duped, so a
- * caller passing a scope already in REQUESTED_SCOPES doesn't double it on
- * the consent screen.
- */
-export function buildAuthorizeUrl(opts: {
-  hubOrigin: string;
-  clientId: string;
-  redirectUri: string;
-  challenge: string;
-  state: string;
-  extraScopes?: string[];
-}): URL {
-  const scopes = new Set(REQUESTED_SCOPES.split(/\s+/).filter(Boolean));
-  for (const s of opts.extraScopes ?? []) {
-    const trimmed = s.trim();
-    if (trimmed) scopes.add(trimmed);
-  }
-  const u = new URL(`${opts.hubOrigin}/oauth/authorize`);
-  u.searchParams.set("client_id", opts.clientId);
-  u.searchParams.set("redirect_uri", opts.redirectUri);
-  u.searchParams.set("response_type", "code");
-  u.searchParams.set("scope", Array.from(scopes).join(" "));
-  u.searchParams.set("code_challenge", opts.challenge);
-  u.searchParams.set("code_challenge_method", "S256");
-  u.searchParams.set("state", opts.state);
-  return u;
-}
-
-/**
- * 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

@@ -1,136 +0,0 @@
-/**
- * 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

@@ -1,19 +0,0 @@
-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>,
-);