an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions
HTML agent-harnessagent-orchestrationagentsai-agentsautonomous-agentsclaude-codecodexcoding-agentsdesktop-appdeveloper-toolselectrongemini-cliharnessharness-engineeringlocal-firstmemorymulti-agentopencodeorchestrationtypescript
feat(integrations): Phase 2 foundation — integrations registry + loopback secret broker
Chaitanya Giriaf22ac2bdad1
diff --git a/src/main/config.ts b/src/main/config.tsindex 2fa933f9..91b3234e 100644--- a/src/main/config.ts+++ b/src/main/config.ts@@ -9,6 +9,7 @@ import {type AgentProvider} from '../shared/agentProvider';import { defaultMcpDefaults } from '../shared/mcpCatalog';+import type { IntegrationRecord } from '../shared/integrations';/** A recurring auto-dispatched mission fired on an interval by the scheduler. */export interface ScheduledMission {@@ -170,6 +171,11 @@ export interface HarnessConfig {* — idle-based, never wall-clock, so an actively-working worker is never reaped.* Default 20. */workerIdleTimeoutMinutes?: number;+ /** Registered integrations (Phase 2) — labeled REST endpoints workers reach through+ * the loopback secret broker. METADATA ONLY: each record carries a `secretRef`+ * handle, never the secret value (secrets live encrypted in a separate file via+ * Electron safeStorage — see src/main/integrations.ts). Default []. */+ integrations?: IntegrationRecord[];/** Circuit-breaker thresholds (Lane A #6.6b). Unset = conservative defaults. */circuitBreaker?: CircuitBreakerConfig;/** Enterprise Knowledge Graph (multimodal context for agents). Default OFF. */@@ -265,6 +271,7 @@ const DEFAULTS: HarnessConfig = {mcpDefaults: defaultMcpDefaults(),maxConcurrentWorkers: 4,workerIdleTimeoutMinutes: 20,+ integrations: [],semanticMemory: true,embeddingModel: 'minilm',missions: [OPS_STANDUP_MISSION],diff --git a/src/main/index.ts b/src/main/index.tsindex 5b582131..0e04ab07 100644--- a/src/main/index.ts+++ b/src/main/index.ts@@ -28,6 +28,9 @@ import { SlackWebhookServer, SlackReplyServer, postSlackReply, type SlackEventFiimport { WebhookServer, type WebhookInbound, type WebhookTaskStatus } from './webhook';import { transcribeWithGroq, DEFAULT_GROQ_MODEL } from './freeflow';import { TelemetryCollector } from './telemetry';+import { IntegrationBroker } from './integrationBroker';+import * as integrations from './integrations';+import { validateBaseUrl, buildAuthHeaders, secretRefFor, INTEGRATION_TEMPLATES } from '../shared/integrations';import { ControlRegistry } from './control';import { fetchHireManifest, readHireManifestFile } from './hire';import { parseHireDeepLink, type HireManifest } from '../shared/hire';@@ -171,6 +174,15 @@ interface WorkerRec {* force-removed) when it holds unintegrated work — god is the sole integrator. */const liveWorkers = new Map<string, WorkerRec>();+/** The loopback secret broker (Phase 2). Workers reach registered integrations through+ * it without ever seeing a credential. getRecord/getSecret are injected so the broker+ * stays electron-free + unit-testable. Started in bootstrapHiveServices; each worker is+ * granted a per-worker capability token at spawn (revoked in teardownPty). */+const integrationBroker = new IntegrationBroker({+ getRecord: integrations.getRecord,+ getSecret: integrations.getSecret+});+/*** Tear down everything tied to a PTY id: archive its hive agent, remove its* isolated git worktree, and drop the bookkeeping-map entries. Runs on BOTH an@@ -186,6 +198,9 @@ const liveWorkers = new Map<string, WorkerRec>();* error can never crash the caller (an IPC handler or node-pty's onExit).*/function teardownPty(id: string): void {+ // 0) Revoke this id's broker capability (if any). Idempotent + harmless for a+ // non-worker PTY; ensures a dead worker's token can never reach an integration.+ try { integrationBroker.revoke(id); } catch { /* best-effort */ }// 1) Archive the agent — retained + flagged; only live-PTY agents are active.const agentId = ptyToAgent.get(id);if (agentId) {@@ -1901,6 +1916,46 @@ ipcMain.handle('terminal:openAtFolder', async (_evt, cwd: unknown) => {});});+// ─── IPC: integrations (Phase 2 registry — backend for Ryan's Settings UI) ────+// Records are metadata only (config-backed); secrets are encrypted at rest and NEVER+// returned over IPC. `list` redacts secretRef to a `hasSecret` boolean.+ipcMain.handle('integrations:list', () => integrations.listRecordsRedacted());+ipcMain.handle('integrations:templates', () => INTEGRATION_TEMPLATES);+ipcMain.handle('integrations:upsert', (_evt, record: unknown) => integrations.upsertRecord(record));+ipcMain.handle('integrations:setSecret', (_evt, payload: unknown) => {+ const p = (payload ?? {}) as { id?: unknown; secret?: unknown };+ if (typeof p.id !== 'string' || !p.id) return { ok: false, error: 'id required' };+ if (typeof p.secret !== 'string' || !p.secret) return { ok: false, error: 'secret required' };+ return integrations.setSecret(secretRefFor(p.id), p.secret);+});+ipcMain.handle('integrations:remove', (_evt, payload: unknown) => {+ const p = (payload ?? {}) as { id?: unknown };+ if (typeof p.id !== 'string' || !p.id) return { ok: false, error: 'id required' };+ return integrations.removeRecord(p.id);+});+// Probe an integration's reachability through the broker's own auth path (admin-only;+// runs in main, so the secret is used but never returned — only the upstream status).+ipcMain.handle('integrations:test', async (_evt, payload: unknown) => {+ const p = (payload ?? {}) as { id?: unknown; path?: unknown };+ if (typeof p.id !== 'string' || !p.id) return { ok: false, error: 'id required' };+ const rec = integrations.getRecord(p.id);+ if (!rec) return { ok: false, error: 'unknown integration' };+ const probe = validateBaseUrl(rec.baseUrl);+ if (!probe.ok) return { ok: false, error: probe.error };+ const secret = integrations.getSecret(rec.secretRef);+ const headers = buildAuthHeaders(rec.authType, rec.authHeader, secret);+ try {+ const ac = new AbortController();+ const timer = setTimeout(() => ac.abort(), 15_000);+ const target = typeof p.path === 'string' && p.path ? new URL(p.path.replace(/^\/+/, ''), probe.url.origin) : probe.url;+ const r = await fetch(target, { method: 'GET', headers, redirect: 'manual', signal: ac.signal });+ clearTimeout(timer);+ return { ok: r.ok, status: r.status };+ } catch (e) {+ return { ok: false, error: e instanceof Error ? e.message : String(e) };+ }+});+// ─── IPC: config ────────────────────────────────────────────────────────────ipcMain.handle('config:get', (): HarnessConfig => readConfig());ipcMain.handle('config:update', (_evt, patch: Partial<HarnessConfig>) => writeConfig(patch));@@ -1939,6 +1994,7 @@ ipcMain.handle('config:changeHome', async (_evt, payload: unknown) => {// half-written object and corrupt the moved repo.try { clearMissionTimers(); } catch (e) { console.error('[changeHome] clearMissionTimers:', e); }try { stopEphemeralWorkerWatcher(); } catch (e) { console.error('[changeHome] stopWorkerWatcher:', e); }+ try { integrationBroker.stop(); } catch (e) { console.error('[changeHome] broker.stop:', e); }try { hive.stopRouter(); } catch (e) { console.error('[changeHome] stopRouter:', e); }try { hookServer.stop(); } catch (e) { console.error('[changeHome] hookServer.stop:', e); }try { stopSlackServer(); } catch (e) { console.error('[changeHome] slack.stop:', e); }@@ -2169,6 +2225,7 @@ function teardownAndQuit(): void {// half-torn-down socket) must never abort the quit or pop a crash dialog.try { clearMissionTimers(); } catch (e) { console.error('[quit] clearMissionTimers:', e); }try { stopEphemeralWorkerWatcher(); } catch (e) { console.error('[quit] stopWorkerWatcher:', e); }+ try { integrationBroker.stop(); } catch (e) { console.error('[quit] broker.stop:', e); }try { hive.stopRouter(); } catch (e) { console.error('[quit] stopRouter:', e); }try { hookServer.stop(); } catch (e) { console.error('[quit] hookServer.stop:', e); }try { telemetry.stop(); } catch (e) { console.error('[quit] telemetry.stop:', e); }@@ -2222,6 +2279,7 @@ ipcMain.handle('app:resetAll', () => {// Tear everything down first so nothing writes back into the dirs we wipe.try { clearMissionTimers(); } catch (e) { console.error('[reset] clearMissionTimers:', e); }try { stopEphemeralWorkerWatcher(); } catch (e) { console.error('[reset] stopWorkerWatcher:', e); }+ try { integrationBroker.stop(); } catch (e) { console.error('[reset] broker.stop:', e); }try { hive.stopRouter(); } catch (e) { console.error('[reset] stopRouter:', e); }try { hookServer.stop(); } catch (e) { console.error('[reset] hookServer.stop:', e); }try { telemetry.stop(); } catch (e) { console.error('[reset] telemetry.stop:', e); }@@ -2643,10 +2701,21 @@ async function processSpawnRequest(filePath: string): Promise<void> {role: 'worker',cwd};+ // Phase 2: grant this worker a broker capability over the currently-enabled+ // integrations and inject the broker URL + a per-worker capability TOKEN (a handle,+ // never a secret) into its env, so it can reach registered REST integrations through+ // the loopback secret broker without ever seeing a credential. Only when the broker+ // is up; the grant is revoked in teardownPty (and below if the spawn fails).+ const brokerEnv: Record<string, string> = {};+ if (integrationBroker.running()) {+ const token = integrationBroker.grant(workerId, integrations.enabledIds());+ brokerEnv.MD_BROKER_URL = integrationBroker.url();+ brokerEnv.MD_BROKER_TOKEN = token;+ }const spawnOpts: AgentSpawnOptions = {id: workerId, cwd, command, cols: 120, rows: 32,args: raw.model ? ['--model', raw.model] : [],- hive: meta, isolate, provider: raw.provider+ hive: meta, isolate, provider: raw.provider, env: brokerEnv};let res: { ok: boolean; error?: string };@@ -2657,7 +2726,7 @@ async function processSpawnRequest(filePath: string): Promise<void> {} catch (e) {res = { ok: false, error: String(e) };}- if (!res.ok) { fail(`spawn failed — ${res.error ?? 'unknown error'}`); return; }+ if (!res.ok) { integrationBroker.revoke(workerId); fail(`spawn failed — ${res.error ?? 'unknown error'}`); return; }// Register for done-scan / idle-reap / safe teardown (pty id == workerId).liveWorkers.set(workerId, { workerId, reqId, slack, baseBranch, spawnedAt: Date.now() });@@ -2754,6 +2823,12 @@ function bootstrapHiveServices(): void {archiveOrphanedAgents(); // #57/#58: archive stale archived:false entries with no live PTYhive.startRouter();startEphemeralWorkerWatcher(); // poll HIVE_ROOT/spawn-requests → ephemeral workers+ // Phase 2: the loopback secret broker. Bind it BEFORE workers spawn so each spawn can+ // be granted a capability token + the broker URL in its env. Loopback-only, idempotent.+ void integrationBroker.start().then((r) => {+ if (r.ok) console.log('[broker] integration broker listening on', integrationBroker.url());+ else console.error('[broker] failed to start:', r.error);+ });ensureDefaultMissions(); // one-time: seed the built-in hourly ops standupsyncMissions(); // arm recurring auto-dispatch missions now the router is livehookServer.start();diff --git a/src/main/integrationBroker.ts b/src/main/integrationBroker.tsnew file mode 100644index 00000000..4b067a95--- /dev/null+++ b/src/main/integrationBroker.ts@@ -0,0 +1,311 @@+/**+ * Loopback secret broker (Phase 2 foundation, main process).+ *+ * A 127.0.0.1-only HTTP proxy. An ephemeral worker calls+ * <METHOD> http://127.0.0.1:<port>/i/<integrationId>/<path...>+ * authenticating with a PER-WORKER CAPABILITY TOKEN (a handle, NOT any secret) in the+ * `Authorization: Bearer` / `X-MD-Broker-Token` header. The broker validates the token,+ * authorizes the integration, decrypts the integration's real secret, injects it as the+ * upstream auth header, forwards to the integration's baseUrl, and streams the response+ * back. The worker uses the integration WITHOUT EVER SEEING the credential.+ *+ * Generalizes the existing src/main/slack.ts `SlackReplyServer` (a loopback broker that+ * posts Slack replies without the agent seeing the bot token) to an N-integration proxy.+ *+ * DEPENDENCY-FREE of electron by design: `getRecord` + `getSecret` are injected, so this+ * module is unit-testable under plain node. The secret is materialized ONLY here, at+ * forward-time, and is NEVER logged, NEVER returned to the worker, NEVER echoed in an+ * error.+ *+ * NOT an open proxy: a worker can only reach baseUrls the user registered (it selects an+ * integration by id, never a host), and the path is confined under the integration+ * origin (see resolveUpstreamUrl).+ *+ * Contract: hive/docs/integrations-spec.md.+ */+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';+import { randomBytes, timingSafeEqual } from 'node:crypto';+import { Readable } from 'node:stream';+import {+ type IntegrationRecord,+ buildAuthHeaders,+ resolveUpstreamUrl,+ authTypeNeedsSecret+} from '../shared/integrations';++const MAX_BODY_BYTES = 10 * 1024 * 1024; // 10 MB request-body cap+const UPSTREAM_TIMEOUT_MS = 30_000;+const DEFAULT_USER_AGENT = 'munder-difflin-broker/1';++/** Hop-by-hop headers never forwarded in either direction. */+const HOP_BY_HOP = new Set([+ 'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization',+ 'te', 'trailer', 'transfer-encoding', 'upgrade'+]);+/** Request headers the worker is NEVER allowed to pass upstream. */+const STRIP_REQUEST = new Set([+ 'authorization', 'x-md-broker-token', 'host', 'cookie', 'content-length', ...HOP_BY_HOP+]);+/** Response headers never forwarded back (fetch already decodes the body, so the+ * upstream content-encoding/length would be wrong). */+const STRIP_RESPONSE = new Set([+ 'content-encoding', 'content-length', 'set-cookie', ...HOP_BY_HOP+]);++interface Capability {+ workerId: string;+ allowedIds: Set<string>;+ grantedAt: number;+}++export interface IntegrationBrokerDeps {+ /** Resolve an integration record by id (injected — the registry). */+ getRecord: (id: string) => IntegrationRecord | undefined;+ /** Decrypt a secret by ref (injected — the secret store). Main-internal. */+ getSecret: (secretRef: string | undefined) => string | undefined;+}++/** True for IPv4 loopback (127.0.0.0/8) and IPv6 ::1 (incl. v4-mapped). Mirrors slack.ts. */+function isLoopback(addr: string): boolean {+ const a = addr.replace(/^::ffff:/, '');+ return a === '::1' || a.startsWith('127.');+}++export class IntegrationBroker {+ private server: Server | null = null;+ private port = 0;+ private readonly deps: IntegrationBrokerDeps;+ /** token -> capability. In-memory only; NEVER persisted. */+ private readonly byToken = new Map<string, Capability>();+ /** workerId -> token, for revoke. */+ private readonly byWorker = new Map<string, string>();++ constructor(deps: IntegrationBrokerDeps) {+ this.deps = deps;+ }++ /** Bind a loopback port (0 ⇒ OS-assigned). Resolves the bound port. */+ start(preferredPort = 0): Promise<{ ok: boolean; port?: number; error?: string }> {+ return new Promise((resolve) => {+ if (this.server) { resolve({ ok: true, port: this.port }); return; }+ const server = createServer((req, res) => this.handle(req, res));+ const onError = (e: Error): void => { server.off('listening', onListening); resolve({ ok: false, error: e.message }); };+ const onListening = (): void => {+ server.off('error', onError);+ this.server = server;+ const addr = server.address();+ this.port = addr && typeof addr === 'object' ? addr.port : preferredPort;+ resolve({ ok: true, port: this.port });+ };+ server.once('error', onError);+ server.once('listening', onListening);+ // 127.0.0.1 ONLY — never bound to a routable interface, never tunneled.+ server.listen(preferredPort, '127.0.0.1');+ });+ }++ /** Close the broker. Idempotent and best-effort. Clears all capabilities. */+ stop(): void {+ try { this.server?.close(); } catch { /* noop */ }+ this.server = null;+ this.port = 0;+ this.byToken.clear();+ this.byWorker.clear();+ }++ /** Whether the broker is bound and serving. */+ running(): boolean {+ return !!this.server && this.port > 0;+ }++ /** The base URL workers use (only valid while running). */+ url(): string {+ return `http://127.0.0.1:${this.port}`;+ }++ /** Mint a per-worker capability token granting access to `allowedIds`. Any prior+ * token for this worker is revoked first. The token is a random handle — never a+ * secret, never persisted. */+ grant(workerId: string, allowedIds: string[]): string {+ this.revoke(workerId);+ const token = randomBytes(32).toString('base64url');+ this.byToken.set(token, { workerId, allowedIds: new Set(allowedIds), grantedAt: Date.now() });+ this.byWorker.set(workerId, token);+ return token;+ }++ /** Revoke a worker's capability (called on teardown). Idempotent. */+ revoke(workerId: string): void {+ const token = this.byWorker.get(workerId);+ if (token) { this.byToken.delete(token); this.byWorker.delete(workerId); }+ }++ /** Constant-time-ish lookup of a presented token against live capabilities. */+ private resolveCapability(provided: string | undefined): Capability | undefined {+ if (!provided) return undefined;+ const a = Buffer.from(provided);+ for (const [token, cap] of this.byToken) {+ const b = Buffer.from(token);+ if (a.length === b.length && timingSafeEqual(a, b)) return cap;+ }+ return undefined;+ }++ private static sendError(res: ServerResponse, status: number, code: string, message: string): void {+ if (res.headersSent) { try { res.end(); } catch { /* noop */ } return; }+ res.writeHead(status, { 'content-type': 'application/json' });+ res.end(JSON.stringify({ error: message, code }));+ }++ /** Extract the bearer/x-md-broker-token from the request. */+ private static tokenFrom(req: IncomingMessage): string | undefined {+ const x = req.headers['x-md-broker-token'];+ if (typeof x === 'string' && x) return x;+ const auth = req.headers['authorization'];+ if (typeof auth === 'string') {+ const m = /^Bearer\s+(.+)$/i.exec(auth.trim());+ if (m) return m[1].trim();+ }+ return undefined;+ }++ private handle(req: IncomingMessage, res: ServerResponse): void {+ // 1) Loopback — defense in depth even though the bind already excludes others.+ if (!isLoopback(req.socket.remoteAddress ?? '')) {+ return IntegrationBroker.sendError(res, 403, 'forbidden', 'loopback callers only');+ }+ // 2) Capability token.+ const cap = this.resolveCapability(IntegrationBroker.tokenFrom(req));+ if (!cap) return IntegrationBroker.sendError(res, 401, 'unauthorized', 'missing or invalid capability token');++ // 3) Parse /i/<integrationId>/<path...>.+ const rawUrl = req.url ?? '';+ const m = /^\/i\/([^/?#]+)(?:\/([^?#]*))?(\?[^#]*)?$/.exec(rawUrl);+ if (!m) return IntegrationBroker.sendError(res, 404, 'not_found', 'expected /i/<integrationId>/<path>');+ const integrationId = decodeURIComponent(m[1]);+ const path = m[2] ?? '';+ const query = m[3] ?? '';++ // 4) Authorize against this worker's capability.+ if (!cap.allowedIds.has(integrationId)) {+ return IntegrationBroker.sendError(res, 403, 'forbidden', 'integration not in this worker capability');+ }+ // 5) Resolve the record (still enabled?).+ const rec = this.deps.getRecord(integrationId);+ if (!rec) return IntegrationBroker.sendError(res, 404, 'not_found', 'unknown integration');+ if (!rec.enabled) return IntegrationBroker.sendError(res, 403, 'forbidden', 'integration is disabled');++ // 6) Confine the upstream URL under the integration origin (NOT an open proxy).+ const upstream = resolveUpstreamUrl(rec.baseUrl, path + query);+ if (!upstream) return IntegrationBroker.sendError(res, 400, 'bad_request', 'invalid or out-of-bounds path');++ // 7) Secret (decrypted ONLY here, used ONLY to inject the upstream header).+ let secret: string | undefined;+ if (authTypeNeedsSecret(rec.authType)) {+ secret = this.deps.getSecret(rec.secretRef);+ if (!secret) return IntegrationBroker.sendError(res, 503, 'no_secret', 'no secret configured for this integration');+ }++ void this.forward(req, res, rec, upstream, secret);+ }++ private async forward(+ req: IncomingMessage,+ res: ServerResponse,+ rec: IntegrationRecord,+ upstream: URL,+ secret: string | undefined+ ): Promise<void> {+ // Buffer the request body with a hard cap (write methods).+ const method = (req.method ?? 'GET').toUpperCase();+ const hasBody = method !== 'GET' && method !== 'HEAD';+ let body: Buffer | undefined;+ if (hasBody) {+ try {+ body = await readBodyCapped(req);+ } catch (e) {+ if ((e as Error).message === 'too_large') {+ return IntegrationBroker.sendError(res, 413, 'payload_too_large', 'request body too large');+ }+ return IntegrationBroker.sendError(res, 400, 'bad_request', 'could not read request body');+ }+ }++ // Sanitize worker headers, then inject the auth header(s). Injected auth ALWAYS+ // wins: the strip list removes any worker-supplied authorization/auth header.+ const outHeaders: Record<string, string> = {};+ for (const [k, v] of Object.entries(req.headers)) {+ const key = k.toLowerCase();+ if (STRIP_REQUEST.has(key)) continue;+ if (Array.isArray(v)) outHeaders[key] = v.join(', ');+ else if (typeof v === 'string') outHeaders[key] = v;+ }+ if (!outHeaders['user-agent']) outHeaders['user-agent'] = DEFAULT_USER_AGENT;+ const injected = buildAuthHeaders(rec.authType, rec.authHeader, secret);+ for (const [k, v] of Object.entries(injected)) {+ delete outHeaders[k]; // ensure the worker can't shadow an injected header+ outHeaders[k] = v;+ }++ const ac = new AbortController();+ const timer = setTimeout(() => ac.abort(), UPSTREAM_TIMEOUT_MS);+ let upstreamRes: Response;+ try {+ upstreamRes = await fetch(upstream, {+ method,+ headers: outHeaders,+ body: body as BodyInit | undefined,+ redirect: 'manual',+ signal: ac.signal+ });+ } catch (e) {+ clearTimeout(timer);+ // The message could in theory contain the URL but never the secret.+ return IntegrationBroker.sendError(res, 502, 'bad_gateway', `upstream request failed: ${(e as Error).message}`);+ }++ // Stream the response back (status + sanitized headers + body).+ const respHeaders: Record<string, string> = {};+ upstreamRes.headers.forEach((value, key) => {+ if (!STRIP_RESPONSE.has(key.toLowerCase())) respHeaders[key] = value;+ });+ res.writeHead(upstreamRes.status, respHeaders);+ try {+ if (upstreamRes.body) {+ await pipeWebStream(upstreamRes.body, res);+ } else {+ res.end();+ }+ } catch {+ try { res.end(); } catch { /* socket gone */ }+ } finally {+ clearTimeout(timer);+ }+ }+}++/** Read a request body into a Buffer, aborting past MAX_BODY_BYTES (throws 'too_large'). */+function readBodyCapped(req: IncomingMessage): Promise<Buffer> {+ return new Promise((resolve, reject) => {+ const chunks: Buffer[] = [];+ let size = 0;+ req.on('data', (c: Buffer) => {+ size += c.length;+ if (size > MAX_BODY_BYTES) { reject(new Error('too_large')); req.destroy(); return; }+ chunks.push(c);+ });+ req.on('end', () => resolve(Buffer.concat(chunks)));+ req.on('error', (e) => reject(e));+ });+}++/** Pipe a web ReadableStream (fetch response body) to a node ServerResponse. */+function pipeWebStream(web: ReadableStream<Uint8Array>, res: ServerResponse): Promise<void> {+ return new Promise((resolve, reject) => {+ const node = Readable.fromWeb(web as Parameters<typeof Readable.fromWeb>[0]);+ node.on('error', reject);+ res.on('error', reject);+ res.on('finish', resolve);+ node.pipe(res);+ });+}diff --git a/src/main/integrations.ts b/src/main/integrations.tsnew file mode 100644index 00000000..eb4121c7--- /dev/null+++ b/src/main/integrations.ts@@ -0,0 +1,156 @@+/**+ * Integrations registry + encrypted secret store (Phase 2 foundation, main process).+ *+ * Two responsibilities, deliberately separated from the broker:+ * 1. Registry — config-backed CRUD over IntegrationRecord metadata (NO secrets).+ * 2. Secret store — secrets ENCRYPTED AT REST via Electron `safeStorage`, kept in a+ * file SEPARATE from config.json, decrypted only here, only in main.+ *+ * The broker (src/main/integrationBroker.ts) is electron-free and receives `getRecord`+ * + `getSecret` from here by injection, so it stays unit-testable without electron.+ *+ * SECURITY: a secret is never written unless `safeStorage.isEncryptionAvailable()`+ * (fail closed — no plaintext fallback), never returned to the renderer, never logged,+ * never placed in agent env/transcript, never echoed in any response. Records carry+ * only a `secretRef` handle.+ *+ * Contract: hive/docs/integrations-spec.md.+ */+import { app, safeStorage } from 'electron';+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';+import { dirname, join } from 'node:path';+import {+ type IntegrationRecord,+ validateIntegrationRecord,+ authTypeNeedsSecret,+ secretRefFor+} from '../shared/integrations';+import { readConfig, writeConfig } from './config';++// ─── Registry (config-backed) ────────────────────────────────────────────────++/** All registered integration records (metadata only). */+export function listRecords(): IntegrationRecord[] {+ return readConfig().integrations ?? [];+}++/** Look up one record by id. */+export function getRecord(id: string): IntegrationRecord | undefined {+ return listRecords().find((r) => r.id === id);+}++/** Ids of integrations a worker may use right now (enabled, and — for secret auth —+ * actually holding a stored secret). This is the default capability scope granted to+ * every ephemeral worker. */+export function enabledIds(): string[] {+ return listRecords()+ .filter((r) => r.enabled && (!authTypeNeedsSecret(r.authType) || hasSecret(r.secretRef)))+ .map((r) => r.id);+}++/** Create or replace a record (validated). Stamps createdAt/updatedAt; preserves the+ * original createdAt on update. Does NOT touch the secret store. */+export function upsertRecord(input: unknown): { ok: true; record: IntegrationRecord } | { ok: false; error: string } {+ const v = validateIntegrationRecord(input);+ if (!v.ok) return v;+ const now = Date.now();+ const existing = getRecord(v.value.id);+ const record: IntegrationRecord = {+ ...v.value,+ createdAt: existing?.createdAt ?? now,+ updatedAt: now+ };+ const next = listRecords().filter((r) => r.id !== record.id);+ next.push(record);+ writeConfig({ integrations: next });+ return { ok: true, record };+}++/** Remove a record AND its stored secret. */+export function removeRecord(id: string): { ok: boolean } {+ const next = listRecords().filter((r) => r.id !== id);+ writeConfig({ integrations: next });+ deleteSecret(secretRefFor(id));+ return { ok: true };+}++/** Records with the secretRef redacted to a boolean — the renderer-safe shape. */+export function listRecordsRedacted(): Array<Omit<IntegrationRecord, 'secretRef'> & { hasSecret: boolean }> {+ return listRecords().map(({ secretRef, ...rest }) => ({ ...rest, hasSecret: !!secretRef && hasSecret(secretRef) }));+}++// ─── Secret store (encrypted at rest) ────────────────────────────────────────++function secretsPath(): string {+ return join(app.getPath('userData'), 'integration-secrets.json');+}++function readSecretBlob(): Record<string, string> {+ const p = secretsPath();+ if (!existsSync(p)) return {};+ try {+ const parsed = JSON.parse(readFileSync(p, 'utf8'));+ return parsed && typeof parsed === 'object' ? (parsed as Record<string, string>) : {};+ } catch {+ return {};+ }+}++function writeSecretBlob(blob: Record<string, string>): void {+ const p = secretsPath();+ mkdirSync(dirname(p), { recursive: true });+ writeFileSync(p, JSON.stringify(blob, null, 2), { encoding: 'utf8', mode: 0o600 });+}++/** Store a secret ENCRYPTED. Fail closed if OS encryption is unavailable (never+ * writes plaintext). The plaintext is used only to encrypt and is not retained. */+export function setSecret(secretRef: string, plaintext: string): { ok: boolean; error?: string } {+ if (!secretRef) return { ok: false, error: 'secretRef required' };+ if (typeof plaintext !== 'string' || plaintext === '') return { ok: false, error: 'secret required' };+ try {+ if (!safeStorage.isEncryptionAvailable()) {+ return { ok: false, error: 'OS secret encryption is unavailable; refusing to store a secret in plaintext' };+ }+ const cipher = safeStorage.encryptString(plaintext).toString('base64');+ const blob = readSecretBlob();+ blob[secretRef] = cipher;+ writeSecretBlob(blob);+ return { ok: true };+ } catch (e) {+ return { ok: false, error: e instanceof Error ? e.message : String(e) };+ }+}++/** Decrypt a secret. MAIN-INTERNAL ONLY — never expose this over IPC. Returns+ * undefined if absent or undecryptable (the broker maps that to 503 no_secret). */+export function getSecret(secretRef: string | undefined): string | undefined {+ if (!secretRef) return undefined;+ const cipher = readSecretBlob()[secretRef];+ if (!cipher) return undefined;+ try {+ if (!safeStorage.isEncryptionAvailable()) return undefined;+ return safeStorage.decryptString(Buffer.from(cipher, 'base64'));+ } catch {+ return undefined;+ }+}++/** Whether a secret is stored for this ref (no decryption). */+export function hasSecret(secretRef: string | undefined): boolean {+ if (!secretRef) return false;+ return !!readSecretBlob()[secretRef];+}++/** Delete a stored secret. Idempotent. */+export function deleteSecret(secretRef: string | undefined): void {+ if (!secretRef) return;+ const blob = readSecretBlob();+ if (secretRef in blob) {+ delete blob[secretRef];+ if (Object.keys(blob).length === 0) {+ try { rmSync(secretsPath(), { force: true }); } catch { /* best-effort */ }+ } else {+ writeSecretBlob(blob);+ }+ }+}diff --git a/src/shared/integrations.ts b/src/shared/integrations.tsnew file mode 100644index 00000000..8d41a9be--- /dev/null+++ b/src/shared/integrations.ts@@ -0,0 +1,259 @@+/**+ * Integrations registry — shared schema (Phase 2 foundation).+ *+ * A dependency-free, importable-by-both (main + renderer) module declaring the+ * integration record/template types, their validation, and the v1 reference+ * templates. Mirrors the posture of `src/shared/mcpCatalog.ts`: NO electron / node /+ * UI imports so it can be pulled into the main process, the preload bridge, and the+ * renderer alike.+ *+ * An *integration* is a labeled REST endpoint a user registers ("label it and it's+ * available"). The record carries METADATA ONLY — never the secret value, only a+ * `secretRef` handle into the encrypted secret store (see src/main/integrations.ts).+ * The loopback secret broker (src/main/integrationBroker.ts) is the ONLY place a real+ * secret is materialized, and only at forward-time inside the main process.+ *+ * Relationship to mcpCatalog.ts: that catalog declares STDIO MCP servers; this+ * registry declares HTTP REST endpoints reached through the loopback broker — a+ * complementary transport, not a competing catalog. Where a service overlaps+ * (github/db/email/search) the labels are kept aligned.+ *+ * Full contract: hive/docs/integrations-spec.md.+ */++export type IntegrationKind = 'github' | 'custom-rest';++/** How the broker injects credentials when forwarding to the integration's baseUrl.+ * This is the ONLY auth-injection vocabulary; the secret is supplied by the broker+ * at forward-time, never stored here. */+export type IntegrationAuthType =+ | 'none' // public API — inject nothing+ | 'bearer' // Authorization: Bearer <secret>+ | 'header' // <authHeader>: <secret> (authHeader required)+ | 'github'; // Authorization: Bearer <secret> + GitHub API headers++/** A registered integration. METADATA ONLY — carries NO secret value, only a+ * `secretRef` handle. Safe to persist in config.json and cross IPC to the renderer. */+export interface IntegrationRecord {+ /** Stable slug, unique. See SLUG_RE. Also seeds the secretRef (`int:<id>`). */+ id: string;+ /** Human label for the UI (<= 60 chars). */+ label: string;+ /** Preset family — drives default headers and UI affordances. */+ kind: IntegrationKind;+ /** https origin (+ optional base path). The broker forwards <baseUrl>/<path>. A+ * loopback http origin is allowed only for explicit local custom-rest targets. */+ baseUrl: string;+ /** How the broker injects auth when forwarding upstream. */+ authType: IntegrationAuthType;+ /** REQUIRED iff authType === 'header' — the header NAME to inject the secret under. */+ authHeader?: string;+ /** HANDLE into the encrypted secret store; NEVER the secret. Present iff+ * authType !== 'none'. Convention: `int:<id>`. */+ secretRef?: string;+ /** Consent gate. A worker can reach an integration ONLY when enabled. */+ enabled: boolean;+ /** epoch ms. */+ createdAt: number;+ /** epoch ms. */+ updatedAt: number;+}++/** A preset that seeds an IntegrationRecord. Dwight extends the catalog by appending+ * to INTEGRATION_TEMPLATES — no broker or registry changes needed. */+export interface IntegrationTemplate {+ kind: IntegrationKind;+ /** Default label (user-editable). */+ label: string;+ /** Default origin. Empty for custom-rest (the user supplies it). */+ baseUrl: string;+ authType: IntegrationAuthType;+ /** For authType 'header'. */+ authHeader?: string;+ /** UI prompt for the secret field, e.g. "GitHub personal access token". */+ secretLabel?: string;+ /** One line: where to get the secret / what scopes it needs. */+ secretHelp?: string;+ /** https link for the UI. */+ docsUrl?: string;+ /** Default slug seed. */+ idSuggestion: string;+}++/** Integration id: lowercase slug, 2–40 chars, no leading/trailing hyphen. */+export const INTEGRATION_SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/;+/** A header name the broker may inject under (authType 'header'). */+export const HEADER_NAME_RE = /^[A-Za-z0-9-]{1,64}$/;+export const ALL_AUTH_TYPES: readonly IntegrationAuthType[] = ['none', 'bearer', 'header', 'github'];+export const ALL_KINDS: readonly IntegrationKind[] = ['github', 'custom-rest'];++/** The secretRef handle for an integration id (1:1). */+export function secretRefFor(id: string): string {+ return `int:${id}`;+}++/** True iff this auth type needs a stored secret. */+export function authTypeNeedsSecret(t: IntegrationAuthType): boolean {+ return t !== 'none';+}++/**+ * Validate an integration record (the upsert gate). Mirrors validateHireManifest's+ * style: returns { ok:true } or { ok:false, error }. Fail closed — anything not+ * explicitly allowed is rejected. `createdAt`/`updatedAt` are stamped by the+ * registry, so they are not required on input.+ */+export function validateIntegrationRecord(+ rec: unknown+): { ok: true; value: Omit<IntegrationRecord, 'createdAt' | 'updatedAt'> } | { ok: false; error: string } {+ if (!rec || typeof rec !== 'object') return { ok: false, error: 'record must be an object' };+ const r = rec as Record<string, unknown>;++ const id = typeof r.id === 'string' ? r.id.trim() : '';+ if (!INTEGRATION_SLUG_RE.test(id)) {+ return { ok: false, error: 'id must be a lowercase slug (2–40 chars, a–z 0–9 -, no leading/trailing hyphen)' };+ }+ const label = typeof r.label === 'string' ? r.label.trim() : '';+ if (!label || label.length > 60) return { ok: false, error: 'label is required and must be <= 60 chars' };++ const kind = r.kind as IntegrationKind;+ if (!ALL_KINDS.includes(kind)) return { ok: false, error: `kind must be one of ${ALL_KINDS.join(', ')}` };++ const authType = r.authType as IntegrationAuthType;+ if (!ALL_AUTH_TYPES.includes(authType)) {+ return { ok: false, error: `authType must be one of ${ALL_AUTH_TYPES.join(', ')}` };+ }++ const baseUrl = typeof r.baseUrl === 'string' ? r.baseUrl.trim() : '';+ const urlCheck = validateBaseUrl(baseUrl);+ if (!urlCheck.ok) return { ok: false, error: urlCheck.error };++ let authHeader: string | undefined;+ if (authType === 'header') {+ authHeader = typeof r.authHeader === 'string' ? r.authHeader.trim() : '';+ if (!authHeader || !HEADER_NAME_RE.test(authHeader)) {+ return { ok: false, error: "authType 'header' requires authHeader matching [A-Za-z0-9-]{1,64}" };+ }+ } else if (r.authHeader != null && String(r.authHeader).trim() !== '') {+ return { ok: false, error: "authHeader is only valid when authType === 'header'" };+ }++ const needsSecret = authTypeNeedsSecret(authType);+ const secretRef = needsSecret ? secretRefFor(id) : undefined;+ const enabled = r.enabled === true;++ return { ok: true, value: { id, label, kind, baseUrl, authType, authHeader, secretRef, enabled } };+}++/** Validate a baseUrl: https origin (+ optional path), no userinfo, no traversal.+ * A loopback http origin (127.0.0.1 / [::1] / localhost) is permitted for explicit+ * local custom-rest targets the user registers. */+export function validateBaseUrl(baseUrl: string): { ok: true; url: URL } | { ok: false; error: string } {+ if (!baseUrl) return { ok: false, error: 'baseUrl is required' };+ let u: URL;+ try {+ u = new URL(baseUrl);+ } catch {+ return { ok: false, error: 'baseUrl must be a valid URL' };+ }+ if (u.username || u.password) return { ok: false, error: 'baseUrl must not contain userinfo' };+ if (u.search || u.hash) return { ok: false, error: 'baseUrl must not contain a query or fragment' };+ if (baseUrl.includes('..')) return { ok: false, error: 'baseUrl must not contain ".."' };+ const isLoopbackHost =+ u.hostname === '127.0.0.1' || u.hostname === '::1' || u.hostname === '[::1]' || u.hostname === 'localhost';+ if (u.protocol === 'https:') return { ok: true, url: u };+ if (u.protocol === 'http:' && isLoopbackHost) return { ok: true, url: u };+ return { ok: false, error: 'baseUrl must be https (http allowed only for 127.0.0.1/localhost)' };+}++/**+ * Build the upstream auth headers the broker injects when forwarding. Pure — the+ * caller (the broker, in main) passes the already-decrypted secret; this function+ * never reads any store and never logs. Returns the header map to merge into the+ * outbound request (lowercased keys).+ */+export function buildAuthHeaders(+ authType: IntegrationAuthType,+ authHeader: string | undefined,+ secret: string | undefined+): Record<string, string> {+ switch (authType) {+ case 'none':+ return {};+ case 'bearer':+ return secret ? { authorization: `Bearer ${secret}` } : {};+ case 'header':+ return secret && authHeader ? { [authHeader.toLowerCase()]: secret } : {};+ case 'github':+ return {+ ...(secret ? { authorization: `Bearer ${secret}` } : {}),+ accept: 'application/vnd.github+json',+ 'x-github-api-version': '2022-11-28'+ };+ default:+ return {};+ }+}++/**+ * Join an integration baseUrl with a worker-supplied path, confining the result+ * under the baseUrl origin (NOT an open proxy). Returns null if the path would+ * escape the origin (absolute URL, host override, or traversal above the base path).+ * `pathAndQuery` is the part after `/i/<integrationId>/` including any query string.+ */+export function resolveUpstreamUrl(baseUrl: string, pathAndQuery: string): URL | null {+ let base: URL;+ try {+ base = new URL(baseUrl);+ } catch {+ return null;+ }+ // Reject anything that smells like an absolute target or traversal.+ if (/^[a-z][a-z0-9+.-]*:\/\//i.test(pathAndQuery)) return null; // scheme://...+ if (pathAndQuery.startsWith('//')) return null; // protocol-relative host override+ // Decode the path before the traversal check so an encoded `%2e%2e` is caught too.+ const pathOnly = pathAndQuery.split(/[?#]/)[0];+ let decodedPath: string;+ try { decodedPath = decodeURIComponent(pathOnly); } catch { return null; }+ if (decodedPath.split('/').some((seg) => seg === '..')) return null;++ // Normalize the base path to a directory prefix, then append the worker path.+ const basePath = base.pathname.endsWith('/') ? base.pathname : base.pathname + '/';+ const rel = pathAndQuery.replace(/^\/+/, '');+ let resolved: URL;+ try {+ resolved = new URL(basePath + rel, base.origin);+ } catch {+ return null;+ }+ // Confine: same origin AND the resolved path stays under the base path prefix.+ if (resolved.origin !== base.origin) return null;+ const confinePrefix = base.pathname.endsWith('/') ? base.pathname : base.pathname + '/';+ if (confinePrefix !== '/' && !(resolved.pathname + '/').startsWith(confinePrefix) && resolved.pathname !== base.pathname) {+ return null;+ }+ return resolved;+}++/** v1 reference templates — the two end-to-end references. Dwight appends more here. */+export const INTEGRATION_TEMPLATES: IntegrationTemplate[] = [+ {+ kind: 'github',+ label: 'GitHub',+ baseUrl: 'https://api.github.com',+ authType: 'github',+ secretLabel: 'GitHub personal access token',+ secretHelp: 'Create a fine-grained or classic PAT at github.com/settings/tokens with the scopes your workers need.',+ docsUrl: 'https://docs.github.com/rest',+ idSuggestion: 'github'+ },+ {+ kind: 'custom-rest',+ label: 'Custom REST API',+ baseUrl: '',+ authType: 'bearer',+ secretLabel: 'API key / token',+ secretHelp: 'Point baseUrl at any REST API. Choose how its credential is sent: Bearer token, a custom header, or none.',+ idSuggestion: 'my-api'+ }+];