xytara 3.1.10 → 3.1.12

package/.env.example

@@ -17,6 +17,7 @@ XYTARA_X402_TOPUP_UNITS=1000
 # The runtime mints a fresh CDP Bearer JWT per request when both are set.
 CDP_API_KEY_ID=
 CDP_API_KEY_SECRET=
+# (XYTARA_X402_CDP_KEY_ID / XYTARA_X402_CDP_KEY_SECRET are accepted as aliases for the two above)
 XYTARA_PAYMENT_MAX_AGE_SECONDS=300
 XYTARA_WALLET_REGISTRY_JSON=[]
 XYTARA_TREASURY_DESTINATION_ID=
@@ -24,6 +25,9 @@ XYTARA_TREASURY_DESTINATION_KIND=
 XYTARA_TREASURY_ACCOUNT_ID=
 XYTARA_TREASURY_EXTERNAL_REF=
 XYTARA_TREASURY_DESTINATIONS_JSON={}
+# optional file-backed alternatives to the two *_JSON values above (blank = use the JSON values)
+XYTARA_WALLET_REGISTRY_PATH=
+XYTARA_TREASURY_DESTINATIONS_PATH=
 XYTARA_BSV_TERANODE_NETWORK=mainnet
 XYTARA_BSV_TERANODE_RPC_URL=
 XYTARA_BSV_TERANODE_MODE=opreturn
@@ -37,6 +41,18 @@ XYTARA_BSV_TERANODE_SETTLEMENT_RUNTIME_MODE=mock
 # operator write surfaces fail closed until both tokens are set
 XYTARA_CREDIT_BRIDGE_BEARER_TOKEN=
 XYTARA_ACCOUNT_AUTH_BEARER_TOKEN=
+# commerce-bridge write surface (distinct from the credit bridge); also fails closed until set
+XYTARA_COMMERCE_BRIDGE_BEARER_TOKEN=
+# optional: require spend-proof binding on spend-credential use (blank = runtime default)
+XYTARA_REQUIRE_SPEND_PROOF_BINDING=
+# hosted-checkout webhook verification (blank = runtime defaults; set the secret before going live)
+XYTARA_CHECKOUT_WEBHOOK_SECRET=
+XYTARA_HOSTED_CHECKOUT_WEBHOOK_SECRET=
+XYTARA_CHECKOUT_WEBHOOK_VERIFICATION_REQUIRED=
+XYTARA_CHECKOUT_WEBHOOK_MAX_AGE_SECONDS=
+# optional commerce pack map / prep TTL overrides (blank = runtime defaults)
+XYTARA_COMMERCE_PACK_MAP_JSON=
+XYTARA_COMMERCE_PREP_TTL_MS=
 XYTARA_CALLBACK_DELIVERY_ENABLED=true
 XYTARA_CALLBACK_SIGNING_SECRET=
 XYTARA_CALLBACK_TIMEOUT_MS=5000
@@ -47,10 +63,52 @@ XYTARA_SETTLEMENT_REFRESH_INTERVAL_MS=1500
 XYTARA_RATE_LIMIT_ENABLED=true
 XYTARA_RATE_LIMIT_WINDOW_MS=60000
 XYTARA_RATE_LIMIT_MAX_REQUESTS=600
-XYTARA_EXTERNAL_EXECUTION_REQUIRED=false
+# optional: scope the rate limit per route instead of globally (blank = runtime default)
+XYTARA_RATE_LIMIT_ROUTE_SCOPED=
+XYTARA_REQUEST_TIMEOUT_MS=30000
+XYTARA_HEADERS_TIMEOUT_MS=15000
 XYTARA_EXECUTION_TARGETS_JSON=[]
+# External execution (env targets + registered providers). Cold-start ride-out retries ONLY on
+# not-processed signals (408/429/503, connection refused/DNS). The budget is the TOTAL wall-clock for
+# one buyer call across all retries AND failover candidates, kept inside the ~60s x402 authorization
+# window so a ridden-out call still settles. Per-target timeout_ms is capped at 30000 for the same reason.
+XYTARA_EXTERNAL_EXECUTION_RETRY_WINDOW_MS=45000
+XYTARA_EXTERNAL_EXECUTION_MAX_RETRIES=29
+XYTARA_EXTERNAL_EXECUTION_BUDGET_MS=50000
+# Open execution-provider network (lib/provider_registry.js): providers self-register an endpoint +
+# the capabilities they serve; the runtime routes paid calls to ACTIVE providers and splits revenue.
+# Registration FAILS CLOSED until the bearer is set, UNLESS open registration is turned on. Every
+# provider still lands pending until an operator activates it (the vetting gate). See the live
+# machine contract at GET /v1/provider-network/contract.
+XYTARA_PROVIDER_REGISTRY_BEARER_TOKEN=
+# 1 = permissionless self-registration (no bearer); still rate-limited + pending-capped.
+XYTARA_PROVIDER_OPEN_REGISTRATION=0
+XYTARA_PROVIDER_REGISTRATION_RATE_PER_MIN=5
+XYTARA_PROVIDER_REGISTRATION_RATE_GLOBAL_PER_MIN=60
+XYTARA_PROVIDER_MAX_PENDING=100
+# provider endpoint policy: strict (default when RENDER is set) = https only + no loopback/private/
+# link-local/metadata hosts, re-checked by DNS at dispatch; permissive (default locally) for dev/tests
+XYTARA_PROVIDER_ENDPOINT_POLICY=
+# cap on a provider's revenue share, basis points (10000 = 100%)
+XYTARA_PROVIDER_MAX_REVENUE_SHARE_BPS=10000
+# health/failover: consecutive failures -> unhealthy; cooldown before a half-open retry; max candidates tried
+XYTARA_PROVIDER_UNHEALTHY_THRESHOLD=3
+XYTARA_PROVIDER_UNHEALTHY_COOLDOWN_MS=60000
+XYTARA_PROVIDER_FAILOVER_MAX=3
+# routing reputation recency decay, factor in (0,1): fades older observations so recent performance
+# weighs more. 1 (default) = no decay (lifetime counts). e.g. 0.95 once the network has real history.
+XYTARA_PROVIDER_REPUTATION_DECAY=1
+# Provider payout auto-execution via an EXTERNAL signer (the runtime stays key-less). OFF unless the
+# URL is set; otherwise payouts are recorded and the operator sends + confirms them. See services/payout-signer.
+XYTARA_PAYOUT_SIGNER_URL=
+XYTARA_PAYOUT_SIGNER_BEARER=
+XYTARA_PAYOUT_SIGNER_TIMEOUT_MS=20000
 XYTARA_L402_ENABLED=false
 XYTARA_L402_SHARED_SECRET=
+# optional L402 tuning (blank = runtime defaults)
+XYTARA_L402_MAX_AGE_SECONDS=
+XYTARA_L402_INVOICE_RATE_PER_MIN=
+XYTARA_L402_INVOICE_RATE_GLOBAL_PER_MIN=
 XYTARA_BOLT_ENABLED=false
 XYTARA_BOLT_SHARED_SECRET=
 XYTARA_BOLT_NETWORK=mainnet
@@ -61,6 +119,8 @@ XYTARA_MPP_SHARED_SECRET=
 XYTARA_MPP_PROVIDER=stripe_tempo_compatible
 XYTARA_MPP_SETTLEMENT_FAMILY=cards_or_stablecoin_or_lightning
 XYTARA_MPP_MAX_AGE_SECONDS=300
+# optional minimum MPP amount in minor units (blank = runtime default)
+XYTARA_MPP_MIN_AMOUNT_MINOR=
 XYTARA_NETWORK_DNS_RESULT_ORDER=verbatim
 XYTARA_NETWORK_PREFERRED_IP_FAMILY=auto
 XYTARA_EXTERNAL_EXECUTION_IP_FAMILY=auto

package/README.md

@@ -1,6 +1,6 @@
 # xytara
 
-[![smithery badge](https://smithery.ai/badge/naxytra/xytara-mcp-executor)](https://smithery.ai/servers/naxytra/xytara-mcp-executor)
+Listed on [Smithery](https://smithery.ai/server/naxytra/xytara-mcp-executor) · [Glama](https://glama.ai/mcp/servers/naxytra/xytara-mcp-executor) · the official MCP registry (`com.naxytra/xytara-mcp-executor`).
 
 **x402 pay-per-call agent-commerce runtime** — the payment and execution layer of the naxytra
 machine stack. An agent discovers a capability, pays once with x402 (gasless USDC on Base), and gets

package/RELEASE_NOTES.md

@@ -1,7 +1,5 @@
-`xytara` 3.1.10 adds a free-tier cold-start ride-out and a reference payout signer, and refreshes the public collateral.
+`xytara` 3.1.12 makes the public adapter-depth surface report open-network providers truthfully.
 
-Highlights:
-
-- **Cold-start ride-out** — external execution now retries only not-processed signals (408/429/503 and connection-refused) within the x402 settlement window, so a cold free-tier provider warms up mid-retry instead of failing an unsettled call. No always-on keepalive is required. An ambiguous timeout or reset is never retried, so there is no double-execution.
-- **Reference payout signer** (`services/payout-signer`) — a separately-deployed service that sends provider payouts on Base while the runtime stays key-less. Fail-closed and double-pay-safe, with an optional durable (Supabase) idempotency store so a free-tier restart cannot cause a re-send.
-- Refreshed README and package metadata to lead with the proven, mainnet-demonstrated capabilities.
+- `/v1/adapter-depth` and `/v1/adapter-depth/summary` now count ACTIVE open-network providers that declared an adapter task as provider-live paths, alongside operator env targets. Each is labelled `routing: open_provider_registry`, and the pack lists its `depth_sources`. A pending provider never counts, and a provider is shown as shadowed (not counted) when an operator env target pins the whole lane, because env targets are routed first.
+- Previously the surface only looked at env targets, so it reported `provider_wiring_required` even while paid MCP calls were being served by the live registry provider. It now reports `initial_provider_live_path` for the task that provider serves.
+- Internal callers without runtime state keep the env-only view, so no other surface changes.

package/lib/adapter_depth_contract.js

@@ -3,6 +3,7 @@
 const packageJson = require("../package.json");
 const { catalog } = require("../fixtures/catalog");
 const { loadExecutionTargetRegistry } = require("./external_execution_runtime");
+const { listProviders } = require("./provider_registry");
 
 function normalizeString(value, fallback = "") {
   const raw = typeof value === "string" ? value.trim() : "";
@@ -59,10 +60,60 @@ function summarizeTarget(target) {
   };
 }
 
-function summarizeAdapterTaskDepth(task) {
-  const targets = listTargetsForTask(task.task_ref).map(summarizeTarget);
+// ACTIVE open-network providers that declared this task_ref. Env targets resolve before the
+// registry at call time, so a provider is shadowed (not routed) when an enabled env target pins
+// the WHOLE lane (task_ref with no tool/integration selector); it is then listed but not counted.
+function listRegistryProvidersForTask(state, taskRef, envTargets) {
+  if (!state) return [];
+  const normalizedTaskRef = normalizeString(taskRef);
+  const wholeLanePinned = envTargets.some((target) =>
+    target.enabled !== false
+    && normalizeString(target.task_ref) === normalizedTaskRef
+    && !normalizeString(target.tool_name)
+    && !normalizeString(target.integration_id)
+  );
+  return listProviders(state, { status: "active" })
+    .filter((provider) => Array.isArray(provider.task_refs) && provider.task_refs.includes(normalizedTaskRef))
+    .map((provider) => {
+      const health = (provider.health && provider.health.status) || "healthy";
+      return {
+        target_id: `registry:${provider.provider_id}`,
+        provider: provider.provider_id,
+        routing: "open_provider_registry",
+        task_ref: normalizedTaskRef,
+        tool_name: null,
+        tool_names: Array.isArray(provider.tool_names) ? provider.tool_names.slice() : [],
+        integration_id: null,
+        enabled: !wholeLanePinned,
+        shadowed_by_env_target: wholeLanePinned,
+        health_status: health,
+        timeout_ms: provider.timeout_ms,
+        endpoint_configured: Boolean(normalizeString(provider.endpoint_url)),
+        auth_configured: Boolean(normalizeString(provider.auth_token)),
+        operational_coverage: {
+          execute_endpoint: Boolean(normalizeString(provider.endpoint_url)),
+          bearer_auth: Boolean(normalizeString(provider.auth_token)),
+          bounded_timeout: Number(provider.timeout_ms || 0) >= 500,
+          // The provider-network execution contract fixes the deliverable shape
+          // (result.output / output_payload), and activation is operator-vetted against it.
+          proof_fact_compatible: true,
+          deterministic_retry_surface: true,
+          tool_level_binding: Array.isArray(provider.tool_names) && provider.tool_names.length > 0,
+          operator_health_surface: "runtime_tracked_provider_health",
+          operator_tool_catalog_surface: null
+        }
+      };
+    });
+}
+
+function summarizeAdapterTaskDepth(task, state) {
+  const envTargets = listTargetsForTask(task.task_ref).map(summarizeTarget);
+  const registryTargets = listRegistryProvidersForTask(state, task.task_ref, loadExecutionTargetRegistry());
+  const targets = envTargets.concat(registryTargets);
   const enabledTargets = targets.filter((target) => target.enabled);
-  const toolNames = Array.from(new Set(enabledTargets.map((target) => target.tool_name).filter(Boolean))).sort();
+  const toolNames = Array.from(new Set(enabledTargets
+    .flatMap((target) => [target.tool_name].concat(target.tool_names || []))
+    .filter(Boolean))).sort();
   const allTargetsCovered = enabledTargets.length > 0 && enabledTargets.every((target) =>
     target.operational_coverage.execute_endpoint
     && target.operational_coverage.bounded_timeout
@@ -80,6 +131,8 @@ function summarizeAdapterTaskDepth(task) {
     provider_live: enabledTargets.length > 0,
     configured_target_count: targets.length,
     enabled_target_count: enabledTargets.length,
+    env_target_count: envTargets.length,
+    registry_provider_count: registryTargets.filter((target) => target.enabled).length,
     configured_tool_count: toolNames.length,
     configured_tools: toolNames,
     execution_targets: targets,
@@ -89,11 +142,17 @@ function summarizeAdapterTaskDepth(task) {
   };
 }
 
-function buildAdapterDepthPack() {
-  const adapterTasks = listAdapterTasks().map(summarizeAdapterTaskDepth);
+// `state` (optional): the live runtime state. When given, ACTIVE open-network providers count as
+// provider-live paths alongside operator env targets (each labelled routing:open_provider_registry).
+// Without it the pack is env-target-only, exactly as before.
+function buildAdapterDepthPack(state) {
+  const adapterTasks = listAdapterTasks().map((task) => summarizeAdapterTaskDepth(task, state));
   const providerLiveTasks = adapterTasks.filter((task) => task.provider_live);
   const deepenedTasks = adapterTasks.filter((task) => task.provider_depth_state === "provider_live_path_deepened");
   const configuredTargets = loadExecutionTargetRegistry().filter((target) => target && target.enabled !== false);
+  const registryProviderIds = new Set(adapterTasks.flatMap((task) =>
+    task.execution_targets.filter((target) => target.routing === "open_provider_registry" && target.enabled).map((target) => target.provider)
+  ));
   return {
     ok: true,
     product: packageJson.name,
@@ -110,8 +169,10 @@ function buildAdapterDepthPack() {
       deepened_provider_live_task_count: deepenedTasks.length,
       configured_execution_target_count: configuredTargets.length,
       configured_provider_count: new Set(configuredTargets.map((target) => normalizeString(target.provider))).size,
-      configured_tool_count: new Set(configuredTargets.map((target) => normalizeString(target.tool_name)).filter(Boolean)).size
+      configured_tool_count: new Set(configuredTargets.map((target) => normalizeString(target.tool_name)).filter(Boolean)).size,
+      registry_provider_count: registryProviderIds.size
     },
+    depth_sources: state ? ["operator_env_targets", "open_provider_registry"] : ["operator_env_targets"],
     adapter_tasks: adapterTasks,
     production_depth_requirements: [
       "at_least_one_enabled_execution_target_for_provider_backed_task",
@@ -136,8 +197,8 @@ function buildAdapterDepthPack() {
   };
 }
 
-function summarizeAdapterDepthPack() {
-  const pack = buildAdapterDepthPack();
+function summarizeAdapterDepthPack(state) {
+  const pack = buildAdapterDepthPack(state);
   return {
     ok: true,
     product: pack.product,
@@ -145,6 +206,7 @@ function summarizeAdapterDepthPack() {
     summary_version: "xytara-adapter-depth-summary-v1",
     adapter_depth_state: pack.adapter_depth_state,
     counts: pack.counts,
+    depth_sources: pack.depth_sources,
     public_claim_boundary: pack.public_claim_boundary,
     linked_surfaces: pack.linked_surfaces
   };

package/lib/capability_execution_truth.js

@@ -108,6 +108,9 @@ function classifyTask(task, settlementReadiness) {
   }
 
   if (normalizeString(task && task.public_category) === "adapter") {
+    // Only ENABLED targets make an adapter lane live — a bound-but-disabled target must not be
+    // reported as provider_live (adapter-depth filters the same way; the two surfaces must agree).
+    const enabledTargets = providerTargets.filter((target) => target.enabled);
     return {
       task_ref: task.public_task_ref,
       internal_task_ref: task.task_ref,
@@ -115,10 +118,11 @@ function classifyTask(task, settlementReadiness) {
       public_category: task.public_category,
       execution_mode: task.execution_mode,
       latency_class: task.latency_class,
-      execution_truth: providerTargets.length > 0 ? "provider_live" : "provider_wiring_required",
-      execution_origin: providerTargets.length > 0 ? "external_execution_target" : "adapter_lane_without_bound_target",
-      commercialization_posture: providerTargets.length > 0 ? "sellable_live_now" : "sellable_by_integration",
-      matching_execution_target_count: providerTargets.length,
+      execution_truth: enabledTargets.length > 0 ? "provider_live" : "provider_wiring_required",
+      execution_origin: enabledTargets.length > 0 ? "external_execution_target" : "adapter_lane_without_bound_target",
+      commercialization_posture: enabledTargets.length > 0 ? "sellable_live_now" : "sellable_by_integration",
+      matching_execution_target_count: enabledTargets.length,
+      disabled_execution_target_count: providerTargets.length - enabledTargets.length,
       matching_execution_targets: providerTargets,
       requirements: {
         configured_provider_target_required: true

package/lib/command_flow.js

@@ -10,6 +10,7 @@ const { resolveSpendCredential, evaluateAuthorityBindingAction } = require("./ac
 const { validateIntegrationSelection } = require("../integrations/dispatch");
 const { markPaymentAccepted, settleDeferredPayment, verifyPaymentAcceptance } = require("./payment_verification");
 const { executeExternalTarget, resolveExecutionTarget } = require("./external_execution_runtime");
+const { externalExecutionBudgetMs } = require("./external_execution_policy");
 const { resolveRegisteredTargets, hasActiveMatchingProvider, recordProviderHealth, recordProviderRouting, recordProviderSettlement } = require("./provider_registry");
 const { claimDeferredExecution, releaseDeferredExecution } = require("./execution_dedupe");
 
@@ -94,12 +95,36 @@ function buildCreditRejectionResponse(creditDecision, quote) {
   };
 }
 
+// What a provider is allowed to see of the buyer's payment context: the verification outcome and
+// scalar payment facts only. NEVER the signed x402 authorization / deferred-settlement material
+// (that would hand a third-party provider the buyer's signature before settlement), and never
+// signature-, secret- or raw-looking keys or nested objects from any lane's payload.
+const SENSITIVE_CONTEXT_KEY = /signature|secret|private|authorization|raw|base64|header|token/i;
+function sanitizeAuthorizationContextForProvider(context) {
+  if (!context || typeof context !== "object") return null;
+  const payload = context.payment_payload && typeof context.payment_payload === "object" ? context.payment_payload : null;
+  const safePayload = payload
+    ? Object.fromEntries(Object.entries(payload).filter(([key, value]) => !SENSITIVE_CONTEXT_KEY.test(key) && (value === null || typeof value !== "object")))
+    : null;
+  return {
+    ok: context.ok === true,
+    verification_mode: context.verification_mode || null,
+    wallet_id: context.wallet_id || null,
+    age_seconds: Number.isFinite(Number(context.age_seconds)) ? Number(context.age_seconds) : null,
+    payment_payload: safePayload
+  };
+}
+
 async function buildExternalExecutionOptions(state, payload, quote, authorizationContext) {
+  // One wall-clock budget for the whole call (every retry of every candidate), inside the x402
+  // authorization window — see external_execution_policy.js.
+  const executionOptions = { deadline_ms: Date.now() + externalExecutionBudgetMs() };
+  const forwardedContext = sanitizeAuthorizationContextForProvider(authorizationContext);
   // Operator-pinned env target resolves first and is used as-is (an explicit single target,
   // no failover). Empty env + empty registry -> {} (unchanged behavior).
   const envTarget = resolveExecutionTarget(payload, quote);
   if (envTarget) {
-    const execution = await executeExternalTarget(envTarget, payload, quote, authorizationContext);
+    const execution = await executeExternalTarget(envTarget, payload, quote, forwardedContext, executionOptions);
     if (!execution || !execution.ok) {
       return { error: execution || { ok: false, status: 502, reason: "external_execution_failed" } };
     }
@@ -122,7 +147,12 @@ async function buildExternalExecutionOptions(state, payload, quote, authorizatio
   }
   let lastError = null;
   for (const target of candidates) {
-    const execution = await executeExternalTarget(target, payload, quote, authorizationContext);
+    if (Date.now() >= executionOptions.deadline_ms) {
+      // Budget spent on earlier candidates: stop here rather than start a call that cannot settle.
+      lastError = lastError || { ok: false, status: 504, reason: "external_execution_budget_exhausted" };
+      break;
+    }
+    const execution = await executeExternalTarget(target, payload, quote, forwardedContext, executionOptions);
     try { recordProviderRouting(state, target.registered_provider_id); } catch (_) { /* non-fatal */ }
     if (execution && execution.ok) {
       try { recordProviderHealth(state, target.registered_provider_id, { ok: true }); } catch (_) { /* non-fatal */ }
@@ -139,9 +169,38 @@ async function buildExternalExecutionOptions(state, payload, quote, authorizatio
   return { error: lastError };
 }
 
+// Assets the x402 lane can settle in, with their on-chain decimals (needed to turn settled base
+// units into the ledger's cents). Anything else cannot be reconciled and must not accrue on the quote.
+const X402_ASSET_DECIMALS = new Map([
+  ["0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", 6], // USDC, Base mainnet (eip155:8453)
+  ["0x036cbd53842c5426634e7929541ec2318f3dcf7e", 6]  // USDC, Base Sepolia (eip155:84532)
+]);
+
+// The amount a provider's revenue share is computed from. The quote is what we ASKED for; on the
+// x402 lane the facilitator settles exactly the advertised `accepts` amount, which may differ from
+// the catalog quote — so accrue on min(quote, settled) and never on money that was not collected.
+// Other lanes bind the paid amount to the quote at verification time (local_signed) or charge the
+// quote directly (credits / hosted checkout), so the quote is the settled amount there.
+function reconcileProviderSettlementAmount(quote, verification) {
+  const quoted = quote && Number.isFinite(Number(quote.amount_minor)) ? Math.max(0, Math.round(Number(quote.amount_minor))) : 0;
+  const mode = verification && typeof verification.verification_mode === "string" ? verification.verification_mode : null;
+  if (mode !== "x402_facilitator") {
+    return { amount_minor: quoted, quoted_minor: quoted, settled_minor: null, settlement_basis: mode ? `${mode}_quote` : "quote", reconciled: true };
+  }
+  const paymentPayload = (verification && verification.payment_payload) || {};
+  const decimals = X402_ASSET_DECIMALS.get(String(paymentPayload.x402_asset || "").toLowerCase());
+  const baseUnits = /^\d{1,30}$/.test(String(paymentPayload.x402_amount)) ? Number(paymentPayload.x402_amount) : NaN;
+  const centsCurrency = /^USD(_CENTS)?$/i.test(String((quote && quote.currency) || "USD_CENTS"));
+  if (decimals === undefined || !Number.isFinite(baseUnits) || !centsCurrency) {
+    return { amount_minor: 0, quoted_minor: quoted, settled_minor: null, settlement_basis: "x402_unreconciled_asset", reconciled: false };
+  }
+  const settledCents = Math.floor(baseUnits / Math.pow(10, decimals - 2));
+  return { amount_minor: Math.min(quoted, settledCents), quoted_minor: quoted, settled_minor: settledCents, settlement_basis: "x402_settled_min_quote", reconciled: true };
+}
+
 // Records the provider revenue-share split for a settled call routed to a registered
 // provider. Fail-safe: metering must NEVER break or reverse a settled/charged response.
-function attributeProviderSettlement(state, externalExecutionOptions, payload, quote, extra) {
+function attributeProviderSettlement(state, externalExecutionOptions, payload, quote, extra, verification) {
   const execution = externalExecutionOptions && externalExecutionOptions.externalExecution;
   const providerId = execution && execution.registered_provider_id;
   if (!providerId) return;
@@ -149,9 +208,14 @@ function attributeProviderSettlement(state, externalExecutionOptions, payload, q
     const taskRef = (payload && payload.task_ref)
       || (Array.isArray(payload && payload.tasks) && payload.tasks[0] && payload.tasks[0].task_ref)
       || null;
+    const reconciled = reconcileProviderSettlementAmount(quote, verification);
     recordProviderSettlement(state, {
       provider_id: providerId,
-      amount_minor: quote && Number.isFinite(Number(quote.amount_minor)) ? Number(quote.amount_minor) : 0,
+      amount_minor: reconciled.amount_minor,
+      quoted_minor: reconciled.quoted_minor,
+      settled_minor: reconciled.settled_minor,
+      settlement_basis: reconciled.settlement_basis,
+      reconciled: reconciled.reconciled,
       currency: quote && quote.currency ? quote.currency : null,
       transaction_id: (extra && extra.transaction_id) || (quote && quote.quote_id) || null,
       settlement_ref: (extra && extra.settlement_ref) || null,
@@ -299,7 +363,7 @@ async function executeCommandRequest(state, payload, headers, options) {
         };
         attributeProviderSettlement(state, externalExecutionOptions, payload, quote, {
           transaction_id: creditSpend.credit_spend.credit_spend_id
-        });
+        }, paymentVerification);
         return {
           status: 200,
           payload: createCommandResult(state, {
@@ -486,7 +550,7 @@ async function executeCommandRequest(state, payload, headers, options) {
 
     attributeProviderSettlement(state, externalExecutionOptions, payload, quote, {
       settlement_ref: (settledVerification.settlement && (settledVerification.settlement.transaction || settledVerification.settlement.txid)) || null
-    });
+    }, settledVerification);
     return {
       status: 200,
       payload: createCommandResult(state, payload, quote, {
@@ -544,7 +608,7 @@ async function executeAuthorizedCommandRequest(state, payload, authorizationCont
     };
   }
 
-  attributeProviderSettlement(state, externalExecutionOptions, payload, quote);
+  attributeProviderSettlement(state, externalExecutionOptions, payload, quote, undefined, paymentVerification);
   return {
     status: 200,
     payload: createCommandResult(state, payload, quote, {
@@ -557,5 +621,7 @@ async function executeAuthorizedCommandRequest(state, payload, authorizationCont
 module.exports = {
   executeAuthorizedCommandRequest,
   executeCommandRequest,
-  buildExternalExecutionOptions
+  buildExternalExecutionOptions,
+  reconcileProviderSettlementAmount,
+  sanitizeAuthorizationContextForProvider
 };

package/lib/external_execution_policy.js

@@ -0,0 +1,143 @@
+"use strict";
+
+const dns = require("dns").promises;
+const net = require("net");
+
+// Upper bound on a single provider call. The x402 (EIP-3009) authorization a buyer signs is valid
+// for roughly a minute, so a provider allowed to run longer than this could do real work for a
+// payment that then fails to settle (nobody pays). Applies to env targets and registered providers.
+const MAX_TARGET_TIMEOUT_MS = 30000;
+const DEFAULT_TARGET_TIMEOUT_MS = 10000;
+const MIN_TARGET_TIMEOUT_MS = 500;
+
+// Total wall-clock budget for ONE buyer call across cold-start ride-out retries AND failover
+// candidates, shared so three candidates can never each consume a full window. Kept inside the
+// x402 settlement window (~60s) with headroom for the settle call itself.
+const DEFAULT_EXECUTION_BUDGET_MS = 50000;
+const MAX_EXECUTION_BUDGET_MS = 55000;
+
+function clampTargetTimeoutMs(value) {
+  const n = Number(value || DEFAULT_TARGET_TIMEOUT_MS) || DEFAULT_TARGET_TIMEOUT_MS;
+  return Math.min(MAX_TARGET_TIMEOUT_MS, Math.max(MIN_TARGET_TIMEOUT_MS, Math.round(n)));
+}
+
+function externalExecutionBudgetMs() {
+  const raw = process.env.XYTARA_EXTERNAL_EXECUTION_BUDGET_MS;
+  if (raw === undefined || raw === "") return DEFAULT_EXECUTION_BUDGET_MS;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_EXECUTION_BUDGET_MS;
+  return Math.min(MAX_EXECUTION_BUDGET_MS, Math.max(1000, Math.round(n)));
+}
+
+// Endpoint policy. "strict" (default on a hosted deploy, i.e. when RENDER is set) requires https
+// and refuses endpoints at loopback / private / link-local / metadata addresses, so a registered
+// provider cannot turn the runtime into a request proxy into its own network (SSRF). "permissive"
+// (default locally) keeps http://127.0.0.1-style endpoints usable for tests and development.
+function endpointPolicyMode() {
+  const raw = String(process.env.XYTARA_PROVIDER_ENDPOINT_POLICY || "").trim().toLowerCase();
+  if (raw === "strict" || raw === "permissive") return raw;
+  return process.env.RENDER ? "strict" : "permissive";
+}
+
+function isPrivateIp(ip) {
+  const family = net.isIP(ip);
+  if (family === 4) {
+    const p = ip.split(".").map(Number);
+    if (p[0] === 10 || p[0] === 127 || p[0] === 0) return true;
+    if (p[0] === 169 && p[1] === 254) return true;              // link-local + cloud metadata
+    if (p[0] === 172 && p[1] >= 16 && p[1] <= 31) return true;
+    if (p[0] === 192 && p[1] === 168) return true;
+    if (p[0] === 100 && p[1] >= 64 && p[1] <= 127) return true; // carrier-grade NAT
+    if (p[0] >= 224) return true;                                // multicast / reserved / broadcast
+    return false;
+  }
+  if (family === 6) {
+    const lower = ip.toLowerCase();
+    if (lower === "::" || lower === "::1") return true;
+    if (lower.startsWith("fe80:") || lower.startsWith("fc") || lower.startsWith("fd")) return true; // link-local, ULA
+    if (lower.startsWith("::ffff:")) return isPrivateIp(lower.slice(7));                            // v4-mapped
+    if (lower.startsWith("ff")) return true;                                                        // multicast
+    return false;
+  }
+  return false;
+}
+
+function isBlockedHostname(hostname) {
+  const h = String(hostname || "").toLowerCase().replace(/\.$/, "");
+  if (!h || h === "localhost" || h.endsWith(".localhost")) return true;
+  if (h.endsWith(".local") || h.endsWith(".internal") || h.endsWith(".localdomain")) return true;
+  if (h === "metadata" || h === "metadata.google.internal") return true;
+  return false;
+}
+
+function hostOf(parsedUrl) {
+  return String(parsedUrl.hostname || "").replace(/^\[|\]$/g, "");
+}
+
+// Synchronous shape check (used at registration): protocol + literal-host rules. No DNS here.
+function checkEndpointUrlShape(endpointUrl) {
+  const policy = endpointPolicyMode();
+  let parsed;
+  try {
+    parsed = new URL(String(endpointUrl || ""));
+  } catch (_) {
+    return { ok: false, reason: "endpoint_url_invalid", policy };
+  }
+  if (parsed.username || parsed.password) {
+    return { ok: false, reason: "endpoint_url_credentials_not_allowed", policy };
+  }
+  if (policy !== "strict") return { ok: true, policy };
+  if (parsed.protocol !== "https:") {
+    return { ok: false, reason: "endpoint_url_insecure", detail: "https:// is required for provider endpoints", policy };
+  }
+  const host = hostOf(parsed);
+  if (isBlockedHostname(host) || (net.isIP(host) && isPrivateIp(host))) {
+    return { ok: false, reason: "endpoint_url_not_public", detail: "loopback, private, link-local and metadata hosts are refused", policy };
+  }
+  return { ok: true, policy };
+}
+
+// Dispatch-time check: re-validates the shape AND resolves the host, refusing any address in a
+// private range (defeats DNS rebinding to an internal address after registration). Results are
+// cached briefly so the hot path adds at most one lookup per host per minute.
+const resolveCache = new Map();
+const RESOLVE_CACHE_TTL_MS = 60000;
+
+async function checkEndpointBeforeDispatch(endpointUrl) {
+  const shape = checkEndpointUrlShape(endpointUrl);
+  if (!shape.ok || shape.policy !== "strict") return shape;
+  let host;
+  try {
+    host = hostOf(new URL(String(endpointUrl)));
+  } catch (_) {
+    return { ok: false, reason: "endpoint_url_invalid", policy: shape.policy };
+  }
+  if (net.isIP(host)) return shape; // literal already checked above
+  const cached = resolveCache.get(host);
+  if (cached && cached.expires_at > Date.now()) return cached.result;
+  let result;
+  try {
+    const addresses = await dns.lookup(host, { all: true, verbatim: true });
+    const bad = addresses.find((entry) => isPrivateIp(entry.address));
+    result = bad
+      ? { ok: false, reason: "endpoint_url_not_public", detail: "endpoint resolves to a non-public address", policy: shape.policy }
+      : { ok: true, policy: shape.policy };
+  } catch (_) {
+    // Unresolvable host: let the fetch surface ENOTFOUND (a not-processed, failover-safe signal).
+    result = { ok: true, policy: shape.policy, unresolved: true };
+  }
+  resolveCache.set(host, { result, expires_at: Date.now() + RESOLVE_CACHE_TTL_MS });
+  return result;
+}
+
+module.exports = {
+  MAX_TARGET_TIMEOUT_MS,
+  DEFAULT_TARGET_TIMEOUT_MS,
+  DEFAULT_EXECUTION_BUDGET_MS,
+  clampTargetTimeoutMs,
+  externalExecutionBudgetMs,
+  endpointPolicyMode,
+  isPrivateIp,
+  checkEndpointUrlShape,
+  checkEndpointBeforeDispatch
+};