@indemn/cli 1.7.7 → 1.7.9

package/src/sdk/types.ts

@@ -1,3 +1,4 @@
+import type { Access } from './access.js';
 // Environment and configuration types
 
 export type Environment = 'dev' | 'production';
@@ -53,6 +54,8 @@ export interface IndemnConfig {
   org_id?: string;
   org_name?: string;
   hosts: Record<Environment, EnvironmentHosts>;
+  /** What the person may do (GET /auth/me/access), saved with the login; display only. */
+  access?: Access;
 }
 
 // API response types

package/test/mcp/__snapshots__/tools-snapshot.test.ts.snap

@@ -111,10 +111,15 @@ exports[`MCP tool list > gives every tool a title and annotations 1`] = `
   "platform_list",
   "platform_save",
   "promote_prod_call",
+  "publish_campaign",
   "reimport_kb_source",
   "remove_holiday",
   "run_evaluation",
   "run_simulation",
+  "save_book",
+  "save_campaign",
+  "save_campaign_template",
+  "save_template_skill",
   "save_ticket_rule",
   "scrape_url",
   "search_phone_numbers",
@@ -122,10 +127,12 @@ exports[`MCP tool list > gives every tool a title and annotations 1`] = `
   "set_agent_transcriber",
   "set_agent_voice",
   "set_business_hours",
+  "set_campaign_status",
   "set_config",
   "set_org_admin_settings",
   "set_org_timezone",
   "set_prompt",
+  "set_touchpoint",
   "simulation_status",
   "test_function",
   "transfer_agent_owner",

package/test/mcp/access.test.ts

@@ -0,0 +1,158 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ToolListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
+import { on, recordFetch } from '../helpers/fetch-recorder.js';
+import { cleanEnv, useTempHome } from '../helpers/config-home.js';
+import { jwtExpiringIn } from '../helpers/jwt.js';
+import { connectPair } from '../helpers/mcp-pair.js';
+import { IndemnClient } from '../../src/sdk/client.js';
+import { registerTools } from '../../src/mcp/tools.js';
+import { refreshAccess, resetAccess, usableSomewhere, type Access } from '../../src/sdk/access.js';
+import type { Registry } from '../../src/mcp/registry.js';
+
+const A = 'aaaaaaaaaaaaaaaaaaaaaaaa';
+const B = 'bbbbbbbbbbbbbbbbbbbbbbbb';
+
+function accessWith(bTickets = false): Access {
+  return {
+    user: { id: 'u1', email: 'pat@example.test', name: 'Pat' },
+    is_indemn_staff: false,
+    capabilities: [],
+    orgs: [
+      { org_id: A, org_name: 'QA A', role: 'admin', is_org_admin: true, capabilities: ['member', 'tickets'],
+        projects: [{ project_id: 'p1', name: 'A main', role: 'admin', capabilities: ['conversations:messages', 'conversations:read'] }] },
+      { org_id: B, org_name: 'QA B', role: 'guest', is_org_admin: false, capabilities: bTickets ? ['member', 'tickets'] : ['member'],
+        projects: [{ project_id: 'p2', name: 'B main', role: 'guest', capabilities: ['conversations:messages'] }] },
+    ],
+  };
+}
+
+describe('role-aware MCP tools', () => {
+  let home: ReturnType<typeof useTempHome>;
+  let registry: Registry;
+
+  beforeEach(() => {
+    cleanEnv();
+    home = useTempHome();
+    resetAccess();
+    vi.spyOn(process, 'cwd').mockReturnValue(home.dir);
+    IndemnClient.saveConfig({
+      environment: 'dev', user_id: 'u1', session: { token: jwtExpiringIn(5 * 3_600_000) },
+      orgs: [{ id: A, name: 'QA A' }, { id: B, name: 'QA B' }],
+      access: accessWith(),
+    });
+  });
+  afterEach(() => { resetAccess(); home.cleanup(); });
+
+  function setup(server: Parameters<typeof registerTools>[0]) {
+    registry = registerTools(server, new IndemnClient());
+    registry.applyVisibility();
+  }
+
+  async function toolNames(pair: Awaited<ReturnType<typeof connectPair>>) {
+    return (await pair.client.listTools()).tools.map((t) => t.name);
+  }
+
+  it('hides tools the person can use nowhere, keeps the rest', async () => {
+    recordFetch();
+    const pair = await connectPair(setup);
+    const names = await toolNames(pair);
+    expect(names).toContain('list_tickets'); // tickets on in QA A
+    expect(names).toContain('get_conversation'); // admin in A's project
+    expect(names).toContain('list_agents'); // membership only
+    expect(names).not.toContain('set_org_admin_settings'); // staff only
+    expect(names).not.toContain('create_sandbox_org'); // support account only
+    expect(names).not.toContain('mark_conversation_test'); // staff + agent
+    await pair.close();
+  });
+
+  it('a folder linked to one org counts only that org', async () => {
+    vi.stubEnv('INDEMN_ORG_ID', B);
+    recordFetch();
+    const pair = await connectPair(setup);
+    const names = await toolNames(pair);
+    expect(names).not.toContain('list_tickets');
+    expect(names).not.toContain('get_conversation');
+    expect(names).toContain('list_agents');
+    await pair.close();
+  });
+
+  it('refuses early, with the reason, where the org has no access (after asking again)', async () => {
+    const { calls } = recordFetch([on('GET', '/auth/me/access', { json: accessWith() })]);
+    const pair = await connectPair(setup);
+    const res = await pair.call('list_tickets', { org_id: B });
+    expect(res.isError).toBe(true);
+    expect(res.body).toContain('Tickets are not turned on for QA B');
+    expect(calls.some((c) => c.url.includes('/auth/me/access'))).toBe(true); // stale access is re-checked first
+    expect(calls.some((c) => c.url.includes('/tickets'))).toBe(false);
+    await pair.close();
+  });
+
+  it('a refresh that grants access lets the call through', async () => {
+    const { calls } = recordFetch([on('GET', '/auth/me/access', { json: accessWith(true) })]);
+    const pair = await connectPair(setup);
+    const res = await pair.call('list_tickets', { org_id: B });
+    expect(res.isError).toBe(false);
+    expect(calls.some((c) => c.url.includes(`/organization/${B}/tickets`))).toBe(true);
+    await pair.close();
+  });
+
+  it('concurrent calls for different orgs each get their own answer', async () => {
+    const { calls } = recordFetch([on('GET', '/auth/me/access', { json: accessWith() })]);
+    const pair = await connectPair(setup);
+    const [inA, inB, inA2] = await Promise.all([
+      pair.call('list_tickets', { org_id: A }),
+      pair.call('list_tickets', { org_id: B }),
+      pair.call('list_tickets', { org_id: A }),
+    ]);
+    expect(inA.isError).toBe(false);
+    expect(inA2.isError).toBe(false);
+    expect(inB.isError).toBe(true);
+    expect(inA.body.context.org_id).toBe(A);
+    const ticketCalls = calls.filter((c) => c.url.includes('/tickets'));
+    expect(ticketCalls).toHaveLength(2);
+    expect(ticketCalls.every((c) => c.url.includes(`/organization/${A}/tickets`))).toBe(true);
+    await pair.close();
+  });
+
+  it('a server refusal names the person\'s role', async () => {
+    recordFetch([
+      on('GET', '/auth/me/access', { json: accessWith() }),
+      on('GET', '/ai-studio/v2/bots', { status: 403, json: { success: false, msg: 'Forbidden' } }),
+    ]);
+    const pair = await connectPair(setup);
+    const res = await pair.call('list_agents', { org_id: B });
+    expect(res.isError).toBe(true);
+    expect(res.body).toContain('Not allowed');
+    expect(res.body).toContain('Your role: guest in QA B.');
+    await pair.close();
+  });
+
+  it('tells the host when the visible tools change', async () => {
+    vi.stubEnv('INDEMN_ORG_ID', B);
+    recordFetch([on('GET', '/auth/me/access', { json: accessWith(true) })]);
+    const pair = await connectPair(setup);
+    let changed = 0;
+    pair.client.setNotificationHandler(ToolListChangedNotificationSchema, async () => { changed += 1; });
+    expect(await toolNames(pair)).not.toContain('list_tickets');
+    await refreshAccess(new IndemnClient());
+    registry.applyVisibility();
+    await vi.waitFor(() => expect(changed).toBeGreaterThan(0));
+    expect(await toolNames(pair)).toContain('list_tickets');
+    await pair.close();
+  });
+
+  it('unknown access hides nothing', () => {
+    expect(usableSomewhere('set_org_admin_settings', null)).toBe(true);
+    expect(usableSomewhere('list_tickets', null)).toBe(true);
+  });
+
+  it('a host session (INDEMN_TOKEN) never writes access to this machine', async () => {
+    IndemnClient.clearConfig();
+    vi.stubEnv('INDEMN_TOKEN', jwtExpiringIn(3_600_000));
+    vi.stubEnv('INDEMN_ENV', 'dev');
+    recordFetch([on('GET', '/auth/me/access', { json: accessWith() })]);
+    const got = await refreshAccess(new IndemnClient());
+    expect(got?.orgs).toHaveLength(2);
+    expect(IndemnClient.loadConfig()).toBeNull();
+  });
+});

package/test/mcp/campaigns.test.ts

@@ -0,0 +1,165 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { on, recordFetch, type RecordedCall, type Responder } from '../helpers/fetch-recorder.js';
+import { cleanEnv } from '../helpers/config-home.js';
+import { connectPair } from '../helpers/mcp-pair.js';
+import { IndemnClient } from '../../src/sdk/client.js';
+import { registerTools } from '../../src/mcp/tools.js';
+import { TOOL_META } from '../../src/mcp/tool-meta.js';
+
+const ORG = 'aaaaaaaaaaaaaaaaaaaaaaaa';
+const solutionsOn = on('GET', `/organization/${ORG}/configurations`, { json: { enableSolutions: true } });
+const approve = () => ({ action: 'accept' as const, content: { confirm: true } });
+async function pair(elicit: () => { action: 'accept' | 'decline'; content?: Record<string, unknown> } = approve) {
+  cleanEnv();
+  const client = new IndemnClient({ apiKey: `ind_dev_${'a'.repeat(64)}`, orgId: ORG, environment: 'dev' });
+  return connectPair((server) => { registerTools(server, client); }, { elicit });
+}
+const fetches = (responders: Responder[]) => recordFetch([solutionsOn, ...responders]);
+const writes = (calls: RecordedCall[]) => calls.filter((c) => c.method !== 'GET').map((c) => `${c.method} ${c.url.split('campaigns-service')[1]}`);
+const draft = { audience: null, touchpoints: [], escalation_policy: {}, channel_policy: {} };
+const campaign = { id: 'c1', name: 'GL renewals', status: 'draft', current_version_n: null, draft };
+
+describe('campaign tools', () => {
+  let p: Awaited<ReturnType<typeof pair>> | undefined;
+  afterEach(async () => { await p?.close(); p = undefined; });
+
+  it('with Solutions off, reads and changes are refused before any card or call, saying how to turn it on', async () => {
+    const { calls } = recordFetch([on('GET', '/configurations', { json: { enableSolutions: false } })]);
+    p = await pair();
+    for (const [name, args] of [['get_campaigns', { what: 'list' }], ['save_campaign', { solution_id: 's1', book_id: 'b1', name: 'X', campaign_type: 'renewal' }]] as const) {
+      const res = await p.call(name, args);
+      expect(res.isError).toBe(true);
+      expect(String(res.body)).toMatch(/Solutions is not turned on.*set_org_admin_settings.*Nothing was changed/);
+    }
+    expect(p.questions).toHaveLength(0);
+    expect(calls.filter((c) => c.url.includes('campaigns-service'))).toHaveLength(0);
+  });
+
+  it('save_campaign without an id creates, asking first by name; confirm and empty fields never reach the service', async () => {
+    const { calls } = fetches([on('GET', '/campaigns-service/books/b1', { json: { id: 'b1', name: 'GL book' } }), on('POST', '/campaigns-service/campaigns', { json: campaign })]);
+    p = await pair();
+    const res = await p.call('save_campaign', { solution_id: 's1', book_id: 'b1', name: 'GL renewals', campaign_type: 'renewal', closes: '', confirm: true });
+    expect(res.isError).toBe(false);
+    expect(p.questions[0].message).toContain('create campaign "GL renewals" as a draft; it sends nothing until it is published and started');
+    expect(writes(calls)).toEqual(['POST /campaigns']);
+    expect(calls.find((c) => c.method === 'POST')!.body).toEqual({ solution_id: 's1', book_id: 'b1', name: 'GL renewals', campaign_type: 'renewal' });
+  });
+
+  it('a create missing what it needs is answered at once: no card, no call', async () => {
+    const { calls } = fetches([]);
+    p = await pair();
+    const res = await p.call('save_campaign', { name: 'GL renewals' });
+    expect(res.isError).toBe(true);
+    expect(String(res.body)).toContain('To create a campaign also give solution_id, book_id, campaign_type');
+    expect(p.questions).toHaveLength(0);
+    expect(writes(calls)).toEqual([]);
+  });
+
+  it('save_campaign with an id changes only the draft parts given, by name on the card', async () => {
+    const touchpoints = [{ key: 't1', channel: 'email' }];
+    const { calls } = fetches([
+      on('GET', '/campaigns-service/campaigns/c1', { json: { ...campaign, draft: { ...draft, touchpoints } } }),
+      on('PUT', '/campaigns-service/campaigns/c1/draft', (c) => ({ json: c.body })),
+    ]);
+    p = await pair();
+    const res = await p.call('save_campaign', { campaign_id: 'c1', audience: '{"field":"status","op":"eq","value":"active"}' });
+    expect(res.isError).toBe(false);
+    expect(p.questions[0].message).toContain('change the audience in the draft of campaign "GL renewals"');
+    expect(calls.find((c) => c.method === 'PUT')!.body).toEqual({ ...draft, touchpoints, audience: { field: 'status', op: 'eq', value: 'active' } });
+  });
+
+  it('set_touchpoint takes flat fields and rules as JSON text, and drafts unless told to send', async () => {
+    const { calls } = fetches([
+      on('GET', '/campaigns-service/campaigns/c1', { json: campaign }),
+      on('PUT', '/campaigns-service/campaigns/c1/draft', (c) => ({ json: c.body })),
+    ]);
+    p = await pair();
+    const res = await p.call('set_touchpoint', { campaign_id: 'c1', key: 't1_60', channel: 'email', when: '{"field":"derived.days_out","op":"lte","value":60}' });
+    expect(res.isError).toBe(false);
+    expect((calls.find((c) => c.method === 'PUT')!.body as typeof draft).touchpoints).toEqual([{ key: 't1_60', channel: 'email', terminal_action: 'draft', when: { field: 'derived.days_out', op: 'lte', value: 60 } }]);
+    expect(p.questions[0].message).toContain('touchpoint "t1_60" in the draft of campaign "GL renewals" (email)');
+  });
+
+  it('starting a campaign is its own approval and says it reaches customers; a decline changes nothing', async () => {
+    const { calls } = fetches([on('GET', '/campaigns-service/campaigns/c1', { json: campaign }), on('POST', '/status', { json: { ...campaign, status: 'running' } })]);
+    p = await pair(() => ({ action: 'decline' }));
+    await p.call('set_campaign_status', { campaign_id: 'c1', status: 'running' });
+    expect(p.questions[0].message).toMatch(/START campaign "GL renewals".*reach real customers/);
+    expect(writes(calls)).toEqual([]);
+  });
+
+  it("the service's refusal reaches the person as it is", async () => {
+    fetches([
+      on('GET', '/campaigns-service/campaigns/c1', { json: campaign }),
+      on('POST', '/status', { status: 409, json: { detail: 'cannot start a campaign that has never published a version' } }),
+    ]);
+    p = await pair();
+    const res = await p.call('set_campaign_status', { campaign_id: 'c1', status: 'running' });
+    expect(res.isError).toBe(true);
+    expect(String(res.body)).toContain('never published a version');
+  });
+
+  it('an id that names nothing gets no card', async () => {
+    const { calls } = fetches([on('GET', '/campaigns-service/campaigns/nope', { status: 404, json: { detail: 'not found' } })]);
+    p = await pair();
+    const res = await p.call('publish_campaign', { campaign_id: 'nope' });
+    expect(String(res.body)).toContain('Not found: campaign nope');
+    expect(p.questions).toHaveLength(0);
+    expect(writes(calls)).toEqual([]);
+  });
+
+  it('save_campaign_template with an id saves a new version from the latest one, named on the card', async () => {
+    const { calls } = fetches([
+      on('GET', '/campaigns-service/templates/tpl1/versions', { json: { items: [{ version_n: 1, subject: 'Renewal', body: 'Old', uses_variables: [] }] } }),
+      on('GET', '/campaigns-service/templates/tpl1', { json: { id: 'tpl1', name: 'GL reminder' } }),
+      on('POST', '/campaigns-service/templates/tpl1/versions', (c) => ({ json: { version_n: 2, ...(c.body as object) } })),
+    ]);
+    p = await pair();
+    const res = await p.call('save_campaign_template', { template_id: 'tpl1', body: 'New', subject: '' });
+    expect(res.isError).toBe(false);
+    expect(calls.find((c) => c.method === 'POST')!.body).toEqual({ subject: 'Renewal', body: 'New', uses_variables: [] });  // "" kept the subject
+    expect(p.questions[0].message).toContain('new version of template "GL reminder" (body)');
+  });
+
+  it('save_template_skill creates and changes, by name on the card', async () => {
+    const { calls } = fetches([
+      on('GET', '/campaigns-service/template-skills/sk1', { json: { id: 'sk1', name: 'Tone', instructions: 'Brief.' } }),
+      (c) => (c.method === 'GET' ? undefined : { json: { id: 'sk1' } }),
+    ]);
+    p = await pair();
+    await p.call('save_template_skill', { solution_id: 's1', key: 'tone', name: 'Tone', instructions: 'Brief.' });
+    await p.call('save_template_skill', { template_skill_id: 'sk1', instructions: 'Warm.' });
+    expect(writes(calls)).toEqual(['POST /template-skills', 'PUT /template-skills/sk1']);
+    expect(calls.filter((c) => c.method !== 'GET').map((c) => c.body)).toEqual([{ solution_id: 's1', key: 'tone', name: 'Tone', instructions: 'Brief.' }, { name: 'Tone', instructions: 'Warm.' }]);
+    expect(p.questions[1].message).toContain('change template skill "Tone" (instructions)');
+  });
+
+  it('save_book changes only the parts given; a create whose change is refused says the book exists', async () => {
+    const { calls } = fetches([
+      on('GET', '/campaigns-service/books/b1', { json: { id: 'b1', name: 'GL book' } }),
+      on('POST', '/campaigns-service/books', { json: { id: 'b2', name: 'New book' } }),
+      on('PUT', '/books/b2/display', { status: 400, json: { detail: 'display names keys absent from the schema: no.such' } }),
+      (c) => (c.method === 'GET' ? undefined : { json: { id: 'b1' } }),
+    ]);
+    p = await pair();
+    const res = await p.call('save_book', { book_id: 'b1', identity_keys: ['policy.number'], display: '{"primary":["policy.number"],"secondary":["insured.name"]}' });
+    expect(res.isError).toBe(false);
+    expect(p.questions[0].message).toContain('change book "GL book": identity keys to policy.number; display to primary policy.number; secondary insured.name.');
+    const made = await p.call('save_book', { solution_id: 's1', name: 'New book', display: '{"primary":["no.such"]}' });
+    expect(String(made.body)).toMatch(/The book was created \(id b2\), but .*no\.such.*do not create it again/);
+    expect(writes(calls)).toEqual(['PUT /books/b1/identity-keys', 'PUT /books/b1/display', 'POST /books', 'PUT /books/b2/display']);
+  });
+
+  it('a book change card shows the new values', () => {
+    expect(TOOL_META.save_book.describe!({ book_id: 'b1', source: { kind: 'upload' }, field_map: [{ source_path: 'Policy #', schema_key: 'policy.number' }, { source_path: 'Insured', schema_key: 'insured.name' }] }))
+      .toBe('This will change book b1: source to upload; field map to Policy # → policy.number, Insured → insured.name.');
+  });
+
+  it('get_campaigns reads books', async () => {
+    const { calls } = fetches([on('GET', '/campaigns-service/books', { json: { total: 1, items: [{ id: 'b1', name: 'GL book' }] } })]);
+    p = await pair();
+    const res = await p.call('get_campaigns', { what: 'books', solution_id: 's1' });
+    expect(res.isError).toBe(false);
+    expect(calls.some((c) => c.method === 'GET' && c.url.includes('/campaigns-service/books?') && c.url.includes('solution_id=s1'))).toBe(true);
+  });
+});

package/test/mcp/tools-snapshot.test.ts

@@ -17,7 +17,7 @@ describe('MCP tool list', () => {
       expect(typeof tool.annotations?.readOnlyHint, tool.name).toBe('boolean');
     }
     expect(tools.map((t) => t.name).sort()).toMatchSnapshot();
-    expect(tools).toHaveLength(141); // +numbers // +set_agent_transcriber // +set_org_admin_settings // +remove_holiday // +create_sandbox_org
+    expect(tools).toHaveLength(148); // +7 campaign tools // +numbers // +set_agent_transcriber // +set_org_admin_settings // +remove_holiday // +create_sandbox_org
     const props = (name: string) => Object.keys((tools.find((t) => t.name === name)!.inputSchema as { properties?: object }).properties ?? {});
     for (const name of ['list_agents', 'delete_agent', 'set_prompt', 'list_org_members', 'list_channels', 'chat_with_agent']) {
       expect(props(name), name).toContain('org_id');
@@ -26,7 +26,7 @@ describe('MCP tool list', () => {
       expect(props(name), name).not.toContain('org_id');
     }
     // Writes that change what customers get or reach outside ask first on every host (a dry run, then confirm).
-    for (const name of ['delete_agent', 'create_function', 'test_function', 'add_kb_data', 'scrape_url', 'upload_kb_file']) {
+    for (const name of ['delete_agent', 'create_function', 'test_function', 'add_kb_data', 'scrape_url', 'upload_kb_file', 'save_campaign', 'set_touchpoint', 'publish_campaign', 'set_campaign_status', 'save_campaign_template', 'save_template_skill', 'save_book']) {
       expect(props(name), name).toContain('confirm');
     }
     // The person chooses how much of a website is crawled: only scrape_url crawls, and it needs their choice.

package/test/sdk/auth.test.ts

@@ -24,7 +24,8 @@ describe('token-first login', () => {
     ]);
     const result = await login('qa@indemn.ai', 'pw', 'dev', { firebaseSignIn: fakeFirebase });
 
-    expect(calls.map((c) => `${c.method} ${new URL(c.url).pathname}`)).toEqual(['POST /api/auth/firebase/signin', 'GET /api/organization']);
+    // Then what the person may do, kept with the login (display only).
+    expect(calls.map((c) => `${c.method} ${new URL(c.url).pathname}`)).toEqual(['POST /api/auth/firebase/signin', 'GET /api/organization', 'GET /api/auth/me/access']);
     expect(calls.some((c) => c.url.includes('/auth/api-keys'))).toBe(false);
     expect(calls[1].headers.authorization).toBe(`JWT ${token}`);
     expect(result.orgs).toEqual([{ id: A._id, name: 'QA A' }, { id: B._id, name: 'QA B' }]);

package/test/sdk/browser-login.test.ts

@@ -0,0 +1,147 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync } from 'node:fs';
+import { request } from 'node:http';
+import { join } from 'node:path';
+import { on, recordFetch } from '../helpers/fetch-recorder.js';
+import { cleanEnv, useTempHome } from '../helpers/config-home.js';
+import { jwtExpiringIn } from '../helpers/jwt.js';
+import { approveUrl, createPkce, dashboardUrl, startLoopback } from '../../src/sdk/browser-login.js';
+import { loginWithBrowser } from '../../src/sdk/auth.js';
+
+/** GET a loopback URL with node:http (global fetch is recorded in these tests). */
+function hit(url: string): Promise<{ status: number; body: string }> {
+  return new Promise((resolve, reject) => {
+    request(url, (res) => {
+      let body = '';
+      res.on('data', (c) => (body += c));
+      res.on('end', () => resolve({ status: res.statusCode ?? 0, body }));
+    }).on('error', reject).end();
+  });
+}
+
+describe('PKCE and URLs', () => {
+  beforeEach(() => cleanEnv());
+
+  it('challenge is the base64url SHA-256 of the verifier; values are fresh each time', () => {
+    const a = createPkce();
+    const b = createPkce();
+    expect(a.challenge).toBe(createHash('sha256').update(a.verifier).digest('base64url'));
+    expect(a.challenge).toMatch(/^[A-Za-z0-9_-]{43}$/);
+    expect(a.verifier).toMatch(/^[A-Za-z0-9_-]{43}$/);
+    expect(a.state).toMatch(/^[A-Za-z0-9_-]{43}$/);
+    expect(a.verifier).not.toBe(b.verifier);
+    expect(a.state).not.toBe(b.state);
+  });
+
+  it('dashboard is the copilot host without /api, or INDEMN_DASHBOARD_URL (Indemn or localhost only)', () => {
+    expect(dashboardUrl('https://devcopilot.indemn.ai/api')).toBe('https://devcopilot.indemn.ai');
+    vi.stubEnv('INDEMN_DASHBOARD_URL', 'http://localhost:5174/');
+    expect(dashboardUrl('https://devcopilot.indemn.ai/api')).toBe('http://localhost:5174');
+    vi.stubEnv('INDEMN_DASHBOARD_URL', 'https://evil.example');
+    expect(() => dashboardUrl('https://devcopilot.indemn.ai/api')).toThrow(/indemn\.ai/);
+  });
+
+  it('approve URL carries port, state and challenge but never the verifier', () => {
+    const p = createPkce();
+    const url = approveUrl('https://copilot.indemn.ai', 50123, p);
+    expect(url.startsWith('https://copilot.indemn.ai/#/cli-login?')).toBe(true);
+    const q = new URLSearchParams(url.split('?')[1]);
+    expect(q.get('port')).toBe('50123');
+    expect(q.get('state')).toBe(p.state);
+    expect(q.get('challenge')).toBe(p.challenge);
+    expect(url).not.toContain(p.verifier);
+  });
+});
+
+describe('loopback listener', () => {
+  it('binds 127.0.0.1, ignores a wrong state, takes the first matching callback, then closes', async () => {
+    const loop = await startLoopback('the-state', 10_000);
+    const base = `http://127.0.0.1:${loop.port}`;
+    expect((await hit(`${base}/other`)).status).toBe(404);
+    expect((await hit(`${base}/callback?code=x&state=wrong`)).status).toBe(400);
+    const ok = await hit(`${base}/callback?code=the-code&state=the-state`);
+    expect(ok.status).toBe(200);
+    expect(ok.body).toContain('close this tab');
+    expect(ok.body).not.toContain('the-code');
+    await expect(loop.result).resolves.toEqual({ code: 'the-code' });
+    await expect(hit(`${base}/callback?code=again&state=the-state`)).rejects.toThrow();
+  });
+
+  it('reports a cancel from the browser', async () => {
+    const loop = await startLoopback('s', 10_000);
+    await hit(`http://127.0.0.1:${loop.port}/callback?error=access_denied&state=s`);
+    await expect(loop.result).resolves.toEqual({ error: 'access_denied' });
+  });
+
+  it('times out', async () => {
+    const loop = await startLoopback('s', 50);
+    await expect(loop.result).rejects.toThrow(/Timed out/);
+  });
+});
+
+describe('loginWithBrowser', () => {
+  let home: ReturnType<typeof useTempHome>;
+  beforeEach(() => { cleanEnv(); home = useTempHome(); });
+  afterEach(() => home.cleanup());
+
+  /** A fake browser: reads the approve URL and calls back like the dashboard would. */
+  function approvingBrowser(seen: { challenge?: string }, outcome: 'approve' | 'cancel' = 'approve') {
+    return async (url: string) => {
+      const q = new URLSearchParams(url.split('?')[1]);
+      seen.challenge = q.get('challenge') ?? undefined;
+      const back = new URLSearchParams(outcome === 'approve' ? { code: 'one-time-code', state: q.get('state')! } : { error: 'access_denied', state: q.get('state')! });
+      setTimeout(() => void hit(`http://127.0.0.1:${q.get('port')}/callback?${back}`), 10);
+      return true;
+    };
+  }
+
+  it('exchanges the code with the verifier and saves the session like a normal login', async () => {
+    const token = jwtExpiringIn(24 * 3_600_000, { cli: true });
+    const { calls } = recordFetch([
+      on('POST', '/auth/cli/token', { json: { token: `JWT ${token}`, expires_at: 'x', user: { _id: 'u1', email: 'pat@example.test' } } }),
+      on('GET', '/organization', { json: { success: true, userOrganizations: [{ _id: 'aaaaaaaaaaaaaaaaaaaaaaaa', name: 'Acme' }] } }),
+    ]);
+    const seen: { challenge?: string } = {};
+    const result = await loginWithBrowser('dev', { open: approvingBrowser(seen), timeoutMs: 10_000 });
+
+    const exchange = calls.find((c) => c.url.endsWith('/auth/cli/token'))!;
+    expect(new URL(exchange.url).origin).toBe('https://devcopilot.indemn.ai');
+    expect(exchange.headers.authorization).toBeUndefined();
+    const body = exchange.body as { code: string; code_verifier: string };
+    expect(body.code).toBe('one-time-code');
+    expect(createHash('sha256').update(body.code_verifier).digest('base64url')).toBe(seen.challenge);
+
+    expect(result.email).toBe('pat@example.test');
+    expect(result.orgs).toEqual([{ id: 'aaaaaaaaaaaaaaaaaaaaaaaa', name: 'Acme' }]);
+    const saved = JSON.parse(readFileSync(join(home.dir, '.indemn', 'config.json'), 'utf8'));
+    expect(saved.session.token).toBe(token);
+    expect(saved.email).toBe('pat@example.test');
+    expect(saved).not.toHaveProperty('api_key');
+    if (process.platform !== 'win32') {
+      expect(statSync(join(home.dir, '.indemn', 'config.json')).mode & 0o777).toBe(0o600);
+      expect(statSync(join(home.dir, '.indemn')).mode & 0o777).toBe(0o700);
+    }
+  });
+
+  it('cancel in the browser saves nothing', async () => {
+    recordFetch([]);
+    await expect(loginWithBrowser('dev', { open: approvingBrowser({}, 'cancel'), timeoutMs: 10_000 })).rejects.toThrow(/cancelled/);
+    expect(() => readFileSync(join(home.dir, '.indemn', 'config.json'))).toThrow();
+  });
+
+  it('a refused code says to log in again', async () => {
+    recordFetch([on('POST', '/auth/cli/token', { status: 400, json: { success: false, error: 'invalid_grant' } })]);
+    await expect(loginWithBrowser('dev', { open: approvingBrowser({}), timeoutMs: 10_000 })).rejects.toThrow(/not accepted/);
+  });
+
+  it('shows the URL even when the browser cannot be opened', async () => {
+    recordFetch([]);
+    const shown: Array<[string, boolean]> = [];
+    const pending = loginWithBrowser('dev', { open: async () => false, showUrl: (u, o) => shown.push([u, o]), timeoutMs: 100 });
+    await expect(pending).rejects.toThrow(/Timed out/);
+    expect(shown).toHaveLength(1);
+    expect(shown[0][1]).toBe(false);
+    expect(shown[0][0]).toContain('/#/cli-login?');
+  });
+});