Skip to content

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

feat(integrations): Phase 2 foundation — integrations registry + loopback secret broker

Chaitanya Giriaf22ac2bdad1
diff --git a/src/main/config.ts b/src/main/config.ts
index 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.ts
index 5b582131..0e04ab07 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -28,6 +28,9 @@ import { SlackWebhookServer, SlackReplyServer, postSlackReply, type SlackEventFi
import { 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 PTY
hive.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 standup
syncMissions(); // arm recurring auto-dispatch missions now the router is live
hookServer.start();
diff --git a/src/main/integrationBroker.ts b/src/main/integrationBroker.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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'
+ }
+];