@openparachute/agent 0.1.0

package/src/web/routes/secrets.ts

@@ -0,0 +1,282 @@
+/**
+ * /api/secrets — CRUD over paraclaw's local AES-256-GCM secret store.
+ *
+ * Auth: `agent:admin` for mutation (POST/PUT/DELETE), `agent:read` for GET.
+ * The mutation gate is admin-not-write because a write-only token would
+ * otherwise be enough to swap any vault credential and silently MITM
+ * downstream API calls. Plaintext values are accepted on POST and never
+ * returned by any GET — `listSecrets()` is metadata-only by design. There
+ * is no "show value" endpoint; if a human needs the value they should
+ * re-mint (or back it out via the original platform's UI).
+ */
+import http from 'node:http';
+
+import { getAgentGroupSecretMode, getAgentGroupSecretModes, setAgentGroupSecretMode } from '../../db/agent-groups.js';
+import {
+  type AssignedMode,
+  type SecretKind,
+  type SecretRow,
+  addAssignment,
+  deleteSecret,
+  findStaleSessionsForSecret,
+  getSecretById,
+  listAssignments,
+  listSecrets,
+  putSecret,
+  removeAssignment,
+  replaceAssignments,
+} from '../../secrets/index.js';
+import type { SecretMode } from '../../types.js';
+
+const ALLOWED_KINDS: SecretKind[] = ['channel-token', 'api-key', 'generic'];
+const ALLOWED_MODES: AssignedMode[] = ['all', 'selective'];
+
+// Camel-cased view shape consumed by `web/ui/src/lib/api.ts:SecretView`.
+// The DB layer stores snake_case; we transform at the boundary so the UI
+// stays in idiomatic JS and the storage stays in idiomatic SQL.
+interface SecretView {
+  id: string;
+  name: string;
+  kind: SecretKind;
+  agentGroupId: string | null;
+  assignedMode: 'all' | 'selective';
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Per-secret `assignedMode` is now derived from the recipient agent group's
+ * `secret_mode` (paraclaw#9 — modes moved off the per-secret row). For a
+ * scoped secret we read its containing group; globals report `'all'` because
+ * a global is unconditionally in-scope and the recipient group's mode gates
+ * actual injection. Field stays in the response shape for UI continuity.
+ *
+ * Pass `modes` when projecting a list — callers prefetch one query for all
+ * groups touched by the rows, avoiding the per-row SELECT this helper would
+ * otherwise issue. Single-row paths can omit it.
+ */
+function toView(r: SecretRow, modes?: Map<string, SecretMode>): SecretView {
+  const assignedMode: AssignedMode = r.agent_group_id
+    ? ((modes ? modes.get(r.agent_group_id) : getAgentGroupSecretMode(r.agent_group_id)) ?? 'selective')
+    : 'all';
+  return {
+    id: r.id,
+    name: r.name,
+    kind: r.kind,
+    agentGroupId: r.agent_group_id,
+    assignedMode,
+    createdAt: r.created_at,
+    updatedAt: r.updated_at,
+  };
+}
+
+interface PutBody {
+  name?: string;
+  value?: string;
+  kind?: string;
+  // Both the snake_case (legacy) and camelCase (UI) forms are accepted on
+  // input — saves a coordinated migration, costs one or-fallback line.
+  agent_group_id?: string | null;
+  agentGroupId?: string | null;
+  /**
+   * Accepted on POST for backward-compatibility with the existing UI/MCP
+   * callers that still send it. Now applies to the recipient agent_group
+   * (paraclaw#9): scoped secret + assigned_mode='all' flips the parent
+   * group's secret_mode to 'all'. No-op for globals (no parent group).
+   */
+  assigned_mode?: string;
+}
+
+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;
+}
+
+export interface SecretsRouteContext {
+  pathname: string;
+  method: string;
+  url: URL;
+  req: http.IncomingMessage;
+  res: http.ServerResponse;
+}
+
+/**
+ * Returns true if the route handled the request, false to fall through.
+ */
+export async function handleSecretsRoute(ctx: SecretsRouteContext): Promise<boolean> {
+  const { pathname, method, url, req, res } = ctx;
+
+  if (pathname === '/api/secrets' && method === 'GET') {
+    const groupParam = url.searchParams.get('agent_group_id');
+    let scope: string | null | undefined = undefined;
+    if (groupParam !== null) scope = groupParam === '' ? null : groupParam;
+    const rows = listSecrets(scope);
+    const groupIds = [...new Set(rows.map((r) => r.agent_group_id).filter((x): x is string => !!x))];
+    const modes = getAgentGroupSecretModes(groupIds);
+    json(res, 200, { secrets: rows.map((r) => toView(r, modes)) });
+    return true;
+  }
+
+  if (pathname === '/api/secrets' && method === 'POST') {
+    let body: PutBody;
+    try {
+      body = await readJsonBody<PutBody>(req);
+    } catch {
+      error(res, 400, 'invalid JSON body');
+      return true;
+    }
+    const name = (body.name ?? '').trim();
+    if (!name) {
+      error(res, 400, 'name is required');
+      return true;
+    }
+    if (typeof body.value !== 'string' || body.value.length === 0) {
+      error(res, 400, 'value is required');
+      return true;
+    }
+    const kind = (body.kind ?? 'generic') as SecretKind;
+    if (!ALLOWED_KINDS.includes(kind)) {
+      error(res, 400, `invalid kind: ${kind}`);
+      return true;
+    }
+    const mode = body.assigned_mode === undefined ? undefined : (body.assigned_mode as AssignedMode);
+    if (mode !== undefined && !ALLOWED_MODES.includes(mode)) {
+      error(res, 400, `invalid assigned_mode: ${mode}`);
+      return true;
+    }
+
+    const agentGroupId = body.agentGroupId ?? body.agent_group_id ?? null;
+    const id = putSecret(name, body.value, {
+      kind,
+      agent_group_id: agentGroupId,
+    });
+    if (mode !== undefined && agentGroupId) {
+      setAgentGroupSecretMode(agentGroupId, mode);
+    }
+    // Re-read so the response carries the canonical timestamps the upsert
+    // wrote (rather than guessing). Same scope filter — listSecrets returns
+    // both global + scoped rows when scope is the agent id, so we narrow
+    // by id manually. Fast path: in practice <100 secrets per install.
+    const view = listSecrets(agentGroupId).find((r) => r.id === id);
+    if (!view) {
+      // Should never happen — putSecret just wrote the row. Surfaced as
+      // 500 so a regression is loud, not silently masked.
+      error(res, 500, `secret ${id} disappeared between write and read`);
+      return true;
+    }
+    json(res, 200, { secret: toView(view) });
+    return true;
+  }
+
+  // Stale-sessions probe — match before the bare /:id DELETE so the more-specific
+  // path wins. Surface for the post-save banner: which running containers were
+  // spawned BEFORE this secret's last update AND would inject it on next spawn?
+  const staleMatch = pathname.match(/^\/api\/secrets\/([^/]+)\/stale-sessions$/);
+  if (staleMatch && method === 'GET') {
+    const id = decodeURIComponent(staleMatch[1]);
+    const meta = getSecretById(id);
+    if (!meta) {
+      error(res, 404, `secret not found: ${id}`);
+      return true;
+    }
+    const stale = findStaleSessionsForSecret(id);
+    json(res, 200, {
+      secretId: id,
+      secretUpdatedAt: meta.updated_at,
+      staleSessions: stale,
+    });
+    return true;
+  }
+
+  // Assignments — match before the bare /:id DELETE so the more-specific path wins.
+  const assignOne = pathname.match(/^\/api\/secrets\/([^/]+)\/assignments\/([^/]+)$/);
+  if (assignOne && method === 'DELETE') {
+    const secretId = decodeURIComponent(assignOne[1]);
+    const groupId = decodeURIComponent(assignOne[2]);
+    const ok = removeAssignment(secretId, groupId);
+    if (!ok) {
+      error(res, 404, `assignment not found: ${secretId} -> ${groupId}`);
+      return true;
+    }
+    json(res, 200, { secretId, agentGroupId: groupId, removed: true });
+    return true;
+  }
+
+  const assignList = pathname.match(/^\/api\/secrets\/([^/]+)\/assignments$/);
+  if (assignList) {
+    const secretId = decodeURIComponent(assignList[1]);
+    if (method === 'GET') {
+      json(res, 200, { secretId, agentGroupIds: listAssignments(secretId) });
+      return true;
+    }
+    if (method === 'PUT') {
+      let body: { agentGroupIds?: unknown };
+      try {
+        body = await readJsonBody<{ agentGroupIds?: unknown }>(req);
+      } catch {
+        error(res, 400, 'invalid JSON body');
+        return true;
+      }
+      const ids = body.agentGroupIds;
+      if (!Array.isArray(ids) || !ids.every((x) => typeof x === 'string')) {
+        error(res, 400, 'agentGroupIds must be a string[]');
+        return true;
+      }
+      try {
+        replaceAssignments(secretId, ids as string[]);
+      } catch (err) {
+        error(res, 404, err instanceof Error ? err.message : String(err));
+        return true;
+      }
+      json(res, 200, { secretId, agentGroupIds: listAssignments(secretId) });
+      return true;
+    }
+    if (method === 'POST') {
+      let body: { agentGroupId?: unknown };
+      try {
+        body = await readJsonBody<{ agentGroupId?: unknown }>(req);
+      } catch {
+        error(res, 400, 'invalid JSON body');
+        return true;
+      }
+      if (typeof body.agentGroupId !== 'string' || !body.agentGroupId.trim()) {
+        error(res, 400, 'agentGroupId is required');
+        return true;
+      }
+      try {
+        addAssignment(secretId, body.agentGroupId);
+      } catch (err) {
+        // Likely a FK violation (unknown secret_id or agent_group_id).
+        // Return 400 rather than 500 so the UI can surface a clean message.
+        error(res, 400, err instanceof Error ? err.message : String(err));
+        return true;
+      }
+      json(res, 201, { secretId, agentGroupId: body.agentGroupId, added: true });
+      return true;
+    }
+  }
+
+  const del = pathname.match(/^\/api\/secrets\/([^/]+)$/);
+  if (del && method === 'DELETE') {
+    const id = decodeURIComponent(del[1]);
+    const ok = deleteSecret(id);
+    if (!ok) {
+      error(res, 404, `secret not found: ${id}`);
+      return true;
+    }
+    json(res, 200, { id, deleted: true });
+    return true;
+  }
+
+  return false;
+}

package/src/web/routes/sessions.ts

@@ -0,0 +1,123 @@
+/**
+ * /api/sessions — global session list + per-session close.
+ *
+ * The list aggregates every agent group's sessions into one flat view so
+ * the /sessions page can show "everything alive across the install" without
+ * making N requests against /api/groups/:folder/status. Liveness uses the
+ * same heartbeat-mtime computation as `getGroupStatus` (90s default
+ * threshold) — see src/parachute/group-status.ts for the rationale.
+ *
+ * Close behavior: marks the row `status='closed'`, `container_status='stopped'`
+ * AND calls `killContainer` to actually stop the running Docker container.
+ * Post web-server merge, the host + web share one process and one
+ * `activeContainers` Map, so `killContainer` is no longer a no-op from this
+ * route — it reaps the container synchronously and the operator's "Close"
+ * click takes effect immediately rather than waiting for the sweep ceiling.
+ */
+import http from 'node:http';
+
+import fs from 'node:fs';
+
+import { getAllAgentGroups } from '../../db/agent-groups.js';
+import { killContainer } from '../../container-runner.js';
+import { getSession, getSessionsByAgentGroup, updateSession } from '../../db/sessions.js';
+import { log } from '../../log.js';
+import { DEFAULT_ALIVE_THRESHOLD_MS } from '../../parachute/group-status.js';
+import { heartbeatPath } from '../../session-manager.js';
+
+interface SessionView {
+  id: string;
+  agentGroupId: string;
+  agentGroupFolder: string;
+  agentGroupName: string;
+  messagingGroupId: string | null;
+  status: 'active' | 'closed';
+  containerStatus: 'running' | 'idle' | 'stopped';
+  alive: boolean;
+  createdAt: string;
+  lastActiveAt: string | null;
+  lastHeartbeatAt: string | null;
+}
+
+function readHeartbeatMtimeMs(agentGroupId: string, sessionId: string): number {
+  try {
+    return fs.statSync(heartbeatPath(agentGroupId, sessionId)).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+function listAllSessions(): SessionView[] {
+  const nowMs = Date.now();
+  const out: SessionView[] = [];
+  for (const group of getAllAgentGroups()) {
+    for (const s of getSessionsByAgentGroup(group.id)) {
+      const heartbeatMs = readHeartbeatMtimeMs(group.id, s.id);
+      const alive = heartbeatMs > 0 && nowMs - heartbeatMs <= DEFAULT_ALIVE_THRESHOLD_MS;
+      out.push({
+        id: s.id,
+        agentGroupId: group.id,
+        agentGroupFolder: group.folder,
+        agentGroupName: group.name,
+        messagingGroupId: s.messaging_group_id,
+        status: s.status,
+        containerStatus: s.container_status,
+        alive,
+        createdAt: s.created_at,
+        lastActiveAt: s.last_active,
+        lastHeartbeatAt: heartbeatMs > 0 ? new Date(heartbeatMs).toISOString() : null,
+      });
+    }
+  }
+  // Newest first — matches the UI's natural reading order.
+  out.sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1));
+  return out;
+}
+
+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 });
+
+export interface SessionsRouteContext {
+  pathname: string;
+  method: string;
+  res: http.ServerResponse;
+}
+
+export async function handleSessionsRoute(ctx: SessionsRouteContext): Promise<boolean> {
+  const { pathname, method, res } = ctx;
+
+  if (pathname === '/api/sessions' && method === 'GET') {
+    json(res, 200, { sessions: listAllSessions() });
+    return true;
+  }
+
+  // POST /api/sessions/:id/close
+  const closeMatch = pathname.match(/^\/api\/sessions\/([^/]+)\/close$/);
+  if (closeMatch && method === 'POST') {
+    const id = decodeURIComponent(closeMatch[1]);
+    const session = getSession(id);
+    if (!session) {
+      error(res, 404, `session not found: ${id}`);
+      return true;
+    }
+    if (session.status === 'closed') {
+      // Idempotent — already closed, return the current view.
+      json(res, 200, { id, status: 'closed' });
+      return true;
+    }
+    updateSession(id, { status: 'closed', container_status: 'stopped' });
+    // Kill the running container synchronously. Post web-merge, host + web
+    // share `activeContainers`, so this is no longer a no-op.
+    killContainer(id, 'closed via web');
+    log.info('session closed via web', { sessionId: id });
+    json(res, 200, { id, status: 'closed' });
+    return true;
+  }
+
+  return false;
+}

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

@@ -0,0 +1,106 @@
+/**
+ * Tests for `/api/settings/operator-identity` and the underlying
+ * `listOperatorIdentities` helper. Exercises the "first owner per
+ * channel" derivation against a real in-memory DB seeded with
+ * representative `users` + `user_roles` rows.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { closeDb, initTestDb, runMigrations } from '../../db/index.js';
+import { upsertUser } from '../../modules/permissions/db/users.js';
+import { grantRole } from '../../modules/permissions/db/user-roles.js';
+import { listOperatorIdentities } from './settings.js';
+
+beforeEach(() => {
+  const db = initTestDb();
+  runMigrations(db);
+});
+
+afterEach(() => {
+  closeDb();
+});
+
+const now = (): string => new Date().toISOString();
+
+function seedUser(id: string, kind: string): void {
+  upsertUser({ id, kind, display_name: null, created_at: now() });
+}
+
+describe('listOperatorIdentities', () => {
+  it('returns empty record on a fresh install with no owners', () => {
+    expect(listOperatorIdentities()).toEqual({});
+  });
+
+  it('returns the owner native id for each channel', () => {
+    seedUser('telegram:1190596288', 'telegram');
+    grantRole({
+      user_id: 'telegram:1190596288',
+      role: 'owner',
+      agent_group_id: null,
+      granted_by: null,
+      granted_at: now(),
+    });
+
+    expect(listOperatorIdentities()).toEqual({
+      telegram: '1190596288',
+    });
+  });
+
+  it('returns oldest owner per channel when multiple owners exist', () => {
+    seedUser('telegram:1111', 'telegram');
+    seedUser('telegram:2222', 'telegram');
+    grantRole({
+      user_id: 'telegram:1111',
+      role: 'owner',
+      agent_group_id: null,
+      granted_by: null,
+      granted_at: '2026-01-01T00:00:00.000Z',
+    });
+    grantRole({
+      user_id: 'telegram:2222',
+      role: 'owner',
+      agent_group_id: null,
+      granted_by: null,
+      granted_at: '2026-02-01T00:00:00.000Z',
+    });
+
+    expect(listOperatorIdentities()).toEqual({ telegram: '1111' });
+  });
+
+  it('groups one identity per channel when owner has multi-channel presence', () => {
+    seedUser('telegram:1190596288', 'telegram');
+    seedUser('discord:9876543210', 'discord');
+    grantRole({
+      user_id: 'telegram:1190596288',
+      role: 'owner',
+      agent_group_id: null,
+      granted_by: null,
+      granted_at: '2026-01-01T00:00:00.000Z',
+    });
+    grantRole({
+      user_id: 'discord:9876543210',
+      role: 'owner',
+      agent_group_id: null,
+      granted_by: null,
+      granted_at: '2026-01-02T00:00:00.000Z',
+    });
+
+    expect(listOperatorIdentities()).toEqual({
+      telegram: '1190596288',
+      discord: '9876543210',
+    });
+  });
+
+  it('ignores admins (only owners count as the install operator)', () => {
+    seedUser('telegram:7777', 'telegram');
+    grantRole({
+      user_id: 'telegram:7777',
+      role: 'admin',
+      agent_group_id: null,
+      granted_by: null,
+      granted_at: now(),
+    });
+
+    expect(listOperatorIdentities()).toEqual({});
+  });
+});