@a2a-exposed/control-core 0.8.6 → 0.8.8

package/README.md

@@ -2,7 +2,7 @@
 
 [![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 in an inbox. Webhooks wake your agent. Without one, it polls, guided by next-check hints. The agent reads the inbox 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 inbox 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. 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`.
 
 ## Who it's for
 
@@ -18,7 +18,7 @@ Requires Node 22.18+. The skills are installed into the project the agent works
    npx -y skills add telegraphic-dev/a2a-exposed
    ```
 
-2. **Deploy an inbox** 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.
+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.
 
    ```bash
    npx -y a2a-exposed@latest init --hostname agent.example.com --agent-name "My Agent"
@@ -33,13 +33,13 @@ Requires Node 22.18+. The skills are installed into the project the agent works
    npx -y a2a-exposed@latest pair set-password --web
    ```
 
-   `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 10 minutes). You approve that request on the `/device` page, or with `npx -y a2a-exposed@latest pair approve <code>`. Removing the inbox later is `npx -y a2a-exposed@latest uninstall` ([Self-hosting](docs/self-hosting.md#remove-an-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)).
 
 After the skill is in the project, you can ask the agent to set this up. It follows the setup skill. Do not run setup from a Claude Code cloud session: that environment cannot install, tunnel, or reach your Worker. 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.
 
 ## Hosted
 
-[a2a.exposed](https://a2a.exposed) hosts the inbox and is open to everyone. Pricing is at [a2a.exposed/pricing](https://a2a.exposed/pricing). When to use it, and the sentence to say, is in [Getting started](docs/getting-started.md#hosted-inbox).
+[a2a.exposed](https://a2a.exposed) hosts the A2A endpoint and is open to everyone. Pricing is at [a2a.exposed/pricing](https://a2a.exposed/pricing). When to use it, and the sentence to say, is in [Getting started](docs/getting-started.md#hosted-inbox).
 
 ## Docs
 
@@ -47,13 +47,13 @@ After the skill is in the project, you can ask the agent to set this up. It foll
 | --- | --- |
 | [Getting started](docs/getting-started.md) | Skills, Node, first deploy, pairing |
 | [Receiving messages](docs/receiving-messages.md) | Webhooks wake your agent. Without one, it polls, guided by next-check hints |
-| [Self-hosting](docs/self-hosting.md) | Cloudflare inbox, workers.dev, tunnel, uninstall, public façade |
+| [Self-hosting](docs/self-hosting.md) | Cloudflare A2A endpoint, workers.dev, tunnel, uninstall, public façade |
 | [CLI](docs/cli.md) | Commands, flags, config |
 | [MCP](docs/mcp.md) | Remote connector at `/mcp` |
 | [Feedback](docs/feedback.md) | Report a bug or an idea |
 | [Security](docs/security.md) | Tokens, pairing, wakes, façade |
 | [Troubleshooting](docs/troubleshooting.md) | FAQ and common failures |
-| [Upgrading](docs/upgrading.md) | Move an existing inbox forward |
+| [Upgrading](docs/upgrading.md) | Move an existing A2A endpoint forward |
 | [Protocol](docs/protocol.md) | A2A 1.0 and 0.3, OAuth, endpoints |
 
 Changes are listed in [CHANGELOG.md](CHANGELOG.md). Agent workflows live in [`skills/`](skills/a2a-exposed/SKILL.md).

package/dist/index.js

@@ -2097,7 +2097,45 @@ async function releaseWorking(db, inboxId, now) {
   const row = await readInboxById(db, inboxId);
   if (row?.status === "working") await patchInbox(db, inboxId, now, { status: "pending" });
 }
+function httpsIssuer(value) {
+  const raw = value.trim();
+  if (!raw || raw.length > 300) return "";
+  try {
+    const url = new URL(raw);
+    if (url.protocol !== "https:" || url.username || url.password) return "";
+    return raw;
+  } catch {
+    return "";
+  }
+}
+function plainCredential(value, max) {
+  const text = value.trim();
+  if (!text || text.length > max || /[\u0000-\u001f]/.test(text)) return "";
+  return text;
+}
+function subjectsText(value) {
+  const list = typeof value === "string" ? value.split(",") : value;
+  const subjects = list.map((item) => item.trim()).filter((item) => item && !/[\u0000-\u001f]/.test(item));
+  const text = subjects.join(",");
+  return text && text.length <= 2e3 ? text : "";
+}
+function inboxApprovalBindings(input) {
+  if (!input) return null;
+  const issuer = httpsIssuer(input.issuer);
+  const clientId = plainCredential(input.clientId, 200);
+  const clientSecret = plainCredential(input.clientSecret, 512);
+  const allowed = subjectsText(input.allowedSubjects);
+  if (!issuer || !clientId || !clientSecret || !allowed) return null;
+  return [
+    { type: "plain_text", name: "APPROVAL_OIDC_ISSUER", text: issuer },
+    { type: "plain_text", name: "APPROVAL_OIDC_CLIENT_ID", text: clientId },
+    { type: "secret_text", name: "APPROVAL_OIDC_CLIENT_SECRET", text: clientSecret },
+    { type: "plain_text", name: "APPROVAL_OIDC_ALLOWED_SUBJECTS", text: allowed },
+    { type: "plain_text", name: "APPROVAL_METHODS", text: "oidc" }
+  ];
+}
 function scriptMetadata(input) {
+  const approval = inboxApprovalBindings(input.approvalOidc);
   return {
     main_module: "index.js",
     compatibility_date: INBOX_COMPATIBILITY_DATE,
@@ -2108,7 +2146,8 @@ function scriptMetadata(input) {
       { type: "plain_text", name: "PAIRING_APPROVAL", text: "human" },
       { 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 }
+      { type: "secret_text", name: "OWNER_TOKEN", text: input.ownerToken },
+      ...approval ?? []
     ]
   };
 }
@@ -2527,7 +2566,8 @@ async function runInboxStep(input) {
     script: input.script,
     migrations: input.migrations,
     grant,
-    permissionDelaysMs: input.permissionDelaysMs ?? PERMISSION_DELAYS_MS
+    permissionDelaysMs: input.permissionDelaysMs ?? PERMISSION_DELAYS_MS,
+    approvalOidc: input.approvalOidc
   };
   try {
     if (next !== "verify") {
@@ -2813,7 +2853,7 @@ async function runUpload(ctx) {
     accountId,
     name: workerName,
     script: ctx.script,
-    metadata: scriptMetadata({ d1Id: databaseId, publicUrl, workerName, ownerToken, scriptTag })
+    metadata: scriptMetadata({ d1Id: databaseId, publicUrl, workerName, ownerToken, scriptTag, approvalOidc: ctx.approvalOidc })
   });
   if (uploaded2 !== true) {
     return { wizard: await failOrWait(ctx, "upload", uploaded2, "Cloudflare stops while uploading the inbox.", "upload") };
@@ -3079,6 +3119,7 @@ export {
   hashOwnerToken,
   headerSafeToken,
   httpsOrigin,
+  inboxApprovalBindings,
   inboxCanProvision,
   listAccounts,
   listCloudflareInboxes,

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

@@ -26,8 +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, resumeFields, runInboxStep, viewInboxWizard, } from "../provision/inbox.js";
-export type { InboxMigration, InboxWizard, ProvisionFields, WizardControl, WizardState, WizardStepId, WizardStepView, } from "../provision/inbox.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 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";
 export type { ControlMigration } from "./migrations.js";

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

@@ -89,6 +89,31 @@ interface StoredStepNote {
 }
 /** A new Cloudflare agent. The finished ones stay. */
 export declare function createCloudflareAgent(db: Sql, userId: string, host: SetupHost, now?: number): Promise<string>;
+/** Account sign-in for a Cloudflare agent. The dashboard creates the client and passes these four fields. */
+export type ApprovalOidcInput = {
+    issuer: string;
+    clientId: string;
+    clientSecret: string;
+    allowedSubjects: string | readonly string[];
+};
+type ScriptBinding = {
+    type: "d1";
+    name: string;
+    id: string;
+} | {
+    type: "plain_text";
+    name: string;
+    text: string;
+} | {
+    type: "secret_text";
+    name: string;
+    text: string;
+};
+/**
+ * Worker bindings for account sign-in. Returns the list when the issuer is https and every field
+ * has a value. Otherwise returns null and the upload keeps the approval password.
+ */
+export declare function inboxApprovalBindings(input: ApprovalOidcInput | undefined): ScriptBinding[] | null;
 export declare function fieldsFromForm(form: FormData): ProvisionFields;
 export declare function resumeFields(value: {
     name?: unknown;
@@ -136,6 +161,12 @@ export declare function runInboxStep(input: {
     fetchImpl?: typeof fetch;
     /** Pauses after a permission error. Tests pass zeros. Production waits about 15 seconds across 4 tries. */
     permissionDelaysMs?: number[];
+    /**
+     * Account sign-in for this Cloudflare agent. When issuer, client id, client secret, and allowed
+     * subjects are all set, the upload writes the APPROVAL_OIDC_* bindings and APPROVAL_METHODS=oidc.
+     * Omit it and the agent stays on the approval password.
+     */
+    approvalOidc?: ApprovalOidcInput;
 }): Promise<{
     wizard: InboxWizard;
     ownerToken?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@a2a-exposed/control-core",
-	"version": "0.8.6",
-	"description": "Inbox provisioning, routing, and D1 migrations for a2a-exposed.",
+	"version": "0.8.8",
+	"description": "A2A endpoint provisioning, routing, and D1 migrations for a2a-exposed.",
 	"type": "module",
 	"scripts": {
 		"prepare": "node control/scripts/build-core.mjs",