@indemn/cli 1.7.6 → 1.7.8

package/src/mcp/registry.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod/v3';
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ErrorCode, type CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { Environment } from '../sdk/types.js';
 import { NeedsInputError, PERSON_TIMEOUT_MS } from '../core/runtime.js';
@@ -118,7 +118,9 @@ export async function guardDestructive(
         message: `${formText} Proceed?`,
         requestedSchema: {
           type: 'object',
-          properties: { confirm: { type: 'boolean', title: 'Proceed', description: 'Tick (Space), then submit, to make this change.' } },
+          // Ticked already, so approving takes Enter twice in Claude Code (to Accept, then submit), not Space then
+          // Enter. Still one boolean field: Darwin's card reads that as an approval (Approve / Decline).
+          properties: { confirm: { type: 'boolean', title: 'Proceed', description: 'Ticked already: press Enter twice to approve (Space unticks).', default: true } },
           required: ['confirm'],
         },
       }, { timeout: PERSON_TIMEOUT_MS });
@@ -167,10 +169,29 @@ export function createRegistry(
      * and the ids that name nothing (no card is shown for those).
      */
     displayNames?: (args: Args, orgId?: string) => Promise<{ names: Record<string, string>; missing?: string[] }>;
+    /**
+     * Role awareness (display only; the servers still decide): hide tools the person can't use
+     * anywhere, refuse early with the reason when the person's access says so, and name the
+     * person's role when a server refuses.
+     */
+    access?: {
+      visible: (name: string) => boolean;
+      deny: (name: string, orgId?: string) => Promise<string | null>;
+      explain: (orgId?: string) => Promise<string | null>;
+    };
   },
 ) {
   const metaTable = opts.meta ?? TOOL_META;
   const registered: string[] = [];
+  const handles = new Map<string, RegisteredTool>();
+
+  // A refusal from the servers names the person's role (handlers report errors as results).
+  const withRoleNote = async (result: CallToolResult, orgId?: string): Promise<CallToolResult> => {
+    const first = result.isError ? result.content?.[0] : undefined;
+    if (!opts.access || !first || first.type !== 'text' || !/^Error: (Not allowed|Access denied)/.test(first.text)) return result;
+    const role = await opts.access.explain(orgId).catch(() => null);
+    return role ? { ...result, content: [{ ...first, text: `${first.text} ${role}` }, ...result.content.slice(1)] } : result;
+  };
 
   return {
     tool(name: string, description: string, shape: Shape, handler: Handler, extra: { preview?: (args: Args) => Promise<string>; guardWhen?: (args: Args) => Promise<boolean> } = {}): void {
@@ -200,12 +221,18 @@ export function createRegistry(
           .describe('Set true only after the user has agreed to the dry run. Ignored when the host can ask the user itself.');
       }
 
-      server.registerTool(
+      const handle = server.registerTool(
         name,
         { title: meta.title, description, inputSchema, annotations: meta.annotations },
         (async (args: Args) => {
+          let orgId: string | undefined;
           try {
             const org = orgScoped ? await opts.resolveOrg!(typeof args.org_id === 'string' ? args.org_id : undefined) : undefined;
+            orgId = org?.id;
+            const refusal = opts.access ? await opts.access.deny(name, org?.id) : null;
+            if (refusal) {
+              return { content: [{ type: 'text', text: `Error: Not allowed: ${refusal} Nothing was changed.` }], isError: true };
+            }
             return await runWithOrg(org?.id, async () => {
               let confirmedByPerson = false;
               // A guarded tool asks every time, or only when guardWhen says so (e.g. the agent may be live).
@@ -231,7 +258,7 @@ export function createRegistry(
                 if (!gate.proceed) return gate.result;
                 confirmedByPerson = gate.byPerson;
               }
-              const result = await handler(args, { confirmedByPerson });
+              const result = await withRoleNote(await handler(args, { confirmedByPerson }), orgId);
               return withContext(result, { ...(await opts.context()), ...(confirmedByPerson ? { approved_by_person: true } : {}) }, paginate ? { limit: Number(args.limit ?? 50), page: Number(args.page ?? 1) } : undefined);
             });
           } catch (err) {
@@ -240,16 +267,30 @@ export function createRegistry(
               const message = err.message.replace('Choose one with --org <id>', 'Call again with org_id set to one of the ids below');
               return text({ needs_input: true, message, choices: err.choices, to_proceed: 'Ask the user which organization to use, then call again with org_id set to its id.' });
             }
-            const message = err instanceof Error ? err.message : String(err);
+            let message = err instanceof Error ? err.message : String(err);
+            if (opts.access && /^(Not allowed|Access denied)/.test(message)) {
+              const role = await opts.access.explain(orgId).catch(() => null);
+              if (role) message = `${message} ${role}`;
+            }
             return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
           }
         }) as never,
       );
       registered.push(name);
+      handles.set(name, handle);
     },
     names(): string[] {
       return [...registered];
     },
+    /** Show only the tools the person can use somewhere; the host is told when the list changes. */
+    applyVisibility(): void {
+      if (!opts.access) return;
+      for (const [name, handle] of handles) {
+        const show = opts.access.visible(name);
+        if (show && !handle.enabled) handle.enable();
+        else if (!show && handle.enabled) handle.disable();
+      }
+    },
   };
 }
 

package/src/mcp/server.ts

@@ -2,6 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { IndemnClient } from '../sdk/client.js';
 import { registerTools } from './tools.js';
+import { refreshAccess } from '../sdk/access.js';
 import { setAskers, type Askers } from '../core/scope.js';
 import { cliVersion, PERSON_TIMEOUT_MS } from '../core/runtime.js';
 
@@ -75,8 +76,26 @@ export async function startServer(): Promise<void> {
   }, { instructions: SERVER_INSTRUCTIONS });
 
   setAskers(mcpAskers(server));
-  registerTools(server, client);
+  const registry = registerTools(server, client);
+
+  // A host session (INDEMN_TOKEN) may be a different identity than any saved login,
+  // so never hide tools for it — deny() still refuses with the reason when a call
+  // isn't allowed. A saved login hides from what it already knows, before the host
+  // lists tools, then keeps it fresh.
+  const ownLogin = client.getCredential()?.source === 'config';
+  if (ownLogin) registry.applyVisibility();
 
   const transport = new StdioServerTransport();
   await server.connect(transport);
+
+  const refresh = () =>
+    refreshAccess(client).then(
+      () => { if (ownLogin) registry.applyVisibility(); },
+      () => undefined,
+    );
+  void refresh();
+  setInterval(() => void refresh(), ACCESS_REFRESH_MS).unref();
 }
+
+/** How often a running MCP server asks again what the person may do. */
+const ACCESS_REFRESH_MS = 15 * 60_000;

package/src/mcp/tool-meta.ts

@@ -114,7 +114,8 @@ export const TOOL_META: Record<string, ToolMeta> = {
   delete_knowledge_base: { ...destroy('Delete knowledge base'), guard: true, describe: (a) => `This will delete knowledge base ${a.kb_id} with all its sources and vectors.` },
   list_kb_data: read('List knowledge base entries'),
   add_kb_data: { ...write('Add knowledge base entry'), guard: true, describe: (a) => `This will add an entry to knowledge base ${a.kb_id}; agents using it answer from it at once.` },
-  scrape_url: { ...write('Scrape a website into a knowledge base', { openWorldHint: true }), guard: true, describe: (a) => `This will crawl ${a.url} into knowledge base ${a.kb_id}; agents using it answer from it once it is imported.` },
+  // The approval says which crawl it is: a whole-site crawl stops at kb-service's default of 100 pages.
+  scrape_url: { ...write('Scrape a website into a knowledge base', { openWorldHint: true }), guard: true, describe: (a) => `${a.crawl_mode === 'selected' ? `This will import only the page ${a.url}` : `This will crawl the whole site from ${a.url} (up to 100 pages)`} into knowledge base ${a.kb_id}; agents using it answer from it once it is imported.` },
   upload_kb_file: { ...write('Upload file to knowledge base'), guard: true, describe: (a) => `This will upload ${a.file_path} into knowledge base ${a.kb_id}; agents using it answer from it once it is imported.` },
   update_kb_data: {
     ...write('Update knowledge base entry', { idempotentHint: true }),

package/src/mcp/tools.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod/v3';
+import { currentAccess, orgDenial, refreshAccess, roleIn, usableSomewhere } from '../sdk/access.js';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { IndemnClient } from '../sdk/client.js';
 import { AgentInsightsSDK, AgentsSDK } from '../sdk/agents.js';
@@ -168,8 +169,22 @@ const skillDefinition = z.preprocess(parseJsonText, z.object({
 }).passthrough());
 
 export function registerTools(server: McpServer, client: IndemnClient): Registry {
+  // Role awareness: the folder's linked org (or INDEMN_ORG_ID) narrows what counts; otherwise any org.
+  const orgInView = () => process.env.INDEMN_ORG_ID || client.getLink()?.org_id || undefined;
   const reg = createRegistry(server, {
     context: () => client.getResultContext(),
+    access: {
+      visible: (name) => usableSomewhere(name, currentAccess(client), orgInView()),
+      // Refuse early only when the saved access still says no after asking again (it may be stale).
+      deny: async (name, orgId) => {
+        if (!orgDenial(name, currentAccess(client), orgId)) return null;
+        return orgDenial(name, await refreshAccess(client), orgId);
+      },
+      explain: async (orgId) => {
+        const role = roleIn((await refreshAccess(client)) ?? currentAccess(client), orgId);
+        return role ? `Your role: ${role}.` : null;
+      },
+    },
     // Each call decides its own org; an answer given once is not reused for the next call.
     resolveOrg: (explicit) => client.resolveOrg(explicit, { cache: false }),
     // The person approves a change by names: look up the ids the call names.
@@ -1070,16 +1085,12 @@ export function registerTools(server: McpServer, client: IndemnClient): Registry
       kb_id: z.string().describe('The knowledge base ID'),
       question: z.string().optional().describe('FAQ question'),
       answer: z.string().optional().describe('FAQ answer'),
-      source_url: z.string().optional().describe('Source URL (initiates scraping via import endpoint)'),
       content: z.string().optional().describe('Raw content'),
     },
     async (args) => {
       try {
+        // A website goes through scrape_url, where the person chooses the whole site or one page.
         const { kb_id, ...input } = args;
-        if (input.source_url) {
-          const result = await kb.scrapeUrl(kb_id, input.source_url as string);
-          return success(result);
-        }
         const result = await kb.addDataSource(kb_id, input);
         return success(result);
       } catch (err) { return error(err); }
@@ -1088,11 +1099,11 @@ export function registerTools(server: McpServer, client: IndemnClient): Registry
 
   reg.tool(
     'scrape_url',
-    'Scrape a website URL and add it as a data source to a knowledge base. The crawl runs in the background; its pages appear in the knowledge base only when it ends.',
+    'Scrape a website URL and add it as a data source to a knowledge base. The crawl runs in the background; its pages appear in the knowledge base only when it ends. Unless the person already said, ask them first whether to crawl the whole site (up to 100 pages) or import only this page.',
     {
       kb_id: z.string().describe('The knowledge base ID'),
       url: z.string().describe('URL to scrape'),
-      crawl_mode: z.string().optional().describe('Crawl mode: "full" (entire site) or "selected"'),
+      crawl_mode: z.enum(['full', 'selected']).describe('What the person chose: "full" crawls the whole site from url (up to 100 pages); "selected" imports only this page (one call per page).'),
     },
     async (args) => {
       try {

package/src/sdk/access.ts

@@ -0,0 +1,143 @@
+import { IndemnClient } from './client.js';
+
+/**
+ * What the signed-in person may do, as copilot-server reports it
+ * (GET /auth/me/access). Display information only: copilot-server and
+ * darwin-service still decide every request. The CLI uses it to hide MCP
+ * tools the person can't use anywhere and to explain refusals by role.
+ * Unknown access (older server, offline) hides nothing.
+ */
+export interface AccessProject {
+  project_id: string;
+  name: string | null;
+  role: string;
+  capabilities: string[];
+}
+
+export interface AccessOrg {
+  org_id: string;
+  org_name: string;
+  role: string | null;
+  is_org_admin: boolean;
+  capabilities: string[];
+  projects: AccessProject[];
+}
+
+export interface Access {
+  user: { id: string; email: string; name: string | null };
+  is_indemn_staff: boolean;
+  capabilities: string[];
+  orgs: AccessOrg[];
+  fetched_at?: string;
+}
+
+type Scope = 'user' | 'org' | 'project';
+
+/** MCP tools whose use depends on a role, staff email or org setting (copilot config/cliCapabilities.js). */
+export const TOOL_REQUIRES: Readonly<Record<string, { scope: Scope; capability: string }>> = Object.freeze({
+  create_sandbox_org: { scope: 'user', capability: 'org:sandbox_create' },
+  set_org_admin_settings: { scope: 'user', capability: 'org:admin_settings' },
+  get_conversation: { scope: 'project', capability: 'conversations:read' },
+  chat_with_agent: { scope: 'project', capability: 'conversations:read' },
+  mark_conversation_test: { scope: 'project', capability: 'conversations:mark_test' },
+  list_tickets: { scope: 'org', capability: 'tickets' },
+  get_ticket: { scope: 'org', capability: 'tickets' },
+  create_ticket: { scope: 'org', capability: 'tickets' },
+  update_ticket: { scope: 'org', capability: 'tickets' },
+  archive_ticket: { scope: 'org', capability: 'tickets' },
+  list_ticket_rules: { scope: 'org', capability: 'tickets' },
+  save_ticket_rule: { scope: 'org', capability: 'tickets' },
+  delete_ticket_rule: { scope: 'org', capability: 'tickets' },
+});
+
+let memo: Access | null = null;
+
+/** The last known access: this process's, else the one saved with the login (config credential only). */
+export function currentAccess(client?: IndemnClient): Access | null {
+  if (memo) return memo;
+  // A host session (INDEMN_TOKEN) may be a different identity than the saved login; don't use its access.
+  const source = (client ?? new IndemnClient()).getCredential()?.source;
+  return source === 'config' ? IndemnClient.loadConfig()?.access ?? null : null;
+}
+
+/** Defend against a malformed payload: every array field defaults to empty, bad orgs are dropped. */
+function normalize(raw: Access): Pick<Access, 'capabilities' | 'orgs'> {
+  const strings = (v: unknown): string[] => (Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : []);
+  const orgs = (Array.isArray(raw.orgs) ? raw.orgs : [])
+    .filter((o): o is AccessOrg => Boolean(o) && typeof o.org_id === 'string')
+    .map((o) => ({
+      ...o,
+      capabilities: strings(o.capabilities),
+      projects: (Array.isArray(o.projects) ? o.projects : [])
+        .filter((pr): pr is AccessProject => Boolean(pr) && typeof pr.project_id === 'string')
+        .map((pr) => ({ ...pr, capabilities: strings(pr.capabilities) })),
+    }));
+  return { capabilities: strings(raw.capabilities), orgs };
+}
+
+/** Forget the in-process copy (tests, logout). */
+export function resetAccess(): void {
+  memo = null;
+}
+
+/**
+ * Ask copilot again. Saved with the login only when the credential is the saved
+ * login; a host's session (INDEMN_TOKEN) never writes to this machine's config.
+ * Returns null when it can't be read (older server, offline): callers then hide nothing.
+ */
+export async function refreshAccess(client: IndemnClient): Promise<Access | null> {
+  try {
+    const raw = await client.copilotGet<Access>('/auth/me/access');
+    if (!raw || !Array.isArray(raw.orgs)) return null;
+    const stamped: Access = { ...raw, ...normalize(raw), fetched_at: new Date().toISOString() };
+    memo = stamped;
+    if (client.getCredential()?.source === 'config') IndemnClient.saveConfig({ access: stamped });
+    return stamped;
+  } catch {
+    return null;
+  }
+}
+
+function orgsInView(access: Access, onlyOrgId?: string): AccessOrg[] {
+  return onlyOrgId ? access.orgs.filter((o) => o.org_id === onlyOrgId) : access.orgs;
+}
+
+/** True unless access is known and says the tool can't be used in any org/project in view. */
+export function usableSomewhere(tool: string, access: Access | null, onlyOrgId?: string): boolean {
+  const rule = TOOL_REQUIRES[tool];
+  if (!rule || !access) return true;
+  if (rule.scope === 'user') return access.capabilities.includes(rule.capability);
+  const orgs = orgsInView(access, onlyOrgId);
+  if (rule.scope === 'org') return orgs.some((o) => o.capabilities.includes(rule.capability));
+  return orgs.some((o) => o.projects.some((p) => p.capabilities.includes(rule.capability)));
+}
+
+/** The person's role in an org, for messages ("agent in Acme"). */
+export function roleIn(access: Access | null, orgId: string | undefined): string | null {
+  if (!access || !orgId) return null;
+  const org = access.orgs.find((o) => o.org_id === orgId);
+  if (!org) return null;
+  return `${org.role ?? 'member'} in ${org.org_name}`;
+}
+
+/**
+ * For org-scoped requirements: why this org can't be used, or null. Project-scoped
+ * requirements are decided by the server (the project comes from the agent).
+ */
+export function orgDenial(tool: string, access: Access | null, orgId: string | undefined): string | null {
+  const rule = TOOL_REQUIRES[tool];
+  if (!rule || !access || rule.scope === 'project') return null;
+  if (rule.scope === 'user') {
+    if (access.capabilities.includes(rule.capability)) return null;
+    return rule.capability === 'org:sandbox_create'
+      ? 'Only the Indemn support account can create sandbox organizations.'
+      : 'This is for Indemn staff only.';
+  }
+  if (!orgId) return null;
+  const org = access.orgs.find((o) => o.org_id === orgId);
+  if (!org) return null; // not in the list: let the server answer
+  if (org.capabilities.includes(rule.capability)) return null;
+  return rule.capability === 'tickets'
+    ? `Tickets are not turned on for ${org.org_name}.`
+    : `Your role (${org.role ?? 'member'} in ${org.org_name}) does not allow this.`;
+}

package/src/sdk/auth.ts

@@ -3,6 +3,8 @@ import { getAuth, signInWithEmailAndPassword } from '@firebase/auth';
 import { DEFAULT_HOSTS, IndemnClient } from './client.js';
 import { exchangeIdToken, toStoredSession } from './session.js';
 import type { Credential } from './credentials.js';
+import { browserSignIn, type BrowserLoginOptions } from './browser-login.js';
+import { refreshAccess, resetAccess } from './access.js';
 import type { Environment, EnvironmentHosts, OrgSummary } from './types.js';
 
 // Firebase client configs per environment — public configuration (not secrets),
@@ -62,7 +64,21 @@ export async function login(email: string, password: string, env: Environment =
     idToken,
     opts?.mfaCodePrompt,
   );
+  return saveLogin(env, { ...session, email: session.email ?? email });
+}
+
+/**
+ * Log in through the browser: the dashboard's sign-in (with the emailed code when
+ * the account uses it) approves this computer, and the CLI gets its own 24-hour
+ * session. Same storage and same rules as the password login.
+ */
+export async function loginWithBrowser(env: Environment = 'dev', opts?: BrowserLoginOptions): Promise<LoginResult> {
+  const session = await browserSignIn(env, opts);
+  return saveLogin(env, session);
+}
 
+/** Keep a fresh copilot session with the person's orgs, replacing any earlier login. */
+async function saveLogin(env: Environment, session: { token: string; userId: string; email?: string }): Promise<LoginResult> {
   // Which orgs this person belongs to, asked with the new session itself.
   const authed = new IndemnClient({ environment: env, token: session.token });
   const res = await authed.copilotGet<{ userOrganizations?: Array<{ _id: string; name: string }> }>('/organization');
@@ -73,13 +89,17 @@ export async function login(email: string, password: string, env: Environment =
   IndemnClient.saveConfig({
     environment: env,
     user_id: session.userId,
-    email: session.email ?? email,
+    email: session.email,
     session: stored,
     orgs,
     hosts: DEFAULT_HOSTS,
   });
 
-  return { userId: session.userId, email: session.email ?? email, environment: env, orgs, expiresAt: stored.expires_at };
+  // What the person may do, kept with the login (best effort: an older server has no such endpoint).
+  resetAccess();
+  await refreshAccess(new IndemnClient({ environment: env }));
+
+  return { userId: session.userId, email: session.email ?? '', environment: env, orgs, expiresAt: stored.expires_at };
 }
 
 /** Revoke the session on the server, then forget it locally. */
@@ -96,6 +116,7 @@ export async function logout(): Promise<{ revoked: boolean }> {
     }
   }
   IndemnClient.clearConfig();
+  resetAccess();
   return { revoked };
 }
 

package/src/sdk/browser-login.ts

@@ -0,0 +1,193 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { createServer, type Server } from 'node:http';
+import { spawn } from 'node:child_process';
+import type { AddressInfo } from 'node:net';
+import { IndemnClient } from './client.js';
+import { CliError, indemnHost } from '../core/runtime.js';
+import type { Environment } from './types.js';
+
+/**
+ * `indemn login` through the browser (OAuth-style loopback + PKCE):
+ * 1. listen on 127.0.0.1 (random port) and open the dashboard's /cli-login page
+ *    with a random `state` and the SHA-256 challenge of a secret verifier;
+ * 2. the person signs in there (with the emailed code if their account uses it)
+ *    and approves; the browser comes back to 127.0.0.1 with a one-time code;
+ * 3. the CLI trades code + verifier for its own 24-hour session.
+ * No token ever travels in a URL, and the verifier never leaves this process.
+ */
+
+export const LOGIN_TIMEOUT_MS = 5 * 60_000;
+
+export interface Pkce {
+  verifier: string;
+  challenge: string;
+  state: string;
+}
+
+export function createPkce(): Pkce {
+  const verifier = randomBytes(32).toString('base64url');
+  const challenge = createHash('sha256').update(verifier).digest('base64url');
+  const state = randomBytes(32).toString('base64url');
+  return { verifier, challenge, state };
+}
+
+function sameSecret(a: string, b: string): boolean {
+  const x = Buffer.from(a);
+  const y = Buffer.from(b);
+  return x.length === y.length && timingSafeEqual(x, y);
+}
+
+/** The dashboard that serves /cli-login: INDEMN_DASHBOARD_URL, else the copilot host without `/api`. */
+export function dashboardUrl(copilotHost: string): string {
+  const explicit = process.env.INDEMN_DASHBOARD_URL;
+  if (explicit) return indemnHost(explicit, 'INDEMN_DASHBOARD_URL').replace(/\/+$/, '');
+  return copilotHost.replace(/\/+$/, '').replace(/\/api$/, '');
+}
+
+export function approveUrl(dashboard: string, port: number, pkce: Pkce): string {
+  const query = new URLSearchParams({ port: String(port), state: pkce.state, challenge: pkce.challenge });
+  return `${dashboard}/#/cli-login?${query.toString()}`;
+}
+
+export type CallbackResult = { code: string } | { error: string };
+
+export interface Loopback {
+  port: number;
+  /** First callback whose `state` matches; others are refused and ignored. */
+  result: Promise<CallbackResult>;
+  close: () => void;
+}
+
+const PAGE = (title: string, body: string) =>
+  `<!doctype html><html><head><meta charset="utf-8"><title>${title}</title></head>` +
+  `<body style="font-family:system-ui,sans-serif;max-width:32rem;margin:4rem auto;padding:0 1rem">` +
+  `<h1 style="font-size:1.1rem">${title}</h1><p>${body}</p></body></html>`;
+
+/** Listen on 127.0.0.1 only, for one `GET /callback` carrying our `state`. */
+export async function startLoopback(state: string, timeoutMs: number = LOGIN_TIMEOUT_MS): Promise<Loopback> {
+  let settle!: (r: CallbackResult) => void;
+  let fail!: (e: Error) => void;
+  const result = new Promise<CallbackResult>((resolve, reject) => {
+    settle = resolve;
+    fail = reject;
+  });
+
+  let done = false;
+  const server: Server = createServer((req, res) => {
+    res.setHeader('Cache-Control', 'no-store');
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+    // The page has no subresources and echoes nothing; these just harden it.
+    res.setHeader('Referrer-Policy', 'no-referrer');
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('Content-Security-Policy', "default-src 'none'; style-src 'unsafe-inline'");
+    // A raw socket can send a target that URL() rejects; never let that crash login.
+    let url: URL;
+    try {
+      url = new URL(req.url ?? '/', 'http://127.0.0.1');
+    } catch {
+      res.writeHead(400).end(PAGE('Bad request', 'Nothing to see here.'));
+      return;
+    }
+    // DNS-rebinding defence: only our own loopback Host is served.
+    const host = (req.headers.host ?? '').toLowerCase();
+    if (host && !/^(127\.0\.0\.1|localhost)(:\d+)?$/.test(host)) {
+      res.writeHead(400).end(PAGE('Bad request', 'Nothing to see here.'));
+      return;
+    }
+    if (req.method !== 'GET' || url.pathname !== '/callback' || done) {
+      res.writeHead(404).end(PAGE('Not found', 'Nothing to see here.'));
+      return;
+    }
+    const got = url.searchParams.get('state') ?? '';
+    if (!sameSecret(got, state)) {
+      res.writeHead(400).end(PAGE('Sign-in link mismatch', 'This sign-in did not come from your terminal. Run <code>indemn login</code> again.'));
+      return;
+    }
+    const code = url.searchParams.get('code');
+    const error = url.searchParams.get('error');
+    done = true;
+    if (code) {
+      res.writeHead(200).end(PAGE('Signed in to the Indemn CLI', 'You can close this tab and return to your terminal.'));
+      settle({ code });
+    } else {
+      res.writeHead(200).end(PAGE('Sign-in cancelled', 'The CLI was not signed in. You can close this tab.'));
+      settle({ error: error || 'access_denied' });
+    }
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => resolve());
+  });
+  const { port } = server.address() as AddressInfo;
+
+  const timer = setTimeout(() => {
+    if (!done) {
+      done = true;
+      fail(new CliError('Timed out waiting for the browser (5 minutes). Run `indemn login` again.'));
+    }
+  }, timeoutMs);
+  timer.unref();
+
+  const close = () => {
+    clearTimeout(timer);
+    server.closeAllConnections?.();
+    server.close();
+  };
+  result.then(close, close);
+  return { port, result, close };
+}
+
+/** Open a URL in the default browser without a shell. Resolves false if nothing could be started. */
+export function openBrowser(url: string): Promise<boolean> {
+  const [cmd, args] =
+    process.platform === 'darwin' ? ['open', [url]]
+      : process.platform === 'win32' ? ['rundll32', ['url.dll,FileProtocolHandler', url]]
+        : ['xdg-open', [url]];
+  return new Promise((resolve) => {
+    try {
+      const child = spawn(cmd, args as string[], { stdio: 'ignore', detached: true });
+      child.once('error', () => resolve(false));
+      child.once('spawn', () => {
+        child.unref();
+        resolve(true);
+      });
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+export interface BrowserLoginOptions {
+  /** Opens the approve page; defaults to the system browser. */
+  open?: (url: string) => Promise<boolean>;
+  /** Told the URL (always), so it can be opened by hand. */
+  showUrl?: (url: string, opened: boolean) => void;
+  timeoutMs?: number;
+}
+
+/** Run the browser flow; returns the copilot session (without the "JWT " prefix). */
+export async function browserSignIn(env: Environment, opts: BrowserLoginOptions = {}): Promise<{ token: string; userId: string; email?: string }> {
+  const client = new IndemnClient({ environment: env });
+  const pkce = createPkce();
+  const loop = await startLoopback(pkce.state, opts.timeoutMs);
+  try {
+    const url = approveUrl(dashboardUrl(client.getHosts().copilot), loop.port, pkce);
+    const opened = await (opts.open ?? openBrowser)(url);
+    opts.showUrl?.(url, opened);
+
+    const outcome = await loop.result;
+    if ('error' in outcome) throw new CliError('Sign-in was cancelled in the browser.');
+
+    let res: { token: string; user: { _id: string; email?: string } };
+    try {
+      res = await client.copilotPostUnauth('/auth/cli/token', { code: outcome.code, code_verifier: pkce.verifier });
+    } catch {
+      throw new CliError('The sign-in code was not accepted (it may have expired). Run `indemn login` again.');
+    }
+    if (!res?.token || !res.user?._id) throw new CliError('Sign-in returned no session. Run `indemn login` again.');
+    return { token: res.token.replace(/^JWT\s+/i, ''), userId: String(res.user._id), email: res.user.email };
+  } finally {
+    loop.close();
+  }
+}