Skip to content

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.

feat(cloud): accept public routine webhooks and queue them for the host

leepokai3591351cd7eb
diff --git a/cloud/README.md b/cloud/README.md
index 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, access
requests, 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, WebSocket
Hibernation). 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 Worker
builds 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 and
cached 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.dev
New 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 relay
diff --git a/cloud/src/api.ts b/cloud/src/api.ts
index 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<Respo
return 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.toml
index 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.md
index 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