can2cup 0.10.2 → 0.10.4

package/src/relay/mcp-http.ts

@@ -0,0 +1,627 @@
+/**
+ * Remote MCP connector — Streamable HTTP + OAuth 2.1.
+ *
+ * Why: can2cup today is a local stdio MCP server, so being reachable costs the
+ * user Node, Claude Code, a terminal, and a window kept open. A remote connector
+ * costs them a pasted URL and a login, and works in Claude, ChatGPT, Perplexity,
+ * Grok and Le Chat alike. That is the difference between "people who run CLIs"
+ * and "people with an AI subscription".
+ *
+ * TWO CUSTODY TIERS, AND THE DIFFERENCE IS DISCLOSED RATHER THAN HIDDEN.
+ *   local   the ed25519 key never left its owner's machine. The relay cannot sign
+ *           for it, so this surface is read-only for that agent and says why.
+ *   hosted  the relay holds the key. Weaker attribution — the operator could sign
+ *           as this agent — but the alternative for someone with nothing installed
+ *           is no agent at all. Custody is reported by can2cup_whoami and by the
+ *           public, unauthenticated GET /hosted/:pub, so a counterparty can always
+ *           weigh what a given signature is worth instead of being misled by it.
+ *
+ * The brake is the mandate, not a hardcoded blocklist: the same rules the local
+ * client enforces before signing run here before a hosted envelope is signed, and
+ * the default mandate (max_commit_amount 0, may_grant empty) means nothing binding
+ * leaves until its owner deliberately widens it.
+ *
+ * Auth: the OAuth authorization step reuses the LINE binding rather than inventing
+ * a second identity system. The human types `/link` to the can2cup bot, gets a short
+ * code, and pastes it into the consent page; that code resolves to their LINE
+ * userId, and to the agent bound to it — or mints one if there is none, which is
+ * what makes this an entrance rather than a second screen.
+ */
+import {
+  type MsgType, PROTOCOL_VERSION, checkMandate, lineDeepLink, pubFromPriv, randomHex, signHex, signRequestHeaders, signingBytes,
+} from "../protocol/index.js";
+// The browser entry is the one that bundles for a Worker: the package's Node entry
+// pulls in `fs` for file output, which we never use.
+// @ts-expect-error no bundled types on this path
+import QR from "qrcode/lib/browser.js";
+
+export const MCP_SERVER_VERSION = "0.4.14";
+
+/**
+ * v0.4.10: a hosted agent may send any message type. The previous build also kept
+ * a hardcoded blocklist on top of the mandate, which meant two overlapping rules
+ * and an agent that felt broken ("why can I not agree to anything?"). One rule is
+ * better: the mandate decides, exactly as it does for a local agent, and the
+ * default mandate is conservative enough (max_commit_amount 0, may_grant empty)
+ * that nothing binding gets out until its owner deliberately widens it. Custody
+ * stays disclosed at GET /hosted/:pub, so a counterparty can still weigh what a
+ * hosted signature is worth.
+ */
+const SENDABLE: readonly MsgType[] = [
+  "text", "question", "proposal", "counter", "accept", "reject", "withdraw", "escalate",
+  "grant", "revoke", "attachment", "close",
+];
+
+/** Conservative starting rules for a hosted agent, mirroring the local mandate.json template. */
+const DEFAULT_HOSTED_MANDATE: HostedMandate = {
+  never_disclose: ["sk-live-", "sk-ant-", "ghp_", "glpat-", "xoxb-", "-----BEGIN"],
+  max_commit_amount: 0,
+  may_grant: [],
+  max_grant_hours: 2,
+};
+
+/** Versions we can speak. We echo the client's if we know it, else offer our latest. */
+const KNOWN_PROTOCOLS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+const LATEST_PROTOCOL = KNOWN_PROTOCOLS[0];
+
+const CODE_TTL_MS = 10 * 60_000;
+
+export interface McpBinding { pub: string; name: string; userId: string }
+export interface McpRoom { name: string; state: string; lastSeq: number; participants: Record<string, string> }
+export interface HostedKey { priv: string; userId: string; createdAt: string }
+export interface HostedMandate {
+  never_disclose: string[];
+  max_commit_amount: number | null;
+  currency?: string;
+  may_grant: string[];
+  max_grant_hours: number;
+}
+/** Per-room capability a hosted agent earned by joining. */
+export interface HostedCap { cap: string; name: string }
+
+/** Everything this surface needs from BridgeDO, so the module stays storage-agnostic. */
+export interface McpDeps {
+  get<T>(k: string): Promise<T | undefined>;
+  put(k: string, v: unknown): Promise<void>;
+  del(k: string): Promise<void>;
+  bindingByUser(userId: string): Promise<McpBinding | undefined>;
+  bindingByPub(pub: string): Promise<McpBinding | undefined>;
+  roomsFor(pub: string): Promise<Record<string, McpRoom>>;
+  pendingInbox(pub: string): Promise<number>;
+  awayAt(pub: string): Promise<string | undefined>;
+  /** Creates the binding both ways, exactly as the LINE /link flow does. */
+  bind(userId: string, pub: string, name: string): Promise<void>;
+  isPaused(pub: string): Promise<boolean>;
+  /** Talk to a RoomDO directly through its binding rather than over the network.
+   *  A loopback fetch to our own hostname is a real round trip that depends on the
+   *  external name being reachable from inside the Worker — under `wrangler dev`
+   *  with a route configured it left the machine entirely and hit production. It
+   *  also skips the worker key check on room creation, which is correct: this is
+   *  an internal caller, not an untrusted one. */
+  roomCall(roomId: string, subpath: string, init?: RequestInit): Promise<Response>;
+  newRoomId(): string;
+  /** The LINE official account id, for the one-tap deep link on the consent page. */
+  lineOa(): string | undefined;
+  /** Operator-set quotas for the hosted tier. */
+  limits(): { roomsPerDay: number };
+}
+
+export const hostedKeyOf = (d: McpDeps, pub: string) => d.get<HostedKey>(`hosted:${pub}`);
+const capsOf = async (d: McpDeps, pub: string) => (await d.get<Record<string, HostedCap>>(`hcap:${pub}`)) ?? {};
+
+/**
+ * Mint an agent identity the relay holds the key for.
+ *
+ * This is the custody tier, and it is a real trade, not a shortcut: the relay can
+ * sign as this agent, so this agent's messages carry weaker attribution than one
+ * signed on its owner's machine. It exists because the alternative for a person
+ * with no laptop install is no agent at all. Custody is disclosed by whoami and
+ * by the public /hosted/:pub endpoint, so a reader of a transcript can always
+ * tell which tier signed an entry. What it may actually say is decided by the
+ * mandate, which starts conservative.
+ */
+export async function createHostedAgent(d: McpDeps, userId: string): Promise<McpBinding> {
+  const priv = randomHex(32);
+  const pub = pubFromPriv(priv);
+  const name = `agent-${pub.slice(0, 6)}`;
+  await d.put(`hosted:${pub}`, { priv, userId, createdAt: new Date().toISOString() } as HostedKey);
+  await d.put(`hmandate:${pub}`, DEFAULT_HOSTED_MANDATE);
+  await d.bind(userId, pub, name);
+  return { pub, name, userId };
+}
+
+interface StoredClient { name: string; redirectUris: string[]; at: number }
+interface StoredCode { clientId: string; pub: string; challenge: string; redirectUri: string; at: number }
+interface StoredToken { pub: string; clientId: string; at: number }
+
+// ------------------------------------------------------------------ oauth ---
+
+/** RFC 9728. Tells a connector which authorization server guards this resource. */
+export const protectedResourceMetadata = (origin: string) => ({
+  resource: `${origin}/mcp`,
+  authorization_servers: [origin],
+  bearer_methods_supported: ["header"],
+  scopes_supported: ["can2cup"],
+});
+
+/** RFC 8414. */
+export const authorizationServerMetadata = (origin: string) => ({
+  issuer: origin,
+  authorization_endpoint: `${origin}/oauth/authorize`,
+  token_endpoint: `${origin}/oauth/token`,
+  registration_endpoint: `${origin}/oauth/register`,
+  response_types_supported: ["code"],
+  grant_types_supported: ["authorization_code"],
+  code_challenge_methods_supported: ["S256"], // PKCE is required, plain is not accepted
+  token_endpoint_auth_methods_supported: ["none"], // public clients only
+  scopes_supported: ["can2cup"],
+});
+
+const b64url = (b: ArrayBuffer): string => {
+  let s = "";
+  for (const x of new Uint8Array(b)) s += String.fromCharCode(x);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+
+async function s256(verifier: string): Promise<string> {
+  return b64url(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier)));
+}
+
+/** RFC 7591 dynamic client registration. Connectors register themselves, so there
+ *  is nothing for the user to copy; we only keep what we need to validate a redirect. */
+export async function register(d: McpDeps, body: unknown): Promise<Response> {
+  const b = (body ?? {}) as { client_name?: string; redirect_uris?: unknown };
+  const uris = Array.isArray(b.redirect_uris) ? b.redirect_uris.filter((u): u is string => typeof u === "string") : [];
+  if (uris.length === 0) return Response.json({ error: "invalid_client_metadata", error_description: "redirect_uris is required" }, { status: 400 });
+  const clientId = randomHex(16);
+  await d.put(`oauth:client:${clientId}`, { name: b.client_name ?? "", redirectUris: uris, at: Date.now() } as StoredClient);
+  return Response.json({
+    client_id: clientId,
+    client_name: b.client_name ?? "",
+    redirect_uris: uris,
+    grant_types: ["authorization_code"],
+    response_types: ["code"],
+    token_endpoint_auth_method: "none",
+  }, { status: 201 });
+}
+
+/** The LINE deep link with "/link" prefilled — the message the bot answers with a code. */
+const lineLink = (oa: string) => lineDeepLink(oa, "/link");
+
+/** Rendered server-side as inline SVG: this page is nearly always open on a desktop
+ *  browser (you add a connector on a computer) while LINE lives on the phone, so a
+ *  tap-through deep link reaches nothing. A QR crosses that gap. Never let QR
+ *  trouble break the page — the typed-code path still works without it. */
+async function qrSvg(target: string): Promise<string | undefined> {
+  try {
+    return await (QR as { toString: (t: string, o: object) => Promise<string> })
+      .toString(target, { type: "svg", margin: 1, width: 168, errorCorrectionLevel: "M" });
+  } catch { return undefined; }
+}
+
+const page = (origin: string, clientName: string, q: URLSearchParams, error?: string, lineOa?: string, qr?: string) => `<!doctype html>
+<html lang="zh-Hant"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>連結 can2cup</title><style>
+:root{color-scheme:light dark;--bg:#fff;--fg:#18181b;--mut:#71717a;--line:#e4e4e7;--acc:#2563eb;--err:#dc2626}
+@media(prefers-color-scheme:dark){:root{--bg:#18181b;--fg:#fafafa;--mut:#a1a1aa;--line:#3f3f46;--acc:#60a5fa;--err:#f87171}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.6 system-ui,-apple-system,"Noto Sans TC",sans-serif;display:grid;place-items:center;min-height:100vh;padding:24px}
+.card{width:100%;max-width:420px;border:1px solid var(--line);border-radius:14px;padding:28px}
+h1{font-size:19px;margin:0 0 6px}p{color:var(--mut);margin:0 0 18px}
+ol{color:var(--mut);padding-left:20px;margin:0 0 18px}li{margin:6px 0}
+code{background:var(--line);padding:1px 6px;border-radius:5px;color:var(--fg)}
+input{width:100%;padding:11px 13px;font:inherit;font-variant-numeric:tabular-nums;letter-spacing:.08em;text-transform:uppercase;border:1px solid var(--line);border-radius:9px;background:transparent;color:var(--fg)}
+button{width:100%;margin-top:14px;padding:11px;font:inherit;font-weight:600;border:0;border-radius:9px;background:var(--acc);color:#fff;cursor:pointer}
+.qr{text-align:center;margin:0 0 4px}.qr svg{width:168px;height:168px;background:#fff;padding:8px;border-radius:10px}
+.cap{color:var(--mut);font-size:13px;text-align:center;margin:0 0 14px}
+.line{display:inline-block;text-decoration:none;color:#06c755;font-weight:600}
+.err{color:var(--err);margin:0 0 14px}.f{color:var(--mut);font-size:13px;margin:16px 0 0}
+.step{font-weight:600;margin:0 0 8px}
+</style></head><body><div class="card">
+<h1>把 can2cup 連給${clientName ? " " + clientName.replace(/[<>&]/g, "") : "這個 app"}</h1>
+<p>讓這個 app 裡的 AI 能替你在 can2cup 房間裡跟別人的 agent 對話。</p>
+${error ? `<p class="err">${error}</p>` : ""}
+${qr ? `<p class="step">① 用手機 LINE 掃這個 QR</p><div class="qr">${qr}</div>
+<p class="cap">傳聲罐罐的聊天會打開,<code>/link</code> 已經填好 —— 按送出就好。<br>
+${lineOa ? `已經在手機上看這頁?<a class="line" href="${lineLink(lineOa)}">直接開啟 LINE</a>` : ""}</p>
+<p class="step">② 把機器人回你的代碼貼到下面</p>`
+  : `<ol><li>在 LINE 對 <strong>傳聲罐罐 can2cup</strong> 傳 <code>/link</code></li><li>把機器人回你的代碼貼到下面</li></ol>`}
+<form method="post" action="${origin}/oauth/authorize?${q.toString()}">
+<input name="code" placeholder="AB12-CD34" autocomplete="off" autocapitalize="characters" required autofocus>
+<button type="submit">連結</button></form>
+<p class="f"><a href="${origin}/terms" style="color:var(--mut)">服務條款與濫用通報</a></p>
+<p class="f">代碼 10 分鐘內有效。<br>
+還沒有 can2cup agent 的話,這一步會替你建立一個,<strong>金鑰由這台 relay 保管</strong> —— 方便,但它的訊息歸屬強度比裝在自己電腦上的弱,而且<strong>不能代你做出承諾</strong>(accept / grant)。想要完整強度就在自己機器上裝 can2cup。</p>
+</div></body></html>`;
+
+export async function authorizeGet(d: McpDeps, url: URL, origin: string): Promise<Response> {
+  const q = url.searchParams;
+  const clientId = q.get("client_id") ?? "";
+  const client = await d.get<StoredClient>(`oauth:client:${clientId}`);
+  if (!client) return new Response("unknown client_id", { status: 400 });
+  if (!client.redirectUris.includes(q.get("redirect_uri") ?? "")) return new Response("redirect_uri not registered for this client", { status: 400 });
+  if (q.get("code_challenge_method") !== "S256" || !q.get("code_challenge")) return new Response("PKCE with S256 is required", { status: 400 });
+  const oa = d.lineOa();
+  return new Response(page(origin, client.name, q, undefined, oa, oa ? await qrSvg(lineLink(oa)) : undefined), { headers: { "content-type": "text/html; charset=utf-8" } });
+}
+
+export async function authorizePost(d: McpDeps, url: URL, form: FormData, origin: string): Promise<Response> {
+  const q = url.searchParams;
+  const clientId = q.get("client_id") ?? "";
+  const redirectUri = q.get("redirect_uri") ?? "";
+  const client = await d.get<StoredClient>(`oauth:client:${clientId}`);
+  if (!client || !client.redirectUris.includes(redirectUri)) return new Response("bad client", { status: 400 });
+
+  const typed = String(form.get("code") ?? "").trim().toUpperCase().replace(/\s+/g, "");
+  const rec = typed ? await d.get<{ userId: string; at: number }>(`pcode:${typed}`) : undefined;
+  const oa = d.lineOa();
+  const qr = oa ? await qrSvg(lineLink(oa)) : undefined;
+  const fail = (m: string) => new Response(page(origin, client.name, q, m, oa, qr), { status: 400, headers: { "content-type": "text/html; charset=utf-8" } });
+  if (!rec) return fail("這個代碼無效。請在 LINE 重新輸入 /link 取得新的。");
+  if (Date.now() - rec.at > CODE_TTL_MS) return fail("代碼已過期(10 分鐘)。請重新取得。");
+  // No agent yet? Make one. This is the whole point of the connector: a person
+  // with nothing installed must be able to finish this flow.
+  const binding = (await d.bindingByUser(rec.userId)) ?? (await createHostedAgent(d, rec.userId));
+
+  // One-shot: the code cannot be replayed into a second authorization.
+  await d.del(`pcode:${typed}`);
+  const code = randomHex(24);
+  await d.put(`oauth:code:${code}`, {
+    clientId, pub: binding.pub, challenge: q.get("code_challenge")!, redirectUri, at: Date.now(),
+  } as StoredCode);
+
+  const back = new URL(redirectUri);
+  back.searchParams.set("code", code);
+  if (q.get("state")) back.searchParams.set("state", q.get("state")!);
+  return Response.redirect(back.toString(), 302);
+}
+
+export async function token(d: McpDeps, form: URLSearchParams): Promise<Response> {
+  const bad = (e: string, desc: string) => Response.json({ error: e, error_description: desc }, { status: 400 });
+  if (form.get("grant_type") !== "authorization_code") return bad("unsupported_grant_type", "only authorization_code is supported");
+  const code = form.get("code") ?? "";
+  const rec = await d.get<StoredCode>(`oauth:code:${code}`);
+  if (!rec) return bad("invalid_grant", "unknown or already-used code");
+  await d.del(`oauth:code:${code}`); // single use, whatever happens next
+  if (Date.now() - rec.at > 60_000) return bad("invalid_grant", "code expired");
+  if (rec.clientId !== (form.get("client_id") ?? "")) return bad("invalid_grant", "code was issued to a different client");
+  if (rec.redirectUri !== (form.get("redirect_uri") ?? "")) return bad("invalid_grant", "redirect_uri mismatch");
+  const verifier = form.get("code_verifier") ?? "";
+  if (!verifier || (await s256(verifier)) !== rec.challenge) return bad("invalid_grant", "PKCE verification failed");
+
+  const access = randomHex(32);
+  await d.put(`oauth:tok:${access}`, { pub: rec.pub, clientId: rec.clientId, at: Date.now() } as StoredToken);
+  return Response.json({ access_token: access, token_type: "Bearer", scope: "can2cup" });
+}
+
+// -------------------------------------------------------------------- mcp ---
+
+const NONE = { type: "object", properties: {}, additionalProperties: false } as const;
+
+const TOOLS = [
+  {
+    name: "can2cup_whoami",
+    description:
+      "Who this agent is on can2cup: its public key, display name, who holds its signing key, whether a "
+      + "principal is linked on LINE, and how many principal instructions are waiting.",
+    inputSchema: NONE,
+  },
+  {
+    name: "can2cup_rooms",
+    description:
+      "The can2cup rooms this agent is in, with each room's name, open/closed state, last sequence number "
+      + "and participants.",
+    inputSchema: NONE,
+  },
+  {
+    name: "can2cup_join",
+    description:
+      "Join a room from an invite link the other party gave you (looks like https://<relay>/j/<id>#<secret>). "
+      + "Hosted agents only — an agent whose key lives on its owner's machine must join from there.",
+    inputSchema: {
+      type: "object",
+      properties: { invite: { type: "string", description: "the full invite link, including the part after #" } },
+      required: ["invite"], additionalProperties: false,
+    },
+  },
+  {
+    name: "can2cup_create_room",
+    description:
+      "Open a new room and get an invite link to hand to the other party out of band (LINE, mail, in person). "
+      + "Their agent joins with can2cup_join. Hosted agents only.",
+    inputSchema: {
+      type: "object",
+      properties: { name: { type: "string", description: "what this conversation is about" } },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "can2cup_invite",
+    description: "Get the invite link for a room you are already in, to give to someone else.",
+    inputSchema: {
+      type: "object",
+      properties: { room: { type: "string", description: "room id (12 hex)" } },
+      required: ["room"], additionalProperties: false,
+    },
+  },
+  {
+    name: "can2cup_send",
+    description:
+      "Say something in a room. `type` carries the intent. Your principal's mandate is checked before "
+      + "anything is signed: a blocked message is never sent and you are told why.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        room: { type: "string", description: "room id (12 hex)" },
+        type: { type: "string", enum: [...SENDABLE], description: "message intent (default text)" },
+        text: { type: "string", description: "what to say" },
+        amount: { type: "number", description: "figure attached to a proposal, counter or accept" },
+        scope: { type: "string", description: "for a grant: what is being authorised, e.g. \"read:logs/*\"" },
+        expiresHours: { type: "number", description: "for a grant: how long it lasts" },
+        ref: { type: "number", description: "for a revoke: the seq of the grant being withdrawn" },
+        url: { type: "string", description: "for an attachment: an https URL (the relay never stores bytes)" },
+      },
+      required: ["room", "text"], additionalProperties: false,
+    },
+  },
+  {
+    name: "can2cup_history",
+    description: "Read a room's transcript from a sequence number onwards.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        room: { type: "string", description: "room id (12 hex)" },
+        since: { type: "number", description: "return messages after this seq (default 0)" },
+      },
+      required: ["room"], additionalProperties: false,
+    },
+  },
+] as const;
+
+const WRITE_TOOLS = ["can2cup_join", "can2cup_send", "can2cup_create_room", "can2cup_invite"];
+
+const rpcErr = (id: unknown, code: number, message: string) =>
+  Response.json({ jsonrpc: "2.0", id: id ?? null, error: { code, message } });
+
+const text = (id: unknown, s: string) =>
+  Response.json({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: s }] } });
+
+/**
+ * The outbound gate, for hosted agents only. The local client enforces the full
+ * mandate from mandate.json before anything is signed; a hosted agent has no
+ * local client, so the same rules have to live here or the easy tier ships with
+ * no brake at all — which is the one thing this product must not do.
+ */
+async function mandateBlock(d: McpDeps, pub: string, type: MsgType, body: Record<string, unknown>): Promise<string | null> {
+  if (await d.isPaused(pub)) return "your principal has paused this agent's outbound messages (/resume in LINE).";
+  const m = { ...DEFAULT_HOSTED_MANDATE, ...((await d.get<HostedMandate>(`hmandate:${pub}`)) ?? {}) };
+  const msg = checkMandate(m, type, body);
+  // A blocked verdict gets the explicit "NOT SENT." suffix here: a hosted agent has no
+  // local client output to make that unmistakable, the tool result is all it sees.
+  return msg && (msg.startsWith("blocked by mandate") ? `${msg} NOT SENT.` : msg);
+}
+
+const j = async (res: Response): Promise<Record<string, unknown>> => {
+  const t = await res.text();
+  try { return t ? JSON.parse(t) : {}; } catch { return { error: t.slice(0, 200) }; }
+};
+
+async function callTool(d: McpDeps, pub: string, name: string, args: Record<string, unknown>, origin: string): Promise<string> {
+  const binding = await d.bindingByPub(pub);
+  const hosted = await hostedKeyOf(d, pub);
+  // v0.9.14: a hosted agent has no heartbeat; each connector call is its "being seen", so the idle-binding
+  // rule (v0.9.12) can cover it the same way it covers a local agent.
+  if (hosted) await d.put(`seen:${pub}`, new Date().toISOString());
+
+  if (WRITE_TOOLS.includes(name) && !hosted) {
+    return "This agent's signing key lives on its owner's machine, so the relay cannot act for it. "
+      + "Use the local can2cup client (or the can2cup CLI) for anything that has to be signed.";
+  }
+  const me = hosted ? { pub, priv: hosted.priv, name: binding?.name ?? "" } : undefined;
+
+  switch (name) {
+    case "can2cup_whoami": {
+      const away = await d.awayAt(pub);
+      return JSON.stringify({
+        pubkey: pub,
+        name: binding?.name ?? "",
+        keyCustody: hosted ? "hosted — this relay holds the signing key" : "local — the key never leaves its owner's machine",
+        canCommit: hosted ? "yes, within the mandate below" : "only from the local client",
+        principalLinkedOnLine: !!binding,
+        pendingPrincipalInstructions: await d.pendingInbox(pub),
+        localAgentAwake: hosted ? "n/a (hosted)" : !away,
+      }, null, 2);
+    }
+
+    case "can2cup_rooms": {
+      const rooms = await d.roomsFor(pub);
+      const list = Object.entries(rooms).map(([id, r]) => ({
+        room: id, name: r.name, state: r.state, lastSeq: r.lastSeq, participants: Object.values(r.participants),
+      }));
+      return list.length ? JSON.stringify(list, null, 2) : "This agent is not in any can2cup room.";
+    }
+
+    case "can2cup_join": {
+      // The secret rides in the URL fragment precisely so it never reaches a server log.
+      const m = /\/j\/([0-9a-f]{12})#(.+)$/.exec(String(args.invite ?? "").trim());
+      if (!m) return "That does not look like a can2cup invite link (expected https://<relay>/j/<id>#<secret>).";
+      const [, room, frag] = m;
+      // #<secret>.<key> marks an E2E room. A hosted agent joining one would hand this relay
+      // the room key, which silently defeats the encryption — refuse rather than pretend.
+      if (frag.includes(".")) {
+        return "This room is END-TO-END ENCRYPTED. A hosted agent's key (and then the room key) would "
+          + "live on the relay, which is exactly what E2E exists to prevent — join it from a local "
+          + "can2cup client instead (npm i -g <relay>/dl/can2cup.tgz).";
+      }
+      const secret = frag;
+      const path = `/rooms/${room}/join`;
+      const body = JSON.stringify({ pubkey: pub, name: me!.name });
+      const res = await d.roomCall(room, "/join", {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${secret}`,
+          ...signRequestHeaders("POST", path, body, me!),
+        },
+        body,
+      });
+      const out = await j(res);
+      if (!res.ok) return `Could not join ${room}: ${String(out.error ?? res.status)}`;
+      const caps = await capsOf(d, pub);
+      caps[room] = { cap: String(out.cap ?? ""), name: String(out.name ?? "") };
+      await d.put(`hcap:${pub}`, caps);
+      return `Joined room ${room}${out.name ? ` "${String(out.name)}"` : ""}. Participants: `
+        + Object.values((out.participants ?? {}) as Record<string, { name?: string }>).map((p) => p.name || "?").join(", ");
+    }
+
+    case "can2cup_create_room": {
+      const day = new Date().toISOString().slice(0, 10);
+      const qk = `q:rooms:${pub}:${day}`;
+      const used = (await d.get<number>(qk)) ?? 0;
+      const lim = d.limits().roomsPerDay;
+      if (used >= lim) return `Daily room quota reached for this identity (${lim}/day). NOT CREATED — try tomorrow or ask the operator.`;
+      const id = d.newRoomId();
+      const created = await j(await d.roomCall(id, "", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ name: String(args.name ?? ""), creator: { pubkey: pub, name: me!.name } }),
+      }));
+      if (typeof created.id !== "string") return `Could not open a room: ${String(created.error ?? "unknown error")}`;
+      const caps = await capsOf(d, pub);
+      caps[id] = { cap: String(created.cap ?? ""), name: String(args.name ?? "") };
+      await d.put(`hcap:${pub}`, caps);
+      await d.put(qk, used + 1);
+      return `Room ${id} is open.\n\nInvite link — give it to the other party whole and privately; `
+        + `everything after the # is the secret:\n${origin}/j/${created.id}#${String(created.secret)}`;
+    }
+
+    case "can2cup_invite": {
+      const room = String(args.room ?? "");
+      const caps = await capsOf(d, pub);
+      const cap = caps[room]?.cap;
+      if (!cap) return `This agent has no capability for room ${room}.`;
+      // Only a cap-authenticated caller gets the current invite secret back.
+      const info = await j(await d.roomCall(room, "/info", { headers: { authorization: `Bearer ${cap}` } }));
+      if (typeof info.secret !== "string") return `Could not read the invite secret for ${room}: ${String(info.error ?? "unknown error")}`;
+      return `${origin}/j/${room}#${info.secret}`;
+    }
+
+    case "can2cup_send": {
+      const room = String(args.room ?? "");
+      const type = (args.type ?? "text") as MsgType;
+      if (!SENDABLE.includes(type)) return `"${type}" is not a can2cup message type.`;
+      const caps = await capsOf(d, pub);
+      const cap = caps[room]?.cap;
+      if (!cap) return `This agent has no capability for room ${room}. Join it first with can2cup_join.`;
+
+      const body: Record<string, unknown> = { text: String(args.text ?? "") };
+      if (typeof args.amount === "number") body.amount = args.amount;
+      if (typeof args.scope === "string") body.scope = args.scope;
+      if (typeof args.ref === "number") body.ref = args.ref;
+      if (typeof args.url === "string") body.url = args.url;
+      if (typeof args.expiresHours === "number") {
+        body.expires = new Date(Date.now() + args.expiresHours * 3.6e6).toISOString();
+      }
+      const blocked = await mandateBlock(d, pub, type, body);
+      if (blocked) return blocked;
+
+      // prev must be the hash of the latest entry we have seen, so read before signing.
+      const poll = await j(await d.roomCall(room, "/messages?since=999999999", { headers: { authorization: `Bearer ${cap}` } }));
+      if (typeof poll.lastHash !== "string") return `Could not read room ${room}: ${String(poll.error ?? "unknown error")}`;
+      const unsigned = { v: PROTOCOL_VERSION, room, from: pub, ts: new Date().toISOString(), type, body, prev: poll.lastHash };
+      const sent = await j(await d.roomCall(room, "/messages", {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${cap}` },
+        body: JSON.stringify({ ...unsigned, sig: signHex(signingBytes(unsigned), me!.priv) }),
+      }));
+      if (typeof sent.seq !== "number") return `Not sent: ${String(sent.error ?? "unknown error")}`;
+      return `Sent as ${type} at seq ${sent.seq} in room ${room}.`;
+    }
+
+    case "can2cup_history": {
+      const room = String(args.room ?? "");
+      const since = typeof args.since === "number" ? args.since : 0;
+      const caps = await capsOf(d, pub);
+      const cap = caps[room]?.cap;
+      if (!cap) return `This agent has no capability for room ${room}.`;
+      const poll = await j(await d.roomCall(room, `/messages?since=${since}`, { headers: { authorization: `Bearer ${cap}` } }));
+      const msgs = (poll.messages ?? []) as Array<{ seq: number; from: string; type: string; body: { text?: string }; ts: string }>;
+      if (!Array.isArray(msgs) || msgs.length === 0) return `Nothing in room ${room} after seq ${since}.`;
+      return msgs.map((e) => `#${e.seq} ${e.from === "relay" ? "relay" : e.from.slice(0, 8)} [${e.type}] ${e.body?.text ?? JSON.stringify(e.body)}`).join("\n");
+    }
+
+    default:
+      return `unknown tool: ${name}`;
+  }
+}
+
+/**
+ * Streamable HTTP transport. One endpoint: POST carries JSON-RPC, a notification
+ * (no id) gets 202 with no body, everything else answers inline. We do not open
+ * an SSE stream — nothing here pushes, so advertising one would be a lie.
+ */
+export async function handleMcp(d: McpDeps, req: Request, origin: string): Promise<Response> {
+  const unauthorized = () => new Response(JSON.stringify({ error: "unauthorized" }), {
+    status: 401,
+    headers: {
+      "content-type": "application/json",
+      // Sends a connector to the metadata document instead of leaving it guessing.
+      "www-authenticate": `Bearer resource_metadata="${origin}/.well-known/oauth-protected-resource"`,
+    },
+  });
+
+  if (req.method === "GET") return new Response("this MCP endpoint does not open a server stream", { status: 405 });
+  if (req.method !== "POST") return new Response("method not allowed", { status: 405 });
+
+  const auth = req.headers.get("authorization") ?? "";
+  if (!auth.startsWith("Bearer ")) return unauthorized();
+  const tok = await d.get<StoredToken>(`oauth:tok:${auth.slice(7)}`);
+  if (!tok) return unauthorized();
+
+  let msg: { jsonrpc?: string; id?: unknown; method?: unknown; params?: unknown };
+  try { msg = (await req.json()) as typeof msg; }
+  catch { return rpcErr(null, -32700, "invalid JSON"); }
+
+  const id = msg.id;
+  const method = typeof msg.method === "string" ? msg.method : "";
+  if (msg.jsonrpc !== "2.0" || !method) return rpcErr(id ?? null, -32600, "invalid JSON-RPC request");
+  if (await d.get(`ban:pub:${tok.pub}`)) return rpcErr(id ?? null, -32000, "this identity has been banned by the relay operator");
+  // A notification has no id and expects no body.
+  if (id === undefined) return new Response(null, { status: 202 });
+
+  switch (method) {
+    case "initialize": {
+      const asked = (msg.params as { protocolVersion?: string } | undefined)?.protocolVersion;
+      return Response.json({
+        jsonrpc: "2.0", id,
+        result: {
+          protocolVersion: asked && KNOWN_PROTOCOLS.includes(asked) ? asked : LATEST_PROTOCOL,
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: "can2cup", version: MCP_SERVER_VERSION },
+          instructions:
+            "can2cup rooms let agents that answer to different humans talk to each other. Call can2cup_whoami "
+            + "first: it tells you whether this agent's key is hosted here or lives on its owner's machine. "
+            + "A hosted agent can join rooms and talk, but cannot send accept / grant / revoke / close — those "
+            + "create or withdraw authority and must be signed on the principal's own machine. An agent with a "
+            + "local key is read-only through this surface; use its local client to send.",
+        },
+      }, { headers: { "mcp-session-id": randomHex(16) } });
+    }
+    case "ping":
+      return Response.json({ jsonrpc: "2.0", id, result: {} });
+    case "tools/list":
+      return Response.json({ jsonrpc: "2.0", id, result: { tools: TOOLS } });
+    case "tools/call": {
+      const p = msg.params as { name?: string; arguments?: Record<string, unknown> } | undefined;
+      const name = p?.name ?? "";
+      if (!TOOLS.some((t) => t.name === name)) return rpcErr(id, -32602, `unknown tool: ${name}`);
+      try { return text(id, await callTool(d, tok.pub, name, p?.arguments ?? {}, origin)); }
+      catch (e) { return text(id, `tool failed: ${(e as Error).message}`); }
+    }
+    case "resources/list":
+      return Response.json({ jsonrpc: "2.0", id, result: { resources: [] } });
+    case "prompts/list":
+      return Response.json({ jsonrpc: "2.0", id, result: { prompts: [] } });
+    default:
+      return rpcErr(id, -32601, `method not found: ${method}`);
+  }
+}

package/tsconfig.relay.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["@cloudflare/workers-types"]
+  },
+  "include": ["src/protocol", "src/relay"]
+}