uvd-x402-sdk 2.87.0 → 2.89.0

package/dist/{validation-mSLW4tcO.d.mts → validation-B95g0MqC.d.mts}

@@ -1,4 +1,4 @@
-import { i as X402Header, X as X402Version, C as ChainConfig, j as X402PayloadData, k as X402HeaderV1, l as X402PaymentOption, m as X402HeaderV2, T as TokenType, n as PaymentTokenMetadata, o as X402HeaderName, p as PaymentHeaders } from './index-DOBhTF-j.mjs';
+import { j as X402Header, X as X402Version, C as ChainConfig, k as X402PayloadData, l as X402HeaderV1, m as X402PaymentOption, n as X402HeaderV2, T as TokenType, o as PaymentTokenMetadata, p as X402HeaderName, q as PaymentHeaders } from './index-BWN0Haa0.mjs';
 
 /**
  * uvd-x402-sdk - x402 Protocol Utilities

package/dist/{validation-C7p3a6Ep.d.ts → validation-_Tcjm2gu.d.ts}

@@ -1,4 +1,4 @@
-import { i as X402Header, X as X402Version, C as ChainConfig, j as X402PayloadData, k as X402HeaderV1, l as X402PaymentOption, m as X402HeaderV2, T as TokenType, n as PaymentTokenMetadata, o as X402HeaderName, p as PaymentHeaders } from './index-DOBhTF-j.js';
+import { j as X402Header, X as X402Version, C as ChainConfig, k as X402PayloadData, l as X402HeaderV1, m as X402PaymentOption, n as X402HeaderV2, T as TokenType, o as PaymentTokenMetadata, p as X402HeaderName, q as PaymentHeaders } from './index-BWN0Haa0.js';
 
 /**
  * uvd-x402-sdk - x402 Protocol Utilities

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uvd-x402-sdk",
-  "version": "2.87.0",
+  "version": "2.89.0",
   "description": "x402 Payment SDK - Gasless crypto payments across 25 blockchains via Ultravioleta facilitator. Supports EVM (including Scroll, SKALE Base, Robinhood Chain), Solana, Fogo, Stellar, NEAR, Algorand, Sui, and XRP Ledger. Features: ERC-8004 Trustless Agents, Escrow/Refunds, multi-stablecoin (USDC, EURC, AUSD, PYUSD, USDT, USDG).",
   "author": "Ultravioleta DAO <ultravioletadao@gmail.com>",
   "license": "MIT",

package/src/backend/index.ts

@@ -3685,6 +3685,42 @@ export function supportsRelayedFeedback(network: string): boolean {
   return (RELAYED_FEEDBACK_NETWORKS as readonly string[]).includes(wireNetwork(network));
 }
 
+/**
+ * Networks where the facilitator serves the rater-authored feedback rail on
+ * **Solana**, through `POST /feedback/solana/prepare` + `/submit`.
+ *
+ * A separate list from {@link RELAYED_FEEDBACK_NETWORKS} on purpose, and the
+ * two must never be merged. That one names the chains where Execution Market
+ * deployed a `FeedbackDelegate` and the facilitator verified it on-chain; it
+ * routes to `/feedback/evm/*`. Adding `solana` to it would send a Solana
+ * rating to the EVM route, which answers 400 — and would claim a delegate that
+ * does not exist and is not missing.
+ *
+ * Solana needs no delegate at all: account 0 of the program's `give_feedback`
+ * instruction is already declared `[signer, writable] client`, so the rater
+ * signs as the author natively and the facilitator only co-signs as fee payer.
+ * Nothing is delegated because nothing has to be.
+ *
+ * Both networks are served by the deployed facilitator (v2.16.0, measured
+ * against `GET /supported`).
+ */
+export const SOLANA_FEEDBACK_NETWORKS: readonly Erc8004Network[] = [
+  'solana',
+  'solana-devnet',
+] as const;
+
+/**
+ * Whether `network` serves the rater-authored feedback rail on Solana.
+ *
+ * A routing hint, never the authority: the facilitator re-resolves the
+ * programs and the RPC provider per request and answers
+ * `400 "<network> is not a Solana network served by this facilitator"` for
+ * anything else.
+ */
+export function supportsSolanaFeedback(network: string): boolean {
+  return (SOLANA_FEEDBACK_NETWORKS as readonly string[]).includes(wireNetwork(network));
+}
+
 /**
  * An EIP-7702 authorization, as a wallet produces it.
  *
@@ -3821,6 +3857,84 @@ export interface SubmitRelayFeedbackRequest {
   authorization?: RelayAuthorizationParams;
 }
 
+/**
+ * Request body for `POST /feedback/solana/prepare`.
+ *
+ * `rater` is REQUIRED here and is a base58 Solana pubkey — an `0x` address is
+ * refused (`400 "rater must be a base58 Solana pubkey on this network"`).
+ * `agentId` is the agent's asset pubkey, also base58.
+ */
+export interface PrepareSolanaFeedbackRequest {
+  x402Version: 1 | 2;
+  /** One of {@link SOLANA_FEEDBACK_NETWORKS} */
+  network: Erc8004Network;
+  /**
+   * The rating, plus who signs it.
+   *
+   * **Set `score`.** It is optional on the wire and the ATOM Engine ignores an
+   * unscored feedback entirely: the record lands on the agent, the transaction
+   * succeeds, and the program reports `had_impact=false` — reputation stays at
+   * zero however much unscored feedback accumulates, and it is not retroactive.
+   * Omit it only when a deliberately non-scoring record is what you want.
+   */
+  feedback: FeedbackParams & { rater: string };
+}
+
+/**
+ * Response from `POST /feedback/solana/prepare`.
+ *
+ * Carries an UNSIGNED transaction whose `client` account is the rater. Sign it
+ * with the rater's key and hand it back to {@link Erc8004Client.submitSolanaFeedback}.
+ */
+export interface PrepareSolanaFeedbackResponse {
+  success: boolean;
+  /**
+   * base64 of the bincode-serialised unsigned **legacy** transaction — read it
+   * with `Transaction.from()`, not `VersionedTransaction`.
+   *
+   * It expects TWO signatures: the rater's, which you add, and the fee
+   * payer's, which `/feedback/solana/submit` adds. Do not re-encode the
+   * message or rebuild the instruction — the facilitator rebuilds it from the
+   * declared parameters and refuses to co-sign anything that is not
+   * byte-for-byte what it offered.
+   */
+  transaction?: string;
+  /** Who must sign as `client`, i.e. who the chain will record as the author */
+  rater?: string;
+  /** Who pays the fee. Still the facilitator — that is the point */
+  feePayer?: string;
+  /** The blockhash baked into the message. Submit before it expires */
+  blockhash?: string;
+  /**
+   * Last block height at which this transaction is still valid.
+   *
+   * Past it the network drops the transaction; nothing is written and nothing
+   * is charged. Prepare again rather than resubmitting.
+   */
+  lastValidBlockHeight?: number;
+  error?: string;
+  network: Erc8004Network;
+}
+
+/**
+ * Request body for `POST /feedback/solana/submit`.
+ *
+ * The feedback parameters are not redundant with `prepare`: the facilitator
+ * re-derives the message from them plus the blockhash carried by
+ * {@link transaction}, and refuses to co-sign anything that does not match
+ * byte for byte. Signing arbitrary blobs would turn the fee-payer keypair into
+ * a public signing oracle — one `system_program::transfer` would empty the
+ * wallet with the facilitator's signature on it.
+ */
+export interface SubmitSolanaFeedbackRequest {
+  x402Version: 1 | 2;
+  network: Erc8004Network;
+  /** Exactly what was sent to `prepare`, `rater` included */
+  feedback: FeedbackParams & { rater: string };
+  /** base64 of the rater-signed transaction */
+  transaction: string;
+}
+
 /**
  * Request body for `POST /feedback/response/evm/prepare`.
  *
@@ -4876,6 +4990,152 @@ export class Erc8004Client {
     }
   }
 
+  /**
+   * Ask the facilitator for the Solana transaction the rater must sign.
+   *
+   * Step 1 of the rater-authored rail on Solana. Writes nothing on-chain and
+   * costs nothing: it resolves the programs and the agent asset, reads the
+   * registry collection and a finalized blockhash, and hands back an UNSIGNED
+   * transaction whose `client` account is the rater.
+   *
+   * Why this exists, and why it is not the EVM rail: the program's
+   * `give_feedback` instruction declares account 0 as
+   * `[signer, writable] client (feedback author / fee payer)`, and plain
+   * `POST /feedback` puts the FACILITATOR's keypair there — so the chain
+   * records the facilitator as the author of the rating. Solana carries several
+   * signers per transaction natively, so the rater signs as `client` while the
+   * facilitator stays the fee payer. **No delegation and no program change**,
+   * which is why {@link SOLANA_FEEDBACK_NETWORKS} is its own list and `solana`
+   * must never appear in {@link RELAYED_FEEDBACK_NETWORKS} — that one routes to
+   * `/feedback/evm/*`, which answers 400 here.
+   *
+   * What to do with the answer:
+   * 1. Deserialise `transaction` — base64 of the bincode-serialised **legacy**
+   *    transaction, which is `@solana/web3.js`'s `Transaction.from()`, not
+   *    `VersionedTransaction` — and add the RATER's ed25519 signature. Sign the
+   *    message as it came: re-encoding it changes bytes the facilitator will
+   *    compare. The fee payer's slot stays empty; `submit` fills it.
+   * 2. Hand it back to {@link Erc8004Client.submitSolanaFeedback} with the SAME
+   *    feedback parameters, before `lastValidBlockHeight` passes.
+   *
+   * @param request - Network, rater pubkey and feedback parameters
+   * @returns The unsigned transaction, the fee payer and the blockhash window
+   *
+   * @example
+   * ```ts
+   * import { Transaction } from '@solana/web3.js';
+   *
+   * const prep = await erc8004.prepareSolanaFeedback({
+   *   x402Version: 1,
+   *   network: 'solana',
+   *   feedback: {
+   *     agentId: '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgHkv',
+   *     rater: raterPubkey,   // base58: who the chain records as the author
+   *     value: 87,
+   *     score: 95,            // without it the rating counts for nothing
+   *     tag1: 'quality',
+   *   },
+   * });
+   *
+   * const tx = Transaction.from(Buffer.from(prep.transaction!, 'base64'));
+   * tx.partialSign(raterKeypair);
+   * ```
+   */
+  async prepareSolanaFeedback(
+    request: PrepareSolanaFeedbackRequest,
+  ): Promise<PrepareSolanaFeedbackResponse> {
+    const url = `${this.baseUrl}/feedback/solana/prepare`;
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Accept': 'application/json',
+        },
+        body: JSON.stringify({ ...request, network: wireNetwork(request.network) }),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        return {
+          success: false,
+          error: `Facilitator error: ${response.status} - ${errorText}`,
+          network: request.network,
+        };
+      }
+
+      return await response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+        network: request.network,
+      };
+    }
+  }
+
+  /**
+   * Co-sign and send a rater-signed Solana feedback transaction.
+   *
+   * Step 2 of the rater-authored rail on Solana. What lands on-chain has the
+   * RATER as `client`, so the agent's feedback lists the rater rather than the
+   * facilitator — and only the rater can revoke it.
+   *
+   * Pass back the same feedback parameters {@link Erc8004Client.prepareSolanaFeedback}
+   * was given. They are not redundant: the facilitator re-derives the message
+   * from them plus the blockhash inside the submitted transaction, and refuses
+   * to co-sign anything that is not byte-for-byte what it built
+   * (`400 "submitted transaction does not match the one this facilitator built"`).
+   * The rater's signature is verified BEFORE the facilitator adds its own, so a
+   * transaction the network would reject never costs a fee.
+   *
+   * @param request - Feedback parameters plus the rater-signed transaction
+   * @returns Feedback response with the transaction signature
+   */
+  async submitSolanaFeedback(
+    request: SubmitSolanaFeedbackRequest,
+  ): Promise<FeedbackResponse> {
+    const url = `${this.baseUrl}/feedback/solana/submit`;
+
+    try {
+      const { response, error } = await this.writeJson(url, {
+        ...request,
+        network: wireNetwork(request.network),
+      });
+
+      if (error) {
+        return {
+          success: false,
+          error: error.error,
+          network: request.network,
+          ...failureFields(error),
+        };
+      }
+
+      return await response.json();
+    } catch (error) {
+      // Timeout or connection failure: the write may already be on-chain.
+      // Retryable, never replayable -- and on this rail a resubmission needs a
+      // fresh `prepare`, because the blockhash the rater signed over expires.
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+        network: request.network,
+        retryable: true,
+        safeToReplay: false,
+        retryAfterSeconds: DEFAULT_RETRY_AFTER_SECONDS,
+      };
+    }
+  }
+
   /**
    * Revoke previously submitted feedback
    *

package/src/client/X402Client.ts

@@ -25,6 +25,14 @@ import type {
   WalletAdapter,
 } from '../types';
 import { X402Error, DEFAULT_CONFIG } from '../types';
+import {
+  PurchasePolicy,
+  PolicyRefusedError,
+  decideOnChallenge,
+  noReadableOffer,
+  canonicalRecipient,
+} from '../policy';
+import type { PolicyApproval, ReadChallenge } from '../policy';
 import {
   SUPPORTED_CHAINS,
   getChainByName,
@@ -40,6 +48,52 @@ import {
   buildTokenMetadata,
 } from '../utils';
 
+/**
+ * The x402 scheme vocabulary, shared by all three implementations.
+ *
+ * The same five the Rust facilitator's closed `Scheme` enum holds and the same
+ * five the Python SDK keys `KNOWN_SCHEMES` on. A scheme outside this set is one
+ * no implementation in the stack can name, so an entry carrying one is unreadable
+ * and is counted by the name the seller used.
+ *
+ * Kept as a set of known NAMES rather than of payable ones because the two are
+ * different questions, and conflating them is what rule 7 is about: naming what a
+ * seller offered is how a caller learns to go find a facilitator that implements
+ * it. See {@link CLIENT_PAYABLE_SCHEMES} for the other question.
+ */
+export const KNOWN_SCHEMES: ReadonlySet<string> = new Set([
+  'exact',
+  'upto',
+  'escrow',
+  'commerce',
+  'fhe-transfer',
+]);
+
+/**
+ * Of those, the ones the BUYER path in this client can actually sign.
+ *
+ * One entry, and that is the point: the payload builder stamps
+ * `scheme: 'exact'` into everything it produces, so `exact` is the only thing
+ * this client can honestly present. `escrow` and `commerce` are implemented on
+ * the SELLER side (`src/backend`) and in the pre-auth builder, and `upto` and
+ * `fhe-transfer` are not implemented here at all.
+ *
+ * # Why this is a SECOND set and not a narrower first one
+ *
+ * `parse402` used to accept any entry carrying an amount, a payee and a network,
+ * so a well-formed offer asking for a scheme this build cannot present was read
+ * as payable and then **signed as `exact`** -- a payment offered to the seller
+ * under a scheme it never asked for. Recognising a scheme is not being able to
+ * pay it. Collapsing these two sets into one re-opens exactly that hole: widen
+ * this one to the five known names and a well-formed `escrow` offer gets signed
+ * as `exact` again.
+ *
+ * Both cases end the same way for the caller -- the entry is excluded and counted
+ * by its scheme name -- and `no-readable-offer` says "no offer in this challenge
+ * is one this build **can pay**", which is the frame both of them sit in.
+ */
+export const CLIENT_PAYABLE_SCHEMES: ReadonlySet<string> = new Set(['exact']);
+
 /**
  * X402Client - Main SDK client for x402 payments
  *
@@ -82,6 +136,17 @@ export class X402Client {
   // Event emitter
   private eventHandlers: Map<X402Event, Set<X402EventHandler<X402Event>>> = new Map();
 
+  /**
+   * What this buyer is allowed to sign, evaluated against the offer in hand
+   * before anything is signed.
+   *
+   * `permissive()` when the caller supplied none, and that asymmetry is
+   * deliberate: this SDK had no budget before 2.89.0, so switching one on
+   * silently would refuse payments consumers are making today, while whoever
+   * sits down to WRITE a policy gets the deny-by-default one.
+   */
+  private readonly purchasePolicy: PurchasePolicy;
+
   constructor(config: X402ClientConfig = {}) {
     this.config = {
       ...DEFAULT_CONFIG,
@@ -106,9 +171,21 @@ export class X402Client {
       }
     }
 
+    this.purchasePolicy = config.policy ?? PurchasePolicy.permissive();
+
     this.log('X402Client initialized', { config: this.config });
   }
 
+  /**
+   * The policy in force, for a caller that wants to record a settled payment
+   * against it with {@link PurchasePolicy.recordSpend}.
+   *
+   * Nothing on the payment path ever widens it.
+   */
+  get policy(): PurchasePolicy {
+    return this.purchasePolicy;
+  }
+
   // ============================================================================
   // PUBLIC API - Wallet Connection
   // ============================================================================
@@ -375,8 +452,19 @@ export class X402Client {
     }
 
     const tokenType: TokenType = options.tokenType || 'usdc';
-    const { version, offers } = this.parse402(body, tokenType);
+    const challenge = this.parse402(body, tokenType);
+    const { version, offers } = challenge;
     if (offers.length === 0) {
+      // Step 1 of the policy contract, and two different facts that used to be
+      // one error. A seller that sent offers none of which this build can read is
+      // asking for a scheme we do not implement; saying so names what it wanted,
+      // where "no usable payment options" sends the caller hunting a bug in its
+      // own code. A seller that sent none at all is the other fact, and keeps the
+      // error it always had.
+      const unreadableCount = challenge.unreadableCount ?? challenge.unreadable.length;
+      if (unreadableCount > 0) {
+        throw new PolicyRefusedError(noReadableOffer(challenge.unreadable));
+      }
       throw new X402Error(
         '402 response offered no usable payment options',
         'NO_ACCEPTABLE_PAYMENT'
@@ -412,6 +500,33 @@ export class X402Client {
       }
     }
 
+    // The policy, evaluated against THIS offer, before anything is signed. An
+    // offer that diverges from a listing but sits inside an authorised policy
+    // proceeds -- stopping to ask would turn every ordinary reprice into a halt --
+    // and one that does not is refused with a concrete cause. The policy is never
+    // widened to fit the offer, and there is no confirmation hook in this path.
+    //
+    // The whole challenge goes in, never just the offer: `validUntil` lives in
+    // the challenge's `extensions`, and a call that takes the parts is how it gets
+    // dropped.
+    const decision = decideOnChallenge(this.purchasePolicy, challenge, chosen, {
+      now: Math.floor(Date.now() / 1000),
+      quote: options.advertised,
+    });
+    if (!decision.ok) {
+      this.log('policy refused this offer', { cause: decision.refusal.code });
+      this.emit('paymentFailed', {
+        error: decision.refusal.message,
+        code: 'POLICY_REFUSED',
+      });
+      throw new PolicyRefusedError(decision.refusal);
+    }
+    const approval: PolicyApproval = decision.approval;
+    this.log('policy approved this offer', {
+      versusQuote: approval.versusQuote.code,
+      amount: String(approval.amount),
+    });
+
     if (!chosen.chainName) {
       throw new X402Error(
         `402 asked for payment on unknown network '${chosen.network}'`,
@@ -419,6 +534,38 @@ export class X402Client {
       );
     }
 
+    // The policy just approved the offer's OWN asset, but `createPayment` signs
+    // for whatever token `tokenType` resolves to on this chain -- and reads the
+    // price at that token's decimals. With USDC on both sides they coincide,
+    // which is why this never showed. They do not have to: a seller pricing in a
+    // token that is not the configured one would get an approval for asset A and
+    // a signature for asset B, at B's decimals, and the caller would believe a
+    // budget it never actually enforced.
+    //
+    // Refused rather than silently re-pointed: which token to pay with is the
+    // caller's decision, and guessing it from the seller's 402 is how a wallet
+    // ends up signing for a token nobody chose.
+    const configuredToken = getTokenConfig(chosen.chainName, tokenType);
+    if (
+      chosen.asset &&
+      configuredToken &&
+      canonicalRecipient(configuredToken.address) !== canonicalRecipient(chosen.asset)
+    ) {
+      throw new X402Error(
+        `402 wants ${chosen.asset} on ${chosen.chainName}, but this client signs ` +
+          `${configuredToken.address} (tokenType '${tokenType}'). Pass the tokenType ` +
+          'that matches the offer; signing the configured token would pay a ' +
+          'different asset than the one that was approved.',
+        'NO_ACCEPTABLE_PAYMENT',
+        {
+          offered: chosen.asset,
+          wouldSign: configuredToken.address,
+          tokenType,
+          network: chosen.chainName,
+        }
+      );
+    }
+
     if (chosen.chainName !== this.currentChainName) {
       await this.switchChain(chosen.chainName);
     }
@@ -442,20 +589,43 @@ export class X402Client {
       paidHeaders['PAYMENT-SIGNATURE'] = payment.paymentHeader;
     }
 
-    return doFetch(url, { ...options.init, method, headers: paidHeaders });
+    const paid = await doFetch(url, { ...options.init, method, headers: paidHeaders });
+
+    // Approving did not spend: signing can fail and a settlement can be refused,
+    // and a cumulative limit that counted attempts would lock a caller out of
+    // money it never spent. A retry that came back as anything but another 402 is
+    // the seller accepting the payment, which is the moment a caller records it --
+    // by its own hand, in `onPaid`, never automatically here.
+    if (paid.status !== 402) {
+      options.onPaid?.(approval);
+    }
+    return paid;
   }
 
   /**
-   * Normalise a 402 body into its envelope version and its payment offers.
+   * Normalise a 402 body into its envelope version, its payment offers, the ones
+   * it could not read, and the challenge's `extensions`.
    *
    * Reads both spec shapes -- `{x402Version, accepts: [...]}` and the non-spec
    * one where a lone requirement sits at the top level -- and both dialects of
    * the price field (`maxAmountRequired` in v1, `amount` in v2).
+   *
+   * **`accepts` is a list, so one unreadable entry does not sink the list.** A
+   * seller offering `exact` alongside a scheme this build does not implement used
+   * to be unpayable in the Rust crate, and the buyer never learned there was a
+   * perfectly payable offer right there. The readable ones are kept and the
+   * others are counted by scheme name, so a refusal can say what the seller
+   * offered instead of "could not parse". Discovering the service keeps working
+   * even when buying it automatically does not.
+   *
+   * Returns the WHOLE challenge on purpose: handing `offers` alone downstream is
+   * what dropped the seller's `validUntil` on the floor in Rust for a full commit
+   * with every unit test green.
    */
   private parse402(
     body: unknown,
     tokenType: TokenType
-  ): { version: X402Version; offers: X402PaymentOffer[] } {
+  ): ReadChallenge & { version: X402Version } {
     const doc = (body ?? {}) as Record<string, unknown>;
     const version: X402Version = Number(doc.x402Version) === 2 ? 2 : 1;
 
@@ -466,16 +636,64 @@ export class X402Client {
         : [];
 
     const offers: X402PaymentOffer[] = [];
+    const unreadable: string[] = [];
+    let unreadableCount = 0;
+
+    /** Count an entry this build cannot pay, by scheme name when it has one. */
+    const cannotRead = (accept: Record<string, unknown> | null) => {
+      unreadableCount += 1;
+      const scheme = accept?.scheme;
+      if (typeof scheme === 'string' && scheme) unreadable.push(scheme);
+    };
+
     for (const entry of rawAccepts) {
-      if (!entry || typeof entry !== 'object') continue;
+      if (!entry || typeof entry !== 'object') {
+        cannotRead(null);
+        continue;
+      }
       const accept = entry as Record<string, unknown>;
 
+      // The scheme first, so a well-formed offer in a scheme we cannot pay is
+      // counted by the NAME the seller used -- the informative half of rule 7 --
+      // instead of being reported for whichever field it also happened to omit.
+      //
+      // An ABSENT scheme is unreadable, not `exact`. Rust requires the field, so a
+      // challenge without it fails to deserialise there, and a buyer that guessed
+      // `exact` would sign under a scheme the seller never actually named -- which
+      // is the same hole as signing a named one we cannot present, minus the
+      // evidence. It is counted (`unreadableCount`) without a name, because it has
+      // none to report.
+      //
+      // Note this is deliberately ASYMMETRIC with the seller side of this SDK,
+      // where a missing scheme reads as `exact` ("the default, not an override",
+      // `src/backend/index.ts`). A seller is lenient about what it accepts; a
+      // buyer is strict about what it signs.
+      const declaredScheme = accept.scheme;
+      if (
+        typeof declaredScheme !== 'string' ||
+        !declaredScheme ||
+        !KNOWN_SCHEMES.has(declaredScheme) ||
+        !CLIENT_PAYABLE_SCHEMES.has(declaredScheme)
+      ) {
+        cannotRead(accept);
+        continue;
+      }
+
       const amount = accept.amount ?? accept.maxAmountRequired;
       const payTo = accept.payTo;
       const network = accept.network;
-      if (amount === undefined || amount === null) continue;
-      if (typeof payTo !== 'string' || !payTo) continue;
-      if (typeof network !== 'string' || !network) continue;
+      if (amount === undefined || amount === null) {
+        cannotRead(accept);
+        continue;
+      }
+      if (typeof payTo !== 'string' || !payTo) {
+        cannotRead(accept);
+        continue;
+      }
+      if (typeof network !== 'string' || !network) {
+        cannotRead(accept);
+        continue;
+      }
 
       const chainName = getChainByName(network) ? network : caip2ToChain(network);
 
@@ -490,7 +708,12 @@ export class X402Client {
       });
     }
 
-    return { version, offers };
+    const extensions =
+      doc.extensions && typeof doc.extensions === 'object' && !Array.isArray(doc.extensions)
+        ? (doc.extensions as Record<string, unknown>)
+        : undefined;
+
+    return { version, offers, unreadable, unreadableCount, extensions };
   }
 
   /**

package/src/index.ts

@@ -156,6 +156,34 @@ export type { AnchoredEvidence, EvidenceMode, RecipientRole, AnchorOptions } fro
 
 export { X402Client } from './client';
 
+// ============================================================================
+// Buyer policy - what this buyer is allowed to sign, decided before it signs
+// ============================================================================
+
+export {
+  PurchasePolicy,
+  PolicyRefusedError,
+  decideOnChallenge,
+  noReadableOffer,
+  offerValidUntil,
+  offerAsset,
+  canonicalRecipient,
+  assetKey,
+  OFFER_VALIDITY_EXTENSION,
+} from './policy';
+export type {
+  PolicyAsset,
+  PolicyRefusal,
+  PolicyRefusalCode,
+  PolicyApproval,
+  PolicyDecision,
+  QuoteComparison,
+  AdvertisedQuote,
+  EvaluateOptions,
+  DecideOptions,
+  ReadChallenge,
+} from './policy';
+
 // Chain configuration
 export {
   SUPPORTED_CHAINS,