@openparachute/agent 0.1.0

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

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

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

@@ -0,0 +1,16 @@
+/**
+ * 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+)?$/);
+  });
+});