@a2a-exposed/control-core 0.8.26 → 0.8.28

package/README.md

@@ -2,50 +2,29 @@
 
 [![npm](https://img.shields.io/npm/v/a2a-exposed)](https://www.npmjs.com/package/a2a-exposed) [![CI](https://github.com/telegraphic-dev/a2a-exposed/actions/workflows/ci.yml/badge.svg)](https://github.com/telegraphic-dev/a2a-exposed/actions/workflows/ci.yml)
 
-a2a-exposed gives an AI agent a public [A2A](https://a2a-protocol.org) address. A Cloudflare Worker serves the agent card and the JSON-RPC endpoint. Inbound messages become tasks on the A2A endpoint. Webhooks wake your agent. Without one, it polls, guided by next-check hints. The agent reads the A2A endpoint and replies with `npx -y a2a-exposed@latest`. The same command sends messages to other A2A agents (1.0 or 0.3). The owner pages on that A2A endpoint are `/` and `/device`.
+a2a-exposed gives an AI agent a public [A2A](https://a2a-protocol.org) address. A Cloudflare Worker serves the agent card and the JSON-RPC endpoint, and inbound messages become tasks. Webhooks wake your agent, or the agent polls. The owner pages are `/` and `/device`.
 
 ## Who it's for
 
 Agents that can call out over HTTP and cannot run a public server: hosted assistants, coding agents, routines, and chat bots. Peers discover the card at `https://<host>/.well-known/agent-card.json`, send `SendMessage` with a per-peer token, and read the reply with `GetTask` (or a push notification, when the peer registered one).
 
-## Quick start
-
-No Cloudflare account, or no preference? Start with a [hosted agent](docs/getting-started.md#hosted-inbox) at `https://<name>.a2a.exposed`. It is in open beta with a Free plan; see [pricing](https://a2a.exposed/pricing).
-
-Claude Code cloud sessions use the [hosted connector](docs/mcp.md#hosted-connector), with no skill install or CLI. Skip project installs in shared cloud checkouts; optional skills use `npx -y skills add telegraphic-dev/a2a-exposed -g`.
-
-Self-hosting requires Node 22.18+. The skills are installed into the project the agent works in. They do not install the CLI. Every command runs through npx.
-
-1. **Add the skills to the project**
-
-   ```bash
-   npx -y skills add telegraphic-dev/a2a-exposed
-   ```
-
-2. **Deploy an A2A endpoint** in your Cloudflare account. [Self-hosting](docs/self-hosting.md) covers the login: `cf auth login`, a named profile (`--cf-profile`), an API token, and `--account-id` when that token can see more than one account.
-
-   Before running `init` or another Cloudflare change, the agent shows you the account name/id from `npx cf auth whoami` and the plan: Worker name, D1 database, hostname and any workers.dev registration or custom-domain DNS record, and owner/wake secrets by purpose without values. It waits for your explicit yes; a login is not consent. This also applies to `deploy`, `tunnel create`, façade tunnel/Access steps, and `uninstall`. See the [consent checklist](skills/a2a-exposed-setup/references/deploy.md#before-cloudflare-changes). Ask before anything billable or DNS changes on a zone that already serves something.
-
-   ```bash
-   npx -y a2a-exposed@latest init --hostname agent.example.com --agent-name "My Agent"
-   ```
-
-   Omit `--hostname` to serve on `*.workers.dev`. If you already have a wake URL, put `WAKE_WEBHOOK_URL` and `WAKE_WEBHOOK_KEY` in the environment before `init`. Never pass secrets on the command line.
+## Hosted
 
-3. **Check the deployment, then let peers connect**
+No Cloudflare account is required. [a2a.exposed](https://a2a.exposed/hosted) hosts the A2A endpoint and is open to everyone. It is in open beta with a Free plan; see [pricing](https://a2a.exposed/pricing). Sign in at https://a2a.exposed/app and create an agent at `https://<name>.a2a.exposed`.
 
-   ```bash
-   npx -y a2a-exposed@latest status
-   npx -y a2a-exposed@latest pair set-password --web
-   ```
+When the CLI cannot run, connect https://a2a.exposed/mcp. Sign-in is the owner identity. The owner token stays on the A2A endpoint. Claude Code cloud sessions use the [hosted connector](docs/mcp.md#hosted-connector). The steps are in [Getting started](docs/getting-started.md#hosted-inbox).
 
-   `status` is read-only and prints the next step. Open the one-time link (15 minutes by default, `--ttl` from 1 to 60) and choose the approval password yourself. Another agent then runs `npx -y a2a-exposed@latest connect https://agent.example.com` (the code lasts 60 minutes). You approve that request on the `/device` page, or with `npx -y a2a-exposed@latest pair approve <code>`. Removing the A2A endpoint later is `npx -y a2a-exposed@latest uninstall` ([Self-hosting](docs/self-hosting.md#remove-an-inbox)).
+## Self-host
 
-After the skill is in the project, you can ask the agent to set this up. It follows the setup skill. Claude Code cloud sessions follow the [hosted checklist](docs/mcp.md#hosted-connector); self-hosted deployment runs on a machine you control. Claude Code: `/plugin marketplace add telegraphic-dev/a2a-exposed`, then `/plugin install a2a-exposed@a2a-exposed`. [Getting started](docs/getting-started.md) has Node, the client table, and what to do if setup stops halfway.
+Self-hosting needs Node 22.18+. Commands run through npx. Confirm the Cloudflare account and the plan before `init` changes it. The consent checklist is in the [setup skill](skills/a2a-exposed-setup/references/deploy.md#before-cloudflare-changes). [Self-hosting](docs/self-hosting.md) covers login, API tokens, and `--account-id`.
 
-## Hosted
+```bash
+npx -y skills add telegraphic-dev/a2a-exposed
+npx -y a2a-exposed@latest init --hostname agent.example.com --agent-name "My Agent"
+npx -y a2a-exposed@latest status
+```
 
-[a2a.exposed](https://a2a.exposed/hosted) hosts the A2A endpoint and is open to everyone. Pricing is at [a2a.exposed/pricing](https://a2a.exposed/pricing). Sign in at https://a2a.exposed/app to create an agent; no Cloudflare account is needed. When the CLI cannot run, connect https://a2a.exposed/mcp. Sign-in is the owner identity. The owner token stays on the A2A endpoint. Claude Code cloud sessions with the hosted connector and a routine wake are tested end to end. Other Claude clients and Codex are untested on this address. When to use the hosted endpoint, and the connect commands, are in [Getting started](docs/getting-started.md#hosted-inbox).
+Omit `--hostname` to serve on `*.workers.dev`. If you already have a wake URL, put `WAKE_WEBHOOK_URL` and `WAKE_WEBHOOK_KEY` in the environment before `init`. Never pass secrets on the command line. Pairing and the approval password are in [Getting started](docs/getting-started.md).
 
 ## Docs
 

package/dist/index.js

@@ -3182,6 +3182,324 @@ var CONTROL_MIGRATIONS = [
   { name: "0014_cloudflare_inbox_agent.sql", sql: cloudflare_inbox_agent_default },
   { name: "0015_cloudflare_grant_access.sql", sql: cloudflare_grant_access_default }
 ];
+
+// src/core/redact.ts
+var REDACTED = "[redacted]";
+var TOKEN_RE = /(?:a2aow_|s2a_|a2amcpr_|a2amcp_|a2aot_)[A-Za-z0-9_-]{20,}/g;
+var USERINFO_RE = /([a-z][a-z0-9+.-]*:\/\/)[^/?\s]*@/gi;
+var BEARER_RE = /(bearer\s+)(\S{8,})/gi;
+var BASIC_RE = /(basic\s+)(\S+)/gi;
+var PEM_RE = /-----BEGIN (?:[A-Z0-9]+ )?PRIVATE KEY-----[\s\S]*?(?:-----END (?:[A-Z0-9]+ )?PRIVATE KEY-----|$)/g;
+var API_KEY_RE = /(?:(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|\bAKIA[0-9A-Z]{16}\b|\bsk_(?:live|test)_[A-Za-z0-9]{10,}|\brk_(?:live|test)_[A-Za-z0-9]{10,}|\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}|\bxox[baprs]-[A-Za-z0-9-]{10,}|\bAIza[0-9A-Za-z_-]{35}\b)/g;
+var JWT_RE = /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g;
+var AUTH_RE = /\b((?:proxy-)?authorization)(\s*[:=]\s*)([^\n]+)/gi;
+var QUERY_RE = /(^|[?&#\s])([^?&#\s="'<>]+)(\s*=\s*)("(?:\\.|[^"\\])*(?:"|$)|'(?:\\.|[^'\\])*(?:'|$)|(?:\\(?!["'])|[^&#\s"'<>\\])*)/g;
+var ASSIGN_RE = /\b([A-Za-z_][A-Za-z0-9_]*)(\s*=\s*)/g;
+var SECRET_EXACT = /* @__PURE__ */ new Set([
+  "authorization",
+  "proxyauthorization",
+  "cookie",
+  "setcookie",
+  "password",
+  "passwd",
+  "secret",
+  "token",
+  "apikey",
+  "accesstoken",
+  "refreshtoken",
+  "idtoken",
+  "clientsecret",
+  "privatekey",
+  "hmacsecret",
+  "credential",
+  "credentials",
+  "bearer",
+  "webhookkey",
+  "accessclientid",
+  "accessclientsecret"
+]);
+var SECRET_SUFFIX = [
+  "authorization",
+  "token",
+  "secret",
+  "password",
+  "passwd",
+  "credential",
+  "credentials",
+  "apikey",
+  "clientsecret",
+  "privatekey",
+  "webhookkey",
+  "accessclientid",
+  "accessclientsecret",
+  "cookie"
+];
+function parameterName(name) {
+  return name.replace(/\+/g, " ").replace(/(?:%[0-9a-f]{2})+/gi, (encoded) => {
+    try {
+      return decodeURIComponent(encoded);
+    } catch {
+      return encoded.replace(/%([0-7][0-9a-f])/gi, (_all, hex) => String.fromCharCode(parseInt(hex, 16)));
+    }
+  });
+}
+function compactName(name) {
+  return name.trim().toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function secretName(name) {
+  const compact = compactName(name);
+  if (!compact || compact === "key" || compact === "name" || compact === "value" || compact === "id") return false;
+  if (SECRET_EXACT.has(compact)) return true;
+  return SECRET_SUFFIX.some((suffix) => compact.length > suffix.length && compact.endsWith(suffix));
+}
+function replaceAll(value, pattern, replacement) {
+  pattern.lastIndex = 0;
+  return value.replace(pattern, replacement);
+}
+function quotedValueEnd(text, start) {
+  const quote = text[start];
+  if (quote !== '"' && quote !== "'") return -1;
+  for (let i = start + 1; i < text.length; i += 1) {
+    if (text[i] === "\\") {
+      i += 1;
+      continue;
+    }
+    if (text[i] === quote) return i + 1;
+  }
+  return text.length;
+}
+function unquotedValueEnd(text, start) {
+  let i = start;
+  while (i < text.length && !/\s/.test(text[i])) i += 1;
+  return i;
+}
+function redactAssignments(text) {
+  const pattern = new RegExp(ASSIGN_RE.source, "g");
+  const parameters = Array.from(text.matchAll(new RegExp(QUERY_RE.source, "g")));
+  let parameter = 0;
+  let out = "";
+  let last = 0;
+  let match;
+  while ((match = pattern.exec(text)) !== null) {
+    while (parameter < parameters.length && parameters[parameter].index + parameters[parameter][0].length <= match.index) parameter += 1;
+    if (parameter < parameters.length && parameters[parameter].index <= match.index) continue;
+    const name = match[1] ?? "";
+    if (!secretName(name)) continue;
+    const sep = match[2] ?? "=";
+    const valueStart = match.index + match[0].length;
+    const quoted = quotedValueEnd(text, valueStart);
+    const valueEnd = quoted >= 0 ? quoted : unquotedValueEnd(text, valueStart);
+    out += text.slice(last, match.index);
+    out += secretName(name) && valueEnd > valueStart ? `${name}${sep}${REDACTED}` : text.slice(match.index, valueEnd);
+    last = valueEnd;
+    pattern.lastIndex = valueEnd;
+  }
+  return out + text.slice(last);
+}
+function jsonValueEnd(text, start) {
+  if (text[start] === '"') return quotedValueEnd(text, start);
+  if (text[start] === "[" || text[start] === "{") {
+    const closers = [text[start] === "[" ? "]" : "}"];
+    for (let i = start + 1; i < text.length; i += 1) {
+      const char = text[i];
+      if (char === '"') i = quotedValueEnd(text, i) - 1;
+      else if (char === "[" || char === "{") closers.push(char === "[" ? "]" : "}");
+      else if (char === closers[closers.length - 1]) {
+        closers.pop();
+        if (!closers.length) return i + 1;
+      }
+    }
+    return text.length;
+  }
+  let end = start;
+  while (end < text.length && !/[\s,}\]]/.test(text[end])) end += 1;
+  return end;
+}
+function redactJsonFields(text, depth, cache) {
+  let out = "";
+  let last = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    if (text[i] !== '"') continue;
+    const keyEnd = quotedValueEnd(text, i);
+    let cursor = keyEnd;
+    while (/\s/.test(text[cursor] ?? "") && cursor < text.length) cursor += 1;
+    if (text[cursor] === ":") {
+      let name;
+      try {
+        name = JSON.parse(text.slice(i, keyEnd));
+      } catch {
+        i = keyEnd - 1;
+        continue;
+      }
+      if (secretName(name)) {
+        cursor += 1;
+        while (cursor < text.length && /\s/.test(text[cursor])) cursor += 1;
+        const end = jsonValueEnd(text, cursor);
+        if (end > cursor) {
+          out += text.slice(last, cursor) + JSON.stringify(REDACTED);
+          last = end;
+          i = end - 1;
+          continue;
+        }
+      }
+    }
+    if (text[cursor] !== ":") {
+      try {
+        const decoded = JSON.parse(text.slice(i, keyEnd));
+        const cleaned = redactNested(decoded, depth + 1, cache);
+        if (cleaned !== decoded) {
+          out += text.slice(last, i) + JSON.stringify(cleaned);
+          last = keyEnd;
+        }
+      } catch {
+      }
+    }
+    i = keyEnd - 1;
+  }
+  return out + text.slice(last);
+}
+function redactNested(value, depth, cache = /* @__PURE__ */ new Map()) {
+  try {
+    if (depth >= 64) return REDACTED;
+    const key = depth + ":" + value;
+    const cached = cache.get(key);
+    if (cached !== void 0) return cached;
+    const text = redactText(value, depth, cache);
+    const decoded = parameterName(text);
+    let result = text;
+    if (decoded !== text) {
+      const cleaned = redactNested(decoded, depth + 1, cache);
+      if (cleaned !== decoded) result = encodeURIComponent(cleaned);
+    }
+    cache.set(key, result);
+    return result;
+  } catch {
+    return REDACTED;
+  }
+}
+function redactText(value, depth, cache) {
+  let text = redactJsonFields(value, depth, cache);
+  text = replaceAll(text, PEM_RE, REDACTED);
+  text = replaceAll(text, JWT_RE, REDACTED);
+  text = replaceAll(text, API_KEY_RE, REDACTED);
+  text = replaceAll(text, TOKEN_RE, REDACTED);
+  text = replaceAll(text, BEARER_RE, `$1${REDACTED}`);
+  text = replaceAll(text, BASIC_RE, `$1${REDACTED}`);
+  text = replaceAll(text, AUTH_RE, (_all, name, sep, rest) => {
+    if (rest.trim().length < 8 && !/bearer|basic/i.test(rest)) return `${name}${sep}${rest}`;
+    return `${name}${sep}${REDACTED}`;
+  });
+  text = replaceAll(text, USERINFO_RE, `$1${REDACTED}@`);
+  const cleanParameter = (all, sep, name, assignment, item) => {
+    let decoded = name;
+    while (true) {
+      const next = parameterName(decoded);
+      if (next === decoded) break;
+      decoded = next;
+    }
+    let setup = false;
+    if (decoded.trim().toLowerCase() === "t") {
+      let candidate = item.replace(/^["']|["']$/g, "");
+      while (true) {
+        const next = parameterName(candidate);
+        if (next === candidate) break;
+        candidate = next;
+      }
+      setup = /^[A-Za-z0-9_-]{16,}/.test(candidate);
+    }
+    if (!item) return all;
+    if (!secretName(decoded) && !setup) {
+      const quote = item[0];
+      const wrapped = (quote === '"' || quote === "'") && item.endsWith(quote) && item.length > 1;
+      const cleaned = wrapped ? quote + redactNested(item.slice(1, -1), depth + 1, cache) + quote : redactNested(item, depth + 1, cache);
+      return `${sep}${name}${assignment}${cleaned}`;
+    }
+    return `${sep}${name}${assignment}${REDACTED}`;
+  };
+  const strings = [];
+  for (let i = 0; i < text.length; i += 1) {
+    if (text[i] !== '"') continue;
+    const end = quotedValueEnd(text, i);
+    try {
+      JSON.parse(text.slice(i, end));
+      strings.push([i, end]);
+    } catch {
+    }
+    i = end - 1;
+  }
+  const parameters = new RegExp(QUERY_RE.source, "g");
+  let out = "";
+  let last = 0;
+  let match;
+  while ((match = parameters.exec(text)) !== null) {
+    if (strings.some(([start, end2]) => match.index >= start && match.index < end2)) continue;
+    const valueStart = match.index + match[1].length + match[2].length + match[3].length;
+    const quoted = quotedValueEnd(text, valueStart);
+    let end = quoted >= 0 ? quoted : valueStart;
+    while (end < text.length && !/[&#\s<>]/.test(text[end])) {
+      if ((text[end] === '"' || text[end] === "'") && (quoted >= 0 || text[end - 1] === "=")) end = quotedValueEnd(text, end);
+      else end += 1;
+    }
+    match[4] = text.slice(valueStart, end);
+    match[0] = text.slice(match.index, end);
+    parameters.lastIndex = end;
+    const cleaned = cleanParameter(match[0], match[1], match[2], match[3], match[4]);
+    if (cleaned === match[0]) {
+      parameters.lastIndex = match.index + match[1].length + match[2].length + match[3].length;
+      continue;
+    }
+    out += text.slice(last, match.index) + cleaned;
+    last = parameters.lastIndex;
+  }
+  text = out + text.slice(last);
+  text = redactAssignments(text);
+  return text;
+}
+function own(record, name) {
+  for (const key of Object.keys(record)) {
+    if (key.toLowerCase() === name) return { key, value: record[key] };
+  }
+  return null;
+}
+function pairLabel(record) {
+  const name = own(record, "name");
+  const key = own(record, "key");
+  if (name && typeof name.value === "string" && secretName(name.value)) return name.value;
+  if (key && typeof key.value === "string" && secretName(key.value)) return key.value;
+  return "";
+}
+function walk(value, seen) {
+  if (typeof value === "string") return redactNested(value, 0);
+  if (!value || typeof value !== "object") return value;
+  if (seen.has(value)) return REDACTED;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    if (value.length === 2 && typeof value[0] === "string" && secretName(value[0])) return [value[0], REDACTED];
+    return value.map((item) => walk(item, seen));
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return value;
+  const record = value;
+  const hidden = /* @__PURE__ */ new Set();
+  const valueField = own(record, "value");
+  if (valueField && pairLabel(record)) hidden.add(valueField.key);
+  const out = {};
+  for (const [key, item] of Object.entries(record)) {
+    if (hidden.has(key) || secretName(key)) {
+      out[key] = REDACTED;
+      continue;
+    }
+    out[key] = walk(item, seen);
+  }
+  return out;
+}
+function sanitized(value) {
+  return walk(value, /* @__PURE__ */ new WeakSet());
+}
+function redact(value) {
+  if (typeof value === "string") return redactNested(value, 0);
+  return sanitized(value);
+}
 export {
   ACCOUNT_SETTINGS_READ,
   CONTROL_MIGRATIONS,
@@ -3278,6 +3596,7 @@ export {
   readCloudflareInbox,
   readCloudflareInboxById,
   readInboxById,
+  redact,
   refreshCloudflareGrant,
   refreshTokenAfterResponse,
   registerWorkersDevSubdomain,
@@ -3292,6 +3611,7 @@ export {
   runInboxStep,
   runRemovalStep,
   sanitizeCloudflareText,
+  sanitized,
   saveCloudflareGrant,
   saveWakeSettings,
   sealCloudflareRefresh,

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

@@ -32,3 +32,4 @@ export type { ApprovalOidcInput, InboxMigration, InboxWizard, ProvisionFields, W
 export { INBOX_MIGRATIONS } from "../provision/inbox-migrations.js";
 export { CONTROL_MIGRATIONS, CONTROL_MIGRATIONS_DIR } from "./migrations.js";
 export type { ControlMigration } from "./migrations.js";
+export { redact, sanitized } from "./redact.js";

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

@@ -0,0 +1,9 @@
+/**
+ * Copy `value` with secrets removed.
+ * A `{ name, value }` or `{ key, value }` pair, and a `[name, value]` pair, lose `value`
+ * when that name is a secret. A pair whose name is an ordinary field stays.
+ */
+export declare function sanitized<T>(value: T): T;
+/** Remove secrets from text. An object is copied with {@link sanitized}. */
+export declare function redact(value: string): string;
+export declare function redact(value: unknown): unknown;

package/package.json

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