@openparachute/agent 0.1.0

package/src/web/routes/agent-provider.test.ts

@@ -0,0 +1,282 @@
+/**
+ * Tests for the `/api/settings/agent-provider` route helpers.
+ * Exercises `readAgentProviderView` and `setAgentProvider` against
+ * a real in-memory DB so the encrypted upsert + audit log + view
+ * shape stay in sync end-to-end.
+ */
+import fs from 'fs';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('../../config.js', async () => {
+  const actual = await vi.importActual('../../config.js');
+  return { ...actual, DATA_DIR: '/tmp/paraclaw-test-agent-provider-route' };
+});
+
+const TEST_DIR = '/tmp/paraclaw-test-agent-provider-route';
+
+beforeEach(async () => {
+  if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+  fs.mkdirSync(TEST_DIR, { recursive: true });
+  vi.resetModules();
+  const { initTestDb, runMigrations } = await import('../../db/index.js');
+  const db = initTestDb();
+  runMigrations(db);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('readAgentProviderView', () => {
+  it('returns a fresh-install view with everything null/false when no row exists', async () => {
+    const { readAgentProviderView } = await import('./agent-provider.js');
+    expect(readAgentProviderView()).toEqual({
+      source: null,
+      hasApiKey: false,
+      serverUrl: null,
+      updatedAt: null,
+    });
+  });
+
+  it('exposes only booleans for stored secrets — never the plaintext', async () => {
+    const { putProviderCredentials, DEFAULT_SCOPE_ID } = await import('../../modules/provider-credentials/db.js');
+    putProviderCredentials({
+      scopeId: DEFAULT_SCOPE_ID,
+      source: 'anthropic_api_key',
+      apiKey: 'sk-ant-api03-secret-do-not-leak',
+    });
+
+    const { readAgentProviderView } = await import('./agent-provider.js');
+    const view = readAgentProviderView();
+    expect(view.source).toBe('anthropic_api_key');
+    expect(view.hasApiKey).toBe(true);
+    expect(JSON.stringify(view)).not.toContain('sk-ant-api03-secret-do-not-leak');
+  });
+
+  it('exposes setup-token presence as hasApiKey: true (single secret slot)', async () => {
+    const { putProviderCredentials, DEFAULT_SCOPE_ID } = await import('../../modules/provider-credentials/db.js');
+    putProviderCredentials({ scopeId: DEFAULT_SCOPE_ID, source: 'claude_setup_token', apiKey: 'sk-ant-oat01-secret' });
+
+    const { readAgentProviderView } = await import('./agent-provider.js');
+    const view = readAgentProviderView();
+    expect(view.source).toBe('claude_setup_token');
+    expect(view.hasApiKey).toBe(true);
+    expect(JSON.stringify(view)).not.toContain('sk-ant-oat01-secret');
+  });
+});
+
+describe('setAgentProvider', () => {
+  it('rejects unknown source with 400', async () => {
+    const { setAgentProvider } = await import('./agent-provider.js');
+    const result = setAgentProvider({ source: 'something-else' as never }, 'telegram:1');
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.status).toBe(400);
+      expect(result.message).toContain('source must be one of');
+    }
+  });
+
+  it('claude_setup_token → requires apiKey, then stores it (trimmed)', async () => {
+    const { setAgentProvider } = await import('./agent-provider.js');
+
+    const missing = setAgentProvider({ source: 'claude_setup_token' }, 'telegram:1');
+    expect(missing.ok).toBe(false);
+    if (!missing.ok) {
+      expect(missing.status).toBe(400);
+      expect(missing.message).toContain('apiKey is required');
+    }
+
+    const ok = setAgentProvider({ source: 'claude_setup_token', apiKey: '  sk-ant-oat01-paste  ' }, 'telegram:1');
+    expect(ok.ok).toBe(true);
+    if (ok.ok) {
+      expect(ok.view.source).toBe('claude_setup_token');
+      expect(ok.view.hasApiKey).toBe(true);
+    }
+
+    const { readProviderCredentials } = await import('../../modules/provider-credentials/db.js');
+    expect(readProviderCredentials()?.apiKey).toBe('sk-ant-oat01-paste');
+  });
+
+  it('anthropic_api_key → requires apiKey, then stores it', async () => {
+    const { setAgentProvider } = await import('./agent-provider.js');
+    const missing = setAgentProvider({ source: 'anthropic_api_key' }, 'telegram:1');
+    expect(missing.ok).toBe(false);
+    if (!missing.ok) expect(missing.status).toBe(400);
+
+    const ok = setAgentProvider({ source: 'anthropic_api_key', apiKey: '  sk-ant-test  ' }, 'telegram:1');
+    expect(ok.ok).toBe(true);
+
+    const { readProviderCredentials } = await import('../../modules/provider-credentials/db.js');
+    expect(readProviderCredentials()?.apiKey).toBe('sk-ant-test');
+  });
+
+  it('external_server → requires apiKey + valid serverUrl', async () => {
+    const { setAgentProvider } = await import('./agent-provider.js');
+
+    const noKey = setAgentProvider(
+      { source: 'external_server', serverUrl: 'https://openrouter.ai/api/v1' },
+      'telegram:1',
+    );
+    expect(noKey.ok).toBe(false);
+
+    const noUrl = setAgentProvider({ source: 'external_server', apiKey: 'k' }, 'telegram:1');
+    expect(noUrl.ok).toBe(false);
+
+    const badUrl = setAgentProvider({ source: 'external_server', apiKey: 'k', serverUrl: 'not a url' }, 'telegram:1');
+    expect(badUrl.ok).toBe(false);
+    if (!badUrl.ok) expect(badUrl.message).toContain('valid URL');
+
+    const ok = setAgentProvider(
+      { source: 'external_server', apiKey: 'or-key', serverUrl: 'https://openrouter.ai/api/v1' },
+      'telegram:1',
+    );
+    expect(ok.ok).toBe(true);
+
+    const { readProviderCredentials } = await import('../../modules/provider-credentials/db.js');
+    const row = readProviderCredentials();
+    expect(row?.apiKey).toBe('or-key');
+    expect(row?.serverUrl).toBe('https://openrouter.ai/api/v1');
+  });
+
+  it('emits agent_provider_source_changed audit on every successful change', async () => {
+    const { log } = await import('../../log.js');
+    const infoSpy = vi.spyOn(log, 'info').mockImplementation(() => {});
+
+    const { setAgentProvider } = await import('./agent-provider.js');
+    const ok = setAgentProvider({ source: 'claude_setup_token', apiKey: 'sk-ant-oat01-x' }, 'telegram:42');
+    expect(ok.ok).toBe(true);
+
+    const auditCalls = infoSpy.mock.calls.filter(
+      (c) => (c[1] as { audit?: string } | undefined)?.audit === 'agent_provider_source_changed',
+    );
+    expect(auditCalls).toHaveLength(1);
+    const [, payload] = auditCalls[0]!;
+    expect(payload).toMatchObject({
+      audit: 'agent_provider_source_changed',
+      fromSource: null,
+      toSource: 'claude_setup_token',
+      actor: 'telegram:42',
+    });
+    expect(payload).toHaveProperty('hasServerUrl');
+  });
+
+  it('switching sources clears the previous source-specific fields', async () => {
+    const { setAgentProvider } = await import('./agent-provider.js');
+    setAgentProvider(
+      { source: 'external_server', apiKey: 'or-key', serverUrl: 'https://openrouter.ai/api/v1' },
+      'telegram:1',
+    );
+
+    setAgentProvider({ source: 'claude_setup_token', apiKey: 'sk-ant-oat01-new' }, 'telegram:1');
+
+    const { readProviderCredentials } = await import('../../modules/provider-credentials/db.js');
+    const row = readProviderCredentials();
+    expect(row?.source).toBe('claude_setup_token');
+    expect(row?.apiKey).toBe('sk-ant-oat01-new');
+    expect(row?.serverUrl).toBeNull();
+  });
+});
+
+describe('per-group agent provider (paraclaw#86)', () => {
+  it('readGroupAgentProviderView reports unoverridden + effective from default', async () => {
+    const { putProviderCredentials, DEFAULT_SCOPE_ID } = await import('../../modules/provider-credentials/db.js');
+    putProviderCredentials({ scopeId: DEFAULT_SCOPE_ID, source: 'anthropic_api_key', apiKey: 'install-default-key' });
+
+    const { readGroupAgentProviderView } = await import('./agent-provider.js');
+    const view = readGroupAgentProviderView('ag-no-override');
+    expect(view.overridden).toBe(false);
+    expect(view.override.source).toBeNull();
+    expect(view.override.hasApiKey).toBe(false);
+    expect(view.effective.source).toBe('anthropic_api_key');
+    expect(view.effective.hasApiKey).toBe(true);
+  });
+
+  it('setGroupAgentProvider stores under the group id, not the default sentinel', async () => {
+    const { setGroupAgentProvider } = await import('./agent-provider.js');
+    const result = setGroupAgentProvider(
+      { source: 'claude_setup_token', apiKey: '  sk-ant-oat01-group  ' },
+      'ag-special',
+      'telegram:7',
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.view.overridden).toBe(true);
+    expect(result.view.override.source).toBe('claude_setup_token');
+    expect(result.view.override.hasApiKey).toBe(true);
+    expect(result.view.effective.source).toBe('claude_setup_token');
+
+    const { readProviderCredentials } = await import('../../modules/provider-credentials/db.js');
+    const groupRow = readProviderCredentials('ag-special');
+    expect(groupRow?.apiKey).toBe('sk-ant-oat01-group');
+    const defaultRow = readProviderCredentials();
+    expect(defaultRow).toBeUndefined();
+  });
+
+  it('per-group audit emits agentGroupId and never the secret', async () => {
+    const { log } = await import('../../log.js');
+    const infoSpy = vi.spyOn(log, 'info').mockImplementation(() => {});
+
+    const { setGroupAgentProvider } = await import('./agent-provider.js');
+    const ok = setGroupAgentProvider(
+      { source: 'external_server', apiKey: 'or-key', serverUrl: 'https://openrouter.ai/api/v1' },
+      'ag-9',
+      'telegram:9',
+    );
+    expect(ok.ok).toBe(true);
+
+    const auditCalls = infoSpy.mock.calls.filter(
+      (c) => (c[1] as { audit?: string } | undefined)?.audit === 'agent_provider_source_changed',
+    );
+    expect(auditCalls).toHaveLength(1);
+    const [, payload] = auditCalls[0]!;
+    expect(payload).toMatchObject({
+      audit: 'agent_provider_source_changed',
+      agentGroupId: 'ag-9',
+      toSource: 'external_server',
+      actor: 'telegram:9',
+    });
+    expect(JSON.stringify(payload)).not.toContain('or-key');
+  });
+
+  it('clearGroupAgentProvider deletes the override row + emits override_cleared audit', async () => {
+    const { putProviderCredentials, DEFAULT_SCOPE_ID } = await import('../../modules/provider-credentials/db.js');
+    putProviderCredentials({ scopeId: DEFAULT_SCOPE_ID, source: 'anthropic_api_key', apiKey: 'install-default-key' });
+    putProviderCredentials({ scopeId: 'ag-x', source: 'claude_setup_token', apiKey: 'sk-ant-oat01-x' });
+
+    const { log } = await import('../../log.js');
+    const infoSpy = vi.spyOn(log, 'info').mockImplementation(() => {});
+
+    const { clearGroupAgentProvider } = await import('./agent-provider.js');
+    const result = clearGroupAgentProvider('ag-x', 'telegram:1');
+    expect(result.cleared).toBe(true);
+    expect(result.view.overridden).toBe(false);
+    expect(result.view.effective.source).toBe('anthropic_api_key');
+
+    const { readProviderCredentials } = await import('../../modules/provider-credentials/db.js');
+    expect(readProviderCredentials('ag-x')).toBeUndefined();
+
+    const auditCalls = infoSpy.mock.calls.filter(
+      (c) => (c[1] as { audit?: string } | undefined)?.audit === 'agent_provider_override_cleared',
+    );
+    expect(auditCalls).toHaveLength(1);
+    expect(auditCalls[0]![1]).toMatchObject({
+      audit: 'agent_provider_override_cleared',
+      agentGroupId: 'ag-x',
+      fromSource: 'claude_setup_token',
+      actor: 'telegram:1',
+    });
+  });
+
+  it('clearGroupAgentProvider on unset row is idempotent — no audit, cleared:false', async () => {
+    const { log } = await import('../../log.js');
+    const infoSpy = vi.spyOn(log, 'info').mockImplementation(() => {});
+
+    const { clearGroupAgentProvider } = await import('./agent-provider.js');
+    const result = clearGroupAgentProvider('ag-nope', 'telegram:1');
+    expect(result.cleared).toBe(false);
+    const auditCalls = infoSpy.mock.calls.filter(
+      (c) => (c[1] as { audit?: string } | undefined)?.audit === 'agent_provider_override_cleared',
+    );
+    expect(auditCalls).toHaveLength(0);
+  });
+});

package/src/web/routes/agent-provider.ts

@@ -0,0 +1,309 @@
+/**
+ * `/api/settings/agent-provider` — read + write the install-wide
+ * agent-provider credential source (paraclaw#78).
+ * `/api/groups/:folder/agent-provider` — per-agent-group override
+ * (paraclaw#86); same shape, scoped to the group's id. Both back the
+ * `/agent/settings/agent-provider` and `/agent/groups/<folder>` UIs.
+ *
+ * Three sources, all paste-only:
+ *   - `claude_setup_token` — operator runs `claude setup-token` on a host
+ *     where they're authenticated to a Pro/Max/Team/Enterprise subscription
+ *     and pastes the printed token. Container gets `CLAUDE_CODE_OAUTH_TOKEN`.
+ *   - `anthropic_api_key` — Anthropic Console API key. Container gets
+ *     `ANTHROPIC_API_KEY`.
+ *   - `external_server` — self-hosted Claude proxy or a vendor that speaks
+ *     the Anthropic API. Container gets `ANTHROPIC_API_KEY` + `ANTHROPIC_BASE_URL`.
+ *
+ * Security note: the secret value (token / key) is never returned in
+ * responses. The GET shape exposes only "is this slot populated?" via
+ * boolean flags, so the operator can see what's configured without
+ * pulling secrets out of the encrypted store and into a browser.
+ *
+ * Audit log: source changes emit `audit: 'agent_provider_source_changed'`
+ * via structured `log.info`, mirroring the PR4 sender-approval pattern.
+ * Per-group changes carry an `agentGroupId` field; per-group clear emits
+ * `audit: 'agent_provider_override_cleared'`.
+ */
+import http from 'node:http';
+
+import { log } from '../../log.js';
+import {
+  DEFAULT_SCOPE_ID,
+  deleteProviderCredentials,
+  putProviderCredentials,
+  readProviderCredentials,
+  type ProviderSource,
+} from '../../modules/provider-credentials/index.js';
+
+interface AgentProviderView {
+  source: ProviderSource | null;
+  hasApiKey: boolean;
+  serverUrl: string | null;
+  updatedAt: string | null;
+}
+
+/**
+ * Per-group response shape: same fields as the install-wide view, plus
+ * `overridden` (true iff a row exists for this agent_group_id) and an
+ * `effective` snapshot of what spawn would actually use right now —
+ * either the override or the inherited default. The UI uses
+ * `overridden` to decide between "Override default" and "Clear
+ * override" affordances.
+ */
+export interface GroupAgentProviderView {
+  agentGroupId: string;
+  overridden: boolean;
+  override: AgentProviderView;
+  effective: AgentProviderView;
+}
+
+const json = (res: http.ServerResponse, status: number, body: unknown): void => {
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(body));
+};
+const error = (res: http.ServerResponse, status: number, message: string): void =>
+  json(res, status, { error: message });
+
+async function readJsonBody<T>(req: http.IncomingMessage): Promise<T> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) chunks.push(chunk as Buffer);
+  if (chunks.length === 0) return {} as T;
+  return JSON.parse(Buffer.concat(chunks).toString('utf8')) as T;
+}
+
+function viewForScope(scopeId: string): AgentProviderView {
+  const row = readProviderCredentials(scopeId);
+  return {
+    source: row?.source ?? null,
+    hasApiKey: !!row?.apiKey,
+    serverUrl: row?.serverUrl ?? null,
+    updatedAt: row?.updatedAt ?? null,
+  };
+}
+
+export function readAgentProviderView(): AgentProviderView {
+  return viewForScope(DEFAULT_SCOPE_ID);
+}
+
+export function readGroupAgentProviderView(agentGroupId: string): GroupAgentProviderView {
+  const overrideRow = readProviderCredentials(agentGroupId);
+  const override = viewForScope(agentGroupId);
+  const effective = overrideRow ? override : viewForScope(DEFAULT_SCOPE_ID);
+  return {
+    agentGroupId,
+    overridden: overrideRow != null,
+    override,
+    effective,
+  };
+}
+
+interface SetAgentProviderBody {
+  source?: ProviderSource;
+  apiKey?: string;
+  serverUrl?: string;
+}
+
+const VALID_SOURCES: ProviderSource[] = ['claude_setup_token', 'anthropic_api_key', 'external_server'];
+
+export interface SetAgentProviderResult {
+  ok: true;
+  view: AgentProviderView;
+}
+
+export interface SetAgentProviderError {
+  ok: false;
+  status: number;
+  message: string;
+}
+
+export function setAgentProvider(
+  body: SetAgentProviderBody,
+  actor: string | null,
+): SetAgentProviderResult | SetAgentProviderError {
+  const result = applySetForScope(body, DEFAULT_SCOPE_ID, actor, null);
+  if (!result.ok) return result;
+  return { ok: true, view: readAgentProviderView() };
+}
+
+export interface SetGroupAgentProviderResult {
+  ok: true;
+  view: GroupAgentProviderView;
+}
+
+export function setGroupAgentProvider(
+  body: SetAgentProviderBody,
+  agentGroupId: string,
+  actor: string | null,
+): SetGroupAgentProviderResult | SetAgentProviderError {
+  const result = applySetForScope(body, agentGroupId, actor, agentGroupId);
+  if (!result.ok) return result;
+  return { ok: true, view: readGroupAgentProviderView(agentGroupId) };
+}
+
+export interface ClearGroupAgentProviderResult {
+  ok: true;
+  view: GroupAgentProviderView;
+  cleared: boolean;
+}
+
+export function clearGroupAgentProvider(agentGroupId: string, actor: string | null): ClearGroupAgentProviderResult {
+  const previous = readProviderCredentials(agentGroupId);
+  const cleared = deleteProviderCredentials(agentGroupId);
+  if (cleared) {
+    log.info('Agent-provider override cleared', {
+      audit: 'agent_provider_override_cleared',
+      agentGroupId,
+      fromSource: previous?.source ?? null,
+      actor,
+    });
+  }
+  return { ok: true, view: readGroupAgentProviderView(agentGroupId), cleared };
+}
+
+function applySetForScope(
+  body: SetAgentProviderBody,
+  scopeId: string,
+  actor: string | null,
+  agentGroupId: string | null,
+): { ok: true } | SetAgentProviderError {
+  const { source, apiKey, serverUrl } = body;
+  if (!source || !VALID_SOURCES.includes(source)) {
+    return { ok: false, status: 400, message: `source must be one of ${VALID_SOURCES.join(', ')}` };
+  }
+
+  const previous = readProviderCredentials(scopeId);
+  const previousSource = previous?.source ?? null;
+
+  switch (source) {
+    case 'claude_setup_token': {
+      if (!apiKey || !apiKey.trim()) {
+        return { ok: false, status: 400, message: 'apiKey is required for claude_setup_token' };
+      }
+      putProviderCredentials({ scopeId, source, apiKey: apiKey.trim(), serverUrl: null });
+      break;
+    }
+    case 'anthropic_api_key': {
+      if (!apiKey || !apiKey.trim()) {
+        return { ok: false, status: 400, message: 'apiKey is required for anthropic_api_key' };
+      }
+      putProviderCredentials({ scopeId, source, apiKey: apiKey.trim(), serverUrl: null });
+      break;
+    }
+    case 'external_server': {
+      if (!apiKey || !apiKey.trim()) {
+        return { ok: false, status: 400, message: 'apiKey is required for external_server' };
+      }
+      if (!serverUrl || !serverUrl.trim()) {
+        return { ok: false, status: 400, message: 'serverUrl is required for external_server' };
+      }
+      try {
+        new URL(serverUrl);
+      } catch {
+        return { ok: false, status: 400, message: 'serverUrl must be a valid URL' };
+      }
+      putProviderCredentials({
+        scopeId,
+        source,
+        apiKey: apiKey.trim(),
+        serverUrl: serverUrl.trim(),
+      });
+      break;
+    }
+  }
+
+  log.info('Agent-provider source updated', {
+    audit: 'agent_provider_source_changed',
+    fromSource: previousSource,
+    toSource: source,
+    actor,
+    agentGroupId,
+    // Don't log apiKey — that's the secret.
+    hasServerUrl: source === 'external_server' && !!serverUrl,
+  });
+
+  return { ok: true };
+}
+
+export interface AgentProviderRouteContext {
+  pathname: string;
+  method: string;
+  req: http.IncomingMessage;
+  res: http.ServerResponse;
+  /** Hub-issued JWT subject for the audit line. */
+  actorSubject: string | null;
+}
+
+export async function handleAgentProviderRoute(ctx: AgentProviderRouteContext): Promise<boolean> {
+  const { pathname, method, req, res, actorSubject } = ctx;
+  if (pathname !== '/api/settings/agent-provider') return false;
+
+  if (method === 'GET') {
+    json(res, 200, readAgentProviderView());
+    return true;
+  }
+  if (method === 'POST') {
+    let body: SetAgentProviderBody;
+    try {
+      body = await readJsonBody<SetAgentProviderBody>(req);
+    } catch {
+      error(res, 400, 'invalid JSON body');
+      return true;
+    }
+    const result = setAgentProvider(body, actorSubject);
+    if (!result.ok) {
+      error(res, result.status, result.message);
+      return true;
+    }
+    json(res, 200, result.view);
+    return true;
+  }
+  error(res, 405, `${method} not allowed`);
+  return true;
+}
+
+export interface GroupAgentProviderRouteContext {
+  method: string;
+  req: http.IncomingMessage;
+  res: http.ServerResponse;
+  agentGroupId: string;
+  actorSubject: string | null;
+}
+
+/**
+ * Per-group agent-provider sub-route. Mounted under
+ * `/api/groups/:folder/agent-provider`; the caller has already resolved
+ * folder → agentGroupId and gated on the right `claw:*` scope.
+ *
+ *   - GET    → `GroupAgentProviderView` (override + effective + flag)
+ *   - POST   → set / replace the override
+ *   - DELETE → clear the override (idempotent — 200 either way)
+ */
+export async function handleGroupAgentProviderRoute(ctx: GroupAgentProviderRouteContext): Promise<void> {
+  const { method, req, res, agentGroupId, actorSubject } = ctx;
+  if (method === 'GET') {
+    json(res, 200, readGroupAgentProviderView(agentGroupId));
+    return;
+  }
+  if (method === 'POST') {
+    let body: SetAgentProviderBody;
+    try {
+      body = await readJsonBody<SetAgentProviderBody>(req);
+    } catch {
+      error(res, 400, 'invalid JSON body');
+      return;
+    }
+    const result = setGroupAgentProvider(body, agentGroupId, actorSubject);
+    if (!result.ok) {
+      error(res, result.status, result.message);
+      return;
+    }
+    json(res, 200, result.view);
+    return;
+  }
+  if (method === 'DELETE') {
+    const result = clearGroupAgentProvider(agentGroupId, actorSubject);
+    json(res, 200, result.view);
+    return;
+  }
+  error(res, 405, `${method} not allowed`);
+}