xytara 3.1.10 → 3.1.11

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,11 @@
-`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.11 hardens the open provider network's money ledger and the hosted executor, and tightens repository hygiene. No API is removed; the public provider directory now lists active providers only.
 
 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.
+- **Settled-amount reconciliation** — a provider's revenue share accrues on min(quote, the amount actually settled on-chain) for x402 calls; an unrecognised settlement asset accrues nothing and is flagged. Every ledger row records its settlement basis (quoted vs. settled).
+- **Registration-scoped ledgers** — ledger rows and payouts belong to one registration of a `provider_id`. A removed and re-registered id never sees, inherits, or is credited by a previous owner's rows, and removal cancels that registration's pending payouts.
+- **In-flight payout guard** — a payout being sent by the external signer cannot be cancelled mid-dispatch (so no freed reservation can ever be re-sent); a payout cancelled before a late tx report is reinstated for reconciliation instead of being lost.
+- **One execution budget per call** — cold-start ride-out retries and failover candidates share a single wall-clock budget inside the x402 authorization window, and per-target timeouts are capped at 30s, so a routed call can always still settle.
+- **Provider endpoint policy** — on hosted deploys, provider endpoints must be public `https` (loopback, private, link-local and metadata hosts are refused and re-checked by DNS at dispatch); redirects are never followed. Providers receive only a sanitized payment context — never the buyer's signed authorization.
+- The MCP executor's bearer check is timing-safe and fails closed on a hosted deploy; adapter execution truth counts only enabled targets; rate-limit identity compares are timing-safe.
+- Repository hygiene: a complete `.gitignore`, the publish workflow waits for the live deploy before registry publication, and `.env.example` documents every runtime knob.

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
+};

package/lib/external_execution_runtime.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const { buildFetchOptionsForPurpose } = require("./network_transport");
+const { clampTargetTimeoutMs, checkEndpointBeforeDispatch } = require("./external_execution_policy");
 
 function normalizeString(value, fallback = "") {
   const raw = typeof value === "string" ? value.trim() : "";
@@ -35,7 +36,7 @@ function loadExecutionTargetRegistry() {
         integration_id: normalizeString(item.integration_id) || null,
         provider: normalizeString(item.provider, "external_execution"),
         auth_token: normalizeString(item.auth_token) || null,
-        timeout_ms: Math.max(500, Number(item.timeout_ms || 10000) || 10000),
+        timeout_ms: clampTargetTimeoutMs(item.timeout_ms),
         enabled: item.enabled !== false
       };
     })
@@ -95,9 +96,9 @@ function executionRetryDelayMs(attempt, retryAfterHeader) {
   return Math.min(500 * Math.pow(2, attempt), 5000); // 500ms, 1000, 2000, 4000, cap 5000
 }
 
-async function executeExternalTargetOnce(target, body) {
+async function executeExternalTargetOnce(target, body, timeoutMs) {
   const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), target.timeout_ms);
+  const timer = setTimeout(() => controller.abort(), Math.max(1, Number(timeoutMs) || target.timeout_ms));
   try {
     const response = await fetch(target.endpoint_url, {
       method: "POST",
@@ -107,6 +108,9 @@ async function executeExternalTargetOnce(target, body) {
       },
       body,
       signal: controller.signal,
+      // Never follow a redirect: a provider must not be able to bounce the call (and its bearer)
+      // to another host, including an internal one.
+      redirect: "error",
       ...buildFetchOptionsForPurpose("external_execution")
     });
     const text = await response.text();
@@ -118,8 +122,39 @@ async function executeExternalTargetOnce(target, body) {
   }
 }
 
-async function executeExternalTarget(target, payload, quote, authorizationContext) {
+async function executeExternalTarget(target, payload, quote, authorizationContext, options) {
   if (!target) return null;
+  const opts = ensureObject(options);
+  // One shared wall-clock budget for the WHOLE buyer call (every retry of every failover
+  // candidate), set by the caller so three candidates can never each burn a full ride-out window
+  // and push settlement past the x402 authorization expiry. Absent (direct callers) -> only the
+  // ride-out window below bounds this call.
+  const budgetDeadline = Number.isFinite(Number(opts.deadline_ms)) ? Number(opts.deadline_ms) : null;
+  const budgetExhausted = (attempts) => ({
+    ok: false,
+    status: 504,
+    reason: "external_execution_budget_exhausted",
+    provider: target.provider,
+    target_id: target.target_id,
+    failover_safe: false, // nothing left to spend on another candidate either
+    attempts
+  });
+  if (budgetDeadline !== null && Date.now() >= budgetDeadline) return budgetExhausted(0);
+  // Dispatch-time endpoint policy (strict on hosted deploys): refused BEFORE anything is sent, so
+  // this is a not-processed failure and failing over to the next candidate is safe.
+  const endpointCheck = await checkEndpointBeforeDispatch(target.endpoint_url);
+  if (!endpointCheck.ok) {
+    return {
+      ok: false,
+      status: 502,
+      reason: "external_execution_endpoint_rejected",
+      details: endpointCheck.reason,
+      provider: target.provider,
+      target_id: target.target_id,
+      failover_safe: true,
+      attempts: 0
+    };
+  }
   const body = JSON.stringify({
     command: payload && payload.command ? payload.command : "command.execute",
     task_ref: payload && payload.task_ref ? payload.task_ref : null,
@@ -143,17 +178,22 @@ async function executeExternalTarget(target, payload, quote, authorizationContex
     ? Math.max(0, Math.min(39, Number(process.env.XYTARA_EXTERNAL_EXECUTION_MAX_RETRIES) || 0))
     : 29;
   const maxAttempts = maxRetries + 1;
-  const deadline = Date.now() + retryWindowMs;
+  const rideOutDeadline = Date.now() + retryWindowMs;
+  const deadline = budgetDeadline !== null ? Math.min(rideOutDeadline, budgetDeadline) : rideOutDeadline;
+  const remainingBudgetMs = () => (budgetDeadline !== null ? budgetDeadline - Date.now() : Infinity);
+  // A retry sleep never runs past the deadline, and a single attempt never outlives the budget.
+  const boundedSleep = (ms) => sleep(Math.max(0, Math.min(ms, deadline - Date.now())));
 
   for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    if (remainingBudgetMs() <= 0) return budgetExhausted(attempt);
     try {
-      const r = await executeExternalTargetOnce(target, body);
+      const r = await executeExternalTargetOnce(target, body, Math.min(target.timeout_ms, remainingBudgetMs()));
       if (r.ok) {
         return { ok: true, provider: target.provider, target_id: target.target_id, target_response: r.parsed || null };
       }
       // Retry only a provider-rejected (not-processed) status, while the ride-out budget lasts.
       if (RETRYABLE_EXECUTION_STATUS.has(r.status) && Date.now() < deadline && attempt + 1 < maxAttempts) {
-        await sleep(executionRetryDelayMs(attempt, r.retry_after));
+        await boundedSleep(executionRetryDelayMs(attempt, r.retry_after));
         continue;
       }
       return {
@@ -173,7 +213,7 @@ async function executeExternalTarget(target, payload, quote, authorizationContex
       // -> not processed -> safe to ride out too. A timeout or mid-stream reset is AMBIGUOUS -> stop.
       const notProcessed = !isAbort && NOT_PROCESSED_NET_CODES.has(connectErrorCode(error));
       if (notProcessed && Date.now() < deadline && attempt + 1 < maxAttempts) {
-        await sleep(executionRetryDelayMs(attempt, null));
+        await boundedSleep(executionRetryDelayMs(attempt, null));
         continue;
       }
       return {

package/lib/provider_network_contract.js

@@ -31,7 +31,7 @@ function buildProviderNetworkContract() {
       "3. An OPERATOR activates it (status:'active').",
       "4. When a buyer pays (x402) for a capability you serve, the runtime POSTs the job to your endpoint_url; you execute and return the deliverable.",
       "5. On your success the payment settles on-chain and your revenue_share accrues.",
-      "6. The operator pays out your accrued balance to your payout_address (manually or via a signer)."
+      "6. The operator pays out your accrued balance to your payout_address (manually or via a signer). Track it yourself any time via GET /providers/<id>/earnings with your owner_secret."
     ],
 
     registration: {
@@ -82,9 +82,11 @@ function buildProviderNetworkContract() {
           body: "object — the buyer's input, e.g. { tool_name, arguments }",
           account_id: "string — the buyer's account ref",
           quote: "object — the priced quote for this call",
-          authorization_context: "object — payment/authorization context"
+          authorization_context: "object — SANITIZED payment context: { ok, verification_mode, wallet_id, age_seconds, payment_payload (scalar facts only) }. Never the buyer's signed authorization, signatures, or settlement material."
         }
       },
+      endpoint_policy: "endpoint_url must be https and publicly routable on the hosted network (loopback, private, link-local and metadata hosts are refused, re-checked by DNS at dispatch); URLs with embedded credentials are refused; redirects are never followed.",
+      execution_budget: "One buyer call has a total wall-clock budget (default 50s, inside the x402 authorization window) shared across ride-out retries and failover; your timeout_ms is capped at 30000 ms. Finish well inside it — a call that outlives the authorization cannot settle.",
       response: {
         on_success: "Return HTTP 2xx with the deliverable. The runtime surfaces your output from result.output OR a top-level output_payload / output_ref.",
         example_success_bodies: [
@@ -108,8 +110,9 @@ function buildProviderNetworkContract() {
         unhealthy_cooldown_ms: intEnv("XYTARA_PROVIDER_UNHEALTHY_COOLDOWN_MS", 60000)
       },
       reputation: {
-        description: "The runtime tracks your lifetime success rate and prefers higher-reputation providers within the healthy tier. New providers get an optimistic score (a fair first shot); one early failure is recoverable (not disqualifying).",
-        routing_score: "(success + 2) / (success + failure + 2)"
+        description: "The runtime tracks your lifetime success rate and prefers higher-reputation providers within the healthy tier. New providers get an optimistic score (a fair first shot); one early failure is recoverable (not disqualifying). The operator may enable recency decay so recent performance outweighs stale history (your raw lifetime counts are still shown either way).",
+        routing_score: "(success + 2) / (success + failure + 2)",
+        recency_decay: intEnv("XYTARA_PROVIDER_REPUTATION_DECAY", 1)
       },
       failover_max_candidates: intEnv("XYTARA_PROVIDER_FAILOVER_MAX", 3),
       note: "Operator-pinned execution targets (if any) take precedence over the registry for a given capability."
@@ -117,13 +120,15 @@ function buildProviderNetworkContract() {
 
     economics: {
       settlement: "Buyers pay via x402 (gasless USDC on Base). The runtime settles on-chain only AFTER your execution succeeds — a failed call does not charge the buyer.",
-      revenue_share: "Your provider_share = floor(settled_amount * revenue_share_bps / 10000); the platform keeps the remainder (incl. rounding).",
-      payouts: "Your accrued share is paid to your payout_address by the operator (reconciled ledger: create -> on-chain send -> confirm). Amounts are tracked in the quote's minor unit (USD_CENTS)."
+      revenue_share: "Your provider_share = floor(settled_amount * revenue_share_bps / 10000); the platform keeps the remainder (incl. rounding). settled_amount = min(quote, the amount actually settled on-chain for the call) — never money that was not collected; each ledger row records its settlement_basis.",
+      payouts: "Your accrued share is paid to your payout_address by the operator (reconciled ledger: create -> on-chain send -> confirm). Amounts are tracked in the quote's minor unit (USD_CENTS). Ledger rows and payouts are scoped to your registration: a removed-and-re-registered provider_id starts a fresh ledger and never inherits another owner's rows."
     },
 
     discovery: {
-      list: "GET /v1/provider-network/providers — public; shows each provider's capabilities, status, health, and reputation (never secrets).",
-      self: "GET /v1/provider-network/providers/<provider_id> — your public record."
+      list: "GET /v1/provider-network/providers — public; lists ACTIVE (vetted) providers with capabilities, status, health, and reputation (never secrets). Pending/suspended records are visible to the operator only.",
+      self: "GET /v1/provider-network/providers/<provider_id> — your public record.",
+      earnings:
+        "GET /v1/provider-network/providers/<provider_id>/earnings — your OWN earnings (read-only): payout_state (accrued/paid/pending/available/owed), your settlement rows, and your payout history. Authenticate with YOUR owner_secret via the 'x-provider-owner-secret' header (or Authorization: Bearer <owner_secret>) — this is the provider side, it needs no operator bearer."
     },
 
     operator_gated: [
@@ -133,7 +138,7 @@ function buildProviderNetworkContract() {
     ],
 
     guidance: [
-      "Be idempotent per request — retries and failover can re-send a provably-not-processed job.",
+      "Be idempotent per request — key on quote.quote_id (unique per buyer call): retries and failover can re-send a provably-not-processed job, and some proxies return 503 after forwarding a request.",
       "Be reliable — health and reputation gate your routing and ordering.",
       "Return a 429 with Retry-After when overloaded (it is treated as 'did not process' and is safely retried)."
     ]