@openparachute/agent 0.1.2 → 0.2.2

package/src/web/routes/vaults.test.ts

@@ -1,389 +0,0 @@
-/**
- * Route-level tests for `/api/vaults*`. The proxy primitives are exercised
- * in `src/web/vault-proxy.test.ts`; this file covers the dispatcher in
- * `routes/vaults.ts` — URL pattern matching, the attached-to-group merge
- * by tokenLabel, vault-not-found 404s, and refresh-cache invalidation.
- *
- * Strategy: stub global `fetch` for the HTTP calls (vault REST + hub
- * well-known), and `vi.mock` the DB/attachment readers so the test
- * doesn't need a real central DB or filesystem groups dir.
- */
-import http from 'node:http';
-
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-import { clearHubDiscoveryCache } from '../hub-discovery.js';
-
-vi.mock('../../db/connection.js', () => ({
-  openDb: () => ({
-    prepare: () => ({ all: () => [{ folder: 'group-a' }, { folder: 'group-b' }] }),
-    close: () => {},
-  }),
-}));
-
-vi.mock('../../parachute/vault-mcp.js', () => ({
-  listVaultAttachments: vi.fn(() => []),
-}));
-
-import { listVaultAttachments } from '../../parachute/vault-mcp.js';
-import { handleVaultsRoute } from './vaults.js';
-
-const mockedListVaultAttachments = listVaultAttachments as unknown as ReturnType<typeof vi.fn>;
-
-let prevHub: string | undefined;
-
-beforeEach(() => {
-  prevHub = process.env.PARACHUTE_HUB_ORIGIN;
-  delete process.env.PARACHUTE_AGENT_HUB_ORIGIN;
-  delete process.env.PARACLAW_HUB_ORIGIN;
-  process.env.PARACHUTE_HUB_ORIGIN = 'https://parachute.example';
-  clearHubDiscoveryCache();
-  mockedListVaultAttachments.mockReset();
-  mockedListVaultAttachments.mockReturnValue([]);
-});
-
-afterEach(() => {
-  if (prevHub === undefined) delete process.env.PARACHUTE_HUB_ORIGIN;
-  else process.env.PARACHUTE_HUB_ORIGIN = prevHub;
-  clearHubDiscoveryCache();
-  vi.unstubAllGlobals();
-});
-
-interface FakeResponse {
-  statusCode: number;
-  body: unknown;
-  headers: Record<string, string>;
-  res: http.ServerResponse;
-}
-
-function fakeRes(): FakeResponse {
-  const captured: FakeResponse = {
-    statusCode: 0,
-    body: undefined,
-    headers: {},
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    res: undefined as any,
-  };
-  const res = {
-    writeHead(status: number, headers: Record<string, string>) {
-      captured.statusCode = status;
-      captured.headers = headers;
-    },
-    end(chunk: string) {
-      try {
-        captured.body = chunk ? JSON.parse(chunk) : undefined;
-      } catch {
-        captured.body = chunk;
-      }
-    },
-  } as unknown as http.ServerResponse;
-  captured.res = res;
-  return captured;
-}
-
-function fakeReq(body?: unknown): http.IncomingMessage {
-  if (body === undefined) {
-    return Object.assign(Object.create(null), {
-      [Symbol.asyncIterator]: async function* () {},
-    }) as http.IncomingMessage;
-  }
-  const buf = Buffer.from(JSON.stringify(body));
-  return Object.assign(Object.create(null), {
-    [Symbol.asyncIterator]: async function* () {
-      yield buf;
-    },
-  }) as http.IncomingMessage;
-}
-
-function jsonOk(body: unknown, status = 200): Response {
-  return new Response(JSON.stringify(body), {
-    status,
-    headers: { 'content-type': 'application/json' },
-  });
-}
-
-/** Each call returns a fresh Response — Response bodies are single-use. */
-function alwaysOk(body: unknown, status = 200) {
-  return vi.fn().mockImplementation(async () => jsonOk(body, status));
-}
-
-const HUB_VAULTS_BODY = {
-  vaults: [
-    { name: 'work', url: 'https://h/vault/work', version: '0.4.7' },
-    { name: 'personal', url: 'https://h/vault/personal', version: '0.4.7' },
-  ],
-};
-
-describe('handleVaultsRoute', () => {
-  it('GET /api/vaults returns the hub well-known list', async () => {
-    vi.stubGlobal('fetch', alwaysOk(HUB_VAULTS_BODY));
-    const cap = fakeRes();
-    const handled = await handleVaultsRoute({
-      pathname: '/api/vaults',
-      method: 'GET',
-      url: new URL('https://x/api/vaults'),
-      req: fakeReq(),
-      res: cap.res,
-      authHeader: 'Bearer x',
-    });
-    expect(handled).toBe(true);
-    expect(cap.statusCode).toBe(200);
-    expect(cap.body).toEqual({ vaults: HUB_VAULTS_BODY.vaults });
-  });
-
-  it('POST /api/vaults/refresh clears the cache so the next call refetches', async () => {
-    const stub = alwaysOk(HUB_VAULTS_BODY);
-    vi.stubGlobal('fetch', stub);
-    // Prime the cache via GET.
-    await handleVaultsRoute({
-      pathname: '/api/vaults',
-      method: 'GET',
-      url: new URL('https://x/api/vaults'),
-      req: fakeReq(),
-      res: fakeRes().res,
-      authHeader: 'Bearer x',
-    });
-    expect(stub).toHaveBeenCalledTimes(1);
-    // Same call — cache hit, no extra fetch.
-    await handleVaultsRoute({
-      pathname: '/api/vaults',
-      method: 'GET',
-      url: new URL('https://x/api/vaults'),
-      req: fakeReq(),
-      res: fakeRes().res,
-      authHeader: 'Bearer x',
-    });
-    expect(stub).toHaveBeenCalledTimes(1);
-    // Refresh forces a refetch.
-    const cap = fakeRes();
-    await handleVaultsRoute({
-      pathname: '/api/vaults/refresh',
-      method: 'POST',
-      url: new URL('https://x/api/vaults/refresh'),
-      req: fakeReq(),
-      res: cap.res,
-      authHeader: 'Bearer x',
-    });
-    expect(cap.statusCode).toBe(200);
-    expect(stub).toHaveBeenCalledTimes(2);
-  });
-
-  it('GET /api/vaults/:name returns 404 when the vault is unknown', async () => {
-    vi.stubGlobal('fetch', alwaysOk(HUB_VAULTS_BODY));
-    const cap = fakeRes();
-    await handleVaultsRoute({
-      pathname: '/api/vaults/ghost',
-      method: 'GET',
-      url: new URL('https://x/api/vaults/ghost'),
-      req: fakeReq(),
-      res: cap.res,
-      authHeader: 'Bearer x',
-    });
-    expect(cap.statusCode).toBe(404);
-    expect(cap.body).toMatchObject({ error: expect.stringContaining('ghost') });
-  });
-
-  it('GET /api/vaults/:name surfaces attached groups via listVaultAttachments', async () => {
-    vi.stubGlobal('fetch', alwaysOk(HUB_VAULTS_BODY));
-    mockedListVaultAttachments.mockReturnValue([
-      {
-        folder: 'group-a',
-        mcpName: 'parachute-vault',
-        attachment: {
-          vaultBaseUrl: 'https://h/vault/work',
-          scope: 'vault:read',
-          tokenLabel: 'claw-a',
-          attachedAt: '2026-04-29T00:00:00Z',
-        },
-      },
-      {
-        folder: 'group-b',
-        mcpName: 'parachute-vault',
-        attachment: {
-          // Different vault — must not appear in the response.
-          vaultBaseUrl: 'https://h/vault/personal',
-          scope: 'vault:write',
-          tokenLabel: 'claw-b',
-          attachedAt: '2026-04-29T00:00:00Z',
-        },
-      },
-    ]);
-    const cap = fakeRes();
-    await handleVaultsRoute({
-      pathname: '/api/vaults/work',
-      method: 'GET',
-      url: new URL('https://x/api/vaults/work'),
-      req: fakeReq(),
-      res: cap.res,
-      authHeader: 'Bearer x',
-    });
-    expect(cap.statusCode).toBe(200);
-    const body = cap.body as { vault: unknown; attachedGroups: Array<{ folder: string }> };
-    expect(body.vault).toMatchObject({ name: 'work' });
-    expect(body.attachedGroups).toHaveLength(1);
-    expect(body.attachedGroups[0]).toMatchObject({ folder: 'group-a', tokenLabel: 'claw-a' });
-  });
-
-  it('GET /api/vaults/:name/tokens enriches each token with attachedTo by tokenLabel', async () => {
-    const fetchStub = vi
-      .fn()
-      // 1st call: hub well-known (resolveVaultBaseUrl)
-      .mockResolvedValueOnce(jsonOk(HUB_VAULTS_BODY))
-      // 2nd call: vault GET /tokens
-      .mockResolvedValueOnce(
-        jsonOk({
-          tokens: [
-            { id: 't_1', label: 'claw-work', scopes: ['vault:read'] },
-            { id: 't_2', label: 'orphan-token', scopes: ['vault:read'] },
-          ],
-        }),
-      );
-    vi.stubGlobal('fetch', fetchStub);
-    mockedListVaultAttachments.mockReturnValue([
-      {
-        folder: 'group-a',
-        mcpName: 'parachute-vault',
-        attachment: {
-          vaultBaseUrl: 'https://h/vault/work',
-          scope: 'vault:read',
-          tokenLabel: 'claw-work',
-          attachedAt: '2026-04-29T00:00:00Z',
-        },
-      },
-    ]);
-
-    const cap = fakeRes();
-    await handleVaultsRoute({
-      pathname: '/api/vaults/work/tokens',
-      method: 'GET',
-      url: new URL('https://x/api/vaults/work/tokens'),
-      req: fakeReq(),
-      res: cap.res,
-      authHeader: 'Bearer the-jwt',
-    });
-    expect(cap.statusCode).toBe(200);
-    const body = cap.body as { tokens: Array<{ id: string; attachedTo: Array<{ folder: string }> }> };
-    const claw = body.tokens.find((t) => t.id === 't_1');
-    const orphan = body.tokens.find((t) => t.id === 't_2');
-    expect(claw?.attachedTo).toEqual([{ folder: 'group-a', scope: 'vault:read' }]);
-    expect(orphan?.attachedTo).toEqual([]);
-    // Vault was hit with the operator's JWT verbatim.
-    expect(fetchStub).toHaveBeenLastCalledWith(
-      'https://h/vault/work/tokens',
-      expect.objectContaining({
-        headers: expect.objectContaining({ Authorization: 'Bearer the-jwt' }),
-      }),
-    );
-  });
-
-  it('GET /api/vaults/:name/tokens mirrors a vault 401 verbatim (consent prompt path)', async () => {
-    const fetchStub = vi
-      .fn()
-      .mockResolvedValueOnce(jsonOk(HUB_VAULTS_BODY))
-      .mockResolvedValueOnce(jsonOk({ error: 'missing vault:work:admin' }, 401));
-    vi.stubGlobal('fetch', fetchStub);
-    const cap = fakeRes();
-    await handleVaultsRoute({
-      pathname: '/api/vaults/work/tokens',
-      method: 'GET',
-      url: new URL('https://x/api/vaults/work/tokens'),
-      req: fakeReq(),
-      res: cap.res,
-      authHeader: 'Bearer x',
-    });
-    expect(cap.statusCode).toBe(401);
-    expect(cap.body).toMatchObject({ error: 'missing vault:work:admin' });
-  });
-
-  it('POST /api/vaults/:name/tokens forwards body and mirrors the vault 201', async () => {
-    const fetchStub = vi
-      .fn()
-      .mockResolvedValueOnce(jsonOk(HUB_VAULTS_BODY))
-      .mockResolvedValueOnce(jsonOk({ id: 't_new', token: 'pvt_new', label: 'fresh' }, 201));
-    vi.stubGlobal('fetch', fetchStub);
-    const cap = fakeRes();
-    await handleVaultsRoute({
-      pathname: '/api/vaults/work/tokens',
-      method: 'POST',
-      url: new URL('https://x/api/vaults/work/tokens'),
-      req: fakeReq({ label: 'fresh', scopes: ['vault:read'] }),
-      res: cap.res,
-      authHeader: 'Bearer x',
-    });
-    expect(cap.statusCode).toBe(201);
-    expect(cap.body).toMatchObject({ id: 't_new' });
-    const [, init] = fetchStub.mock.calls[1] as [string, RequestInit];
-    expect(JSON.parse(init.body as string)).toMatchObject({
-      label: 'fresh',
-      scopes: ['vault:read'],
-    });
-  });
-
-  it('POST /api/vaults/:name/tokens returns 400 on invalid JSON body', async () => {
-    vi.stubGlobal('fetch', alwaysOk(HUB_VAULTS_BODY));
-    const badReq = Object.assign(Object.create(null), {
-      [Symbol.asyncIterator]: async function* () {
-        yield Buffer.from('{not-json');
-      },
-    }) as http.IncomingMessage;
-    const cap = fakeRes();
-    await handleVaultsRoute({
-      pathname: '/api/vaults/work/tokens',
-      method: 'POST',
-      url: new URL('https://x/api/vaults/work/tokens'),
-      req: badReq,
-      res: cap.res,
-      authHeader: 'Bearer x',
-    });
-    expect(cap.statusCode).toBe(400);
-  });
-
-  it('DELETE /api/vaults/:name/tokens/:id forwards and mirrors the vault 200', async () => {
-    const fetchStub = vi
-      .fn()
-      .mockResolvedValueOnce(jsonOk(HUB_VAULTS_BODY))
-      .mockResolvedValueOnce(jsonOk({ ok: true }));
-    vi.stubGlobal('fetch', fetchStub);
-    const cap = fakeRes();
-    await handleVaultsRoute({
-      pathname: '/api/vaults/work/tokens/t_abc123',
-      method: 'DELETE',
-      url: new URL('https://x/api/vaults/work/tokens/t_abc123'),
-      req: fakeReq(),
-      res: cap.res,
-      authHeader: 'Bearer x',
-    });
-    expect(cap.statusCode).toBe(200);
-    expect(fetchStub).toHaveBeenLastCalledWith(
-      'https://h/vault/work/tokens/t_abc123',
-      expect.objectContaining({ method: 'DELETE' }),
-    );
-  });
-
-  it('returns 404 for token routes when vault name is unknown', async () => {
-    vi.stubGlobal('fetch', alwaysOk(HUB_VAULTS_BODY));
-    const cap = fakeRes();
-    await handleVaultsRoute({
-      pathname: '/api/vaults/ghost/tokens',
-      method: 'GET',
-      url: new URL('https://x/api/vaults/ghost/tokens'),
-      req: fakeReq(),
-      res: cap.res,
-      authHeader: 'Bearer x',
-    });
-    expect(cap.statusCode).toBe(404);
-  });
-
-  it('returns false for an unmatched path so the dispatcher falls through', async () => {
-    const cap = fakeRes();
-    const handled = await handleVaultsRoute({
-      pathname: '/api/something-else',
-      method: 'GET',
-      url: new URL('https://x/api/something-else'),
-      req: fakeReq(),
-      res: cap.res,
-      authHeader: 'Bearer x',
-    });
-    expect(handled).toBe(false);
-  });
-});

package/src/web/routes/vaults.ts

@@ -1,225 +0,0 @@
-/**
- * /api/vaults — vault management surface for `/agent/vaults`.
- *
- * Five endpoints, plus a list endpoint that lived inline in `server.ts`
- * before this module landed. All admin operations forward the operator's
- * hub-issued session JWT to the vault unmodified — see
- * `docs/design/2026-04-29-vault-management-ui.md` § Admin auth model and
- * `src/web/vault-proxy.ts` for the rationale.
- *
- * Scope at the paraclaw boundary is checked by `server.ts` via
- * `pickVaultScope()` before dispatch reaches this handler. The vault
- * validates `vault:<name>:admin` independently — paraclaw doesn't downgrade
- * or re-issue. A 401/403 from the vault is mirrored verbatim so the
- * browser can trigger an OAuth consent flow for the missing narrow scope.
- */
-import http from 'node:http';
-
-import { CENTRAL_DB_PATH } from '../../config.js';
-import { openDb } from '../../db/connection.js';
-import { listVaultAttachments } from '../../parachute/vault-mcp.js';
-import { clearHubDiscoveryCache, fetchHubVaults, type VaultListing } from '../hub-discovery.js';
-import { forwardToVault, resolveVaultBaseUrl } from '../vault-proxy.js';
-
-interface VaultTokenRecord {
-  id: string;
-  label: string;
-  scopes?: string[];
-  permission?: string;
-  expires_at?: string | null;
-  created_at?: string;
-  last_used_at?: string | null;
-}
-
-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 listGroupFolders(): string[] {
-  const db = openDb(CENTRAL_DB_PATH, { readonly: true });
-  try {
-    return db
-      .prepare<{ folder: string }>('SELECT folder FROM agent_groups')
-      .all()
-      .map((r) => r.folder);
-  } finally {
-    db.close();
-  }
-}
-
-/**
- * Build the "attached to" map for a vault: which agent groups currently
- * have a parachute.json record pointing at this vault, keyed by tokenLabel
- * for cheap merge into the tokens listing.
- *
- * Match by `vaultBaseUrl` (canonical, hub-published form, trailing slashes
- * already trimmed at write time in `attachVaultToGroup`). Tokens without a
- * matching group are still surfaced — they show as orphans in the UI.
- */
-function buildAttachedByLabel(vaultBaseUrl: string): Map<string, { folder: string; scope: string }[]> {
-  const target = vaultBaseUrl.replace(/\/+$/, '');
-  const folders = listGroupFolders();
-  const entries = listVaultAttachments(folders);
-  const byLabel = new Map<string, { folder: string; scope: string }[]>();
-  for (const e of entries) {
-    if (e.attachment.vaultBaseUrl.replace(/\/+$/, '') !== target) continue;
-    const list = byLabel.get(e.attachment.tokenLabel) ?? [];
-    list.push({ folder: e.folder, scope: e.attachment.scope });
-    byLabel.set(e.attachment.tokenLabel, list);
-  }
-  return byLabel;
-}
-
-export interface VaultsRouteContext {
-  pathname: string;
-  method: string;
-  url: URL;
-  req: http.IncomingMessage;
-  res: http.ServerResponse;
-  /** Operator's full `Authorization` header value, forwarded to vault. */
-  authHeader: string;
-}
-
-export async function handleVaultsRoute(ctx: VaultsRouteContext): Promise<boolean> {
-  const { pathname, method, req, res, authHeader } = ctx;
-
-  if (pathname === '/api/vaults' && method === 'GET') {
-    try {
-      const vaults = await fetchHubVaults();
-      json(res, 200, { vaults });
-    } catch (err) {
-      error(res, 502, err instanceof Error ? err.message : String(err));
-    }
-    return true;
-  }
-
-  if (pathname === '/api/vaults/refresh' && method === 'POST') {
-    clearHubDiscoveryCache();
-    try {
-      const vaults = await fetchHubVaults();
-      json(res, 200, { vaults });
-    } catch (err) {
-      error(res, 502, err instanceof Error ? err.message : String(err));
-    }
-    return true;
-  }
-
-  // Token-id-bound routes — match before the parent /tokens path so the
-  // more-specific match wins.
-  const tokenById = pathname.match(/^\/api\/vaults\/([^/]+)\/tokens\/([^/]+)$/);
-  if (tokenById && method === 'DELETE') {
-    const name = decodeURIComponent(tokenById[1]);
-    const id = decodeURIComponent(tokenById[2]);
-    const baseUrl = await resolveVaultBaseUrl(name);
-    if (!baseUrl) {
-      error(res, 404, `vault not found: ${name}`);
-      return true;
-    }
-    const result = await forwardToVault({
-      method: 'DELETE',
-      vaultBaseUrl: baseUrl,
-      subpath: `/tokens/${encodeURIComponent(id)}`,
-      authHeader,
-    });
-    json(res, result.status, result.body);
-    return true;
-  }
-
-  const tokensList = pathname.match(/^\/api\/vaults\/([^/]+)\/tokens$/);
-  if (tokensList) {
-    const name = decodeURIComponent(tokensList[1]);
-    const baseUrl = await resolveVaultBaseUrl(name);
-    if (!baseUrl) {
-      error(res, 404, `vault not found: ${name}`);
-      return true;
-    }
-    if (method === 'GET') {
-      const result = await forwardToVault({
-        method: 'GET',
-        vaultBaseUrl: baseUrl,
-        subpath: '/tokens',
-        authHeader,
-      });
-      if (result.status >= 400) {
-        json(res, result.status, result.body);
-        return true;
-      }
-      // Merge attached-to-group derivation by tokenLabel. Vault returns
-      // `{tokens: [{id, label, ...}]}`; we add `attachedTo: [{folder, scope}]`
-      // to each row so the UI doesn't need a separate fetch.
-      const tokens = (result.body as { tokens?: VaultTokenRecord[] }).tokens ?? [];
-      const byLabel = buildAttachedByLabel(baseUrl);
-      const enriched = tokens.map((t) => ({
-        ...t,
-        attachedTo: byLabel.get(t.label) ?? [],
-      }));
-      json(res, 200, { tokens: enriched });
-      return true;
-    }
-    if (method === 'POST') {
-      let body: { label?: string; scopes?: unknown; expires_at?: string | null };
-      try {
-        body = await readJsonBody(req);
-      } catch {
-        error(res, 400, 'invalid JSON body');
-        return true;
-      }
-      const result = await forwardToVault({
-        method: 'POST',
-        vaultBaseUrl: baseUrl,
-        subpath: '/tokens',
-        authHeader,
-        body,
-      });
-      json(res, result.status, result.body);
-      return true;
-    }
-    error(res, 405, `method not allowed: ${method} ${pathname}`);
-    return true;
-  }
-
-  const detail = pathname.match(/^\/api\/vaults\/([^/]+)$/);
-  if (detail && method === 'GET') {
-    const name = decodeURIComponent(detail[1]);
-    let vaults: VaultListing[];
-    try {
-      vaults = await fetchHubVaults();
-    } catch (err) {
-      error(res, 502, err instanceof Error ? err.message : String(err));
-      return true;
-    }
-    const hit = vaults.find((v) => v.name === name);
-    if (!hit) {
-      error(res, 404, `vault not found: ${name}`);
-      return true;
-    }
-    const folders = listGroupFolders();
-    const entries = listVaultAttachments(folders).filter(
-      (e) => e.attachment.vaultBaseUrl.replace(/\/+$/, '') === hit.url.replace(/\/+$/, ''),
-    );
-    json(res, 200, {
-      vault: hit,
-      attachedGroups: entries.map((e) => ({
-        folder: e.folder,
-        mcpName: e.mcpName,
-        scope: e.attachment.scope,
-        tokenLabel: e.attachment.tokenLabel,
-        attachedAt: e.attachment.attachedAt,
-      })),
-    });
-    return true;
-  }
-
-  return false;
-}

package/src/web/server-version.test.ts

@@ -1,16 +0,0 @@
-/**
- * Regression test for paraclaw#101 — SERVICE_VERSION must read from
- * package.json, not be hardcoded. Without this dynamism, every rc bump
- * silently lies about the running version.
- */
-import { describe, expect, test } from 'vitest';
-
-import { SERVICE_VERSION } from './server.js';
-import pkg from '../../package.json' with { type: 'json' };
-
-describe('SERVICE_VERSION', () => {
-  test('matches package.json version (no hardcoded drift)', () => {
-    expect(SERVICE_VERSION).toBe(pkg.version);
-    expect(SERVICE_VERSION).toMatch(/^\d+\.\d+\.\d+(-[a-z]+\.\d+)?$/);
-  });
-});