feat(connectors): write-consent gate + first write tool (github_create_issue) (#90)

Writes operate with the user's real credentials, so they're gated behind explicit
per-instance consent — the prerequisite for every write connector (Sheets next, #89).

- migration 0051: instance_connector_consent (instance_id, connector, scope=write).
- lib/connector-consent.ts: hasConsent / setConsent / revokeConsent / listConsents /
  listAllConsents (admin). Fail-closed.
- runRegistryTool: a scope:"write" tool is refused unless the instance has write
  consent for its connector (and there IS an instance context) — enforced uniformly
  for the runtime, the API, and MCP.
- First write tool: github_create_issue (scope:"write"), reusing the GitHub-App token.
- Owner routes (routes/tools.ts): GET /:id/connectors/consent, PUT
  /:id/connectors/:connector/consent { enabled }.
- Admin visibility: GET /v1/admin/connectors (all consents across users).
- Tests: consent fail-closed (no consent / no instance) + gate-passes-when-granted;
  full API suite green (717).

Part of epic #84. Next: Google Sheets connector (#89) rides this gate.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: serge-the-dev

workers/api/migrations/0051_connector_consent.sql

@@ -0,0 +1,15 @@
+-- Write-consent for connector tools (issue #90). Reads via a connected system are
+-- allowed once the connector is connected; WRITES (create issue/PR, append to a
+-- sheet, …) operate with the user's real credentials, so they require explicit
+-- per-instance consent for that connector's write scope. A row here = "this instance
+-- may use <connector> tools of <scope>." Enforced in runRegistryTool (fail-closed:
+-- no row → no write).
+CREATE TABLE IF NOT EXISTS instance_connector_consent (
+  instance_id TEXT NOT NULL REFERENCES agent_instances(id),
+  user_id     TEXT NOT NULL REFERENCES users(id),
+  connector   TEXT NOT NULL,   -- e.g. 'github'
+  scope       TEXT NOT NULL,   -- 'write' (reads don't need consent)
+  created_at  TEXT NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (instance_id, connector, scope)
+);
+CREATE INDEX IF NOT EXISTS idx_connector_consent_user ON instance_connector_consent(user_id, created_at DESC);

workers/api/src/lib/connector-consent.ts

@@ -0,0 +1,57 @@
+// Per-instance write-consent for connector tools (issue #90). Reads are allowed
+// once a connector is connected; writes require an explicit consent row. All queries
+// parameterized. See migration 0051.
+import type { Env } from "../types.js";
+
+export type ConnectorScope = "write";
+
+/** Does this instance have consent for <connector> <scope>? Fail-closed on any error. */
+export async function hasConsent(
+	env: Env,
+	instanceId: string | undefined,
+	connector: string,
+	scope: ConnectorScope,
+): Promise<boolean> {
+	if (!instanceId) return false;
+	try {
+		const row = await env.DB.prepare(
+			"SELECT 1 AS ok FROM instance_connector_consent WHERE instance_id = ?1 AND connector = ?2 AND scope = ?3",
+		).bind(instanceId, connector, scope).first<{ ok: number }>();
+		return !!row;
+	} catch {
+		return false;
+	}
+}
+
+export async function setConsent(env: Env, instanceId: string, userId: string, connector: string, scope: ConnectorScope): Promise<void> {
+	await env.DB.prepare(
+		`INSERT INTO instance_connector_consent (instance_id, user_id, connector, scope)
+		 VALUES (?1, ?2, ?3, ?4)
+		 ON CONFLICT(instance_id, connector, scope) DO NOTHING`,
+	).bind(instanceId, userId, connector, scope).run();
+}
+
+export async function revokeConsent(env: Env, instanceId: string, connector: string, scope: ConnectorScope): Promise<void> {
+	await env.DB.prepare(
+		"DELETE FROM instance_connector_consent WHERE instance_id = ?1 AND connector = ?2 AND scope = ?3",
+	).bind(instanceId, connector, scope).run();
+}
+
+export interface ConsentRow { instance_id: string; user_id: string; connector: string; scope: string; created_at: string }
+
+export async function listConsents(env: Env, instanceId: string): Promise<ConsentRow[]> {
+	const res = await env.DB.prepare(
+		"SELECT instance_id, user_id, connector, scope, created_at FROM instance_connector_consent WHERE instance_id = ?1",
+	).bind(instanceId).all<ConsentRow>();
+	return res.results ?? [];
+}
+
+/** Admin: every connector consent across all users (with owner login). */
+export async function listAllConsents(env: Env): Promise<Array<ConsentRow & { owner_login: string | null }>> {
+	const res = await env.DB.prepare(
+		`SELECT c.instance_id, c.user_id, c.connector, c.scope, c.created_at, u.github_login AS owner_login
+		 FROM instance_connector_consent c LEFT JOIN users u ON u.id = c.user_id
+		 ORDER BY c.created_at DESC`,
+	).all<ConsentRow & { owner_login: string | null }>();
+	return res.results ?? [];
+}

workers/api/src/lib/connectors/github.ts

@@ -98,4 +98,32 @@ export const GITHUB_TOOLS: RegistryTool[] = [
 			return issue ? { content: JSON.stringify(issue, null, 2), success: true } : { content: `Issue #${num} not found in ${repo}.`, success: false };
 		},
 	},
+	{
+		name: "github_create_issue",
+		connector: "github",
+		scope: "write",
+		description: "Open a new GitHub issue in a repo. WRITE — requires the GitHub connector's write consent for this instance.",
+		parameters: {
+			repo: { type: "string", description: 'The repository, "owner/name".', required: true },
+			title: { type: "string", description: "Issue title.", required: true },
+			body: { type: "string", description: "Issue body (markdown)." },
+			labels: { type: "string", description: "Comma-separated labels to apply." },
+		},
+		handler: async (ctx, input) => {
+			const repo = String(input.repo || "");
+			const title = String(input.title || "").trim();
+			if (!title) return { content: "An issue `title` is required.", success: false };
+			const r = await resolveRepo(ctx, repo);
+			if ("error" in r) return { content: r.error, success: false };
+			const labels = String(input.labels || "").split(",").map((s) => s.trim()).filter(Boolean);
+			const res = await fetch(`https://api.github.com/repos/${repo}/issues`, {
+				method: "POST",
+				headers: { ...GH(r.token), "Content-Type": "application/json" },
+				body: JSON.stringify({ title, body: input.body ? String(input.body) : undefined, ...(labels.length ? { labels } : {}) }),
+			});
+			if (!res.ok) return { content: `GitHub returned ${res.status} creating the issue in ${repo}`, success: false };
+			const data = (await res.json()) as { number?: number; html_url?: string };
+			return { content: `Opened issue #${data.number} — ${data.html_url}`, success: true };
+		},
+	},
 ];

workers/api/src/lib/tool-registry.test.ts

@@ -4,6 +4,17 @@ import type { Env } from "../types.js";
 
 const envNoGithub = {} as unknown as Env; // githubAppConfigured() → false
 
+/** Env whose consent lookup returns `granted` for every (instance,connector,write). */
+function envWithConsent(granted: boolean): Env {
+	return {
+		DB: {
+			prepare(_sql: string) {
+				return { bind() { return { first: async () => (granted ? { ok: 1 } : null) }; } };
+			},
+		},
+	} as unknown as Env;
+}
+
 describe("tool registry", () => {
 	it("registers the GitHub connector tools", () => {
 		const names = registryToolNameSet();
@@ -37,6 +48,26 @@ describe("tool registry", () => {
 
 	it("getRegistryTool returns the tool with its scope", () => {
 		expect(getRegistryTool("github_workflow_runs")?.scope).toBe("read");
+		expect(getRegistryTool("github_create_issue")?.scope).toBe("write");
 		expect(getRegistryTool("does_not_exist")).toBeUndefined();
 	});
+
+	it("blocks a WRITE tool without consent (fail-closed)", async () => {
+		const r = await runRegistryTool("github_create_issue", { env: envWithConsent(false), userId: "u1", instanceId: "i1" }, { repo: "o/n", title: "hi" });
+		expect(r.success).toBe(false);
+		expect(r.content).toMatch(/isn't permitted|not permitted|consent/i);
+	});
+
+	it("blocks a WRITE tool when there's no instance context (fail-closed)", async () => {
+		const r = await runRegistryTool("github_create_issue", { env: envWithConsent(true), userId: "u1" }, { repo: "o/n", title: "hi" });
+		expect(r.success).toBe(false);
+	});
+
+	it("passes the consent gate for a WRITE tool when granted (then fails later on not-connected)", async () => {
+		const r = await runRegistryTool("github_create_issue", { env: envWithConsent(true), userId: "u1", instanceId: "i1" }, { repo: "o/n", title: "hi" });
+		// Gate passed → handler ran → GitHub not configured in this env → its own error,
+		// NOT the consent error.
+		expect(r.content).not.toMatch(/isn't permitted/i);
+		expect(r.content).toMatch(/not connected|not configured/i);
+	});
 });

workers/api/src/lib/tool-registry.ts

@@ -5,6 +5,7 @@
 // STORAGE_TOOLS catalog is untouched; registry tools are dispatched alongside them.
 import type { Env } from "../types.js";
 import { GITHUB_TOOLS } from "./connectors/github.js";
+import { hasConsent } from "./connector-consent.js";
 
 export interface RegistryToolCtx {
 	env: Env;
@@ -71,6 +72,15 @@ export async function runRegistryTool(
 ): Promise<{ name: string; content: string; success: boolean }> {
 	const tool = REGISTRY.get(name);
 	if (!tool) return { name, content: `Unknown tool: ${name}`, success: false };
+	// Write-consent gate (issue #90): a write tool needs explicit per-instance consent
+	// for its connector. Fail-closed — no instance context or no consent → refused.
+	if (tool.scope === "write" && !(await hasConsent(ctx.env, ctx.instanceId, tool.connector, "write"))) {
+		return {
+			name,
+			content: `Writing via the ${tool.connector} connector isn't permitted for this agent. Enable write access for ${tool.connector} in the instance's Connections settings, then try again.`,
+			success: false,
+		};
+	}
 	try {
 		const r = await tool.handler(ctx, input || {});
 		return { name, content: r.content, success: r.success };

workers/api/src/routes/admin.ts

@@ -3,6 +3,7 @@ import type { Context } from "hono";
 import { HttpError, isAdmin, requireAdmin, requireUser } from "../lib/auth.js";
 import { getOverviewStats, getUserDetail, listAdminAudit, listAgents, listInstances, listUsers } from "../lib/admin.js";
 import { summarizeErrors, type RawError } from "../lib/admin-errors.js";
+import { listAllConsents } from "../lib/connector-consent.js";
 import { aggregateAdminUsage, type AdminUsageRow } from "../lib/usage.js";
 import { groupTerminalNodes } from "./terminals.js";
 import { relayConnected } from "../lib/runner-client.js";
@@ -87,6 +88,12 @@ adminRoutes.get("/audit", async (c) => {
 	return c.json({ count: rows.length, audit: rows });
 });
 
+/** GET /v1/admin/connectors — every connector write-consent across all users (visibility, #90). */
+adminRoutes.get("/connectors", async (c) => {
+	await requireAdmin(c);
+	return c.json({ consents: await listAllConsents(c.env) });
+});
+
 /** GET /v1/admin/overview — one-shot dashboard counts (users/agents/instances/errors/spend). */
 adminRoutes.get("/overview", async (c) => {
 	await requireAdmin(c);

workers/api/src/routes/tools.ts

@@ -2,6 +2,7 @@ import { Hono } from "hono";
 import { HttpError, requireUser } from "../lib/auth.js";
 import { requireOwnedInstance } from "./instances-runtime.js";
 import { getRegistryTool, registryTools, runRegistryTool } from "../lib/tool-registry.js";
+import { listConsents, revokeConsent, setConsent } from "../lib/connector-consent.js";
 import type { Env } from "../types.js";
 
 /**
@@ -37,3 +38,26 @@ toolRoutes.post("/:id/tools/:name", async (c) => {
 	const result = await runRegistryTool(name, { env: c.env, userId: session.uid, instanceId }, input);
 	return c.json(result);
 });
+
+/** GET /v1/instances/:id/connectors/consent — write-consents granted on this instance. */
+toolRoutes.get("/:id/connectors/consent", async (c) => {
+	const session = await requireUser(c);
+	await requireOwnedInstance(c.env, c.req.param("id"), session.uid);
+	return c.json({ consents: await listConsents(c.env, c.req.param("id")) });
+});
+
+/**
+ * PUT /v1/instances/:id/connectors/:connector/consent { enabled } — grant/revoke
+ * write consent for a connector (issue #90). Owner-scoped. Scope is "write" (reads
+ * never need consent).
+ */
+toolRoutes.put("/:id/connectors/:connector/consent", async (c) => {
+	const session = await requireUser(c);
+	const instanceId = c.req.param("id");
+	await requireOwnedInstance(c.env, instanceId, session.uid);
+	const connector = c.req.param("connector");
+	const body = (await c.req.json().catch(() => ({}))) as { enabled?: boolean };
+	if (body.enabled) await setConsent(c.env, instanceId, session.uid, connector, "write");
+	else await revokeConsent(c.env, instanceId, connector, "write");
+	return c.json({ ok: true, connector, scope: "write", enabled: !!body.enabled });
+});