@fased/fased 0.1.62 → 0.1.64

package/dist/gateway/a2a-http.js

@@ -1,9 +1,14 @@
 import { loadConfig } from "../config/io.js";
 import "../config/config.js";
+import { resolveWalletRuntimeConfig } from "../wallet/wallet-runtime-config.js";
+import { readWalletProviderRegistry, resolveWalletUserRole } from "../wallet/wallet-provider-registry.js";
 import { buildPublishedFederationOffers } from "../federation/offers.js";
 import { normalizeHandle, resolveFederationBaseUrl, resolveFederationHandle } from "../federation/runtime.js";
+import { createOrExecuteWalletSend, getWalletSendApprovalRequest } from "../wallet/wallet-send-approvals.js";
+import { FEDERATION_A2A_RPC_PATH, FEDERATION_PEER_HEADERS, authorizeFederationPeerRequestV2 } from "../federation/peer-auth-v2.js";
 import { orchestrateA2aTaskSettlement } from "./a2a-settlement.js";
-import { randomUUID } from "node:crypto";
+import { authorizeDurableA2aTask, claimDurableA2aPaymentChallenge, claimDurableA2aTaskExecution, issueDurableA2aPaymentChallenge, readDurableA2aPaymentChallenge, readDurableA2aTask, reserveDurableA2aTask, updateDurableA2aTask } from "./a2a-task-store.js";
+import { createHash, randomUUID } from "node:crypto";
 
 //#region src/gateway/a2a-http.ts
 const OFFER_SCHEMA_ID = "https://schemas.fased.ai/fased-agent-offer-v0.json";
@@ -105,18 +110,15 @@ async function readJsonBody(req, maxBytes) {
 		});
 	});
 }
-function extractSenderHandle(req, params, domain) {
-	const fromHeader = typeof req.headers["x-fased-sender-handle"] === "string" ? req.headers["x-fased-sender-handle"] : "";
-	const fromParams = typeof params?.senderHandle === "string" ? params.senderHandle : isRecord(params?.sender) && typeof params.sender.handle === "string" ? params.sender.handle : "";
-	const handle = fromHeader || fromParams;
-	return normalizeHandle(handle, domain);
-}
 function taskHasPaidReferences(task) {
 	if (!isRecord(task)) {
 		return false;
 	}
 	return task.invoice !== undefined || task.invoiceRef !== undefined || task.receipt !== undefined || task.receiptRef !== undefined;
 }
+function requestHasPaidReferences(task, params) {
+	return taskHasPaidReferences(task) || params?.invoice !== undefined || params?.receipt !== undefined;
+}
 function extractOfferId(taskInput, params) {
 	if (isRecord(taskInput) && typeof taskInput.offerId === "string") {
 		return taskInput.offerId.trim();
@@ -361,9 +363,21 @@ function extractMarketplacePaymentSummary(taskInput, params) {
 		...payer ? { payer } : {},
 		...payee ? { payee } : {},
 		...typeof receipt?.txRef === "string" && receipt.txRef.trim() ? { txRef: receipt.txRef.trim() } : {},
-		...typeof receipt?.settledAt === "string" && receipt.settledAt.trim() ? { settledAt: receipt.settledAt.trim() } : {}
+		...typeof receipt?.settledAt === "string" && receipt.settledAt.trim() ? { settledAt: receipt.settledAt.trim() } : {},
+		...typeof receipt?.challengeId === "string" && receipt.challengeId.trim() ? { challengeId: receipt.challengeId.trim() } : {},
+		...typeof receipt?.paymentMemo === "string" && receipt.paymentMemo.trim() ? { paymentMemo: receipt.paymentMemo.trim() } : {}
 	};
 }
+function fixedOfferAmountBaseUnits(offer) {
+	const amount = offer.pricing.amount;
+	const decimals = offer.paymentDefaults?.assetDecimals;
+	if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0 || typeof decimals !== "number" || !Number.isInteger(decimals) || decimals < 0 || decimals > 18) {
+		return null;
+	}
+	const scaled = amount * 10 ** decimals;
+	const rounded = Math.round(scaled);
+	return Number.isSafeInteger(rounded) && Math.abs(scaled - rounded) < 1e-6 ? rounded : null;
+}
 function buildCanonicalResultPayload(task, actor) {
 	const input = isRecord(task.input) ? task.input : null;
 	const prompt = input && typeof input.prompt === "string" ? input.prompt.trim() : "";
@@ -417,19 +431,15 @@ function toTaskSnapshot(task) {
 		createdAt: task.createdAt,
 		updatedAt: task.updatedAt,
 		output: task.output,
-		error: task.error
+		error: task.error,
+		settlement: task.settlement,
+		paymentRecovery: task.paymentRecovery
 	};
 }
 function writeSseEvent(res, event, data) {
 	res.write(`event: ${event}\n`);
 	res.write(`data: ${JSON.stringify(data)}\n\n`);
 }
-function buildAuthHeaders(apiToken) {
-	if (!apiToken) {
-		return {};
-	}
-	return { Authorization: `Bearer ${apiToken}` };
-}
 function headerValue(value) {
 	if (Array.isArray(value)) {
 		return typeof value[0] === "string" ? value[0] : "";
@@ -487,7 +497,6 @@ function createA2aHandler(opts) {
 	const profileVersion = opts.profileVersion ?? "v0.2";
 	const rpcPath = opts.rpcPath ?? "/a2a";
 	const streamPath = opts.streamPath ?? "/a2a/stream";
-	const tierCacheTtlMs = opts.tierCacheTtlMs ?? 3e4;
 	const url = new URL(opts.origin);
 	const domain = url.hostname;
 	const federationBaseUrl = resolveFederationBaseUrl(process.env);
@@ -499,26 +508,187 @@ function createA2aHandler(opts) {
 	});
 	const agentId = opts.agentId?.trim() || process.env.FASED_A2A_AGENT_ID?.trim() || handle;
 	const tasks = new Map();
-	const tierCache = new Map();
 	const federationBaseUrlResolved = opts.federationBaseUrl?.trim() || process.env.FASED_FEDERATION_BASE_URL?.trim() || federationBaseUrl;
 	const federationApiToken = opts.federationApiToken?.trim() || process.env.FASED_FEDERATION_API_TOKEN?.trim();
 	const settlementOrchestrator = opts.settlementOrchestrator ?? (async (params) => await orchestrateA2aTaskSettlement({
 		taskId: params.taskId,
 		taskInput: params.taskInput,
+		invoice: params.invoice,
+		receipt: params.receipt,
+		offer: params.offer,
+		challenge: params.challenge,
 		senderHandle: params.senderHandle,
 		env: params.env
 	}));
-	function updateTask(task, patch) {
-		if (patch.status) {
-			task.status = patch.status;
+	async function ensureReviewedRefundApproval(task, recovery) {
+		if (recovery.status !== "refund-required" || recovery.approvalRequestId) {
+			return recovery;
+		}
+		const challenge = readDurableA2aPaymentChallenge({
+			taskId: task.taskId,
+			env: process.env
+		});
+		if (!challenge || challenge.status !== "claimed") {
+			return {
+				...recovery,
+				reason: `${recovery.reason}; reviewed refund preparation is blocked because the claimed seller challenge is unavailable`,
+				updatedAt: new Date().toISOString()
+			};
+		}
+		const registry = readWalletProviderRegistry(process.env);
+		const candidates = registry.wallets.filter((wallet) => resolveWalletUserRole(wallet) === "agent" && wallet.addresses?.solana?.trim() === challenge.payeeAddress);
+		if (candidates.length !== 1) {
+			return {
+				...recovery,
+				reason: `${recovery.reason}; reviewed refund preparation requires exactly one Agent wallet matching the paid seller address`,
+				updatedAt: new Date().toISOString()
+			};
+		}
+		const wallet = candidates[0];
+		const cfg = loadConfig();
+		const created = await createOrExecuteWalletSend({
+			payload: {
+				actionKind: "send",
+				chain: "solana",
+				to: challenge.payerAddress,
+				amount: String(challenge.amount),
+				...challenge.asset.kind === "spl-token" ? { program: challenge.asset.address } : {},
+				memo: `fased:a2a-refund:v1:${challenge.challengeId}`,
+				walletId: wallet.id,
+				walletName: wallet.name,
+				providerId: wallet.providerId
+			},
+			requestedBy: "a2a-refund",
+			executionIntentId: `a2a-refund:${challenge.challengeId}`,
+			sendPath: "reviewed",
+			settlementContext: {
+				taskId: task.taskId,
+				invoiceId: challenge.invoiceId,
+				senderHandle: challenge.senderHandle
+			},
+			config: resolveWalletRuntimeConfig(cfg, process.env),
+			runtimeConfig: cfg,
+			providerIdOverride: wallet.providerId,
+			env: process.env
+		});
+		if (!created.ok) {
+			return {
+				...recovery,
+				reason: `${recovery.reason}; reviewed refund preparation failed: ${created.message ?? created.code ?? "unknown error"}`,
+				updatedAt: new Date().toISOString()
+			};
+		}
+		if (created.mode !== "manual") {
+			return {
+				...recovery,
+				reason: `${recovery.reason}; reviewed refund preparation failed closed because the reviewed path did not return a manual approval`,
+				updatedAt: new Date().toISOString()
+			};
+		}
+		return {
+			...recovery,
+			approvalRequestId: created.request.id,
+			reason: `${recovery.reason}; reviewed refund approval ${created.request.id} is pending operator and signer-owned WebAuthn authorization`,
+			updatedAt: new Date().toISOString()
+		};
+	}
+	async function reconcileReviewedRefund(task) {
+		const recovery = task.paymentRecovery;
+		if (recovery?.status !== "refund-required" || !recovery.approvalRequestId) {
+			return;
+		}
+		const challenge = readDurableA2aPaymentChallenge({
+			taskId: task.taskId,
+			env: process.env
+		});
+		const approval = getWalletSendApprovalRequest({
+			requestId: recovery.approvalRequestId,
+			env: process.env
+		});
+		if (!challenge || approval?.status !== "executed" || !approval.result?.txHash || approval.payload.to !== challenge.payerAddress || approval.payload.amount !== String(challenge.amount) || approval.payload.memo !== `fased:a2a-refund:v1:${challenge.challengeId}` || (challenge.asset.kind === "spl-token" ? approval.payload.program !== challenge.asset.address : Boolean(approval.payload.program))) {
+			return;
+		}
+		const refunded = {
+			...recovery,
+			status: "refunded",
+			refundTxRef: approval.result.txHash,
+			reason: `reviewed refund ${approval.result.txHash} executed through signer-owned authorization`,
+			updatedAt: new Date().toISOString()
+		};
+		const durable = await updateDurableA2aTask({
+			taskId: task.taskId,
+			paymentRecovery: refunded,
+			env: process.env
+		});
+		task.paymentRecovery = durable.paymentRecovery;
+		task.updatedAt = durable.updatedAt;
+	}
+	function taskFromDurable(record) {
+		return {
+			taskId: record.taskId,
+			status: record.status,
+			createdAt: record.createdAt,
+			updatedAt: record.updatedAt,
+			input: record.input,
+			output: record.output,
+			error: record.error,
+			marketplacePayment: record.marketplacePayment,
+			settlement: record.settlement,
+			paymentRecovery: record.paymentRecovery,
+			timers: [],
+			subscribers: new Set()
+		};
+	}
+	function resolveTask(taskId) {
+		const active = tasks.get(taskId);
+		if (active) {
+			return active;
 		}
-		if (patch.output !== undefined) {
-			task.output = patch.output;
+		const durable = readDurableA2aTask({
+			taskId,
+			env: process.env
+		});
+		if (!durable) {
+			return undefined;
 		}
-		if (patch.error !== undefined) {
-			task.error = patch.error;
+		const task = taskFromDurable(durable);
+		tasks.set(taskId, task);
+		return task;
+	}
+	async function updateTask(task, patch) {
+		const paymentRecovery = patch.paymentRecovery ?? ((patch.status === "failed" || patch.status === "canceled") && task.settlement?.status === "executed" && task.settlement.txHash ? {
+			status: "refund-required",
+			paymentTxRef: task.settlement.txHash,
+			reason: patch.error ?? `paid task entered terminal state ${patch.status}; seller must refund or resolve the dispute`,
+			updatedAt: new Date().toISOString()
+		} : undefined);
+		const durable = await updateDurableA2aTask({
+			taskId: task.taskId,
+			...patch.status ? { status: patch.status } : {},
+			...patch.output !== undefined ? { output: patch.output } : {},
+			...patch.error !== undefined ? { error: patch.error } : {},
+			...patch.settlement !== undefined ? { settlement: patch.settlement } : {},
+			...paymentRecovery !== undefined ? { paymentRecovery } : {},
+			env: process.env
+		});
+		if (durable.paymentRecovery?.status === "refund-required" && !durable.paymentRecovery.approvalRequestId) {
+			const reviewedRecovery = await ensureReviewedRefundApproval(task, durable.paymentRecovery);
+			if (reviewedRecovery !== durable.paymentRecovery) {
+				const refreshed = await updateDurableA2aTask({
+					taskId: task.taskId,
+					paymentRecovery: reviewedRecovery,
+					env: process.env
+				});
+				durable.paymentRecovery = refreshed.paymentRecovery;
+				durable.updatedAt = refreshed.updatedAt;
+			}
 		}
-		task.updatedAt = new Date().toISOString();
+		task.status = durable.status;
+		task.output = durable.output;
+		task.error = durable.error;
+		task.settlement = durable.settlement;
+		task.paymentRecovery = durable.paymentRecovery;
+		task.updatedAt = durable.updatedAt;
 		const snapshot = toTaskSnapshot(task);
 		for (const subscriber of task.subscribers) {
 			if (subscriber.writableEnded || subscriber.destroyed) {
@@ -538,81 +708,74 @@ function createA2aHandler(opts) {
 		}
 		task.timers = [];
 	}
-	async function resolveSenderTier(senderHandle) {
-		if (!senderHandle) {
-			return "unverified";
-		}
-		const cached = tierCache.get(senderHandle);
-		if (cached && cached.expiresAt > Date.now()) {
-			return cached.tier;
-		}
-		if (!federationBaseUrlResolved) {
-			return "unverified";
-		}
-		const endpoint = new URL(`/api/federation/directory/${encodeURIComponent(senderHandle)}`, federationBaseUrlResolved);
-		try {
-			const res = await fetch(endpoint, { headers: {
-				...buildAuthHeaders(federationApiToken),
-				accept: "application/json"
-			} });
-			let tier = "unverified";
-			if (res.ok) {
-				const body = await res.json();
-				if (isRecord(body)) {
-					const status = typeof body.status === "string" ? body.status : "";
-					if (status === "verified") {
-						tier = "verified";
-					} else if (status === "revoked") {
-						tier = "blocked";
-					} else {
-						tier = "unverified";
-					}
-				}
-			} else if (res.status === 404) {
-				tier = "unverified";
-			}
-			tierCache.set(senderHandle, {
-				tier,
-				expiresAt: Date.now() + tierCacheTtlMs
-			});
-			return tier;
-		} catch {
-			return "unverified";
-		}
+	async function releaseTaskExecution(task) {
+		const release = task.executionRelease;
+		task.executionRelease = undefined;
+		await release?.();
 	}
-	function createTask(input, marketplacePayment) {
-		const createdAt = new Date().toISOString();
-		const requestedTaskId = isRecord(input) && typeof input.taskId === "string" ? input.taskId.trim() : "";
-		const taskId = requestedTaskId && !tasks.has(requestedTaskId) ? requestedTaskId : randomUUID();
-		const task = {
+	async function createTask(params) {
+		const requestedTaskId = isRecord(params.input) && typeof params.input.taskId === "string" ? params.input.taskId.trim() : "";
+		const taskId = requestedTaskId || randomUUID();
+		const reserved = await reserveDurableA2aTask({
 			taskId,
-			status: "queued",
-			createdAt,
-			updatedAt: createdAt,
-			input,
-			...marketplacePayment ? { marketplacePayment } : {},
-			timers: [],
-			subscribers: new Set()
+			senderHandle: params.senderHandle,
+			input: params.input,
+			marketplacePayment: params.marketplacePayment,
+			accessToken: params.accessToken,
+			env: process.env
+		});
+		const existing = tasks.get(taskId);
+		const task = existing ?? taskFromDurable(reserved.record);
+		if (!existing) {
+			tasks.set(task.taskId, task);
+		}
+		return {
+			task,
+			created: reserved.created,
+			accessToken: reserved.accessToken
 		};
+	}
+	function requestTaskAccessToken(req, params) {
+		const header = headerValue(req.headers["x-fased-task-token"]).trim();
+		const param = typeof params?.taskAccessToken === "string" ? params.taskAccessToken.trim() : "";
+		return header || param;
+	}
+	function anonymousSenderKey(req) {
+		const client = opts.peerAuthClientIp ?? req.socket?.remoteAddress ?? "unknown";
+		const digest = createHash("sha256").update(client, "utf8").digest("hex").slice(0, 24);
+		return `anonymous:${digest}`;
+	}
+	function scheduleTaskExecution(task) {
+		if (isTerminal(task.status) || task.timers.length > 0) {
+			void releaseTaskExecution(task);
+			return;
+		}
 		const queuedToRunning = setTimeout(() => {
 			if (task.status !== "queued") {
 				return;
 			}
-			updateTask(task, { status: "running" });
+			void updateTask(task, { status: "running" }).catch(async (error) => {
+				task.error = error instanceof Error ? error.message : String(error);
+				clearTaskTimers(task);
+				await releaseTaskExecution(task);
+			});
 		}, 10);
 		const runningToDone = setTimeout(() => {
 			if (task.status === "canceled") {
+				void releaseTaskExecution(task);
 				return;
 			}
-			updateTask(task, {
+			void updateTask(task, {
 				status: "succeeded",
 				output: buildCanonicalResultPayload(task, handle)
+			}).catch((error) => {
+				task.error = error instanceof Error ? error.message : String(error);
+			}).finally(async () => {
+				clearTaskTimers(task);
+				await releaseTaskExecution(task);
 			});
-			clearTaskTimers(task);
 		}, 50);
 		task.timers.push(queuedToRunning, runningToDone);
-		tasks.set(task.taskId, task);
-		return task;
 	}
 	return async (req, res) => {
 		const parsed = new URL(req.url ?? "/", opts.origin);
@@ -640,7 +803,11 @@ function createA2aHandler(opts) {
 				"payments",
 				"service-offers"
 			],
-			auth: { type: "none" },
+			auth: {
+				type: "task-capability-and-federation-peer-v2",
+				paidTasks: "signed-federation-peer-v2-required",
+				taskAccess: "x-fased-task-token-header-or-json-rpc-taskAccessToken-required"
+			},
 			metadata: {
 				apBridgeEnabled: opts.includeApBridgeMetadata ?? true,
 				supportedObjects: [
@@ -669,7 +836,20 @@ function createA2aHandler(opts) {
 				});
 				return true;
 			}
-			const task = tasks.get(taskId);
+			const accessToken = requestTaskAccessToken(req);
+			const authorized = authorizeDurableA2aTask({
+				taskId,
+				accessToken,
+				env: process.env
+			});
+			if (!authorized) {
+				sendJson(res, 404, {
+					status: "not_found",
+					reason: "task not found"
+				});
+				return true;
+			}
+			const task = resolveTask(taskId);
 			if (!task) {
 				sendJson(res, 404, {
 					status: "not_found",
@@ -682,6 +862,7 @@ function createA2aHandler(opts) {
 			res.setHeader("Cache-Control", "no-cache, no-transform");
 			res.setHeader("Connection", "keep-alive");
 			res.setHeader("X-Accel-Buffering", "no");
+			res.setHeader("Referrer-Policy", "no-referrer");
 			writeSseEvent(res, "task.snapshot", toTaskSnapshot(task));
 			if (isTerminal(task.status)) {
 				res.end();
@@ -718,11 +899,31 @@ function createA2aHandler(opts) {
 			return true;
 		}
 		const params = isRecord(rpc.params) ? rpc.params : undefined;
-		const senderHandle = extractSenderHandle(req, params, domain);
-		const senderTier = await resolveSenderTier(senderHandle);
-		if (senderTier === "blocked") {
-			sendRpcError(res, id, -32040, "blocked sender");
-			return true;
+		let senderHandle = anonymousSenderKey(req);
+		let senderTier = "unverified";
+		const signedProtocolHeader = headerValue(req.headers[FEDERATION_PEER_HEADERS.protocolVersion]);
+		if (signedProtocolHeader) {
+			if (rpcPath !== FEDERATION_A2A_RPC_PATH) {
+				sendRpcError(res, id, -32040, "signed A2A requires the canonical /a2a endpoint");
+				return true;
+			}
+			const peerAuth = await authorizeFederationPeerRequestV2({
+				req,
+				body: body.value,
+				recipientHandle: handle,
+				expectedPath: FEDERATION_A2A_RPC_PATH,
+				directoryBaseUrl: federationBaseUrlResolved,
+				directoryApiToken: federationApiToken,
+				clientIp: opts.peerAuthClientIp,
+				env: process.env,
+				deps: opts.peerAuthDeps
+			});
+			if (!peerAuth.ok) {
+				sendRpcError(res, id, -32040, peerAuth.reason, peerAuth.statusCode, { code: peerAuth.code });
+				return true;
+			}
+			senderHandle = peerAuth.senderHandle;
+			senderTier = "verified";
 		}
 		if (rpc.method === "a2a.ping" || rpc.method === "ping") {
 			sendRpcResult(res, id, {
@@ -750,9 +951,45 @@ function createA2aHandler(opts) {
 			sendRpcResult(res, id, { offer });
 			return true;
 		}
+		if (rpc.method === "payments.prepare" || rpc.method === "payment.prepare" || rpc.method === "payments/prepare") {
+			if (senderTier !== "verified") {
+				sendRpcError(res, id, -32041, "payment challenge requires verified sender");
+				return true;
+			}
+			const taskId = typeof params?.taskId === "string" ? params.taskId.trim() : "";
+			const offerId = typeof params?.offerId === "string" ? params.offerId.trim() : "";
+			const payerAddress = typeof params?.payerAddress === "string" ? params.payerAddress.trim() : "";
+			const offer = findOfferById(offerId, offers);
+			const payment = offer?.paymentDefaults;
+			const amount = offer ? fixedOfferAmountBaseUnits(offer) : null;
+			const payer = normalizeAddressForChain("solana", payerAddress);
+			const payee = normalizeAddressForChain("solana", payment?.payee.address);
+			const asset = payment ? extractCanonicalAsset(payment.asset, "solana") : null;
+			if (!taskId || !offer || !payment || !amount || !payer || !payee || !asset) {
+				sendRpcError(res, id, -32602, "invalid fixed-price Solana payment challenge request");
+				return true;
+			}
+			try {
+				const challenge = await issueDurableA2aPaymentChallenge({
+					taskId,
+					senderHandle,
+					offerId: offer.id,
+					payerAddress: payer,
+					payeeAddress: payee,
+					amount,
+					currency: payment.currency,
+					asset,
+					env: process.env
+				});
+				sendRpcResult(res, id, challenge);
+			} catch (error) {
+				sendRpcError(res, id, -32055, error instanceof Error ? error.message : String(error));
+			}
+			return true;
+		}
 		if (rpc.method === "tasks.create" || rpc.method === "task.create" || rpc.method === "tasks/create") {
 			const taskInput = params && "task" in params ? params.task : params;
-			const hasPaidReferences = taskHasPaidReferences(taskInput);
+			const hasPaidReferences = requestHasPaidReferences(taskInput, params);
 			const offerIssue = validateOfferReference(taskInput, params, offers);
 			if (offerIssue) {
 				sendRpcError(res, id, offerIssue.code, offerIssue.message, 200, offerIssue.data);
@@ -772,13 +1009,39 @@ function createA2aHandler(opts) {
 				sendRpcError(res, id, -32041, "paid task requires verified sender");
 				return true;
 			}
-			const task = createTask(taskInput, extractMarketplacePaymentSummary(taskInput, params));
+			let taskResult;
+			try {
+				taskResult = await createTask({
+					input: taskInput,
+					marketplacePayment: extractMarketplacePaymentSummary(taskInput, params),
+					senderHandle,
+					accessToken: requestTaskAccessToken(req, params)
+				});
+			} catch (error) {
+				sendRpcError(res, id, -32054, error instanceof Error ? error.message : String(error));
+				return true;
+			}
+			const task = taskResult.task;
 			let settlement;
-			if (hasPaidReferences) {
+			const executionRelease = isTerminal(task.status) ? null : await claimDurableA2aTaskExecution({
+				taskId: task.taskId,
+				env: process.env
+			});
+			if (executionRelease) {
+				task.executionRelease = executionRelease;
+			}
+			if (hasPaidReferences && executionRelease && (!task.settlement || task.settlement.status !== "executed")) {
 				try {
 					settlement = await settlementOrchestrator({
 						taskId: task.taskId,
 						taskInput,
+						invoice: params?.invoice,
+						receipt: params?.receipt,
+						offer: findOfferById(extractOfferId(taskInput, params), offers),
+						challenge: readDurableA2aPaymentChallenge({
+							taskId: task.taskId,
+							env: process.env
+						}),
 						senderHandle,
 						senderTier,
 						env: process.env
@@ -789,10 +1052,37 @@ function createA2aHandler(opts) {
 						reason: `settlement orchestration error: ${String(err)}`
 					};
 				}
+				if (settlement.status === "executed") {
+					try {
+						await claimDurableA2aPaymentChallenge({
+							taskId: task.taskId,
+							challengeId: settlement.challengeId ?? "",
+							senderHandle,
+							payerAddress: settlement.payerAddress ?? "",
+							txRef: settlement.txHash ?? "",
+							env: process.env
+						});
+					} catch (error) {
+						settlement = {
+							status: "failed",
+							reason: error instanceof Error ? error.message : String(error)
+						};
+					}
+				}
+				await updateTask(task, { settlement });
+			} else {
+				settlement = task.settlement;
+			}
+			const settlementAllowsExecution = !hasPaidReferences || task.settlement?.status === "executed";
+			if (executionRelease && settlementAllowsExecution) {
+				scheduleTaskExecution(task);
+			} else if (executionRelease) {
+				await releaseTaskExecution(task);
 			}
 			sendRpcResult(res, id, {
 				taskId: task.taskId,
 				status: task.status,
+				...taskResult.accessToken ? { taskAccessToken: taskResult.accessToken } : {},
 				streamUrl: `${new URL(streamPath, visibleOrigin).toString()}?taskId=${encodeURIComponent(task.taskId)}`,
 				...settlement ? { settlement } : {}
 			});
@@ -804,11 +1094,44 @@ function createA2aHandler(opts) {
 				sendRpcError(res, id, -32602, "missing taskId");
 				return true;
 			}
-			const task = tasks.get(taskId);
+			const authorized = authorizeDurableA2aTask({
+				taskId,
+				accessToken: requestTaskAccessToken(req, params),
+				env: process.env
+			});
+			const task = authorized ? resolveTask(taskId) : undefined;
 			if (!task) {
 				sendRpcError(res, id, -32044, "task not found");
 				return true;
 			}
+			await reconcileReviewedRefund(task);
+			sendRpcResult(res, id, toTaskSnapshot(task));
+			return true;
+		}
+		if (rpc.method === "tasks.refund.prepare" || rpc.method === "task.refund.prepare" || rpc.method === "tasks/refund/prepare") {
+			if (senderTier !== "verified") {
+				sendRpcError(res, id, -32041, "refund preparation requires the verified paying peer");
+				return true;
+			}
+			const taskId = typeof params?.taskId === "string" ? params.taskId.trim() : "";
+			const authorized = taskId ? authorizeDurableA2aTask({
+				taskId,
+				accessToken: requestTaskAccessToken(req, params),
+				env: process.env
+			}) : false;
+			const task = authorized ? resolveTask(taskId) : undefined;
+			if (!task?.paymentRecovery || task.paymentRecovery.status !== "refund-required") {
+				sendRpcError(res, id, -32044, "refund-required task not found");
+				return true;
+			}
+			const recovery = await ensureReviewedRefundApproval(task, task.paymentRecovery);
+			const durable = await updateDurableA2aTask({
+				taskId,
+				paymentRecovery: recovery,
+				env: process.env
+			});
+			task.paymentRecovery = durable.paymentRecovery;
+			task.updatedAt = durable.updatedAt;
 			sendRpcResult(res, id, toTaskSnapshot(task));
 			return true;
 		}
@@ -818,14 +1141,20 @@ function createA2aHandler(opts) {
 				sendRpcError(res, id, -32602, "missing taskId");
 				return true;
 			}
-			const task = tasks.get(taskId);
+			const authorized = authorizeDurableA2aTask({
+				taskId,
+				accessToken: requestTaskAccessToken(req, params),
+				env: process.env
+			});
+			const task = authorized ? resolveTask(taskId) : undefined;
 			if (!task) {
 				sendRpcError(res, id, -32044, "task not found");
 				return true;
 			}
 			if (!isTerminal(task.status)) {
 				clearTaskTimers(task);
-				updateTask(task, { status: "canceled" });
+				await updateTask(task, { status: "canceled" });
+				await releaseTaskExecution(task);
 			}
 			sendRpcResult(res, id, toTaskSnapshot(task));
 			return true;