a2a-exposed 0.5.0 → 0.6.0

package/package.json

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

package/worker/cloudflare.config.ts

@@ -1,8 +1,9 @@
 // a2a-exposed Worker configuration. Everything deployment-specific comes from environment
-// variables at deploy time (set by `npx a2a-exposed init|deploy`, or export them yourself;
+// variables at deploy time (set by `npx -y a2a-exposed@latest init|deploy`, or export them yourself;
 // see deploy.env.example). Nothing account- or owner-specific is committed here.
-import { bindings, defineConfig, triggers } from "cf/config";
-import * as entrypoint from "./src/index.ts" with { type: "cf-worker" };
+import { bindings, defineConfig, exports, triggers } from "cf/config";
+import * as selfHost from "./src/index.ts" with { type: "cf-worker" };
+import * as hostedEntry from "./src/hosted.ts" with { type: "cf-worker" };
 
 const e: Record<string, string | undefined> = (globalThis as any).process?.env ?? {};
 const v = (k: string) => (e[k] ?? "").trim();
@@ -32,7 +33,7 @@ const plain: Record<string, string> = {
 	WAKE_KEY_HEADER: v("WAKE_KEY_HEADER"), // generic preset (default "authorization")
 	WAKE_KEY_PREFIX: e.WAKE_KEY_PREFIX ?? "", // generic preset; unset = "Bearer "
 	WAKE_BODY_TEMPLATE: v("WAKE_BODY_TEMPLATE"), // generic preset JSON template
-	WAKE_CLI_COMMAND: v("WAKE_CLI_COMMAND"), // how the woken agent runs the CLI (default "npx a2a-exposed")
+	WAKE_CLI_COMMAND: v("WAKE_CLI_COMMAND"), // how the woken agent runs the CLI (default "npx -y a2a-exposed@latest")
 	WAKE_DEBOUNCE_SECONDS: v("WAKE_DEBOUNCE_SECONDS"),
 	WAKE_MAX_PER_HOUR: v("WAKE_MAX_PER_HOUR"),
 	MAX_BODY: v("A2A_MAX_BODY"),
@@ -45,24 +46,65 @@ const plain: Record<string, string> = {
 	// Access (never a Tailnet / LAN URL: the Worker can't reach those, and they never appear in the public card)
 	UPSTREAM_URL: v("A2A_UPSTREAM_URL"),
 	UPSTREAM_CARD_URL: v("A2A_UPSTREAM_CARD_URL"), // default <upstream origin>/.well-known/agent-card.json
+	// Hosted multi-tenant gates. All empty by default, and empty is omitted, so a self-host deploy is unchanged.
+	// TENANCY=host switches the entrypoint to src/hosted.ts and adds TENANT_DO + TENANT_DIRECTORY below.
+	// QUOTAS, USAGE_SINK, WAKE_TARGET_POLICY, SIGNUP_URL and BRANDING are parsed and reserved.
+	// APPROVAL_OIDC_* turn on OpenID Connect approval when issuer, client id, secret and allowlist are all set.
+	TENANCY: v("TENANCY"),
+	TENANT_DOMAIN: v("TENANT_DOMAIN"),
+	DATA_REGION: v("DATA_REGION"), // eu | fedramp; unset = Cloudflare's default placement
+	QUOTAS: v("QUOTAS"),
+	USAGE_SINK: v("USAGE_SINK"),
+	WAKE_TARGET_POLICY: v("WAKE_TARGET_POLICY"),
+	SIGNUP_URL: v("SIGNUP_URL"),
+	BRANDING: v("BRANDING"),
+	APPROVAL_OIDC_ISSUER: v("APPROVAL_OIDC_ISSUER"),
+	APPROVAL_OIDC_CLIENT_ID: v("APPROVAL_OIDC_CLIENT_ID"),
+	APPROVAL_OIDC_ALLOWED_SUBJECTS: v("APPROVAL_OIDC_ALLOWED_SUBJECTS"),
+	APPROVAL_METHODS: v("APPROVAL_METHODS"),
 };
+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.
+const backups = v("A2A_BACKUP_BUCKET") === "1";
 const envBindings: Record<string, any> = {
 	DB: bindings.d1(v("A2A_D1_ID") ? { name: v("A2A_D1_NAME") || name, id: v("A2A_D1_ID") } : { name: v("A2A_D1_NAME") || name }),
 };
+// Per-tenant SQLite and the name directory exist only on a hosted deploy. A self-host build does not export the
+// Durable Object class and does not declare these bindings, so `cf deploy` stays the single-tenant Worker on D1.
+if (hosted) {
+	envBindings.TENANT_DO = bindings.durableObject({ worker: name, exportName: "TenantStore" });
+	envBindings.TENANT_DIRECTORY = bindings.kv();
+}
+if (backups) {
+	const region = v("DATA_REGION");
+	const bucketName = v("A2A_BACKUP_BUCKET_NAME");
+	envBindings.BACKUP_BUCKET = bindings.r2({
+		...(bucketName ? { name: bucketName } : {}),
+		...(region === "eu" || region === "fedramp" ? { jurisdiction: region } : {}),
+	});
+}
+const crons = [
+	...(v("A2A_ENABLE_CRON") === "1" ? [triggers.scheduled({ schedule: "* * * * *" })] : []),
+	...(backups ? [triggers.scheduled({ schedule: "0 3 * * *" })] : []),
+];
 for (const [k, val] of Object.entries(plain)) if (val !== "" || (k === "WAKE_KEY_PREFIX" && "WAKE_KEY_PREFIX" in e)) envBindings[k] = bindings.text(val);
 
 // Secrets are uploaded separately (never in this file): OWNER_TOKEN, WAKE_WEBHOOK_URL, WAKE_WEBHOOK_KEY, WAKE_HMAC_SECRET,
 // and in proxy mode UPSTREAM_TOKEN, UPSTREAM_ACCESS_CLIENT_ID, UPSTREAM_ACCESS_CLIENT_SECRET.
 // They are declared only in development mode (`cf dev`), so local dev reads them from .dev.vars while
 // production deploys never fail because an optional wake secret is unset.
-const SECRETS = ["OWNER_TOKEN", "WAKE_WEBHOOK_URL", "WAKE_WEBHOOK_KEY", "WAKE_HMAC_SECRET", "UPSTREAM_TOKEN", "UPSTREAM_ACCESS_CLIENT_ID", "UPSTREAM_ACCESS_CLIENT_SECRET"];
+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"] : [])];
 
 export default defineConfig((ctx) => ({
 	...(v("CLOUDFLARE_ACCOUNT_ID") ? { accountId: v("CLOUDFLARE_ACCOUNT_ID") } : {}),
 	worker: {
 		name,
 		compatibilityDate: "2026-10-06",
-		entrypoint,
+		entrypoint: hosted ? hostedEntry : selfHost,
+		...(hosted ? { exports: { TenantStore: exports.durableObject({ storage: "sqlite" }) } } : {}),
 		...(hostname ? { domains: [hostname] } : {}),
 		workersDev,
 		// Optional persisted Workers Logs (A2A_WORKERS_LOGS=1, `init|deploy --workers-logs`): the JSON event lines plus
@@ -71,6 +113,7 @@ export default defineConfig((ctx) => ({
 		env: ctx.mode === "development" ? { ...envBindings, ...Object.fromEntries(SECRETS.map((k) => [k, bindings.secret()])) } : envBindings,
 		// Optional cron flush of debounced wakes (the Worker also flushes opportunistically on every request).
 		// Requires a workers.dev subdomain on the account (always the case for workers.dev deployments).
-		...(v("A2A_ENABLE_CRON") === "1" ? { triggers: [triggers.scheduled({ schedule: "* * * * *" })] } : {}),
+		// A2A_BACKUP_BUCKET=1 adds a second trigger, 03:00 UTC, which writes SQL snapshots and does not flush wakes.
+		...(crons.length ? { triggers: crons } : {}),
 	},
 }));

package/worker/deploy.env.example

@@ -18,7 +18,7 @@ WAKE_PRESET=generic
 # WAKE_KEY_HEADER=authorization
 # WAKE_KEY_PREFIX=Bearer 
 # WAKE_BODY_TEMPLATE={"text":"{{summary}}"}
-# Command shown in wake hints (CLI: --cli-command; default "npx a2a-exposed"). Until the CLI is on npm:
+# Command shown in wake hints (CLI: --cli-command; default "npx -y a2a-exposed@latest"). For a source checkout:
 # WAKE_CLI_COMMAND=node /path/to/a2a-exposed/cli/bin/a2a-exposed.mjs
 # WAKE_DEBOUNCE_SECONDS=10
 # WAKE_MAX_PER_HOUR=0
@@ -31,3 +31,30 @@ WAKE_PRESET=generic
 # Cloudflare Access WAKE_ACCESS_CLIENT_ID / WAKE_ACCESS_CLIENT_SECRET; in proxy mode UPSTREAM_TOKEN,
 # UPSTREAM_ACCESS_CLIENT_ID / UPSTREAM_ACCESS_CLIENT_SECRET) go in a separate chmod-600
 # file passed with `cf deploy --secrets-file <file>`; never commit them.
+#
+# Optional multi-tenant gates. Leave them unset for a self-hosted inbox (`npx -y a2a-exposed@latest init`
+# never sets them). Unset means today's single-tenant Worker on D1, and the build does not export a Durable Object.
+# TENANCY=host switches the entry to the multi-tenant router and adds the TENANT_DO and TENANT_DIRECTORY bindings.
+# The other values are reserved (parsed, not enforced yet). Do not set TENANCY for a self-hosted inbox.
+# TENANCY=
+# TENANT_DOMAIN=example.com
+# DATA_REGION=eu
+# Written onto a directory entry the first time that entry has no region. After that the stored region places the tenant.
+# QUOTAS=on
+# USAGE_SINK=d1
+# WAKE_TARGET_POLICY=public-https
+# SIGNUP_URL=https://example.com
+# BRANDING=hosted
+# OpenID Connect approval (optional). All four of issuer, client id, allowlist and the client secret
+# must be set or the pages stay password-only. APPROVAL_METHODS=oidc hides the password once that
+# config is complete; APPROVAL_METHODS=password keeps the password even if an issuer is set.
+# APPROVAL_OIDC_ISSUER=https://example.com
+# APPROVAL_OIDC_CLIENT_ID=
+# APPROVAL_OIDC_ALLOWED_SUBJECTS=
+# APPROVAL_METHODS=password
+# Secrets (same secrets file, never here): APPROVAL_OIDC_CLIENT_SECRET, and for a hosted deploy TENANT_SECRETS_KEY.
+# Hosted approval uses the tenant's pushed approval object, not these Worker settings.
+# 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
+# With DATA_REGION=eu or fedramp the bucket is created in that jurisdiction. Objects are kept 30 days.

package/worker/migrations/0008_oidc_txns.sql

@@ -0,0 +1,12 @@
+-- Short-lived OpenID Connect sign-in (authorization code + PKCE). The callback deletes the row;
+-- expired rows are removed when a new one is stored and by the pairing cleanup.
+CREATE TABLE IF NOT EXISTS oidc_txns (
+	state TEXT PRIMARY KEY,
+	nonce TEXT NOT NULL,
+	verifier TEXT NOT NULL,
+	kind TEXT NOT NULL,
+	csrf TEXT NOT NULL,
+	user_code TEXT,
+	payload_json TEXT NOT NULL,
+	expires_ms INTEGER NOT NULL
+);

package/worker/package.json

@@ -7,13 +7,17 @@
 	"scripts": {
 		"build": "cf build",
 		"deploy": "cf deploy",
-		"test": "node --test test/*.test.ts",
+		"test": "node --import ./test/register-hooks.mjs --test test/*.test.ts",
 		"typecheck": "cf workers types && tsc"
 	},
-	"engines": { "node": ">=22.18" },
+	"engines": {
+		"node": ">=22.18"
+	},
 	"devDependencies": {
 		"@cloudflare/vite-plugin": "beta",
 		"cf": "^1.0.0-beta.13",
+		"esbuild": "^0.28.1",
+		"miniflare": "^5.20261006.0-alpha",
 		"typescript": "^7.0.2",
 		"vite": "^8.3.0"
 	}

package/worker/src/approval-oidc.ts

@@ -0,0 +1,247 @@
+// Optional OpenID Connect approval for /device and /oauth/authorize.
+// Active only when the issuer (https), client id, client secret and at least one allowed subject are all set,
+// and the method list includes oidc (or APPROVAL_METHODS was left unset). Password stays the default.
+// The client secret is read from TenantContext and is never logged or placed on the gate object.
+import * as A from "./a2a.ts";
+import type { ApprovalOidcGate, TenantContext } from "./tenancy.ts";
+
+export const TXN_TTL_MS = 10 * 60 * 1000;
+const ID_TOKEN_MAX = 8192;
+const SKEW_S = 60;
+const FETCH_MS = 5000;
+
+export type OidcKind = "device" | "mcp";
+
+export interface ApprovalPolicy {
+	oidc: boolean;
+	password: boolean;
+	/** Button label: configured label, otherwise the issuer host. */
+	label: string;
+}
+
+export function issuerHost(issuer: string): string {
+	try { return new URL(issuer).host; } catch { return ""; }
+}
+
+export function issuerBase(issuer: string): string {
+	return issuer.replace(/\/+$/, "");
+}
+
+/**
+ * What the approval pages offer.
+ * OIDC is on when it is fully configured and methods include oidc, or when methods were not specified.
+ * Password stays on unless methods were specified as oidc only AND the OIDC config is complete
+ * (an incomplete `APPROVAL_METHODS=oidc` must not lock the operator out).
+ * `APPROVAL_METHODS=password` keeps the password and does not turn OIDC on.
+ */
+export function approvalPolicy(gate: ApprovalOidcGate): ApprovalPolicy {
+	const configured = !!(gate.issuer && gate.clientId && gate.hasClientSecret && gate.allowedSubjects.length);
+	const oidc = configured && (gate.methods.includes("oidc") || !gate.methodsSpecified);
+	const oidcOnly = gate.methodsSpecified && gate.methods.includes("oidc") && !gate.methods.includes("password");
+	return { oidc, password: !(oidcOnly && configured), label: gate.label || issuerHost(gate.issuer) };
+}
+
+export type StartResult = { ok: true; location: string } | { ok: false; error: string; reason: string };
+export type FinishResult =
+	| { ok: true; userCode: string | null; payload: Record<string, unknown>; subject: string }
+	| { ok: false; error: string; reason: string; userCode: string | null };
+
+const FAIL = "Sign-in could not be verified. Nothing was approved.";
+const UNREACHABLE = "The identity provider could not be reached. Nothing was approved.";
+
+function b64url(bytes: Uint8Array): string {
+	return btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function b64urlDecode(s: string): Uint8Array {
+	if (!/^[A-Za-z0-9_-]+$/.test(s) || s.length > ID_TOKEN_MAX) throw new Error("b64");
+	const pad = "=".repeat((4 - (s.length % 4)) % 4);
+	const bin = atob(s.replace(/-/g, "+").replace(/_/g, "/") + pad);
+	const out = new Uint8Array(bin.length);
+	for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+	return out;
+}
+
+async function pkce(): Promise<{ verifier: string; challenge: string }> {
+	const verifier = b64url(crypto.getRandomValues(new Uint8Array(32)));
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+	return { verifier, challenge: b64url(new Uint8Array(digest)) };
+}
+
+function httpsEndpoint(v: unknown): string {
+	if (typeof v !== "string" || !v) throw new Error("endpoint");
+	const u = new URL(v);
+	if (u.protocol !== "https:" || u.username || u.password) throw new Error("endpoint");
+	return u.toString();
+}
+
+async function readJson(res: Response, max: number): Promise<any> {
+	const len = Number(res.headers.get("content-length") || 0);
+	if (len > max) throw new Error("large");
+	const text = await res.text();
+	if (text.length > max) throw new Error("large");
+	return JSON.parse(text);
+}
+
+async function getJson(url: string): Promise<any> {
+	const res = await fetch(url, { headers: { accept: "application/json" }, redirect: "error", signal: AbortSignal.timeout(FETCH_MS) });
+	if (!res.ok) throw new Error("http");
+	return readJson(res, 65536);
+}
+
+interface Discovery {
+	authorization_endpoint: string;
+	token_endpoint: string;
+	jwks_uri: string;
+}
+
+async function discover(issuer: string): Promise<Discovery> {
+	const doc = await getJson(`${issuerBase(issuer)}/.well-known/openid-configuration`);
+	if (issuerBase(String(doc?.issuer || "")) !== issuerBase(issuer)) throw new Error("issuer");
+	return {
+		authorization_endpoint: httpsEndpoint(doc.authorization_endpoint),
+		token_endpoint: httpsEndpoint(doc.token_endpoint),
+		jwks_uri: httpsEndpoint(doc.jwks_uri),
+	};
+}
+
+/** Begin a sign-in. `userCode` is stored with the state and is not put on the identity provider's URL. */
+export async function startOidc(ctx: TenantContext, o: {
+	kind: OidcKind; redirectUri: string; csrf: string; userCode: string | null; payload: Record<string, unknown>;
+}): Promise<StartResult> {
+	const gate = ctx.gates.approvalOidc;
+	if (!approvalPolicy(gate).oidc || !ctx.approvalClientSecret()) return { ok: false, error: "OpenID Connect approval is not configured.", reason: "config" };
+	let disc: Discovery;
+	try { disc = await discover(gate.issuer); }
+	catch { return { ok: false, error: UNREACHABLE, reason: "discovery" }; }
+	const { verifier, challenge } = await pkce();
+	const state = b64url(crypto.getRandomValues(new Uint8Array(32)));
+	const nonce = b64url(crypto.getRandomValues(new Uint8Array(32)));
+	const payload = JSON.stringify(o.payload);
+	if (payload.length > 16384) return { ok: false, error: "This approval could not be started.", reason: "payload" };
+	const now = Date.now();
+	await ctx.DB.prepare("DELETE FROM oidc_txns WHERE expires_ms < ?").bind(now).run();
+	await ctx.DB.prepare("INSERT INTO oidc_txns (state, nonce, verifier, kind, csrf, user_code, payload_json, expires_ms) VALUES (?, ?, ?, ?, ?, ?, ?, ?)")
+		.bind(state, nonce, verifier, o.kind, o.csrf, o.userCode, payload, now + TXN_TTL_MS).run();
+	const u = new URL(disc.authorization_endpoint);
+	u.searchParams.set("response_type", "code");
+	u.searchParams.set("client_id", gate.clientId);
+	u.searchParams.set("redirect_uri", o.redirectUri);
+	// `email` is required for an email allowlist: providers omit `email` and `email_verified` unless this scope is requested.
+	u.searchParams.set("scope", "openid email");
+	u.searchParams.set("state", state);
+	u.searchParams.set("nonce", nonce);
+	u.searchParams.set("code_challenge", challenge);
+	u.searchParams.set("code_challenge_method", "S256");
+	return { ok: true, location: u.toString() };
+}
+
+function onAllowlist(value: unknown, subjects: string[]): boolean {
+	if (typeof value !== "string") return false;
+	for (const want of subjects) if (A.timingSafeEqualStr(value, want)) return true;
+	return false;
+}
+
+/**
+ * OIDC ID Token validation: `aud` must contain this client. When `aud` has more than one value, `azp` is required
+ * and must be this client id. A present `azp` must match even when there is only one audience.
+ */
+function audienceOk(aud: unknown, azp: unknown, clientId: string): boolean {
+	const raw = typeof aud === "string" ? [aud] : Array.isArray(aud) ? aud : [];
+	if (!onAllowlist(clientId, raw.filter((a): a is string => typeof a === "string"))) return false;
+	const multi = raw.length > 1;
+	if (!multi && azp === undefined) return true;
+	return typeof azp === "string" && A.timingSafeEqualStr(azp, clientId);
+}
+
+/**
+ * Prefer `sub`. An `email` match is a separate path and is ignored unless `email_verified` is boolean true,
+ * so an unverified address cannot approve.
+ */
+function subjectAllowed(claims: { sub?: unknown; email?: unknown; email_verified?: unknown }, subjects: string[]): boolean {
+	if (onAllowlist(claims.sub, subjects)) return true;
+	if (claims.email_verified !== true) return false;
+	return onAllowlist(claims.email, subjects);
+}
+
+async function verifyIdToken(token: string, jwks: { keys?: any[] }, expect: { iss: string; aud: string; nonce: string; subjects: string[] }): Promise<{ subject: string } | { reason: string }> {
+	if (typeof token !== "string" || token.length < 20 || token.length > ID_TOKEN_MAX) return { reason: "token" };
+	const parts = token.split(".");
+	if (parts.length !== 3) return { reason: "token" };
+	let header: any;
+	try { header = JSON.parse(new TextDecoder().decode(b64urlDecode(parts[0]))); }
+	catch { return { reason: "token" }; }
+	// RS256 only. `none` and HMAC (which would use the client secret as a MAC key) are rejected before verification.
+	if (header.alg !== "RS256") return { reason: "alg" };
+	const keys: any[] = Array.isArray(jwks.keys) ? jwks.keys : [];
+	const jwk = header.kid ? keys.find((k) => k && k.kid === header.kid) : keys.length === 1 ? keys[0] : null;
+	if (!jwk || jwk.kty !== "RSA" || !jwk.n || !jwk.e || (jwk.alg && jwk.alg !== "RS256")) return { reason: "key" };
+	let key: CryptoKey;
+	try {
+		key = await crypto.subtle.importKey("jwk", { kty: "RSA", n: jwk.n, e: jwk.e, alg: "RS256", ext: true },
+			{ name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["verify"]);
+	} catch { return { reason: "key" }; }
+	let sig: Uint8Array;
+	try { sig = b64urlDecode(parts[2]); } catch { return { reason: "sig" }; }
+	const ok = await crypto.subtle.verify({ name: "RSASSA-PKCS1-v1_5" }, key, sig, new TextEncoder().encode(`${parts[0]}.${parts[1]}`));
+	if (!ok) return { reason: "sig" };
+	let claims: any;
+	try { claims = JSON.parse(new TextDecoder().decode(b64urlDecode(parts[1]))); }
+	catch { return { reason: "token" }; }
+	if (issuerBase(String(claims.iss || "")) !== issuerBase(expect.iss)) return { reason: "iss" };
+	if (!audienceOk(claims.aud, claims.azp, expect.aud)) return { reason: "aud" };
+	if (typeof claims.nonce !== "string" || !A.timingSafeEqualStr(claims.nonce, expect.nonce)) return { reason: "nonce" };
+	const nowS = Date.now() / 1000;
+	if (typeof claims.exp !== "number" || !Number.isFinite(claims.exp) || claims.exp + SKEW_S < nowS) return { reason: "exp" };
+	if (typeof claims.nbf === "number" && claims.nbf - SKEW_S > nowS) return { reason: "nbf" };
+	if (!subjectAllowed(claims, expect.subjects)) return { reason: "sub" };
+	return { subject: typeof claims.sub === "string" ? claims.sub : String(claims.email) };
+}
+
+/**
+ * Complete a sign-in. The state row is deleted on every callback, including failure, so it cannot be replayed.
+ * The CSRF cookie is not read here: SameSite=Strict is dropped on the cross-site return from the identity
+ * provider. The start POST already checked that cookie and stored it with this state.
+ */
+export async function finishOidc(ctx: TenantContext, o: {
+	kind: OidcKind; redirectUri: string; state: string; code: string | null; error: string | null;
+}): Promise<FinishResult> {
+	const state = o.state || "";
+	if (!/^[A-Za-z0-9_-]{20,128}$/.test(state)) return { ok: false, error: "This sign-in expired or was already used. Nothing was approved.", reason: "state", userCode: null };
+	const row: any = await ctx.DB.prepare("DELETE FROM oidc_txns WHERE state = ? RETURNING *").bind(state).first();
+	if (!row || row.kind !== o.kind) return { ok: false, error: "This sign-in expired or was already used. Nothing was approved.", reason: "state", userCode: null };
+	const userCode = row.user_code || null;
+	if (Date.now() >= row.expires_ms) return { ok: false, error: "This sign-in expired. Nothing was approved.", reason: "expired", userCode };
+	if (o.error || !o.code) return { ok: false, error: "Sign-in was cancelled. Nothing was approved.", reason: "cancelled", userCode };
+	const gate = ctx.gates.approvalOidc;
+	const secret = ctx.approvalClientSecret();
+	if (!approvalPolicy(gate).oidc || !secret) return { ok: false, error: "OpenID Connect approval is not configured.", reason: "config", userCode };
+	let disc: Discovery;
+	try { disc = await discover(gate.issuer); }
+	catch { return { ok: false, error: UNREACHABLE, reason: "discovery", userCode }; }
+	let idToken = "";
+	try {
+		const body = new URLSearchParams({
+			grant_type: "authorization_code", code: o.code, redirect_uri: o.redirectUri,
+			client_id: gate.clientId, client_secret: secret, code_verifier: row.verifier,
+		});
+		const res = await fetch(disc.token_endpoint, {
+			method: "POST", headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+			body, redirect: "error", signal: AbortSignal.timeout(FETCH_MS),
+		});
+		if (!res.ok) return { ok: false, error: UNREACHABLE, reason: "token", userCode };
+		const tok = await readJson(res, 65536);
+		idToken = typeof tok.id_token === "string" ? tok.id_token : "";
+	} catch { return { ok: false, error: UNREACHABLE, reason: "token", userCode }; }
+	let jwks: { keys?: any[] };
+	try { jwks = await getJson(disc.jwks_uri); }
+	catch { return { ok: false, error: UNREACHABLE, reason: "jwks", userCode }; }
+	const verified = await verifyIdToken(idToken, jwks, { iss: gate.issuer, aud: gate.clientId, nonce: row.nonce, subjects: gate.allowedSubjects });
+	if ("reason" in verified) return { ok: false, error: FAIL, reason: verified.reason, userCode };
+	let payload: Record<string, unknown> = {};
+	try {
+		const parsed = JSON.parse(row.payload_json || "{}");
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) payload = parsed;
+	} catch { /* empty payload */ }
+	return { ok: true, userCode, payload, subject: verified.subject };
+}

package/worker/src/backup.ts

@@ -0,0 +1,186 @@
+// Daily SQL snapshots. The R2 binding and the `0 3 * * *` trigger exist only when the deploy sets
+// A2A_BACKUP_BUCKET=1. With that unset there is no bucket and this module is not called.
+// Objects are `tenants/<id>/<YYYY-MM-DD>.sql`. A dated object is removed when its date is 30 or more
+// days before the run (UTC), which keeps 30 daily snapshots.
+
+import { exportRows, toSql, ExportError } from "./export.ts";
+import { parseDirectoryEntry, pinDirectoryRegion, tenantRegion, TENANT_NAME, type DirectoryEntry } from "./directory.ts";
+import { namespaceForRegion, parseGates, type DoNamespace, type KvNamespace, type SqlDb, type WorkerBindings } from "./tenancy.ts";
+
+export const DAILY_CRON = "0 3 * * *";
+export const RETENTION_DAYS = 30;
+/** Self-host has one inbox, so its objects live under this id. */
+export const SELF_TENANT_ID = "self";
+
+const TENANT_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export type R2BucketLike = NonNullable<WorkerBindings["BACKUP_BUCKET"]>;
+
+export interface BackupWritten {
+	tenantId: string;
+	key: string;
+	deleted: string[];
+}
+
+export interface BackupReport {
+	written: BackupWritten[];
+	skipped: { tenantId: string; status: string }[];
+	failed: { tenantId: string; error: string }[];
+}
+
+export function dayUtc(now: Date): string {
+	return now.toISOString().slice(0, 10);
+}
+
+/** UTC midnight for a real calendar day, or null. */
+export function parseDay(day: string): number | null {
+	const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(day);
+	if (!m) return null;
+	const y = Number(m[1]), mo = Number(m[2]), d = Number(m[3]);
+	const t = Date.UTC(y, mo - 1, d);
+	const dt = new Date(t);
+	if (dt.getUTCFullYear() !== y || dt.getUTCMonth() !== mo - 1 || dt.getUTCDate() !== d) return null;
+	return t;
+}
+
+/** True when `fileDay` is at least {@link RETENTION_DAYS} before `today`. */
+export function olderThanRetention(fileDay: string, today: string): boolean {
+	const file = parseDay(fileDay);
+	const now = parseDay(today);
+	if (file === null || now === null) return false;
+	return now - file >= RETENTION_DAYS * DAY_MS;
+}
+
+export function snapshotKey(tenantId: string, day: string): string {
+	if (!TENANT_ID.test(tenantId)) throw new ExportError("backup: tenant id is invalid");
+	if (parseDay(day) === null) throw new ExportError("backup: day is invalid");
+	return `tenants/${tenantId}/${day}.sql`;
+}
+
+/** The `YYYY-MM-DD` in `tenants/<id>/<day>.sql`, or null when the key is not one of ours. */
+export function objectDay(key: string, tenantId: string): string | null {
+	const prefix = `tenants/${tenantId}/`;
+	if (!key.startsWith(prefix) || !key.endsWith(".sql")) return null;
+	const day = key.slice(prefix.length, -".sql".length);
+	return parseDay(day) === null ? null : day;
+}
+
+async function listAll(bucket: R2BucketLike, prefix: string): Promise<string[]> {
+	const keys: string[] = [];
+	let cursor: string | undefined;
+	for (;;) {
+		const res = await bucket.list({ prefix, cursor, limit: 1000 });
+		for (const obj of res.objects ?? []) keys.push(obj.key);
+		if (!res.truncated) return keys;
+		if (!res.cursor || res.cursor === cursor) throw new ExportError("backup: snapshot listing did not finish");
+		cursor = res.cursor;
+	}
+}
+
+/** Delete dated objects for this tenant that are past retention. The object written today stays. */
+export async function pruneSnapshots(bucket: R2BucketLike, tenantId: string, today: string): Promise<string[]> {
+	if (!TENANT_ID.test(tenantId)) throw new ExportError("backup: tenant id is invalid");
+	const doomed = (await listAll(bucket, `tenants/${tenantId}/`)).filter((key) => {
+		const day = objectDay(key, tenantId);
+		return day !== null && olderThanRetention(day, today);
+	});
+	for (let i = 0; i < doomed.length; i += 1000) await bucket.delete(doomed.slice(i, i + 1000));
+	return doomed;
+}
+
+export async function writeSnapshot(bucket: R2BucketLike, tenantId: string, sql: string, now = new Date()): Promise<BackupWritten> {
+	const day = dayUtc(now);
+	const key = snapshotKey(tenantId, day);
+	await bucket.put(key, sql, { httpMetadata: { contentType: "application/sql" } });
+	const deleted = await pruneSnapshots(bucket, tenantId, day);
+	return { tenantId, key, deleted };
+}
+
+/** One self-host inbox, under {@link SELF_TENANT_ID}. */
+export async function backupDatabase(bucket: R2BucketLike, db: SqlDb, tenantId = SELF_TENANT_ID, now = new Date()): Promise<BackupWritten> {
+	const file = await exportRows(db, now);
+	return writeSnapshot(bucket, tenantId, toSql(file), now);
+}
+
+interface KvLister extends KvNamespace {
+	list?(options?: { prefix?: string; cursor?: string; limit?: number }): Promise<{
+		keys: { name: string }[];
+		list_complete: boolean;
+		cursor?: string;
+	}>;
+}
+
+async function directoryNames(kv: KvLister): Promise<string[]> {
+	if (typeof kv.list !== "function") throw new ExportError("backup: directory cannot be listed");
+	const names: string[] = [];
+	let cursor: string | undefined;
+	for (;;) {
+		const res = await kv.list({ prefix: "tenant:", cursor, limit: 1000 });
+		for (const k of res.keys ?? []) {
+			const name = k.name.startsWith("tenant:") ? k.name.slice("tenant:".length) : "";
+			if (TENANT_NAME.test(name)) names.push(name);
+		}
+		if (res.list_complete !== false) return names;
+		if (!res.cursor || res.cursor === cursor) throw new ExportError("backup: directory listing did not finish");
+		cursor = res.cursor;
+	}
+}
+
+function clip(e: unknown): string {
+	const msg = e instanceof Error ? e.message : String(e);
+	return msg.slice(0, 200);
+}
+
+/**
+ * Fan-out for a hosted deploy. Active tenants are exported; other statuses are skipped.
+ * An entry with no region yet is pinned the same way a request would pin it, then read.
+ * One tenant's failure is recorded and the rest still run.
+ */
+export async function backupDirectory(
+	kv: KvLister,
+	bucket: R2BucketLike,
+	ns: DoNamespace,
+	dataRegion: string,
+	now = new Date(),
+): Promise<BackupReport> {
+	const report: BackupReport = { written: [], skipped: [], failed: [] };
+	const names = await directoryNames(kv);
+	for (const name of names) {
+		let entry: DirectoryEntry | null = null;
+		try {
+			const raw = await kv.get(`tenant:${name}`, "json");
+			entry = parseDirectoryEntry(raw);
+			if (!entry) throw new ExportError("backup: directory entry is unreadable");
+			const pinned = await pinDirectoryRegion(kv, name, entry, dataRegion);
+			if (!pinned) throw new ExportError("backup: directory unavailable");
+			entry = pinned;
+			if (entry.status !== "active") {
+				report.skipped.push({ tenantId: entry.id, status: entry.status });
+				continue;
+			}
+			const sql = await exportTenantSql(ns, entry);
+			report.written.push(await writeSnapshot(bucket, entry.id, sql.sql, now));
+		} catch (e) {
+			report.failed.push({ tenantId: entry?.id || name, error: clip(e) });
+		}
+	}
+	return report;
+}
+
+export async function exportTenantSql(ns: DoNamespace, entry: DirectoryEntry): Promise<{ sql: string; exportedAt: string }> {
+	const bound = namespaceForRegion(ns, tenantRegion(entry));
+	const stub = bound.get(bound.idFromName(entry.id)) as { exportSql?: () => Promise<{ sql: string; exportedAt: string }> };
+	if (typeof stub.exportSql !== "function") throw new ExportError("exportSql: not available");
+	const out = await stub.exportSql();
+	if (!out || typeof out.sql !== "string" || typeof out.exportedAt !== "string") throw new ExportError("exportSql: empty");
+	return out;
+}
+
+/** Hosted daily job. Returns null when this invocation is not the backup cron or the bucket is unset. */
+export async function hostedDailyBackup(controller: { cron?: string }, env: WorkerBindings, now = new Date()): Promise<BackupReport | null> {
+	if (controller.cron !== DAILY_CRON || !env.BACKUP_BUCKET) return null;
+	if (env.TENANCY !== "host" || !env.TENANT_DO) return null;
+	if (!env.TENANT_DIRECTORY) throw new ExportError("backup: directory cannot be listed");
+	return backupDirectory(env.TENANT_DIRECTORY, env.BACKUP_BUCKET, env.TENANT_DO, parseGates(env).gates.dataRegion, now);
+}