Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.
Rust acpagent-client-protocolai-agentsai-assistantclaudeclaude-codecodexcoding-agentscursorgeminigemini-cligrok-bot-alternativeiosiphonelinuxmacosmcpopen-sourcerustself-hosted
feat(cloud): accept public routine webhooks and queue them for the host
leepokai3591351cd7eb
diff --git a/cloud/README.md b/cloud/README.mdindex 2468b856..2764d95a 100644--- a/cloud/README.md+++ b/cloud/README.md@@ -4,10 +4,12 @@ Cloudflare Worker for accounts and the off-LAN relay (spec: [docs/reference/remo- **`/v1` API** (`src/api.ts`): Clerk-authenticated account routes (devices, claims, computers, accessrequests, grants), `Codync-Sig`-authenticated host routes (`/v1/host/*`), the Clerk webhook, and a- 15-minute cron that expires requests and prunes nonces. D1 schema: `migrations/0001_init.sql`.+ 15-minute cron that expires requests and prunes nonces, and the public routine webhook route+ `POST /v1/hooks/:computerId/:routineId` (spec §7.8). D1 schema: `migrations/0001_init.sql`.- **`ComputerRelay`** (`src/relay.ts`): one Durable Object per computer (SQLite storage, WebSocketHibernation). It admits device sockets against the host-signed ACL, forwards channel frames it can't- read, reports presence, and holds the offline mailbox. It is reachable only through requests the Worker+ read, reports presence, holds the offline mailbox, and queues routine webhook deliveries (`hookbox`,+ checked against the keys the host registers; `src/hooks.ts`). It is reachable only through requests the Workerbuilds itself (`X-Codync-Internal: 1`); `/internal/*` has no public route.- **Auth** (`src/auth.ts`): Clerk session JWTs via `@clerk/backend` (`CLERK_SECRET_KEY` → JWKS fetched andcached per isolate; `CLERK_JWT_KEY` → networkless, dev/e2e only) and Ed25519 request signatures@@ -63,6 +65,8 @@ npx wrangler deploy --env dev # → https://dev-api.codync.devNew computers are limited to 10 per IP per minute with the Workers Rate Limiting binding`REGISTER_LIMITER` (`[[ratelimits]]`; each environment needs its own `namespace_id`).+Public routine webhook deliveries are limited to 60 per sender IP and hook per minute with+`HOOK_LIMITER` (same binding kind, its own `namespace_id` per environment).## Remote screen relaydiff --git a/cloud/src/api.ts b/cloud/src/api.tsindex 6e322d15..ac801853 100644--- a/cloud/src/api.ts+++ b/cloud/src/api.ts@@ -15,6 +15,7 @@ import {verifySig,type SignedRequest,} from "./auth";+import { HOOK_ID, HOOK_MAX_BODY } from "./hooks";import type { Env } from "./index";export const VERSION = "2.2.0";@@ -40,6 +41,7 @@ const STATUS: Record<string, number> = {claimExpired: 410,requestExpired: 410,upgradeRequired: 426,+ tooLarge: 413,rateLimited: 429,internal: 500,};@@ -899,6 +901,30 @@ export async function relayDevice(c: Ctx, [computerId]: string[]): Promise<Resporeturn forward(c, computerId!, "device", s, pair);}+// ---- routine webhooks (§7.8) ----++/**+ * `POST /v1/hooks/:computerId/:hookId`: a public delivery for one of the computer's routines. The+ * computer's DO checks the key and queues it for the host; the host checks again before it runs.+ */+export async function routineHook(c: Ctx, [computerId, hookId]: string[]): Promise<Response> {+ if (!COMPUTER_ID.test(computerId!) || !HOOK_ID.test(hookId!)) throw new ApiError("notFound");+ if (c.raw.length > HOOK_MAX_BODY) throw new ApiError("tooLarge", "Deliveries are limited to 64 KB");+ if (c.env.HOOK_LIMITER) {+ const ip = c.req.headers.get("CF-Connecting-IP") ?? "unknown";+ if (!(await c.env.HOOK_LIMITER.limit({ key: `${ip}|${computerId}/${hookId}` })).success) throw new ApiError("rateLimited");+ }+ // Only registered computers get a DO; random IDs never create one.+ const row = await c.env.DB.prepare("SELECT status FROM computers WHERE id = ?").bind(computerId).first<{ status: string }>();+ if (!row || row.status !== "active") throw new ApiError("notFound");+ const headers = new Headers(c.req.headers);+ headers.set("X-Codync-Internal", "1");+ headers.set("X-Codync-Hook", hookId!);+ return c.env.RELAY.get(c.env.RELAY.idFromName(computerId!)).fetch(+ new Request("https://do/internal/hook", { method: "POST", headers, body: c.raw }),+ );+}+// ---- webhooks ----export async function clerkWebhook(c: Ctx) {diff --git a/cloud/src/hooks.ts b/cloud/src/hooks.tsnew file mode 100644index 00000000..ebb7adcb--- /dev/null+++ b/cloud/src/hooks.ts@@ -0,0 +1,88 @@+// Public routine webhooks (spec §7.8): the checks a delivery passes before it is queued for the host.+//+// The host registers each webhook routine's id and key over its relay socket. A sender proves it holds+// the key with `Authorization: Bearer <key>` or, for GitHub and compatible senders, an+// `X-Hub-Signature-256` HMAC of the body. The host checks the same proof again before running anything.++import { utf8 } from "./auth";++export const HOOK_ID = /^[A-Za-z0-9_-]{1,64}$/;+export const HOOK_MAX_BODY = 64 * 1024;+const KEY_MIN = 32;+const KEY_MAX = 256;+const DELIVERY_MAX = 200;++/** Headers the host gets with a delivery; everything else stays at the edge. */+export const FORWARDED_HEADERS = [+ "authorization",+ "content-type",+ "user-agent",+ "x-delivery-id",+ "idempotency-key",+ "x-github-event",+ "x-github-delivery",+ "x-github-hook-id",+ "x-hub-signature-256",+] as const;++export interface Hook {+ id: string;+ key: string;+ enabled: boolean;+}++/** Shape-checks the host's `hooks` list; `null` when any entry is malformed. */+export function parseHooks(v: unknown, max: number): Hook[] | null {+ if (!Array.isArray(v) || v.length > max) return null;+ const out: Hook[] = [];+ const seen = new Set<string>();+ for (const h of v) {+ if (!h || typeof h !== "object") return null;+ const { id, key, enabled } = h as Record<string, unknown>;+ if (typeof id !== "string" || !HOOK_ID.test(id) || seen.has(id)) return null;+ if (typeof key !== "string" || key.length < KEY_MIN || key.length > KEY_MAX) return null;+ if (typeof enabled !== "boolean") return null;+ seen.add(id);+ out.push({ id, key, enabled });+ }+ return out;+}++function equal(a: Uint8Array, b: Uint8Array): boolean {+ if (a.length !== b.length) return false;+ return crypto.subtle.timingSafeEqual(a, b);+}++function fromHex(s: string): Uint8Array | null {+ if (!/^(?:[0-9a-f]{2})+$/i.test(s)) return null;+ return Uint8Array.from(s.match(/../g)!.map((b) => parseInt(b, 16)));+}++/** Bearer key or `X-Hub-Signature-256: sha256=<hex HMAC-SHA256(key, body)>`. */+export async function authorized(key: string, headers: Headers, body: Uint8Array): Promise<boolean> {+ const bearer = /^Bearer (.+)$/.exec(headers.get("authorization") ?? "")?.[1];+ if (bearer !== undefined && equal(utf8(bearer), utf8(key))) return true;+ const sig = /^sha256=([0-9a-fA-F]{64})$/.exec(headers.get("x-hub-signature-256") ?? "")?.[1];+ if (sig === undefined) return false;+ const mac = await crypto.subtle.importKey("raw", utf8(key), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);+ return crypto.subtle.verify("HMAC", mac, fromHex(sig)!, body);+}++/**+ * The sender's delivery id (retries reuse it, so the queue and the host can drop duplicates), or a+ * fresh one. `null` when the sender's id is unusable.+ */+export function deliveryId(headers: Headers): string | null {+ const given = headers.get("x-delivery-id") ?? headers.get("x-github-delivery") ?? headers.get("idempotency-key");+ if (given === null) return crypto.randomUUID();+ return given.length > 0 && given.length <= DELIVERY_MAX && /^[\x21-\x7e]+$/.test(given) ? given : null;+}++export function forwarded(headers: Headers): Record<string, string> {+ const out: Record<string, string> = {};+ for (const name of FORWARDED_HEADERS) {+ const v = headers.get(name);+ if (v !== null) out[name] = v;+ }+ return out;+}diff --git a/cloud/src/index.ts b/cloud/src/index.tsindex 2ab0e840..394f3329 100644--- a/cloud/src/index.ts+++ b/cloud/src/index.ts@@ -17,6 +17,8 @@ export interface Env {TURN_KEY_ID?: string;TURN_KEY_API_TOKEN?: string;TURN_LIMITER?: RateLimit;+ /** Public routine webhook deliveries per sender IP and hook. */+ HOOK_LIMITER?: RateLimit;CLERK_ISSUER: string;CLERK_SECRET_KEY?: string;/** dev / e2e only: networkless verification with this public key. */@@ -27,6 +29,9 @@ export interface Env {type Handler = (c: Ctx, params: string[]) => Promise<unknown>;+/** Above every route's own limit (64 KB bodies); the routes check theirs. */+const MAX_REQUEST = 128 * 1024;+const ID = "([A-Za-z0-9_-]{1,64})";const routes: [string, RegExp, Handler][] = [["GET", /^\/v1\/health$/, api.health],@@ -57,6 +62,7 @@ const routes: [string, RegExp, Handler][] = [// Any segment reaches the handler so a malformed computerId gets its 400 (§7.1).["GET", /^\/v1\/relay\/device\/([^/]+)$/, api.relayDevice],["POST", /^\/v1\/webhooks\/clerk$/, api.clerkWebhook],+ ["POST", new RegExp(`^/v1/hooks/${ID}/${ID}$`), api.routineHook],];export default {@@ -67,7 +73,10 @@ export default {for (const [method, pattern, handler] of routes) {const m = pattern.exec(url.pathname);if (!m || req.method !== method) continue;+ // Every route takes small bodies; refuse a big one before reading it.+ if (Number(req.headers.get("content-length") ?? 0) > MAX_REQUEST) throw new ApiError("tooLarge");const raw = new Uint8Array(await req.arrayBuffer());+ if (raw.length > MAX_REQUEST) throw new ApiError("tooLarge");const out = await handler({ req, env, exec, url, raw, now: Date.now() }, m.slice(1));return out instanceof Response ? out : Response.json(out);}diff --git a/cloud/src/relay.ts b/cloud/src/relay.tsindex 4b6edee1..c2413c28 100644--- a/cloud/src/relay.ts+++ b/cloud/src/relay.ts@@ -1,11 +1,13 @@// ComputerRelay: one Durable Object per computer (spec §7, §8.5).//// Presence, ciphertext forwarding between the host socket and device sockets, ACL admission, and the-// offline mailbox (device → host). It never parses channel frames and never stores chat. Reached only-// through requests the Worker builds itself (`X-Codync-Internal: 1`), never a client's own request.+// offline mailbox (device → host), and the queue of public routine webhook deliveries (§7.8). It never+// parses channel frames and never stores chat. Reached only through requests the Worker builds itself+// (`X-Codync-Internal: 1`), never a client's own request.import { DurableObject } from "cloudflare:workers";import { b64url, fromB64url, NONCE_TTL_MS, randomId, utf8, verifyEd25519 } from "./auth";+import { authorized, deliveryId, forwarded, HOOK_ID, HOOK_MAX_BODY, parseHooks } from "./hooks";import type { Env } from "./index";const MAX_DEVICE_SOCKETS = 16;@@ -20,6 +22,13 @@ const MBOX_PER_DEVICE = 50;const MBOX_PER_COMPUTER = 500;const MBOX_MAX_BYTES = 8 * 1024 * 1024;const MBOX_TTL_MS = 24 * 3600_000;+const MAX_HOOKS = 1000;+const HOOK_TTL_MS = 72 * 3600_000;+const HOOK_PER_HOOK = 100;+const HOOK_PER_COMPUTER = 1000;+const HOOK_MAX_BYTES = 16 * 1024 * 1024;+const HOOK_RETRY_MIN_MS = 30_000;+const HOOK_RETRY_MAX_MS = 15 * 60_000;const HOST_TIMEOUT_MS = 90_000;const ALARM_MS = 60_000;/** epk(32) ‖ sig(64) ‖ ciphertext with at least its 16-byte tag (§6.4). */@@ -108,6 +117,11 @@ export class ComputerRelay extends DurableObject<Env> {size INTEGER, exp INTEGER, state TEXT, UNIQUE(dk, nonce));CREATE TABLE IF NOT EXISTS nonces(kid TEXT, nonce TEXT, exp INTEGER, PRIMARY KEY(kid, nonce));CREATE TABLE IF NOT EXISTS blocked(dk TEXT PRIMARY KEY, grant_id TEXT, blocked_at INTEGER);+ CREATE TABLE IF NOT EXISTS hooks(id TEXT PRIMARY KEY, key TEXT NOT NULL, enabled INTEGER NOT NULL);+ CREATE TABLE IF NOT EXISTS hookbox(seq INTEGER PRIMARY KEY AUTOINCREMENT, hook TEXT NOT NULL,+ delivery TEXT NOT NULL, headers TEXT NOT NULL, body BLOB NOT NULL, size INTEGER NOT NULL, at INTEGER NOT NULL,+ exp INTEGER NOT NULL, state TEXT NOT NULL, attempts INTEGER NOT NULL DEFAULT 0,+ not_before INTEGER NOT NULL DEFAULT 0, UNIQUE(hook, delivery));`);ctx.setWebSocketAutoResponse(new WebSocketRequestResponsePair(PING, PONG));}@@ -119,6 +133,7 @@ export class ComputerRelay extends DurableObject<Env> {const { pathname } = new URL(req.url);if (pathname === "/relay") return this.relay(req);if (pathname === "/internal/block" && req.method === "POST") return this.block(req);+ if (pathname === "/internal/hook" && req.method === "POST") return this.hook(req);if (pathname === "/internal/changed" && req.method === "POST") {this.toHosts({ t: "cloud.changed" });return Response.json({});@@ -219,6 +234,108 @@ export class ComputerRelay extends DurableObject<Env> {return Response.json({});}+ // ---- routine webhooks (§7.8) ----++ /**+ * `POST /internal/hook` with the sender's body and forwarded headers, `X-Codync-Hook: <id>`.+ * 401 for an unknown hook or a wrong key alike, so hook ids can't be probed.+ */+ private async hook(req: Request): Promise<Response> {+ const id = req.headers.get("X-Codync-Hook") ?? "";+ const body = new Uint8Array(await req.arrayBuffer());+ if (!HOOK_ID.test(id)) return errorResponse(400, "badRequest");+ if (body.length > HOOK_MAX_BODY) return errorResponse(413, "tooLarge");+ const hook = this.sql.exec<{ key: string; enabled: number }>("SELECT key, enabled FROM hooks WHERE id = ?", id).toArray()[0];+ if (!hook || !(await authorized(hook.key, req.headers, body))) return errorResponse(401, "unauthorized");+ if (!hook.enabled) return errorResponse(409, "paused");+ const delivery = deliveryId(req.headers);+ if (delivery === null) return errorResponse(400, "badDeliveryId");+ const now = Date.now();+ const dup = this.sql.exec("SELECT 1 FROM hookbox WHERE hook = ? AND delivery = ?", id, delivery).toArray().length > 0;+ if (dup) return Response.json({ delivery, queued: true, duplicate: true }, { status: 202 });+ const mine = this.sql.exec<{ n: number }>("SELECT COUNT(*) AS n FROM hookbox WHERE hook = ?", id).one().n;+ const all = this.sql.exec<{ n: number; b: number }>("SELECT COUNT(*) AS n, COALESCE(SUM(size), 0) AS b FROM hookbox").one();+ if (mine >= HOOK_PER_HOOK || all.n >= HOOK_PER_COMPUTER || all.b + body.length > HOOK_MAX_BYTES) {+ return Response.json({ error: { code: "full" } }, { status: 429, headers: { "Retry-After": "60" } });+ }+ this.sql.exec(+ "INSERT INTO hookbox(hook, delivery, headers, body, size, at, exp, state) VALUES (?, ?, ?, ?, ?, ?, ?, 'queued')",+ id,+ delivery,+ JSON.stringify(forwarded(req.headers)),+ body.slice().buffer,+ body.length,+ now,+ now + HOOK_TTL_MS,+ );+ const host = this.readyHost();+ if (host) this.deliverHook(host, now);+ await this.ensureAlarm(now + ALARM_MS);+ return Response.json({ delivery, queued: true }, { status: 202 });+ }++ /** `{"t":"hooks","hooks":[{id,key,enabled}]}`: the host's whole current set replaces the stored one. */+ private onHooks(ws: WebSocket, msg: Msg): void {+ const hooks = parseHooks(msg.hooks, MAX_HOOKS);+ if (!hooks) return send(ws, JSON.stringify({ t: "error", code: "badHooks" }));+ this.ctx.storage.transactionSync(() => {+ this.sql.exec("DELETE FROM hooks");+ for (const h of hooks) this.sql.exec("INSERT INTO hooks(id, key, enabled) VALUES (?, ?, ?)", h.id, h.key, h.enabled ? 1 : 0);+ // Deliveries for a removed hook can't run any more; in-flight ones finish with their ack.+ this.sql.exec("DELETE FROM hookbox WHERE state = 'queued' AND hook NOT IN (SELECT id FROM hooks)");+ });+ send(ws, JSON.stringify({ t: "hooks.ok", n: hooks.length }));+ }++ /** `{"t":"hook.ack","seq","ok","retry"?}`: done, refused for good, or try again later. */+ private async onHookAck(ws: WebSocket, msg: Msg, now: number): Promise<void> {+ const row = this.sql+ .exec<{ attempts: number }>("SELECT attempts FROM hookbox WHERE seq = ? AND state = 'delivering'", Number(msg.seq))+ .toArray()[0];+ if (row) {+ if (msg.ok !== true && msg.retry === true) {+ const wait = Math.min(HOOK_RETRY_MIN_MS * 2 ** row.attempts, HOOK_RETRY_MAX_MS);+ this.sql.exec(+ "UPDATE hookbox SET state = 'queued', attempts = attempts + 1, not_before = ? WHERE seq = ?",+ now + wait,+ Number(msg.seq),+ );+ await this.ensureAlarm(now + wait);+ } else {+ this.sql.exec("DELETE FROM hookbox WHERE seq = ?", Number(msg.seq));+ }+ }+ this.deliverHook(ws, now);+ }++ /** One delivery in flight at a time, oldest first, skipping ones waiting out a retry. */+ private deliverHook(host: WebSocket, now: number): void {+ const a = host.deserializeAttachment() as HostAttachment;+ if (!a.ready) return;+ if (this.sql.exec("SELECT 1 FROM hookbox WHERE state = 'delivering'").toArray().length) return;+ const row = this.sql+ .exec<{ seq: number; hook: string; delivery: string; headers: string; body: ArrayBuffer; at: number }>(+ "SELECT seq, hook, delivery, headers, body, at FROM hookbox WHERE state = 'queued' AND exp > ? AND not_before <= ? ORDER BY seq LIMIT 1",+ now,+ now,+ )+ .toArray()[0];+ if (!row) return;+ this.sql.exec("UPDATE hookbox SET state = 'delivering' WHERE seq = ?", row.seq);+ send(+ host,+ JSON.stringify({+ t: "hook.item",+ seq: row.seq,+ hook: row.hook,+ delivery: row.delivery,+ headers: JSON.parse(row.headers),+ body: b64url(new Uint8Array(row.body)),+ at: row.at,+ }),+ );+ }+// ---- messages ----override async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void> {@@ -252,6 +369,7 @@ export class ComputerRelay extends DurableObject<Env> {send(ws, JSON.stringify({ t: "open", link: d.link, dk: d.dk, pair: d.pair }));}this.deliverNext(ws, now);+ this.deliverHook(ws, now);return;}case "data": {@@ -267,6 +385,10 @@ export class ComputerRelay extends DurableObject<Env> {}case "mbox.ack":return this.onAck(ws, msg, now);+ case "hooks":+ return this.onHooks(ws, msg);+ case "hook.ack":+ return this.onHookAck(ws, msg, now);case "ping":return send(ws, PONG);default:@@ -470,7 +592,10 @@ export class ComputerRelay extends DurableObject<Env> {this.toDevice(row.dk, { t: "mbox.expired", nonce: row.nonce });}this.sql.exec("DELETE FROM mailbox WHERE exp <= ?", now);+ this.sql.exec("DELETE FROM hookbox WHERE exp <= ? AND state = 'queued'", now);this.sql.exec("DELETE FROM nonces WHERE exp <= ?", now);+ const host = this.readyHost();+ if (host) this.deliverHook(host, now);const acl = this.acl();let next = now + ALARM_MS;@@ -480,8 +605,15 @@ export class ComputerRelay extends DurableObject<Env> {if (exp <= now) this.safeClose(ws, 4410, "pairingExpired");else next = Math.min(next, exp);}+ // A delivery waiting out its retry wakes the DO when it's due.+ const due = this.sql+ .exec<{ t: number | null }>("SELECT MIN(not_before) AS t FROM hookbox WHERE state = 'queued' AND not_before > ?", now)+ .one().t;+ if (due !== null) next = Math.min(next, due);const busy =- this.ctx.getWebSockets().length > 0 || this.sql.exec("SELECT 1 FROM mailbox LIMIT 1").toArray().length > 0;+ this.ctx.getWebSockets().length > 0 ||+ this.sql.exec("SELECT 1 FROM mailbox LIMIT 1").toArray().length > 0 ||+ this.sql.exec("SELECT 1 FROM hookbox LIMIT 1").toArray().length > 0;if (busy) await this.ctx.storage.setAlarm(next);}@@ -489,6 +621,7 @@ export class ComputerRelay extends DurableObject<Env> {private async hostOffline(now: number, exclude?: WebSocket): Promise<void> {this.setMeta("lastSeenAt", String(now));this.sql.exec("UPDATE mailbox SET state = 'queued' WHERE state = 'delivering'");+ this.sql.exec("UPDATE hookbox SET state = 'queued' WHERE state = 'delivering'");if (!this.readyHost(exclude)) {const presence = JSON.stringify(this.presence(exclude));for (const [ws] of this.devices()) send(ws, presence);diff --git a/cloud/test/e2e/relay.e2e.ts b/cloud/test/e2e/relay.e2e.tsindex 8ca43ce0..d46f856e 100644--- a/cloud/test/e2e/relay.e2e.ts+++ b/cloud/test/e2e/relay.e2e.ts@@ -204,6 +204,47 @@ async function main() {});check(!history.entries.some((e: Json) => e.data?.clientNonce === "e2e-mbox-2"), "the cancelled message never ran");+ step("5b. public routine webhooks through the cloud");+ const hookRoutine = async (name: string) =>+ (await loopback("saveRoutine", { botId: bot, name, instruction: "Summarize the delivery", triggers: [{ type: "webhook" }] })).routine.id as string;+ const runFor = (routine: string, delivery: string) => async () =>+ ((await loopback("routines", { botId: bot })).runs as Json[]).find((r) => r.routineId === routine && r.deliveryId === delivery);+ const live = await hookRoutine("Live hook");+ const creds = await loopback("routineWebhook", { botId: bot, id: live });+ check(creds.url === `${CLOUD}/v1/hooks/${computerId}/${live}`, "public URL names this computer and routine");+ // The host registers its hooks right after it comes online; give the set a moment to land.+ const deliver = (url: string, headers: Record<string, string>, body: string) =>+ fetch(url, { method: "POST", headers: { "Content-Type": "application/json", ...headers }, body });+ await waitFor("hook registered", async () => (await deliver(creds.url, { Authorization: "Bearer nope" }, "{}")).status === 401 || undefined);+ const accepted = await waitFor("bearer delivery accepted", async () => {+ const res = await deliver(creds.url, { Authorization: `Bearer ${creds.key}`, "X-Delivery-Id": "e2e-hook-1" }, '{"text":"build failed"}');+ return res.status === 202 ? res : undefined;+ });+ check(accepted.status === 202, "bearer delivery queued (202)");+ const run1 = await waitFor("run from the public delivery", runFor(live, "e2e-hook-1"), 20_000);+ check(run1.event?.text === "build failed", "the run carries the delivered event");+ check((await deliver(creds.url, { Authorization: "Bearer wrong" }, "{}")).status === 401, "a wrong key is refused at the edge");++ const offline = await hookRoutine("Offline hook");+ const offCreds = await loopback("routineWebhook", { botId: bot, id: offline });+ await waitFor("second hook registered", async () =>+ (await deliver(offCreds.url, { Authorization: "Bearer nope" }, "{}")).status === 401 || undefined,+ );+ await stop(host!);+ const ghBody = '{"action":"opened","pull_request":{"title":"Add hooks"},"repository":{"full_name":"o/r"}}';+ const mac = await crypto.subtle.sign(+ "HMAC",+ await crypto.subtle.importKey("raw", ref.enc.encode(offCreds.key), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]),+ ref.enc.encode(ghBody),+ );+ const sig = `sha256=${Buffer.from(mac).toString("hex")}`;+ const queued = await deliver(offCreds.url, { "X-GitHub-Event": "pull_request", "X-GitHub-Delivery": "e2e-gh-1", "X-Hub-Signature-256": sig }, ghBody);+ check(queued.status === 202, "a signed GitHub delivery is queued while the host is down");+ await startHost();+ const run2 = await waitFor("run after the host came back", runFor(offline, "e2e-gh-1"), 30_000);+ check(run2.event?.event === "pull_request.opened" && run2.event?.repo === "o/r", "delivered once the host is back, as a GitHub event");+ ch = await Channel.open(ch.wire, phone.key, pairing.signKey, { relay: true });+step("6. account: claim, access request with SAS, revocation");const userId = "user_e2e";const token = await clerkToken(userId);diff --git a/cloud/test/hooks.test.ts b/cloud/test/hooks.test.tsnew file mode 100644index 00000000..eba5d5c0--- /dev/null+++ b/cloud/test/hooks.test.ts@@ -0,0 +1,172 @@+// Public routine webhooks (§7.8): ingress checks, the per-computer queue, delivery to the host and acks.++import { runDurableObjectAlarm, runInDurableObject, SELF } from "cloudflare:test";+import { describe, expect, it } from "vitest";+import type { ComputerRelay } from "../src/relay";+import { env, hostSocket, newHost, ORIGIN, type TestHost } from "./helpers";++const KEY = "k".repeat(64);+const stub = (host: TestHost) => env.RELAY.get(env.RELAY.idFromName(host.cid)) as DurableObjectStub<ComputerRelay>;++async function post(host: TestHost, hook: string, o: { body?: string; headers?: Record<string, string> } = {}) {+ const res = await SELF.fetch(`${ORIGIN}/v1/hooks/${host.cid}/${hook}`, {+ method: "POST",+ headers: { "Content-Type": "application/json", "CF-Connecting-IP": `10.1.${Math.floor(Math.random() * 255)}.1`, ...o.headers },+ body: o.body ?? '{"text":"hi"}',+ });+ return { status: res.status, body: (await res.json()) as Record<string, unknown> & { error?: { code: string } } };+}++const bearer = (key = KEY) => ({ Authorization: `Bearer ${key}` });++async function hmac(key: string, body: string): Promise<string> {+ const k = await crypto.subtle.importKey("raw", new TextEncoder().encode(key), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);+ const mac = new Uint8Array(await crypto.subtle.sign("HMAC", k, new TextEncoder().encode(body)));+ return `sha256=${[...mac].map((b) => b.toString(16).padStart(2, "0")).join("")}`;+}++/** A ready host that registered `hooks`. */+async function withHooks(hooks: { id: string; key?: string; enabled?: boolean }[], o: { ready?: boolean } = {}) {+ const host = await newHost();+ const ws = await hostSocket(host, [], o);+ ws.send({ t: "hooks", hooks: hooks.map((h) => ({ id: h.id, key: h.key ?? KEY, enabled: h.enabled ?? true })) });+ expect(await ws.nextT("hooks.ok")).toEqual({ t: "hooks.ok", n: hooks.length });+ return { host, ws };+}++const decode = (b64: string) => new TextDecoder().decode(Uint8Array.from(atob(b64.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0)));++describe("ingress", () => {+ it("refuses unknown computers, unknown hooks and wrong keys alike", async () => {+ const { host } = await withHooks([{ id: "r1" }]);+ expect((await post({ ...host, cid: "A".repeat(22) }, "r1", { headers: bearer() })).status).toBe(404);+ expect((await post(host, "bad id!", { headers: bearer() })).status).toBe(404);+ const unknown = await post(host, "r2", { headers: bearer() });+ const wrong = await post(host, "r1", { headers: bearer("x".repeat(64)) });+ const missing = await post(host, "r1");+ for (const r of [unknown, wrong, missing]) {+ expect(r.status).toBe(401);+ expect(r.body.error?.code).toBe("unauthorized");+ }+ });++ it("accepts a bearer key or a GitHub signature of the exact body", async () => {+ const { host } = await withHooks([{ id: "r1" }]);+ expect((await post(host, "r1", { headers: bearer() })).status).toBe(202);+ const body = '{"action":"opened"}';+ expect((await post(host, "r1", { body, headers: { "X-Hub-Signature-256": await hmac(KEY, body) } })).status).toBe(202);+ expect((await post(host, "r1", { body: `${body} `, headers: { "X-Hub-Signature-256": await hmac(KEY, body) } })).status).toBe(401);+ expect((await post(host, "r1", { body, headers: { "X-Hub-Signature-256": await hmac("y".repeat(64), body) } })).status).toBe(401);+ expect((await post(host, "r1", { body, headers: { "X-Hub-Signature-256": "sha256=zz" } })).status).toBe(401);+ });++ it("refuses paused hooks, oversized bodies and unusable delivery ids", async () => {+ const { host } = await withHooks([{ id: "off", enabled: false }, { id: "on" }]);+ const paused = await post(host, "off", { headers: bearer() });+ expect(paused.status).toBe(409);+ expect(paused.body.error?.code).toBe("paused");+ expect((await post(host, "on", { headers: bearer(), body: "x".repeat(64 * 1024 + 1) })).status).toBe(413);+ expect((await post(host, "on", { headers: { ...bearer(), "X-Delivery-Id": "has space" } })).status).toBe(400);+ });++ it("queues each delivery id once", async () => {+ const { host } = await withHooks([{ id: "r1" }], { ready: false });+ const first = await post(host, "r1", { headers: { ...bearer(), "X-GitHub-Delivery": "d-1" } });+ expect(first).toEqual({ status: 202, body: { delivery: "d-1", queued: true } });+ const again = await post(host, "r1", { headers: { ...bearer(), "X-GitHub-Delivery": "d-1" } });+ expect(again.body).toEqual({ delivery: "d-1", queued: true, duplicate: true });+ });++ it("caps a hook's queue at 100", async () => {+ const { host } = await withHooks([{ id: "r1" }], { ready: false });+ for (let i = 0; i < 100; i++) expect((await post(host, "r1", { headers: bearer() })).status).toBe(202);+ const full = await post(host, "r1", { headers: bearer() });+ expect(full.status).toBe(429);+ expect(full.body.error?.code).toBe("full");+ });+});++describe("delivery", () => {+ it("hands the host one delivery at a time with its body and forwarded headers", async () => {+ const { host, ws } = await withHooks([{ id: "r1" }]);+ await post(host, "r1", { body: '{"n":1}', headers: { ...bearer(), "X-Delivery-Id": "a", "X-GitHub-Event": "push", Cookie: "secret" } });+ await post(host, "r1", { body: '{"n":2}', headers: { ...bearer(), "X-Delivery-Id": "b" } });+ const item = await ws.nextT("hook.item");+ expect(item).toMatchObject({ t: "hook.item", hook: "r1", delivery: "a" });+ expect(decode(item.body)).toBe('{"n":1}');+ expect(item.headers).toMatchObject({ authorization: `Bearer ${KEY}`, "x-github-event": "push", "x-delivery-id": "a" });+ expect(item.headers.cookie).toBeUndefined();+ await ws.none((m) => m.t === "hook.item");+ ws.send({ t: "hook.ack", seq: item.seq, ok: true });+ const next = await ws.nextT("hook.item");+ expect(next.delivery).toBe("b");+ ws.send({ t: "hook.ack", seq: next.seq, ok: true });+ await ws.none((m) => m.t === "hook.item");+ });++ it("keeps deliveries while the host is away and sends them once it is ready", async () => {+ const { host, ws } = await withHooks([{ id: "r1" }], { ready: false });+ await post(host, "r1", { headers: { ...bearer(), "X-Delivery-Id": "while-away" } });+ await ws.none((m) => m.t === "hook.item");+ ws.send({ t: "ready" });+ expect((await ws.nextT("hook.item")).delivery).toBe("while-away");+ });++ it("puts an unacknowledged delivery back when the host drops", async () => {+ const { host, ws } = await withHooks([{ id: "r1" }]);+ await post(host, "r1", { headers: { ...bearer(), "X-Delivery-Id": "x" } });+ await ws.nextT("hook.item");+ ws.ws.close(1000);+ const again = await hostSocket(host);+ expect((await again.nextT("hook.item")).delivery).toBe("x");+ });++ it("retries a busy delivery later without holding up the others", async () => {+ const { host, ws } = await withHooks([{ id: "r1" }, { id: "r2" }]);+ await post(host, "r1", { headers: { ...bearer(), "X-Delivery-Id": "busy" } });+ await post(host, "r2", { headers: { ...bearer(), "X-Delivery-Id": "other" } });+ const busy = await ws.nextT("hook.item");+ ws.send({ t: "hook.ack", seq: busy.seq, ok: false, retry: true });+ const other = await ws.nextT("hook.item");+ expect(other.delivery).toBe("other");+ ws.send({ t: "hook.ack", seq: other.seq, ok: true });+ await ws.none((m) => m.t === "hook.item");+ // Due again: the alarm hands it back.+ await stubSql(host, "UPDATE hookbox SET not_before = 0");+ await runDurableObjectAlarm(stub(host));+ expect((await ws.nextT("hook.item")).delivery).toBe("busy");+ });++ it("drops a refused delivery and queued ones of removed hooks", async () => {+ const { host, ws } = await withHooks([{ id: "r1" }, { id: "r2" }]);+ await post(host, "r1", { headers: { ...bearer(), "X-Delivery-Id": "one" } });+ await post(host, "r2", { headers: { ...bearer(), "X-Delivery-Id": "gone" } });+ const one = await ws.nextT("hook.item");+ ws.send({ t: "hooks", hooks: [{ id: "r1", key: KEY, enabled: true }] });+ await ws.nextT("hooks.ok");+ ws.send({ t: "hook.ack", seq: one.seq, ok: false, code: "unauthorized" });+ await ws.none((m) => m.t === "hook.item");+ expect((await post(host, "r2", { headers: bearer() })).status).toBe(401);+ });++ it("rejects a malformed hooks list and keeps the stored one", async () => {+ const { host, ws } = await withHooks([{ id: "r1" }]);+ for (const hooks of [[{ id: "r1", key: "short", enabled: true }], [{ id: "r1", key: KEY }], "nope", [{ id: "r1", key: KEY, enabled: true }, { id: "r1", key: KEY, enabled: true }]]) {+ ws.send({ t: "hooks", hooks });+ expect(await ws.nextT("error")).toEqual({ t: "error", code: "badHooks" });+ }+ expect((await post(host, "r1", { headers: bearer() })).status).toBe(202);+ });++ it("expires queued deliveries after 72 hours", async () => {+ const { host } = await withHooks([{ id: "r1" }], { ready: false });+ await post(host, "r1", { headers: bearer() });+ await stubSql(host, "UPDATE hookbox SET exp = 1");+ await runDurableObjectAlarm(stub(host));+ expect(await stubSql(host, "SELECT COUNT(*) AS n FROM hookbox")).toEqual([{ n: 0 }]);+ });+});++function stubSql(host: TestHost, query: string): Promise<unknown[]> {+ return runInDurableObject(stub(host), (_obj, state) => state.storage.sql.exec(query).toArray());+}diff --git a/cloud/wrangler.toml b/cloud/wrangler.tomlindex 2ced8879..86156202 100644--- a/cloud/wrangler.toml+++ b/cloud/wrangler.toml@@ -35,6 +35,12 @@ name = "TURN_LIMITER"namespace_id = "1011"simple = { limit = 12, period = 60 }+# Public routine webhook deliveries per sender IP and hook (POST /v1/hooks/...).+[[ratelimits]]+name = "HOOK_LIMITER"+namespace_id = "1021"+simple = { limit = 60, period = 60 }+[triggers]crons = ["*/15 * * * *"]@@ -45,7 +51,7 @@ routes = [{ pattern = "dev-api.codync.dev", custom_domain = true }]vars = { CLERK_ISSUER = "https://sunny-mollusk-8651.clerk.accounts.dev" }d1_databases = [{ binding = "DB", database_name = "codync-dev", database_id = "0c03c398-3cec-4f06-a76e-998176ca19ae", migrations_dir = "migrations" }]durable_objects.bindings = [{ name = "RELAY", class_name = "ComputerRelay" }]-ratelimits = [{ name = "REGISTER_LIMITER", namespace_id = "1002", simple = { limit = 10, period = 60 } }, { name = "TURN_LIMITER", namespace_id = "1012", simple = { limit = 12, period = 60 } }]+ratelimits = [{ name = "REGISTER_LIMITER", namespace_id = "1002", simple = { limit = 10, period = 60 } }, { name = "TURN_LIMITER", namespace_id = "1012", simple = { limit = 12, period = 60 } }, { name = "HOOK_LIMITER", namespace_id = "1022", simple = { limit = 60, period = 60 } }]triggers = { crons = ["*/15 * * * *"] }# local: wrangler dev / e2e with a local D1; CLERK_JWT_KEY is injected by the test (--var).@@ -55,4 +61,4 @@ routes = []vars = { CLERK_ISSUER = "https://clerk.test.local" }d1_databases = [{ binding = "DB", database_name = "codync-local", database_id = "local", migrations_dir = "migrations" }]durable_objects.bindings = [{ name = "RELAY", class_name = "ComputerRelay" }]-ratelimits = [{ name = "REGISTER_LIMITER", namespace_id = "1003", simple = { limit = 10, period = 60 } }, { name = "TURN_LIMITER", namespace_id = "1013", simple = { limit = 12, period = 60 } }]+ratelimits = [{ name = "REGISTER_LIMITER", namespace_id = "1003", simple = { limit = 10, period = 60 } }, { name = "TURN_LIMITER", namespace_id = "1013", simple = { limit = 12, period = 60 } }, { name = "HOOK_LIMITER", namespace_id = "1023", simple = { limit = 60, period = 60 } }]diff --git a/docs/reference/remote-relay.md b/docs/reference/remote-relay.mdindex fb7f4ec3..803f21cf 100644--- a/docs/reference/remote-relay.md+++ b/docs/reference/remote-relay.md@@ -371,6 +371,8 @@ Host → DO:| `data` | `link`, `m`(channel 訊息物件) | host 必須 ready;將 `m` 原樣(`JSON.stringify(m)`)送到該 link 的 device socket || `close` | `link`, `code`, `reason` | 關閉該 device socket || `mbox.ack` | `seq`, `ok`(bool), `code`(`ok:false` 時:`unauthorized`/`unknownBot`/`invalid`) | 刪除 mailbox 項目,通知發送裝置 `mbox.delivered` 或 `mbox.failed` |+| `hooks` | `hooks`:`[{"id","key","enabled"}]`(完整集合,≤ 1000) | 取代 DO 存的 webhook 集合(§7.8);格式錯誤 → `{"t":"error","code":"badHooks"}` 且保留舊集合。成功 → `{"t":"hooks.ok","n"}` |+| `hook.ack` | `seq`, `ok`(bool), `retry`(bool), `code` | `ok` 或 `retry:false` → 刪除;`retry:true` → 退回 queued,`not_before = now + min(30 s·2^attempts, 15 min)` || `ping` | — | auto-response |DO → Host:@@ -381,6 +383,8 @@ DO → Host:| `data` | `link`, `m`(device 送來的 channel 訊息物件) || `close` | `link`(device 斷線) || `mbox.item` | `seq`, `from`(dk), `nonce`(clientNonce), `d`(blob b64url), `exp` |+| `hook.item` | `seq`, `hook`(routine id), `delivery`, `headers`(白名單,小寫名), `body`(b64url), `at` |+| `hooks.ok` | `n` || `cloud.changed` | —(Worker 通知:請立刻拉 `/v1/host/state`) || `acl.ok` / `error` | 見上 |@@ -435,6 +439,20 @@ Close code 總表:`1000` 正常、`1011` 內部錯誤/逾時、`4001 unautho- 投遞:host `ready` 後,DO 依 `seq` 遞增逐則送 `mbox.item`(狀態改 `delivering`);host 逐則處理並 `mbox.ack`。host 斷線時 `delivering` 退回 `queued`,重連後重送(host 以 clientNonce 去重)。- TTL 到期 → 刪除 + `mbox.expired`。+### 7.8 公開 routine webhook++讓外部服務(GitHub、監控、腳本)觸發 routine,不需要公網 IP、開 port 或使用者自己的 tunnel:沿用 host 主動連出的 relay socket。++- **網址**:`POST {cloud}/v1/hooks/{computerId}/{routineId}`。Worker 檢查兩個 id 的格式、body ≤ 64 KiB(否則 `413 tooLarge`)、`HOOK_LIMITER`(每「來源 IP + hook」每分鐘 60 次 → `429`)、computer 存在且 `active`(否則 `404`,不為隨機 id 建 DO),再把原 request 轉給該 computer 的 DO `/internal/hook`。+- **註冊**:host 在 `ready` 後送 `hooks`,之後每當集合改變(新增/刪除 webhook routine、暫停/恢復、換 key)就重送整個集合。只含有 `webhook` 或 `event` trigger 的 routine。+- **驗證(DO 一次、host 再一次)**:`Authorization: Bearer <key>`(常數時間比較),或 `X-Hub-Signature-256: sha256=<hex HMAC-SHA256(key, 原始 body)>`(GitHub 與相容服務)。未知 hook 與錯誤 key 一律 `401 unauthorized`,無法探測 id。已暫停 → `409 paused`。host 是最終權威:DO 的集合過期或被竄改時,host 仍會拒絕。+- **去重**:delivery id 取 `X-Delivery-Id`、`X-GitHub-Delivery` 或 `Idempotency-Key`(可列印 ASCII、≤ 200;不合法 → `400 badDeliveryId`;都沒有 → DO 產生 UUID)。DO 以 `(hook, delivery)` 唯一;佇列中的重送回 `202 {"duplicate":true}`。已投遞後的重送由 host 以保留中的 run 紀錄去重。+- **佇列(DO `hookbox`)**:每 hook ≤ 100、每 computer ≤ 1000 則、總計 ≤ 16 MiB(滿 → `429 full`,`Retry-After: 60`);TTL 72 小時。成功入列 → `202 {"delivery","queued":true}`。+- **投遞**:host `ready` 時,DO 依 `seq` 一次送一則 `hook.item`(狀態 `delivering`),跳過 `not_before` 未到的;host 斷線時退回 `queued`。alarm 清除過期項目,並在最早的 `not_before` 喚醒。+- **轉給 host 的 header 白名單**:`authorization`、`content-type`、`user-agent`、`x-delivery-id`、`idempotency-key`、`x-github-event`、`x-github-delivery`、`x-github-hook-id`、`x-hub-signature-256`。+- **Host 處理**(`routines::hooks`):驗證 → GitHub `ping` 回 ok 不執行 → 暫停回 `paused` → 轉成 event(JSON 物件原樣;GitHub → `{source:"github", event:"<event>.<action>", repo, sender, text, url, payload}`;其他 → `{text}`)→ trigger 不符回 ok(忽略)→ 排入 run。routine 正在執行 → `retry:true`。+- **信任邊界**:webhook 內容在 Cloudflare 以 HTTPS 解開,雲端看得到明文,也存著 key(用來驗 HMAC)。這不是 §6 的端對端加密;App 與文件都需明講。+---## 8. Cloud HTTP API@@ -480,6 +498,8 @@ The route table below summarizes the contract. Executable schema and validation- `POST /v1/host/access-requests/{id}/decision` `{"decision":"approve"|"deny"}` → `{"status","grantId"?}`(`cloud/src/api.ts` 的原子更新;request 過期 → `410 requestExpired`;approve 要求 `device_nonce IS NOT NULL`,否則 `409`)- `POST /v1/host/unclaim` `{}` → `{}`(在電腦上移出帳號;同 `DELETE /v1/computers/{id}` 的效果)+**Routine webhook(公開)**:`POST /v1/hooks/{computerId}/{routineId}`,§7.8。+**Relay**:§7.1。**Webhook**:`user.deleted` → accounts `status='deleted'`、devices 撤銷、grants 撤銷(`accountDeleted`)、computers owner=NULL、DO block + changed。## 9. Host integration