diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..4a9d1ba --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,30 @@ +# Changelog + +Newest first. Each release also has fuller notes in `docs/vX.Y.Z.md`. + +## 0.13.0 + +Agents can use a person's Copper for iOS through the cloud ([notes](docs/v0.13.0.md)). One new +migration (`0016_device_agent`); upgrading from 0.12.x is a binary swap. + +- **Device agent relay** (`/v1/info` feature `device_agent`, [api.md](docs/api.md#device-agent-relay)): + - device side (gate + session): `POST`/`GET /v1/me/links`, `GET`/`DELETE /v1/me/links/{id}`, + the SSE mailbox `GET /v1/me/links/{id}/frames` and its upload + `POST /v1/me/links/{id}/frames` (body up to 32 MiB), agent tokens + `POST`/`GET /v1/me/agent-tokens` and `DELETE /v1/me/agent-tokens/{id}`; + - agent side (no gate header, `Authorization: Bearer cat_…`): `GET /v1/agent/status` and + `POST /v1/agent/mcp` — MCP Streamable HTTP (stateless) with JSON or SSE answers, 10 s + keepalive comments, progress notifications, `cancel` to the device on a 200 s deadline or + when the agent goes away, and an immediate answer when Copper is not open; 600 + requests/minute per token. +- Deleting a device (`DELETE /v1/devices/{id}`, admin API too) turns off its link and agent + tokens. +- New metrics: `device_agent_streams`, `device_agent_calls_total{status}`, + `agent_rate_limited_total`; one `agent call` log line per call, never arguments or results. + +## 0.12.0 and earlier + +See [v0.12.0](docs/v0.12.0.md) · [v0.11.1](docs/v0.11.1.md) · [v0.11.0](docs/v0.11.0.md) · +[v0.10.0](docs/v0.10.0.md) · [v0.9.0](docs/v0.9.0.md) · [v0.8.1](docs/v0.8.1.md) · +[v0.8.0](docs/v0.8.0.md) · [v0.7.0](docs/v0.7.0.md) · [v0.6.0](docs/v0.6.0.md) · +[v0.5.0](docs/v0.5.0.md) · [v0.4.0](docs/v0.4.0.md) · [v0.3.0](docs/v0.3.0.md). diff --git a/Cargo.lock b/Cargo.lock index 3e1c5c5..0814a32 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -638,7 +638,7 @@ checksum = "a6ef517f0926dd24a1582492c791b6a4818a4d94e789a334894aa15b0d12f55c" [[package]] name = "copper-cloud" -version = "0.12.0" +version = "0.13.0" dependencies = [ "anyhow", "axum", @@ -661,6 +661,7 @@ dependencies = [ "tokio-rustls", "tokio-tungstenite", "tracing", + "tracing-subscriber", "url", "uuid", "zeroize", @@ -669,7 +670,7 @@ dependencies = [ [[package]] name = "copper-cloud-canvas-link" -version = "0.12.0" +version = "0.13.0" dependencies = [ "anyhow", "axum", @@ -698,7 +699,7 @@ dependencies = [ [[package]] name = "copper-cloud-canvas-migrate" -version = "0.12.0" +version = "0.13.0" dependencies = [ "anyhow", "axum", @@ -722,7 +723,7 @@ dependencies = [ [[package]] name = "copper-cloud-core" -version = "0.12.0" +version = "0.13.0" dependencies = [ "aes-gcm", "anyhow", diff --git a/Cargo.toml b/Cargo.toml index ea856cd..045e156 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -8,7 +8,7 @@ members = [ ] [workspace.package] -version = "0.12.0" +version = "0.13.0" edition = "2021" license = "MIT" repository = "https://github.com/copper-browser/copper-cloud" diff --git a/README.md b/README.md index faf7690..93eff21 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,9 @@ People can join with **company single sign-on** (Google Workspace or any OpenID provider): share one `https://HOST/start` page, they install Copper and click *Continue with Google* — no account to create, no password ([docs/sso.md](docs/sso.md)). **Agent integrations** let a trusted service pair headless Coppers (e.g. one per bot) to its owners' -accounts ([docs/sso.md](docs/sso.md#agent-integrations)). +accounts ([docs/sso.md](docs/sso.md#agent-integrations)). The **device agent relay** lets an +agent (any MCP client) use a person's Copper for iOS while it is open on their screen, through +`/v1/agent/mcp` with a token the phone mints ([docs/api.md](docs/api.md#device-agent-relay)). ## Install on a VM (Ubuntu 22.04/24.04, Debian 12, Amazon Linux 2023, Fedora) @@ -33,7 +35,7 @@ curl -fsSL https://raw.githubusercontent.com/copper-browser/copper-cloud/main/in or from a release tarball: ```sh -tar xzf copper-cloud-0.12.0-linux-x86_64.tar.gz && sudo ./install.sh +tar xzf copper-cloud-0.13.0-linux-x86_64.tar.gz && sudo ./install.sh ``` The installer sets up Postgres (unless you pass `DATABASE_URL`), a `copper-cloud` system user, @@ -133,6 +135,7 @@ All commands take `--config PATH` (default `/etc/copper-cloud/copper-cloud.toml` - [Architecture](docs/architecture.md) — components, data model, request path - [HTTP API](docs/api.md) — every endpoint with requests and responses +- [Changelog](CHANGELOG.md) — what changed in each release - [Admin API](docs/admin-api.md) — the admin portal's `/admin/api/*` contract - [Addons](docs/addons.md) — slot addons: manifest, bundles, who gets what, API, CLI, security - [Canvas link](docs/canvas-link.md) — how canvases are served by a linked Canvas Cloud: @@ -147,7 +150,7 @@ All commands take `--config PATH` (default `/etc/copper-cloud/copper-cloud.toml` - [Operations](docs/operations.md) — doctor, logs, metrics, backups, upgrades - [Onboarding a team](docs/onboarding.md) — single sign-on first, link codes, people, keeping links valid - [Single sign-on + agent integrations](docs/sso.md) — Google / OIDC setup, `/start`, agent pairing -- [v0.12.0 release notes](docs/v0.12.0.md) · [v0.11.1](docs/v0.11.1.md) · [v0.11.0](docs/v0.11.0.md) · [v0.10.0](docs/v0.10.0.md) · [v0.9.0](docs/v0.9.0.md) · [v0.8.1](docs/v0.8.1.md) · [v0.8.0](docs/v0.8.0.md) · [v0.7.0](docs/v0.7.0.md) · [v0.6.0](docs/v0.6.0.md) · [v0.5.0](docs/v0.5.0.md) · [v0.4.0](docs/v0.4.0.md) · [v0.3.0](docs/v0.3.0.md) +- [v0.13.0 release notes](docs/v0.13.0.md) · [v0.12.0](docs/v0.12.0.md) · [v0.11.1](docs/v0.11.1.md) · [v0.11.0](docs/v0.11.0.md) · [v0.10.0](docs/v0.10.0.md) · [v0.9.0](docs/v0.9.0.md) · [v0.8.1](docs/v0.8.1.md) · [v0.8.0](docs/v0.8.0.md) · [v0.7.0](docs/v0.7.0.md) · [v0.6.0](docs/v0.6.0.md) · [v0.5.0](docs/v0.5.0.md) · [v0.4.0](docs/v0.4.0.md) · [v0.3.0](docs/v0.3.0.md) ## Development diff --git a/crates/copper-cloud/Cargo.toml b/crates/copper-cloud/Cargo.toml index 8a3ad0d..632cea7 100644 --- a/crates/copper-cloud/Cargo.toml +++ b/crates/copper-cloud/Cargo.toml @@ -54,5 +54,6 @@ reqwest.workspace = true tokio-tungstenite.workspace = true serde_json.workspace = true tokio.workspace = true +tracing-subscriber.workspace = true uuid.workspace = true zip.workspace = true diff --git a/crates/copper-cloud/migrations/0016_device_agent.sql b/crates/copper-cloud/migrations/0016_device_agent.sql new file mode 100644 index 0000000..433fa43 --- /dev/null +++ b/crates/copper-cloud/migrations/0016_device_agent.sql @@ -0,0 +1,40 @@ +-- Device agent relay (copper-cloud 0.13.0; see docs/api.md "Device agent relay"). +-- +-- An agent (any MCP client) calls the tools of a person's Copper for iOS through the cloud: the +-- phone registers a link with its tool manifest and holds an SSE mailbox open while Copper is +-- on screen; the agent presents a `cat_…` token the phone minted. Which link is online and the +-- calls in flight live in memory (one daemon per instance), never here. + +-- One link per (user, device). `tools` is the manifest the device last registered (a JSON +-- array, ≤ 100 entries, ≤ 256 KiB), served to agents by `tools/list` even while the phone is +-- closed. Revoking (or deleting the device) sets `revoked_at`; registering again clears it and +-- keeps the id. No foreign key to `devices`, so a revoked link outlives its device row. +CREATE TABLE device_links ( + id uuid PRIMARY KEY, + user_id uuid NOT NULL REFERENCES users (id) ON DELETE CASCADE, + device_id uuid NOT NULL, + label text NOT NULL CHECK (length(label) BETWEEN 1 AND 200), + client_version text CHECK (client_version IS NULL OR length(client_version) <= 64), + tools jsonb NOT NULL DEFAULT '[]'::jsonb CHECK (jsonb_typeof(tools) = 'array'), + created_at timestamptz NOT NULL DEFAULT now(), + last_seen_at timestamptz, + revoked_at timestamptz, + UNIQUE (user_id, device_id) +); + +-- Agent tokens: `cat_` + 32 random bytes base64url, minted by a device for one agent and bound +-- to that user and device. Only SHA-256(token) is stored; the token is shown once. Deleting the +-- device revokes them. +CREATE TABLE agent_tokens ( + id uuid PRIMARY KEY, + user_id uuid NOT NULL REFERENCES users (id) ON DELETE CASCADE, + device_id uuid NOT NULL, + label text NOT NULL CHECK (length(label) BETWEEN 1 AND 100), + token_sha256 bytea NOT NULL UNIQUE CHECK (length(token_sha256) = 32), + created_at timestamptz NOT NULL DEFAULT now(), + last_used_at timestamptz, + revoked_at timestamptz +); + +CREATE INDEX agent_tokens_user_idx ON agent_tokens (user_id, created_at DESC); +CREATE INDEX agent_tokens_device_idx ON agent_tokens (user_id, device_id) WHERE revoked_at IS NULL; diff --git a/crates/copper-cloud/src/admin_api.rs b/crates/copper-cloud/src/admin_api.rs index f299ebe..d5c3e32 100644 --- a/crates/copper-cloud/src/admin_api.rs +++ b/crates/copper-cloud/src/admin_api.rs @@ -1174,11 +1174,17 @@ async fn delete_device( .execute(&mut *tx) .await?; } - let detail = if let [user] = users.as_slice() { + // Its device-agent link and agent tokens are turned off with it. + let agent = copper_cloud_core::device_agent::revoke_device(&mut tx, &users, id).await?; + let mut detail = if let [user] = users.as_slice() { json!({ "user_id": user }) } else { json!({ "user_ids": users }) }; + if !agent.is_empty() { + detail["revoked_agent_links"] = json!(agent.links.len()); + detail["revoked_agent_tokens"] = json!(agent.tokens.len()); + } audit( &mut *tx, s.admin_id, @@ -1188,6 +1194,7 @@ async fn delete_device( ) .await?; tx.commit().await?; + agent.apply(&state.device_agent); Ok(Json(json!({ "ok": true, "deleted": users.len() }))) } diff --git a/crates/copper-cloud/tests/device_agent.rs b/crates/copper-cloud/tests/device_agent.rs new file mode 100644 index 0000000..d6d6018 --- /dev/null +++ b/crates/copper-cloud/tests/device_agent.rs @@ -0,0 +1,1604 @@ +//! Device agent relay (`device_agent`, 0.13.0): links, the frames mailbox, agent tokens, +//! `/v1/agent/*` outside the gate, and MCP calls relayed to a simulated device (an SSE reader +//! for `request` / `cancel` frames plus frames POSTs for replies and progress). + +#![allow(clippy::too_many_lines)] + +mod common; + +use std::pin::Pin; +use std::time::{Duration, Instant}; + +use common::{new_device, session_from, start_with, Session, TestServer, PASSWORD}; +use futures::{Stream, StreamExt as _}; +use reqwest::Method; +use serde_json::{json, Value}; + +const DEVICE_NAME: &str = "Ada's iPhone"; +const SSE_ACCEPT: &str = "application/json, text/event-stream"; + +/// Short relay timings so deadlines, keepalives and offline devices take about a second. +fn tune(cfg: &mut copper_cloud_core::config::Config) { + cfg.limits.auth_per_minute = 1000; + let t = &mut cfg.device_agent; + t.relay_deadline = Duration::from_millis(1500); + t.agent_keepalive = Duration::from_millis(200); + t.device_ping = Duration::from_millis(400); + t.offline_grace = Duration::from_millis(500); +} + +async fn start() -> TestServer { + start_with(tune).await +} + +async fn json_of(r: reqwest::Response) -> Value { + let status = r.status(); + let text = r.text().await.unwrap(); + serde_json::from_str(&text).unwrap_or_else(|_| panic!("{status}: {text}")) +} + +async fn expect_error(r: reqwest::Response, status: u16, code: &str) -> Value { + assert_eq!(r.status(), status); + let body = json_of(r).await; + assert_eq!(body["error"], code, "{body}"); + body +} + +// --------------------------------------------------------------------------------------------- +// A minimal SSE reader + +type Chunks = Pin>> + Send>>; + +struct SseReader { + chunks: Chunks, + buf: Vec, + /// `:` comment lines seen so far (keepalives). + comments: usize, +} + +#[derive(Debug)] +struct Ev { + name: String, + data: String, +} + +impl Ev { + fn json(&self) -> Value { + serde_json::from_str(&self.data).unwrap_or_else(|_| panic!("not JSON: {}", self.data)) + } +} + +impl SseReader { + fn new(r: reqwest::Response) -> Self { + Self { + chunks: Box::pin(r.bytes_stream().map(|c| c.map(|b| b.to_vec()))), + buf: Vec::new(), + comments: 0, + } + } + + /// The next event (comments are counted and skipped); `None` once the stream ended. + async fn next(&mut self) -> Option { + tokio::time::timeout(Duration::from_secs(10), self.read()) + .await + .expect("timed out waiting for an SSE event") + } + + /// Like [`Self::next`], but `Err` if nothing arrives within `wait`. + async fn next_within(&mut self, wait: Duration) -> Result, ()> { + tokio::time::timeout(wait, self.read()) + .await + .map_err(|_| ()) + } + + /// The next event that is not a `ping`. + async fn next_event(&mut self) -> Option { + loop { + let ev = self.next().await?; + if ev.name != "ping" { + return Some(ev); + } + } + } + + async fn read(&mut self) -> Option { + loop { + if let Some(pos) = self.buf.windows(2).position(|w| w == b"\n\n") { + let block: Vec = self.buf.drain(..pos + 2).collect(); + let text = String::from_utf8(block).unwrap(); + let (mut name, mut data, mut comment) = (String::new(), Vec::new(), false); + for line in text.lines() { + if line.starts_with(':') { + comment = true; + } else if let Some(v) = line.strip_prefix("event:") { + v.trim_start().clone_into(&mut name); + } else if let Some(v) = line.strip_prefix("data:") { + data.push(v.strip_prefix(' ').unwrap_or(v).to_owned()); + } + } + if name.is_empty() && data.is_empty() { + if comment { + self.comments += 1; + } + continue; + } + return Some(Ev { + name, + data: data.join("\n"), + }); + } + match self.chunks.next().await { + Some(Ok(chunk)) => self.buf.extend_from_slice(&chunk), + Some(Err(_)) | None => return None, + } + } + } +} + +fn assert_sse_headers(r: &reqwest::Response) { + let h = r.headers(); + assert!( + h["content-type"] + .to_str() + .unwrap() + .starts_with("text/event-stream"), + "{h:?}" + ); + assert_eq!(h["cache-control"], "no-store"); + assert_eq!(h["x-accel-buffering"], "no"); +} + +// --------------------------------------------------------------------------------------------- +// Device side helpers + +/// A signed-up account whose device is named [`DEVICE_NAME`] (the phone). +async fn phone(s: &TestServer, email: &str) -> Session { + let p = s.signup(email, PASSWORD, &new_device()).await; + let r = s + .authed(Method::PATCH, &format!("/v1/devices/{}", p.device_id), &p) + .json(&json!({ "name": DEVICE_NAME })) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 200); + p +} + +/// Another device of the same account (`Other Mac`). +async fn second_device(s: &TestServer, email: &str) -> Session { + let r = s.login(email, PASSWORD, &new_device()).await; + assert_eq!(r.status(), 200); + session_from(&r.json().await.unwrap()) +} + +fn tool(name: &str) -> Value { + json!({ + "name": name, + "description": format!("{name} on the phone"), + "inputSchema": { "type": "object", "properties": { "goal": { "type": "string" } } }, + }) +} + +fn manifest() -> Value { + json!([ + tool("jev_run"), + tool("jev_observe"), + tool("browser_snapshot") + ]) +} + +async fn register(s: &TestServer, p: &Session, body: Value) -> reqwest::Response { + s.authed(Method::POST, "/v1/me/links", p) + .json(&body) + .send() + .await + .unwrap() +} + +/// Register the phone's link with [`manifest`]; returns the link object. +async fn register_ok(s: &TestServer, p: &Session) -> Value { + let r = register( + s, + p, + json!({ "label": DEVICE_NAME, "client_version": "ios-1.0.0", "tools": manifest() }), + ) + .await; + assert_eq!(r.status(), 200); + json_of(r).await +} + +async fn get_link(s: &TestServer, p: &Session, id: &str) -> Value { + let r = s + .authed(Method::GET, &format!("/v1/me/links/{id}"), p) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 200); + json_of(r).await +} + +async fn list_links(s: &TestServer, p: &Session) -> Vec { + let r = s + .authed(Method::GET, "/v1/me/links", p) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 200); + json_of(r).await.as_array().unwrap().clone() +} + +/// `POST /v1/me/agent-tokens`; returns the minted token object. +async fn mint(s: &TestServer, p: &Session, label: &str) -> Value { + let r = s + .authed(Method::POST, "/v1/me/agent-tokens", p) + .json(&json!({ "label": label })) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 201); + json_of(r).await +} + +fn token_of(minted: &Value) -> String { + minted["token"].as_str().unwrap().to_owned() +} + +/// Open the frames stream (asserting the SSE headers). +async fn frames(s: &TestServer, p: &Session, link: &str) -> SseReader { + let r = s + .authed(Method::GET, &format!("/v1/me/links/{link}/frames"), p) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 200); + assert_sse_headers(&r); + SseReader::new(r) +} + +/// Open the frames stream and read `hello`; returns the reader and the hello data. +async fn connect(s: &TestServer, p: &Session, link: &str) -> (SseReader, Value) { + let mut dev = frames(s, p, link).await; + let hello = dev.next().await.expect("hello"); + assert_eq!(hello.name, "hello"); + let data = hello.json(); + (dev, data) +} + +async fn post_frames(s: &TestServer, p: &Session, link: &str, frames: Value) -> Value { + let r = s + .authed(Method::POST, &format!("/v1/me/links/{link}/frames"), p) + .json(&json!({ "frames": frames })) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 200); + let body = json_of(r).await; + assert_eq!(body["ok"], true); + body +} + +/// Read the next `request` frame on the device's stream. +async fn next_request(dev: &mut SseReader) -> Value { + let ev = dev.next_event().await.expect("request frame"); + assert_eq!(ev.name, "request", "{ev:?}"); + ev.json() +} + +// --------------------------------------------------------------------------------------------- +// Agent side helpers + +/// A request to `/v1/agent/*` with the token and **no** gate header. +fn agent(s: &TestServer, method: Method, path: &str, token: &str) -> reqwest::RequestBuilder { + s.http.request(method, s.url(path)).bearer_auth(token) +} + +/// `POST /v1/agent/mcp`, JSON answer; returns the JSON-RPC response. +async fn rpc(s: &TestServer, token: &str, body: Value) -> Value { + let r = agent(s, Method::POST, "/v1/agent/mcp", token) + .json(&body) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 200); + assert!(r.headers()["content-type"] + .to_str() + .unwrap() + .starts_with("application/json")); + json_of(r).await +} + +#[allow(clippy::needless_pass_by_value)] +fn call(id: i64, tool: &str, arguments: Value) -> Value { + json!({ + "jsonrpc": "2.0", "id": id, "method": "tools/call", + "params": { "name": tool, "arguments": arguments }, + }) +} + +/// A JSON-mode `tools/call` running in the background (its own client and connection). +fn spawn_call(s: &TestServer, token: &str, body: Value) -> tokio::task::JoinHandle { + let url = s.url("/v1/agent/mcp"); + let token = token.to_owned(); + tokio::spawn(async move { + let r = reqwest::Client::new() + .post(url) + .bearer_auth(token) + .json(&body) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 200); + r.json::().await.unwrap() + }) +} + +/// An SSE-mode `tools/call`: returns once the headers are in. +async fn sse_call(s: &TestServer, token: &str, body: Value) -> SseReader { + let r = reqwest::Client::new() + .post(s.url("/v1/agent/mcp")) + .bearer_auth(token) + .header("Accept", SSE_ACCEPT) + .json(&body) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 200); + assert_sse_headers(&r); + SseReader::new(r) +} + +async fn status(s: &TestServer, token: &str) -> Value { + let r = agent(s, Method::GET, "/v1/agent/status", token) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 200); + json_of(r).await +} + +fn text_of(result: &Value) -> String { + result["content"][0]["text"] + .as_str() + .unwrap_or_else(|| panic!("no text block: {result}")) + .to_owned() +} + +/// Poll `cond` for up to 5 s. +async fn eventually(what: &str, mut cond: F) +where + F: FnMut() -> Fut, + Fut: std::future::Future, +{ + let until = Instant::now() + Duration::from_secs(5); + while !cond().await { + assert!(Instant::now() < until, "timed out: {what}"); + tokio::time::sleep(Duration::from_millis(50)).await; + } +} + +// --------------------------------------------------------------------------------------------- +// Links + +#[tokio::test] +async fn links_register_upsert_revoke_and_reregister() { + let s = start().await; + let p = phone(&s, "ada@example.com").await; + let link = register_ok(&s, &p).await; + let id = link["id"].as_str().unwrap().to_owned(); + assert_eq!(link["device_id"], p.device_id.as_str()); + assert_eq!(link["device_name"], DEVICE_NAME); + assert_eq!(link["label"], DEVICE_NAME); + assert_eq!(link["online"], false); + assert_eq!(link["revoked"], false); + assert_eq!(link["tools"], 3); + assert!(link["last_seen_at"].is_null()); + assert!(link["created_at"].is_string()); + + // Idempotent per device: same id; omitted fields keep their stored value. + let again = json_of( + register( + &s, + &p, + json!({ "label": "Ada's phone", "tools": [tool("jev_run")] }), + ) + .await, + ) + .await; + assert_eq!(again["id"], id.as_str()); + assert_eq!(again["label"], "Ada's phone"); + assert_eq!(again["tools"], 1); + let kept = json_of(register(&s, &p, json!({})).await).await; + assert_eq!(kept["id"], id.as_str()); + assert_eq!(kept["label"], "Ada's phone"); + assert_eq!(kept["tools"], 1); + register_ok(&s, &p).await; + + let listed = list_links(&s, &p).await; + assert_eq!(listed.len(), 1); + assert_eq!(listed[0]["id"], id.as_str()); + assert_eq!(get_link(&s, &p, &id).await["tools"], 3); + + // Another user's link: 404; their list is their own. + let bob = phone(&s, "bob@example.com").await; + for m in [Method::GET, Method::DELETE] { + let r = s + .authed(m, &format!("/v1/me/links/{id}"), &bob) + .send() + .await + .unwrap(); + expect_error(r, 404, "not_found").await; + } + assert_eq!(list_links(&s, &bob).await.len(), 0); + + // A link from a second device: its own id, label defaults to the device name. + let mac = second_device(&s, "ada@example.com").await; + let mac_link = json_of(register(&s, &mac, json!({})).await).await; + assert_ne!(mac_link["id"], id.as_str()); + assert_eq!(mac_link["label"], "Other Mac"); + assert_eq!(mac_link["tools"], 0); + assert_eq!(list_links(&s, &p).await.len(), 2); + + // Revoke (from any device of the user): gone from the list, still readable, idempotent. + let r = s + .authed(Method::DELETE, &format!("/v1/me/links/{id}"), &mac) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 200); + assert_eq!(json_of(r).await, json!({ "ok": true })); + let listed = list_links(&s, &p).await; + assert_eq!(listed.len(), 1); + assert_eq!(listed[0]["id"], mac_link["id"]); + let revoked = get_link(&s, &p, &id).await; + assert_eq!(revoked["revoked"], true); + assert_eq!(revoked["online"], false); + let r = s + .authed(Method::DELETE, &format!("/v1/me/links/{id}"), &p) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 200); + + // Registering again brings the same link back. + let back = register_ok(&s, &p).await; + assert_eq!(back["id"], id.as_str()); + assert_eq!(back["revoked"], false); + assert_eq!(list_links(&s, &p).await.len(), 2); + + // Bad manifests: 400, and the stored one is untouched. + let many: Vec = (0..101).map(|i| tool(&format!("t{i}"))).collect(); + for bad in [ + json!({ "tools": { "name": "jev_run" } }), + json!({ "tools": ["jev_run"] }), + json!({ "tools": [{ "description": "no name" }] }), + json!({ "tools": [tool("jev_run"), tool("jev_run")] }), + json!({ "tools": many }), + json!({ "tools": [{ "name": "big", "description": "x".repeat(300 * 1024) }] }), + ] { + expect_error(register(&s, &p, bad).await, 400, "bad_request").await; + } + assert_eq!(get_link(&s, &p, &id).await["tools"], 3); + // Small routes keep small body caps (only the frames upload takes 32 MiB). + let r = s + .authed(Method::POST, "/v1/me/agent-tokens", &p) + .json(&json!({ "label": "x".repeat(20 * 1024) })) + .send() + .await + .unwrap(); + expect_error(r, 413, "payload_too_large").await; + + // Gate + session like every user route. + let r = s + .http + .get(s.url("/v1/me/links")) + .bearer_auth(&p.token) + .send() + .await + .unwrap(); + expect_error(r, 401, "instance_key").await; + let r = s.req(Method::GET, "/v1/me/links").send().await.unwrap(); + expect_error(r, 401, "session").await; +} + +#[tokio::test] +async fn frames_owner_only_hello_ping_and_superseded() { + let s = start().await; + let p = phone(&s, "ada@example.com").await; + let id = register_ok(&s, &p).await["id"].as_str().unwrap().to_owned(); + let path = format!("/v1/me/links/{id}/frames"); + + // Only the link's own device: 403 for the user's other device, 404 for another user. + let mac = second_device(&s, "ada@example.com").await; + let r = s.authed(Method::GET, &path, &mac).send().await.unwrap(); + expect_error(r, 403, "forbidden").await; + let r = s + .authed(Method::POST, &path, &mac) + .json(&json!({ "frames": [{ "type": "heartbeat" }] })) + .send() + .await + .unwrap(); + expect_error(r, 403, "forbidden").await; + let bob = phone(&s, "bob@example.com").await; + let r = s.authed(Method::GET, &path, &bob).send().await.unwrap(); + expect_error(r, 404, "not_found").await; + + // `hello` first, with the link and the protocol. + let (mut first, hello) = connect(&s, &p, &id).await; + assert_eq!(hello["protocol"], 1); + assert_eq!(hello["link"]["id"], id.as_str()); + assert_eq!(hello["link"]["online"], true); + assert_eq!(hello["link"]["revoked"], false); + assert_eq!(hello["link"]["tools"], 3); + let link = get_link(&s, &p, &id).await; + assert_eq!(link["online"], true); + assert!(link["last_seen_at"].is_string()); + let ping = first.next().await.unwrap(); + assert_eq!((ping.name.as_str(), ping.data.as_str()), ("ping", "{}")); + + // A new stream supersedes the old one, which closes. + let (mut second, _) = connect(&s, &p, &id).await; + let ev = first.next_event().await.unwrap(); + assert_eq!((ev.name.as_str(), ev.data.as_str()), ("superseded", "{}")); + assert!(first.next().await.is_none(), "superseded stream must end"); + assert_eq!(get_link(&s, &p, &id).await["online"], true); + assert_eq!(second.next().await.unwrap().name, "ping"); + + // Closing the current stream takes the link offline. + drop(second); + eventually("link offline after its stream closed", || { + let (s, p, id) = (&s, &p, &id); + async move { get_link(s, p, id).await["online"] == false } + }) + .await; + + // Uploads: bad bodies are 400. + for bad in ["{}", "[]", "{\"frames\": {}}", "nope"] { + let r = s + .authed(Method::POST, &path, &p) + .body(bad) + .send() + .await + .unwrap(); + expect_error(r, 400, "bad_request").await; + } +} + +// --------------------------------------------------------------------------------------------- +// Agent tokens and the gate + +#[tokio::test] +async fn agent_tokens_mint_list_revoke() { + let s = start().await; + let p = phone(&s, "ada@example.com").await; + let minted = mint(&s, &p, "phi").await; + let token = token_of(&minted); + let token_id = minted["id"].as_str().unwrap().to_owned(); + assert!( + token.starts_with("cat_") && token.len() == 4 + 43, + "{token}" + ); + assert_eq!(minted["label"], "phi"); + assert_eq!(minted["device_id"], p.device_id.as_str()); + assert!(minted["created_at"].is_string()); + assert_eq!(minted["mcp_url"], "https://localhost:8443/v1/agent/mcp"); + + // No body: label "Agent". + let r = s + .authed(Method::POST, "/v1/me/agent-tokens", &p) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 201); + let other = json_of(r).await; + assert_eq!(other["label"], "Agent"); + + // The list: newest first, never the token. + let r = s + .authed(Method::GET, "/v1/me/agent-tokens", &p) + .send() + .await + .unwrap(); + let list = json_of(r).await; + let list = list.as_array().unwrap(); + assert_eq!(list.len(), 2); + assert_eq!(list[0]["id"], other["id"]); + assert_eq!(list[1]["id"], token_id.as_str()); + assert!(list.iter().all(|t| t.get("token").is_none())); + assert!(list[1]["last_used_at"].is_null()); + assert_eq!(list[1]["device_id"], p.device_id.as_str()); + + // The token works without the gate header and names its device. + let st = status(&s, &token).await; + assert_eq!(st["device"]["id"], p.device_id.as_str()); + assert_eq!(st["device"]["name"], DEVICE_NAME); + assert_eq!(st["online"], false); + assert!(st["label"].is_null(), "never registered: {st}"); + assert_eq!(st["tools"], 0); + assert!(st["last_seen_at"].is_null()); + let r = s + .authed(Method::GET, "/v1/me/agent-tokens", &p) + .send() + .await + .unwrap(); + let list = json_of(r).await; + assert!(list[1]["last_used_at"].is_string(), "{list}"); + + // Missing, malformed, unknown, or other credentials: 401 agent_token. + let unknown = format!("cat_{}", copper_cloud_core::ids::random_token()); + for bad in [ + None, + Some("cat_short"), + Some(unknown.as_str()), + Some(p.token.as_str()), + Some(s.key()), + ] { + let mut rb = s.http.get(s.url("/v1/agent/status")); + if let Some(t) = bad { + rb = rb.bearer_auth(t); + } + let r = rb.send().await.unwrap(); + assert!(r.headers().contains_key("www-authenticate")); + expect_error(r, 401, "agent_token").await; + } + + // Another user cannot revoke it. + let bob = phone(&s, "bob@example.com").await; + let path = format!("/v1/me/agent-tokens/{token_id}"); + let r = s.authed(Method::DELETE, &path, &bob).send().await.unwrap(); + expect_error(r, 404, "not_found").await; + status(&s, &token).await; + + // Revoked: 401 at once (status and MCP), idempotent, gone from the list. + let r = s.authed(Method::DELETE, &path, &p).send().await.unwrap(); + assert_eq!(r.status(), 200); + assert_eq!(json_of(r).await, json!({ "ok": true })); + let r = agent(&s, Method::GET, "/v1/agent/status", &token) + .send() + .await + .unwrap(); + expect_error(r, 401, "agent_token").await; + let r = agent(&s, Method::POST, "/v1/agent/mcp", &token) + .json(&json!({ "jsonrpc": "2.0", "id": 1, "method": "ping" })) + .send() + .await + .unwrap(); + expect_error(r, 401, "agent_token").await; + let r = s.authed(Method::DELETE, &path, &p).send().await.unwrap(); + assert_eq!(r.status(), 200); + let r = s + .authed(Method::GET, "/v1/me/agent-tokens", &p) + .send() + .await + .unwrap(); + assert_eq!(json_of(r).await.as_array().unwrap().len(), 1); +} + +#[tokio::test] +async fn agent_routes_skip_the_gate_every_other_route_keeps_it() { + let s = start().await; + let p = phone(&s, "ada@example.com").await; + let id = register_ok(&s, &p).await["id"].as_str().unwrap().to_owned(); + let token = token_of(&mint(&s, &p, "phi").await); + + status(&s, &token).await; + let pong = rpc( + &s, + &token, + json!({ "jsonrpc": "2.0", "id": 1, "method": "ping" }), + ) + .await; + assert_eq!(pong["result"], json!({})); + // A wrong gate header does not matter here: the token is the credential. + let r = agent(&s, Method::GET, "/v1/agent/status", &token) + .header("X-Copper-Instance", "not-the-key") + .send() + .await + .unwrap(); + assert_eq!(r.status(), 200); + let r = s + .http + .get(s.url("/v1/agent/nope")) + .bearer_auth(&token) + .send() + .await + .unwrap(); + expect_error(r, 404, "not_found").await; + + // Every other /v1 route still needs the gate. + let frames_path = format!("/v1/me/links/{id}/frames"); + for (m, path) in [ + (Method::GET, "/v1/me/links"), + (Method::POST, "/v1/me/links"), + (Method::GET, frames_path.as_str()), + (Method::POST, frames_path.as_str()), + (Method::GET, "/v1/me/agent-tokens"), + (Method::POST, "/v1/me/agent-tokens"), + (Method::GET, "/v1/info"), + (Method::GET, "/v1/devices"), + (Method::GET, "/v1/agents"), + (Method::GET, "/v1/agentx"), + ] { + let r = s + .http + .request(m.clone(), s.url(path)) + .bearer_auth(&p.token) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 401, "{m} {path}"); + assert_eq!(json_of(r).await["error"], "instance_key", "{m} {path}"); + } + // A cat_ token is not a session. + let r = s + .req(Method::GET, "/v1/me/links") + .bearer_auth(&token) + .send() + .await + .unwrap(); + expect_error(r, 401, "session").await; + + let info = json_of(s.req(Method::GET, "/v1/info").send().await.unwrap()).await; + assert!( + info["features"] + .as_array() + .unwrap() + .contains(&json!("device_agent")), + "{info}" + ); +} + +#[tokio::test] +async fn agent_rate_limit_is_per_token() { + let s = start_with(|cfg| { + tune(cfg); + cfg.device_agent.agent_per_minute = 5; + }) + .await; + let p = phone(&s, "ada@example.com").await; + let token_a = token_of(&mint(&s, &p, "a").await); + let token_b = token_of(&mint(&s, &p, "b").await); + for _ in 0..5 { + status(&s, &token_a).await; + } + let resp = agent(&s, Method::GET, "/v1/agent/status", &token_a) + .send() + .await + .unwrap(); + assert_eq!(resp.headers()["retry-after"], "60"); + expect_error(resp, 429, "rate_limited").await; + let resp = agent(&s, Method::POST, "/v1/agent/mcp", &token_a) + .json(&json!({ "jsonrpc": "2.0", "id": 1, "method": "ping" })) + .send() + .await + .unwrap(); + assert_eq!(resp.status(), 429); + status(&s, &token_b).await; +} + +// --------------------------------------------------------------------------------------------- +// MCP + +#[tokio::test] +async fn mcp_protocol_basics() { + let s = start().await; + let p = phone(&s, "ada@example.com").await; + let token = token_of(&mint(&s, &p, "phi").await); + + let init = rpc( + &s, + &token, + json!({ + "jsonrpc": "2.0", "id": 1, "method": "initialize", + "params": { + "protocolVersion": "2025-03-26", + "capabilities": {}, + "clientInfo": { "name": "phi", "version": "1.0" }, + }, + }), + ) + .await; + assert_eq!(init["jsonrpc"], "2.0"); + assert_eq!(init["id"], 1); + let result = &init["result"]; + assert_eq!(result["protocolVersion"], "2025-03-26"); + assert_eq!( + result["capabilities"], + json!({ "tools": { "listChanged": false } }) + ); + assert_eq!(result["serverInfo"]["name"], "copper-mobile"); + assert_eq!(result["serverInfo"]["version"], env!("CARGO_PKG_VERSION")); + let instructions = result["instructions"].as_str().unwrap(); + for needle in [ + "iPhone", + "jev_run", + "DONE", + "BLOCKED", + "browser_snapshot", + "open on their screen", + ] { + assert!(instructions.contains(needle), "{needle}: {instructions}"); + } + let init = rpc( + &s, + &token, + json!({ "jsonrpc": "2.0", "id": 2, "method": "initialize", + "params": { "protocolVersion": "2099-01-01" } }), + ) + .await; + assert_eq!(init["result"]["protocolVersion"], "2025-06-18"); + + // Notifications (and client responses): 202, empty body. + for body in [ + json!({ "jsonrpc": "2.0", "method": "notifications/initialized" }), + json!({ "jsonrpc": "2.0", "method": "notifications/cancelled", "params": { "requestId": 1 } }), + json!({ "jsonrpc": "2.0", "id": 9, "result": {} }), + ] { + let r = agent(&s, Method::POST, "/v1/agent/mcp", &token) + .json(&body) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 202, "{body}"); + assert_eq!(r.text().await.unwrap(), ""); + } + + let pong = rpc( + &s, + &token, + json!({ "jsonrpc": "2.0", "id": "a", "method": "ping" }), + ) + .await; + assert_eq!(pong, json!({ "jsonrpc": "2.0", "id": "a", "result": {} })); + let unknown = rpc( + &s, + &token, + json!({ "jsonrpc": "2.0", "id": 3, "method": "resources/list" }), + ) + .await; + assert_eq!(unknown["id"], 3); + assert_eq!(unknown["error"]["code"], -32601); + let no_name = rpc( + &s, + &token, + json!({ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {} }), + ) + .await; + assert_eq!(no_name["error"]["code"], -32602); + + // Batches, bad JSON, non-objects: 400 with a JSON-RPC error. + for (body, code) in [ + (r#"[{"jsonrpc":"2.0","id":1,"method":"ping"}]"#, -32600), + ("not json", -32700), + ("42", -32600), + (r#"{"jsonrpc":"2.0","id":1}"#, -32600), + ] { + let r = agent(&s, Method::POST, "/v1/agent/mcp", &token) + .body(body) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 400, "{body}"); + assert_eq!(json_of(r).await["error"]["code"], code, "{body}"); + } + + // GET and DELETE: 405. + for m in [Method::GET, Method::DELETE] { + let r = agent(&s, m.clone(), "/v1/agent/mcp", &token) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 405, "{m}"); + assert_eq!(r.headers()["allow"], "POST"); + } + let r = s.http.get(s.url("/v1/agent/mcp")).send().await.unwrap(); + expect_error(r, 401, "agent_token").await; + + // tools/list: empty before the device registers, then its manifest even while offline. + let list = rpc( + &s, + &token, + json!({ "jsonrpc": "2.0", "id": 5, "method": "tools/list" }), + ) + .await; + assert_eq!(list["result"], json!({ "tools": [] })); + register_ok(&s, &p).await; + let list = rpc( + &s, + &token, + json!({ "jsonrpc": "2.0", "id": 6, "method": "tools/list", "params": {} }), + ) + .await; + assert_eq!(list["result"]["tools"], manifest()); + let st = status(&s, &token).await; + assert_eq!(st["online"], false); + assert_eq!(st["tools"], 3); + assert_eq!(st["label"], DEVICE_NAME); +} + +#[tokio::test] +async fn tools_call_answers_at_once_when_it_cannot_reach_the_device() { + let s = start().await; + let p = phone(&s, "ada@example.com").await; + let token = token_of(&mint(&s, &p, "phi").await); + + // Never registered: turned off. + let r = rpc(&s, &token, call(1, "jev_run", json!({}))).await; + assert_eq!(r["id"], 1); + assert_eq!(r["result"]["isError"], true); + let text = text_of(&r["result"]); + assert!( + text.contains("turned off") && text.contains(DEVICE_NAME), + "{text}" + ); + + // Registered, Copper not open: immediate, names the device. + let id = register_ok(&s, &p).await["id"].as_str().unwrap().to_owned(); + let started = Instant::now(); + let r = rpc(&s, &token, call(2, "jev_run", json!({ "goal": "x" }))).await; + assert!( + started.elapsed() < Duration::from_secs(1), + "offline must not wait" + ); + assert_eq!(r["result"]["isError"], true); + assert_eq!( + text_of(&r["result"]), + format!( + "Copper isn't open on {DEVICE_NAME}. Ask the person to open Copper on their iPhone and \ + keep it on screen (Settings › Agents › Let agents use this iPhone must be on), then \ + try again." + ) + ); + // The same as an SSE answer: one message, then the stream ends. + let mut answer = sse_call(&s, &token, call(3, "jev_run", json!({}))).await; + let ev = answer.next().await.unwrap(); + assert_eq!(ev.name, "message"); + let msg = ev.json(); + assert_eq!(msg["id"], 3); + assert!(text_of(&msg["result"]).starts_with("Copper isn't open on")); + assert!(answer.next().await.is_none()); + + // A tool the device does not have: named, offline or online. + let r = rpc(&s, &token, call(4, "nope_tool", json!({}))).await; + assert_eq!(r["result"]["isError"], true); + assert!(text_of(&r["result"]).contains("\"nope_tool\"")); + let (mut dev, _) = connect(&s, &p, &id).await; + let r = rpc(&s, &token, call(5, "other_tool", json!({}))).await; + assert!(text_of(&r["result"]).contains("\"other_tool\"")); + // Nothing reached the device. + match dev.next_within(Duration::from_millis(300)).await { + Err(()) => {} + Ok(Some(ev)) => assert_eq!(ev.name, "ping", "{ev:?}"), + Ok(None) => panic!("the device's stream ended"), + } + // Arguments that are not an object. + let r = rpc(&s, &token, call(6, "jev_run", json!("go"))).await; + assert_eq!(r["error"]["code"], -32602); + + // Revoked: turned off. + let r = s + .authed(Method::DELETE, &format!("/v1/me/links/{id}"), &p) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 200); + assert_eq!(dev.next_event().await.unwrap().name, "revoked"); + let r = rpc(&s, &token, call(7, "jev_run", json!({}))).await; + assert!(text_of(&r["result"]).contains("turned off")); +} + +#[tokio::test] +async fn relayed_call_json_round_trip() { + let s = start().await; + let p = phone(&s, "ada@example.com").await; + let id = register_ok(&s, &p).await["id"].as_str().unwrap().to_owned(); + let minted = mint(&s, &p, "phi").await; + let token = token_of(&minted); + let (mut dev, _) = connect(&s, &p, &id).await; + assert_eq!(status(&s, &token).await["online"], true); + + let args = + json!({ "goal": "Find flights to Lisbon on 2026-11-20", "url": "https://example.com" }); + let pending = spawn_call(&s, &token, call(7, "jev_run", args.clone())); + let req = next_request(&mut dev).await; + let rid = req["id"].as_str().unwrap().to_owned(); + assert!(rid.starts_with("req_"), "{rid}"); + assert_eq!(req["method"], "tools/call"); + assert_eq!( + req["params"], + json!({ "name": "jev_run", "arguments": args }) + ); + assert_eq!( + req["caller"], + json!({ "token_id": minted["id"], "label": "phi" }) + ); + assert_eq!(req["deadline_ms"], 1500); + + // Replies for unknown requests are accepted and ignored; unknown types are skipped. + let ack = post_frames( + &s, + &p, + &id, + json!([ + { "type": "reply", "id": "req_unknown", "result": { "content": [] } }, + { "type": "heartbeat" }, + { "type": "log", "level": "info", "message": "starting" }, + { "type": "bogus" }, + { "no": "type" }, + ]), + ) + .await; + assert_eq!(ack["accepted"], 3); + + let result = json!({ + "content": [{ "type": "text", "text": "DONE: 3 flights" }], + "isError": false, + "structuredContent": { "flights": 3 }, + }); + let ack = post_frames( + &s, + &p, + &id, + json!([{ "type": "reply", "id": rid, "result": result }]), + ) + .await; + assert_eq!(ack["accepted"], 1); + let answer = pending.await.unwrap(); + assert_eq!( + answer, + json!({ "jsonrpc": "2.0", "id": 7, "result": result }) + ); + // A late duplicate is ignored. + post_frames( + &s, + &p, + &id, + json!([{ "type": "reply", "id": rid, "result": result }]), + ) + .await; + + // A reply `error` becomes isError with its message. + let pending = spawn_call(&s, &token, call(8, "browser_snapshot", json!({}))); + let rid = next_request(&mut dev).await["id"] + .as_str() + .unwrap() + .to_owned(); + post_frames( + &s, + &p, + &id, + json!([{ "type": "reply", "id": rid, + "error": { "code": "tab_gone", "message": "The tab was closed" } }]), + ) + .await; + let answer = pending.await.unwrap(); + assert_eq!(answer["id"], 8); + assert_eq!(answer["result"]["isError"], true); + assert_eq!(text_of(&answer["result"]), "The tab was closed"); + + // A progress token on a JSON answer: progress is not delivered, the call still completes. + let mut body = call(9, "jev_observe", json!({})); + body["params"]["_meta"] = json!({ "progressToken": 5 }); + let pending = spawn_call(&s, &token, body); + let rid = next_request(&mut dev).await["id"] + .as_str() + .unwrap() + .to_owned(); + post_frames( + &s, + &p, + &id, + json!([ + { "type": "progress", "id": rid, "seq": 1, "message": "1 · OBSERVE" }, + { "type": "reply", "id": rid, "result": { "content": [], "isError": false } }, + ]), + ) + .await; + assert_eq!( + pending.await.unwrap(), + json!({ "jsonrpc": "2.0", "id": 9, "result": { "content": [], "isError": false } }) + ); +} + +#[tokio::test] +async fn relayed_call_sse_answer_with_progress() { + let s = start().await; + let p = phone(&s, "ada@example.com").await; + let id = register_ok(&s, &p).await["id"].as_str().unwrap().to_owned(); + let token = token_of(&mint(&s, &p, "phi").await); + let (mut dev, _) = connect(&s, &p, &id).await; + + let mut body = call(10, "jev_run", json!({ "goal": "Search for lamps" })); + body["params"]["_meta"] = json!({ "progressToken": "tok-1" }); + let mut answer = sse_call(&s, &token, body).await; + let rid = next_request(&mut dev).await["id"] + .as_str() + .unwrap() + .to_owned(); + post_frames( + &s, + &p, + &id, + json!([ + { "type": "progress", "id": rid, "seq": 1, "message": "1 · OBSERVE" }, + { "type": "progress", "id": rid, "seq": 2, "message": "2 · CLICK [12] button \"Search\"" }, + ]), + ) + .await; + // Stale or repeated seqs are ignored. + post_frames( + &s, + &p, + &id, + json!([ + { "type": "progress", "id": rid, "seq": 2, "message": "dup" }, + { "type": "progress", "id": rid, "seq": 1, "message": "old" }, + ]), + ) + .await; + for (seq, message) in [(1, "1 · OBSERVE"), (2, "2 · CLICK [12] button \"Search\"")] { + let ev = answer.next().await.unwrap(); + assert_eq!(ev.name, "message"); + assert_eq!( + ev.json(), + json!({ + "jsonrpc": "2.0", + "method": "notifications/progress", + "params": { "progressToken": "tok-1", "progress": seq, "message": message }, + }) + ); + } + // Idle: keepalive comments (every 200 ms in this suite). + tokio::time::sleep(Duration::from_millis(700)).await; + post_frames( + &s, + &p, + &id, + json!([{ "type": "reply", "id": rid, + "result": { "content": [{ "type": "text", "text": "DONE" }], "isError": false } }]), + ) + .await; + let ev = answer.next().await.unwrap(); + assert_eq!(ev.name, "message"); + assert_eq!( + ev.json(), + json!({ "jsonrpc": "2.0", "id": 10, + "result": { "content": [{ "type": "text", "text": "DONE" }], "isError": false } }) + ); + assert!( + answer.next().await.is_none(), + "the stream ends after the response" + ); + assert!( + answer.comments >= 1, + "keepalive comments: {}", + answer.comments + ); + + // Without a progress token, progress frames are not forwarded. A pretty-printed reply + // still arrives as one `data:` line. + let mut answer = sse_call(&s, &token, call(11, "jev_run", json!({}))).await; + let rid = next_request(&mut dev).await["id"] + .as_str() + .unwrap() + .to_owned(); + post_frames( + &s, + &p, + &id, + json!([{ "type": "progress", "id": rid, "seq": 1, "message": "1 · OBSERVE" }]), + ) + .await; + let pretty = format!( + "{{\"frames\": [{{\"type\": \"reply\", \"id\": \"{rid}\", \"result\": {{\n \"content\": [],\n \"isError\": false\n}}}}]}}" + ); + let r = s + .authed(Method::POST, &format!("/v1/me/links/{id}/frames"), &p) + .body(pretty) + .send() + .await + .unwrap(); + assert_eq!(json_of(r).await["accepted"], 1); + let ev = answer.next().await.unwrap(); + assert!(!ev.data.contains('\n'), "{:?}", ev.data); + assert_eq!( + ev.json(), + json!({ "jsonrpc": "2.0", "id": 11, "result": { "content": [], "isError": false } }) + ); + assert!(answer.next().await.is_none()); +} + +#[tokio::test] +async fn deadline_cancels_the_call_on_the_device() { + let s = start().await; + let p = phone(&s, "ada@example.com").await; + let id = register_ok(&s, &p).await["id"].as_str().unwrap().to_owned(); + let token = token_of(&mint(&s, &p, "phi").await); + let (mut dev, _) = connect(&s, &p, &id).await; + + // JSON answer: the device gets `cancel` at the deadline, the agent "timed out". + let started = Instant::now(); + let pending = spawn_call(&s, &token, call(12, "jev_run", json!({}))); + let rid = next_request(&mut dev).await["id"] + .as_str() + .unwrap() + .to_owned(); + // Heartbeats keep the device online; nothing answers. + post_frames(&s, &p, &id, json!([{ "type": "heartbeat" }])).await; + let ev = dev.next_event().await.unwrap(); + assert_eq!(ev.name, "cancel"); + assert_eq!(ev.json(), json!({ "id": rid })); + let answer = pending.await.unwrap(); + let elapsed = started.elapsed(); + assert!( + elapsed >= Duration::from_millis(1400) && elapsed < Duration::from_secs(5), + "{elapsed:?}" + ); + assert_eq!(answer["id"], 12); + assert_eq!(answer["result"]["isError"], true); + assert!(text_of(&answer["result"]).contains("timed out")); + // A reply after the deadline is ignored. + post_frames( + &s, + &p, + &id, + json!([{ "type": "reply", "id": rid, "result": { "content": [] } }]), + ) + .await; + + // SSE answer: keepalives while waiting, then the timed-out response. + let mut answer = sse_call(&s, &token, call(13, "jev_run", json!({}))).await; + let rid = next_request(&mut dev).await["id"] + .as_str() + .unwrap() + .to_owned(); + let ev = dev.next_event().await.unwrap(); + assert_eq!( + (ev.name.as_str(), ev.json()), + ("cancel", json!({ "id": rid })) + ); + let msg = answer.next().await.unwrap().json(); + assert_eq!(msg["id"], 13); + assert!(text_of(&msg["result"]).contains("timed out")); + assert!(answer.comments >= 3, "keepalives: {}", answer.comments); + assert!(answer.next().await.is_none()); +} + +#[tokio::test] +async fn agent_going_away_cancels_the_call_on_the_device() { + let s = start().await; + let p = phone(&s, "ada@example.com").await; + let id = register_ok(&s, &p).await["id"].as_str().unwrap().to_owned(); + let token = token_of(&mint(&s, &p, "phi").await); + let (mut dev, _) = connect(&s, &p, &id).await; + + // JSON answer: the agent's request is dropped mid-call. + let pending = spawn_call(&s, &token, call(14, "jev_run", json!({}))); + let rid = next_request(&mut dev).await["id"] + .as_str() + .unwrap() + .to_owned(); + pending.abort(); + let ev = dev.next_event().await.unwrap(); + assert_eq!( + (ev.name.as_str(), ev.json()), + ("cancel", json!({ "id": rid })) + ); + + // SSE answer: the agent closes the stream. + let answer = sse_call(&s, &token, call(15, "jev_run", json!({}))).await; + let rid = next_request(&mut dev).await["id"] + .as_str() + .unwrap() + .to_owned(); + drop(answer); + let ev = dev.next_event().await.unwrap(); + assert_eq!( + (ev.name.as_str(), ev.json()), + ("cancel", json!({ "id": rid })) + ); + // The device's late reply is ignored. + post_frames( + &s, + &p, + &id, + json!([{ "type": "reply", "id": rid, "result": { "content": [] } }]), + ) + .await; +} + +#[tokio::test] +async fn revoking_the_link_closes_its_stream_and_fails_the_call() { + let s = start().await; + let p = phone(&s, "ada@example.com").await; + let id = register_ok(&s, &p).await["id"].as_str().unwrap().to_owned(); + let token = token_of(&mint(&s, &p, "phi").await); + let (mut dev, _) = connect(&s, &p, &id).await; + + let pending = spawn_call(&s, &token, call(16, "jev_run", json!({}))); + next_request(&mut dev).await; + let mac = second_device(&s, "ada@example.com").await; + let r = s + .authed(Method::DELETE, &format!("/v1/me/links/{id}"), &mac) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 200); + let ev = dev.next_event().await.unwrap(); + assert_eq!((ev.name.as_str(), ev.data.as_str()), ("revoked", "{}")); + assert!(dev.next().await.is_none(), "revoked stream must end"); + let answer = pending.await.unwrap(); + assert_eq!(answer["result"]["isError"], true); + assert!(text_of(&answer["result"]).contains("turned off")); + let r = rpc(&s, &token, call(17, "jev_run", json!({}))).await; + assert!(text_of(&r["result"]).contains("turned off")); + assert_eq!(status(&s, &token).await["online"], false); + + // Opening the revoked link's stream: hello (revoked), then revoked, then the end. + let (mut dev, hello) = connect(&s, &p, &id).await; + assert_eq!(hello["link"]["revoked"], true); + assert_eq!(hello["link"]["online"], false); + assert_eq!(dev.next_event().await.unwrap().name, "revoked"); + assert!(dev.next().await.is_none()); + + // Registering again turns it back on. + register_ok(&s, &p).await; + let (_dev, hello) = connect(&s, &p, &id).await; + assert_eq!(hello["link"]["online"], true); + assert_eq!(status(&s, &token).await["online"], true); +} + +#[tokio::test] +async fn revoking_a_token_fails_its_call_in_flight() { + let s = start().await; + let p = phone(&s, "ada@example.com").await; + let id = register_ok(&s, &p).await["id"].as_str().unwrap().to_owned(); + let minted = mint(&s, &p, "phi").await; + let token = token_of(&minted); + let (mut dev, _) = connect(&s, &p, &id).await; + + let pending = spawn_call(&s, &token, call(18, "jev_run", json!({}))); + let rid = next_request(&mut dev).await["id"] + .as_str() + .unwrap() + .to_owned(); + let r = s + .authed( + Method::DELETE, + &format!("/v1/me/agent-tokens/{}", minted["id"].as_str().unwrap()), + &p, + ) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 200); + let ev = dev.next_event().await.unwrap(); + assert_eq!( + (ev.name.as_str(), ev.json()), + ("cancel", json!({ "id": rid })) + ); + let answer = pending.await.unwrap(); + assert_eq!(answer["result"]["isError"], true); + assert!(text_of(&answer["result"]).contains("revoked")); +} + +#[tokio::test] +async fn deleting_the_device_revokes_its_link_and_tokens() { + let s = start().await; + let p = phone(&s, "ada@example.com").await; + let id = register_ok(&s, &p).await["id"].as_str().unwrap().to_owned(); + let token = token_of(&mint(&s, &p, "phi").await); + let (mut dev, _) = connect(&s, &p, &id).await; + + let mac = second_device(&s, "ada@example.com").await; + let r = s + .authed( + Method::DELETE, + &format!("/v1/devices/{}", p.device_id), + &mac, + ) + .send() + .await + .unwrap(); + assert_eq!(r.status(), 200); + assert_eq!(dev.next_event().await.unwrap().name, "revoked"); + let r = agent(&s, Method::GET, "/v1/agent/status", &token) + .send() + .await + .unwrap(); + expect_error(r, 401, "agent_token").await; + let link = get_link(&s, &mac, &id).await; + assert_eq!(link["revoked"], true); + assert_eq!(link["device_name"], DEVICE_NAME, "falls back to the label"); + assert_eq!(list_links(&s, &mac).await.len(), 0); + let r = s + .authed(Method::GET, "/v1/me/agent-tokens", &mac) + .send() + .await + .unwrap(); + assert_eq!(json_of(r).await, json!([])); +} + +#[tokio::test] +async fn large_frames_bodies_are_accepted() { + let s = start().await; + let p = phone(&s, "ada@example.com").await; + let id = register_ok(&s, &p).await["id"].as_str().unwrap().to_owned(); + let token = token_of(&mint(&s, &p, "phi").await); + let (mut dev, _) = connect(&s, &p, &id).await; + + let pending = spawn_call(&s, &token, call(19, "browser_snapshot", json!({}))); + let rid = next_request(&mut dev).await["id"] + .as_str() + .unwrap() + .to_owned(); + let screenshot = "A".repeat(20 * 1024 * 1024); + let ack = post_frames( + &s, + &p, + &id, + json!([{ "type": "reply", "id": rid, "result": { + "content": [{ "type": "image", "mimeType": "image/png", "data": screenshot }], + "isError": false, + } }]), + ) + .await; + assert_eq!(ack["accepted"], 1); + let answer = pending.await.unwrap(); + assert_eq!( + answer["result"]["content"][0]["data"] + .as_str() + .unwrap() + .len(), + 20 * 1024 * 1024 + ); +} + +#[tokio::test] +async fn online_needs_heartbeats_and_a_closed_stream_fails_the_call() { + let s = start_with(|cfg| { + tune(cfg); + cfg.device_agent.online_window = Duration::from_millis(800); + }) + .await; + let p = phone(&s, "ada@example.com").await; + let id = register_ok(&s, &p).await["id"].as_str().unwrap().to_owned(); + let token = token_of(&mint(&s, &p, "phi").await); + let (dev, _) = connect(&s, &p, &id).await; + assert_eq!(status(&s, &token).await["online"], true); + + // Stream open but silent past the window: offline (and calls answer at once). + tokio::time::sleep(Duration::from_millis(1000)).await; + assert_eq!(status(&s, &token).await["online"], false); + let r = rpc(&s, &token, call(20, "jev_run", json!({}))).await; + assert!(text_of(&r["result"]).starts_with("Copper isn't open on")); + // A heartbeat brings it back. + let ack = post_frames(&s, &p, &id, json!([{ "type": "heartbeat" }])).await; + assert_eq!(ack["accepted"], 1); + assert_eq!(status(&s, &token).await["online"], true); + assert!(status(&s, &token).await["last_seen_at"].is_string()); + + // Copper leaves the screen mid-call: the call fails after the offline grace, not the + // whole deadline. + let mut dev = dev; + let pending = spawn_call(&s, &token, call(21, "jev_run", json!({}))); + next_request(&mut dev).await; + let started = Instant::now(); + drop(dev); + let answer = pending.await.unwrap(); + assert!( + started.elapsed() < Duration::from_millis(1400), + "{:?}", + started.elapsed() + ); + assert_eq!(answer["result"]["isError"], true); + assert!( + text_of(&answer["result"]).contains("Copper closed on"), + "{answer}" + ); +} + +/// Collects everything a tracing subscriber writes. +#[derive(Clone, Default)] +struct Captured(std::sync::Arc>>); + +impl std::io::Write for Captured { + fn write(&mut self, buf: &[u8]) -> std::io::Result { + self.0.lock().unwrap().extend_from_slice(buf); + Ok(buf.len()) + } + + fn flush(&mut self) -> std::io::Result<()> { + Ok(()) + } +} + +impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for Captured { + type Writer = Self; + + fn make_writer(&'a self) -> Self { + self.clone() + } +} + +#[tokio::test] +async fn one_log_line_per_call_never_arguments_or_results() { + // With a single registered dispatcher, tracing caches a callsite's interest from whichever + // thread hits it first — another test's thread, with no subscriber, caches "never". A + // second live dispatcher makes interest the union of both, so this thread sees everything. + let _union = tracing::Dispatch::new( + tracing_subscriber::fmt() + .with_max_level(tracing::Level::INFO) + .with_writer(std::io::sink) + .finish(), + ); + let captured = Captured::default(); + let subscriber = tracing_subscriber::fmt() + .json() + .flatten_event(true) + .with_current_span(false) + .with_span_list(false) + .with_max_level(tracing::Level::INFO) + .with_writer(captured.clone()) + .finish(); + // `#[tokio::test]` runs the server's tasks on this thread, so a thread-local subscriber + // sees them. + let _default = tracing::subscriber::set_default(subscriber); + + let s = start().await; + let p = phone(&s, "ada@example.com").await; + let id = register_ok(&s, &p).await["id"].as_str().unwrap().to_owned(); + let minted = mint(&s, &p, "phi").await; + let token = token_of(&minted); + // Offline first, then a relayed call. + rpc( + &s, + &token, + call(1, "jev_run", json!({ "goal": "secret-argument-1" })), + ) + .await; + let (mut dev, _) = connect(&s, &p, &id).await; + let pending = spawn_call( + &s, + &token, + call(2, "jev_run", json!({ "goal": "secret-argument-2" })), + ); + let rid = next_request(&mut dev).await["id"] + .as_str() + .unwrap() + .to_owned(); + post_frames( + &s, + &p, + &id, + json!([ + { "type": "progress", "id": rid, "seq": 1, "message": "secret-progress" }, + { "type": "reply", "id": rid, + "result": { "content": [{ "type": "text", "text": "secret-result" }], "isError": false } }, + ]), + ) + .await; + pending.await.unwrap(); + + let out = String::from_utf8(captured.0.lock().unwrap().clone()).unwrap(); + for secret in [ + "secret-argument", + "secret-progress", + "secret-result", + token.as_str(), + ] { + assert!(!out.contains(secret), "{secret} in the log:\n{out}"); + } + let calls: Vec = out + .lines() + .filter_map(|l| serde_json::from_str::(l).ok()) + .filter(|v| v["message"] == "agent call" && v["token_id"] == minted["id"]) + .collect(); + assert_eq!(calls.len(), 2, "{out}"); + for (line, status) in calls.iter().zip(["offline", "ok"]) { + assert_eq!(line["status"], status, "{line}"); + assert_eq!(line["token_id"], minted["id"], "{line}"); + assert_eq!(line["device_id"], p.device_id.as_str(), "{line}"); + assert_eq!(line["tool"], "jev_run", "{line}"); + assert!(line["ms"].is_u64(), "{line}"); + } +} diff --git a/crates/core/src/app.rs b/crates/core/src/app.rs index f1d298f..cc82ba4 100644 --- a/crates/core/src/app.rs +++ b/crates/core/src/app.rs @@ -21,8 +21,9 @@ use crate::state::SharedState; pub const INSTANCE_HEADER: &str = "x-copper-instance"; /// A `/v1` route reachable without the gate header: the pairing code is the credential -/// (rate limited by the auth limiter). The SSO routes ([`crate::sso::is_sso_path`]) and -/// [`crate::agents::AGENT_PAIR_PATH`] are ungated too. +/// (rate limited by the auth limiter). The SSO routes ([`crate::sso::is_sso_path`]), +/// [`crate::agents::AGENT_PAIR_PATH`] and the device-agent relay's agent side +/// ([`crate::device_agent::is_agent_path`]) are ungated too. pub const PAIR_PATH: &str = "/v1/auth/pair"; /// Query parameter that may carry the gate credential on a canvas room socket @@ -49,6 +50,9 @@ pub const FEATURES: &[&str] = &[ // `GET /v1/sync/docs/{domain}/revisions` (+ `/{version}`, `/{version}/restore`) and the // optional `X-Copper-Build` header on doc writes (0.12.0). "doc_revisions", + // Device agent relay: `/v1/me/links` (+ `/{id}/frames`), `/v1/me/agent-tokens` and the + // ungated `GET /v1/agent/status` + `POST /v1/agent/mcp` (0.13.0). + "device_agent", ]; /// Core `/v1` routes (auth, pairing, devices, sync, intelligence, info). Paths are relative to `/v1`. @@ -62,6 +66,7 @@ pub fn router() -> Router { .merge(crate::sync::routes()) .merge(crate::intelligence::routes()) .merge(crate::addons::routes()) + .merge(crate::device_agent::routes()) } /// The complete HTTP app for the canvas/core test suites: `/healthz` + `/v1/*` (core routes @@ -130,13 +135,15 @@ async fn info( } /// Whether `path` is behind the instance gate: everything under `/v1` except [`PAIR_PATH`], -/// the SSO routes and [`crate::agents::AGENT_PAIR_PATH`] (each carries its own credential or -/// none at all). `/healthz`, `/admin/api/*` (own cookie auth) and the portal are not. +/// the SSO routes, [`crate::agents::AGENT_PAIR_PATH`] and `/v1/agent/*` (each carries its own +/// credential or none at all). `/healthz`, `/admin/api/*` (own cookie auth) and the portal +/// are not. pub fn is_gated(path: &str) -> bool { (path == "/v1" || path.starts_with("/v1/")) && path != PAIR_PATH && path != crate::agents::AGENT_PAIR_PATH && !crate::sso::is_sso_path(path) + && !crate::device_agent::is_agent_path(path) } /// Whether `path` is a canvas room socket, `/v1/canvases/{id}/ws`. @@ -351,6 +358,10 @@ mod tests { "/v1/auth/pairing", "/v1/auth/sso/google/x", "/v1/agents", + "/v1/agentx", + "/v1/me/links", + "/v1/me/links/0192aa/frames", + "/v1/me/agent-tokens", "/v1/x", ] { assert!(is_gated(p), "{p}"); @@ -361,6 +372,9 @@ mod tests { "/v1/auth/sso", "/v1/auth/sso/google", "/v1/agents/pair", + "/v1/agent", + "/v1/agent/status", + "/v1/agent/mcp", "/admin/api/login", "/", "/keys", diff --git a/crates/core/src/auth.rs b/crates/core/src/auth.rs index 57f2b90..8634fcd 100644 --- a/crates/core/src/auth.rs +++ b/crates/core/src/auth.rs @@ -752,8 +752,8 @@ async fn rename_device( Ok(Json(device)) } -/// Remove a device: revokes its sessions (FK cascade) and deletes its `tabs:` doc -/// and that doc's revisions. +/// Remove a device: revokes its sessions (FK cascade), deletes its `tabs:` doc and that +/// doc's revisions, and turns off its device-agent link and agent tokens. async fn delete_device( State(state): State, user: AuthUser, @@ -779,7 +779,18 @@ async fn delete_device( .execute(&mut *tx) .await?; } + let agent = crate::device_agent::revoke_device(&mut tx, &[user.user_id], id).await?; tx.commit().await?; + agent.apply(&state.device_agent); + if !agent.is_empty() { + tracing::info!( + user_id = %user.user_id, + device_id = %id, + links = agent.links.len(), + agent_tokens = agent.tokens.len(), + "deleted device's agent link and tokens revoked" + ); + } Ok(Json(json!({ "ok": true }))) } diff --git a/crates/core/src/config.rs b/crates/core/src/config.rs index 0f0b908..513db4e 100644 --- a/crates/core/src/config.rs +++ b/crates/core/src/config.rs @@ -115,6 +115,45 @@ pub struct Config { /// Test-only SSO endpoint overrides. Never read from the config file or the environment. #[doc(hidden)] pub sso_test: SsoTestHooks, + /// Device-agent relay timings and limits (fixed by the relay contract; tests shorten them). + /// Never read from the config file or the environment. + #[doc(hidden)] + pub device_agent: DeviceAgentTuning, +} + +/// Timings and limits of the device-agent relay (`/v1/me/links`, `/v1/agent/*`). The defaults +/// are the documented contract and the only production behaviour; integration tests shorten +/// them so a deadline or an offline device can be exercised in about a second. +#[doc(hidden)] +#[derive(Clone, Debug)] +pub struct DeviceAgentTuning { + /// How long a relayed `tools/call` waits for the device's reply (200 s). + pub relay_deadline: std::time::Duration, + /// `: keepalive` comment interval on an agent's SSE answer (10 s). + pub agent_keepalive: std::time::Duration, + /// `ping` event interval on a device's frames stream (15 s). + pub device_ping: std::time::Duration, + /// A link is online while its stream is open and it was heard from this recently (45 s). + pub online_window: std::time::Duration, + /// A pending call fails once its device has been offline this long (15 s), instead of + /// waiting out the whole deadline. + pub offline_grace: std::time::Duration, + /// Requests per minute per agent token on `/v1/agent/*` (600). + pub agent_per_minute: u32, +} + +impl Default for DeviceAgentTuning { + fn default() -> Self { + use std::time::Duration; + Self { + relay_deadline: Duration::from_secs(200), + agent_keepalive: Duration::from_secs(10), + device_ping: Duration::from_secs(15), + online_window: Duration::from_secs(45), + offline_grace: Duration::from_secs(15), + agent_per_minute: 600, + } + } } /// Lets integration tests point SSO at a local fake provider. Not configurable by operators: @@ -145,6 +184,7 @@ impl fmt::Debug for Config { .field("log_format", &self.log_format) .field("log_level", &self.log_level) .field("sso_test", &self.sso_test) + .field("device_agent", &self.device_agent) .finish() } } @@ -504,6 +544,7 @@ impl Config { .filter(|s| !s.trim().is_empty()) .unwrap_or_else(|| "info".into()), sso_test: SsoTestHooks::default(), + device_agent: DeviceAgentTuning::default(), }) } @@ -534,6 +575,7 @@ impl Config { log_format: LogFormat::Pretty, log_level: "info".into(), sso_test: SsoTestHooks::default(), + device_agent: DeviceAgentTuning::default(), } } diff --git a/crates/core/src/device_agent/hub.rs b/crates/core/src/device_agent/hub.rs new file mode 100644 index 0000000..f11456c --- /dev/null +++ b/crates/core/src/device_agent/hub.rs @@ -0,0 +1,418 @@ +//! The in-memory relay hub: which link has a frames stream open right now, and the agent calls +//! waiting for a device's reply. Single-process by design (one daemon per instance), like +//! [`crate::events`]. Every method takes the lock briefly and never awaits while holding it. + +use std::collections::HashMap; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::{Mutex, MutexGuard, PoisonError}; +use std::time::{Duration, Instant}; + +use governor::{DefaultKeyedRateLimiter, Quota, RateLimiter}; +use serde_json::value::RawValue; +use tokio::sync::{mpsc, oneshot}; +use uuid::Uuid; + +/// What the cloud sends down a device's frames stream (`GET /v1/me/links/{id}/frames`). +#[derive(Debug)] +pub enum Down { + /// A `request` event; the data (one JSON object) is already serialized. + Request(String), + /// A `cancel` event for this request id. + Cancel(String), + /// A newer stream for the same link replaced this one: `superseded`, then close. + Superseded, + /// The link was turned off: `revoked`, then close. + Revoked, +} + +/// How a pending call ended. +#[derive(Debug)] +pub enum Reply { + /// The device's `result`, exactly as it sent it. + Result(Box), + /// The device's `error.message`. + Error(String), + /// The link was revoked (or its device deleted) while the call was running. + TurnedOff, + /// The agent's token was revoked while the call was running. + TokenRevoked, +} + +/// One device `progress` frame, forwarded to the waiting call. +#[derive(Debug)] +pub struct Progress { + pub seq: i64, + pub message: String, +} + +/// A call handed to a device: wait on `reply`, forward `progress`. +pub struct Call { + pub reply: oneshot::Receiver, + pub progress: mpsc::UnboundedReceiver, +} + +struct Slot { + stream: u64, + tx: mpsc::UnboundedSender, + last_heard: Instant, +} + +struct Pending { + link: Uuid, + token: Uuid, + reply: oneshot::Sender, + progress: mpsc::UnboundedSender, + last_seq: Option, +} + +#[derive(Default)] +struct Inner { + /// Link id → its current frames stream. + slots: HashMap, + /// Request id (`req_…`) → the call waiting for it. + pending: HashMap, +} + +/// The relay hub (lives in [`crate::state::AppState`]). +pub struct Hub { + inner: Mutex, + next_stream: AtomicU64, + online_window: Duration, + limiter: DefaultKeyedRateLimiter, + checks: AtomicU64, +} + +impl std::fmt::Debug for Hub { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + let inner = self.lock(); + f.debug_struct("Hub") + .field("streams", &inner.slots.len()) + .field("pending", &inner.pending.len()) + .finish_non_exhaustive() + } +} + +/// A fresh request id: `req_` + 22 base64url chars (16 random bytes). +pub fn new_request_id() -> String { + format!( + "req_{}", + crate::ids::b64url(&crate::ids::random_bytes::<16>()) + ) +} + +impl Hub { + /// `per_minute` requests per agent token; a link is online while heard from within + /// `online_window`. + pub fn new(per_minute: u32, online_window: Duration) -> Self { + let n = std::num::NonZeroU32::new(per_minute.max(1)).expect("non-zero"); + Self { + inner: Mutex::new(Inner::default()), + next_stream: AtomicU64::new(1), + online_window, + limiter: RateLimiter::keyed(Quota::per_minute(n)), + checks: AtomicU64::new(0), + } + } + + fn lock(&self) -> MutexGuard<'_, Inner> { + self.inner.lock().unwrap_or_else(PoisonError::into_inner) + } + + /// `true` if this agent token may make another request now. + pub fn allow(&self, token: Uuid) -> bool { + if self.checks.fetch_add(1, Ordering::Relaxed) % 4096 == 4095 { + self.limiter.retain_recent(); + self.limiter.shrink_to_fit(); + } + self.limiter.check_key(&token).is_ok() + } + + /// A device opened its frames stream: it becomes the link's stream (the previous one, if + /// any, gets [`Down::Superseded`]). Returns the stream id (for [`Hub::detach`]) and the + /// receiving end. + pub fn attach(&self, link: Uuid) -> (u64, mpsc::UnboundedReceiver) { + let stream = self.next_stream.fetch_add(1, Ordering::Relaxed); + let (tx, rx) = mpsc::unbounded_channel(); + let old = self.lock().slots.insert( + link, + Slot { + stream, + tx, + last_heard: Instant::now(), + }, + ); + if let Some(old) = old { + let _ = old.tx.send(Down::Superseded); + } + (stream, rx) + } + + /// A frames stream ended. No-op if a newer stream already replaced it. Calls in flight stay + /// pending (the device may reconnect and still reply). + pub fn detach(&self, link: Uuid, stream: u64) -> bool { + let mut inner = self.lock(); + if inner.slots.get(&link).is_some_and(|s| s.stream == stream) { + inner.slots.remove(&link); + true + } else { + false + } + } + + /// The device was heard from (heartbeat or any frames POST). + pub fn heard(&self, link: Uuid) { + if let Some(slot) = self.lock().slots.get_mut(&link) { + slot.last_heard = Instant::now(); + } + } + + /// Online: a stream is open and the device was heard from within the online window. + pub fn is_online(&self, link: Uuid) -> bool { + self.lock() + .slots + .get(&link) + .is_some_and(|s| s.last_heard.elapsed() < self.online_window) + } + + /// Hand a call to the device: sends `frame` (the serialized `request` data carrying `id`) + /// down the link's stream and registers the waiter. `None` when the link is offline (the + /// caller answers at once). + pub fn begin(&self, link: Uuid, token: Uuid, id: &str, frame: String) -> Option { + let mut inner = self.lock(); + let slot = inner + .slots + .get(&link) + .filter(|s| s.last_heard.elapsed() < self.online_window)?; + slot.tx.send(Down::Request(frame)).ok()?; + let (reply_tx, reply_rx) = oneshot::channel(); + let (progress_tx, progress_rx) = mpsc::unbounded_channel(); + inner.pending.insert( + id.to_owned(), + Pending { + link, + token, + reply: reply_tx, + progress: progress_tx, + last_seq: None, + }, + ); + Some(Call { + reply: reply_rx, + progress: progress_rx, + }) + } + + /// A device's reply. Only the link the request went to may answer it; a reply for an + /// unknown or finished request is ignored (`false`). + pub fn reply(&self, link: Uuid, id: &str, reply: Reply) -> bool { + let pending = { + let mut inner = self.lock(); + if inner.pending.get(id).is_none_or(|p| p.link != link) { + return false; + } + inner.pending.remove(id) + }; + pending.is_some_and(|p| p.reply.send(reply).is_ok()) + } + + /// A device's progress frame. `seq` must grow (a stale or repeated one is ignored); a frame + /// without one counts as the next. `false` when ignored. + pub fn progress(&self, link: Uuid, id: &str, seq: Option, message: String) -> bool { + let mut inner = self.lock(); + let Some(p) = inner.pending.get_mut(id).filter(|p| p.link == link) else { + return false; + }; + let seq = seq.unwrap_or_else(|| p.last_seq.map_or(1, |s| s.saturating_add(1))); + if p.last_seq.is_some_and(|last| seq <= last) { + return false; + } + p.last_seq = Some(seq); + p.progress.send(Progress { seq, message }).is_ok() + } + + /// Stop waiting for a call: forget it and send the device a `cancel` if its stream is + /// open. `false` if the call had already finished. + pub fn cancel(&self, id: &str) -> bool { + let mut inner = self.lock(); + let Some(p) = inner.pending.remove(id) else { + return false; + }; + if let Some(slot) = inner.slots.get(&p.link) { + let _ = slot.tx.send(Down::Cancel(id.to_owned())); + } + true + } + + /// The link was turned off (revoked, or its device deleted): close its stream with + /// `revoked` and fail its calls in flight. + pub fn revoke_link(&self, link: Uuid) { + let (slot, failed) = { + let mut inner = self.lock(); + let slot = inner.slots.remove(&link); + let ids: Vec = inner + .pending + .iter() + .filter(|(_, p)| p.link == link) + .map(|(id, _)| id.clone()) + .collect(); + let failed: Vec = ids + .iter() + .filter_map(|id| inner.pending.remove(id)) + .collect(); + (slot, failed) + }; + if let Some(slot) = slot { + let _ = slot.tx.send(Down::Revoked); + } + for p in failed { + let _ = p.reply.send(Reply::TurnedOff); + } + } + + /// An agent token was revoked: fail its calls in flight and tell the devices to stop them. + pub fn revoke_token(&self, token: Uuid) { + let failed = { + let mut inner = self.lock(); + let ids: Vec = inner + .pending + .iter() + .filter(|(_, p)| p.token == token) + .map(|(id, _)| id.clone()) + .collect(); + let mut failed = Vec::with_capacity(ids.len()); + for id in ids { + if let Some(p) = inner.pending.remove(&id) { + if let Some(slot) = inner.slots.get(&p.link) { + let _ = slot.tx.send(Down::Cancel(id)); + } + failed.push(p); + } + } + failed + }; + for p in failed { + let _ = p.reply.send(Reply::TokenRevoked); + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn hub() -> Hub { + Hub::new(3, Duration::from_secs(45)) + } + + fn raw(s: &str) -> Box { + RawValue::from_string(s.to_owned()).unwrap() + } + + #[test] + fn request_ids() { + let id = new_request_id(); + assert!(id.starts_with("req_") && id.len() == 4 + 22, "{id}"); + assert_ne!(id, new_request_id()); + } + + #[tokio::test] + async fn attach_supersedes_and_detach_only_removes_its_own_stream() { + let h = hub(); + let link = Uuid::now_v7(); + assert!(!h.is_online(link)); + let (first, mut rx1) = h.attach(link); + assert!(h.is_online(link)); + let (second, _rx2) = h.attach(link); + assert!(matches!(rx1.recv().await, Some(Down::Superseded))); + assert!( + !h.detach(link, first), + "the old stream must not detach the new one" + ); + assert!(h.is_online(link)); + assert!(h.detach(link, second)); + assert!(!h.is_online(link)); + } + + #[tokio::test] + async fn calls_go_to_the_link_and_only_it_may_answer() { + let h = hub(); + let (link, other, token) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7()); + assert!( + h.begin(link, token, "req_a", "{}".into()).is_none(), + "offline" + ); + let (_, mut rx) = h.attach(link); + let mut call = h + .begin(link, token, "req_a", r#"{"id":"req_a"}"#.into()) + .unwrap(); + assert!(matches!(rx.recv().await, Some(Down::Request(f)) if f.contains("req_a"))); + assert!(!h.reply(other, "req_a", Reply::Error("x".into()))); + assert!(h.progress(link, "req_a", Some(2), "two".into())); + assert!( + !h.progress(link, "req_a", Some(2), "again".into()), + "stale seq" + ); + assert!( + !h.progress(link, "req_a", Some(1), "older".into()), + "stale seq" + ); + assert!(h.progress(link, "req_a", None, "next".into())); + assert_eq!(call.progress.recv().await.unwrap().seq, 2); + assert_eq!(call.progress.recv().await.unwrap().seq, 3); + assert!(h.reply(link, "req_a", Reply::Result(raw(r#"{"content":[]}"#)))); + assert!(matches!(call.reply.await, Ok(Reply::Result(r)) if r.get() == r#"{"content":[]}"#)); + assert!( + !h.reply(link, "req_a", Reply::Error("late".into())), + "finished" + ); + assert!(!h.cancel("req_a"), "finished"); + } + + #[tokio::test] + async fn cancel_revoke_and_token_revoke() { + let h = hub(); + let (link, token, other_token) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7()); + let (_, mut rx) = h.attach(link); + let _c = h.begin(link, token, "req_c", "{}".into()).unwrap(); + rx.recv().await.unwrap(); + assert!(h.cancel("req_c")); + assert!(matches!(rx.recv().await, Some(Down::Cancel(id)) if id == "req_c")); + + let t = h.begin(link, token, "req_t", "{}".into()).unwrap(); + let o = h.begin(link, other_token, "req_o", "{}".into()).unwrap(); + rx.recv().await.unwrap(); + rx.recv().await.unwrap(); + h.revoke_token(token); + assert!(matches!(t.reply.await, Ok(Reply::TokenRevoked))); + assert!(matches!(rx.recv().await, Some(Down::Cancel(id)) if id == "req_t")); + + h.revoke_link(link); + assert!(matches!(rx.recv().await, Some(Down::Revoked))); + assert!(matches!(o.reply.await, Ok(Reply::TurnedOff))); + assert!(!h.is_online(link)); + } + + #[test] + fn online_needs_a_recent_heartbeat() { + let h = Hub::new(3, Duration::from_millis(30)); + let link = Uuid::now_v7(); + let _stream = h.attach(link); + assert!(h.is_online(link)); + std::thread::sleep(Duration::from_millis(40)); + assert!(!h.is_online(link)); + assert!(h + .begin(link, Uuid::now_v7(), "req_x", "{}".into()) + .is_none()); + h.heard(link); + assert!(h.is_online(link)); + } + + #[test] + fn rate_limit_per_token() { + let h = hub(); + let (a, b) = (Uuid::now_v7(), Uuid::now_v7()); + assert!(h.allow(a) && h.allow(a) && h.allow(a)); + assert!(!h.allow(a)); + assert!(h.allow(b)); + } +} diff --git a/crates/core/src/device_agent/mcp.rs b/crates/core/src/device_agent/mcp.rs new file mode 100644 index 0000000..dfc7084 --- /dev/null +++ b/crates/core/src/device_agent/mcp.rs @@ -0,0 +1,775 @@ +//! The agent side: `GET /v1/agent/status` and `POST /v1/agent/mcp` — MCP Streamable HTTP, +//! stateless — authenticated by a `cat_` token instead of the instance gate. +//! +//! `tools/call` is relayed to the device: offline, turned off or an unknown tool answer at +//! once; otherwise a `request` frame goes down the device's stream and the reply comes back as +//! the JSON-RPC result. With `Accept: text/event-stream` the answer is an SSE stream (keepalive +//! comments, `notifications/progress` when the call carried a progress token, then the +//! response); otherwise one JSON response. A deadline miss, or the agent going away, sends the +//! device a `cancel`. + +use std::convert::Infallible; +use std::time::{Duration, Instant}; + +use axum::extract::{FromRequestParts, Request, State}; +use axum::http::header::{ACCEPT, AUTHORIZATION}; +use axum::http::request::Parts; +use axum::http::{header, HeaderMap, HeaderValue, StatusCode}; +use axum::response::sse::Event as SseEvent; +use axum::response::{IntoResponse, Response}; +use axum::Json; +use futures::{Stream, StreamExt as _}; +use serde::{Deserialize, Serialize}; +use serde_json::value::RawValue; +use serde_json::{json, Value}; +use time::OffsetDateTime; +use uuid::Uuid; + +use super::hub::{new_request_id, Call, Progress, Reply}; +use super::{plausible_agent_token, sse_response}; +use crate::error::{ApiError, ApiResult}; +use crate::extract::{check_content_length, read_body}; +use crate::ids; +use crate::state::SharedState; + +/// `POST /v1/agent/mcp` body cap. +pub const MCP_BODY_LIMIT: usize = 4 * 1024 * 1024; +/// MCP protocol versions answered as asked; anything else gets the first. +pub const PROTOCOL_VERSIONS: [&str; 3] = ["2025-06-18", "2025-03-26", "2024-11-05"]; +/// How often (at most) a waiting call checks that its device is still online; a quarter of the +/// offline grace when that is shorter. +const WATCH_EVERY: Duration = Duration::from_secs(1); + +/// What `initialize` tells the agent about driving the phone (after the Mac's MCP instructions). +pub const INSTRUCTIONS: &str = "This is the person's own Copper browser on their iPhone, \ +signed in as them; every call acts as the person in their signed-in tabs, on the tab they are \ +looking at. Nothing is sandboxed — act as they would. It only works while Copper is open on \ +their screen: when a call says Copper isn't open, ask them to open it and keep it on screen, \ +then try again. ANY task: the FIRST call is jev_run with the whole goal, every concrete \ +place/date/name/filter and a stop condition. jev_observe = fast indexed read; jev_extract = \ +JSON values. DONE is Jev's claim — verify it with jev_observe or jev_extract. When Jev is \ +BLOCKED, use browser_snapshot, browser_click and browser_type for that part, then jev_run \ +again. Without jev_* tools in tools/list, start with browser_snapshot. Calls run one at a \ +time and each is shown on the page with a Stop button."; + +// --------------------------------------------------------------------------------------------- +// Authentication + +/// The agent behind a valid `cat_` token, and the device it may drive. +pub(crate) struct AgentCaller { + pub token_id: Uuid, + pub user_id: Uuid, + pub device_id: Uuid, + pub label: String, + pub device_name: String, +} + +const TOKEN_SQL: &str = " +WITH t AS ( + SELECT t.id, t.user_id, t.device_id, t.label + FROM agent_tokens t + JOIN users u ON u.id = t.user_id + WHERE t.token_sha256 = $1 AND t.revoked_at IS NULL AND NOT u.disabled +), touch AS ( + UPDATE agent_tokens SET last_used_at = now() + WHERE id IN (SELECT id FROM t) + AND (last_used_at IS NULL OR last_used_at < now() - interval '60 seconds') +) +SELECT t.id, t.user_id, t.device_id, t.label, COALESCE(NULLIF(d.name, ''), 'Copper') AS device_name +FROM t JOIN devices d ON d.user_id = t.user_id AND d.id = t.device_id"; + +fn bad_token() -> ApiError { + ApiError::Unauthorized("agent_token") +} + +fn bearer(headers: &HeaderMap) -> Option<&str> { + let (scheme, token) = headers.get(AUTHORIZATION)?.to_str().ok()?.split_once(' ')?; + scheme.eq_ignore_ascii_case("bearer").then(|| token.trim()) +} + +impl FromRequestParts for AgentCaller { + type Rejection = ApiError; + + async fn from_request_parts( + parts: &mut Parts, + state: &SharedState, + ) -> Result { + let token = bearer(&parts.headers) + .filter(|t| plausible_agent_token(t)) + .ok_or_else(bad_token)?; + let row: Option<(Uuid, Uuid, Uuid, String, String)> = sqlx::query_as(TOKEN_SQL) + .bind(&ids::sha256(token.as_bytes())[..]) + .fetch_optional(&state.db) + .await?; + let Some((token_id, user_id, device_id, label, device_name)) = row else { + tracing::info!("agent request refused: unknown or revoked token"); + return Err(bad_token()); + }; + tracing::Span::current().record("user_id", tracing::field::display(user_id)); + if !state.device_agent.allow(token_id) { + metrics::counter!("agent_rate_limited_total").increment(1); + tracing::warn!(%token_id, "agent rate limit exceeded"); + return Err(ApiError::RateLimited); + } + Ok(Self { + token_id, + user_id, + device_id, + label, + device_name, + }) + } +} + +// --------------------------------------------------------------------------------------------- +// The device's link, as an agent sees it + +#[derive(sqlx::FromRow)] +struct LinkState { + id: Uuid, + label: String, + revoked: bool, + last_seen_at: Option, + tools: i64, + /// Whether the manifest has the tool asked about (`false` when none was). + has_tool: bool, +} + +async fn link_state( + db: &sqlx::PgPool, + caller: &AgentCaller, + tool: Option<&str>, +) -> ApiResult> { + Ok(sqlx::query_as::<_, LinkState>( + "SELECT id, label, revoked_at IS NOT NULL AS revoked, last_seen_at, + jsonb_array_length(tools)::bigint AS tools, + EXISTS (SELECT 1 FROM jsonb_array_elements(tools) e WHERE e->>'name' = $3) + AS has_tool + FROM device_links WHERE user_id = $1 AND device_id = $2", + ) + .bind(caller.user_id) + .bind(caller.device_id) + .bind(tool) + .fetch_optional(db) + .await?) +} + +fn no_store(mut resp: Response) -> Response { + resp.headers_mut() + .insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store")); + resp +} + +/// `GET /v1/agent/status`: the device this token drives and whether Copper is open on it. +pub(crate) async fn status( + State(state): State, + caller: AgentCaller, +) -> ApiResult { + let link = link_state(&state.db, &caller, None).await?; + let online = link + .as_ref() + .is_some_and(|l| !l.revoked && state.device_agent.is_online(l.id)); + let last_seen = link.as_ref().and_then(|l| l.last_seen_at).and_then(|t| { + t.format(&time::format_description::well_known::Rfc3339) + .ok() + }); + Ok(no_store( + Json(json!({ + "device": { "id": caller.device_id, "name": caller.device_name }, + "label": link.as_ref().map(|l| l.label.as_str()), + "online": online, + "last_seen_at": last_seen, + "tools": link.as_ref().map_or(0, |l| l.tools), + })) + .into_response(), + )) +} + +/// `GET` / `DELETE /v1/agent/mcp`: no server-initiated stream and no session. +pub(crate) async fn no_stream(_caller: AgentCaller) -> Response { + let mut resp = ApiError::coded( + StatusCode::METHOD_NOT_ALLOWED, + "method_not_allowed", + "no event stream and no session here: POST one JSON-RPC message per request", + ) + .into_response(); + resp.headers_mut() + .insert(header::ALLOW, HeaderValue::from_static("POST")); + resp +} + +// --------------------------------------------------------------------------------------------- +// JSON-RPC plumbing + +#[derive(Serialize)] +struct RpcResult<'a> { + jsonrpc: &'static str, + id: &'a Value, + result: &'a RawValue, +} + +fn rpc_result(id: &Value, result: &RawValue) -> String { + serde_json::to_string(&RpcResult { + jsonrpc: "2.0", + id, + result, + }) + .unwrap_or_default() +} + +fn rpc_value(id: &Value, result: &Value) -> String { + json!({ "jsonrpc": "2.0", "id": id, "result": result }).to_string() +} + +fn rpc_error(id: &Value, code: i64, message: &str) -> String { + json!({ "jsonrpc": "2.0", "id": id, "error": { "code": code, "message": message } }).to_string() +} + +fn json_answer(status: StatusCode, body: String) -> Response { + no_store( + ( + status, + [( + header::CONTENT_TYPE, + HeaderValue::from_static("application/json"), + )], + body, + ) + .into_response(), + ) +} + +/// `400` with a JSON-RPC error (no usable id): parse errors, batches, malformed messages. +fn rpc_rejected(code: i64, message: &str) -> Response { + json_answer( + StatusCode::BAD_REQUEST, + rpc_error(&Value::Null, code, message), + ) +} + +/// `202 Accepted`, empty body: notifications and responses from the client. +fn accepted() -> Response { + StatusCode::ACCEPTED.into_response() +} + +/// Whether the request's `Accept` names `text/event-stream`. +fn accepts_sse(headers: &HeaderMap) -> bool { + headers + .get_all(ACCEPT) + .iter() + .filter_map(|v| v.to_str().ok()) + .flat_map(|v| v.split(',')) + .any(|m| { + m.split(';') + .next() + .is_some_and(|t| t.trim().eq_ignore_ascii_case("text/event-stream")) + }) +} + +/// A `CallToolResult` with one text block and `isError: true`. +fn tool_error(text: &str) -> Box { + serde_json::value::to_raw_value(&json!({ + "content": [{ "type": "text", "text": text }], + "isError": true, + })) + .expect("serializable") +} + +/// Whether a device's result says `isError: true` (for the log line only). +fn is_error_result(result: &RawValue) -> bool { + #[derive(Deserialize)] + struct Flag { + #[serde(rename = "isError", default)] + is_error: bool, + } + serde_json::from_str::(result.get()).is_ok_and(|f| f.is_error) +} + +/// One SSE `data:` line: a reply may carry pretty-printed JSON, which is compacted so that +/// line-oriented clients see the whole message in a single `data:` field. +fn single_line(body: String) -> String { + if body.contains(['\n', '\r']) { + serde_json::from_str::(&body).map_or(body, |v| v.to_string()) + } else { + body + } +} + +fn message_event(body: String) -> SseEvent { + SseEvent::default().event("message").data(single_line(body)) +} + +// --------------------------------------------------------------------------------------------- +// `POST /v1/agent/mcp` + +/// The MCP endpoint. One JSON-RPC 2.0 message per request (batches: `400`); no session. +pub(crate) async fn mcp( + State(state): State, + caller: AgentCaller, + req: Request, +) -> Response { + let wants_sse = accepts_sse(req.headers()); + if let Err(err) = check_content_length(&req, MCP_BODY_LIMIT) { + return err.into_response(); + } + let bytes = match read_body(req.into_body(), MCP_BODY_LIMIT).await { + Ok(bytes) => bytes, + Err(err) => return err.into_response(), + }; + let Ok(message) = serde_json::from_slice::(&bytes) else { + return rpc_rejected( + -32700, + "parse error: the body must be one JSON-RPC 2.0 message", + ); + }; + drop(bytes); + let mut message = match message { + Value::Object(map) => map, + Value::Array(_) => { + return rpc_rejected( + -32600, + "batches are not supported: send one JSON-RPC message per request", + ) + } + _ => return rpc_rejected(-32600, "invalid request: expected a JSON-RPC 2.0 object"), + }; + let Some(method) = message + .get("method") + .and_then(Value::as_str) + .map(str::to_owned) + else { + // A response from the client (we never send requests): nothing to do. + if message.contains_key("result") || message.contains_key("error") { + return accepted(); + } + return rpc_rejected(-32600, "invalid request: method is required"); + }; + if method.starts_with("notifications/") { + return accepted(); + } + let Some(id) = message.remove("id") else { + // Any other notification: nothing to answer. + return accepted(); + }; + let params = message.remove("params"); + match method.as_str() { + "initialize" => json_answer(StatusCode::OK, rpc_value(&id, &initialize(params.as_ref()))), + "ping" => json_answer(StatusCode::OK, rpc_value(&id, &json!({}))), + "tools/list" => match tools_list(&state, &caller).await { + Ok(tools) => json_answer(StatusCode::OK, rpc_value(&id, &json!({ "tools": tools }))), + Err(err) => err.into_response(), + }, + "tools/call" => tools_call(state, caller, id, params, wants_sse).await, + _ => json_answer( + StatusCode::OK, + rpc_error(&id, -32601, &format!("method not found: {method}")), + ), + } +} + +fn initialize(params: Option<&Value>) -> Value { + let asked = params + .and_then(|p| p.get("protocolVersion")) + .and_then(Value::as_str) + .unwrap_or_default(); + let version = PROTOCOL_VERSIONS + .iter() + .find(|v| **v == asked) + .unwrap_or(&PROTOCOL_VERSIONS[0]); + json!({ + "protocolVersion": version, + "capabilities": { "tools": { "listChanged": false } }, + "serverInfo": { "name": "copper-mobile", "version": env!("CARGO_PKG_VERSION") }, + "instructions": INSTRUCTIONS, + }) +} + +/// The manifest the device last registered (empty if none). +async fn tools_list(state: &SharedState, caller: &AgentCaller) -> ApiResult { + let tools: Option> = + sqlx::query_scalar("SELECT tools FROM device_links WHERE user_id = $1 AND device_id = $2") + .bind(caller.user_id) + .bind(caller.device_id) + .fetch_optional(&state.db) + .await?; + Ok(tools.map_or_else(|| json!([]), |t| t.0)) +} + +// --------------------------------------------------------------------------------------------- +// `tools/call` + +/// The one log line per agent call (never arguments or results) + `device_agent_calls_total`. +struct Audit { + token_id: Uuid, + device_id: Uuid, + tool: String, + started: Instant, + span: tracing::Span, +} + +impl Audit { + fn log(&self, status: &'static str) { + let ms = u64::try_from(self.started.elapsed().as_millis()).unwrap_or(u64::MAX); + metrics::counter!("device_agent_calls_total", "status" => status).increment(1); + self.span.in_scope(|| { + tracing::info!( + token_id = %self.token_id, + device_id = %self.device_id, + tool = %self.tool, + ms, + status, + "agent call" + ); + }); + } +} + +/// A tool name fit for the log: at most 64 characters, no control characters. +fn loggable_tool(name: &str) -> String { + name.chars() + .take(64) + .map(|c| if c.is_control() { ' ' } else { c }) + .collect() +} + +/// Cancels the call on the device (and logs it) if the agent goes away before it finished: +/// dropped with the handler future (JSON answer) or the response body (SSE answer). +struct CallGuard { + state: SharedState, + request_id: String, + audit: Option, +} + +impl CallGuard { + fn finish(&mut self, status: &'static str) { + if let Some(audit) = self.audit.take() { + audit.log(status); + } + } +} + +impl Drop for CallGuard { + fn drop(&mut self) { + if let Some(audit) = self.audit.take() { + self.state.device_agent.cancel(&self.request_id); + audit.log("cancelled"); + } + } +} + +fn offline_text(device: &str) -> String { + format!( + "Copper isn't open on {device}. Ask the person to open Copper on their iPhone and keep it \ + on screen (Settings › Agents › Let agents use this iPhone must be on), then try again." + ) +} + +fn turned_off_text(device: &str) -> String { + format!( + "Agents are turned off on {device}. Ask the person to turn on Settings › Agents › Let \ + agents use this iPhone in Copper, then try again." + ) +} + +fn unknown_tool_text(tool: &str, device: &str) -> String { + format!( + "Copper on {device} has no tool named \"{tool}\". Call tools/list for the tools it offers." + ) +} + +struct RelayInfo { + id: Value, + tool: String, + device_name: String, + link: Uuid, + progress_token: Option, +} + +enum CallEvent { + Progress(String), + Done(String), +} + +fn progress_notification(token: &Value, p: &Progress) -> String { + json!({ + "jsonrpc": "2.0", + "method": "notifications/progress", + "params": { "progressToken": token, "progress": p.seq, "message": p.message }, + }) + .to_string() +} + +/// How a device reply (or the hub) ended the call: the result for the agent and the log status. +fn outcome( + reply: Result, + info: &RelayInfo, +) -> (Box, &'static str) { + let (tool, device) = (&info.tool, &info.device_name); + match reply { + Ok(Reply::Result(result)) => { + let status = if is_error_result(&result) { + "tool_error" + } else { + "ok" + }; + (result, status) + } + Ok(Reply::Error(message)) => (tool_error(&message), "error"), + Ok(Reply::TurnedOff) => ( + tool_error(&format!( + "Agents were turned off on {device} while {tool} was running; the call was stopped." + )), + "revoked", + ), + Ok(Reply::TokenRevoked) => ( + tool_error(&format!( + "This agent's access to {device} was revoked while {tool} was running; the call was stopped." + )), + "token_revoked", + ), + Err(_) => ( + tool_error(&format!("{tool} ended on {device} without a reply.")), + "error", + ), + } +} + +/// Wait for the device: progress events while it works, then exactly one `Done` with the +/// JSON-RPC response. The guard travels inside, so dropping the stream cancels the call. +// `state` and `info` are moved into the stream; clippy cannot see through `stream!`. +#[allow(clippy::needless_pass_by_value)] +fn relay( + state: SharedState, + call: Call, + mut guard: CallGuard, + info: RelayInfo, +) -> impl Stream { + let tuning = state.cfg.device_agent.clone(); + let mut shutdown = crate::shutdown::subscribe(); + async_stream::stream! { + let Call { mut reply, mut progress } = call; + let deadline = tokio::time::sleep(tuning.relay_deadline); + tokio::pin!(deadline); + let mut watch = tokio::time::interval( + WATCH_EVERY.min(tuning.offline_grace / 4).max(Duration::from_millis(10)), + ); + watch.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay); + let mut offline_since: Option = None; + let mut progress_open = true; + let (result, status) = loop { + tokio::select! { + // The deadline and shutdown first (a flood of progress cannot hold them off), + // then progress before the reply, so frames uploaded just before it still go + // out. + biased; + () = &mut deadline => { + state.device_agent.cancel(&guard.request_id); + let text = format!( + "{} timed out: {} did not answer within {} s, so the call was cancelled. \ + Try again, or ask the person to check Copper on their iPhone.", + info.tool, info.device_name, tuning.relay_deadline.as_secs_f64().ceil() + ); + break (tool_error(&text), "timeout"); + } + () = crate::shutdown::wait(&mut shutdown) => { + state.device_agent.cancel(&guard.request_id); + let text = format!( + "Copper Cloud is restarting, so {} was stopped. Try again in a moment.", + info.tool + ); + break (tool_error(&text), "shutdown"); + } + p = progress.recv(), if progress_open => match p { + Some(p) => { + if let Some(token) = &info.progress_token { + yield CallEvent::Progress(progress_notification(token, &p)); + } + } + None => progress_open = false, + }, + r = &mut reply => break outcome(r, &info), + _ = watch.tick() => { + if state.device_agent.is_online(info.link) { + offline_since = None; + } else if offline_since.get_or_insert_with(Instant::now).elapsed() + >= tuning.offline_grace + { + state.device_agent.cancel(&guard.request_id); + let text = format!( + "Copper closed on {} before {} finished (it is no longer open on \ + their screen). Ask the person to open Copper again, then try again.", + info.device_name, info.tool + ); + break (tool_error(&text), "gone_offline"); + } + } + } + }; + guard.finish(status); + yield CallEvent::Done(rpc_result(&info.id, &result)); + } +} + +/// An answer that needs no device: one JSON-RPC response (as SSE when the agent asked for it). +fn answer_now(id: &Value, result: &RawValue, wants_sse: bool) -> Response { + let body = rpc_result(id, result); + if wants_sse { + sse_response( + futures::stream::once(async move { Ok::<_, Infallible>(message_event(body)) }), + None, + ) + } else { + json_answer(StatusCode::OK, body) + } +} + +async fn tools_call( + state: SharedState, + caller: AgentCaller, + id: Value, + params: Option, + wants_sse: bool, +) -> Response { + let params = params.as_ref().and_then(Value::as_object); + let Some(name) = params.and_then(|p| p.get("name")).and_then(Value::as_str) else { + return json_answer( + StatusCode::OK, + rpc_error( + &id, + -32602, + "invalid params: name (the tool to call) is required", + ), + ); + }; + let arguments = match params.and_then(|p| p.get("arguments")) { + None | Some(Value::Null) => json!({}), + Some(args @ Value::Object(_)) => args.clone(), + Some(_) => { + return json_answer( + StatusCode::OK, + rpc_error(&id, -32602, "invalid params: arguments must be an object"), + ) + } + }; + let progress_token = params + .and_then(|p| p.get("_meta")) + .and_then(|m| m.get("progressToken")) + .filter(|t| t.is_string() || t.is_number()) + .cloned(); + let audit = Audit { + token_id: caller.token_id, + device_id: caller.device_id, + tool: loggable_tool(name), + started: Instant::now(), + span: tracing::Span::current(), + }; + let device = caller.device_name.as_str(); + let link = match link_state(&state.db, &caller, Some(name)).await { + Ok(link) => link, + Err(err) => return err.into_response(), + }; + let Some(link) = link.filter(|l| !l.revoked) else { + audit.log("turned_off"); + return answer_now(&id, &tool_error(&turned_off_text(device)), wants_sse); + }; + if !link.has_tool { + audit.log("unknown_tool"); + return answer_now( + &id, + &tool_error(&unknown_tool_text(name, device)), + wants_sse, + ); + } + let tuning = &state.cfg.device_agent; + let request_id = new_request_id(); + let frame = json!({ + "id": request_id, + "method": "tools/call", + "params": { "name": name, "arguments": arguments }, + "caller": { "token_id": caller.token_id, "label": caller.label }, + "deadline_ms": u64::try_from(tuning.relay_deadline.as_millis()).unwrap_or(u64::MAX), + }) + .to_string(); + let Some(call) = state + .device_agent + .begin(link.id, caller.token_id, &request_id, frame) + else { + audit.log("offline"); + return answer_now(&id, &tool_error(&offline_text(device)), wants_sse); + }; + let keepalive = tuning.agent_keepalive; + let info = RelayInfo { + id, + tool: name.to_owned(), + device_name: caller.device_name.clone(), + link: link.id, + progress_token, + }; + let guard = CallGuard { + state: state.clone(), + request_id, + audit: Some(audit), + }; + let events = relay(state, call, guard, info); + if wants_sse { + let stream = events.map(|ev| match ev { + CallEvent::Progress(body) | CallEvent::Done(body) => { + Ok::<_, Infallible>(message_event(body)) + } + }); + return sse_response(stream, Some(keepalive)); + } + let mut events = std::pin::pin!(events); + while let Some(ev) = events.next().await { + if let CallEvent::Done(body) = ev { + return json_answer(StatusCode::OK, body); + } + } + ApiError::internal("relay ended without an answer").into_response() +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn accept_header() { + let h = |v: &str| { + let mut m = HeaderMap::new(); + m.insert(ACCEPT, HeaderValue::from_str(v).unwrap()); + m + }; + assert!(accepts_sse(&h("application/json, text/event-stream"))); + assert!(accepts_sse(&h("Text/Event-Stream;q=0.9"))); + assert!(!accepts_sse(&h("application/json"))); + assert!(!accepts_sse(&h("*/*"))); + assert!(!accepts_sse(&HeaderMap::new())); + } + + #[test] + fn protocol_negotiation() { + let v = |asked: Value| { + initialize(Some(&json!({ "protocolVersion": asked })))["protocolVersion"].clone() + }; + assert_eq!(v(json!("2025-03-26")), "2025-03-26"); + assert_eq!(v(json!("2024-11-05")), "2024-11-05"); + assert_eq!(v(json!("1999-01-01")), "2025-06-18"); + assert_eq!(v(json!(7)), "2025-06-18"); + assert_eq!(initialize(None)["serverInfo"]["name"], "copper-mobile"); + } + + #[test] + fn results_and_lines() { + let err = tool_error("nope"); + assert!(is_error_result(&err)); + let ok = RawValue::from_string(r#"{"content":[],"isError":false}"#.into()).unwrap(); + assert!(!is_error_result(&ok)); + assert_eq!( + rpc_result(&json!(7), &ok), + r#"{"jsonrpc":"2.0","id":7,"result":{"content":[],"isError":false}}"# + ); + assert_eq!(single_line("{\n \"a\": 1\n}".into()), r#"{"a":1}"#); + assert_eq!(loggable_tool("a\nb"), "a b"); + assert_eq!(loggable_tool(&"x".repeat(100)).len(), 64); + } +} diff --git a/crates/core/src/device_agent/mod.rs b/crates/core/src/device_agent/mod.rs new file mode 100644 index 0000000..ae40e27 --- /dev/null +++ b/crates/core/src/device_agent/mod.rs @@ -0,0 +1,890 @@ +//! Device agent relay: an agent (any MCP client) calls the tools of a person's Copper for iOS +//! through the cloud. Nothing listens on the phone: it dials out and holds an event stream while +//! Copper is on screen, and the cloud hands it each call. +//! +//! ```text +//! agent ── POST /v1/agent/mcp (cat_ token) ──▶ copper-cloud ── SSE "request" ──▶ device +//! agent ◀── JSON-RPC result (JSON or SSE) ─── copper-cloud ◀── POST frames "reply" ── device +//! ``` +//! +//! * **Device side** (gate + session, like every `/v1` user route): `POST/GET /v1/me/links`, +//! `GET/DELETE /v1/me/links/{id}`, the SSE mailbox `GET /v1/me/links/{id}/frames` and its +//! upload `POST /v1/me/links/{id}/frames` (body up to [`FRAMES_BODY_LIMIT`]), and agent tokens +//! `POST/GET /v1/me/agent-tokens`, `DELETE /v1/me/agent-tokens/{id}`. One link per +//! (user, device); only the link's own device may open or feed its stream. +//! * **Agent side** (ungated, see [`is_agent_path`]): `Authorization: Bearer cat_…` — `cat_` + 32 +//! random bytes base64url, only SHA-256 stored — on `GET /v1/agent/status` and +//! `POST /v1/agent/mcp` (MCP Streamable HTTP, stateless; [`mcp`]). 600 requests/minute per +//! token. +//! * Which link is online and the calls in flight live in the in-memory [`Hub`] (one daemon per +//! instance); links and tokens persist (`0016_device_agent.sql`). +//! * Logs: one line per agent call (token id, device id, tool, ms, status), never arguments or +//! results. Token mints/revokes and link registrations/revokes are logged (like pairing codes, +//! these user actions are not in the admin audit log). + +pub mod hub; +pub(crate) mod mcp; + +use std::collections::HashSet; +use std::convert::Infallible; +use std::time::Duration; + +use axum::extract::{Path, Request, State}; +use axum::http::{header, HeaderName, HeaderValue, StatusCode}; +use axum::response::sse::{Event as SseEvent, KeepAlive, Sse}; +use axum::response::{IntoResponse, Response}; +use axum::routing::{delete, get, post}; +use axum::{Json, Router}; +use futures::Stream; +use serde::{Deserialize, Serialize}; +use serde_json::value::RawValue; +use serde_json::{json, Value}; +use time::OffsetDateTime; +use tokio::sync::mpsc; +use uuid::Uuid; + +pub use hub::Hub; +use hub::{Down, Reply}; + +use crate::auth::{self, AuthUser}; +use crate::config::{Config, TlsMode}; +use crate::error::{ApiError, ApiResult}; +use crate::extract::{check_content_length, read_body, JsonBody, OptionalJsonBody}; +use crate::ids; +use crate::state::SharedState; + +/// Prefix of every agent token. +pub const AGENT_TOKEN_PREFIX: &str = "cat_"; +/// The agent-side routes, outside the instance gate. +pub const AGENT_PATH: &str = "/v1/agent"; +/// The MCP endpoint (built into `mcp_url`). +pub const MCP_PATH: &str = "/v1/agent/mcp"; +/// `POST /v1/me/links/{id}/frames` body cap (replies may carry screenshots). +pub const FRAMES_BODY_LIMIT: usize = 32 * 1024 * 1024; +/// Most tools in a manifest. +pub const MAX_TOOLS: usize = 100; +/// Largest manifest (compact JSON). +pub const MAX_MANIFEST_BYTES: usize = 256 * 1024; +/// Longest progress message forwarded (longer ones are cut). +pub const MAX_PROGRESS_BYTES: usize = 16 * 1024; +/// Most live agent tokens one user may hold. +pub const MAX_ACTIVE_TOKENS: i64 = 100; +/// Frames protocol version announced in `hello`. +pub const FRAMES_PROTOCOL: u32 = 1; +const MAX_LABEL_CHARS: usize = 100; +const MAX_TOOL_NAME_CHARS: usize = 128; +/// `POST /v1/me/links` body cap: room for a too-big manifest to get a clear 400. +const LINK_BODY_LIMIT: usize = 1024 * 1024; +const TOKEN_BODY_LIMIT: usize = 16 * 1024; + +/// Whether `path` is an agent-side route (`/v1/agent`, `/v1/agent/…`), which carries its own +/// credential instead of the gate header. `/v1/agents/…` is not. +pub fn is_agent_path(path: &str) -> bool { + path.strip_prefix(AGENT_PATH) + .is_some_and(|rest| rest.is_empty() || rest.starts_with('/')) +} + +/// A fresh agent token: `cat_` + 43 base64url chars (32 random bytes). +pub fn new_agent_token() -> String { + format!("{AGENT_TOKEN_PREFIX}{}", ids::random_token()) +} + +/// Shape check before touching the database. +pub fn plausible_agent_token(s: &str) -> bool { + s.strip_prefix(AGENT_TOKEN_PREFIX) + .is_some_and(ids::is_token_shape) +} + +/// `https://HOST[:PORT]/v1/agent/mcp` for agents: the ACME domain when there is one (agents +/// need a publicly trusted certificate), else `public_url`. +pub fn mcp_url(cfg: &Config) -> String { + let host = match (&cfg.tls.domain, cfg.tls.mode) { + (Some(domain), TlsMode::Acme) => domain.clone(), + _ => cfg.public_host().to_owned(), + }; + crate::link::LinkCode { + host, + port: cfg.public_port(), + instance_key: String::new(), + fingerprint: None, + } + .https_url(MCP_PATH) +} + +pub(crate) fn routes() -> Router { + Router::new() + .route("/me/links", get(list_links).post(register_link)) + .route("/me/links/{id}", get(get_link).delete(revoke_link)) + .route("/me/links/{id}/frames", get(open_frames).post(post_frames)) + .route("/me/agent-tokens", get(list_tokens).post(mint_token)) + .route("/me/agent-tokens/{id}", delete(revoke_token)) + .route("/agent/status", get(mcp::status)) + .route( + "/agent/mcp", + post(mcp::mcp).get(mcp::no_stream).delete(mcp::no_stream), + ) +} + +/// An SSE response with the relay's headers: `Cache-Control: no-store` and +/// `X-Accel-Buffering: no` (so a proxy passes each event through at once). +pub(crate) fn sse_response(stream: S, keepalive: Option) -> Response +where + S: Stream> + Send + 'static, +{ + let sse = Sse::new(stream); + let mut resp = match keepalive { + Some(every) => sse + .keep_alive(KeepAlive::new().interval(every).text("keepalive")) + .into_response(), + None => sse.into_response(), + }; + let headers = resp.headers_mut(); + headers.insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store")); + headers.insert( + HeaderName::from_static("x-accel-buffering"), + HeaderValue::from_static("no"), + ); + resp +} + +// --------------------------------------------------------------------------------------------- +// Links + +#[derive(sqlx::FromRow)] +struct LinkRow { + id: Uuid, + device_id: Uuid, + device_name: String, + label: String, + revoked: bool, + created_at: OffsetDateTime, + last_seen_at: Option, + tools: i64, +} + +/// The link object every link route returns (and `hello` carries). +#[derive(Debug, Serialize)] +pub struct LinkView { + pub id: Uuid, + pub device_id: Uuid, + pub device_name: String, + pub label: String, + pub online: bool, + pub revoked: bool, + #[serde(with = "time::serde::rfc3339")] + pub created_at: OffsetDateTime, + #[serde(with = "time::serde::rfc3339::option")] + pub last_seen_at: Option, + /// How many tools the registered manifest has. + pub tools: i64, +} + +const LINK_SQL: &str = + "SELECT l.id, l.device_id, COALESCE(NULLIF(d.name, ''), l.label) AS device_name, + l.label, l.revoked_at IS NOT NULL AS revoked, l.created_at, l.last_seen_at, + jsonb_array_length(l.tools)::bigint AS tools +FROM device_links l +LEFT JOIN devices d ON d.user_id = l.user_id AND d.id = l.device_id"; + +impl LinkRow { + fn view(self, state: &SharedState) -> LinkView { + let online = !self.revoked && state.device_agent.is_online(self.id); + LinkView { + id: self.id, + device_id: self.device_id, + device_name: self.device_name, + label: self.label, + online, + revoked: self.revoked, + created_at: self.created_at, + last_seen_at: self.last_seen_at, + tools: self.tools, + } + } +} + +async fn load_link(state: &SharedState, user_id: Uuid, id: Uuid) -> ApiResult> { + Ok( + sqlx::query_as::<_, LinkRow>(&format!("{LINK_SQL} WHERE l.user_id = $1 AND l.id = $2")) + .bind(user_id) + .bind(id) + .fetch_optional(&state.db) + .await?, + ) +} + +/// The caller's link `id`, which must be this device's own (`404` for another user's link, +/// `403` for another device's). +async fn own_link(state: &SharedState, user: &AuthUser, id: Uuid) -> ApiResult { + let row = load_link(state, user.user_id, id) + .await? + .ok_or(ApiError::NotFound)?; + if row.device_id != user.device_id { + return Err(ApiError::Forbidden); + } + Ok(row) +} + +#[derive(Deserialize)] +struct RegisterRequest { + #[serde(default)] + label: Option, + #[serde(default)] + client_version: Option, + #[serde(default)] + tools: Option, +} + +/// A tool manifest as registered: a JSON array of ≤ [`MAX_TOOLS`] objects, each with a unique, +/// non-empty `name`, ≤ [`MAX_MANIFEST_BYTES`] as compact JSON. +pub fn validate_manifest(tools: &Value) -> ApiResult<()> { + let Value::Array(items) = tools else { + return Err(ApiError::bad_request( + "tools must be an array of tool objects ({name, description, inputSchema})", + )); + }; + if items.len() > MAX_TOOLS { + return Err(ApiError::bad_request(format!( + "too many tools ({}); at most {MAX_TOOLS}", + items.len() + ))); + } + let mut names = HashSet::with_capacity(items.len()); + for (i, tool) in items.iter().enumerate() { + let name = tool + .as_object() + .and_then(|o| o.get("name")) + .and_then(Value::as_str) + .filter(|n| !n.trim().is_empty() && n.chars().count() <= MAX_TOOL_NAME_CHARS) + .ok_or_else(|| { + ApiError::bad_request(format!( + "tools[{i}] must be an object with a non-empty name \ + (at most {MAX_TOOL_NAME_CHARS} characters)" + )) + })?; + if !names.insert(name) { + return Err(ApiError::bad_request(format!( + "tools[{i}]: duplicate tool name \"{name}\"" + ))); + } + } + let bytes = serde_json::to_vec(tools) + .map_err(anyhow::Error::from)? + .len(); + if bytes > MAX_MANIFEST_BYTES { + return Err(ApiError::bad_request(format!( + "the tool manifest is {bytes} bytes; at most {MAX_MANIFEST_BYTES} (256 KiB)" + ))); + } + Ok(()) +} + +/// `POST /v1/me/links`: register (or update) this device's link. Idempotent per device: same +/// id every time, a revoked link comes back un-revoked. Omitted fields keep their stored value +/// (a new link: label = the device name, no tools). +async fn register_link( + State(state): State, + user: AuthUser, + JsonBody(req): JsonBody, +) -> ApiResult> { + if let Some(tools) = &req.tools { + validate_manifest(tools)?; + } + let label = auth::clean_name(req.label.as_deref(), MAX_LABEL_CHARS); + let client_version = auth::clean_name(req.client_version.as_deref(), 64); + let (id, inserted): (Uuid, bool) = sqlx::query_as( + "INSERT INTO device_links (id, user_id, device_id, label, client_version, tools) + VALUES ($1, $2, $3, + COALESCE($4, (SELECT NULLIF(name, '') FROM devices WHERE user_id = $2 AND id = $3), + 'Copper'), + $5, COALESCE($6, '[]'::jsonb)) + ON CONFLICT (user_id, device_id) DO UPDATE SET + label = COALESCE($4, device_links.label), + client_version = COALESCE($5, device_links.client_version), + tools = COALESCE($6, device_links.tools), + revoked_at = NULL + RETURNING id, (xmax = 0) AS inserted", + ) + .bind(ids::uuid_v7()) + .bind(user.user_id) + .bind(user.device_id) + .bind(label) + .bind(client_version) + .bind(req.tools.map(sqlx::types::Json)) + .fetch_one(&state.db) + .await?; + let row = load_link(&state, user.user_id, id) + .await? + .ok_or(ApiError::NotFound)?; + tracing::info!( + user_id = %user.user_id, + device_id = %user.device_id, + link_id = %id, + tools = row.tools, + inserted, + "device link registered" + ); + Ok(Json(row.view(&state))) +} + +/// `GET /v1/me/links`: the caller's live (not revoked) links, oldest first. +async fn list_links( + State(state): State, + user: AuthUser, +) -> ApiResult>> { + let rows = sqlx::query_as::<_, LinkRow>(&format!( + "{LINK_SQL} WHERE l.user_id = $1 AND l.revoked_at IS NULL ORDER BY l.created_at, l.id" + )) + .bind(user.user_id) + .fetch_all(&state.db) + .await?; + Ok(Json(rows.into_iter().map(|r| r.view(&state)).collect())) +} + +/// `GET /v1/me/links/{id}` (revoked included). +async fn get_link( + State(state): State, + user: AuthUser, + Path(id): Path, +) -> ApiResult> { + let row = load_link(&state, user.user_id, id) + .await? + .ok_or(ApiError::NotFound)?; + Ok(Json(row.view(&state))) +} + +/// `DELETE /v1/me/links/{id}`: turn the link off (any of the user's devices may). Closes its +/// stream with `revoked` and fails its calls in flight; agent calls answer "turned off" until +/// the device registers again. Idempotent. +async fn revoke_link( + State(state): State, + user: AuthUser, + Path(id): Path, +) -> ApiResult> { + let revoked: Option = sqlx::query_scalar( + "UPDATE device_links SET revoked_at = COALESCE(revoked_at, now()) + WHERE user_id = $1 AND id = $2 RETURNING id", + ) + .bind(user.user_id) + .bind(id) + .fetch_optional(&state.db) + .await?; + if revoked.is_none() { + return Err(ApiError::NotFound); + } + state.device_agent.revoke_link(id); + tracing::info!(user_id = %user.user_id, link_id = %id, by_device = %user.device_id, "device link revoked"); + Ok(Json(json!({ "ok": true }))) +} + +// --------------------------------------------------------------------------------------------- +// Frames: the device's SSE mailbox and its uploads + +/// Detaches the stream from the hub when the response body is dropped (client gone, superseded, +/// revoked, shutdown) and records when the device was last seen. +struct StreamGuard { + state: SharedState, + link: Uuid, + stream: u64, +} + +impl StreamGuard { + fn new(state: SharedState, link: Uuid, stream: u64) -> Self { + metrics::gauge!("device_agent_streams").increment(1.0); + Self { + state, + link, + stream, + } + } +} + +impl Drop for StreamGuard { + fn drop(&mut self) { + metrics::gauge!("device_agent_streams").decrement(1.0); + if !self.state.device_agent.detach(self.link, self.stream) { + return; + } + tracing::info!(link_id = %self.link, "device frames stream closed"); + if let Ok(rt) = tokio::runtime::Handle::try_current() { + let db = self.state.db.clone(); + let link = self.link; + rt.spawn(async move { + let _ = sqlx::query("UPDATE device_links SET last_seen_at = now() WHERE id = $1") + .bind(link) + .execute(&db) + .await; + }); + } + } +} + +fn sse_event(name: &str, data: impl AsRef) -> SseEvent { + SseEvent::default().event(name).data(data) +} + +// `state` is moved into the stream; clippy cannot see through `stream!`. +#[allow(clippy::needless_pass_by_value)] +fn frames_stream( + state: SharedState, + session_id: Uuid, + hello: String, + attached: Option<(StreamGuard, mpsc::UnboundedReceiver)>, +) -> impl Stream> { + let ping_every = state.cfg.device_agent.device_ping; + let mut shutdown = crate::shutdown::subscribe(); + async_stream::stream! { + yield Ok(sse_event("hello", hello)); + let Some((_guard, mut rx)) = attached else { + // A revoked link: say so, then close (the device registers again to turn it on). + yield Ok(sse_event("revoked", "{}")); + return; + }; + let start = tokio::time::Instant::now(); + let mut ping = tokio::time::interval_at(start + ping_every, ping_every); + let revalidate_every = crate::sync::SSE_REVALIDATE; + let mut revalidate = tokio::time::interval_at(start + revalidate_every, revalidate_every); + loop { + tokio::select! { + down = rx.recv() => match down { + Some(Down::Request(frame)) => { + yield Ok(sse_event("request", frame)); + } + Some(Down::Cancel(id)) => { + yield Ok(sse_event("cancel", json!({ "id": id }).to_string())); + } + Some(Down::Superseded) => { + yield Ok(sse_event("superseded", "{}")); + break; + } + Some(Down::Revoked) => { + yield Ok(sse_event("revoked", "{}")); + break; + } + None => break, + }, + _ = ping.tick() => { + yield Ok(sse_event("ping", "{}")); + } + _ = revalidate.tick() => { + if !crate::sync::session_alive(&state.db, session_id).await { + break; + } + } + () = crate::shutdown::wait(&mut shutdown) => break, + } + } + } +} + +/// `GET /v1/me/links/{id}/frames`: the device's mailbox. Only the link's own device may open it. +/// A new stream supersedes the previous one; a revoked link gets `hello` then `revoked`. +async fn open_frames( + State(state): State, + user: AuthUser, + Path(id): Path, +) -> ApiResult { + let mut row = own_link(&state, &user, id).await?; + let attached = if row.revoked { + None + } else { + let (stream, rx) = state.device_agent.attach(id); + let guard = StreamGuard::new(state.clone(), id, stream); + // Re-checked after attaching: a revoke that committed since `own_link` found no stream + // to close, so this one must not stay attached. + let live = sqlx::query( + "UPDATE device_links SET last_seen_at = now() WHERE id = $1 AND revoked_at IS NULL", + ) + .bind(id) + .execute(&state.db) + .await? + .rows_affected() + > 0; + if live { + tracing::info!(user_id = %user.user_id, link_id = %id, stream, "device frames stream opened"); + Some((guard, rx)) + } else { + row.revoked = true; + None + } + }; + let mut view = row.view(&state); + if attached.is_some() { + view.last_seen_at = Some(OffsetDateTime::now_utc()); + } + let hello = json!({ "link": view, "protocol": FRAMES_PROTOCOL }).to_string(); + Ok(sse_response( + frames_stream(state, user.session_id, hello, attached), + None, + )) +} + +#[derive(Deserialize)] +struct FramesBody { + frames: Vec>, +} + +#[derive(Deserialize)] +struct FrameIn { + #[serde(rename = "type")] + kind: String, + #[serde(default)] + id: Option, + #[serde(default)] + result: Option>, + #[serde(default)] + error: Option, + #[serde(default)] + seq: Option, + #[serde(default)] + message: Option, + #[serde(default)] + level: Option, +} + +#[derive(Deserialize)] +struct FrameError { + #[serde(default)] + code: Option, + #[serde(default)] + message: Option, +} + +/// `s` cut to at most `max` bytes on a character boundary. +fn truncate_utf8(mut s: String, max: usize) -> String { + if s.len() > max { + let mut end = max; + while !s.is_char_boundary(end) { + end -= 1; + } + s.truncate(end); + } + s +} + +/// Apply one uploaded frame; `false` if it is malformed or of an unknown type (skipped). +fn handle_frame(state: &SharedState, link: Uuid, raw: &RawValue) -> bool { + let Ok(frame) = serde_json::from_str::(raw.get()) else { + return false; + }; + let hub = &state.device_agent; + match frame.kind.as_str() { + "reply" => { + let Some(id) = frame.id else { return false }; + let reply = match (frame.result, frame.error) { + (Some(result), _) => Reply::Result(result), + (None, Some(err)) => Reply::Error( + err.message + .filter(|m| !m.trim().is_empty()) + .or_else(|| err.code.map(|c| format!("Copper reported an error ({c})"))) + .unwrap_or_else(|| "Copper reported an error".to_owned()), + ), + (None, None) => Reply::Error("Copper sent an empty reply".to_owned()), + }; + hub.reply(link, &id, reply); + true + } + "progress" => { + let Some(id) = frame.id else { return false }; + let message = truncate_utf8(frame.message.unwrap_or_default(), MAX_PROGRESS_BYTES); + hub.progress(link, &id, frame.seq, message); + true + } + // Every frames POST counts as being heard from (see `post_frames`). + "heartbeat" => true, + "log" => { + tracing::debug!( + link_id = %link, + level = frame.level.as_deref().unwrap_or("info"), + message = frame.message.as_deref().unwrap_or_default(), + "device log" + ); + true + } + _ => false, + } +} + +/// `POST /v1/me/links/{id}/frames`: `{"frames": [...]}` from the link's own device (replies, +/// progress, heartbeats, logs). `200 {"ok": true, "accepted": n}` — `n` well-formed frames of +/// a known type (a reply for an unknown or finished request is still accepted, and ignored). +async fn post_frames( + State(state): State, + user: AuthUser, + Path(id): Path, + req: Request, +) -> ApiResult> { + check_content_length(&req, FRAMES_BODY_LIMIT)?; + own_link(&state, &user, id).await?; + let bytes = read_body(req.into_body(), FRAMES_BODY_LIMIT).await?; + let body: FramesBody = serde_json::from_slice(&bytes) + .map_err(|e| ApiError::bad_request(format!("body must be {{\"frames\": [...]}}: {e}")))?; + drop(bytes); + state.device_agent.heard(id); + let accepted = body + .frames + .iter() + .filter(|raw| handle_frame(&state, id, raw)) + .count(); + sqlx::query( + "UPDATE device_links SET last_seen_at = now() + WHERE id = $1 AND (last_seen_at IS NULL OR last_seen_at < now() - interval '30 seconds')", + ) + .bind(id) + .execute(&state.db) + .await?; + Ok(Json(json!({ "ok": true, "accepted": accepted }))) +} + +// --------------------------------------------------------------------------------------------- +// Agent tokens + +#[derive(Deserialize, Default)] +struct MintRequest { + #[serde(default)] + label: Option, +} + +#[derive(Serialize)] +struct MintedToken { + id: Uuid, + token: String, + label: String, + device_id: Uuid, + #[serde(with = "time::serde::rfc3339")] + created_at: OffsetDateTime, + mcp_url: String, +} + +#[derive(Serialize, sqlx::FromRow)] +struct TokenView { + id: Uuid, + label: String, + device_id: Uuid, + #[serde(with = "time::serde::rfc3339")] + created_at: OffsetDateTime, + #[serde(with = "time::serde::rfc3339::option")] + last_used_at: Option, +} + +/// `POST /v1/me/agent-tokens`: mint a `cat_` token for one agent, bound to the calling user +/// and device. The token is in this response only. +async fn mint_token( + State(state): State, + user: AuthUser, + OptionalJsonBody(req): OptionalJsonBody, +) -> ApiResult<(StatusCode, Json)> { + let label = + auth::clean_name(req.label.as_deref(), MAX_LABEL_CHARS).unwrap_or_else(|| "Agent".into()); + let active: i64 = sqlx::query_scalar( + "SELECT count(*) FROM agent_tokens WHERE user_id = $1 AND revoked_at IS NULL", + ) + .bind(user.user_id) + .fetch_one(&state.db) + .await?; + if active >= MAX_ACTIVE_TOKENS { + return Err(ApiError::bad_request(format!( + "too many agent tokens (max {MAX_ACTIVE_TOKENS}); revoke some first" + ))); + } + let token = new_agent_token(); + let id = ids::uuid_v7(); + let created_at: OffsetDateTime = sqlx::query_scalar( + "INSERT INTO agent_tokens (id, user_id, device_id, label, token_sha256) + VALUES ($1, $2, $3, $4, $5) RETURNING created_at", + ) + .bind(id) + .bind(user.user_id) + .bind(user.device_id) + .bind(&label) + .bind(&ids::sha256(token.as_bytes())[..]) + .fetch_one(&state.db) + .await?; + tracing::info!( + user_id = %user.user_id, + device_id = %user.device_id, + token_id = %id, + "agent token minted" + ); + Ok(( + StatusCode::CREATED, + Json(MintedToken { + id, + token, + label, + device_id: user.device_id, + created_at, + mcp_url: mcp_url(&state.cfg), + }), + )) +} + +/// `GET /v1/me/agent-tokens`: the user's live tokens, newest first (never the token itself). +async fn list_tokens( + State(state): State, + user: AuthUser, +) -> ApiResult>> { + Ok(Json( + sqlx::query_as::<_, TokenView>( + "SELECT id, label, device_id, created_at, last_used_at FROM agent_tokens + WHERE user_id = $1 AND revoked_at IS NULL ORDER BY created_at DESC, id DESC", + ) + .bind(user.user_id) + .fetch_all(&state.db) + .await?, + )) +} + +/// `DELETE /v1/me/agent-tokens/{id}`: revoke at once (its calls in flight fail and are +/// cancelled on the device). Idempotent; `404` if not the caller's. +async fn revoke_token( + State(state): State, + user: AuthUser, + Path(id): Path, +) -> ApiResult> { + let revoked: Option = sqlx::query_scalar( + "UPDATE agent_tokens SET revoked_at = COALESCE(revoked_at, now()) + WHERE id = $1 AND user_id = $2 RETURNING id", + ) + .bind(id) + .bind(user.user_id) + .fetch_optional(&state.db) + .await?; + if revoked.is_none() { + return Err(ApiError::NotFound); + } + state.device_agent.revoke_token(id); + tracing::info!(user_id = %user.user_id, token_id = %id, by_device = %user.device_id, "agent token revoked"); + Ok(Json(json!({ "ok": true }))) +} + +// --------------------------------------------------------------------------------------------- +// Device deletion + +/// What deleting a device turned off. Apply it to the hub ([`RevokedDevice::apply`]) once the +/// transaction has committed. +#[derive(Debug, Default)] +#[must_use] +pub struct RevokedDevice { + pub links: Vec, + pub tokens: Vec, +} + +impl RevokedDevice { + pub fn is_empty(&self) -> bool { + self.links.is_empty() && self.tokens.is_empty() + } + + /// Close the links' streams (failing their calls in flight) and fail the tokens' calls. + pub fn apply(&self, hub: &Hub) { + for link in &self.links { + hub.revoke_link(*link); + } + for token in &self.tokens { + hub.revoke_token(*token); + } + } +} + +/// Revoke the link and every agent token of device `device_id` under `users` (inside the +/// transaction that deletes the device). +pub async fn revoke_device( + conn: &mut sqlx::PgConnection, + users: &[Uuid], + device_id: Uuid, +) -> ApiResult { + let links: Vec = sqlx::query_scalar( + "UPDATE device_links SET revoked_at = COALESCE(revoked_at, now()) + WHERE device_id = $1 AND user_id = ANY($2) RETURNING id", + ) + .bind(device_id) + .bind(users) + .fetch_all(&mut *conn) + .await?; + let tokens: Vec = sqlx::query_scalar( + "UPDATE agent_tokens SET revoked_at = now() + WHERE device_id = $1 AND user_id = ANY($2) AND revoked_at IS NULL RETURNING id", + ) + .bind(device_id) + .bind(users) + .fetch_all(&mut *conn) + .await?; + Ok(RevokedDevice { links, tokens }) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn agent_token_format() { + let t = new_agent_token(); + assert!(t.starts_with("cat_") && t.len() == 4 + 43, "{t}"); + assert!(plausible_agent_token(&t)); + assert_ne!(t, new_agent_token()); + for bad in [ + "", + "cat_", + "cat_short", + &t[4..], + &format!("cai_{}", &t[4..]), + ] { + assert!(!plausible_agent_token(bad), "{bad}"); + } + } + + #[test] + fn agent_paths() { + for p in [ + "/v1/agent", + "/v1/agent/", + "/v1/agent/mcp", + "/v1/agent/status", + ] { + assert!(is_agent_path(p), "{p}"); + } + for p in [ + "/v1/agents", + "/v1/agents/pair", + "/v1/agentx", + "/v1/me/links", + "/agent", + ] { + assert!(!is_agent_path(p), "{p}"); + } + } + + #[test] + fn manifests() { + let tool = + |n: &str| json!({ "name": n, "description": "d", "inputSchema": {"type": "object"} }); + assert!(validate_manifest(&json!([])).is_ok()); + assert!(validate_manifest(&json!([tool("a"), tool("b")])).is_ok()); + assert!(validate_manifest(&json!({"name": "a"})).is_err()); + assert!(validate_manifest(&json!([tool("a"), tool("a")])).is_err()); + assert!(validate_manifest(&json!([{"description": "no name"}])).is_err()); + assert!(validate_manifest(&json!([tool(" ")])).is_err()); + assert!(validate_manifest(&json!(["jev_run"])).is_err()); + let many: Vec = (0..=MAX_TOOLS).map(|i| tool(&format!("t{i}"))).collect(); + assert!(validate_manifest(&Value::Array(many)).is_err()); + let big = json!([{ "name": "a", "description": "x".repeat(MAX_MANIFEST_BYTES) }]); + assert!(validate_manifest(&big).is_err()); + } + + #[test] + fn utf8_truncation() { + assert_eq!(truncate_utf8("héllo".into(), 2), "h"); + assert_eq!(truncate_utf8("héllo".into(), 3), "hé"); + assert_eq!(truncate_utf8("abc".into(), 10), "abc"); + } + + #[test] + fn mcp_url_uses_public_url_or_acme_domain() { + let mut cfg = Config::for_tests("postgres://localhost/unused"); + assert_eq!(mcp_url(&cfg), "https://localhost:8443/v1/agent/mcp"); + cfg.public_url = "cloud.example.com".into(); + cfg.tls.mode = TlsMode::Acme; + cfg.tls.domain = Some("cloud.example.com".into()); + assert_eq!(mcp_url(&cfg), "https://cloud.example.com/v1/agent/mcp"); + } +} diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs index 46a865c..502e6cb 100644 --- a/crates/core/src/lib.rs +++ b/crates/core/src/lib.rs @@ -12,6 +12,7 @@ pub mod auth; pub mod config; pub mod crypto; pub mod db; +pub mod device_agent; pub mod error; pub mod events; pub mod extract; diff --git a/crates/core/src/observe.rs b/crates/core/src/observe.rs index 2a68ee2..1833e9e 100644 --- a/crates/core/src/observe.rs +++ b/crates/core/src/observe.rs @@ -88,6 +88,18 @@ pub fn install_metrics() -> anyhow::Result { "DELETE /v1/sync/history calls refused by the per-user rate limit" ); metrics::describe_gauge!("sse_subscribers", "Open /v1/sync/events streams"); + metrics::describe_gauge!( + "device_agent_streams", + "Open device-agent frames streams (/v1/me/links/{id}/frames)" + ); + metrics::describe_counter!( + "device_agent_calls_total", + "Agent tools/call requests by outcome (ok, tool_error, error, offline, turned_off, unknown_tool, timeout, gone_offline, revoked, token_revoked, cancelled, shutdown)" + ); + metrics::describe_counter!( + "agent_rate_limited_total", + "/v1/agent/* requests rejected by the per-token rate limit" + ); metrics::describe_gauge!("db_pool_size", "Postgres pool connections (open)"); metrics::describe_gauge!("db_pool_idle", "Postgres pool connections (idle)"); metrics::describe_counter!( diff --git a/crates/core/src/state.rs b/crates/core/src/state.rs index 6050dcd..a068369 100644 --- a/crates/core/src/state.rs +++ b/crates/core/src/state.rs @@ -18,6 +18,8 @@ pub struct AppState { pub access_mode: AccessModeCache, /// SSO HTTP client + OIDC discovery cache. pub sso: crate::sso::SsoCache, + /// Device-agent relay: open device streams and agent calls in flight. + pub device_agent: crate::device_agent::Hub, } pub type SharedState = Arc; @@ -26,6 +28,10 @@ impl AppState { /// Build the shared state: derives the key-encryption key from `cfg.master_key`. pub fn new(db: sqlx::PgPool, cfg: Config) -> SharedState { let crypto = Crypto::from_master_key(&cfg.master_key); + let device_agent = crate::device_agent::Hub::new( + cfg.device_agent.agent_per_minute, + cfg.device_agent.online_window, + ); Arc::new(Self { db, cfg: Arc::new(cfg), @@ -34,6 +40,7 @@ impl AppState { started_at: Instant::now(), access_mode: AccessModeCache::default(), sso: crate::sso::SsoCache::default(), + device_agent, }) } } @@ -44,6 +51,7 @@ impl std::fmt::Debug for AppState { .field("cfg", &self.cfg) .field("events", &self.events) .field("access_mode", &self.access_mode) + .field("device_agent", &self.device_agent) .finish_non_exhaustive() } } diff --git a/crates/core/src/sync.rs b/crates/core/src/sync.rs index 516621e..c2b3ef6 100644 --- a/crates/core/src/sync.rs +++ b/crates/core/src/sync.rs @@ -52,7 +52,7 @@ const DEFAULT_HISTORY_LIMIT: usize = 500; /// SSE keepalive comment interval. pub const SSE_KEEPALIVE: Duration = Duration::from_secs(15); /// How often an open SSE stream re-checks that its session still exists. -const SSE_REVALIDATE: Duration = Duration::from_secs(300); +pub(crate) const SSE_REVALIDATE: Duration = Duration::from_secs(300); pub(crate) fn routes() -> Router { Router::new() @@ -1147,7 +1147,7 @@ impl Drop for SubscriberGauge { } } -async fn session_alive(db: &sqlx::PgPool, session_id: Uuid) -> bool { +pub(crate) async fn session_alive(db: &sqlx::PgPool, session_id: Uuid) -> bool { sqlx::query_scalar::<_, bool>( "SELECT EXISTS (SELECT 1 FROM sessions WHERE id = $1 AND expires_at > now())", ) diff --git a/docs/api.md b/docs/api.md index 7bda9b1..531bb13 100644 --- a/docs/api.md +++ b/docs/api.md @@ -5,7 +5,7 @@ RFC 3339 UTC strings. IDs are UUIDs (v7 for server-generated ones). ## Conventions -### Gate credential (every `/v1` request except `POST /v1/auth/pair`, the SSO routes and `POST /v1/agents/pair`) +### Gate credential (every `/v1` request except `POST /v1/auth/pair`, the SSO routes, `POST /v1/agents/pair` and `/v1/agent/*`) ``` X-Copper-Instance: @@ -49,7 +49,8 @@ Always `{"error": "", "message": ""}`: | 401 | `instance_key` / `session` / `credentials` / `account_disabled` / `pairing_code` | see above | | 401 | `sso_only` | password login for an account that only signs in with SSO | | 401 | `sso_failed` / `agent_key` | SSO code exchange or ID-token check failed; bad agent-integration key | -| 403 | `forbidden` | signup disabled; writing another device's `tabs:` doc | +| 401 | `agent_token` | `/v1/agent/*`: missing, malformed, unknown or revoked `cat_` token ([device agent relay](#device-agent-relay)) | +| 403 | `forbidden` | signup disabled; writing another device's `tabs:` doc; opening or feeding another device's link frames | | 403 | `password_signin_disabled` | password signup/login turned off by the admin (use SSO) | | 403 | `sso_domain` / `sso_no_account` / `agent_domain` / `account_disabled` | email domain not allowed; no account and auto-create off; disabled account (SSO, agent pairing) | | 404 | `sso_disabled` / `no_account` | SSO provider not set up / disabled; agent pairing for a missing account with `create_users` off | @@ -58,7 +59,8 @@ Always `{"error": "", "message": ""}`: | 404 | `link_not_found` | unknown, revoked, or deleted-canvas share link | | 409 | `conflict` | email taken; stale `base_version` (body carries the server copy) | | 413 | `payload_too_large` | body or payload over the configured limit | -| 429 | `rate_limited` | auth rate limit, or a per-user limit (mentions, history delete) (header `Retry-After: 60`) | +| 405 | `method_not_allowed` | `GET` / `DELETE /v1/agent/mcp` (no event stream, no session) | +| 429 | `rate_limited` | auth rate limit, a per-user limit (mentions, history delete) or the per-token agent limit (header `Retry-After: 60`) | | 500 | `internal` | server bug / database failure (details only in server logs) | | 502 | `canvas_upstream` | canvas routes only: the linked Canvas Cloud is unreachable, timed out, or rejected the app key ([canvas-link.md](canvas-link.md#status-codes)) | | 503 | `canvas_unavailable` | canvas routes only: no Canvas Cloud is linked | @@ -76,7 +78,8 @@ includes the ungated `POST /v1/auth/pair` and `POST /v1/auth/sso/{provider_id}`. Behind a proxy set `trust_proxy = true` so the right-most `X-Forwarded-For` hop is used. `POST /v1/canvases/{id}/mentions` has its own per-user bucket (60 per minute, bursts of 60), and `DELETE /v1/sync/history` another (20 per minute, bursts of 20; requests rejected with `400` or -`413` do not count). +`413` do not count). `/v1/agent/*` is limited per agent token: 600 requests per minute (bursts of +600, then one every 100 ms). ### Request size limits @@ -86,6 +89,9 @@ Behind a proxy set `trust_proxy = true` so the right-most `X-Forwarded-For` hop | `PUT /v1/sync/docs/{domain}` | base64 of `limits.max_blob_bytes` (8 MB decoded) + 4 KiB | | `POST /v1/sync/history` | `max_history_batch` × (`max_history_entry_bytes` + 8) (≤ 64 MiB) | | `DELETE /v1/sync/history` | 256 KiB (room for 5000 `seqs`) | +| `POST /v1/me/links` | 1 MiB (the `tools` manifest itself: 256 KiB) | +| `POST /v1/me/links/{id}/frames` | 32 MiB (replies may carry screenshots) | +| `POST /v1/agent/mcp` | 4 MiB | Bodies must arrive within 60 s. `Content-Type` is not required. @@ -128,6 +134,8 @@ only ever grows, and an absent field (older servers) means none of them: | `agent_pairing` | 0.9.0 | [`POST /v1/agents/pair`](#post-v1agentspair--no-gate-header) and device-bound pairing codes | | `addons` | 0.10.0 | [`GET /v1/addons`](#addons) and the `addons` event | | `canvas_link` | 0.11.0 | canvases are served by a linked Canvas Cloud through this server ([canvas-link.md](canvas-link.md)); the canvas API itself is unchanged | +| `doc_revisions` | 0.12.0 | [doc revisions](#doc-revisions-features-doc_revisions) and the optional `X-Copper-Build` header | +| `device_agent` | 0.13.0 | the [device agent relay](#device-agent-relay): `/v1/me/links` (+ frames), `/v1/me/agent-tokens`, and the ungated `GET /v1/agent/status` + `POST /v1/agent/mcp` | `canvas` (0.11.0+): `linked` is `true` while a Canvas Cloud is linked and enabled. When it is `false`, every canvas route answers `503 canvas_unavailable`. It says nothing about @@ -437,7 +445,9 @@ Most recently seen first. ### `DELETE /v1/devices/{id}` -Revokes the device's sessions and deletes its `tabs:` doc. `200 {"ok": true}`. +Revokes the device's sessions, deletes its `tabs:` doc, and turns off its +[device agent](#device-agent-relay) link (its stream closes with `revoked`) and agent tokens. +`200 {"ok": true}`. --- @@ -814,6 +824,210 @@ SHA-256 of the body equals `{sha256}` before using it. --- +## Device agent relay + +(`features`: `device_agent`, 0.13.0.) An agent — phi, Claude Code, any MCP client or plain +`curl` — calls the tools of a person's Copper for iOS through this server. The phone dials out +and holds an event stream while Copper is open; the server hands it each call and returns its +reply. Nothing listens on the phone. + +```text +agent ── POST /v1/agent/mcp (cat_ token) ──▶ copper-cloud ── SSE "request" ──▶ Copper on iPhone +agent ◀── JSON-RPC result (JSON or SSE) ──── copper-cloud ◀── POST frames "reply" ── iPhone +``` + +Which links are online and the calls in flight live in memory (one daemon per instance); links +and tokens are stored (`device_links`, `agent_tokens`). + +### Device side 🔒 + +Gate credential + session, like every user route. A link belongs to the calling session's +device; one link per (user, device). + +#### `POST /v1/me/links` + +Register (or update) this device's link and its tool manifest. + +```json +{ "label": "Ada's iPhone", "client_version": "ios-1.0.0", + "tools": [ { "name": "jev_run", "description": "…", "inputSchema": { "type": "object" } } ] } +``` + +`200` — the link object (every link route returns it): + +```json +{ "id": "uuid", "device_id": "uuid", "device_name": "Ada's iPhone", "label": "Ada's iPhone", + "online": false, "revoked": false, "created_at": "2026-10-31T20:00:00Z", "last_seen_at": null, + "tools": 22 } +``` + +- Idempotent: the same device always gets the same link id, and a revoked link comes back + un-revoked. Omitted fields keep their stored value (a new link: `label` = the device name, no + tools). `label` ≤ 100 characters and `client_version` ≤ 64 (longer values are cut). +- `tools` is stored as sent and served to agents by `tools/list`, so an agent can list tools + while the phone is closed. `400` unless it is an array of at most 100 objects, each with a + unique, non-empty `name` (≤ 128 characters), and at most 256 KiB as JSON. +- In the link object, `tools` is how many tools the manifest has; `online` is whether its stream + is open and the device was heard from in the last 45 s; `last_seen_at` is when it last opened + or closed its stream or uploaded frames (refreshed at most every 30 s while online). + +#### `GET /v1/me/links` · `GET /v1/me/links/{id}` · `DELETE /v1/me/links/{id}` + +- `GET /v1/me/links`: the user's live (not revoked) links, oldest first. +- `GET /v1/me/links/{id}`: one link, revoked included. +- `DELETE /v1/me/links/{id}`: revoke it (any of the user's devices may). Its stream gets + `revoked` and closes, its calls in flight fail, and every agent call answers "turned off" until + the device registers again. Idempotent; `200 {"ok": true}`. + +All three answer `404` for another user's link. Deleting the device +([`DELETE /v1/devices/{id}`](#delete-v1devicesid)) revokes its link too. + +#### `GET /v1/me/links/{id}/frames` — SSE mailbox + +Only the link's own device may open it (`403` from the user's other devices, `404` for another +user's link). `Content-Type: text/event-stream`, `Cache-Control: no-store`, `X-Accel-Buffering: +no`. A new stream supersedes the previous one (which gets `superseded` and closes). Each `data:` +is one JSON object: + +| event | data | +|---|---| +| `hello` | `{"link": {…link object…}, "protocol": 1}` — always first | +| `request` | `{"id": "req_…", "method": "tools/call", "params": {"name": "jev_run", "arguments": {…}}, "caller": {"token_id": "uuid", "label": "phi"}, "deadline_ms": 200000}` | +| `cancel` | `{"id": "req_…"}` — the agent went away, timed out or was revoked; stop that call | +| `ping` | `{}` every 15 s | +| `superseded` | `{}`, then the stream closes; do not reconnect from this stream | +| `revoked` | `{}`, then the stream closes; the user turned the link off | + +Opening a revoked link's stream answers `hello` (`"revoked": true`), then `revoked`, then closes. +The stream also ends on server shutdown and when the session is revoked (checked every 5 min). + +#### `POST /v1/me/links/{id}/frames` + +From the link's own device (`403` / `404` as above): `{"frames": [ … ]}`, body up to 32 MiB. +`200 {"ok": true, "accepted": n}` — `n` = well-formed frames of a known type (malformed frames and +unknown types are skipped; a reply for an unknown or finished request is accepted and ignored). +`400` if the body is not `{"frames": [...]}`. + +| frame | shape | +|---|---| +| reply | `{"type": "reply", "id": "req_…", "result": {"content": [...], "isError": false}}` or `{"type": "reply", "id": "req_…", "error": {"code": "…", "message": "…"}}` | +| progress | `{"type": "progress", "id": "req_…", "seq": 3, "message": "3 · CLICK [12] button \"Search\""}` — `seq` must grow (a stale or repeated one is ignored; a frame without one counts as the next); messages over 16 KiB are cut | +| heartbeat | `{"type": "heartbeat"}` every 15 s while the stream is open | +| log | `{"type": "log", "level": "info", "message": "…"}` — logged at debug, never stored | + +A link is **online** while its stream is open and the device was heard from — stream opened, +heartbeat or any other frames POST — within the last 45 s. The phone closes its stream when +Copper leaves the screen. + +#### Agent tokens: `POST /v1/me/agent-tokens` · `GET /v1/me/agent-tokens` · `DELETE /v1/me/agent-tokens/{id}` + +Minted by the phone for one agent; bound to the minting user and device. + +```json +// POST body (optional; label defaults to "Agent", ≤ 100 characters) +{ "label": "phi" } +// 201 +{ "id": "uuid", "token": "cat_<43 base64url chars>", "label": "phi", "device_id": "uuid", + "created_at": "2026-10-31T20:00:00Z", "mcp_url": "https://cloud.example.com/v1/agent/mcp" } +``` + +- The token (`cat_` + 32 random bytes, base64url) is in this response only; the server stores + SHA-256(token). At most 100 live tokens per user (`400` beyond: revoke some). +- `mcp_url` is built from the instance's public URL (with ACME, from `tls.domain`). The agent's + HTTP client must trust the certificate: use ACME or a TLS-terminating proxy, or trust a + self-signed instance's certificate explicitly. +- `GET` lists the user's live tokens, newest first: + `[{"id", "label", "device_id", "created_at", "last_used_at"}]` — never the token + (`last_used_at` is refreshed at most once a minute). +- `DELETE` revokes at once: the next agent request is `401`, and its calls in flight fail and get + a `cancel` on the device. Idempotent; `200 {"ok": true}`; `404` if not yours. Deleting the + device revokes its tokens too. + +### Agent side: `cat_` token, no gate header + +``` +Authorization: Bearer cat_<43 chars> +``` + +`/v1/agent/*` is outside the instance gate: the 256-bit token is the credential (a gate header, +if sent, is ignored). A missing, malformed, unknown or revoked token — or one whose account is +disabled or whose device was deleted — is `401 {"error":"agent_token"}`. The token is read from +the `Authorization` header only. 600 requests per minute per token (`429 rate_limited`). + +#### `GET /v1/agent/status` + +```json +{ "device": { "id": "uuid", "name": "Ada's iPhone" }, "label": "Ada's iPhone", "online": true, + "last_seen_at": "2026-10-31T20:00:00Z", "tools": 22 } +``` + +`online` is `false` when the link is offline, revoked, or was never registered (then `label` and +`last_seen_at` are `null` and `tools` is `0`). `Cache-Control: no-store`. + +#### `POST /v1/agent/mcp` — MCP Streamable HTTP (stateless) + +One JSON-RPC 2.0 message per request. A batch (JSON array), invalid JSON, or a message without a +`method` that is not a response is `400` with a JSON-RPC error (`-32600` / `-32700`, +`"id": null`). No `Mcp-Session-Id` is needed or returned. `GET` and `DELETE` (with a valid token) +answer `405 method_not_allowed` with `Allow: POST`: there is no server-initiated stream. + +| method | answer | +|---|---| +| `initialize` | `{"protocolVersion": , "capabilities": {"tools": {"listChanged": false}}, "serverInfo": {"name": "copper-mobile", "version": ""}, "instructions": ""}` | +| `notifications/*` (also any other message without an `id`, and responses) | `202`, empty body | +| `ping` | `{}` | +| `tools/list` | `{"tools": [...]}` — the manifest the device last registered (empty if none), also while it is offline or turned off | +| `tools/call` | relayed to the device (below) | +| anything else | JSON-RPC error `-32601` | + +`tools/call` (`params.name` required and `params.arguments` an object when present, else +`-32602`): + +- **Turned off** (link revoked or never registered): at once, `isError: true` with "Agents are + turned off on . Ask the person to turn on Settings › Agents › Let agents use this + iPhone in Copper, then try again." +- **Not in the manifest**: at once, `isError: true` naming the tool. +- **Offline**: at once, `{"content": [{"type": "text", "text": "Copper isn't open on . Ask the person to open Copper on their iPhone and keep it on screen (Settings › Agents › + Let agents use this iPhone must be on), then try again."}], "isError": true}`. +- Otherwise the device gets a `request` frame (deadline 200 s) and the server waits for its + reply. A reply's `result` is the JSON-RPC result as sent; a reply `error` becomes + `isError: true` with its message. A deadline miss sends `cancel` to the device and answers + `isError: true` ("… timed out …"). If the device is offline for 15 s while the call runs + (Copper left the screen), the call is cancelled and answers `isError: true` then, instead of + waiting out the deadline. Revoking the link or the token mid-call, or a server shutdown, + answers `isError: true` too. +- With `text/event-stream` in the request's `Accept`, the answer is an SSE stream + (`Cache-Control: no-store`, `X-Accel-Buffering: no`): a `: keepalive` comment after every 10 s + of silence (proxies drop idle requests at 60 s), an `event: message` with + `notifications/progress` (`{"progressToken": , "progress": , "message": "…"}`) + for each device progress frame when the call carried `params._meta.progressToken`, then an + `event: message` with the JSON-RPC response, and the stream ends. Otherwise one + `application/json` response (progress is not delivered). Every other method answers + `application/json`. +- The agent disconnecting mid-call (closing the request or the stream) sends `cancel` to the + device. +- One log line per call — token id, device id, tool name, duration (`ms`), outcome (`status`) — + and a `device_agent_calls_total{status}` count. Never arguments or results. + +The `initialize` instructions tell the agent that this is the person's Copper on their iPhone, +signed in as them; that it only works while Copper is open on their screen; to reach for +`jev_run` first (the whole goal with concrete values and a stop condition; `DONE` is Jev's claim, +verified with `jev_observe` / `jev_extract`), then `browser_snapshot` / `browser_click` / +`browser_type` for whatever Jev is `BLOCKED` on. + +```sh +# The phone minted $CAT for this agent; no gate header needed. +curl -s https://cloud.example.com/v1/agent/status -H "Authorization: Bearer $CAT" +curl -sN https://cloud.example.com/v1/agent/mcp -H "Authorization: Bearer $CAT" \ + -H 'Accept: application/json, text/event-stream' \ + -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"jev_run", + "arguments":{"goal":"Open example.com and read the headline; stop when it is visible"}, + "_meta":{"progressToken":1}}}' +``` + +--- + ## Canvases 🔒 Mounted under the same `/v1` gate and session auth. Since 0.11.0 they are served by the linked diff --git a/docs/architecture.md b/docs/architecture.md index 8409ccf..a4f3e1b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -27,7 +27,7 @@ copper-cloud proxies the canvas API to it as the signed-in user — see [canvas- | Crate | Role | |---|---| | `crates/copper-cloud` (bin + lib) | CLI (clap), `serve` bootstrap, graceful shutdown, `doctor`, `admin`, admin API (`/admin/api`), `/start` onboarding page, embedded admin portal (rust-embed of `portal/out`), migrations dir | -| `crates/core` (`copper-cloud-core`) | config, db pool + embedded migrations, crypto, access mode + access keys + gate, auth extractor + routes, pairing codes, single sign-on (`sso`), agent integrations (`agents`), sync docs/history/SSE, cloud-wide intelligence keys, events, TLS, link codes, observability, app composition | +| `crates/core` (`copper-cloud-core`) | config, db pool + embedded migrations, crypto, access mode + access keys + gate, auth extractor + routes, pairing codes, single sign-on (`sso`), agent integrations (`agents`), the device agent relay (`device_agent`: links, frames, agent tokens, MCP endpoint, in-memory hub), sync docs/history/SSE, cloud-wide intelligence keys, events, TLS, link codes, observability, app composition | | `portal/` | Next.js static export (the admin portal), built with bun into `portal/out` before cargo in CI/release | | `crates/canvas-link` (`copper-cloud-canvas-link`) | the canvas link: settings (sealed app key), REST proxy + WebSocket pipe to Canvas Cloud, event bridge, user provisioning (batch, JIT, reconcile, outbox), `/join/{token}` landing page, `GET /v1/info` `canvas` field, admin/CLI/doctor helpers (see [canvas-link.md](canvas-link.md)) | | `crates/canvas-migrate` (`copper-cloud-canvas-migrate`) | `copper-cloud canvas migrate`: reads the legacy canvas tables, streams them to Canvas Cloud's import, verifies by digest (see [canvas-migration.md](canvas-migration.md)) | @@ -51,7 +51,7 @@ Router │ link.router(): /canvases, /canvases/{*rest}, /people, /invites, /invites/{*rest}, │ /canvas-links/{*rest}, /mentions, /mentions/{*rest} (any method) → Canvas Cloud │ ungated: POST /v1/auth/pair, GET /v1/auth/sso, POST /v1/auth/sso/{id}, -│ POST /v1/agents/pair (each carries its own credential or none) +│ POST /v1/agents/pair, /v1/agent/* (each carries its own credential or none) ├── /admin/api = admin_api::router() (cookie sessions + CSRF header; fallback → 404 JSON) ├── GET /start, GET /join/{token} (server-rendered landing pages, not gated) └── fallback → portal::serve (embedded portal/out; /v1x, /metrics… → 404 JSON) @@ -90,6 +90,8 @@ it. The query string is never logged (it can carry `?token=`). | `sso_providers` | `id` (`google` or a slug) | `kind` google/oidc, `client_id`, sealed `client_secret_sealed` under `data_key_wrapped`, `issuer?` (OIDC), `domains[]`, `auto_create`, `enabled` | | `user_identities` | `(provider_id, subject)` | SSO identity → `user_id` link, last reported `email`, `last_login_at` | | `agent_integrations` | `id`; `key_sha256` unique | `cai_` key hash, `name`, `domains[]`, `create_users`, `last_used_at`, `revoked_at` | +| `device_links` | `id`; `(user_id, device_id)` unique | device agent links: `label`, `client_version`, `tools` (jsonb manifest), `last_seen_at`, `revoked_at` (set by revoke or device delete; no FK to `devices`) | +| `agent_tokens` | `id`; `token_sha256` unique | `cat_` token hash bound to `(user_id, device_id)`, `label`, `last_used_at`, `revoked_at` | | `intelligence_settings` | `id` = 1 (singleton) | cloud-wide AI keys: `data_key_wrapped`, sealed `jev_key_sealed` / `router_key_sealed`, `jev_endpoint`, `jev_model`, `router_url`, `enabled`, `agent_max_turns` (org agent round budget, 1–500 or NULL), `updated_at/by` | | `admins` | `id`; `lower(email)` unique | portal admin accounts (Argon2id), `last_login_at` | | `admin_sessions` | `id`; `token_sha256` unique | `cc_admin` cookie sessions, fixed 7-day `expires_at` | @@ -127,6 +129,20 @@ once; shell CLI deletes: `copper-cloud canvas sync-users --prune`, never automat keepalive comment; a lagging stream gets `resync`. Single-process by design (one daemon per instance). +## Device agent relay + +An agent calls a person's Copper for iOS through `POST /v1/agent/mcp` (ungated, `cat_` token); +the phone holds `GET /v1/me/links/{id}/frames` open while Copper is on screen and posts replies +to the same path ([api.md](api.md#device-agent-relay)). The in-process `device_agent::Hub` (on +`AppState`, like `Events`) maps each link to its current frames stream (`mpsc` sender, stream id, +last heartbeat) and each request id (`req_…`) to the waiting call (`oneshot` for the reply, +`mpsc` for progress). A call is handed down only if the link is online (stream open, heard from +within 45 s); otherwise the agent is answered at once. The waiting side is a stream that owns a +guard: dropping it — the JSON handler future or the SSE body, when the agent goes away — sends +the device a `cancel`. Deadline (200 s), offline grace (15 s), revoke and shutdown end the call +with an `isError` result. Links, manifests and token hashes are in Postgres; nothing about calls +is stored, and the per-call log line never carries arguments or results. + ## Encryption at rest `master_key` → HKDF-SHA256 → KEK. Each user gets a random 32-byte data key wrapped by the KEK. diff --git a/docs/install.md b/docs/install.md index 807adbc..cc6fd56 100644 --- a/docs/install.md +++ b/docs/install.md @@ -12,7 +12,7 @@ curl -fsSL https://raw.githubusercontent.com/copper-browser/copper-cloud/main/in From a release tarball (files at the archive root): ```sh -tar xzf copper-cloud-0.12.0-linux-aarch64.tar.gz +tar xzf copper-cloud-0.13.0-linux-aarch64.tar.gz sudo ./install.sh ``` @@ -67,7 +67,7 @@ data stay. | `COPPER_CLOUD_MASTER_KEY` | generated | base64url of exactly 32 bytes | | `COPPER_CLOUD_BINARY` | — | local binary or release tarball | | `COPPER_CLOUD_BINARY_URL` | — | URL of a binary or release tarball | -| `COPPER_CLOUD_VERSION` | `latest` | GitHub release to fetch (e.g. `0.12.0`) | +| `COPPER_CLOUD_VERSION` | `latest` | GitHub release to fetch (e.g. `0.13.0`) | | `GITHUB_TOKEN` | — | for a private GitHub repository | `sudo -E` (or `sudo VAR=… sh install.sh`) is needed to pass variables through sudo. diff --git a/docs/operations.md b/docs/operations.md index 8f44a81..63daa4d 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -69,7 +69,11 @@ by `"…"`: `POST /v1/sync/history`) log one `history entries skipped` warning per request with the count and the first index/reason. `DELETE /v1/sync/history` logs one `history deleted` line with the count deleted, how many seqs were asked for, and which filters were used (never the times, -seqs or anything about the entries). Useful filters: +seqs or anything about the entries). Every agent `tools/call` through the device agent relay +logs one `agent call` line with `token_id`, `device_id`, `tool`, `ms` and `status` (never +arguments or results); token mints/revokes and link registrations/revokes log `agent token +minted`, `agent token revoked`, `device link registered` and `device link revoked`. Useful +filters: ```sh journalctl -u copper-cloud -o cat | jq -c 'select(.level=="ERROR")' @@ -78,6 +82,7 @@ journalctl -u copper-cloud -o cat | jq -c 'select(.message=="history entries ski journalctl -u copper-cloud -o cat | jq -c 'select(.message=="history deleted")' journalctl -u copper-cloud -o cat | jq -c 'select(.span.status==429)' journalctl -u copper-cloud -o cat | jq -c 'select(.message=="login failed")' +journalctl -u copper-cloud -o cat | jq -c 'select(.message=="agent call") | {token_id, device_id, tool, ms, status}' ``` Change verbosity with `log_level = "debug"` or `RUST_LOG=copper_cloud_core=debug,info` @@ -103,6 +108,9 @@ curl -s http://127.0.0.1:9464/metrics | `history_delete_rate_limited_total` | counter | — (`DELETE /v1/sync/history` refused with `429`) | | `sse_subscribers` | gauge | — (open event streams) | | `auth_rate_limited_total` | counter | — | +| `device_agent_streams` | gauge | — (open device-agent frames streams: phones with Copper on screen) | +| `device_agent_calls_total` | counter | `status` (`ok`, `tool_error`, `error`, `offline`, `turned_off`, `unknown_tool`, `timeout`, `gone_offline`, `revoked`, `token_revoked`, `cancelled`, `shutdown`) | +| `agent_rate_limited_total` | counter | — (`/v1/agent/*` requests refused by the per-token limit) | | `db_pool_size`, `db_pool_idle` | gauge | — (refreshed on scrape) | | `process_uptime_seconds` | gauge | — | @@ -173,7 +181,7 @@ curl -fsSL https://raw.githubusercontent.com/copper-browser/copper-cloud/main/in The installer swaps the binary atomically, runs `migrate`, restarts and waits for health. Migrations are forward-only; take a DB backup first. Downgrading across a migration is not supported (for the 0.11.0 canvas move there is a documented rollback: -[canvas-migration.md](canvas-migration.md#rollback)). Clients reconnect automatically (SSE and +[canvas-migration.md](canvas-migration.md#rollback); for 0.13.0: [v0.13.0.md](v0.13.0.md#rollback)). Clients reconnect automatically (SSE and canvas WebSockets drop during restart). **Upgrading from 0.10.x or older to 0.11.0** moves canvases to a Canvas Cloud: follow the runbook in diff --git a/docs/security.md b/docs/security.md index b313bbb..1ff3ce7 100644 --- a/docs/security.md +++ b/docs/security.md @@ -20,8 +20,9 @@ compromised server process or host, key rotation, multi-instance HA. ### Gate: instance key or access key -Every `/v1` request except `POST /v1/auth/pair` must carry `X-Copper-Instance`. Without an -accepted credential the server answers `401 {"error":"instance_key"}` for every `/v1` path — +Every `/v1` request except `POST /v1/auth/pair` (and the other ungated routes: single sign-on, +`POST /v1/agents/pair` and the device agent relay's `/v1/agent/*`, each with its own credential) +must carry `X-Copper-Instance`. Without an accepted credential the server answers `401 {"error":"instance_key"}` for every `/v1` path — unknown routes included — and never reads request bodies. Two kinds of credential: - **Instance key** — one shared secret per instance, ≥ 32 characters of `[A-Za-z0-9-_.~]` @@ -318,6 +319,28 @@ replaces its previous session and gate key, so a leaked session for an agent dev the next pairing. Every pairing and every key change is audited. The route is not rate limited, because the key is unguessable, and it is checked by shape before any database lookup. +## Device agent relay + +An agent token (`cat_` + 256 random bits, stored as SHA-256, shown once) lets an agent drive one +person's Copper for iOS through `/v1/agent/*` (0.13.0): it acts as that person in their +signed-in tabs, so it is as powerful as the phone's browser while Copper is open on screen. + +- **Bound and narrow.** A token is minted by a signed-in device for itself and works only for + that user and device; it is not a session and opens no other route. The route is outside the + instance gate (the token is the credential), checked by shape before any database lookup, and + limited to 600 requests a minute per token. Tokens are read from the `Authorization` header + only, never a query string. +- **The person stays in control.** Calls reach the phone only while Copper is open on its screen + and the person has turned agents on (the phone holds the stream); every call is announced on + the page with Stop. Revoking a token, revoking the link or deleting the device takes effect at + once: calls in flight fail and the device gets a `cancel`. A disabled account's tokens stop + working. +- **Devices only feed their own link.** Only the link's own device (its session) may open or + post to its frames; a reply is matched to the request id and the link it was sent to. +- **Nothing about calls is stored.** One log line per call (token id, device id, tool, duration, + outcome); arguments, results, progress text and tokens are never logged. Device `log` frames + are written at debug level only. + ## Reporting Security issues: contact the maintainers privately (do not open a public issue). diff --git a/docs/v0.13.0.md b/docs/v0.13.0.md new file mode 100644 index 0000000..b927117 --- /dev/null +++ b/docs/v0.13.0.md @@ -0,0 +1,42 @@ +# copper-cloud v0.13.0 + +Agents can use a person's Copper for iOS through the cloud. One new migration +(`0016_device_agent`); an upgrade from 0.12.x is a binary swap (`sudo ./install.sh` from the +tarball) and the server migrates on start. + +- **Device agent relay** ([api.md](api.md#device-agent-relay)). Copper for iOS registers a link + with its tool manifest (`POST /v1/me/links`) and, while Copper is on screen and the person has + turned agents on, holds an event stream (`GET /v1/me/links/{id}/frames`). An agent — phi, + Claude Code, any MCP client — calls `POST /v1/agent/mcp` with a `cat_` token the phone minted + (`POST /v1/me/agent-tokens`); the cloud hands each `tools/call` to the phone and returns its + reply, as JSON or as an SSE stream with keepalives and progress notifications. A deadline miss + or an agent that goes away sends the phone a `cancel`; a phone that is not open is answered at + once. `/v1/info` lists `device_agent`. +- **`/v1/agent/*` is outside the instance gate**: the 256-bit token is the credential (only its + SHA-256 is stored), limited to 600 requests a minute per token. Revoking a token, the link, or + deleting the device stops calls at once. +- **Logs and metrics.** One `agent call` line per call (token id, device id, tool, duration, + outcome; never arguments or results), and `device_agent_streams`, `device_agent_calls_total`, + `agent_rate_limited_total`. + +Agents need a certificate their HTTP client trusts: ACME (or a TLS-terminating proxy) works as +is; a self-signed instance's certificate must be trusted explicitly. + +## Rollback + +0.12.x does not know migration `0016`, and sqlx refuses a database with an applied migration it +does not know: 0.12.x `serve`, `migrate` and its installer stop with "migration 16 was +previously applied but is missing in the resolved migrations". `0016` only adds two tables, so +either run 0.12.x as `copper-cloud serve --no-migrate`, or remove the migration first (as the +`postgres` superuser or the database owner; every device link and agent token is lost, nothing +else is touched) and reinstall the previous release: + +```sh +sudo systemctl stop copper-cloud +sudo -u postgres psql -w -d copper_cloud -v ON_ERROR_STOP=1 -c \ + "BEGIN; DROP TABLE agent_tokens; DROP TABLE device_links; DELETE FROM _sqlx_migrations WHERE version = 16; COMMIT;" +tar xzf copper-cloud-0.12.0-linux-$(uname -m).tar.gz && sudo ./install.sh +``` + +Upgrading again later re-applies `0016` cleanly (phones register their links again; agent +tokens must be minted again).