@openparachute/agent 0.1.0

package/src/web/routes/settings.ts

@@ -0,0 +1,247 @@
+/**
+ * /api/settings/approval-routing — read + write the channel-default bot
+ * for approval delivery.
+ *
+ * Backs the `/agent/settings/approvals` page. The shape it exposes is
+ * one row per (approver, channel) pair: which bot's DM currently sits
+ * in the `bot_id = ''` slot of `user_dms`, and which other bots on
+ * that channel are reachable.
+ *
+ * Why a per-(approver, channel) view: the channel-default cache is
+ * keyed on `(user_id, channel_type, '')`, so each owner / admin has
+ * their own configurable default. With one owner today (Aaron's
+ * install) it collapses to "my settings"; with future co-admins it
+ * naturally extends without a schema change.
+ *
+ * Available bots are sourced from active adapters only — operators
+ * can't route through a bot whose token is in secrets but never
+ * spawned (orphan secret rule, see channel-registry.spawnSecretsBackedBots).
+ */
+import http from 'node:http';
+
+import { getActiveAdapters } from '../../channels/channel-registry.js';
+import { decodePlatformIdAs } from '../../platform-id.js';
+import { getMessagingGroup } from '../../db/messaging-groups.js';
+import { log } from '../../log.js';
+import { ensureUserDm } from '../../modules/permissions/user-dm.js';
+import { getUserDm, getUserDmsForUser, upsertUserDm } from '../../modules/permissions/db/user-dms.js';
+import { getGlobalAdmins, getOwners } from '../../modules/permissions/db/user-roles.js';
+
+/**
+ * Per-channel native id for the install's primary operator. Backs the
+ * `/channels/new` form's "bot admin user" pre-fill so an operator wiring
+ * a second telegram bot doesn't have to look up their user id again.
+ *
+ * The "operator" is the oldest global owner (from `user_roles`); their
+ * `users.id` carries the channel-prefixed identity already (`telegram:1190596288`),
+ * so the lookup is just "split on first colon, group by channel". No new
+ * schema needed — the row already represents the privileged user for
+ * approvals, which is the same user the form is asking to capture.
+ *
+ * Returns the FIRST owner identity per channel — multi-owner installs
+ * settle to whichever owner was granted first. Edge case: a fresh install
+ * with no owner yet returns an empty record, and the form falls back to
+ * the empty input.
+ */
+export function listOperatorIdentities(): Record<string, string> {
+  const owners = getOwners();
+  const byChannel: Record<string, string> = {};
+  for (const owner of owners) {
+    const sep = owner.user_id.indexOf(':');
+    if (sep < 0) continue;
+    const channelType = owner.user_id.slice(0, sep);
+    const nativeId = owner.user_id.slice(sep + 1);
+    if (!byChannel[channelType]) byChannel[channelType] = nativeId;
+  }
+  return byChannel;
+}
+
+interface BotChoice {
+  botId: string;
+  /** Adapter `name` field — usually `<channelType>:<botId>` for multi-bot or just `<channelType>`. */
+  label: string;
+}
+
+interface ApprovalRoutingRow {
+  /** Namespaced approver user id (`<channel>:<handle>`). */
+  userId: string;
+  /** Channel-type the row applies to (`telegram`, `discord`, …). */
+  channelType: string;
+  /**
+   * Bot id currently sitting in the channel-default slot. Decoded from
+   * the `messaging_groups.platform_id` of the row at `bot_id = ''`.
+   * Null when no channel-default is set (no `pickApprovalDelivery`
+   * fallback exists for this user yet).
+   */
+  currentBotId: string | null;
+  /** Active bots on this channel the operator can route through. */
+  availableBots: BotChoice[];
+}
+
+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;
+}
+
+/**
+ * Approver users today are the union of owners + global admins. Scoped
+ * admins are excluded — their channel-default is per-agent-group at
+ * the call site, not a global routing concern.
+ */
+function listApproverUserIds(): string[] {
+  const seen = new Set<string>();
+  const ordered: string[] = [];
+  const add = (id: string): void => {
+    if (!seen.has(id)) {
+      seen.add(id);
+      ordered.push(id);
+    }
+  };
+  for (const r of getOwners()) add(r.user_id);
+  for (const r of getGlobalAdmins()) add(r.user_id);
+  return ordered;
+}
+
+export function listSettings(): ApprovalRoutingRow[] {
+  // Pre-bucket active adapters by channel type so we can query once per
+  // (user, channel) row without re-scanning the registry.
+  const adaptersByChannel = new Map<string, BotChoice[]>();
+  for (const adapter of getActiveAdapters()) {
+    const list = adaptersByChannel.get(adapter.channelType) ?? [];
+    list.push({ botId: adapter.botId ?? '', label: adapter.name });
+    adaptersByChannel.set(adapter.channelType, list);
+  }
+
+  const rows: ApprovalRoutingRow[] = [];
+  for (const userId of listApproverUserIds()) {
+    // Channel set for this user = channels they have ANY DM cached on,
+    // unioned with channels that have at least one active adapter (so
+    // an approver who's never been DMed yet still appears in the UI
+    // and the operator can pre-configure routing).
+    const channelTypes = new Set<string>();
+    for (const dm of getUserDmsForUser(userId)) channelTypes.add(dm.channel_type);
+    for (const channelType of adaptersByChannel.keys()) channelTypes.add(channelType);
+
+    for (const channelType of channelTypes) {
+      const defaultDm = getUserDm(userId, channelType, '');
+      let currentBotId: string | null = null;
+      if (defaultDm) {
+        const mg = getMessagingGroup(defaultDm.messaging_group_id);
+        if (mg) {
+          // platform_id is v2-shaped after startup-bootstrap. For v1 rows
+          // the decoder returns botId=null, which surfaces as "default
+          // not pinned to a specific bot" in the UI.
+          currentBotId = decodePlatformIdAs(mg.platform_id, 'v2').botId;
+        }
+      }
+      const availableBots = adaptersByChannel.get(channelType) ?? [];
+      rows.push({ userId, channelType, currentBotId, availableBots });
+    }
+  }
+  return rows;
+}
+
+interface SetDefaultBody {
+  userId?: string;
+  channelType?: string;
+  botId?: string;
+}
+
+export async function setDefault(
+  body: SetDefaultBody,
+): Promise<{ ok: true; row: ApprovalRoutingRow } | { ok: false; status: number; message: string }> {
+  const { userId, channelType, botId } = body;
+  if (!userId || !channelType || !botId) {
+    return { ok: false, status: 400, message: 'userId, channelType, and botId are required' };
+  }
+  if (!listApproverUserIds().includes(userId)) {
+    return { ok: false, status: 404, message: `not an approver: ${userId}` };
+  }
+
+  // Cold-resolve via the requested bot. Two purposes: confirms the bot
+  // can actually DM this user (catches Telegram's "bots can't initiate"
+  // before we silently re-point routing at a dead bot) and, on success,
+  // produces the messaging_group whose id we'll write into the
+  // channel-default slot.
+  const mg = await ensureUserDm(userId, { botId });
+  if (!mg) {
+    return {
+      ok: false,
+      status: 422,
+      message:
+        `Bot ${botId} cannot DM ${userId}. The user may need to message the bot first ` +
+        `(common on Telegram), or the adapter for that bot may not be running.`,
+    };
+  }
+  upsertUserDm({
+    user_id: userId,
+    channel_type: channelType,
+    bot_id: '',
+    messaging_group_id: mg.id,
+    resolved_at: new Date().toISOString(),
+  });
+
+  // Recompute the row so the client gets a fresh view without a second
+  // round-trip — same shape the list endpoint emits.
+  const all = listSettings();
+  const updated = all.find((r) => r.userId === userId && r.channelType === channelType);
+  if (!updated) {
+    // Defensive: shouldn't happen since we just wrote the row.
+    return { ok: false, status: 500, message: 'row written but disappeared on re-list' };
+  }
+  return { ok: true, row: updated };
+}
+
+export interface SettingsRouteContext {
+  pathname: string;
+  method: string;
+  req: http.IncomingMessage;
+  res: http.ServerResponse;
+}
+
+export async function handleSettingsRoute(ctx: SettingsRouteContext): Promise<boolean> {
+  const { pathname, method, req, res } = ctx;
+
+  if (pathname === '/api/settings/approval-routing' && method === 'GET') {
+    json(res, 200, { rows: listSettings() });
+    return true;
+  }
+
+  if (pathname === '/api/settings/operator-identity' && method === 'GET') {
+    json(res, 200, { byChannel: listOperatorIdentities() });
+    return true;
+  }
+
+  if (pathname === '/api/settings/approval-routing' && method === 'POST') {
+    let body: SetDefaultBody;
+    try {
+      body = await readJsonBody<SetDefaultBody>(req);
+    } catch {
+      error(res, 400, 'invalid JSON body');
+      return true;
+    }
+    const result = await setDefault(body);
+    if (!result.ok) {
+      error(res, result.status, result.message);
+      return true;
+    }
+    log.info('approval-routing default updated', {
+      userId: body.userId,
+      channelType: body.channelType,
+      botId: body.botId,
+    });
+    json(res, 200, { row: result.row });
+    return true;
+  }
+
+  return false;
+}

package/src/web/routes/setup-status.ts

@@ -0,0 +1,205 @@
+/**
+ * /api/setup/status — readiness probe consumed by the setup wizard.
+ *
+ *   - `secrets`        — AES-GCM master key file is present + readable
+ *   - `hub`            — hub origin reachable; JWKS endpoint resolves
+ *   - `vaultAttached`  — at least one agent group has a vault attached
+ *   - `channels`       — discord + telegram adapter modules present in trunk
+ *
+ * `ready` is the AND of secrets + hub + vaultAttached. Channel installs
+ * are advisory; the wizard surfaces the "install now?" CTA based on the
+ * per-channel `installed` flag, but a missing channel doesn't gate the
+ * rest of the install.
+ *
+ * Shape mirrors `web/ui/src/lib/api.ts:SetupStatus` — drift here breaks
+ * the wizard. The optional `secrets.missing` array is for surfacing
+ * specific symptoms (e.g. 'master.key' wrong-mode); empty when ok.
+ */
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+
+import { GROUPS_DIR } from '../../config.js';
+import { getDb } from '../../db/connection.js';
+import { getMasterKeyPath, loadOrCreateMasterKey } from '../../secrets/master-key.js';
+import { readVaultAttachment } from '../../parachute/vault-mcp.js';
+import { getHubOrigin } from '../auth.js';
+
+interface SetupCheck {
+  ok: boolean;
+  detail: string;
+  fix: string | null;
+  missing?: string[];
+}
+
+interface SetupStatus {
+  secrets: SetupCheck;
+  hub: SetupCheck;
+  vaultAttached: SetupCheck;
+  channels: {
+    discord: { installed: boolean };
+    telegram: { installed: boolean };
+  };
+  ready: boolean;
+}
+
+// src/channels lives at <repo>/src/channels relative to the project root.
+// The web server bootstrap chdirs to project root, so a bare relative path
+// works regardless of where Bun launched the process from.
+const CHANNELS_DIR = path.resolve('src/channels');
+
+function checkSecrets(): SetupCheck {
+  const keyPath = getMasterKeyPath();
+  // The wizard runs *before* any agent boot — generating the key here on
+  // first poll is intentional. After the file exists, every subsequent
+  // call confirms readability + permission mode.
+  try {
+    loadOrCreateMasterKey();
+  } catch (err) {
+    return {
+      ok: false,
+      detail: err instanceof Error ? err.message : String(err),
+      fix: `Inspect ${keyPath} — expected 32 raw bytes, mode 0600.`,
+      missing: ['master.key'],
+    };
+  }
+  // Mode check is best-effort: on platforms where the FS doesn't preserve
+  // POSIX bits (rare for this tool's target deployments) we still report
+  // ok=true since the key loaded — but the fix nudges toward 0600.
+  try {
+    const stat = fs.statSync(keyPath);
+    const mode = stat.mode & 0o777;
+    if (mode !== 0o600) {
+      return {
+        ok: false,
+        detail: `master.key has mode 0${mode.toString(8)}; expected 0600`,
+        fix: `chmod 600 ${keyPath}`,
+      };
+    }
+  } catch {
+    // statSync failure after a successful load is impossible in practice;
+    // if it ever fires, treat as ok=true since we already have the key.
+  }
+  return {
+    ok: true,
+    detail: `master key present at ${keyPath} (mode 0600)`,
+    fix: null,
+  };
+}
+
+async function checkHub(): Promise<SetupCheck> {
+  const origin = getHubOrigin();
+  // Probe the JWKS endpoint specifically — that's what auth.ts actually
+  // pulls on every request. A 200 with a JSON body containing keys[] is
+  // the only signal that matters; root health checks lie when /.well-known
+  // is mis-routed.
+  const url = `${origin}/.well-known/jwks.json`;
+  try {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), 1500);
+    const r = await fetch(url, { signal: ctrl.signal });
+    clearTimeout(t);
+    if (!r.ok) {
+      return {
+        ok: false,
+        detail: `JWKS at ${url} returned ${r.status}`,
+        fix: `Confirm parachute-hub is running and accessible at ${origin}.`,
+      };
+    }
+    const body = (await r.json()) as { keys?: unknown[] };
+    if (!Array.isArray(body.keys) || body.keys.length === 0) {
+      return {
+        ok: false,
+        detail: `JWKS at ${url} returned no keys`,
+        fix: `Hub may still be initializing; retry in a few seconds.`,
+      };
+    }
+    return { ok: true, detail: `hub reachable at ${origin}`, fix: null };
+  } catch (err) {
+    return {
+      ok: false,
+      detail: `${url} unreachable: ${err instanceof Error ? err.message : String(err)}`,
+      fix: `Set PARACHUTE_HUB_ORIGIN to the hub's actual origin, or start parachute-hub.`,
+    };
+  }
+}
+
+function checkVaultAttached(): SetupCheck {
+  // Agent groups are listed in central DB; vault attachment lives in
+  // `groups/<folder>/parachute.json`. The two sources have to agree —
+  // a row in agent_groups without a parachute.json means the group exists
+  // but isn't vault-bound yet.
+  let folders: string[] = [];
+  try {
+    const rows = getDb().prepare<{ folder: string }>('SELECT folder FROM agent_groups').all();
+    folders = rows.map((r) => r.folder);
+  } catch (err) {
+    return {
+      ok: false,
+      detail: `agent_groups query failed: ${err instanceof Error ? err.message : String(err)}`,
+      fix: 'Run migrations: `bun src/index.ts` once to bring the central DB up to date.',
+    };
+  }
+  if (folders.length === 0) {
+    return {
+      ok: false,
+      detail: 'no agent groups created yet',
+      fix: 'Create an agent group from /groups → "+ New".',
+    };
+  }
+  const attached = folders.filter((f) => readVaultAttachment(f) !== null);
+  if (attached.length === 0) {
+    return {
+      ok: false,
+      detail: `${folders.length} agent group(s) exist, none have a vault attached`,
+      fix: 'Open any group and run "Attach vault".',
+    };
+  }
+  return {
+    ok: true,
+    detail: `${attached.length} of ${folders.length} agent group(s) have a vault attached`,
+    fix: null,
+  };
+}
+
+function checkChannel(name: string): { installed: boolean } {
+  // The channel adapter is installed iff `src/channels/<name>.ts` exists
+  // and the barrel imports it. We check the file presence; if the file
+  // exists but isn't barrel-imported, the wizard's "install" CTA will
+  // re-run idempotently and the import gets appended.
+  return {
+    installed: fs.existsSync(path.join(CHANNELS_DIR, `${name}.ts`)),
+  };
+}
+
+export interface SetupStatusContext {
+  pathname: string;
+  method: string;
+  res: http.ServerResponse;
+}
+
+const json = (res: http.ServerResponse, status: number, body: unknown): void => {
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(body));
+};
+
+export async function handleSetupStatusRoute(ctx: SetupStatusContext): Promise<boolean> {
+  if (ctx.pathname !== '/api/setup/status') return false;
+  if (ctx.method !== 'GET') return false;
+
+  const secrets = checkSecrets();
+  const hub = await checkHub();
+  const vaultAttached = checkVaultAttached();
+  const status: SetupStatus = {
+    secrets,
+    hub,
+    vaultAttached,
+    channels: {
+      discord: checkChannel('discord'),
+      telegram: checkChannel('telegram'),
+    },
+    ready: secrets.ok && hub.ok && vaultAttached.ok,
+  };
+  json(ctx.res, 200, status);
+  return true;
+}