@a2a-exposed/control-core 0.8.8 → 0.8.10

package/dist/index.js

@@ -59,6 +59,65 @@ async function newApprovalClient(input) {
   return { clientId, clientSecret, secretHash: await sha256(clientSecret), redirectUris, approval };
 }
 
+// src/tenants/events.ts
+var EVENT_REPLAY_WINDOW_S = 300;
+var URL_MAX = 2e3;
+var SECRET_MAX = 512;
+function httpsEventUrl(value) {
+  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) {
+  const text = (value || "").trim();
+  if (!text || text.length > SECRET_MAX || /[\u0000-\u001f]/.test(text)) return "";
+  return text;
+}
+function pairingEventConfig(eventUrl, eventSecret) {
+  const url = httpsEventUrl(eventUrl);
+  const secret = eventSecretText(eventSecret);
+  if (!url || !secret) return null;
+  return { EVENT_URL: url, EVENT_SECRET: secret };
+}
+function headerValue(headers, name) {
+  if (typeof headers.get === "function") return headers.get(name) || "";
+  const record = headers;
+  const direct = record[name];
+  if (typeof direct === "string") return direct;
+  const found = Object.keys(record).find((key) => key.toLowerCase() === name.toLowerCase());
+  const value = found ? record[found] : "";
+  return typeof value === "string" ? value : "";
+}
+async function hmacHex(secret, message) {
+  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("");
+}
+function timingSafeEqual(a, b) {
+  const left = new TextEncoder().encode(a);
+  const right = new TextEncoder().encode(b);
+  if (left.length !== right.length) return false;
+  let diff = 0;
+  for (let i = 0; i < left.length; i++) diff |= left[i] ^ right[i];
+  return diff === 0;
+}
+async function verifyEventSignature(body, headers, secret, now = Date.now()) {
+  const key = eventSecretText(secret);
+  const timestamp = headerValue(headers, "x-a2a-timestamp").trim();
+  const presented = headerValue(headers, "x-a2a-signature").trim();
+  if (!key || !/^\d{1,12}$/.test(timestamp) || !presented.startsWith("sha256=")) return false;
+  const skew = Math.abs(Math.floor(now / 1e3) - Number(timestamp));
+  if (skew > EVENT_REPLAY_WINDOW_S) return false;
+  const expected = `sha256=${await hmacHex(key, `${timestamp}.${body}`)}`;
+  return timingSafeEqual(expected, presented);
+}
+
 // src/tenants/push.ts
 function namespaceFor(ns, region) {
   if ((region === "eu" || region === "fedramp") && typeof ns.jurisdiction === "function") return ns.jurisdiction(region);
@@ -226,6 +285,97 @@ function tenantNameProblem(name) {
   return "";
 }
 
+// src/tenants/wake-secrets.ts
+var INFO = "tenant-wake-secrets v1";
+var SALT = "a2a-exposed";
+var WAKE_SECRET_KEYS = [
+  "WAKE_WEBHOOK_KEY",
+  "WAKE_HMAC_SECRET",
+  "WAKE_ACCESS_CLIENT_ID",
+  "WAKE_ACCESS_CLIENT_SECRET",
+  "EVENT_SECRET"
+];
+var MAX_WAKE_VALUE = 4096;
+var MAX_WAKE_PLAIN = (() => {
+  let n = 2;
+  for (let i = 0; i < WAKE_SECRET_KEYS.length; i++) {
+    if (i) n += 1;
+    n += WAKE_SECRET_KEYS[i].length + 5 + MAX_WAKE_VALUE * 6;
+  }
+  return n;
+})();
+var MAX_WAKE_SEALED = 3 + 16 + 1 + Math.ceil((MAX_WAKE_PLAIN * 3 + 16) * 4 / 3);
+function b64(bytes2) {
+  let raw = "";
+  for (let i = 0; i < bytes2.length; i += 32768) raw += String.fromCharCode(...bytes2.subarray(i, i + 32768));
+  return btoa(raw);
+}
+var unb64 = (s) => Uint8Array.from(atob(s), (c) => c.charCodeAt(0));
+async function derive(ikm, tenantId) {
+  if (!ikm || !tenantId) return null;
+  const base = await crypto.subtle.importKey("raw", new TextEncoder().encode(ikm), "HKDF", false, ["deriveKey"]);
+  return crypto.subtle.deriveKey(
+    { name: "HKDF", hash: "SHA-256", salt: new TextEncoder().encode(SALT), info: new TextEncoder().encode(`${INFO}\0${tenantId}`) },
+    base,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
+}
+function payloadOf(secrets) {
+  const payload = {};
+  for (const key of WAKE_SECRET_KEYS) {
+    const value = secrets[key];
+    if (value == null || value === "") continue;
+    if (typeof value !== "string" || value.length > MAX_WAKE_VALUE) return null;
+    payload[key] = value;
+  }
+  return payload;
+}
+async function sealWakeSecrets(ikm, tenantId, secrets) {
+  const key = await derive(ikm, tenantId);
+  const payload = payloadOf(secrets);
+  if (!key || !payload) return null;
+  const json = JSON.stringify(payload);
+  const encoded = new TextEncoder().encode(json);
+  if (json.length > MAX_WAKE_PLAIN || encoded.length > MAX_WAKE_PLAIN * 3) return null;
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ct = new Uint8Array(await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv, additionalData: new TextEncoder().encode(tenantId) },
+    key,
+    encoded
+  ));
+  const sealed = `v1.${b64(iv)}.${b64(ct)}`;
+  return sealed.length <= MAX_WAKE_SEALED ? sealed : null;
+}
+async function openWakeSecrets(ikm, tenantId, sealed) {
+  if (sealed == null || sealed === "") return {};
+  if (sealed.length > MAX_WAKE_SEALED) return null;
+  const key = await derive(ikm, tenantId);
+  if (!key) return null;
+  const [version, iv, ct, extra] = sealed.split(".");
+  if (version !== "v1" || !iv || !ct || extra !== void 0) return null;
+  try {
+    const plain = new TextDecoder().decode(await crypto.subtle.decrypt(
+      { name: "AES-GCM", iv: unb64(iv), additionalData: new TextEncoder().encode(tenantId) },
+      key,
+      unb64(ct)
+    ));
+    if (plain.length > MAX_WAKE_PLAIN) return null;
+    const parsed = JSON.parse(plain);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const out = {};
+    for (const name of WAKE_SECRET_KEYS) {
+      const value = parsed[name];
+      if (typeof value !== "string" || !value || value.length > MAX_WAKE_VALUE) continue;
+      out[name] = value;
+    }
+    return out;
+  } catch {
+    return null;
+  }
+}
+
 // src/tenants/create.ts
 function configuredFreeAgentLimit(value) {
   const trimmed = (value ?? "").trim();
@@ -265,7 +415,11 @@ async function createTenant(db, plane, input) {
   const hash = await sha2562(token);
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const region = regionOf(input.dataRegion);
+  const events = input.eventUrl && input.eventSecret ? pairingEventConfig(input.eventUrl, input.eventSecret) : null;
+  const sealedEvents = events ? await sealWakeSecrets((input.secretsKey || "").trim(), id, { EVENT_SECRET: events.EVENT_SECRET }) : null;
   const config = { AGENT_NAME: name };
+  if (events && sealedEvents) config.EVENT_URL = events.EVENT_URL;
+  const secretsEnc = sealedEvents;
   const version = 1;
   const domain = (input.domain || "").trim().toLowerCase().replace(/^\.+|\.+$/g, "");
   const publicUrl = domain ? `https://${name}.${domain}` : null;
@@ -281,8 +435,8 @@ async function createTenant(db, plane, input) {
         `INSERT INTO tenants (
 				   id, name, owner_account_id, status, region, config_json, limits_json, approval_json,
 				   owner_token_hash, secrets_enc, config_version, created_at, updated_at
-				 ) VALUES (?, ?, ?, 'active', ?, ?, '{}', ?, ?, NULL, ?, ?, ?)`
-      ).bind(id, name, input.accountId, region, JSON.stringify(config), JSON.stringify(approval), hash, version, now, now),
+				 ) VALUES (?, ?, ?, 'active', ?, ?, '{}', ?, ?, ?, ?, ?, ?)`
+      ).bind(id, name, input.accountId, region, JSON.stringify(config), JSON.stringify(approval), hash, secretsEnc, version, now, now),
       ...client ? [db.prepare(
         "INSERT INTO oauth_client (id, secret_hash, owner_account_id, redirect_uris, created_at) VALUES (?, ?, ?, ?, ?)"
       ).bind(client.clientId, client.secretHash, input.accountId, JSON.stringify(client.redirectUris), now)] : [],
@@ -303,7 +457,7 @@ async function createTenant(db, plane, input) {
     limits_json: "{}",
     approval_json: JSON.stringify(approval),
     owner_token_hash: hash,
-    secrets_enc: null,
+    secrets_enc: secretsEnc,
     version,
     created_at: now
   };
@@ -343,96 +497,6 @@ async function listTenants(db, accountId, domain) {
   }));
 }
 
-// src/tenants/wake-secrets.ts
-var INFO = "tenant-wake-secrets v1";
-var SALT = "a2a-exposed";
-var WAKE_SECRET_KEYS = [
-  "WAKE_WEBHOOK_KEY",
-  "WAKE_HMAC_SECRET",
-  "WAKE_ACCESS_CLIENT_ID",
-  "WAKE_ACCESS_CLIENT_SECRET"
-];
-var MAX_WAKE_VALUE = 4096;
-var MAX_WAKE_PLAIN = (() => {
-  let n = 2;
-  for (let i = 0; i < WAKE_SECRET_KEYS.length; i++) {
-    if (i) n += 1;
-    n += WAKE_SECRET_KEYS[i].length + 5 + MAX_WAKE_VALUE * 6;
-  }
-  return n;
-})();
-var MAX_WAKE_SEALED = 3 + 16 + 1 + Math.ceil((MAX_WAKE_PLAIN * 3 + 16) * 4 / 3);
-function b64(bytes2) {
-  let raw = "";
-  for (let i = 0; i < bytes2.length; i += 32768) raw += String.fromCharCode(...bytes2.subarray(i, i + 32768));
-  return btoa(raw);
-}
-var unb64 = (s) => Uint8Array.from(atob(s), (c) => c.charCodeAt(0));
-async function derive(ikm, tenantId) {
-  if (!ikm || !tenantId) return null;
-  const base = await crypto.subtle.importKey("raw", new TextEncoder().encode(ikm), "HKDF", false, ["deriveKey"]);
-  return crypto.subtle.deriveKey(
-    { name: "HKDF", hash: "SHA-256", salt: new TextEncoder().encode(SALT), info: new TextEncoder().encode(`${INFO}\0${tenantId}`) },
-    base,
-    { name: "AES-GCM", length: 256 },
-    false,
-    ["encrypt", "decrypt"]
-  );
-}
-function payloadOf(secrets) {
-  const payload = {};
-  for (const key of WAKE_SECRET_KEYS) {
-    const value = secrets[key];
-    if (value == null || value === "") continue;
-    if (typeof value !== "string" || value.length > MAX_WAKE_VALUE) return null;
-    payload[key] = value;
-  }
-  return payload;
-}
-async function sealWakeSecrets(ikm, tenantId, secrets) {
-  const key = await derive(ikm, tenantId);
-  const payload = payloadOf(secrets);
-  if (!key || !payload) return null;
-  const json = JSON.stringify(payload);
-  const encoded = new TextEncoder().encode(json);
-  if (json.length > MAX_WAKE_PLAIN || encoded.length > MAX_WAKE_PLAIN * 3) return null;
-  const iv = crypto.getRandomValues(new Uint8Array(12));
-  const ct = new Uint8Array(await crypto.subtle.encrypt(
-    { name: "AES-GCM", iv, additionalData: new TextEncoder().encode(tenantId) },
-    key,
-    encoded
-  ));
-  const sealed = `v1.${b64(iv)}.${b64(ct)}`;
-  return sealed.length <= MAX_WAKE_SEALED ? sealed : null;
-}
-async function openWakeSecrets(ikm, tenantId, sealed) {
-  if (sealed == null || sealed === "") return {};
-  if (sealed.length > MAX_WAKE_SEALED) return null;
-  const key = await derive(ikm, tenantId);
-  if (!key) return null;
-  const [version, iv, ct, extra] = sealed.split(".");
-  if (version !== "v1" || !iv || !ct || extra !== void 0) return null;
-  try {
-    const plain = new TextDecoder().decode(await crypto.subtle.decrypt(
-      { name: "AES-GCM", iv: unb64(iv), additionalData: new TextEncoder().encode(tenantId) },
-      key,
-      unb64(ct)
-    ));
-    if (plain.length > MAX_WAKE_PLAIN) return null;
-    const parsed = JSON.parse(plain);
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
-    const out = {};
-    for (const name of WAKE_SECRET_KEYS) {
-      const value = parsed[name];
-      if (typeof value !== "string" || !value || value.length > MAX_WAKE_VALUE) continue;
-      out[name] = value;
-    }
-    return out;
-  } catch {
-    return null;
-  }
-}
-
 // src/tenants/wake.ts
 var WAKE_PRESETS = ["grok-bot", "claude-code", "openclaw-wake", "openclaw-agent", "hermes", "generic"];
 var PLAIN_HEADERS = /* @__PURE__ */ new Set([
@@ -2134,8 +2198,18 @@ function inboxApprovalBindings(input) {
     { type: "plain_text", name: "APPROVAL_METHODS", text: "oidc" }
   ];
 }
+function inboxEventBindings(eventUrl, eventSecret) {
+  const url = httpsEventUrl(eventUrl);
+  const secret = eventSecretText(eventSecret);
+  if (!url || !secret) return null;
+  return [
+    { type: "plain_text", name: "EVENT_URL", text: url },
+    { type: "secret_text", name: "EVENT_SECRET", text: secret }
+  ];
+}
 function scriptMetadata(input) {
   const approval = inboxApprovalBindings(input.approvalOidc);
+  const events = inboxEventBindings(input.eventUrl, input.eventSecret);
   return {
     main_module: "index.js",
     compatibility_date: INBOX_COMPATIBILITY_DATE,
@@ -2147,7 +2221,8 @@ function scriptMetadata(input) {
       { type: "plain_text", name: "WAKE_PRESET", text: "generic" },
       { type: "plain_text", name: PROVISION_TAG_NAME, text: input.scriptTag },
       { type: "secret_text", name: "OWNER_TOKEN", text: input.ownerToken },
-      ...approval ?? []
+      ...approval ?? [],
+      ...events ?? []
     ]
   };
 }
@@ -2567,7 +2642,9 @@ async function runInboxStep(input) {
     migrations: input.migrations,
     grant,
     permissionDelaysMs: input.permissionDelaysMs ?? PERMISSION_DELAYS_MS,
-    approvalOidc: input.approvalOidc
+    approvalOidc: input.approvalOidc,
+    eventUrl: input.eventUrl,
+    eventSecret: input.eventSecret
   };
   try {
     if (next !== "verify") {
@@ -2853,7 +2930,7 @@ async function runUpload(ctx) {
     accountId,
     name: workerName,
     script: ctx.script,
-    metadata: scriptMetadata({ d1Id: databaseId, publicUrl, workerName, ownerToken, scriptTag, approvalOidc: ctx.approvalOidc })
+    metadata: scriptMetadata({ d1Id: databaseId, publicUrl, workerName, ownerToken, scriptTag, approvalOidc: ctx.approvalOidc, eventUrl: ctx.eventUrl, eventSecret: ctx.eventSecret })
   });
   if (uploaded2 !== true) {
     return { wizard: await failOrWait(ctx, "upload", uploaded2, "Cloudflare stops while uploading the inbox.", "upload") };
@@ -3056,6 +3133,7 @@ export {
   CONTROL_MIGRATIONS_DIR,
   D1_WRITE,
   DNS_WRITE,
+  EVENT_REPLAY_WINDOW_S,
   EVERY_PLAN,
   HOST_RE,
   INBOX_COMPATIBILITY_DATE,
@@ -3110,6 +3188,7 @@ export {
   deliverOutbox,
   describeCfFailure,
   describeSetupGrant,
+  eventSecretText,
   fieldsFromForm,
   findD1,
   flushOutbox,
@@ -3118,9 +3197,11 @@ export {
   grantedScopeSet,
   hashOwnerToken,
   headerSafeToken,
+  httpsEventUrl,
   httpsOrigin,
   inboxApprovalBindings,
   inboxCanProvision,
+  inboxEventBindings,
   listAccounts,
   listCloudflareInboxes,
   listTenants,
@@ -3132,6 +3213,7 @@ export {
   normalizeHostname,
   openCloudflareRefresh,
   openWakeSecrets,
+  pairingEventConfig,
   parseSetupChoice,
   parseSetupHost,
   permissionNotReady,
@@ -3167,6 +3249,7 @@ export {
   tenantForAccount,
   tenantNameProblem,
   uploadWorker,
+  verifyEventSignature,
   viewInboxWizard,
   wakeHeaderProblem,
   wakeSettingsOf,

package/dist/types/control/src/core/index.d.ts

@@ -26,7 +26,8 @@ export * from "../provision/statements.js";
 export * from "../provision/permission-wait.js";
 export * from "../provision/inbox-row.js";
 export * from "../provision/remove.js";
-export { INBOX_COMPATIBILITY_DATE, PERMISSION_DELAYS_MS, PERMISSION_TRIES, WIZARD_STEPS, createCloudflareAgent, dashboardLinks, fieldsFromForm, permissionRetryDue, inboxApprovalBindings, resumeFields, runInboxStep, viewInboxWizard, } from "../provision/inbox.js";
+export { INBOX_COMPATIBILITY_DATE, PERMISSION_DELAYS_MS, PERMISSION_TRIES, WIZARD_STEPS, createCloudflareAgent, dashboardLinks, fieldsFromForm, permissionRetryDue, inboxApprovalBindings, inboxEventBindings, resumeFields, runInboxStep, viewInboxWizard, } from "../provision/inbox.js";
+export { EVENT_REPLAY_WINDOW_S, eventSecretText, httpsEventUrl, pairingEventConfig, verifyEventSignature, } from "../tenants/events.js";
 export type { ApprovalOidcInput, InboxMigration, InboxWizard, ProvisionFields, WizardControl, WizardState, WizardStepId, WizardStepView, } from "../provision/inbox.js";
 export { INBOX_MIGRATIONS } from "../provision/inbox-migrations.js";
 export { CONTROL_MIGRATIONS, CONTROL_MIGRATIONS_DIR } from "./migrations.js";

package/dist/types/control/src/provision/inbox.d.ts

@@ -114,6 +114,11 @@ type ScriptBinding = {
  * has a value. Otherwise returns null and the upload keeps the approval password.
  */
 export declare function inboxApprovalBindings(input: ApprovalOidcInput | undefined): ScriptBinding[] | null;
+/**
+ * Bindings for a signed pairing event. Null unless the URL is https and the secret has a value,
+ * so a partial pair leaves the upload unchanged.
+ */
+export declare function inboxEventBindings(eventUrl?: string, eventSecret?: string): ScriptBinding[] | null;
 export declare function fieldsFromForm(form: FormData): ProvisionFields;
 export declare function resumeFields(value: {
     name?: unknown;
@@ -167,6 +172,9 @@ export declare function runInboxStep(input: {
      * Omit it and the agent stays on the approval password.
      */
     approvalOidc?: ApprovalOidcInput;
+    /** https URL and secret for pairing events. Both are required; a partial pair writes no EVENT_* binding. */
+    eventUrl?: string;
+    eventSecret?: string;
 }): Promise<{
     wizard: InboxWizard;
     ownerToken?: string;

package/dist/types/control/src/tenants/create.d.ts

@@ -31,6 +31,13 @@ export declare function createTenant(db: Sql, plane: DataPlane, input: {
     issuer?: string;
     label?: string;
     freeAgentLimit?: number | null;
+    /**
+     * https URL and secret for pairing events, plus the key that seals the secret.
+     * A partial pair, or a secret that cannot be sealed, is left out of the tenant.
+     */
+    eventUrl?: string;
+    eventSecret?: string;
+    secretsKey?: string;
 }): Promise<CreateResult>;
 export declare function listTenants(db: Sql, accountId: string, domain?: string): Promise<{
     id: string;

package/dist/types/control/src/tenants/events.d.ts

@@ -0,0 +1,19 @@
+/** How far `x-a2a-timestamp` may sit from the check, in seconds. */
+export declare const EVENT_REPLAY_WINDOW_S = 300;
+/** https URL with no userinfo, at most 2000 characters. Any other value returns "". */
+export declare function httpsEventUrl(value: string | undefined): string;
+/** Shared secret for the HMAC. Empty when missing, too long, or it contains a control character. */
+export declare function eventSecretText(value: string | undefined): string;
+/**
+ * Tenant config fields for pairing events. Null unless the URL is https and the secret has a value,
+ * so a partial pair is left out of the push.
+ */
+export declare function pairingEventConfig(eventUrl: string, eventSecret: string): {
+    EVENT_URL: string;
+    EVENT_SECRET: string;
+} | null;
+/**
+ * True when `x-a2a-signature` is the HMAC-SHA256 of the timestamp, a period, and the raw body,
+ * and `x-a2a-timestamp` is within 5 minutes of `now`. The header value is `sha256=<hex>`.
+ */
+export declare function verifyEventSignature(body: string, headers: Headers | Record<string, string | null | undefined>, secret: string, now?: number): Promise<boolean>;

package/dist/types/control/src/tenants/wake-secrets.d.ts

@@ -1,5 +1,5 @@
-/** Secret wake fields. Anything else in the blob is ignored. */
-export declare const WAKE_SECRET_KEYS: readonly ["WAKE_WEBHOOK_KEY", "WAKE_HMAC_SECRET", "WAKE_ACCESS_CLIENT_ID", "WAKE_ACCESS_CLIENT_SECRET"];
+/** Sealed secret fields. Anything else in the blob is ignored. */
+export declare const WAKE_SECRET_KEYS: readonly ["WAKE_WEBHOOK_KEY", "WAKE_HMAC_SECRET", "WAKE_ACCESS_CLIENT_ID", "WAKE_ACCESS_CLIENT_SECRET", "EVENT_SECRET"];
 export type WakeSecretKey = (typeof WAKE_SECRET_KEYS)[number];
 export type WakeSecrets = Partial<Record<WakeSecretKey, string>>;
 /** One secret. The form uses the same cap. */
@@ -11,6 +11,11 @@ export declare const MAX_WAKE_VALUE = 4096;
 export declare const MAX_WAKE_PLAIN: number;
 /** `v1.` + base64(12-byte iv) + `.` + base64(utf-8 plaintext + 16-byte tag). */
 export declare const MAX_WAKE_SEALED: number;
+/**
+ * Config written next to a sealed blob. The sealed fields stay in `secrets_enc`.
+ * With no ciphertext, the config is returned unchanged.
+ */
+export declare function omitSealedSecrets<T extends Record<string, unknown>>(config: T, secretsEnc: string | null | undefined): T;
 /** `v1.<iv>.<ciphertext>`, or null when the key or a value is unusable. */
 export declare function sealWakeSecrets(ikm: string, tenantId: string, secrets: WakeSecrets): Promise<string | null>;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@a2a-exposed/control-core",
-	"version": "0.8.8",
+	"version": "0.8.10",
 	"description": "A2A endpoint provisioning, routing, and D1 migrations for a2a-exposed.",
 	"type": "module",
 	"scripts": {