a2a-exposed 0.8.21 → 0.8.23

package/lib/address.mjs

@@ -0,0 +1,129 @@
+// Announce this inbox's address to paired peers, and keep the previous address forwarding for a grace period.
+// The pairing identity private key stays in peer-identity.json (mode 600) or sealed on the Worker. It is never printed.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import * as C from "./config.mjs";
+import { CLI, die, httpJson } from "./a2a.mjs";
+import { baseUrl } from "./commands.mjs";
+
+const IDENTITY_FILE = () => path.join(C.CONFIG_DIR, "peer-identity.json");
+
+function b64url(buf) {
+	return Buffer.from(buf).toString("base64url");
+}
+
+/** Local Ed25519 key, created on first use. The file is mode 600. */
+export function loadOrCreateLocalIdentity() {
+	const file = IDENTITY_FILE();
+	try {
+		const cur = JSON.parse(fs.readFileSync(file, "utf8"));
+		if (cur && typeof cur.publicKey === "string" && typeof cur.privateKey === "string" && cur.publicKey && cur.privateKey)
+			return { publicKey: cur.publicKey, privateKey: cur.privateKey };
+	} catch { /* create below */ }
+	const kp = crypto.generateKeyPairSync("ed25519");
+	// JWK `x` is the raw 32-byte public key. PKCS8 is what the Worker imports. Both are base64url.
+	const publicKey = kp.publicKey.export({ format: "jwk" }).x;
+	const privateKey = b64url(kp.privateKey.export({ type: "pkcs8", format: "der" }));
+	const ident = { publicKey, privateKey };
+	if (!ident.publicKey || !ident.privateKey) die("could not create a pairing identity");
+	fs.mkdirSync(C.CONFIG_DIR, { recursive: true, mode: 0o700 });
+	fs.writeFileSync(file, JSON.stringify(ident, null, 2) + "\n", { mode: 0o600 });
+	try { fs.chmodSync(file, 0o600); } catch { /* the write mode is already 600 */ }
+	return ident;
+}
+
+async function ownerCall(method, p, body) {
+	const base = baseUrl(), tok = C.get("A2A_OWNER_TOKEN");
+	if (!base || !tok) return null;
+	return httpJson(base + p, { method, body, headers: { authorization: `Bearer ${tok}` } });
+}
+
+const ownerError = (r) => (r.data && typeof r.data === "object" && typeof r.data.error === "string" ? r.data.error : `HTTP ${r.status}`);
+
+/** Public key to name in a pairing request. Prefers the key this inbox already serves on its card. */
+export async function publicIdentityForConnect() {
+	let local = null;
+	const ensureLocal = () => local || (local = loadOrCreateLocalIdentity());
+	const base = baseUrl(), tok = C.get("A2A_OWNER_TOKEN");
+	if (!base || !tok) return ensureLocal().publicKey;
+	let got;
+	try { got = await ownerCall("GET", "/owner/identity"); }
+	catch { return ensureLocal().publicKey; }
+	if (!got) return ensureLocal().publicKey;
+	if (got.status === 200 && got.data && typeof got.data.publicKey === "string" && got.data.publicKey) {
+		const file = IDENTITY_FILE();
+		if (fs.existsSync(file)) {
+			try {
+				const cur = JSON.parse(fs.readFileSync(file, "utf8"));
+				if (cur.publicKey && cur.publicKey !== got.data.publicKey)
+					console.error("note: the local pairing identity differs from this A2A endpoint. connect uses the endpoint's identity, which is the one its card can prove.");
+			} catch { /* unreadable local file: the endpoint key still wins */ }
+		}
+		return got.data.publicKey;
+	}
+	if (got.status === 200 && got.data && got.data.publicKey == null) {
+		const ident = ensureLocal();
+		try {
+			const put = await ownerCall("PUT", "/owner/identity", { publicKey: ident.publicKey, privateKey: ident.privateKey });
+			if (put && put.status === 200 && put.data && put.data.publicKey) return put.data.publicKey;
+		} catch { /* the request still carries the local public key */ }
+		return ident.publicKey;
+	}
+	return ensureLocal().publicKey;
+}
+
+async function requireIdentityOnWorker() {
+	const base = baseUrl(), tok = C.get("A2A_OWNER_TOKEN");
+	if (!base || !tok) die(`A2A_BASE_URL / A2A_OWNER_TOKEN missing (run \`${CLI} init\` or edit ${C.CONFIG_FILE})`);
+	let got;
+	try { got = await ownerCall("GET", "/owner/identity"); }
+	catch (e) { die(`could not reach this A2A endpoint: ${e?.message || e}`); }
+	if (!got || got.status === 404) die(`this A2A endpoint's Worker predates address announcements: run \`${CLI} deploy\` first`);
+	if (got.status !== 200) die(`could not read the pairing identity: ${ownerError(got)}`);
+	if (got.data && got.data.publicKey) return got.data.publicKey;
+	const ident = loadOrCreateLocalIdentity();
+	const put = await ownerCall("PUT", "/owner/identity", { publicKey: ident.publicKey, privateKey: ident.privateKey });
+	if (!put || put.status !== 200) die(`could not install the pairing identity: ${put ? ownerError(put) : "no answer"}`);
+	return put.data.publicKey;
+}
+
+export async function announce(o = {}) {
+	if (!!o.to === !!o.all) die(`usage: ${CLI} peer announce (--to <alias> | --all) [--reissue] [--json]`);
+	if (o.reissue && (o.all || !o.to)) die("--reissue needs --to <alias>");
+	if (o.to !== undefined && !/^[A-Za-z0-9_-]{1,64}$/.test(o.to)) die("--to must be a peer alias");
+	await requireIdentityOnWorker();
+	const r = await ownerCall("POST", "/owner/peers/announce", o.all ? { all: true } : { to: o.to, ...(o.reissue ? { reissue: true } : {}) });
+	if (!r || r.status !== 200) die(`could not announce this address: ${r ? ownerError(r) : "no answer"}`);
+	const results = Array.isArray(r.data.results) ? r.data.results : [];
+	if (results.length === 1 && results[0].alias === "*") die(results[0].detail || "could not announce this address");
+	if (o.json) return console.log(JSON.stringify({ results }));
+	if (!results.length) return console.log("No synced peer to announce to. Run peers sync after connect.");
+	for (const row of results) {
+		const host = row.host ? ` (${row.host})` : "";
+		console.log(`${row.alias}${host}: ${row.status}${row.detail ? ` — ${row.detail}` : ""}`);
+	}
+}
+
+export async function forward(o = {}) {
+	const base = baseUrl(), tok = C.get("A2A_OWNER_TOKEN");
+	if (!base || !tok) die(`A2A_BASE_URL / A2A_OWNER_TOKEN missing (run \`${CLI} init\` or edit ${C.CONFIG_FILE})`);
+	if (o.off) {
+		const r = await ownerCall("DELETE", "/owner/address-forward");
+		if (!r || r.status === 404) die(`this A2A endpoint's Worker predates address forwarding: run \`${CLI} deploy\` first`);
+		if (r.status !== 200) die(`could not clear the grace forward: ${ownerError(r)}`);
+		return console.log("grace forward cleared");
+	}
+	if (!o.to) die(`usage: ${CLI} peer forward --to <card-url> [--hours N] | ${CLI} peer forward --off`);
+	let hours;
+	if (o.hours !== undefined) {
+		if (!/^\d{1,4}$/.test(String(o.hours))) die("--hours must be a whole number from 1 to 720 (default 168)");
+		hours = Number(o.hours);
+	}
+	const r = await ownerCall("PUT", "/owner/address-forward", { cardUrl: o.to, ...(hours ? { hours } : {}) });
+	if (!r || r.status === 404) die(`this A2A endpoint's Worker predates address forwarding: run \`${CLI} deploy\` first`);
+	if (r.status !== 200) die(`could not set the grace forward: ${ownerError(r)}`);
+	const until = r.data.until || "";
+	if (o.json) return console.log(JSON.stringify({ cardUrl: r.data.cardUrl, until }));
+	console.log(`grace forward to ${r.data.cardUrl}${until ? ` until ${until}` : ""}`);
+}

package/lib/commands.mjs

@@ -152,7 +152,8 @@ export async function contexts() {
 export async function token(action, label, o) {
 	if (action === "list") {
 		for (const r of await owner("GET", "/owner/peers")) {
-			const via = r.source === "pairing" ? `\tvia pairing: code ${r.user_code || "?"}${r.client_name ? `, ${JSON.stringify(r.client_name)}` : ""}` : "";
+			const via = r.source === "pairing" ? `\tvia pairing: code ${r.user_code || "?"}${r.client_name ? `, ${JSON.stringify(r.client_name)}` : ""}`
+				: r.source === "reverse" ? "\tvia reverse pairing (return token; revoke ends the return path)" : "";
 			console.log(`${r.label}\tcreated=${r.created_at}\t${r.revoked_at ? "REVOKED " + r.revoked_at : "active"}${via}`);
 		}
 		// MCP connectors (Worker 0.5+): their own tokens, listed and revoked by label like peer tokens

package/lib/main.mjs

@@ -7,6 +7,7 @@ import * as dep from "./deploy.mjs";
 import * as tun from "./tunnel.mjs";
 import * as st from "./status.mjs";
 import * as pair from "./pair.mjs";
+import * as address from "./address.mjs";
 import * as account from "./account.mjs";
 import * as upd from "./update.mjs";
 import * as fb from "./feedback.mjs";
@@ -181,6 +182,7 @@ Inbox (owner side)
   working <taskId>                         mark task working
   reply <taskId> (--text T | --stdin) [--state completed|input-required|rejected|failed|working]
         [--artifact] [--artifact-name N] [--force]
+                                           delivery waits at most 18 s; identical retries read the first result
   history <contextId> [--from PEER] [-n 50] [--json]
                                            conversation log. --from is one peer (the wake hint includes it)
   contexts                                 recent conversations
@@ -235,6 +237,14 @@ Outbound (agents you call)
   peers sync [alias...] | peers unsync <alias>
                           upload peers (URL + token, encrypted on the Worker) so the MCP connector can send to
                           them; default: all peers. Re-run after connect, token changes or an owner-token rotation
+  peer announce (--to <alias> | --all) [--reissue] [--json]
+                          tell paired peers this inbox's current card URL. They switch only after the card
+                          proves the same pairing identity. A peer that does not support this keeps the
+                          current pairing. A revoked return token stays revoked unless --to and --reissue.
+                          The return token is not printed
+  peer forward --to <card-url> [--hours N] | peer forward --off
+                          on the old inbox, forward direct replies and answer with a moved pointer for N hours
+                          (default 168, max 720)
                           a token variable set in the environment overrides config.env; when a peer token
                           differs between the two, connect/send/poll/peers/status warn (values never shown)
   send --to <alias|url> [--text T | stdin] [--context C] [--task T] [--push] [--proto 0.3|1.0]
@@ -324,6 +334,7 @@ const SPEC = {
 	history: { from: S, n: { type: "string", short: "n", default: "50" }, json: B },
 	token: { rotate: B },
 	peers: { "token-env": S, "token-stdin": B },
+	peer: { to: S, all: B, reissue: B, hours: S, off: B, json: B },
 	send: { to: S, text: S, context: S, task: S, push: B, proto: S },
 	poll: { to: S, proto: S },
 	status: { json: B },
@@ -432,6 +443,12 @@ export async function main(argv) {
 		case "export": return cmd.exportInbox(o);
 		case "token": return cmd.token(need(p[0], "token issue|list|revoke|rotate [label]"), p[1], o);
 		case "peers": return cmd.peers(p[0] || "list", p.slice(1), o);
+		case "peer": {
+			const sub = need(p[0], "peer announce (--to <alias> | --all) | peer forward --to <card-url> [--hours N] | peer forward --off");
+			if (sub === "announce") return address.announce(o);
+			if (sub === "forward") return address.forward(o);
+			throw new CliError(`unknown peer action ${sub} (announce|forward)`);
+		}
 		case "signup":
 		case "login": {
 			const result = await account.deviceLogin({ controlUrl: o["control-url"] || C.get("CONTROL_URL"), intent: name });

package/lib/pair.mjs

@@ -7,6 +7,7 @@ import path from "node:path";
 import * as C from "./config.mjs";
 import { CLI, describeHttp, die, fetchCard, httpJson, isPrivateHost, pickEndpoint } from "./a2a.mjs";
 import { baseUrl, peerToken, warnPeerTokenEnv } from "./commands.mjs";
+import { publicIdentityForConnect } from "./address.mjs";
 
 export const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
 export const PBKDF2_ITERATIONS = 100000; // default (the Workers runtime's maximum); the Worker advertises its own setting
@@ -168,6 +169,8 @@ export async function list(o) {
 	for (const p of d.pending) {
 		console.log(`--- ${p.userCode}  ${JSON.stringify(p.clientName || p.clientId || "(no name)")} (claimed, untrusted)  expires ${p.expiresAt}${p.replacesLabel ? `  replaces the active token "${p.replacesLabel}"` : ""}`);
 		console.log(`    card: ${p.agentCardUrl || "-"}  from: ${[p.ip || "?", p.country].filter(Boolean).join(", ")}`);
+		if (p.identityFingerprint) console.log(`    identity: ${p.identityFingerprint}`);
+		if (!p.agentCardUrl) console.log("    no callback address yet: replies stay on the task until this agent announces one");
 		console.log(`    link: ${p.verificationUriComplete}`);
 	}
 	console.log(`Ask your human about each request; never approve on your own.`);
@@ -356,6 +359,8 @@ A different agent at the same URL? Pass another --alias.`);
 		// deployment exists) wins. With no override, read this deployment's card, including an http one.
 		const nameUrl = sentCard || (!o["card-url"] && /^https?:\/\//.test(own || "") ? `${own.replace(/\/$/, "")}/.well-known/agent-card.json` : "");
 		const params = { client_name: pairingClientName({ explicit: o.name, cardName: await readCardName(nameUrl), agentName: C.get("A2A_AGENT_NAME"), workerName: C.get("A2A_WORKER_NAME"), ownUrl: own }), client_id: C.get("A2A_WORKER_NAME") || alias };
+		const identity = await publicIdentityForConnect();
+		if (identity) params.agent_identity = identity;
 		if (sentCard) params.agent_card_url = sentCard;
 		// replacing: present the old token, so a peer that supports it swaps the token under the same label (no orphan)
 		const r = await postForm(ep.device, params, replace && oldToken ? oldToken : null);

package/lib/status.mjs

@@ -126,6 +126,11 @@ export function nextStep(s) {
 	if (s.workerVersion && s.latestVersion && newer(s.latestVersion, s.workerVersion) && !newer(s.workerVersion, version))
 		n.also.push(`a2a-exposed ${s.latestVersion} is available: run npx -y a2a-exposed@latest deploy`);
 	const sh = (s.peerTokenShadowed || []).map((k) => `${k} is set in the environment and overrides the different peer token saved in ${s.configFile} (e.g. a stale value from before \`connect\` stored a new one): send/poll use the environment value. Unset ${k} where it is set to use the saved token`);
+	const addr = s.addresses;
+	if (addr && Array.isArray(addr.announcePending) && addr.announcePending.length)
+		n.also.push(`an address announcement is still pending: run \`${CLI} peer announce --all\``);
+	if (addr && Array.isArray(addr.inboundNoAddress) && addr.inboundNoAddress.length)
+		n.also.push("paired peers with no callback keep replies on the task until they announce an address");
 	return sh.length ? { ...n, also: [...n.also, ...sh] } : n;
 }
 
@@ -238,7 +243,7 @@ export async function collect() {
 		card: { ok: false, error: "not checked" }, ownerApi: { ok: false, error: "not checked" }, wake: null, tunnel: null, zones: null, pairing: null,
 		upstream: C.get("A2A_UPSTREAM_URL") || null, facade: null, upstreamVerify: null, upstreamVerifyError: "", facadePeerAuth: null,
 		upstreamNoToken: C.get("A2A_UPSTREAM_NO_TOKEN") === "1", localUpstreamToken: fingerprint(process.env.UPSTREAM_TOKEN),
-		peerTokenShadowed: shadowedPeerTokens(),
+		peerTokenShadowed: shadowedPeerTokens(), addresses: null,
 		mcp: "unknown", health: null, workerVersion: null, cliVersion: D.VERSION, latestVersion: readCache(cacheFile())?.latest || null,
 	};
 	const envBase = (process.env.A2A_BASE_URL || "").replace(/\/$/, "");
@@ -263,6 +268,10 @@ export async function collect() {
 						...(typeof pr.oidcIssuer === "string" && pr.oidcIssuer ? { oidcIssuer: pr.oidcIssuer } : {}),
 						...(typeof pr.manageUrl === "string" && pr.manageUrl ? { manageUrl: pr.manageUrl } : {}) };
 			} catch { /* older Worker (no pairing yet): leave unknown */ }
+			try {
+				const ad = await ownerTry("GET", "/owner/address");
+				if (ad.status === 200 && ad.data && typeof ad.data === "object") s.addresses = ad.data;
+			} catch { /* older Worker: no address lifecycle */ }
 			if (s.upstream) {
 				try { s.facade = await owner("GET", "/owner/facade"); }
 				catch (e) { s.facade = { mode: "unknown", error: e.message }; }
@@ -378,6 +387,16 @@ export async function status(o) {
 			rows.push(["tunnel", !t ? "none" : `${t.wakeUrl} -> ${t.origin || "?"}; ${!t.complete ? "INCOMPLETE" : t.tokenFileOk ? "set up" : "set up, but the connector token file is MISSING"}` +
 				(t.connections != null ? `; ${tunnelStateLabel(t.state)}, ${t.connections} connector connection(s)` : t.error ? `; state unknown (${t.error})` : "")]);
 			if (s.zones) rows.push(["zones", s.zones.length ? s.zones.join(", ") : "none on this account"]);
+			const addr = s.addresses;
+			if (addr) {
+				const bits = [];
+				if (Array.isArray(addr.inboundNoAddress) && addr.inboundNoAddress.length)
+					bits.push(`${addr.inboundNoAddress.length} paired peer(s) with no callback (${addr.inboundNoAddress.map((x) => x.label).join(", ")})`);
+				if (Array.isArray(addr.announcePending) && addr.announcePending.length)
+					bits.push(`announce still pending for ${addr.announcePending.map((x) => x.alias).join(", ")}`);
+				if (addr.forward && addr.forward.active) bits.push(`grace forward until ${addr.forward.until}`);
+				if (bits.length) rows.push(["addresses", bits.join("; ")]);
+			}
 			const pg = s.pairing;
 			if (pg) rows.push(["pairing", pg.mode === "off" ? "off (token issue only)"
 				: `${pg.mode} approval; approval password ${pg.passwordSet ? `set${pg.passwordSetAt ? ` ${pg.passwordSetAt}` : ""}${pg.passwordSetVia ? ` (via ${pg.passwordSetVia})` : ""}` : `NOT SET${pg.setupLinkExpiresAt ? ` (a setup link is open until ${pg.setupLinkExpiresAt})` : ""}`}${pg.oidcIssuer ? `; OpenID Connect (${pg.oidcIssuer})` : ""}${pg.manageUrl ? `; dashboard ${pg.manageUrl}` : ""}${pg.pending ? `; ${pg.pending} pending request(s): ${CLI} pair list` : ""}`]);

package/package.json

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

package/worker/migrations/0014_peer_address.sql

@@ -0,0 +1,10 @@
+-- Pairing identity and the last verified callback address. Existing rows stay valid: every new column is nullable,
+-- so a peer paired before this migration keeps its token and has no callback until it announces one.
+ALTER TABLE peers ADD COLUMN identity_key TEXT;
+ALTER TABLE peers ADD COLUMN card_url TEXT;
+ALTER TABLE peers ADD COLUMN previous_card_url TEXT;
+ALTER TABLE peers ADD COLUMN previous_until_ms INTEGER;
+-- Sealed copy of a return token this inbox minted (source = 'reverse'). Null for every other peer.
+-- The owner API never selects this column. Export omits it.
+ALTER TABLE peers ADD COLUMN token_enc TEXT;
+ALTER TABLE device_requests ADD COLUMN identity_key TEXT;

package/worker/migrations/0015_outbound_source.sql

@@ -0,0 +1,3 @@
+-- Who created an outbound peer. NULL is an owner upload (`peers sync`). `announce` is a row this
+-- inbox created from a verified PeerAddressUpdate. An announcement must not repoint any other row.
+ALTER TABLE outbound_peers ADD COLUMN source TEXT;

package/worker/src/address.ts

@@ -0,0 +1,220 @@
+// Pairing identity and address proofs. Web Crypto only, so this runs in Workers and in Node's test runner.
+// The private key never appears in a return value of the HTTP handlers. Callers seal it before storage.
+
+export const IDENTITY_URI = "https://a2a.exposed/ext/peer-identity/v1";
+export const MOVED_URI = "https://a2a.exposed/ext/moved/v1";
+export const MOVED_CODE = -32011;
+export const DEFAULT_GRACE_HOURS = 168;
+export const MAX_GRACE_HOURS = 720;
+export const IDENTITY_SETTING = "peer_identity";
+export const FORWARD_SETTING = "address_forward";
+export const ANNOUNCE_SETTING = "announce_status";
+/** Additional data for the sealed identity blob. Not a peer label. */
+export const IDENTITY_AAD = "peer-identity";
+
+const IDENTITY_TEXT = "a2a-exposed-peer-identity-v1";
+const UPDATE_TEXT = "a2a-exposed-address-update-v1";
+
+export function b64urlEncode(b: Uint8Array): string {
+	let s = "";
+	for (const byte of b) s += String.fromCharCode(byte);
+	return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+export function b64urlDecode(s: string): Uint8Array | null {
+	if (typeof s !== "string" || !/^[A-Za-z0-9_-]{1,512}$/.test(s)) return null;
+	try {
+		const pad = s.length % 4 === 0 ? "" : "=".repeat(4 - (s.length % 4));
+		const raw = atob(s.replace(/-/g, "+").replace(/_/g, "/") + pad);
+		const out = new Uint8Array(raw.length);
+		for (let i = 0; i < raw.length; i++) out[i] = raw.charCodeAt(i);
+		return out;
+	} catch {
+		return null;
+	}
+}
+
+/** Canonical base64url of a raw 32-byte Ed25519 public key, or "". */
+export function cleanPublicKey(v: unknown): string {
+	if (typeof v !== "string") return "";
+	const raw = b64urlDecode(v.trim());
+	return raw && raw.length === 32 ? b64urlEncode(raw) : "";
+}
+
+/** A peer token the caller grants this inbox, so this inbox can call the new address back. Anything else is refused. */
+export function cleanReverseToken(v: unknown): string {
+	return typeof v === "string" && /^(?:a2aow_|s2a_)[A-Za-z0-9_-]{43}$/.test(v) ? v : "";
+}
+
+/** https agent-card URL, no query, no hash, no credentials. */
+export function canonicalCardUrl(v: unknown): string {
+	if (typeof v !== "string" || !v || v.length > 300) return "";
+	try {
+		const u = new URL(v);
+		if (u.protocol !== "https:" || u.username || u.password || u.search || u.hash) return "";
+		if (u.pathname !== "/.well-known/agent-card.json") return "";
+		return u.href;
+	} catch {
+		return "";
+	}
+}
+
+/** Card URL for this deployment. Empty unless the public URL is https. */
+export function cardUrlFor(publicUrl: string): string {
+	try {
+		const u = new URL(publicUrl);
+		if (u.protocol !== "https:") return "";
+		return new URL("/.well-known/agent-card.json", u.origin).href;
+	} catch {
+		return "";
+	}
+}
+
+export function originOf(url: string): string {
+	try { return new URL(url).origin; } catch { return ""; }
+}
+
+export function hostOf(url: string): string {
+	try { return new URL(url).host; } catch { return ""; }
+}
+
+/** Grace length in hours. `undefined` is the default. Anything else outside 1–720 is refused (`null`). */
+export function graceHours(v: unknown): number | null {
+	if (v === undefined || v === null || v === "") return DEFAULT_GRACE_HOURS;
+	const n = typeof v === "number" ? v : typeof v === "string" && /^\d{1,4}$/.test(v) ? Number(v) : NaN;
+	if (!Number.isInteger(n) || n < 1 || n > MAX_GRACE_HOURS) return null;
+	return n;
+}
+
+export function identityMessage(cardUrl: string, publicKey: string): Uint8Array {
+	return new TextEncoder().encode(`${IDENTITY_TEXT}\n${cardUrl}\n${publicKey}`);
+}
+
+export function updateMessage(cardUrl: string, publicKey: string, reverseHash: string): Uint8Array {
+	return new TextEncoder().encode(`${UPDATE_TEXT}\n${cardUrl}\n${publicKey}\n${reverseHash || "-"}`);
+}
+
+const ed25519 = { name: "Ed25519" };
+
+export async function generateIdentity(): Promise<{ publicKey: string; privateKey: string }> {
+	const kp = await crypto.subtle.generateKey(ed25519 as any, true, ["sign", "verify"]) as CryptoKeyPair;
+	const pub = new Uint8Array(await (crypto.subtle.exportKey as any)("raw", kp.publicKey));
+	const priv = new Uint8Array(await (crypto.subtle.exportKey as any)("pkcs8", kp.privateKey));
+	return { publicKey: b64urlEncode(pub), privateKey: b64urlEncode(priv) };
+}
+
+async function importPrivate(pkcs8: string): Promise<CryptoKey | null> {
+	const raw = b64urlDecode(pkcs8);
+	if (!raw) return null;
+	try {
+		return await crypto.subtle.importKey("pkcs8", raw, ed25519 as any, false, ["sign"]);
+	} catch {
+		return null;
+	}
+}
+
+async function importPublic(publicKey: string): Promise<CryptoKey | null> {
+	const raw = b64urlDecode(publicKey);
+	if (!raw || raw.length !== 32) return null;
+	try {
+		return await crypto.subtle.importKey("raw", raw, ed25519 as any, false, ["verify"]);
+	} catch {
+		return null;
+	}
+}
+
+export async function signBytes(privateKey: string, message: Uint8Array): Promise<string | null> {
+	const key = await importPrivate(privateKey);
+	if (!key) return null;
+	try {
+		return b64urlEncode(new Uint8Array(await crypto.subtle.sign(ed25519 as any, key, message as BufferSource)));
+	} catch {
+		return null;
+	}
+}
+
+export async function verifyBytes(publicKey: string, message: Uint8Array, signature: string): Promise<boolean> {
+	const key = await importPublic(publicKey);
+	const sig = b64urlDecode(signature);
+	if (!key || !sig) return false;
+	try {
+		return await crypto.subtle.verify(ed25519 as any, key, sig as BufferSource, message as BufferSource);
+	} catch {
+		return false;
+	}
+}
+
+/** True when this private key produces signatures this public key accepts. */
+export async function identityMatches(privateKey: string, publicKey: string): Promise<boolean> {
+	const clean = cleanPublicKey(publicKey);
+	if (!clean) return false;
+	const sig = await signBytes(privateKey, new TextEncoder().encode("a2a-exposed-identity-check-v1"));
+	return !!sig && await verifyBytes(clean, new TextEncoder().encode("a2a-exposed-identity-check-v1"), sig);
+}
+
+export function identityExtension(publicKey: string, cardUrl: string, signature: string): JsonExt {
+	return {
+		uri: IDENTITY_URI,
+		description: "Proves this card URL is served by this pairing identity",
+		params: { publicKey, cardUrl, signature },
+	};
+}
+
+export function movedExtension(cardUrl: string, until: string): JsonExt {
+	return {
+		uri: MOVED_URI,
+		description: "This inbox answers with a moved pointer until the grace time, and forwards a direct reply when the new inbox accepts it",
+		params: { cardUrl, until },
+	};
+}
+
+type JsonExt = { uri: string; description: string; params: Record<string, string> };
+
+export function extensionParams(card: unknown, uri: string): Record<string, unknown> | null {
+	const caps = card && typeof card === "object" ? (card as { capabilities?: { extensions?: unknown } }).capabilities : null;
+	const list = caps?.extensions;
+	if (!Array.isArray(list)) return null;
+	for (const item of list) {
+		if (!item || typeof item !== "object") continue;
+		const ext = item as { uri?: unknown; params?: unknown };
+		if (ext.uri === uri && ext.params && typeof ext.params === "object" && !Array.isArray(ext.params))
+			return ext.params as Record<string, unknown>;
+	}
+	return null;
+}
+
+export function movedFromCard(card: unknown, now = Date.now()): { cardUrl: string; until: string } | null {
+	const params = extensionParams(card, MOVED_URI);
+	if (!params) return null;
+	const cardUrl = canonicalCardUrl(params.cardUrl);
+	const until = typeof params.until === "string" ? params.until : "";
+	const untilMs = Date.parse(until);
+	if (!cardUrl || !Number.isFinite(untilMs) || untilMs <= now) return null;
+	return { cardUrl, until };
+}
+
+/** The card's identity proof, when the public key and signature match this card URL. */
+export async function cardProves(card: unknown, publicKey: string, cardUrl: string): Promise<boolean> {
+	const want = cleanPublicKey(publicKey);
+	const url = canonicalCardUrl(cardUrl);
+	if (!want || !url) return false;
+	const params = extensionParams(card, IDENTITY_URI);
+	if (!params) return false;
+	if (cleanPublicKey(params.publicKey) !== want) return false;
+	if (canonicalCardUrl(params.cardUrl) !== url) return false;
+	if (typeof params.signature !== "string") return false;
+	return verifyBytes(want, identityMessage(url, want), params.signature);
+}
+
+export type AnnounceStatus = "updated" | "unsupported" | "rejected" | "failed";
+
+/** What an address announcement got back. Method-not-found keeps the current pairing. */
+export function announceOutcome(status: number, body: unknown): { status: AnnounceStatus; detail: string } {
+	const obj = body && typeof body === "object" ? body as { result?: { ok?: unknown }; error?: { code?: unknown; message?: unknown } } : null;
+	if (status === 200 && obj?.result?.ok === true) return { status: "updated", detail: "Peer stored the address." };
+	const code = obj?.error?.code;
+	if (code === -32601) return { status: "unsupported", detail: "This peer does not accept address announcements. The current pairing is unchanged." };
+	if (status === 401 || status === 403 || code === -32000) return { status: "rejected", detail: "The pairing token was rejected." };
+	const message = typeof obj?.error?.message === "string" ? obj.error.message.slice(0, 200) : "";
+	return { status: "failed", detail: message || `HTTP ${status}` };
+}

package/worker/src/deadline.ts

@@ -0,0 +1,22 @@
+/** Stop waiting even when an internal binding ignores cancellation. Callers pass
+ * the signal into every request and check it before starting another side effect. */
+export async function withDeadline<T>(ms: number, run: (signal: AbortSignal) => Promise<T>, parent?: AbortSignal): Promise<T> {
+	const controller = new AbortController();
+	const cancel = () => controller.abort(parent?.reason);
+	if (parent?.aborted) cancel();
+	else parent?.addEventListener("abort", cancel, { once: true });
+	const timer = setTimeout(() => controller.abort(new Error("Reply delivery timed out; its outcome may be uncertain")), ms);
+	let stop!: () => void;
+	const aborted = new Promise<never>((_resolve, reject) => {
+		stop = () => reject(controller.signal.reason);
+		controller.signal.addEventListener("abort", stop, { once: true });
+	});
+	try {
+		controller.signal.throwIfAborted();
+		return await Promise.race([run(controller.signal), aborted]);
+	} finally {
+		clearTimeout(timer);
+		parent?.removeEventListener("abort", cancel);
+		controller.signal.removeEventListener("abort", stop);
+	}
+}

package/worker/src/export.ts

@@ -100,6 +100,7 @@ const OMIT_COLUMNS: Record<string, readonly string[]> = {
 	outbound: ["push_token_hash"],
 	mcp_grants: ["access_hash", "refresh_hash"],
 	outbound_peers: ["token_enc"],
+	peers: ["token_enc"],
 	device_requests: ["replaces_hash", "ip", "country"],
 };
 
@@ -137,7 +138,7 @@ export function redactExport(file: ExportFile): ExportFile {
 		const omit = new Set(OMIT_COLUMNS[name] ?? []);
 		const rows: Record<string, unknown>[] = [];
 		for (const [index, row] of (file.tables[name] ?? []).entries()) {
-			if (name === "settings" && (row.key === "approval_password" || row.key === "password_setup")) continue;
+			if (name === "settings" && (row.key === "approval_password" || row.key === "password_setup" || row.key === "peer_identity")) continue;
 			const out: Record<string, unknown> = {};
 			for (const [key, value] of Object.entries(row)) {
 				if (omit.has(key) || key.toLowerCase() === "replaces_hash") continue;