a2a-exposed 0.8.8 → 0.8.9

package/lib/deploy.mjs

@@ -34,7 +34,8 @@ export const WAKE_SECRETS = ["WAKE_WEBHOOK_URL", "WAKE_WEBHOOK_KEY", "WAKE_HMAC_
 export const UPSTREAM_SECRETS = ["UPSTREAM_TOKEN", "UPSTREAM_ACCESS_CLIENT_ID", "UPSTREAM_ACCESS_CLIENT_SECRET"];
 /** OpenID Connect client secret for approval. Environment only; never config.env. */
 export const OIDC_SECRETS = ["APPROVAL_OIDC_CLIENT_SECRET"];
-const DEPLOY_SECRETS = [...WAKE_SECRETS, ...UPSTREAM_SECRETS, ...OIDC_SECRETS];
+export const EVENT_SECRETS = ["EVENT_SECRET"];
+const DEPLOY_SECRETS = [...WAKE_SECRETS, ...UPSTREAM_SECRETS, ...OIDC_SECRETS, ...EVENT_SECRETS];
 
 // Non-secret deploy settings persisted in config.env and passed to cloudflare.config.ts as env vars.
 const DEPLOY_KEYS = [
@@ -171,7 +172,7 @@ export function wakeSecretsFromEnv() {
 /** Secrets init/deploy upload when exported: the wake secrets plus, for proxy mode, the upstream credentials. */
 export function deploySecretsFromEnv() {
 	const s = wakeSecretsFromEnv();
-	for (const k of [...UPSTREAM_SECRETS, ...OIDC_SECRETS]) if (process.env[k]) s[k] = process.env[k];
+	for (const k of [...UPSTREAM_SECRETS, ...OIDC_SECRETS, ...EVENT_SECRETS]) if (process.env[k]) s[k] = process.env[k];
 	return s;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "a2a-exposed",
-	"version": "0.8.8",
+	"version": "0.8.9",
 	"description": "Give any AI agent a public A2A (Agent2Agent) endpoint: a Cloudflare Worker, a wake webhook, or scheduled checks",
 	"type": "module",
 	"bin": {

package/worker/cloudflare.config.ts

@@ -64,6 +64,8 @@ const plain: Record<string, string> = {
 	APPROVAL_METHODS: v("APPROVAL_METHODS"),
 	// Optional https URL of this agent's dashboard page. A pairing wake and the MCP inbox line include it as manageUrl.
 	MANAGE_URL: v("MANAGE_URL"),
+	// Optional https URL for a signed pairing event. EVENT_SECRET is uploaded as a secret. Both are required for a post.
+	EVENT_URL: v("EVENT_URL"),
 };
 const hosted = v("TENANCY") === "host";
 // Daily R2 snapshots. Unset: no binding and no extra cron, so a self-host deploy stays the single-tenant Worker.
@@ -103,7 +105,8 @@ for (const [k, val] of Object.entries(plain)) if (val !== "" || (k === "WAKE_KEY
 const SECRETS = ["OWNER_TOKEN", "WAKE_WEBHOOK_URL", "WAKE_WEBHOOK_KEY", "WAKE_HMAC_SECRET", "UPSTREAM_TOKEN", "UPSTREAM_ACCESS_CLIENT_ID", "UPSTREAM_ACCESS_CLIENT_SECRET",
 	// Declared for `cf dev` only when a deploy asks for them, so a self-host .dev.vars without these still starts.
 	...(v("TENANCY") === "host" ? ["TENANT_SECRETS_KEY"] : []),
-	...(v("TENANCY") === "host" || v("APPROVAL_OIDC_ISSUER") ? ["APPROVAL_OIDC_CLIENT_SECRET"] : [])];
+	...(v("TENANCY") === "host" || v("APPROVAL_OIDC_ISSUER") ? ["APPROVAL_OIDC_CLIENT_SECRET"] : []),
+	...(v("EVENT_URL") ? ["EVENT_SECRET"] : [])];
 
 export default defineConfig((ctx) => ({
 	...(v("CLOUDFLARE_ACCOUNT_ID") ? { accountId: v("CLOUDFLARE_ACCOUNT_ID") } : {}),

package/worker/deploy.env.example

@@ -47,6 +47,10 @@ WAKE_PRESET=generic
 # Optional https URL of this agent's dashboard page. When set, a pairing wake and the MCP inbox line
 # include it as manageUrl.
 # MANAGE_URL=https://example.com/app/agents/name#pairing
+# Optional pairing event. When EVENT_URL is https and EVENT_SECRET is set, a new request and an
+# approval or denial POST a signed JSON body to that URL. The secret is uploaded on deploy, not stored here.
+# EVENT_URL=https://example.com/api/agent-events
+# Secret (same secrets file, never here): EVENT_SECRET.
 # Daily SQL snapshots to R2. Unset: no BACKUP_BUCKET binding and no extra cron. The minute wake cron stays A2A_ENABLE_CRON.
 # A2A_BACKUP_BUCKET=1
 # A2A_BACKUP_BUCKET_NAME=a2a-exposed-backups

package/worker/src/hosted.ts

@@ -20,7 +20,7 @@ import { bookmarkForTime as readBookmark, exportRows, restoreBookmark as applyBo
 import { hostedDailyBackup } from "./backup.ts";
 import { lookupDirectory, pinDirectoryRegion, tenantNameFromHost, tenantRegion, TENANT_NAME, type DirectoryEntry } from "./directory.ts";
 import { hostedTenantContext, namespaceForRegion, parseGates, type WorkerBindings } from "./tenancy.ts";
-import { WAKE_SECRET_KEYS, openWakeSecrets } from "./wake-secrets.ts";
+import { WAKE_SECRET_KEYS, omitSealedSecrets, openWakeSecrets } from "./wake-secrets.ts";
 
 export { clearDirectoryCache, directoryKey, lookupDirectory, parseDirectoryEntry, pinDirectoryRegion, tenantNameFromHost, tenantRegion, TENANT_NAME } from "./directory.ts";
 export type { DirectoryEntry };
@@ -279,19 +279,20 @@ export class TenantStore extends DurableObject<WorkerBindings> {
 				await this.#enqueueArm(false);
 				return { version: current.version, applied: false };
 			}
-			const config = requireObject(body.config, "config");
 			const limits = requireObject(body.limits, "limits");
 			const approval = requireObject(body.approval, "approval");
+			const secretsEnc = body.secretsEnc ?? null;
+			const storedConfig = omitSealedSecrets(requireObject(body.config, "config"), secretsEnc);
 			const next: StoredConfig = {
 				version: body.version,
 				tenantId: body.tenantId,
 				name: body.name,
 				status: body.status,
-				config: stringRecord(config),
+				config: stringRecord(storedConfig),
 				limits,
 				approval,
 				ownerTokenHash: body.ownerTokenHash ? body.ownerTokenHash.toLowerCase() : null,
-				secretsEnc: body.secretsEnc ?? null,
+				secretsEnc,
 			};
 			const now = new Date().toISOString();
 			this.#tx(() => {
@@ -304,7 +305,7 @@ export class TenantStore extends DurableObject<WorkerBindings> {
 					   config_json = excluded.config_json, limits_json = excluded.limits_json, approval_json = excluded.approval_json,
 					   owner_token_hash = excluded.owner_token_hash, secrets_enc = excluded.secrets_enc, updated_at = excluded.updated_at`,
 					next.version, next.tenantId, next.name, next.status,
-					JSON.stringify(config), JSON.stringify(limits), JSON.stringify(approval),
+					JSON.stringify(storedConfig), JSON.stringify(limits), JSON.stringify(approval),
 					next.ownerTokenHash, next.secretsEnc, now,
 				);
 			});

package/worker/src/index.ts

@@ -11,6 +11,7 @@ import { fetchCheckedWake } from "./wake-target.ts";
 import * as P from "./pairing.ts";
 import * as M from "./mcp.ts";
 import { accountIdOf, DASHBOARD_ACTOR_HEADER, matchOwnerRpc, ownerResponseLeaks, scrubOwnerClaims, type OwnerRpcRequest, type OwnerRpcResult } from "./owner-rpc.ts";
+import { pairingAgent, pairingEventTarget, postPairingEvent } from "./pairing-events.ts";
 import { publicManageUrl, resolveTenant, type TenantContext, type WorkerBindings } from "./tenancy.ts";
 import { exportRows, redactExport, REDACTED_SQL_SKIP, scrubSecretText, toSql } from "./export.ts";
 import { backupDatabase, DAILY_CRON } from "./backup.ts";
@@ -1058,7 +1059,7 @@ async function handleOwner(req: Request, ctx: TenantContext, ectx: ExecutionCont
 			return json({ revoked: true, label });
 		}
 	}
-	if (seg[0] === "pairing") return await ownerPairing(req, ctx, m, seg.slice(1), body, trusted);
+	if (seg[0] === "pairing") return await ownerPairing(req, ctx, ectx, m, seg.slice(1), body, trusted);
 	if (seg[0] === "mcp" && !seg[1] && m === "GET") {
 		const rows = await ctx.DB.prepare("SELECT label, client_id, client_name, redirect_host, scope, created_at, last_used_at, revoked_at, refresh_expires_ms FROM mcp_grants ORDER BY created_at").all();
 		return json({ enabled: mcpOn(ctx), url: oauthUrls(ctx).mcp, grants: (rows.results as Json[]).map((r) => ({ ...r, refresh_expires_ms: undefined,
@@ -1270,13 +1271,15 @@ async function deviceAuthorization(req: Request, ctx: TenantContext, ectx: Execu
 		return oauthError("slow_down", "this A2A endpoint has too many pairing requests waiting; try again later", 429, retry);
 	}
 	const deviceCode = P.newDeviceCode();
+	const deviceHash = await A.sha256(deviceCode);
+	const country = clientCountry(req);
 	let userCode = "";
 	for (let i = 0; i < 5 && !userCode; i++) {
 		const c = P.newUserCode();
 		const r = await ctx.DB.prepare(
 			`INSERT INTO device_requests (device_hash, user_code, client_id, client_name, agent_card_url, ip, country, status, created_ms, expires_ms, interval_s)
 			 VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?, ?) ON CONFLICT DO NOTHING`,
-		).bind(await A.sha256(deviceCode), c, clientId || null, clientName || null, cardUrl || null, ip || null, clientCountry(req) || null,
+		).bind(deviceHash, c, clientId || null, clientName || null, cardUrl || null, ip || null, country || null,
 			now, now + P.EXPIRES_S * 1000, P.INTERVAL_S).run();
 		if (r.meta.changes === 1) userCode = c;
 	}
@@ -1302,6 +1305,8 @@ async function deviceAuthorization(req: Request, ctx: TenantContext, ectx: Execu
 				...(manage ? { manageUrl: manage } : {}),
 				...(replaces ? { replacesLabel: replaces.label } : {}) } });
 	})());
+	publishPairingEvent(ctx, ectx, { type: "pairing_requested", requestId: deviceHash, code: shown, name: clientName, alias: clientId,
+		ip, country, createdAt: new Date(now).toISOString(), expiresAt: new Date(now + P.EXPIRES_S * 1000).toISOString() });
 	return json({ device_code: deviceCode, user_code: shown, verification_uri: u.page, verification_uri_complete: complete,
 		expires_in: P.EXPIRES_S, interval: P.INTERVAL_S, ...(replaces ? { replaces_label: replaces.label } : {}) }, 200, { pragma: "no-cache" });
 }
@@ -1375,7 +1380,7 @@ const pendingRequest = async (ctx: TenantContext, code: string): Promise<Json |
 	ctx.DB.prepare("SELECT * FROM device_requests WHERE user_code = ?").bind(code).first();
 
 /** Approve or deny a pending request. Returns the label (approve) or an error message. */
-async function decide(ctx: TenantContext, code: string, approve: boolean, by: string): Promise<{ ok: boolean; label?: string; error?: string; request?: Json; replaced?: boolean }> {
+async function decide(ctx: TenantContext, ectx: ExecutionContext, code: string, approve: boolean, by: string): Promise<{ ok: boolean; label?: string; error?: string; request?: Json; replaced?: boolean }> {
 	const r = await pendingRequest(ctx, code);
 	if (!r) return { ok: false, error: "no pairing request with that code" };
 	if (r.status !== "pending") return { ok: false, error: `that request was already ${r.status === "denied" ? "denied" : "approved"}` };
@@ -1387,9 +1392,46 @@ async function decide(ctx: TenantContext, code: string, approve: boolean, by: st
 		.bind(approve ? "approved" : "denied", label, Date.now(), by, r.device_hash).run();
 	if (u.meta.changes !== 1) return { ok: false, error: "that request was decided meanwhile" };
 	log(approve ? "pairing_approved" : "pairing_denied", { userCode: P.formatUserCode(code), by, label, ...(replacing ? { replaces: label } : {}) });
+	publishPairingEvent(ctx, ectx, { type: "pairing_decided", requestId: String(r.device_hash), code: P.formatUserCode(code),
+		name: r.client_name || "", alias: r.client_id || "", ip: r.ip || "", country: r.country || "",
+		createdAt: new Date(r.created_ms).toISOString(), expiresAt: new Date(r.expires_ms).toISOString(),
+		decision: approve ? "approved" : "denied" });
 	return { ok: true, label: label || undefined, request: r, replaced: replacing };
 }
 
+/**
+ * Hand the open-count query and the EVENT_URL post to waitUntil.
+ * The HTTP response returns before either of them runs. A missing URL or secret leaves the request as it was.
+ */
+function publishPairingEvent(ctx: TenantContext, ectx: ExecutionContext, event: {
+	type: "pairing_requested" | "pairing_decided";
+	requestId: string;
+	code: string;
+	name: string;
+	alias: string;
+	ip: string;
+	country: string;
+	createdAt: string;
+	expiresAt: string;
+	decision?: "approved" | "denied";
+}): void {
+	const target = pairingEventTarget(ctx.EVENT_URL, ctx.EVENT_SECRET);
+	if (!target) return;
+	const agent = pairingAgent(ctx.PUBLIC_URL, ctx.id);
+	try {
+		ectx.waitUntil((async () => {
+			try {
+				const row: Json = await ctx.DB.prepare("SELECT COUNT(*) AS n FROM device_requests WHERE status = 'pending' AND expires_ms > ?").bind(Date.now()).first();
+				await postPairingEvent(target, { ...event, agent, pending: Number(row?.n ?? 0) });
+			} catch (error) {
+				log("pairing_event_failed", { type: event.type, error: String(error).slice(0, 200) });
+			}
+		})());
+	} catch (error) {
+		log("pairing_event_failed", { type: event.type, error: String(error).slice(0, 200) });
+	}
+}
+
 const pageRequest = (r: Json): P.PageRequest => ({ userCode: r.user_code, clientName: r.client_name || "", clientId: r.client_id || "",
 	agentCardUrl: r.agent_card_url || "", ip: r.ip || "", country: r.country || "", createdMs: r.created_ms, expiresMs: r.expires_ms,
 	replacesLabel: r.replaces_label || undefined });
@@ -1439,7 +1481,7 @@ function cookie(req: Request, name: string): string {
 }
 
 /** GET/POST /device: the owner approves or denies a request with the approval password (no scripts, strict CSP). */
-async function devicePage(req: Request, ctx: TenantContext, url: URL, head = false): Promise<Response> {
+async function devicePage(req: Request, ctx: TenantContext, ectx: ExecutionContext, url: URL, head = false): Promise<Response> {
 	const nonce = P.randomB64(), ip = clientIp(req);
 	const csrfName = "a2a_device_csrf";
 	let csrf = cookie(req, csrfName);
@@ -1494,7 +1536,7 @@ async function devicePage(req: Request, ctx: TenantContext, url: URL, head = fal
 		}
 		const r0 = await pendingRequest(ctx, code);
 		if (!r0 || r0.status !== "pending" || Date.now() >= r0.expires_ms) { await show(form.user_code); return send(404); }
-		const d0 = await decide(ctx, code, false, "page");
+		const d0 = await decide(ctx, ectx, code, false, "page");
 		if (!d0.ok) { await show(null, { kind: "error", text: d0.error! }); return send(409); }
 		model.settled = "denied";
 		model.notice = { kind: "ok", text: `Denied. ${r0.client_name || r0.client_id || "the agent"} gets no token.` };
@@ -1534,14 +1576,14 @@ async function devicePage(req: Request, ctx: TenantContext, url: URL, head = fal
 		const left = P.LIMITS.wrongPerCode - (res?.failed_attempts ?? P.LIMITS.wrongPerCode);
 		log("pairing_wrong_password", { ip, userCode: P.formatUserCode(code), left });
 		if (left <= 0) {
-			await decide(ctx, code, false, "lockout");
+			await decide(ctx, ectx, code, false, "lockout");
 			await show(null, { kind: "error", text: "Wrong password. Too many wrong attempts for this code: the request was denied." });
 			return send(403);
 		}
 		await show(form.user_code, { kind: "error", text: `Wrong password. ${left} attempt${left === 1 ? "" : "s"} left for this code.` });
 		return send(403);
 	}
-	const d = await decide(ctx, code, true, "human");
+	const d = await decide(ctx, ectx, code, true, "human");
 	if (!d.ok) { await show(null, { kind: "error", text: d.error! }); return send(409); }
 	const who = r.client_name || r.client_id || "the agent";
 	model.settled = "approved";
@@ -1550,7 +1592,7 @@ async function devicePage(req: Request, ctx: TenantContext, url: URL, head = fal
 }
 
 /** GET /device/oidc/callback: the identity provider returns here. State is the CSRF; the cookie is not re-checked. */
-async function deviceOidcCallback(req: Request, ctx: TenantContext, url: URL, head = false): Promise<Response> {
+async function deviceOidcCallback(req: Request, ctx: TenantContext, ectx: ExecutionContext, url: URL, head = false): Promise<Response> {
 	const nonce = P.randomB64();
 	const pw = await approvalPassword(ctx);
 	const model: P.PageModel = { agentName: ctx.AGENT_NAME || "this A2A endpoint", mode: pairingMode(ctx), cli: cliCommand(ctx), csrf: P.randomB64(), passwordSet: !!pw, timeZone: clientTimeZone(req), ...approvalPageBits(ctx) };
@@ -1593,7 +1635,7 @@ async function deviceOidcCallback(req: Request, ctx: TenantContext, url: URL, he
 		model.notice = { kind: "error", text: done.error };
 		return send(400);
 	}
-	const d = await decide(ctx, done.userCode || "", true, "oidc");
+	const d = await decide(ctx, ectx, done.userCode || "", true, "oidc");
 	if (!d.ok) { model.notice = { kind: "error", text: d.error! }; return send(409); }
 	const who = d.request.client_name || d.request.client_id || "the agent";
 	model.settled = "approved";
@@ -1686,7 +1728,7 @@ async function setupPage(req: Request, ctx: TenantContext, url: URL, head = fals
 }
 
 /** Owner API: /owner/pairing (list, mode), /owner/pairing/password (set), /owner/pairing/<code>/approve|deny. */
-async function ownerPairing(req: Request, ctx: TenantContext, m: string, seg: string[], body: () => Promise<Json>, trusted = false): Promise<Response> {
+async function ownerPairing(req: Request, ctx: TenantContext, ectx: ExecutionContext, m: string, seg: string[], body: () => Promise<Json>, trusted = false): Promise<Response> {
 	const mode = pairingMode(ctx);
 	if (!seg[0] && m === "GET") {
 		const now = Date.now();
@@ -1747,7 +1789,7 @@ async function ownerPairing(req: Request, ctx: TenantContext, m: string, seg: st
 		if (approve && mode !== "agent" && !dashboardHuman && !ownerAuthed)
 			return json({ error: `approval mode is human: this call cannot approve. The owner approves with the owner token, or on ${oauthUrls(ctx).page}?user_code=${P.formatUserCode(code)} with the approval password.` }, 403);
 		const by = dashboardHuman ? "human" : approve && mode === "agent" ? "agent" : "owner";
-		const d = await decide(ctx, code, approve, by);
+		const d = await decide(ctx, ectx, code, approve, by);
 		if (!d.ok) return json({ error: d.error }, 409);
 		return json({ ok: true, decision: approve ? "approved" : "denied", userCode: P.formatUserCode(code), label: d.label || null,
 			clientName: d.request.client_name || d.request.client_id || null, replaced: !!d.replaced });
@@ -2611,8 +2653,8 @@ async function handle(req: Request, ctx: TenantContext, ectx: ExecutionContext,
 			if (req.method === "GET" && path === "/.well-known/oauth-protected-resource") return json(protectedResourceMetadata(ctx), 200, { "access-control-allow-origin": "*" });
 			if (req.method === "POST" && path === "/oauth/device_authorization") return await deviceAuthorization(req, ctx, ectx);
 			if (req.method === "POST" && path === "/oauth/token") return await tokenEndpoint(req, ctx);
-			if (path === "/device" && (req.method === "GET" || req.method === "POST")) return await devicePage(req, ctx, url, head);
-			if (req.method === "GET" && path === "/device/oidc/callback") return await deviceOidcCallback(req, ctx, url, head);
+			if (path === "/device" && (req.method === "GET" || req.method === "POST")) return await devicePage(req, ctx, ectx, url, head);
+			if (req.method === "GET" && path === "/device/oidc/callback") return await deviceOidcCallback(req, ctx, ectx, url, head);
 			if (path === "/device/setup" && (req.method === "GET" || req.method === "POST")) return await setupPage(req, ctx, url, head);
 			return json({ error: "not found" }, 404);
 		}

package/worker/src/pairing-events.ts

@@ -0,0 +1,120 @@
+// Dashboard notice for a pairing request. Posted only when EVENT_URL and EVENT_SECRET are both set.
+// The signature matches control/src/tenants/events.ts `verifyEventSignature`.
+
+export const EVENT_TIMEOUT_MS = 3000;
+
+export type PairingEventType = "pairing_requested" | "pairing_decided";
+
+export interface PairingEvent {
+	type: PairingEventType;
+	agent: string;
+	requestId: string;
+	code: string;
+	name: string;
+	alias: string;
+	ip: string;
+	country: string;
+	createdAt: string;
+	expiresAt: string;
+	pending: number;
+	decision?: "approved" | "denied";
+}
+
+const URL_MAX = 2000;
+const SECRET_MAX = 512;
+
+function httpsEventUrl(value: string | undefined): string {
+	const raw = (value || "").trim();
+	if (!raw || raw.length > URL_MAX) return "";
+	try {
+		const url = new URL(raw);
+		if (url.protocol !== "https:" || url.username || url.password) return "";
+		return raw;
+	} catch {
+		return "";
+	}
+}
+
+function eventSecretText(value: string | undefined): string {
+	const text = (value || "").trim();
+	if (!text || text.length > SECRET_MAX || /[\u0000-\u001f]/.test(text)) return "";
+	return text;
+}
+
+/** Public host, or the tenant id when the public URL has no host. */
+export function pairingAgent(publicUrl: string, tenantId: string): string {
+	try {
+		const host = new URL(publicUrl).host;
+		if (host) return host;
+	} catch { /* tenant id below */ }
+	return tenantId || "";
+}
+
+/** The post target, or null when either value is missing or unusable. */
+export function pairingEventTarget(url: string | undefined, secret: string | undefined): { url: string; secret: string } | null {
+	const target = httpsEventUrl(url);
+	const key = eventSecretText(secret);
+	if (!target || !key) return null;
+	return { url: target, secret: key };
+}
+
+/** Stable JSON. `decision` is present only on a decided request. */
+export function serializePairingEvent(event: PairingEvent): string {
+	const body: Record<string, string | number> = {
+		type: event.type,
+		agent: event.agent,
+		requestId: event.requestId,
+		code: event.code,
+		name: event.name,
+		alias: event.alias,
+		ip: event.ip,
+		country: event.country,
+		createdAt: event.createdAt,
+		expiresAt: event.expiresAt,
+		pending: event.pending,
+	};
+	if (event.type === "pairing_decided" && (event.decision === "approved" || event.decision === "denied")) body.decision = event.decision;
+	return JSON.stringify(body);
+}
+
+async function hmacHex(secret: string, message: string): Promise<string> {
+	const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+	const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(message));
+	return [...new Uint8Array(mac)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+const log = (event: string, kw: Record<string, unknown> = {}) => console.log(JSON.stringify({ ts: new Date().toISOString(), event, ...kw }));
+
+/**
+ * POST the event. One retry after a timeout or a failed response. The promise settles
+ * on its own: a network error stays inside this function.
+ */
+export async function postPairingEvent(
+	target: { url: string; secret: string },
+	event: PairingEvent,
+	opts: { fetchImpl?: typeof fetch; timeoutMs?: number; now?: number } = {},
+): Promise<void> {
+	try {
+		const body = serializePairingEvent(event);
+		const timestamp = String(Math.floor((opts.now ?? Date.now()) / 1000));
+		const signature = `sha256=${await hmacHex(target.secret, `${timestamp}.${body}`)}`;
+		const fetchImpl = opts.fetchImpl ?? fetch;
+		const timeoutMs = opts.timeoutMs ?? EVENT_TIMEOUT_MS;
+		const headers = { "content-type": "application/json", "x-a2a-timestamp": timestamp, "x-a2a-signature": signature };
+		for (let attempt = 1; attempt <= 2; attempt++) {
+			try {
+				const res = await fetchImpl(target.url, { method: "POST", headers, body, redirect: "manual", signal: AbortSignal.timeout(timeoutMs) });
+				try { await res.body?.cancel(); } catch { /* the status is enough */ }
+				if (res.ok) {
+					log("pairing_event_sent", { type: event.type });
+					return;
+				}
+				log("pairing_event_failed", { type: event.type, attempt, status: res.status });
+			} catch (error) {
+				log("pairing_event_failed", { type: event.type, attempt, error: String(error).slice(0, 200) });
+			}
+		}
+	} catch (error) {
+		log("pairing_event_failed", { type: event.type, error: String(error).slice(0, 200) });
+	}
+}

package/worker/src/tenancy.ts

@@ -41,6 +41,10 @@ export const CONFIG_KEYS = [
 	"MCP",
 	/** Optional https URL of this agent's dashboard page. Omitted from pairing output when unset or not https. */
 	"MANAGE_URL",
+	/** Optional https URL that receives a signed pairing event. Omitted from the post when the secret is absent. */
+	"EVENT_URL",
+	/** HMAC key for that post. A Worker secret on a self-hosted agent. On a hosted agent the sealed secrets blob supplies it. */
+	"EVENT_SECRET",
 ] as const;
 
 export type ConfigKey = (typeof CONFIG_KEYS)[number];
@@ -383,6 +387,8 @@ export class TenantContext implements ConfigFields {
 	readonly UPSTREAM_ACCESS_CLIENT_SECRET?: string;
 	readonly MCP?: string;
 	readonly MANAGE_URL?: string;
+	readonly EVENT_URL?: string;
+	readonly EVENT_SECRET?: string;
 
 	/** Self-host only. Never set on a hosted context, so a platform OWNER_TOKEN cannot unlock a tenant. */
 	readonly #ownerToken?: string;

package/worker/src/version.ts

@@ -1,2 +1,2 @@
 /** Inbox build. Keep this equal to `version` in cli/package.json. */
-export const VERSION = "0.8.8";
+export const VERSION = "0.8.9";

package/worker/src/wake-secrets.ts

@@ -5,12 +5,13 @@
 const INFO = "tenant-wake-secrets v1";
 const SALT = "a2a-exposed";
 
-/** Secret wake fields. Anything else in the blob is ignored. */
+/** Sealed secret fields. Anything else in the blob is ignored. */
 export const WAKE_SECRET_KEYS = [
 	"WAKE_WEBHOOK_KEY",
 	"WAKE_HMAC_SECRET",
 	"WAKE_ACCESS_CLIENT_ID",
 	"WAKE_ACCESS_CLIENT_SECRET",
+	"EVENT_SECRET",
 ] as const;
 
 export type WakeSecretKey = (typeof WAKE_SECRET_KEYS)[number];
@@ -51,6 +52,17 @@ async function derive(ikm: string, tenantId: string): Promise<CryptoKey | null>
 	);
 }
 
+/**
+ * Config written next to a sealed blob. The sealed fields stay in `secrets_enc`.
+ * With no ciphertext, the config is returned unchanged.
+ */
+export function omitSealedSecrets<T extends Record<string, unknown>>(config: T, secretsEnc: string | null | undefined): T {
+	if (typeof secretsEnc !== "string" || secretsEnc === "") return config;
+	const stored = { ...config };
+	for (const key of WAKE_SECRET_KEYS) delete stored[key];
+	return stored;
+}
+
 function payloadOf(secrets: WakeSecrets): Record<string, string> | null {
 	const payload: Record<string, string> = {};
 	for (const key of WAKE_SECRET_KEYS) {

package/worker/test/pairing-events.test.ts

@@ -0,0 +1,263 @@
+// Pairing events: signature, retry, payload, and the hosted tenant path.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import worker, { dispatch } from "../src/index.ts";
+import { hostedTenantContext, type WorkerBindings } from "../src/tenancy.ts";
+import { postPairingEvent, type PairingEvent } from "../src/pairing-events.ts";
+import { openWakeSecrets, sealWakeSecrets, WAKE_SECRET_KEYS } from "../src/wake-secrets.ts";
+import { EVENT_REPLAY_WINDOW_S, verifyEventSignature } from "../../control/src/tenants/events.ts";
+import { d1 } from "./d1.ts";
+
+const BASE = "https://agent.example.com";
+const EVENT_URL = "https://example.com/api/agent-events";
+const SECRET = "event-secret";
+
+function sample(over: Partial<PairingEvent> = {}): PairingEvent {
+	return {
+		type: "pairing_requested", agent: "agent.example.com", requestId: "abc", code: "WDJB-4827",
+		name: "Barry Bot", alias: "barry", ip: "198.51.100.7", country: "DE",
+		createdAt: "2026-10-16T14:00:00.000Z", expiresAt: "2026-10-16T15:00:00.000Z", pending: 1, ...over,
+	};
+}
+
+test("verifyEventSignature accepts the posted bytes and rejects a replay, a tampered body, and a wrong secret", async () => {
+	const now = Date.UTC(2026, 9, 16, 14, 0, 0);
+	const seen: { body: string; headers: Headers }[] = [];
+	await postPairingEvent({ url: EVENT_URL, secret: SECRET }, sample(), {
+		now,
+		fetchImpl: (async (url: string, init: RequestInit) => {
+			seen.push({ body: String(init.body), headers: new Headers(init.headers) });
+			assert.equal(url, EVENT_URL);
+			assert.equal(init.redirect, "manual");
+			return new Response("ok");
+		}) as typeof fetch,
+	});
+	assert.equal(seen.length, 1);
+	const { body, headers } = seen[0];
+	const parsed = JSON.parse(body);
+	assert.equal(parsed.type, "pairing_requested");
+	assert.equal(parsed.pending, 1);
+	assert.equal("decision" in parsed, false);
+	assert.equal(await verifyEventSignature(body, headers, SECRET, now), true);
+	assert.equal(await verifyEventSignature(body, headers, SECRET, now + EVENT_REPLAY_WINDOW_S * 1000), true);
+	assert.equal(await verifyEventSignature(body, headers, SECRET, now + (EVENT_REPLAY_WINDOW_S + 1) * 1000), false);
+	assert.equal(await verifyEventSignature(body + " ", headers, SECRET, now), false);
+	assert.equal(await verifyEventSignature(body, headers, "other-secret", now), false);
+	const shifted = new Headers(headers);
+	shifted.set("x-a2a-timestamp", String(Math.floor(now / 1000) + 1));
+	assert.equal(await verifyEventSignature(body, shifted, SECRET, now), false);
+
+	const decided = sample({ type: "pairing_decided", decision: "approved", pending: 0 });
+	let decidedBody = "";
+	await postPairingEvent({ url: EVENT_URL, secret: SECRET }, decided, {
+		now,
+		fetchImpl: (async (_url: string, init: RequestInit) => {
+			decidedBody = String(init.body);
+			return new Response("ok");
+		}) as typeof fetch,
+	});
+	assert.equal(JSON.parse(decidedBody).decision, "approved");
+});
+
+test("a timeout is retried once and a failed post stays inside the function", async () => {
+	let calls = 0;
+	await postPairingEvent({ url: EVENT_URL, secret: SECRET }, sample(), {
+		timeoutMs: 30,
+		fetchImpl: (async (_url: string, init: RequestInit) => {
+			calls++;
+			if (calls === 1) {
+				await new Promise((_resolve, reject) => {
+					const timer = setTimeout(() => reject(new Error("the attempt was not aborted")), 1000);
+					init.signal?.addEventListener("abort", () => {
+						clearTimeout(timer);
+						reject(Object.assign(new Error("aborted"), { name: "AbortError" }));
+					});
+				});
+			}
+			return new Response("ok");
+		}) as typeof fetch,
+	});
+	assert.equal(calls, 2);
+
+	let failed = 0;
+	await postPairingEvent({ url: EVENT_URL, secret: SECRET }, sample(), {
+		timeoutMs: 30,
+		fetchImpl: (async () => {
+			failed++;
+			return new Response("no", { status: 503 });
+		}) as typeof fetch,
+	});
+	assert.equal(failed, 2);
+
+	await assert.doesNotReject(postPairingEvent({ url: EVENT_URL, secret: SECRET }, sample(), {
+		timeoutMs: 30,
+		fetchImpl: (async () => { throw new Error("network down"); }) as typeof fetch,
+	}));
+});
+
+function env(over: Record<string, string> = {}) {
+	const DB = d1(new URL("../migrations/", import.meta.url));
+	return { DB, PUBLIC_URL: BASE, OWNER_TOKEN: "owner-secret", AGENT_NAME: "Test Inbox", ...over };
+}
+
+async function start(bindings: Record<string, string>, fetchImpl: typeof fetch) {
+	const pending: Promise<unknown>[] = [];
+	const bindingsEnv = env(bindings);
+	// Durable Object storage applies migrations on the first query. Run that query before the timed request
+	// so the race covers the pairing response.
+	await bindingsEnv.DB.prepare("SELECT 1").first();
+	const previous = globalThis.fetch;
+	globalThis.fetch = fetchImpl;
+	const req = new Request(BASE + "/oauth/device_authorization", {
+		method: "POST",
+		headers: { "content-type": "application/x-www-form-urlencoded", "cf-connecting-ip": "198.51.100.7" },
+		body: new URLSearchParams({ client_name: "Barry Bot", client_id: "barry", agent_card_url: "https://barry.example.org/card" }).toString(),
+	});
+	(req as { cf?: unknown }).cf = { country: "DE" };
+	const response = worker.fetch(req, bindingsEnv as WorkerBindings, { waitUntil: (p: Promise<unknown>) => pending.push(p), passThroughOnException() {} } as ExecutionContext);
+	return {
+		response, pending, restore: () => { globalThis.fetch = previous; },
+	};
+}
+
+test("the response returns before the event post, and the payload carries the open count", async (t) => {
+	let release: () => void = () => {};
+	const gate = new Promise<void>((resolve) => { release = resolve; });
+	let body = "";
+	let headers = new Headers();
+	let started = false;
+	const run = await start({ EVENT_URL, EVENT_SECRET: SECRET }, (async (url: string, init: RequestInit) => {
+		if (String(url) !== EVENT_URL) return new Response("ok");
+		started = true;
+		body = String(init?.body);
+		headers = new Headers(init?.headers);
+		await gate;
+		return new Response("ok");
+	}) as typeof fetch);
+	t.after(async () => {
+		release();
+		await run.response.catch(() => {});
+		await Promise.allSettled(run.pending);
+		run.restore();
+	});
+	const res = await Promise.race([
+		run.response,
+		new Promise<Response>((_resolve, reject) => setTimeout(() => reject(new Error("the pairing response waited for the event post")), 500)),
+	]);
+	assert.equal(started, false);
+	assert.equal(res.status, 200);
+	const data = await res.json() as { user_code: string };
+	const deadline = Date.now() + 2000;
+	while (!started && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 5));
+	assert.equal(started, true);
+	release();
+	await Promise.all(run.pending);
+	const event = JSON.parse(body);
+	assert.equal(event.type, "pairing_requested");
+	assert.equal(event.agent, "agent.example.com");
+	assert.equal(event.code, data.user_code);
+	assert.equal(event.name, "Barry Bot");
+	assert.equal(event.alias, "barry");
+	assert.equal(event.ip, "198.51.100.7");
+	assert.equal(event.country, "DE");
+	assert.equal(event.pending, 1);
+	assert.match(event.requestId, /^[0-9a-f]{64}$/);
+	assert.equal(await verifyEventSignature(body, headers, SECRET), true);
+
+	const quiet: string[] = [];
+	const off = await start({}, (async (url: string) => {
+		quiet.push(String(url));
+		return new Response("ok");
+	}) as typeof fetch);
+	assert.equal((await off.response).status, 200);
+	await Promise.all(off.pending);
+	off.restore();
+	assert.equal(quiet.some((url) => url === EVENT_URL), false);
+});
+
+test("a hosted tenant posts with the control plane's EVENT_URL and EVENT_SECRET", async () => {
+	const DB = d1(new URL("../migrations/", import.meta.url));
+	await DB.prepare("SELECT 1").first();
+	const sealed = await sealWakeSecrets("platform-secret", "ten_north", { EVENT_SECRET: SECRET });
+	assert.ok(sealed);
+	assert.equal(sealed.includes(SECRET), false);
+	const opened = await openWakeSecrets("platform-secret", "ten_north", sealed);
+	const config: Record<string, string> = { EVENT_URL, EVENT_SECRET: "plaintext-copy" };
+	for (const name of WAKE_SECRET_KEYS) {
+		const value = opened?.[name];
+		if (value) config[name] = value;
+		else delete config[name];
+	}
+	const ctx = hostedTenantContext({ DB, TENANCY: "host", EVENT_URL: "https://platform.example/other", EVENT_SECRET: "platform" } as WorkerBindings, {
+		id: "ten_north", db: DB, publicUrl: "https://northwind.example.com",
+		config,
+	});
+	assert.equal(ctx.mode, "host");
+	assert.equal(ctx.EVENT_URL, EVENT_URL);
+	assert.equal(ctx.EVENT_SECRET, SECRET);
+	const posts: { body: string; headers: Headers }[] = [];
+	const previous = globalThis.fetch;
+	globalThis.fetch = (async (url: string, init: RequestInit) => {
+		if (String(url) === EVENT_URL) posts.push({ body: String(init.body), headers: new Headers(init.headers) });
+		return new Response("ok");
+	}) as typeof fetch;
+	const pending: Promise<unknown>[] = [];
+	const req = new Request("https://northwind.example.com/oauth/device_authorization", {
+		method: "POST",
+		headers: { "content-type": "application/x-www-form-urlencoded", "cf-connecting-ip": "203.0.113.9" },
+		body: new URLSearchParams({ client_name: "Claude", client_id: "claude" }).toString(),
+	});
+	(req as { cf?: unknown }).cf = { country: "US" };
+	const res = await dispatch(req, ctx, { waitUntil: (p: Promise<unknown>) => pending.push(p), passThroughOnException() {} } as ExecutionContext);
+	await Promise.all(pending);
+	globalThis.fetch = previous;
+	assert.equal(res.status, 200);
+	assert.equal(posts.length, 1);
+	const event = JSON.parse(posts[0].body);
+	assert.equal(event.agent, "northwind.example.com");
+	assert.equal(event.name, "Claude");
+	assert.equal(event.alias, "claude");
+	assert.equal(event.country, "US");
+	assert.equal(event.pending, 1);
+	assert.equal(await verifyEventSignature(posts[0].body, posts[0].headers, SECRET), true);
+
+	const plain = hostedTenantContext({ DB, TENANCY: "host", EVENT_URL, EVENT_SECRET: SECRET } as WorkerBindings, {
+		id: "ten_plain", db: DB, publicUrl: "https://plain.example.com",
+	});
+	assert.equal(plain.EVENT_URL, undefined);
+	assert.equal(plain.EVENT_SECRET, undefined);
+});
+
+test("approve posts pairing_decided with the remaining open count", async () => {
+	const bindings = env({ EVENT_URL, EVENT_SECRET: SECRET });
+	const posts: { body: string }[] = [];
+	const previous = globalThis.fetch;
+	globalThis.fetch = (async (url: string, init: RequestInit) => {
+		if (String(url) === EVENT_URL) posts.push({ body: String(init.body) });
+		return new Response("ok");
+	}) as typeof fetch;
+	const pending: Promise<unknown>[] = [];
+	const ectx = { waitUntil: (p: Promise<unknown>) => pending.push(p), passThroughOnException() {} } as ExecutionContext;
+	const call = async (method: string, path: string, body?: string, headers: Record<string, string> = {}) => {
+		const res = await worker.fetch(new Request(BASE + path, { method, headers, body }), bindings as WorkerBindings, ectx);
+		await Promise.all(pending.splice(0));
+		return res;
+	};
+	const started = await call("POST", "/oauth/device_authorization", new URLSearchParams({ client_name: "Barry Bot", client_id: "barry" }).toString(), {
+		"content-type": "application/x-www-form-urlencoded", "cf-connecting-ip": "198.51.100.7",
+	});
+	const first = await started.json() as { user_code: string };
+	const secondRes = await call("POST", "/oauth/device_authorization", new URLSearchParams({ client_name: "Other", client_id: "other" }).toString(), {
+		"content-type": "application/x-www-form-urlencoded", "cf-connecting-ip": "198.51.100.8",
+	});
+	assert.equal(secondRes.status, 200);
+	const denied = await call("POST", `/owner/pairing/${first.user_code}/deny`, "{}", { authorization: "Bearer owner-secret", "content-type": "application/json" });
+	globalThis.fetch = previous;
+	assert.equal(denied.status, 200);
+	const decided = posts.map((post) => JSON.parse(post.body)).filter((event) => event.type === "pairing_decided");
+	assert.equal(decided.length, 1);
+	assert.equal(decided[0].decision, "denied");
+	assert.equal(decided[0].code, first.user_code);
+	assert.equal(decided[0].pending, 1);
+	assert.equal(decided[0].name, "Barry Bot");
+});

package/worker/test/tenancy.test.ts

@@ -6,6 +6,7 @@ import worker from "../src/index.ts";
 import { sha256 } from "../src/a2a.ts";
 import { openPeerToken, openPeerTokenWithKey, sealPeerToken, sealPeerTokenWithKey } from "../src/mcp.ts";
 import { hostedTenantContext, namespaceForRegion, parseGates, publicManageUrl, resolveTenant, type WorkerBindings } from "../src/tenancy.ts";
+import { openWakeSecrets, sealWakeSecrets, WAKE_SECRET_KEYS } from "../src/wake-secrets.ts";
 import { d1 } from "./d1.ts";
 
 const dummy = { prepare() { throw new Error("storage should not be touched"); } } as any;
@@ -35,6 +36,31 @@ test("publicManageUrl keeps an https dashboard page and drops anything else", ()
 	assert.equal(hostedUnset.MANAGE_URL, undefined);
 });
 
+test("EVENT_URL and EVENT_SECRET come from the tenant on a hosted agent", async () => {
+	const url = "https://example.com/api/agent-events";
+	assert.equal(resolveTenant(selfEnv({ EVENT_URL: url, EVENT_SECRET: "event-secret" })).EVENT_SECRET, "event-secret");
+	const sealed = await sealWakeSecrets("platform-secret", "ten_a", { EVENT_SECRET: "tenant-secret" });
+	assert.ok(sealed);
+	assert.equal(sealed.includes("tenant-secret"), false);
+	const opened = await openWakeSecrets("platform-secret", "ten_a", sealed);
+	const config: Record<string, string> = { EVENT_URL: url, EVENT_SECRET: "plaintext-copy" };
+	for (const name of WAKE_SECRET_KEYS) {
+		const value = opened?.[name];
+		if (value) config[name] = value;
+		else delete config[name];
+	}
+	const hosted = hostedTenantContext(selfEnv({ TENANCY: "host", EVENT_URL: "https://platform.example/other", EVENT_SECRET: "platform" }), {
+		id: "ten_a", db: dummy, publicUrl: BASE, config,
+	});
+	assert.equal(hosted.EVENT_URL, url);
+	assert.equal(hosted.EVENT_SECRET, "tenant-secret");
+	const hostedUnset = hostedTenantContext(selfEnv({ TENANCY: "host", EVENT_URL: url, EVENT_SECRET: "platform" }), {
+		id: "ten_a", db: dummy, publicUrl: BASE,
+	});
+	assert.equal(hostedUnset.EVENT_URL, undefined);
+	assert.equal(hostedUnset.EVENT_SECRET, undefined);
+});
+
 test("gates: unset is single-tenant and every reserved gate is off", () => {
 	const g = parseGates({ DB: dummy } as WorkerBindings).gates;
 	assert.equal(g.tenancy, "single");

package/worker/test/wake-secrets.test.ts

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { MAX_WAKE_SEALED, MAX_WAKE_VALUE, openWakeSecrets, sealWakeSecrets, WAKE_SECRET_KEYS } from "../src/wake-secrets.ts";
+import { MAX_WAKE_SEALED, MAX_WAKE_VALUE, omitSealedSecrets, openWakeSecrets, sealWakeSecrets, WAKE_SECRET_KEYS } from "../src/wake-secrets.ts";
 
 const key = "platform-secret";
 const tenant = "ten_a";
@@ -30,7 +30,7 @@ test("a wake secret blob keeps only the known fields", async () => {
 	assert.equal(await sealWakeSecrets(key, tenant, { WAKE_WEBHOOK_KEY: "x".repeat(4097) }), null);
 });
 
-test("four maximum-length wake secrets round-trip", async () => {
+test("every maximum-length sealed secret round-trips", async () => {
 	const value = "x".repeat(MAX_WAKE_VALUE);
 	const secrets = Object.fromEntries(WAKE_SECRET_KEYS.map((name) => [name, value]));
 	const sealed = await sealWakeSecrets(key, tenant, secrets);
@@ -47,3 +47,16 @@ test("four maximum-length wake secrets round-trip", async () => {
 	assert.ok(sealedWorst!.length <= MAX_WAKE_SEALED);
 	assert.deepEqual(await openWakeSecrets(key, tenant, sealedWorst), worst);
 });
+
+test("a sealed blob's fields are left out of the stored config", () => {
+	const url = "https://example.com/api/agent-events";
+	const stored = omitSealedSecrets({
+		AGENT_NAME: "northwind", EVENT_URL: url, EVENT_SECRET: "event-secret", WAKE_WEBHOOK_KEY: "hook-key",
+	}, "v1.iv.ct");
+	assert.equal(stored.EVENT_URL, url);
+	assert.equal(stored.AGENT_NAME, "northwind");
+	assert.equal("EVENT_SECRET" in stored, false);
+	assert.equal("WAKE_WEBHOOK_KEY" in stored, false);
+	assert.equal(omitSealedSecrets({ EVENT_SECRET: "event-secret" }, null).EVENT_SECRET, "event-secret");
+	assert.equal(omitSealedSecrets({ EVENT_SECRET: "event-secret" }, "").EVENT_SECRET, "event-secret");
+});