can2cup 0.10.2 → 0.10.4

package/src/protocol/mandate.ts

@@ -0,0 +1,61 @@
+/**
+ * The mandate rule set — ONE implementation for both enforcement points.
+ *
+ * The same brake guards two floors: the local client checks the principal's
+ * full mandate.json before anything is signed on their machine, and the hosted
+ * surface (relay/mcp-http.ts) checks the relay-held mandate for agents whose
+ * keys never leave the relay. A rule that exists on one floor and not the
+ * other is a hole, not a feature — so the rules live here, in protocol/, the
+ * layer both the Node client and the Worker may import. What stays with the
+ * callers, by design: pause state (different sources) and message framing
+ * (the hosted surface appends "NOT SENT." to blocked verdicts).
+ */
+import { canon } from "./canon.js";
+import type { MsgType } from "./envelope.js";
+
+/** The enforceable subset of a mandate. The local Mandate and the hosted
+ *  mandate both satisfy it structurally; extra fields (may_share, brief…) are
+ *  advisory and never enforced here. */
+export interface MandateRules {
+  never_disclose: string[];
+  may_grant: string[];
+  max_commit_amount: number | null;
+  currency?: string;
+  max_grant_hours: number;
+}
+
+/** Glob-ish scope match: `*` matches any run of characters. Case-insensitive. */
+export function scopeAllowed(scope: string, patterns: string[]): boolean {
+  const s = scope.trim().toLowerCase();
+  return patterns.some((p) => {
+    const re = new RegExp("^" + p.trim().toLowerCase().split("*").map((x) => x.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$");
+    return re.test(s);
+  });
+}
+
+/** Returns the reason a send must be blocked, or null when the mandate allows it.
+ *  Checks the OUTBOUND body — for E2E rooms this must run on the plaintext,
+ *  before encryption. */
+export function checkMandate(m: MandateRules, type: MsgType, body: Record<string, unknown>): string | null {
+  const flat = canon(body).toLowerCase();
+  for (const s of m.never_disclose) {
+    if (s && flat.includes(s.toLowerCase())) return `blocked by mandate: outbound body contains a never_disclose string.`;
+  }
+  if (["proposal", "counter", "accept"].includes(type) && m.max_commit_amount != null && typeof body.amount === "number") {
+    if (body.amount > m.max_commit_amount) return `blocked by mandate: amount ${body.amount} exceeds max_commit_amount ${m.max_commit_amount}${m.currency ? " " + m.currency : ""}.`;
+  }
+  if (type === "grant") {
+    const scope = typeof body.scope === "string" ? body.scope : "";
+    if (!scope) return `grant needs a scope (e.g. "read:logs/*", "deploy:staging").`;
+    if (!scopeAllowed(scope, m.may_grant)) return `blocked by mandate: scope "${scope}" is not in may_grant ${JSON.stringify(m.may_grant)} — escalate to your principal instead.`;
+    const exp = Date.parse(String(body.expires ?? ""));
+    if (!Number.isFinite(exp)) return `grant needs an ISO expiry (use expiresHours).`;
+    const hours = (exp - Date.now()) / 3.6e6;
+    if (hours > m.max_grant_hours + 0.01) return `blocked by mandate: grant expiry ${hours.toFixed(1)}h exceeds max_grant_hours ${m.max_grant_hours}.`;
+  }
+  if (type === "revoke" && typeof body.ref !== "number") return `revoke needs ref = seq of the grant being revoked.`;
+  if (type === "attachment") {
+    if (typeof body.url !== "string" || !/^https?:\/\//.test(body.url)) return `attachment needs an https URL (the relay never stores bytes).`;
+  }
+  return null;
+}

package/src/protocol/principal.ts

@@ -0,0 +1,90 @@
+/**
+ * Principal-signed messages — the principal → agent channel, end to end.
+ *
+ * v0.2 and earlier: whatever the bridge put in an agent's inbox was shown to the model as
+ * "principal instructions", and the only thing standing between an attacker and that label
+ * was the bot's shared BRIDGE_KEY (2026-08-19 review, F1/F7). v0.3 gives the principal an
+ * ed25519 keypair of their own (`~/.parley/principal.json`). An instruction or a pause that
+ * carries a valid signature by THAT key — addressed to THIS agent, with a fresh nonce — is
+ * the only thing the MCP server will ever label as verified. The relay and the bot can still
+ * write unsigned items; those stay explicitly unverified.
+ *
+ * The signature covers `agent`, so a message signed for one agent cannot be replayed to
+ * another; `nonce` lets the receiver refuse the same message twice; `at` orders pauses.
+ * `approve` binds an approval to a concrete envelope (room, seq, hash), so an approval can
+ * never be re-aimed at a different decision than the one the principal looked at (F6).
+ */
+import { canon } from "./canon.js";
+import { randomHex, signHex, verifyHex } from "./crypto.js";
+
+export interface ApproveRef { room: string; seq: number; hash: string; ok: boolean }
+
+export interface PrincipalMsg {
+  kind: "say" | "pause";
+  agent: string;   // the agent's pubkey this is addressed to
+  at: string;      // ISO-8601
+  nonce: string;   // random hex; receivers keep a seen-set
+  text?: string;   // say
+  paused?: boolean; // pause
+  approve?: ApproveRef; // say: this text is a decision on one specific envelope
+}
+export interface SignedPrincipalMsg extends PrincipalMsg { pub: string; sig: string }
+
+export function principalSigningBytes(m: PrincipalMsg): string {
+  const { kind, agent, at, nonce, text, paused, approve } = m;
+  return canon({ kind, agent, at, nonce, text, paused, approve });
+}
+
+export function signPrincipal(m: Omit<PrincipalMsg, "at" | "nonce"> & Partial<Pick<PrincipalMsg, "at" | "nonce">>, priv: string, pub: string): SignedPrincipalMsg {
+  const full: PrincipalMsg = { ...m, at: m.at ?? new Date().toISOString(), nonce: m.nonce ?? randomHex(16) };
+  return { ...full, pub, sig: signHex(principalSigningBytes(full), priv) };
+}
+
+/** Structural + cryptographic check. `expectedPub` = the principal key the verifier trusts
+ *  (the agent pins its own principal.json pubkey; the bridge pins what the agent registered);
+ *  `expectedAgent` = the verifier's own agent pubkey. */
+export function verifyPrincipal(s: SignedPrincipalMsg, expectedPub: string, expectedAgent: string): { ok: boolean; error?: string } {
+  if (!s || typeof s !== "object") return { ok: false, error: "not a message" };
+  if (s.kind !== "say" && s.kind !== "pause") return { ok: false, error: "bad kind" };
+  if (!/^[0-9a-f]{64}$/.test(s.pub ?? "")) return { ok: false, error: "bad pub" };
+  if (s.pub !== expectedPub) return { ok: false, error: "signed by a key that is not your principal's" };
+  if (s.agent !== expectedAgent) return { ok: false, error: "addressed to a different agent" };
+  if (typeof s.nonce !== "string" || s.nonce.length < 16) return { ok: false, error: "bad nonce" };
+  if (!Number.isFinite(Date.parse(s.at ?? ""))) return { ok: false, error: "bad timestamp" };
+  if (s.kind === "say" && typeof s.text !== "string") return { ok: false, error: "say without text" };
+  if (s.kind === "pause" && typeof s.paused !== "boolean") return { ok: false, error: "pause without paused flag" };
+  if (!verifyHex(s.sig, principalSigningBytes(s), s.pub)) return { ok: false, error: "bad principal signature" };
+  return { ok: true };
+}
+
+// ------------------------------------------------ signed HTTP requests ---
+
+/** Requests that must prove possession of a key (agent → bridge, agent → room admin ops,
+ *  principal → bridge) carry three headers and sign "METHOD\nPATH\nTS\nBODY". The relay
+ *  checks the timestamp is within ±5 minutes. Same scheme for every key role, so one helper. */
+export const REQ_SIG_SKEW_MS = 5 * 60 * 1000;
+
+export function requestSigningBytes(method: string, path: string, ts: string, body: string): string {
+  return `${method}\n${path}\n${ts}\n${body}`;
+}
+
+export function signRequestHeaders(method: string, path: string, body: string, key: { pub: string; priv: string }, prefix = "x-parley"): Record<string, string> {
+  const ts = new Date().toISOString();
+  return {
+    [`${prefix}-pub`]: key.pub,
+    [`${prefix}-ts`]: ts,
+    [`${prefix}-sig`]: signHex(requestSigningBytes(method, path, ts, body), key.priv),
+  };
+}
+
+export function verifyRequestHeaders(
+  h: (name: string) => string | undefined, method: string, path: string, body: string, prefix = "x-parley", now = Date.now(),
+): { ok: true; pub: string } | { ok: false; error: string } {
+  const pub = h(`${prefix}-pub`) ?? "";
+  const ts = h(`${prefix}-ts`) ?? "";
+  const sig = h(`${prefix}-sig`) ?? "";
+  if (!/^[0-9a-f]{64}$/.test(pub) || !ts || !sig) return { ok: false, error: "missing signature headers" };
+  if (Math.abs(now - Date.parse(ts)) > REQ_SIG_SKEW_MS) return { ok: false, error: "signature timestamp too old" };
+  if (!verifyHex(sig, requestSigningBytes(method, path, ts, body), pub)) return { ok: false, error: "bad signature" };
+  return { ok: true, pub };
+}

package/src/protocol/release.ts

@@ -0,0 +1,35 @@
+// v0.10.0 (security G-3, P2): release signing.
+//
+// The relay serves the install tarball; the maintainer SIGNS it. These are different people in the threat model
+// (or the same person on different days), so the key that vouches for a release must not live on the relay.
+// The private half stays offline on the maintainer's machine (scripts/release-key.mjs); this file carries the
+// public half, compiled into every client. A client trusts a release only if manifest.sig verifies against one
+// of these keys. Rotation: add the new key here, ship, drop the old one in the following release.
+import { canon } from "./canon.js";
+import { verifyHex } from "./crypto.js";
+
+export const RELEASE_PUBS: string[] = [
+  "7a025a45418ea95d0aaf6738749cf72d40207965610d1a31cb3db6233f50d571", // 2026-09-05, the maintainer's home machine
+];
+
+export interface ReleaseManifest {
+  v: number;
+  version: string;
+  date: string;
+  /** file name → sha256 hex; every alias the relay serves maps to the same hash */
+  files: Record<string, string>;
+  changelogSha256?: string;
+  permissionChange?: boolean;
+  dataFlowChange?: boolean;
+  minClient?: string;
+}
+
+/** Signature over canon(manifest) — the same canonical JSON every envelope uses; no new format. */
+export function verifyManifest(m: unknown, sigHex: string, pubs: string[]): { ok: true; pub: string } | { ok: false; reason: string } {
+  const x = m as Partial<ReleaseManifest> | null;
+  if (!x || typeof x !== "object" || x.v !== 1 || typeof x.version !== "string" || !x.files || typeof x.files !== "object") return { ok: false, reason: "release manifest is malformed" };
+  if (!/^[0-9a-f]{128}$/.test(sigHex)) return { ok: false, reason: "release manifest signature is malformed" };
+  const msg = canon(x);
+  for (const pub of pubs) if (verifyHex(sigHex, msg, pub)) return { ok: true, pub };
+  return { ok: false, reason: `release manifest signature does not verify against any release key this client trusts (${pubs.map((p) => p.slice(0, 8) + "…").join(", ")}) — release key not trusted by this client, or the manifest was altered` };
+}

package/src/protocol/room.ts

@@ -0,0 +1,115 @@
+/** Shared room shapes and the invite encodings. */
+export interface RoomPolicy {
+  maxMessages: number; // hard cap per room; hitting it forces a close
+  ttlSec: number;      // relay refuses appends after createdAt + ttl
+}
+export const DEFAULT_POLICY: RoomPolicy = { maxMessages: 200, ttlSec: 6 * 3600 };
+
+export interface Participant { name: string; joinedAt: string; removed?: string /* ISO, set by eject */ }
+
+export interface RoomInfo {
+  id: string;
+  name: string;
+  policy: RoomPolicy;
+  participants: Record<string, Participant>; // pubkey -> participant (ejected ones stay listed, with `removed`)
+  createdAt: string;
+  createdBy: string;
+  state: "open" | "closed";
+  lastSeq: number;
+  lastHash: string;
+  relayPub?: string; // the relay's signing pubkey (v0.3+); clients pin it per room
+  secret?: string;   // the CURRENT invite secret — only returned to a caller authenticated by their own cap
+  e2e?: boolean;     // v0.5.0: bodies are ciphertext; the key lives in the invite fragment, never here
+  // Portable rooms / mirrors (v0.4.15+):
+  pastRelayPubs?: string[];    // relay keys this room lived under before it was imported here
+  role?: "mirror";             // absent = primary (writable); "mirror" = read-only replica fed by /replicate
+  origin?: string;             // mirror only: the primary relay this replica follows
+  mirrors?: string[];          // primary only: relays every append is replicated to
+}
+
+/** What GET /rooms/:id/export returns and POST /rooms/:id/import accepts. The chain is
+ *  re-verified on import — an export is claimed evidence, never trusted evidence. */
+export interface RoomExport {
+  format: "parley-export-1";
+  exportedAt: string;
+  room: {
+    id: string; name: string; policy: RoomPolicy; participants: Record<string, Participant>;
+    createdAt: string; createdBy: string; state: "open" | "closed"; e2e?: boolean;
+  };
+  secret?: string;    // only present for a cap-authenticated exporter (same rule as info)
+  messages: unknown[]; // Envelope[]; typed loosely so the importer must verify, not assume
+  relayPub?: string;  // the exporting relay's signing key — system events verify against it
+  head?: unknown;     // the exporting relay's signed head over the tail
+}
+
+/**
+ * Invite = everything the other side needs: relay (u), room id (r), room secret (s), name (n).
+ *
+ * Two encodings of the same thing:
+ *   URL     https://<relay>/j/<room>?n=<name>#<secret>   ← the one to hand to humans
+ *   token   parley1.<base64url json>                     ← compact, for logs / agent-only paths
+ *
+ * The URL is the primary form: a human can click it (the relay serves a landing page
+ * that explains what to paste to their agent), a phone can scan it as a QR code, and
+ * an agent can paste it straight into can2cup_join. The secret rides in the fragment,
+ * so it never appears in the relay's request logs. Whoever holds either form can read
+ * and post in the room — treat an invite like a Telegram join link, not like a URL.
+ */
+/** k (v0.5.0): the E2E room key. It rides in the URL fragment after the secret
+ *  (`#<secret>.<key>`), so like the secret it never reaches any server. */
+export interface Invite { u: string; r: string; s: string; n?: string; p?: string /* relay signing pubkey, vouched by the inviter */; k?: string }
+
+const PREFIX = "parley1.";
+const TOKEN_RE = /parley1.[A-Za-z0-9_-]{16,}/;
+const URL_RE = /https?:\/\/[^\s"'<>]+\/j\/[0-9a-f]{12}[^\s"'<>]*/;
+
+export function encodeInvite(i: Invite): string {
+  return PREFIX + b64url(JSON.stringify(i));
+}
+
+export function encodeInviteUrl(i: Invite): string {
+  const base = i.u.replace(/\/+$/, "");
+  const qs = new URLSearchParams();
+  if (i.n) qs.set("n", i.n);
+  if (i.p) qs.set("p", i.p);
+  const qstr = qs.toString();
+  const q = qstr ? `?${qstr}` : "";
+  return `${base}/j/${i.r}${q}#${i.s}${i.k ? "." + i.k : ""}`;
+}
+
+/** Accepts a token, a URL, or any text that contains one of them (agents paste whole chat lines). */
+export function decodeInvite(s: string): Invite {
+  const t = s.trim();
+  const url = URL_RE.exec(t)?.[0];
+  if (url) return decodeInviteUrl(url);
+  const tok = TOKEN_RE.exec(t)?.[0] ?? (t.startsWith(PREFIX) ? t : undefined);
+  if (!tok) throw new Error("not a can2cup invite (expected a https://…/j/<room>#<secret> link or a parley1.… token)");
+  const i = JSON.parse(unb64url(tok.slice(PREFIX.length))) as Invite;
+  if (!i.u || !i.r || !i.s) throw new Error("malformed invite");
+  return i;
+}
+
+export function decodeInviteUrl(url: string): Invite {
+  const u = new URL(url);
+  const m = /^(.*)\/j\/([0-9a-f]{12})$/.exec(u.pathname);
+  if (!m) throw new Error("malformed invite link (expected /j/<room>)");
+  const [s, k] = u.hash.replace(/^#/, "").split(".");
+  if (!/^[0-9a-f]{16,}$/.test(s)) throw new Error("invite link is missing its secret (the part after #) — copy the whole link");
+  const n = u.searchParams.get("n") ?? undefined;
+  const p = u.searchParams.get("p") ?? undefined;
+  return { u: u.origin + m[1], r: m[2], s, ...(n ? { n } : {}), ...(p && /^[0-9a-f]{64}$/.test(p) ? { p } : {}), ...(k && /^[0-9a-f]{64}$/.test(k) ? { k } : {}) };
+}
+
+function b64url(s: string): string {
+  const bytes = new TextEncoder().encode(s);
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function unb64url(s: string): string {
+  const b = s.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (s.length % 4)) % 4);
+  const bin = atob(b);
+  const bytes = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+  return new TextDecoder().decode(bytes);
+}

package/src/protocol/semver.ts

@@ -0,0 +1,14 @@
+/** v0.9.0 upgrade protocol: the only comparison both relay and client need. "1.2.3" style; unknown → 0.0.0. */
+export function parseSemver(v: string | null | undefined): [number, number, number] {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec((v ?? "").trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : [0, 0, 0];
+}
+
+/** negative when a < b, 0 when equal, positive when a > b. */
+export function cmpSemver(a: string | null | undefined, b: string | null | undefined): number {
+  const x = parseSemver(a), y = parseSemver(b);
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] - y[i];
+  return 0;
+}
+
+export const NO_VERSION = "0.0.0";

package/src/relay/a2a.ts

@@ -0,0 +1,212 @@
+/**
+ * A2A (Agent2Agent, Linux Foundation) conformance layer — v1.0.0 of the spec.
+ *
+ * Why this exists: A2A assumes an agent is an HTTP server at a domain. A can2cup
+ * agent is a Claude Code process on somebody's laptop — no domain, no inbound
+ * port, not always awake. The relay already stands in for that laptop, so it is
+ * also the natural place to host the agent's A2A surface.
+ *
+ * What is conformant here and what deliberately is not:
+ *   - The Agent Card, the JSON-RPC envelope, the error codes and the security
+ *     scheme follow the spec exactly. Do not invent fields.
+ *   - can2cup's own semantics (the principal's outbound mandate, and the ed25519
+ *     per-message signature over a hash-chained transcript) have no home in the
+ *     spec — A2A does per-agent-card JWS but explicitly no per-message signing,
+ *     and expresses no principal->agent authority at all. They are therefore
+ *     declared as A2A extensions, which is the sanctioned way to add meaning
+ *     without forking. Both are `required: false`, so an agent that has never
+ *     heard of can2cup can still talk to us.
+ *   - The room stays can2cup's model. A2A's Task is a delegated unit of work with
+ *     a terminal state; a room is an ongoing multi-party ordered log. We map
+ *     `contextId` to the room id at the boundary and keep RoomDO unchanged.
+ *
+ * INGEST IS CLOSED BY DEFAULT. An inbound A2A message cannot be signed by the
+ * sender's can2cup key (the relay holds no private key, and an external agent has
+ * no can2cup identity), so admitting one means writing a relay-attested envelope
+ * into a transcript whose whole value is that every entry is participant-signed.
+ * That is the same trust downgrade as the LINE `/a` path, which is why it is
+ * marked UNVERIFIED there. Until a room opts in, message/send answers with the
+ * spec's UnsupportedOperation — which is also exactly what a non-opted-in room
+ * will answer once ingest ships, so this endpoint does not lie about itself.
+ */
+import { PROTOCOL_VERSION } from "../protocol/index.js";
+
+export const A2A_PROTOCOL_VERSION = "1.0.0";
+export const A2A_AGENT_VERSION = "0.6.0";
+
+/** JSON-RPC 2.0 plus the A2A-specific range. */
+export const RPC = {
+  parseError: -32700,
+  invalidRequest: -32600,
+  methodNotFound: -32601,
+  invalidParams: -32602,
+  internalError: -32603,
+  taskNotFound: -32001,
+  taskNotCancelable: -32002,
+  pushNotificationNotSupported: -32003,
+  unsupportedOperation: -32004,
+  contentTypeNotSupported: -32005,
+} as const;
+
+/** Extension identifiers are namespaced under the relay's own origin, so they
+ *  are dereferenceable by whoever is actually running this deployment. */
+export const extUri = (origin: string, name: string): string => `${origin}/ext/${name}/v1`;
+
+export interface CardOptions {
+  origin: string;
+  relayPub?: string;
+}
+
+export function agentCard(o: CardOptions): unknown {
+  return {
+    protocolVersion: A2A_PROTOCOL_VERSION,
+    name: "can2cup relay",
+    description:
+      "Hosts the A2A surface for personal agents that have no server of their own. " +
+      "Each can2cup room is an ordered, hash-chained transcript between agents that each answer " +
+      "to a different human principal; this gateway lets an A2A caller reach one.",
+    version: A2A_AGENT_VERSION,
+    url: `${o.origin}/a2a`,
+    preferredTransport: "JSONRPC",
+    provider: { organization: "can2cup", url: o.origin },
+    documentationUrl: `${o.origin}/`,
+
+    defaultInputModes: ["text/plain", "application/json"],
+    defaultOutputModes: ["text/plain", "application/json"],
+
+    capabilities: {
+      // Truthful, not aspirational. Flip these in the same commit that implements them.
+      streaming: false,
+      pushNotifications: false,
+      stateTransitionHistory: false,
+      extensions: [
+        {
+          uri: extUri(o.origin, "principal-mandate"),
+          description:
+            "Outbound messages are gated on the sending agent's machine by a mandate its human principal " +
+            "wrote: disclosure limits, a commitment ceiling, and what authority it may delegate. A blocked " +
+            "message is never sent, and the agent reports task state input-required rather than failed. " +
+            "A2A expresses no principal-to-agent authority, so this is carried out of band and declared here.",
+          required: false,
+        },
+        {
+          uri: extUri(o.origin, "signed-transcript"),
+          description:
+            "Every participant message carries an ed25519 signature over a canonical envelope whose prev field " +
+            "is the hash of the previous entry, so the room is a hash chain. The relay additionally signs a " +
+            "transcript head (seq, hash, time) on every read, which lets a client that pinned the relay key " +
+            "prove a fork or a truncated tail after the fact. A2A signs the agent card (JWS) but specifies " +
+            "no per-message signing; callers that do not implement this extension are stored relay-attested " +
+            "and shown to participants as UNVERIFIED.",
+          required: false,
+        },
+      ],
+    },
+
+    securitySchemes: {
+      participantCap: {
+        type: "http",
+        scheme: "bearer",
+        description:
+          "A participant capability for one room, issued by POST /rooms/:id/join to the key that signed the " +
+          "join. The invite secret is a join-and-read key and is not accepted here.",
+      },
+    },
+    security: [{ participantCap: [] }],
+
+    skills: [
+      {
+        id: "room-message",
+        name: "Send a message into a can2cup room",
+        description:
+          "Deliver a message to the participants of one room. contextId must be the room's 12-hex id and the " +
+          "bearer token must be a participant capability for that room. Ingest is opt-in per room: a room that " +
+          "has not enabled it answers -32004 UnsupportedOperation.",
+        tags: ["messaging", "relay", "room", "agent-to-agent"],
+        examples: ["Send a review request into room 77ff7ca1be69"],
+        inputModes: ["text/plain"],
+        outputModes: ["text/plain"],
+      },
+      {
+        id: "room-transcript",
+        name: "Read a room transcript",
+        description:
+          "Return a room's ordered, hash-chained transcript from a given sequence number, together with the " +
+          "relay-signed head. Available today over the native REST surface at GET /rooms/:id/messages.",
+        tags: ["history", "audit", "hash-chain"],
+        inputModes: ["application/json"],
+        outputModes: ["application/json"],
+      },
+    ],
+
+    // Informational: how to reach the native surface this gateway fronts.
+    additionalInterfaces: [{ transport: "HTTP+JSON", url: `${o.origin}/rooms` }],
+  };
+}
+
+interface RpcReq { jsonrpc?: string; id?: unknown; method?: unknown; params?: unknown }
+
+const err = (id: unknown, code: number, message: string, data?: unknown): Response =>
+  Response.json({ jsonrpc: "2.0", id: id ?? null, error: { code, message, ...(data ? { data } : {}) } });
+
+/**
+ * JSON-RPC entry point. Every method the card claims is routed here; the ones we
+ * have not built answer with the spec's own codes rather than a 404, so a caller
+ * gets a machine-readable reason instead of a broken endpoint.
+ */
+export async function handleA2A(req: Request, origin: string): Promise<Response> {
+  if (req.method !== "POST") return err(null, RPC.invalidRequest, "A2A JSON-RPC requires POST");
+
+  let body: RpcReq;
+  try {
+    body = (await req.json()) as RpcReq;
+  } catch {
+    return err(null, RPC.parseError, "invalid JSON");
+  }
+
+  const id = body.id ?? null;
+  if (body.jsonrpc !== "2.0" || typeof body.method !== "string") {
+    return err(id, RPC.invalidRequest, 'jsonrpc must be "2.0" and method must be a string');
+  }
+
+  const auth = req.headers.get("authorization") ?? "";
+  const token = auth.startsWith("Bearer ") ? auth.slice(7) : "";
+
+  switch (body.method) {
+    case "message/send":
+    case "message/stream": {
+      if (!token) {
+        return err(id, RPC.invalidRequest, "a participant capability is required (Authorization: Bearer <cap>)");
+      }
+      const p = body.params as { message?: { contextId?: string } } | undefined;
+      const room = p?.message?.contextId ?? "";
+      if (!/^[0-9a-f]{12}$/.test(room)) {
+        return err(id, RPC.invalidParams, "message.contextId must be a 12-hex can2cup room id");
+      }
+      return err(id, RPC.unsupportedOperation, `room ${room} has not enabled A2A ingest`, {
+        reason: "ingest-not-enabled",
+        detail:
+          "A can2cup transcript is participant-signed end to end. An inbound A2A message cannot carry that " +
+          "signature, so admitting it writes a relay-attested entry that participants see as UNVERIFIED. " +
+          "The room's creator must opt in before this is allowed.",
+        extension: extUri(origin, "signed-transcript"),
+      });
+    }
+
+    case "tasks/get":
+      return err(id, RPC.taskNotFound, "no tasks exist: this gateway does not yet create A2A tasks");
+
+    case "tasks/pushNotificationConfig/set":
+    case "tasks/pushNotificationConfig/get":
+      return err(id, RPC.pushNotificationNotSupported, "push notifications are not implemented on this gateway");
+
+    case "agent/getAuthenticatedExtendedCard":
+      return Response.json({ jsonrpc: "2.0", id, result: agentCard({ origin }) });
+
+    default:
+      return err(id, RPC.methodNotFound, `unknown method: ${body.method}`);
+  }
+}
+
+/** Compile-time tie to the can2cup protocol version this gateway fronts. */
+export const PARLEY_PROTOCOL = PROTOCOL_VERSION;