uvd-x402-sdk 2.99.1 → 2.100.0

package/README.md

@@ -861,6 +861,16 @@ app.post('/api/premium', async (req, res) => {
 
 `createPaymentMiddleware()` and `createHonoMiddleware()` verify and settle automatically by default (`before-handler`). Use `settlementStrategy: 'manual'` if you need to control when settlement happens (e.g., settle only after confirming you can fulfill the request).
 
+### Stack key (services run by Ultravioleta DAO)
+
+Services run by Ultravioleta DAO carry a per-service credential, the stack key, so that the facilitator's rate-limit policy does not answer them `429`. Everything in this SDK that calls the facilitator sends it as `X-UVD-Stack-Key`: the clients `FacilitatorClient` (and the two middlewares), `Erc8004Client`, `BazaarClient`, `EscrowClient` and `AdvancedEscrowClient`, and the functions `anchorEvidence`, `availableBackends`, `streamTrafficEvents` and `getFacilitatorReceipt`, which take the same `stackKey` / `stackKeyHosts` options. It changes nothing else about a payment, and a facilitator that does not know the header ignores it.
+
+- **Where it comes from:** the facilitator's operator issues one per service: `uvdsk_` followed by 43-128 base64url characters. The process receives it as `UVD_STACK_KEY` (read by default) or as the `stackKey` option, from a secret store, never from code.
+- **Not for third parties:** if you integrate this SDK in your own product you have no key and need none. Leave both unset and no header is sent.
+- **Only to a house facilitator:** the key goes over `https://` to `facilitator.ultravioletadao.xyz` and nowhere else, checked on the URL of every request. A request to any other host, or over plain `http://`, carries no header, whether the key came from the option or from `UVD_STACK_KEY`, and warns once, naming the host and never the key. `stackKeyHosts: ['facilitator-staging.example']` ADDS hosts (hostnames only, matched exactly); `facilitator.ultravioletadao.xyz` stays in. Plain `http://` is accepted only for `127.0.0.1` or `localhost`, and only when listed there. `EscrowClient`'s default base URL, `escrow.ultravioletadao.xyz`, is not the facilitator and gets the key only if listed.
+- **The key does not follow redirects:** a redirect answered to a request that carries it fails with `StackKeyRedirectError` (exported), and the key is not sent again. Point the client at the facilitator's final URL.
+- **A bad key never breaks a payment:** one leading BOM (U+FEFF), then spaces, tabs, CR and LF at both ends, are removed, and nothing else. A value that still does not match is not sent: the client warns once, without the value, and pays like any other client. The key never appears in a result, an error, a log line or a printed client.
+
 ## React
 
 ```tsx

package/dist/adapters/index.d.mts

@@ -1,4 +1,4 @@
-import { X as X402Version, a as PaymentResult } from '../index-D8JpL_D5.mjs';
+import { X as X402Version, a as PaymentResult } from '../index-DagQ74ZQ.mjs';
 export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-Z9v4GxOZ.mjs';
 import '../wallet-w7BnImDG.mjs';
 

package/dist/adapters/index.d.ts

@@ -1,4 +1,4 @@
-import { X as X402Version, a as PaymentResult } from '../index-D8JpL_D5.js';
+import { X as X402Version, a as PaymentResult } from '../index-DagQ74ZQ.js';
 export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-C-KmORG9.js';
 import '../wallet-w7BnImDG.js';
 

package/dist/backend/index.d.mts

@@ -1,4 +1,4 @@
 import '../wallet-w7BnImDG.mjs';
-export { a as FacilitatorReceipt, F as FetchReceiptResult, P as PaymentState, b as PurchaseContext, c as RECEIPT_ISSUER, R as ReceiptFetchOptions, d as ReceiptKeys, e as canonicalReceiptJson, f as createPurchaseContext, g as fetchWithReceipt, h as getFacilitatorReceipt, m as mergeHeaderList, i as mergePaymentResponseHeaders, p as parseFacilitatorReceipt, j as paymentResponseHeaders, k as purchaseContextHeader, r as receiptCommitment, l as receiptFromErrorBody, n as receiptFromResponse, v as validatePurchaseContext, o as verifyFacilitatorReceipt } from '../receipts-hnXkpEYi.mjs';
-import '../index-D8JpL_D5.mjs';
-export { A as AMBIGUOUS_LEASE_REASONS, a as AUTHORIZATION_ALREADY_SETTLED, b as AUTHORIZATION_IN_FLIGHT, c as AdmittedAuthorizationCode, ap as AdvancedAuthorizationResult, aq as AdvancedEscrowClient, ar as AdvancedEscrowClientOptions, as as AdvancedEscrowContracts, at as AdvancedEscrowTaskTier, au as AdvancedPaymentInfo, av as AdvancedTransactionResult, aw as AgentId, ax as AgentIdentity, ay as AgentRegistration, az as AgentRegistrationFile, aA as AgentService, aB as AtomStats, aC as BASE_MAINNET_CONTRACTS, aD as BazaarClient, aE as BazaarClientOptions, aF as BazaarDiscoverOptions, aG as BazaarDiscoverResponse, aH as BazaarRegisterOptions, aI as BazaarResource, aJ as CreateEscrowOptions, D as DEFAULT_FACILITATOR_RETRIES, d as DEFAULT_RETRY_AFTER_SECONDS, aK as DEPOSIT_LIMIT_USDC, aL as DiscoveryAccepts, aM as DiscoveryCuration, aN as DiscoveryHealth, aO as DiscoveryHealthStatus, aP as DiscoveryListOptions, aQ as DiscoveryPagination, aR as DiscoveryRegisterOptions, aS as DiscoveryResource, aT as DiscoveryResponse, aU as DiscoverySource, aV as DiscoveryStats, aW as DiscoveryTier, aX as Dispute, aY as DisputeOutcome, aZ as ERC8004_CONTRACTS, a_ as ERC8004_EXTENSION_ID, a$ as ESCROW_CONTRACTS, b0 as ESCROW_NOTHING_TO_VOID, b1 as ESCROW_OPERATOR_GENERATION, b2 as ESCROW_OPERATOR_NOT_DEPLOYED, b3 as ESCROW_TIMEOUT_MS, b4 as ESCROW_UNSUPPORTED_ON_GENERATION, b5 as ESCROW_VOID_AMOUNT_MISMATCH, b6 as Erc8004Client, b7 as Erc8004ClientOptions, b8 as Erc8004LookupError, b9 as Erc8004Network, ba as EscrowClient, bb as EscrowClientOptions, bc as EscrowOperatorGeneration, bd as EscrowPayment, be as EscrowStateResponse, bf as EscrowStatus, F as FacilitatorCallOptions, e as FacilitatorClient, f as FacilitatorClientOptions, g as FacilitatorErrorInfo, h as FacilitatorFailureFields, i as FacilitatorFetchOptions, bg as FeedbackEntry, bh as FeedbackParams, bi as FeedbackRequest, bj as FeedbackResponse, bk as HEALTH_FILTERS, H as HonoMiddlewareOptions, I as IDEMPOTENCY_KEY_HEADER, j as IDEMPOTENT_REPLAYED_HEADER, bl as IdentityByOwnerResponse, bm as IdentityMetadataResponse, bn as IdentityTotalSupplyResponse, bo as LifecycleAuthOptions, M as MAX_RETRY_AFTER_SECONDS, bp as MAX_SEARCH_LEN, bq as MetadataEntryParam, br as OPERATOR_ABI, bs as OPERATOR_ABI_CREATE3, bt as OPERATOR_ABI_V3, bu as PAYMENT_INFO_TYPEHASH, P as ParsedFacilitatorErrorBody, v as PaymentAcceptance, w as PaymentConflictResponse, x as PaymentMiddlewareOptions, y as PaymentPayloadV2, bv as PaymentRequirementResolver, bw as PaymentRequirements, bx as PaymentRequirementsOptions, z as PaymentRequirementsV2, by as PrepareRelayFeedbackRequest, bz as PrepareRelayFeedbackResponse, bA as PrepareRelayResponseRequest, bB as PrepareSolanaFeedbackRequest, bC as PrepareSolanaFeedbackResponse, bD as ProofOfPayment, R as RECEIPT_REQUEST_CONFLICT, bE as RELAYED_FEEDBACK_NETWORKS, C as REPLAYABLE_LEASE_REASONS, bF as RefundRequest, bG as RefundStatus, bH as RegisterAgentRequest, bI as RegisterAgentResponse, bJ as RegisterJobResponse, bK as RegisterJobStatus, bL as RegistrationPendingError, bM as RelayAuthorizationParams, bN as ReputationResponse, bO as ReputationSummary, bP as RequestRefundOptions, E as ResourceInfoV2, S as SETTLEMENT_UNCONFIRMED, bQ as SOLANA_FEEDBACK_NETWORKS, bR as SettleRequest, G as SettleRequestV2, J as SettleResponse, bS as SettleResponseWithProof, bT as SubmitRelayFeedbackRequest, bU as SubmitRelayResponseRequest, bV as SubmitSolanaFeedbackRequest, bW as TIER_FILTERS, bX as TIER_TIMINGS, bY as USDC_DOMAIN_NAME, bZ as UnavailableBody, b_ as UnavailableResponse, V as VerifiedPaymentState, b$ as VerifyRequest, K as VerifyRequestV2, N as VerifyResponse, W as WRITER_LEASE_REASONS, Q as WriterLeaseReason, X as X402_CORS_HEADERS, T as X402_HEADER_NAMES, c0 as ZERO_ADDRESS, c1 as buildErc8004PaymentRequirements, Z as buildPaymentConflictResponse, _ as buildPaymentRequirements, $ as buildSettleRequest, a0 as buildSettleRequestForVersion, a1 as buildSettleRequestV2, c2 as buildUnavailableResponse, a2 as buildVerifyRequest, a3 as buildVerifyRequestForVersion, a4 as buildVerifyRequestV2, c3 as canRefundEscrow, c4 as canReleaseEscrow, c5 as carryFailureFields, a5 as create402Response, a6 as createHonoMiddleware, a7 as createIdempotencyKey, a8 as createPaymentMiddleware, c6 as epochToDate, c7 as escrowTimeRemaining, a9 as extractPaymentFromHeaders, aa as facilitatorFetch, ab as getCorsHeaders, c8 as getEscrowContractsByChainId, c9 as getEscrowOperatorGeneration, ca as getEscrowSupportedChainIds, cb as isAlive, ac as isAmbiguousLeaseReason, ad as isAuthorizationAlreadyUsed, ae as isAuthorizationInFlight, cc as isEscrowExpired, cd as isEscrowSupportedOnChain, ce as isRegisterJobTerminal, af as isReplayableLeaseReason, ag as isSettlementUnconfirmed, ai as parseFacilitatorErrorBody, cf as parsePaymentHeader, aj as parseRetryAfterSeconds, ak as readFacilitatorError, al as resolveEnvelopeVersion, cg as supportsRelayedFeedback, ch as supportsSolanaFeedback, am as toPaymentRequirementsV2, an as toResourceInfoV2, ci as wireNetwork } from '../index-CnHVH3uK.mjs';
+export { a as FacilitatorReceipt, F as FetchReceiptResult, P as PaymentState, b as PurchaseContext, c as RECEIPT_ISSUER, R as ReceiptFetchOptions, d as ReceiptKeys, e as STACK_KEY_HEADER, S as StackKeyOptions, f as StackKeyRedirectError, g as canonicalReceiptJson, h as createPurchaseContext, i as fetchWithReceipt, j as getFacilitatorReceipt, m as mergeHeaderList, k as mergePaymentResponseHeaders, p as parseFacilitatorReceipt, l as paymentResponseHeaders, n as purchaseContextHeader, r as receiptCommitment, o as receiptFromErrorBody, q as receiptFromResponse, v as validatePurchaseContext, s as verifyFacilitatorReceipt } from '../receipts-COPJ_BY9.mjs';
+import '../index-DagQ74ZQ.mjs';
+export { A as AMBIGUOUS_LEASE_REASONS, a as AUTHORIZATION_ALREADY_SETTLED, b as AUTHORIZATION_IN_FLIGHT, c as AdmittedAuthorizationCode, ap as AdvancedAuthorizationResult, aq as AdvancedEscrowClient, ar as AdvancedEscrowClientOptions, as as AdvancedEscrowContracts, at as AdvancedEscrowTaskTier, au as AdvancedPaymentInfo, av as AdvancedTransactionResult, aw as AgentId, ax as AgentIdentity, ay as AgentRegistration, az as AgentRegistrationFile, aA as AgentService, aB as AtomStats, aC as BASE_MAINNET_CONTRACTS, aD as BazaarClient, aE as BazaarClientOptions, aF as BazaarDiscoverOptions, aG as BazaarDiscoverResponse, aH as BazaarRegisterOptions, aI as BazaarResource, aJ as CreateEscrowOptions, D as DEFAULT_FACILITATOR_RETRIES, d as DEFAULT_RETRY_AFTER_SECONDS, aK as DEPOSIT_LIMIT_USDC, aL as DiscoveryAccepts, aM as DiscoveryCuration, aN as DiscoveryHealth, aO as DiscoveryHealthStatus, aP as DiscoveryListOptions, aQ as DiscoveryPagination, aR as DiscoveryRegisterOptions, aS as DiscoveryResource, aT as DiscoveryResponse, aU as DiscoverySource, aV as DiscoveryStats, aW as DiscoveryTier, aX as Dispute, aY as DisputeOutcome, aZ as ERC8004_CONTRACTS, a_ as ERC8004_EXTENSION_ID, a$ as ESCROW_CONTRACTS, b0 as ESCROW_NOTHING_TO_VOID, b1 as ESCROW_OPERATOR_GENERATION, b2 as ESCROW_OPERATOR_NOT_DEPLOYED, b3 as ESCROW_TIMEOUT_MS, b4 as ESCROW_UNSUPPORTED_ON_GENERATION, b5 as ESCROW_VOID_AMOUNT_MISMATCH, b6 as Erc8004Client, b7 as Erc8004ClientOptions, b8 as Erc8004LookupError, b9 as Erc8004Network, ba as EscrowClient, bb as EscrowClientOptions, bc as EscrowOperatorGeneration, bd as EscrowPayment, be as EscrowStateResponse, bf as EscrowStatus, F as FacilitatorCallOptions, e as FacilitatorClient, f as FacilitatorClientOptions, g as FacilitatorErrorInfo, h as FacilitatorFailureFields, i as FacilitatorFetchOptions, bg as FeedbackEntry, bh as FeedbackParams, bi as FeedbackRequest, bj as FeedbackResponse, bk as HEALTH_FILTERS, H as HonoMiddlewareOptions, I as IDEMPOTENCY_KEY_HEADER, j as IDEMPOTENT_REPLAYED_HEADER, bl as IdentityByOwnerResponse, bm as IdentityMetadataResponse, bn as IdentityTotalSupplyResponse, bo as LifecycleAuthOptions, M as MAX_RETRY_AFTER_SECONDS, bp as MAX_SEARCH_LEN, bq as MetadataEntryParam, br as OPERATOR_ABI, bs as OPERATOR_ABI_CREATE3, bt as OPERATOR_ABI_V3, bu as PAYMENT_INFO_TYPEHASH, P as ParsedFacilitatorErrorBody, v as PaymentAcceptance, w as PaymentConflictResponse, x as PaymentMiddlewareOptions, y as PaymentPayloadV2, bv as PaymentRequirementResolver, bw as PaymentRequirements, bx as PaymentRequirementsOptions, z as PaymentRequirementsV2, by as PrepareRelayFeedbackRequest, bz as PrepareRelayFeedbackResponse, bA as PrepareRelayResponseRequest, bB as PrepareSolanaFeedbackRequest, bC as PrepareSolanaFeedbackResponse, bD as ProofOfPayment, R as RECEIPT_REQUEST_CONFLICT, bE as RELAYED_FEEDBACK_NETWORKS, C as REPLAYABLE_LEASE_REASONS, bF as RefundRequest, bG as RefundStatus, bH as RegisterAgentRequest, bI as RegisterAgentResponse, bJ as RegisterJobResponse, bK as RegisterJobStatus, bL as RegistrationPendingError, bM as RelayAuthorizationParams, bN as ReputationResponse, bO as ReputationSummary, bP as RequestRefundOptions, E as ResourceInfoV2, S as SETTLEMENT_UNCONFIRMED, bQ as SOLANA_FEEDBACK_NETWORKS, bR as SettleRequest, G as SettleRequestV2, J as SettleResponse, bS as SettleResponseWithProof, bT as SubmitRelayFeedbackRequest, bU as SubmitRelayResponseRequest, bV as SubmitSolanaFeedbackRequest, bW as TIER_FILTERS, bX as TIER_TIMINGS, bY as USDC_DOMAIN_NAME, bZ as UnavailableBody, b_ as UnavailableResponse, V as VerifiedPaymentState, b$ as VerifyRequest, K as VerifyRequestV2, N as VerifyResponse, W as WRITER_LEASE_REASONS, Q as WriterLeaseReason, X as X402_CORS_HEADERS, T as X402_HEADER_NAMES, c0 as ZERO_ADDRESS, c1 as buildErc8004PaymentRequirements, Z as buildPaymentConflictResponse, _ as buildPaymentRequirements, $ as buildSettleRequest, a0 as buildSettleRequestForVersion, a1 as buildSettleRequestV2, c2 as buildUnavailableResponse, a2 as buildVerifyRequest, a3 as buildVerifyRequestForVersion, a4 as buildVerifyRequestV2, c3 as canRefundEscrow, c4 as canReleaseEscrow, c5 as carryFailureFields, a5 as create402Response, a6 as createHonoMiddleware, a7 as createIdempotencyKey, a8 as createPaymentMiddleware, c6 as epochToDate, c7 as escrowTimeRemaining, a9 as extractPaymentFromHeaders, aa as facilitatorFetch, ab as getCorsHeaders, c8 as getEscrowContractsByChainId, c9 as getEscrowOperatorGeneration, ca as getEscrowSupportedChainIds, cb as isAlive, ac as isAmbiguousLeaseReason, ad as isAuthorizationAlreadyUsed, ae as isAuthorizationInFlight, cc as isEscrowExpired, cd as isEscrowSupportedOnChain, ce as isRegisterJobTerminal, af as isReplayableLeaseReason, ag as isSettlementUnconfirmed, ai as parseFacilitatorErrorBody, cf as parsePaymentHeader, aj as parseRetryAfterSeconds, ak as readFacilitatorError, al as resolveEnvelopeVersion, cg as supportsRelayedFeedback, ch as supportsSolanaFeedback, am as toPaymentRequirementsV2, an as toResourceInfoV2, ci as wireNetwork } from '../index-prkNXpLX.mjs';

package/dist/backend/index.d.ts

@@ -1,4 +1,4 @@
 import '../wallet-w7BnImDG.js';
-export { a as FacilitatorReceipt, F as FetchReceiptResult, P as PaymentState, b as PurchaseContext, c as RECEIPT_ISSUER, R as ReceiptFetchOptions, d as ReceiptKeys, e as canonicalReceiptJson, f as createPurchaseContext, g as fetchWithReceipt, h as getFacilitatorReceipt, m as mergeHeaderList, i as mergePaymentResponseHeaders, p as parseFacilitatorReceipt, j as paymentResponseHeaders, k as purchaseContextHeader, r as receiptCommitment, l as receiptFromErrorBody, n as receiptFromResponse, v as validatePurchaseContext, o as verifyFacilitatorReceipt } from '../receipts-cLnL2c1l.js';
-import '../index-D8JpL_D5.js';
-export { A as AMBIGUOUS_LEASE_REASONS, a as AUTHORIZATION_ALREADY_SETTLED, b as AUTHORIZATION_IN_FLIGHT, c as AdmittedAuthorizationCode, ap as AdvancedAuthorizationResult, aq as AdvancedEscrowClient, ar as AdvancedEscrowClientOptions, as as AdvancedEscrowContracts, at as AdvancedEscrowTaskTier, au as AdvancedPaymentInfo, av as AdvancedTransactionResult, aw as AgentId, ax as AgentIdentity, ay as AgentRegistration, az as AgentRegistrationFile, aA as AgentService, aB as AtomStats, aC as BASE_MAINNET_CONTRACTS, aD as BazaarClient, aE as BazaarClientOptions, aF as BazaarDiscoverOptions, aG as BazaarDiscoverResponse, aH as BazaarRegisterOptions, aI as BazaarResource, aJ as CreateEscrowOptions, D as DEFAULT_FACILITATOR_RETRIES, d as DEFAULT_RETRY_AFTER_SECONDS, aK as DEPOSIT_LIMIT_USDC, aL as DiscoveryAccepts, aM as DiscoveryCuration, aN as DiscoveryHealth, aO as DiscoveryHealthStatus, aP as DiscoveryListOptions, aQ as DiscoveryPagination, aR as DiscoveryRegisterOptions, aS as DiscoveryResource, aT as DiscoveryResponse, aU as DiscoverySource, aV as DiscoveryStats, aW as DiscoveryTier, aX as Dispute, aY as DisputeOutcome, aZ as ERC8004_CONTRACTS, a_ as ERC8004_EXTENSION_ID, a$ as ESCROW_CONTRACTS, b0 as ESCROW_NOTHING_TO_VOID, b1 as ESCROW_OPERATOR_GENERATION, b2 as ESCROW_OPERATOR_NOT_DEPLOYED, b3 as ESCROW_TIMEOUT_MS, b4 as ESCROW_UNSUPPORTED_ON_GENERATION, b5 as ESCROW_VOID_AMOUNT_MISMATCH, b6 as Erc8004Client, b7 as Erc8004ClientOptions, b8 as Erc8004LookupError, b9 as Erc8004Network, ba as EscrowClient, bb as EscrowClientOptions, bc as EscrowOperatorGeneration, bd as EscrowPayment, be as EscrowStateResponse, bf as EscrowStatus, F as FacilitatorCallOptions, e as FacilitatorClient, f as FacilitatorClientOptions, g as FacilitatorErrorInfo, h as FacilitatorFailureFields, i as FacilitatorFetchOptions, bg as FeedbackEntry, bh as FeedbackParams, bi as FeedbackRequest, bj as FeedbackResponse, bk as HEALTH_FILTERS, H as HonoMiddlewareOptions, I as IDEMPOTENCY_KEY_HEADER, j as IDEMPOTENT_REPLAYED_HEADER, bl as IdentityByOwnerResponse, bm as IdentityMetadataResponse, bn as IdentityTotalSupplyResponse, bo as LifecycleAuthOptions, M as MAX_RETRY_AFTER_SECONDS, bp as MAX_SEARCH_LEN, bq as MetadataEntryParam, br as OPERATOR_ABI, bs as OPERATOR_ABI_CREATE3, bt as OPERATOR_ABI_V3, bu as PAYMENT_INFO_TYPEHASH, P as ParsedFacilitatorErrorBody, v as PaymentAcceptance, w as PaymentConflictResponse, x as PaymentMiddlewareOptions, y as PaymentPayloadV2, bv as PaymentRequirementResolver, bw as PaymentRequirements, bx as PaymentRequirementsOptions, z as PaymentRequirementsV2, by as PrepareRelayFeedbackRequest, bz as PrepareRelayFeedbackResponse, bA as PrepareRelayResponseRequest, bB as PrepareSolanaFeedbackRequest, bC as PrepareSolanaFeedbackResponse, bD as ProofOfPayment, R as RECEIPT_REQUEST_CONFLICT, bE as RELAYED_FEEDBACK_NETWORKS, C as REPLAYABLE_LEASE_REASONS, bF as RefundRequest, bG as RefundStatus, bH as RegisterAgentRequest, bI as RegisterAgentResponse, bJ as RegisterJobResponse, bK as RegisterJobStatus, bL as RegistrationPendingError, bM as RelayAuthorizationParams, bN as ReputationResponse, bO as ReputationSummary, bP as RequestRefundOptions, E as ResourceInfoV2, S as SETTLEMENT_UNCONFIRMED, bQ as SOLANA_FEEDBACK_NETWORKS, bR as SettleRequest, G as SettleRequestV2, J as SettleResponse, bS as SettleResponseWithProof, bT as SubmitRelayFeedbackRequest, bU as SubmitRelayResponseRequest, bV as SubmitSolanaFeedbackRequest, bW as TIER_FILTERS, bX as TIER_TIMINGS, bY as USDC_DOMAIN_NAME, bZ as UnavailableBody, b_ as UnavailableResponse, V as VerifiedPaymentState, b$ as VerifyRequest, K as VerifyRequestV2, N as VerifyResponse, W as WRITER_LEASE_REASONS, Q as WriterLeaseReason, X as X402_CORS_HEADERS, T as X402_HEADER_NAMES, c0 as ZERO_ADDRESS, c1 as buildErc8004PaymentRequirements, Z as buildPaymentConflictResponse, _ as buildPaymentRequirements, $ as buildSettleRequest, a0 as buildSettleRequestForVersion, a1 as buildSettleRequestV2, c2 as buildUnavailableResponse, a2 as buildVerifyRequest, a3 as buildVerifyRequestForVersion, a4 as buildVerifyRequestV2, c3 as canRefundEscrow, c4 as canReleaseEscrow, c5 as carryFailureFields, a5 as create402Response, a6 as createHonoMiddleware, a7 as createIdempotencyKey, a8 as createPaymentMiddleware, c6 as epochToDate, c7 as escrowTimeRemaining, a9 as extractPaymentFromHeaders, aa as facilitatorFetch, ab as getCorsHeaders, c8 as getEscrowContractsByChainId, c9 as getEscrowOperatorGeneration, ca as getEscrowSupportedChainIds, cb as isAlive, ac as isAmbiguousLeaseReason, ad as isAuthorizationAlreadyUsed, ae as isAuthorizationInFlight, cc as isEscrowExpired, cd as isEscrowSupportedOnChain, ce as isRegisterJobTerminal, af as isReplayableLeaseReason, ag as isSettlementUnconfirmed, ai as parseFacilitatorErrorBody, cf as parsePaymentHeader, aj as parseRetryAfterSeconds, ak as readFacilitatorError, al as resolveEnvelopeVersion, cg as supportsRelayedFeedback, ch as supportsSolanaFeedback, am as toPaymentRequirementsV2, an as toResourceInfoV2, ci as wireNetwork } from '../index-vMFUhX5W.js';
+export { a as FacilitatorReceipt, F as FetchReceiptResult, P as PaymentState, b as PurchaseContext, c as RECEIPT_ISSUER, R as ReceiptFetchOptions, d as ReceiptKeys, e as STACK_KEY_HEADER, S as StackKeyOptions, f as StackKeyRedirectError, g as canonicalReceiptJson, h as createPurchaseContext, i as fetchWithReceipt, j as getFacilitatorReceipt, m as mergeHeaderList, k as mergePaymentResponseHeaders, p as parseFacilitatorReceipt, l as paymentResponseHeaders, n as purchaseContextHeader, r as receiptCommitment, o as receiptFromErrorBody, q as receiptFromResponse, v as validatePurchaseContext, s as verifyFacilitatorReceipt } from '../receipts-8XsMeo1y.js';
+import '../index-DagQ74ZQ.js';
+export { A as AMBIGUOUS_LEASE_REASONS, a as AUTHORIZATION_ALREADY_SETTLED, b as AUTHORIZATION_IN_FLIGHT, c as AdmittedAuthorizationCode, ap as AdvancedAuthorizationResult, aq as AdvancedEscrowClient, ar as AdvancedEscrowClientOptions, as as AdvancedEscrowContracts, at as AdvancedEscrowTaskTier, au as AdvancedPaymentInfo, av as AdvancedTransactionResult, aw as AgentId, ax as AgentIdentity, ay as AgentRegistration, az as AgentRegistrationFile, aA as AgentService, aB as AtomStats, aC as BASE_MAINNET_CONTRACTS, aD as BazaarClient, aE as BazaarClientOptions, aF as BazaarDiscoverOptions, aG as BazaarDiscoverResponse, aH as BazaarRegisterOptions, aI as BazaarResource, aJ as CreateEscrowOptions, D as DEFAULT_FACILITATOR_RETRIES, d as DEFAULT_RETRY_AFTER_SECONDS, aK as DEPOSIT_LIMIT_USDC, aL as DiscoveryAccepts, aM as DiscoveryCuration, aN as DiscoveryHealth, aO as DiscoveryHealthStatus, aP as DiscoveryListOptions, aQ as DiscoveryPagination, aR as DiscoveryRegisterOptions, aS as DiscoveryResource, aT as DiscoveryResponse, aU as DiscoverySource, aV as DiscoveryStats, aW as DiscoveryTier, aX as Dispute, aY as DisputeOutcome, aZ as ERC8004_CONTRACTS, a_ as ERC8004_EXTENSION_ID, a$ as ESCROW_CONTRACTS, b0 as ESCROW_NOTHING_TO_VOID, b1 as ESCROW_OPERATOR_GENERATION, b2 as ESCROW_OPERATOR_NOT_DEPLOYED, b3 as ESCROW_TIMEOUT_MS, b4 as ESCROW_UNSUPPORTED_ON_GENERATION, b5 as ESCROW_VOID_AMOUNT_MISMATCH, b6 as Erc8004Client, b7 as Erc8004ClientOptions, b8 as Erc8004LookupError, b9 as Erc8004Network, ba as EscrowClient, bb as EscrowClientOptions, bc as EscrowOperatorGeneration, bd as EscrowPayment, be as EscrowStateResponse, bf as EscrowStatus, F as FacilitatorCallOptions, e as FacilitatorClient, f as FacilitatorClientOptions, g as FacilitatorErrorInfo, h as FacilitatorFailureFields, i as FacilitatorFetchOptions, bg as FeedbackEntry, bh as FeedbackParams, bi as FeedbackRequest, bj as FeedbackResponse, bk as HEALTH_FILTERS, H as HonoMiddlewareOptions, I as IDEMPOTENCY_KEY_HEADER, j as IDEMPOTENT_REPLAYED_HEADER, bl as IdentityByOwnerResponse, bm as IdentityMetadataResponse, bn as IdentityTotalSupplyResponse, bo as LifecycleAuthOptions, M as MAX_RETRY_AFTER_SECONDS, bp as MAX_SEARCH_LEN, bq as MetadataEntryParam, br as OPERATOR_ABI, bs as OPERATOR_ABI_CREATE3, bt as OPERATOR_ABI_V3, bu as PAYMENT_INFO_TYPEHASH, P as ParsedFacilitatorErrorBody, v as PaymentAcceptance, w as PaymentConflictResponse, x as PaymentMiddlewareOptions, y as PaymentPayloadV2, bv as PaymentRequirementResolver, bw as PaymentRequirements, bx as PaymentRequirementsOptions, z as PaymentRequirementsV2, by as PrepareRelayFeedbackRequest, bz as PrepareRelayFeedbackResponse, bA as PrepareRelayResponseRequest, bB as PrepareSolanaFeedbackRequest, bC as PrepareSolanaFeedbackResponse, bD as ProofOfPayment, R as RECEIPT_REQUEST_CONFLICT, bE as RELAYED_FEEDBACK_NETWORKS, C as REPLAYABLE_LEASE_REASONS, bF as RefundRequest, bG as RefundStatus, bH as RegisterAgentRequest, bI as RegisterAgentResponse, bJ as RegisterJobResponse, bK as RegisterJobStatus, bL as RegistrationPendingError, bM as RelayAuthorizationParams, bN as ReputationResponse, bO as ReputationSummary, bP as RequestRefundOptions, E as ResourceInfoV2, S as SETTLEMENT_UNCONFIRMED, bQ as SOLANA_FEEDBACK_NETWORKS, bR as SettleRequest, G as SettleRequestV2, J as SettleResponse, bS as SettleResponseWithProof, bT as SubmitRelayFeedbackRequest, bU as SubmitRelayResponseRequest, bV as SubmitSolanaFeedbackRequest, bW as TIER_FILTERS, bX as TIER_TIMINGS, bY as USDC_DOMAIN_NAME, bZ as UnavailableBody, b_ as UnavailableResponse, V as VerifiedPaymentState, b$ as VerifyRequest, K as VerifyRequestV2, N as VerifyResponse, W as WRITER_LEASE_REASONS, Q as WriterLeaseReason, X as X402_CORS_HEADERS, T as X402_HEADER_NAMES, c0 as ZERO_ADDRESS, c1 as buildErc8004PaymentRequirements, Z as buildPaymentConflictResponse, _ as buildPaymentRequirements, $ as buildSettleRequest, a0 as buildSettleRequestForVersion, a1 as buildSettleRequestV2, c2 as buildUnavailableResponse, a2 as buildVerifyRequest, a3 as buildVerifyRequestForVersion, a4 as buildVerifyRequestV2, c3 as canRefundEscrow, c4 as canReleaseEscrow, c5 as carryFailureFields, a5 as create402Response, a6 as createHonoMiddleware, a7 as createIdempotencyKey, a8 as createPaymentMiddleware, c6 as epochToDate, c7 as escrowTimeRemaining, a9 as extractPaymentFromHeaders, aa as facilitatorFetch, ab as getCorsHeaders, c8 as getEscrowContractsByChainId, c9 as getEscrowOperatorGeneration, ca as getEscrowSupportedChainIds, cb as isAlive, ac as isAmbiguousLeaseReason, ad as isAuthorizationAlreadyUsed, ae as isAuthorizationInFlight, cc as isEscrowExpired, cd as isEscrowSupportedOnChain, ce as isRegisterJobTerminal, af as isReplayableLeaseReason, ag as isSettlementUnconfirmed, ai as parseFacilitatorErrorBody, cf as parsePaymentHeader, aj as parseRetryAfterSeconds, ak as readFacilitatorError, al as resolveEnvelopeVersion, cg as supportsRelayedFeedback, ch as supportsSolanaFeedback, am as toPaymentRequirementsV2, an as toResourceInfoV2, ci as wireNetwork } from '../index-CYMXb5eC.js';

package/dist/backend/index.js

@@ -11,6 +11,127 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   if (typeof require !== "undefined") return require.apply(this, arguments);
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
+
+// src/backend/stack-key.ts
+var STACK_KEY_HEADER = "X-UVD-Stack-Key";
+var STACK_KEY_FORMAT = /^uvdsk_[A-Za-z0-9_-]{43,128}$/;
+var LEADING_BOM = /^\uFEFF/;
+var EDGE_WHITESPACE = /^[ \t\r\n]+|[ \t\r\n]+$/g;
+var HOUSE_FACILITATOR_HOSTS = ["facilitator.ultravioletadao.xyz"];
+var LOOPBACK_HOSTS = ["127.0.0.1", "localhost"];
+var StackKeyRedirectError = class extends Error {
+  /** The redirect status, or `0` for an opaque redirect (browsers). */
+  status;
+  constructor(status) {
+    super(
+      `[x402] the facilitator answered a redirect (${status || "opaque"}) to a request carrying ${STACK_KEY_HEADER}; the stack key does not follow redirects. Point the client at the facilitator's final URL.`
+    );
+    this.name = "StackKeyRedirectError";
+    this.status = status;
+  }
+};
+var bindings = /* @__PURE__ */ new WeakMap();
+var warnedFormat = false;
+var warnedHost = false;
+function readEnv() {
+  try {
+    return typeof process !== "undefined" ? process.env?.UVD_STACK_KEY : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function resolveKey(option) {
+  const fromOption = option !== void 0 && option !== null;
+  const raw = fromOption ? option : readEnv();
+  if (raw === void 0 || raw === null) return void 0;
+  const key = typeof raw === "string" ? raw.replace(LEADING_BOM, "").replace(EDGE_WHITESPACE, "") : void 0;
+  if (key === "") return void 0;
+  if (key !== void 0 && STACK_KEY_FORMAT.test(key)) return key;
+  if (!warnedFormat) {
+    warnedFormat = true;
+    console.warn(
+      `[x402] stack key ignored (${fromOption ? "stackKey option" : "UVD_STACK_KEY"}): it is not "uvdsk_" followed by 43-128 base64url characters. Requests go out without ${STACK_KEY_HEADER}.`
+    );
+  }
+  return void 0;
+}
+function listedHosts(option) {
+  if (!Array.isArray(option)) return [];
+  return option.filter((host) => typeof host === "string").map((host) => host.trim().toLowerCase()).filter((host) => host !== "");
+}
+function isHouseFacilitator(url, listed) {
+  const host = url.hostname.toLowerCase();
+  if (url.protocol === "https:") return HOUSE_FACILITATOR_HOSTS.includes(host) || listed.includes(host);
+  if (url.protocol === "http:") return LOOPBACK_HOSTS.includes(host) && listed.includes(host);
+  return false;
+}
+function bindStackKey(owner, options) {
+  const key = resolveKey(options?.stackKey);
+  if (key !== void 0) bindings.set(owner, { key, hosts: listedHosts(options?.stackKeyHosts) });
+}
+function keyFor(owner, url) {
+  const binding = bindings.get(owner);
+  if (binding === void 0) return void 0;
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    parsed = void 0;
+  }
+  if (parsed !== void 0 && isHouseFacilitator(parsed, binding.hosts)) return binding.key;
+  if (!warnedHost) {
+    warnedHost = true;
+    const where = parsed !== void 0 ? `${parsed.protocol}//${parsed.host}` : "an unparseable URL";
+    console.warn(
+      `[x402] stack key not sent: ${where} is not a house facilitator. The key goes only over https to ${HOUSE_FACILITATOR_HOSTS.join(", ")} or to a host in stackKeyHosts (plain http only to 127.0.0.1 or localhost listed there).`
+    );
+  }
+  return void 0;
+}
+function headersWithKey(headers, key) {
+  const out = {};
+  if (typeof Headers !== "undefined" && headers instanceof Headers) {
+    headers.forEach((value, name) => {
+      out[name] = value;
+    });
+  } else if (Array.isArray(headers)) {
+    for (const [name, value] of headers) out[name] = value;
+  } else if (headers) {
+    Object.assign(out, headers);
+  }
+  for (const name of Object.keys(out)) {
+    if (name.toLowerCase() === STACK_KEY_HEADER.toLowerCase()) delete out[name];
+  }
+  out[STACK_KEY_HEADER] = key;
+  return out;
+}
+function isRedirect(response) {
+  return response.type === "opaqueredirect" || response.status >= 300 && response.status < 400;
+}
+async function stackKeyFetch(owner, url, init, fetchImpl) {
+  const doFetch = fetchImpl ?? fetch;
+  const key = keyFor(owner, url);
+  if (key === void 0) return doFetch(url, init);
+  const response = await doFetch(url, { ...init, headers: headersWithKey(init?.headers, key), redirect: "manual" });
+  if (isRedirect(response)) {
+    try {
+      await response.body?.cancel();
+    } catch {
+    }
+    throw new StackKeyRedirectError(response.status);
+  }
+  return response;
+}
+function stackKeyFetcher(owner, fetchImpl) {
+  return (input, init) => stackKeyFetch(
+    owner,
+    typeof input === "string" ? input : input instanceof URL ? input.href : input.url,
+    init,
+    fetchImpl
+  );
+}
+
+// src/receipts.ts
 var RECEIPT_ISSUER = "https://facilitator.ultravioletadao.xyz";
 var encoder = new TextEncoder();
 var decoder = new TextDecoder("utf-8", { fatal: true });
@@ -204,7 +325,9 @@ async function fetchWithReceipt(fetchClient, url, options) {
 async function getFacilitatorReceipt(receiptId, context, options = {}) {
   if (!/^[0-9a-f-]{36}$/.test(receiptId)) throw new Error("invalid receipt ID");
   const issuer = options.issuer || RECEIPT_ISSUER;
-  const response = await (options.fetchImpl || globalThis.fetch)(`${issuer}/receipts/${receiptId}`, { headers: { Authorization: `Bearer ${context.accessToken}` } });
+  const owner = {};
+  bindStackKey(owner, options);
+  const response = await stackKeyFetch(owner, `${issuer}/receipts/${receiptId}`, { headers: { Authorization: `Bearer ${context.accessToken}` } }, options.fetchImpl || globalThis.fetch);
   if (!response.ok) throw new Error(`receipt lookup failed: ${response.status}`);
   const receipt = parseFacilitatorReceipt((await response.json()).receipt);
   if (!receipt || receipt.issuer !== issuer || receipt.purchaseId !== context.purchaseId) throw new Error("receipt lookup mismatch");
@@ -2194,6 +2317,7 @@ var FacilitatorClient = class {
     this.timeout = options.timeout || 3e4;
     this.retries = options.retries;
     this.x402Version = options.x402Version ?? "auto";
+    bindStackKey(this, options);
   }
   /**
    * Get timeout for a specific network, using per-chain defaults when no explicit timeout was set.
@@ -2240,7 +2364,7 @@ var FacilitatorClient = class {
           headers: facilitatorHeaders(idempotencyKey, options.receiptContext),
           body: JSON.stringify(body)
         },
-        { timeoutMs: this.timeout, retries: this.retries }
+        { timeoutMs: this.timeout, retries: this.retries, fetchImpl: stackKeyFetcher(this) }
       );
       if (error) {
         return {
@@ -2301,7 +2425,7 @@ var FacilitatorClient = class {
           headers: facilitatorHeaders(idempotencyKey, options.receiptContext),
           body: JSON.stringify(body)
         },
-        { timeoutMs: settleTimeout, retries: this.retries }
+        { timeoutMs: settleTimeout, retries: this.retries, fetchImpl: stackKeyFetcher(this) }
       );
       if (error) {
         return {
@@ -2418,7 +2542,7 @@ var FacilitatorClient = class {
    */
   async healthCheck() {
     try {
-      const response = await fetch(`${this.baseUrl}/health`, {
+      const response = await stackKeyFetch(this, `${this.baseUrl}/health`, {
         method: "GET"
       });
       return response.ok;
@@ -2432,7 +2556,7 @@ var FacilitatorClient = class {
    * @returns Version info (e.g., { version: "1.37.0" })
    */
   async getVersion() {
-    const response = await fetch(`${this.baseUrl}/version`, {
+    const response = await stackKeyFetch(this, `${this.baseUrl}/version`, {
       method: "GET"
     });
     if (!response.ok) {
@@ -2455,7 +2579,7 @@ var FacilitatorClient = class {
    * ```
    */
   async getSupported() {
-    const response = await fetch(`${this.baseUrl}/supported`, {
+    const response = await stackKeyFetch(this, `${this.baseUrl}/supported`, {
       method: "GET"
     });
     if (!response.ok) {
@@ -2482,7 +2606,7 @@ var FacilitatorClient = class {
    * unrecognised; render the atomic value rather than guessing a scale.
    */
   async getStats() {
-    const response = await fetch(`${this.baseUrl}/api/stats`, { method: "GET" });
+    const response = await stackKeyFetch(this, `${this.baseUrl}/api/stats`, { method: "GET" });
     if (!response.ok) {
       const errorText = await response.text();
       throw new Error(`GET /api/stats failed: ${response.status} - ${errorText}`);
@@ -2505,7 +2629,8 @@ var FacilitatorClient = class {
     if (options.limit !== void 0) params.set("limit", String(options.limit));
     if (options.network) params.set("network", options.network);
     const query = params.toString();
-    const response = await fetch(
+    const response = await stackKeyFetch(
+      this,
       `${this.baseUrl}/transactions${query ? `?${query}` : ""}`,
       { method: "GET" }
     );
@@ -2527,7 +2652,7 @@ var FacilitatorClient = class {
    * ```
    */
   async getBlacklist() {
-    const response = await fetch(`${this.baseUrl}/blacklist`, {
+    const response = await stackKeyFetch(this, `${this.baseUrl}/blacklist`, {
       method: "GET"
     });
     if (!response.ok) {
@@ -2568,7 +2693,7 @@ var FacilitatorClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(`${this.baseUrl}/accepts`, {
+      const response = await stackKeyFetch(this, `${this.baseUrl}/accepts`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
@@ -2880,7 +3005,9 @@ function createPaymentMiddleware(getRequirements, options = {}) {
   const client = new FacilitatorClient({
     baseUrl: options.facilitatorUrl || options.baseUrl,
     timeout: options.timeout,
-    retries: options.retries
+    retries: options.retries,
+    stackKey: options.stackKey,
+    stackKeyHosts: options.stackKeyHosts
   });
   const settlementStrategy = options.settlementStrategy || "before-handler";
   return async (req, res, next) => {
@@ -2982,7 +3109,9 @@ function createHonoMiddleware(options) {
   const client = new FacilitatorClient({
     baseUrl: options.facilitatorUrl || options.baseUrl,
     timeout: options.timeout,
-    retries: options.retries
+    retries: options.retries,
+    stackKey: options.stackKey,
+    stackKeyHosts: options.stackKeyHosts
   });
   const settlementStrategy = options.settlementStrategy || "before-handler";
   if (!options.accepts[0]) {
@@ -3097,6 +3226,7 @@ var BazaarClient = class {
   constructor(options = {}) {
     this.baseUrl = (options.baseUrl || "https://facilitator.ultravioletadao.xyz").replace(/\/+$/, "");
     this.timeout = options.timeout || 3e4;
+    bindStackKey(this, options);
   }
   /**
    * Issue a request against the facilitator with the configured timeout.
@@ -3105,7 +3235,7 @@ var BazaarClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(`${this.baseUrl}${path}`, {
+      const response = await stackKeyFetch(this, `${this.baseUrl}${path}`, {
         ...init,
         headers: { Accept: "application/json", ...init?.headers || {} },
         signal: controller.signal
@@ -3241,7 +3371,7 @@ var BazaarClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(`${this.baseUrl}/health`, {
+      const response = await stackKeyFetch(this, `${this.baseUrl}/health`, {
         method: "GET",
         signal: controller.signal
       });
@@ -3269,6 +3399,7 @@ var EscrowClient = class {
     this.baseUrl = options.baseUrl || "https://escrow.ultravioletadao.xyz";
     this.apiKey = options.apiKey;
     this.timeout = options.timeout || 3e4;
+    bindStackKey(this, options);
   }
   getHeaders(authenticated = false) {
     const headers = {
@@ -3293,7 +3424,7 @@ var EscrowClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "POST",
         headers: this.getHeaders(true),
         body: JSON.stringify({
@@ -3326,7 +3457,7 @@ var EscrowClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "GET",
         headers: this.getHeaders(),
         signal: controller.signal
@@ -3355,7 +3486,7 @@ var EscrowClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "POST",
         headers: this.getHeaders(true),
         signal: controller.signal
@@ -3384,7 +3515,7 @@ var EscrowClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "POST",
         headers: this.getHeaders(true),
         body: JSON.stringify({
@@ -3417,7 +3548,7 @@ var EscrowClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "POST",
         headers: this.getHeaders(true),
         body: JSON.stringify({ amount }),
@@ -3446,7 +3577,7 @@ var EscrowClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "POST",
         headers: this.getHeaders(true),
         body: JSON.stringify({ reason }),
@@ -3474,7 +3605,7 @@ var EscrowClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "GET",
         headers: this.getHeaders(),
         signal: controller.signal
@@ -3505,7 +3636,7 @@ var EscrowClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "POST",
         headers: this.getHeaders(true),
         body: JSON.stringify({ reason, evidence }),
@@ -3534,7 +3665,7 @@ var EscrowClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "POST",
         headers: this.getHeaders(true),
         body: JSON.stringify({ evidence }),
@@ -3562,7 +3693,7 @@ var EscrowClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "GET",
         headers: this.getHeaders(),
         signal: controller.signal
@@ -3595,7 +3726,7 @@ var EscrowClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "GET",
         headers: this.getHeaders(true),
         signal: controller.signal
@@ -3635,7 +3766,7 @@ var EscrowClient = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "POST",
         headers: this.getHeaders(),
         body: JSON.stringify(options),
@@ -3659,7 +3790,7 @@ var EscrowClient = class {
    */
   async healthCheck() {
     try {
-      const response = await fetch(`${this.baseUrl}/health`, {
+      const response = await stackKeyFetch(this, `${this.baseUrl}/health`, {
         method: "GET"
       });
       return response.ok;
@@ -3989,6 +4120,7 @@ var Erc8004Client = class {
     this.baseUrl = options.baseUrl || "https://facilitator.ultravioletadao.xyz";
     this.timeout = options.timeout || 3e4;
     this.retries = options.retries;
+    bindStackKey(this, options);
   }
   /**
    * POST a write route, keeping a refusal readable.
@@ -4014,7 +4146,7 @@ var Erc8004Client = class {
         },
         body: JSON.stringify(body)
       },
-      { timeoutMs: this.timeout, retries: this.retries }
+      { timeoutMs: this.timeout, retries: this.retries, fetchImpl: stackKeyFetcher(this) }
     );
   }
   /**
@@ -4029,7 +4161,7 @@ var Erc8004Client = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "GET",
         headers: { "Accept": "application/json" },
         signal: controller.signal
@@ -4064,7 +4196,7 @@ var Erc8004Client = class {
     const url = `${this.baseUrl}/identity/${wireNetwork(network)}/owner/${address}`;
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-    const response = await fetch(url, {
+    const response = await stackKeyFetch(this, url, {
       method: "GET",
       headers: { Accept: "application/json" },
       signal: controller.signal
@@ -4130,7 +4262,7 @@ var Erc8004Client = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "GET",
         headers: { "Accept": "application/json" },
         signal: controller.signal
@@ -4264,7 +4396,7 @@ var Erc8004Client = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
@@ -4398,7 +4530,7 @@ var Erc8004Client = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
@@ -4544,7 +4676,7 @@ var Erc8004Client = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "GET",
         headers: { "Accept": "application/json" },
         signal: controller.signal
@@ -4808,7 +4940,7 @@ var Erc8004Client = class {
     const url = `${this.baseUrl}/register/status/${encodeURIComponent(jobId)}`;
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-    const response = await fetch(url, {
+    const response = await stackKeyFetch(this, url, {
       method: "GET",
       headers: { Accept: "application/json" },
       signal: controller.signal
@@ -4858,7 +4990,7 @@ var Erc8004Client = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "GET",
         headers: { "Accept": "application/json" },
         signal: controller.signal
@@ -4887,7 +5019,7 @@ var Erc8004Client = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "GET",
         headers: { "Accept": "application/json" },
         signal: controller.signal
@@ -4914,7 +5046,7 @@ var Erc8004Client = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
-      const response = await fetch(url, {
+      const response = await stackKeyFetch(this, url, {
         method: "GET",
         headers: { "Accept": "application/json" },
         signal: controller.signal
@@ -5256,6 +5388,7 @@ var AdvancedEscrowClient = class {
     this.gasLimit = options.gasLimit || 3e5;
     this.timeout = options.timeout || ESCROW_TIMEOUT_MS[this.chainId] || DEFAULT_ESCROW_TIMEOUT_MS;
     this.retries = options.retries;
+    bindStackKey(this, options);
     if (this.walletAdapter && !this.rpcUrl) {
       throw new Error(
         "AdvancedEscrowClient: rpcUrl is required when using a SigningWalletAdapter. The adapter signs transactions offline; an RPC provider is needed to build and broadcast them."
@@ -5474,7 +5607,7 @@ var AdvancedEscrowClient = class {
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), this.timeout);
       try {
-        const response = await fetch(`${this.facilitatorUrl}/settle`, {
+        const response = await stackKeyFetch(this, `${this.facilitatorUrl}/settle`, {
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify(payload),
@@ -5691,7 +5824,7 @@ var AdvancedEscrowClient = class {
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify(payload)
           },
-          { timeoutMs: this.timeout, retries: this.retries }
+          { timeoutMs: this.timeout, retries: this.retries, fetchImpl: stackKeyFetcher(this) }
         );
         if (error) {
           return { success: false, error: error.error, ...failureFields(error) };
@@ -5825,7 +5958,7 @@ var AdvancedEscrowClient = class {
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify(payload)
           },
-          { timeoutMs: this.timeout, retries: this.retries }
+          { timeoutMs: this.timeout, retries: this.retries, fetchImpl: stackKeyFetcher(this) }
         );
         if (error) {
           return { success: false, error: error.error, ...failureFields(error) };
@@ -5902,7 +6035,7 @@ var AdvancedEscrowClient = class {
         tokenCollector: this.contracts.tokenCollector
       }
     };
-    const response = await fetch(`${this.facilitatorUrl}/escrow/state`, {
+    const response = await stackKeyFetch(this, `${this.facilitatorUrl}/escrow/state`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(payload)
@@ -6206,6 +6339,8 @@ exports.REPLAYABLE_LEASE_REASONS = REPLAYABLE_LEASE_REASONS;
 exports.RegistrationPendingError = RegistrationPendingError;
 exports.SETTLEMENT_UNCONFIRMED = SETTLEMENT_UNCONFIRMED;
 exports.SOLANA_FEEDBACK_NETWORKS = SOLANA_FEEDBACK_NETWORKS;
+exports.STACK_KEY_HEADER = STACK_KEY_HEADER;
+exports.StackKeyRedirectError = StackKeyRedirectError;
 exports.TIER_FILTERS = TIER_FILTERS;
 exports.TIER_TIMINGS = TIER_TIMINGS;
 exports.USDC_DOMAIN_NAME = USDC_DOMAIN_NAME;