@okxweb3/app-x402-core 0.1.2 → 0.2.0

package/dist/cjs/server/index.js

@@ -5,6 +5,9 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -27,6 +30,642 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/subscription/codec/typed-data.ts
+function getSubscriptionExtra(req) {
+  const extra = req.extra;
+  if (!extra || !extra.contracts || !extra.plan || !extra.domain) {
+    throw new Error(
+      "subscription codec: PaymentRequirements.extra is missing contracts/plan/domain"
+    );
+  }
+  return extra;
+}
+function defaultPermitAmount(extra) {
+  const initialChargePeriods = BigInt(extra.initialCharge?.periodCount ?? 0);
+  const initialChargeAmount = BigInt(extra.initialCharge?.totalAmount ?? "0");
+  const remainingPeriods = BigInt(extra.maxPeriods) - initialChargePeriods;
+  const remainingAmount = remainingPeriods > 0n ? remainingPeriods * BigInt(extra.amountPerPeriod) : 0n;
+  return (initialChargeAmount + remainingAmount).toString();
+}
+function buildPermit2TypedData(input) {
+  const extra = getSubscriptionExtra(input.selected);
+  const amount = input.amount ?? defaultPermitAmount(extra);
+  const chainId = parseChainIdFromNetwork(input.selected.network);
+  return {
+    domain: {
+      name: "Permit2",
+      chainId,
+      verifyingContract: extra.contracts.permit2
+    },
+    types: PERMIT2_TYPES,
+    primaryType: "PermitSingle",
+    message: {
+      details: {
+        token: input.selected.asset,
+        amount,
+        expiration: input.expiration,
+        nonce: input.nonce
+      },
+      spender: extra.contracts.subscription,
+      sigDeadline: input.sigDeadline
+    }
+  };
+}
+function computePermitSingleStructHash(permit) {
+  const PERMIT_DETAILS_TYPEHASH = (0, import_viem.keccak256)(
+    new TextEncoder().encode(
+      "PermitDetails(address token,uint160 amount,uint48 expiration,uint48 nonce)"
+    )
+  );
+  const detailsHash = (0, import_viem.keccak256)(
+    (0, import_viem.encodeAbiParameters)(
+      [
+        { type: "bytes32" },
+        { type: "address" },
+        { type: "uint160" },
+        { type: "uint48" },
+        { type: "uint48" }
+      ],
+      [
+        PERMIT_DETAILS_TYPEHASH,
+        permit.details.token,
+        BigInt(permit.details.amount),
+        Number(permit.details.expiration),
+        Number(permit.details.nonce)
+      ]
+    )
+  );
+  const PERMIT_SINGLE_TYPEHASH = (0, import_viem.keccak256)(
+    new TextEncoder().encode(
+      "PermitSingle(PermitDetails details,address spender,uint256 sigDeadline)PermitDetails(address token,uint160 amount,uint48 expiration,uint48 nonce)"
+    )
+  );
+  return (0, import_viem.keccak256)(
+    (0, import_viem.encodeAbiParameters)(
+      [{ type: "bytes32" }, { type: "bytes32" }, { type: "address" }, { type: "uint256" }],
+      [PERMIT_SINGLE_TYPEHASH, detailsHash, permit.spender, BigInt(permit.sigDeadline)]
+    )
+  );
+}
+function buildSubscriptionTermsTypedData(input) {
+  const extra = getSubscriptionExtra(input.selected);
+  const domain = input.domain ?? extra.domain;
+  let changeEffectiveAt = 0;
+  if (input.changeFrom?.effectiveAt === "immediate") changeEffectiveAt = 1;
+  else if (input.changeFrom?.effectiveAt === "period_end") changeEffectiveAt = 2;
+  const message = {
+    payer: input.payer,
+    merchant: input.selected.payTo,
+    facilitator: extra.facilitator,
+    token: input.selected.asset,
+    amountPerPeriod: extra.amountPerPeriod,
+    periodSec: extra.periodSec,
+    maxPeriods: extra.maxPeriods,
+    startAt: input.startAt,
+    initialChargePeriods: extra.initialCharge?.periodCount ?? 0,
+    initialChargeAmount: extra.initialCharge?.totalAmount ?? "0",
+    termsDeadline: input.termsDeadline,
+    permitHash: input.permitHash,
+    salt: input.salt,
+    planTier: extra.plan.tier,
+    changeFromSubId: input.changeFrom?.fromSubId ?? ZERO_BYTES32,
+    changeEffectiveAt,
+    periodMode: extra.periodMode ?? 0
+  };
+  return {
+    domain,
+    types: SUBSCRIPTION_TERMS_TYPES,
+    primaryType: "SubscriptionTerms",
+    message
+  };
+}
+function buildCancelAuthTypedData(input) {
+  return {
+    domain: input.domain,
+    types: CANCEL_AUTH_TYPES,
+    primaryType: "CancelAuth",
+    message: {
+      action: 0,
+      subId: input.subId,
+      initiator: CANCEL_INITIATOR_TO_ENUM[input.initiator],
+      nonce: input.nonce,
+      deadline: input.deadline
+    }
+  };
+}
+function buildPendingChangeCancelAuthTypedData(input) {
+  return {
+    domain: input.domain,
+    types: PENDING_CHANGE_CANCEL_AUTH_TYPES,
+    primaryType: "PendingChangeCancelAuth",
+    message: {
+      subId: input.subId,
+      newSubId: input.newSubId,
+      nonce: input.nonce,
+      deadline: input.deadline
+    }
+  };
+}
+function parseChainIdFromNetwork(network) {
+  const parts = network.split(":");
+  if (parts.length !== 2 || parts[0] !== "eip155") {
+    throw new Error(`parseChainIdFromNetwork: expected "eip155:<chainId>", got "${network}"`);
+  }
+  const id = Number(parts[1]);
+  if (!Number.isInteger(id) || id <= 0) {
+    throw new Error(`parseChainIdFromNetwork: invalid chainId "${parts[1]}"`);
+  }
+  return id;
+}
+var import_viem, ZERO_BYTES32, PERMIT2_TYPES, SUBSCRIPTION_TERMS_TYPES, CANCEL_AUTH_TYPES, PENDING_CHANGE_CANCEL_AUTH_TYPES, CANCEL_INITIATOR_TO_ENUM;
+var init_typed_data = __esm({
+  "src/subscription/codec/typed-data.ts"() {
+    "use strict";
+    import_viem = require("viem");
+    ZERO_BYTES32 = `0x${"0".repeat(64)}`;
+    PERMIT2_TYPES = {
+      PermitSingle: [
+        { name: "details", type: "PermitDetails" },
+        { name: "spender", type: "address" },
+        { name: "sigDeadline", type: "uint256" }
+      ],
+      PermitDetails: [
+        { name: "token", type: "address" },
+        { name: "amount", type: "uint160" },
+        { name: "expiration", type: "uint48" },
+        { name: "nonce", type: "uint48" }
+      ]
+    };
+    SUBSCRIPTION_TERMS_TYPES = {
+      SubscriptionTerms: [
+        { name: "payer", type: "address" },
+        { name: "merchant", type: "address" },
+        { name: "facilitator", type: "address" },
+        { name: "token", type: "address" },
+        { name: "amountPerPeriod", type: "uint160" },
+        { name: "periodSec", type: "uint64" },
+        { name: "maxPeriods", type: "uint32" },
+        { name: "startAt", type: "uint64" },
+        { name: "initialChargePeriods", type: "uint32" },
+        { name: "initialChargeAmount", type: "uint160" },
+        { name: "termsDeadline", type: "uint64" },
+        { name: "permitHash", type: "bytes32" },
+        { name: "salt", type: "bytes32" },
+        { name: "planTier", type: "uint8" },
+        { name: "changeFromSubId", type: "bytes32" },
+        { name: "changeEffectiveAt", type: "uint8" },
+        { name: "periodMode", type: "uint8" }
+      ]
+    };
+    CANCEL_AUTH_TYPES = {
+      CancelAuth: [
+        { name: "action", type: "uint8" },
+        { name: "subId", type: "bytes32" },
+        { name: "initiator", type: "uint8" },
+        { name: "nonce", type: "bytes32" },
+        { name: "deadline", type: "uint64" }
+      ]
+    };
+    PENDING_CHANGE_CANCEL_AUTH_TYPES = {
+      PendingChangeCancelAuth: [
+        { name: "subId", type: "bytes32" },
+        { name: "newSubId", type: "bytes32" },
+        { name: "nonce", type: "bytes32" },
+        { name: "deadline", type: "uint64" }
+      ]
+    };
+    CANCEL_INITIATOR_TO_ENUM = {
+      payer: 0,
+      merchant: 1
+    };
+  }
+});
+
+// src/subscription/codec/base64.ts
+function base64EncodeUtf8(value) {
+  if (hasBuffer) return Buffer.from(value, "utf8").toString("base64");
+  const binary = unescape(encodeURIComponent(value));
+  return globalThis.btoa(binary);
+}
+function base64DecodeUtf8(value) {
+  if (hasBuffer) return Buffer.from(value, "base64").toString("utf8");
+  const binary = globalThis.atob(value);
+  return decodeURIComponent(escape(binary));
+}
+var hasBuffer;
+var init_base64 = __esm({
+  "src/subscription/codec/base64.ts"() {
+    "use strict";
+    hasBuffer = typeof Buffer !== "undefined";
+  }
+});
+
+// src/subscription/codec/payload.ts
+function parsePaymentRequired(headerValue) {
+  const json = base64DecodeUtf8(headerValue);
+  const parsed = JSON.parse(json);
+  if (!parsed || !Array.isArray(parsed.accepts)) {
+    throw new Error("parsePaymentRequired: missing or invalid `accepts` array");
+  }
+  return parsed.accepts;
+}
+function encodePaymentPayload(input) {
+  const payload = {
+    x402Version: 2,
+    accepted: input.selected,
+    payload: {
+      permitSingle: input.permitSingle,
+      permitSingleSignature: input.permitSingleSignature,
+      terms: input.terms,
+      termsSignature: input.termsSignature
+    }
+  };
+  return base64EncodeUtf8(JSON.stringify(payload));
+}
+function decodePaymentPayload(headerValue) {
+  const json = base64DecodeUtf8(headerValue);
+  return JSON.parse(json);
+}
+function asSubscriptionPaymentInner(payload) {
+  const inner = payload.payload;
+  if (!inner || !inner.permitSingle || !inner.terms || !inner.permitSingleSignature || !inner.termsSignature) {
+    throw new Error(
+      "asSubscriptionPaymentInner: payload.payload is missing required permitSingle/terms fields"
+    );
+  }
+  return inner;
+}
+var init_payload = __esm({
+  "src/subscription/codec/payload.ts"() {
+    "use strict";
+    init_base64();
+  }
+});
+
+// src/subscription/types.ts
+function hasSubscriptionCapability(scheme) {
+  return typeof scheme === "object" && scheme !== null && "verifyAccess" in scheme && "settlementMode" in scheme && scheme.settlementMode === "pre";
+}
+var init_types = __esm({
+  "src/subscription/types.ts"() {
+    "use strict";
+  }
+});
+
+// src/subscription/errors.ts
+var ErrorCode, ChargeErrorCode, ChargeError;
+var init_errors = __esm({
+  "src/subscription/errors.ts"() {
+    "use strict";
+    ErrorCode = {
+      // subscribe / change
+      TermsBindingInvalid: "terms_binding_invalid",
+      AllowanceInsufficient: "allowance_insufficient",
+      AllowanceExpired: "allowance_expired",
+      // charge
+      PeriodNotDue: "period_not_due",
+      InsufficientBalance: "insufficient_balance",
+      // charge / cancel / access
+      SubscriptionNotActive: "subscription_not_active",
+      /**
+       * SDK-local code. Surfaced by `verifyAccess` when local period math
+       * yields `currentCalculatePeriod === 0` — subscription exists but
+       * `nowSec < startAt`, i.e. has not yet entered its first chargeable
+       * period.
+       */
+      SubscriptionNotYetActive: "subscription_not_yet_active",
+      UnauthorizedCaller: "unauthorized_caller",
+      // cancel
+      CancelSignatureInvalid: "cancel_signature_invalid",
+      CancelNonceUsed: "cancel_nonce_used",
+      // change
+      TierSame: "tier_same",
+      ChangeEffectiveAtMismatch: "change_effective_at_mismatch",
+      MerchantMismatch: "merchant_mismatch",
+      PayerMismatch: "payer_mismatch",
+      PendingChangeExists: "pending_change_exists",
+      SubNotActiveForChange: "sub_not_active_for_change",
+      // cancel-pending-change
+      NoPendingChange: "no_pending_change",
+      // all writes
+      ConfirmationTimeout: "confirmation_timeout"
+    };
+    ChargeErrorCode = {
+      PeriodNotDue: ErrorCode.PeriodNotDue,
+      SubscriptionNotActive: ErrorCode.SubscriptionNotActive,
+      InsufficientBalance: ErrorCode.InsufficientBalance,
+      AllowanceExpired: ErrorCode.AllowanceExpired,
+      UnauthorizedCaller: ErrorCode.UnauthorizedCaller,
+      ConfirmationTimeout: ErrorCode.ConfirmationTimeout
+    };
+    ChargeError = class extends Error {
+      constructor(code, subId, txHash) {
+        super(`charge failed: ${code} (sub=${subId})`);
+        this.name = "ChargeError";
+        this.code = code;
+        this.subId = subId;
+        this.txHash = txHash;
+      }
+    };
+  }
+});
+
+// src/subscription/store.ts
+var InMemoryStore;
+var init_store = __esm({
+  "src/subscription/store.ts"() {
+    "use strict";
+    InMemoryStore = class {
+      constructor() {
+        this.data = /* @__PURE__ */ new Map();
+      }
+      async get(subId) {
+        const sub = this.data.get(subId);
+        return sub ? { ...sub } : null;
+      }
+      async put(sub) {
+        this.data.set(sub.subId, { ...sub });
+      }
+      async delete(subId) {
+        this.data.delete(subId);
+      }
+      /**
+       * Return all subscriptions, ordered by `startAt` ascending. Not part of
+       * the SubscriptionStore interface — admin/debug helper, not used by the
+       * scheme. Production backends should expose paginated equivalents.
+       */
+      async list() {
+        return Array.from(this.data.values()).map((s) => ({ ...s })).sort((a, b) => a.startAt - b.startAt);
+      }
+    };
+  }
+});
+
+// src/subscription/client.ts
+var SubscriptionClient;
+var init_client = __esm({
+  "src/subscription/client.ts"() {
+    "use strict";
+    SubscriptionClient = class {
+      constructor(config) {
+        this.scheme = config.scheme;
+        this.store = config.store;
+      }
+      /**
+       * Run one charge period for a subscription. Throws `ChargeError` (one of 6
+       * codes) on facilitator-side failure. Internally `scheme.charge` already
+       * updates the store on success (and on `planChangeTriggered`); the client is
+       * a pass-through.
+       */
+      async charge(subId) {
+        return this.scheme.charge(subId);
+      }
+      /**
+       * Seller-initiated cancel (e.g. ToS violation, fraud, business reason).
+       *
+       * The SDK does NOT hold the Seller's merchant private key; the Seller must
+       * construct + sign a `CancelAuth` with `by=1 (MERCHANT)` outside and pass
+       * it in. SDK runs verifyCancel (sanity check on the auth) then settleCancel
+       * (facilitator + store mark canceled).
+       *
+       * Throws on either verify or settle failure.
+       */
+      async cancelBySeller(subId, auth, _reason) {
+        const v = await this.scheme.verifyCancel(auth, subId);
+        if (!v.ok) {
+          throw new Error(`cancelBySeller.verify failed: ${v.error}`);
+        }
+        const r = await this.scheme.settleCancel(auth, subId);
+        if (!r.success) {
+          throw new Error(`cancelBySeller.settle failed: ${r.error}`);
+        }
+      }
+      /**
+       * Re-sync a subscription from chain and repair the store. Use when:
+       *   - `charge` threw `SubscriptionNotActive` (buyer may have cancelled
+       *     directly via the facilitator or contract)
+       *   - `charge` threw `ConfirmationTimeout` (network-level failure; chain
+       *     may or may not have written)
+       *   - periodic reconciliation
+       *
+       * If the synced sub is in `"changed"` state, the downstream `changedToSubId`
+       * is also fetched and persisted, so the Seller's `dueIndex` can switch over
+       * to the new sub without manual intervention.
+       */
+      async syncFromChain(subId) {
+        const latest = await this.scheme.getSubscription(subId);
+        if (!latest) return null;
+        await this.store.put(latest);
+        if (latest.state === "changed" && latest.changedToSubId) {
+          const newSub = await this.scheme.getSubscription(latest.changedToSubId);
+          if (newSub) await this.store.put(newSub);
+        }
+        return latest;
+      }
+      /**
+       * Direct store read. Cheap; does NOT touch the chain. Use this for hot-path
+       * lookups (e.g. resolving subId to plan/tier for business logic). For chain
+       * state of record, use `syncFromChain`.
+       */
+      async getSubscription(subId) {
+        return this.store.get(subId);
+      }
+    };
+  }
+});
+
+// src/subscription/codec/verify-terms.ts
+function addrEq(a, b) {
+  return a.toLowerCase() === b.toLowerCase();
+}
+function hexEq(a, b) {
+  return !!a && a.toLowerCase() === b.toLowerCase();
+}
+function verifyTermsBindRequirements(terms, requirements) {
+  const extra = requirements.extra ?? {};
+  if (!extra.plan || extra.amountPerPeriod === void 0 || extra.facilitator === void 0) {
+    return ErrorCode.TermsBindingInvalid;
+  }
+  if (!addrEq(terms.merchant, requirements.payTo)) return ErrorCode.MerchantMismatch;
+  if (!addrEq(terms.token, requirements.asset)) return ErrorCode.TermsBindingInvalid;
+  if (!addrEq(terms.facilitator, extra.facilitator)) return ErrorCode.TermsBindingInvalid;
+  if (terms.amountPerPeriod !== extra.amountPerPeriod) return ErrorCode.TermsBindingInvalid;
+  if (terms.periodSec !== extra.periodSec) return ErrorCode.TermsBindingInvalid;
+  if (terms.maxPeriods !== extra.maxPeriods) return ErrorCode.TermsBindingInvalid;
+  if (terms.periodMode !== (extra.periodMode ?? 0)) return ErrorCode.TermsBindingInvalid;
+  if (terms.planTier !== extra.plan.tier) return ErrorCode.TermsBindingInvalid;
+  if (extra.startAt !== void 0 && terms.startAt !== extra.startAt) {
+    return ErrorCode.TermsBindingInvalid;
+  }
+  const expectedInitPeriods = extra.initialCharge?.periodCount ?? 0;
+  const expectedInitAmount = extra.initialCharge?.totalAmount ?? "0";
+  if (terms.initialChargePeriods !== expectedInitPeriods) return ErrorCode.TermsBindingInvalid;
+  if (terms.initialChargeAmount !== expectedInitAmount) return ErrorCode.TermsBindingInvalid;
+  if (extra.changeFrom) {
+    if (!hexEq(terms.changeFromSubId, extra.changeFrom.fromSubId)) {
+      return ErrorCode.TermsBindingInvalid;
+    }
+    const expectedEff = extra.changeFrom.effectiveAt === "immediate" ? 1 : extra.changeFrom.effectiveAt === "period_end" ? 2 : 0;
+    if (terms.changeEffectiveAt !== expectedEff) return ErrorCode.TermsBindingInvalid;
+  } else {
+    if (terms.changeFromSubId !== ZERO_BYTES32) return ErrorCode.TermsBindingInvalid;
+    if (terms.changeEffectiveAt !== 0) return ErrorCode.TermsBindingInvalid;
+  }
+  return null;
+}
+var init_verify_terms = __esm({
+  "src/subscription/codec/verify-terms.ts"() {
+    "use strict";
+    init_errors();
+    init_typed_data();
+  }
+});
+
+// src/subscription/codec/period-math.ts
+function computeElapsedPeriods(periodMode, startAt, billingAnchorAt, periodSec, nowSec) {
+  if (nowSec < startAt) return 0;
+  if (periodMode === PERIOD_MODE_CALENDAR_MONTH) {
+    const anchor = billingAnchorAt > 0 ? billingAnchorAt : startAt;
+    const startOffset = elapsedCalendarMonths(anchor, startAt);
+    return elapsedCalendarMonths(anchor, nowSec) - startOffset + 1;
+  }
+  if (periodSec <= 0) return 0;
+  return Math.floor((nowSec - startAt) / periodSec) + 1;
+}
+function elapsedCalendarMonths(anchorSec, tsSec) {
+  if (tsSec <= anchorSec) return 0;
+  const anchor = new Date(anchorSec * 1e3);
+  const ts = new Date(tsSec * 1e3);
+  let diff = (ts.getUTCFullYear() - anchor.getUTCFullYear()) * 12 + (ts.getUTCMonth() - anchor.getUTCMonth());
+  if (diff < 0) return 0;
+  if (addCalendarMonths(anchorSec, diff) > tsSec) diff--;
+  return Math.max(diff, 0);
+}
+function addCalendarMonths(anchorSec, n) {
+  const anchor = new Date(anchorSec * 1e3);
+  const targetYear = anchor.getUTCFullYear() + Math.floor((anchor.getUTCMonth() + n) / 12);
+  const targetMonth = ((anchor.getUTCMonth() + n) % 12 + 12) % 12;
+  const daysInTargetMonth = new Date(Date.UTC(targetYear, targetMonth + 1, 0)).getUTCDate();
+  const day = Math.min(anchor.getUTCDate(), daysInTargetMonth);
+  const ts = Date.UTC(
+    targetYear,
+    targetMonth,
+    day,
+    anchor.getUTCHours(),
+    anchor.getUTCMinutes(),
+    anchor.getUTCSeconds(),
+    anchor.getUTCMilliseconds()
+  );
+  return Math.floor(ts / 1e3);
+}
+var PERIOD_MODE_CALENDAR_MONTH;
+var init_period_math = __esm({
+  "src/subscription/codec/period-math.ts"() {
+    "use strict";
+    PERIOD_MODE_CALENDAR_MONTH = 1;
+  }
+});
+
+// src/subscription/codec/access-proof.ts
+function buildAccessProofMessage(input) {
+  return (0, import_viem2.keccak256)(
+    (0, import_viem2.encodePacked)(
+      ["bytes32", "address", "uint256"],
+      [input.subId, input.payer, BigInt(input.timestamp)]
+    )
+  );
+}
+function encodeAccessProof(proof) {
+  return base64EncodeUtf8(JSON.stringify(proof));
+}
+function decodeAccessProof(headerValue) {
+  const json = base64DecodeUtf8(headerValue);
+  const parsed = JSON.parse(json);
+  if (!parsed || parsed.kind !== "subscription-id") {
+    throw new Error(`decodeAccessProof: expected kind="subscription-id", got "${parsed?.kind}"`);
+  }
+  return parsed;
+}
+var import_viem2;
+var init_access_proof = __esm({
+  "src/subscription/codec/access-proof.ts"() {
+    "use strict";
+    import_viem2 = require("viem");
+    init_base64();
+  }
+});
+
+// src/subscription/codec/index.ts
+var init_codec = __esm({
+  "src/subscription/codec/index.ts"() {
+    "use strict";
+    init_verify_terms();
+    init_period_math();
+    init_base64();
+    init_payload();
+    init_access_proof();
+    init_typed_data();
+  }
+});
+
+// src/subscription/facilitator-client.ts
+function supportsSubscription(client) {
+  const c = client;
+  return typeof c.subscribe === "function" && typeof c.changeSubscription === "function" && typeof c.cancelSubscription === "function" && typeof c.cancelPendingChange === "function" && typeof c.chargeSubscription === "function" && typeof c.finalizeExpired === "function" && typeof c.getCharges === "function" && typeof c.getPendingChange === "function" && typeof c.getSubscription === "function";
+}
+var init_facilitator_client = __esm({
+  "src/subscription/facilitator-client.ts"() {
+    "use strict";
+  }
+});
+
+// src/subscription/index.ts
+var subscription_exports = {};
+__export(subscription_exports, {
+  CANCEL_AUTH_TYPES: () => CANCEL_AUTH_TYPES,
+  ChargeError: () => ChargeError,
+  ChargeErrorCode: () => ChargeErrorCode,
+  ErrorCode: () => ErrorCode,
+  InMemoryStore: () => InMemoryStore,
+  PENDING_CHANGE_CANCEL_AUTH_TYPES: () => PENDING_CHANGE_CANCEL_AUTH_TYPES,
+  PERMIT2_TYPES: () => PERMIT2_TYPES,
+  SUBSCRIPTION_TERMS_TYPES: () => SUBSCRIPTION_TERMS_TYPES,
+  SubscriptionClient: () => SubscriptionClient,
+  ZERO_BYTES32: () => ZERO_BYTES32,
+  addCalendarMonths: () => addCalendarMonths,
+  asSubscriptionPaymentInner: () => asSubscriptionPaymentInner,
+  base64DecodeUtf8: () => base64DecodeUtf8,
+  base64EncodeUtf8: () => base64EncodeUtf8,
+  buildAccessProofMessage: () => buildAccessProofMessage,
+  buildCancelAuthTypedData: () => buildCancelAuthTypedData,
+  buildPendingChangeCancelAuthTypedData: () => buildPendingChangeCancelAuthTypedData,
+  buildPermit2TypedData: () => buildPermit2TypedData,
+  buildSubscriptionTermsTypedData: () => buildSubscriptionTermsTypedData,
+  computeElapsedPeriods: () => computeElapsedPeriods,
+  computePermitSingleStructHash: () => computePermitSingleStructHash,
+  decodeAccessProof: () => decodeAccessProof,
+  decodePaymentPayload: () => decodePaymentPayload,
+  elapsedCalendarMonths: () => elapsedCalendarMonths,
+  encodeAccessProof: () => encodeAccessProof,
+  encodePaymentPayload: () => encodePaymentPayload,
+  hasSubscriptionCapability: () => hasSubscriptionCapability,
+  parseChainIdFromNetwork: () => parseChainIdFromNetwork,
+  parsePaymentRequired: () => parsePaymentRequired,
+  supportsSubscription: () => supportsSubscription,
+  verifyTermsBindRequirements: () => verifyTermsBindRequirements
+});
+var init_subscription = __esm({
+  "src/subscription/index.ts"() {
+    "use strict";
+    init_types();
+    init_errors();
+    init_store();
+    init_client();
+    init_codec();
+    init_facilitator_client();
+  }
+});
+
 // src/server/index.ts
 var server_exports = {};
 __export(server_exports, {
@@ -167,6 +806,10 @@ function deepEqual(obj1, obj2) {
   }
 }
 
+// src/http/httpFacilitatorClient.ts
+init_typed_data();
+init_payload();
+
 // src/schemas/index.ts
 var import_zod = require("zod");
 var import_zod2 = require("zod");
@@ -278,6 +921,8 @@ var HTTPFacilitatorClient = class {
   constructor(config) {
     this.url = config?.url || DEFAULT_FACILITATOR_URL;
     this._createAuthHeaders = config?.createAuthHeaders;
+    this._createSubscriptionAuthHeaders = config?.createSubscriptionAuthHeaders;
+    this._fetchFn = config?.fetchFn ?? fetch;
   }
   /**
    * Verify a payment with the facilitator
@@ -294,7 +939,7 @@ var HTTPFacilitatorClient = class {
       const authHeaders = await this.createAuthHeaders("verify");
       headers = { ...headers, ...authHeaders.headers };
     }
-    const response = await fetch(`${this.url}/verify`, {
+    const response = await this._fetchFn(`${this.url}/verify`, {
       method: "POST",
       headers,
       body: JSON.stringify({
@@ -335,7 +980,7 @@ var HTTPFacilitatorClient = class {
       const authHeaders = await this.createAuthHeaders("settle");
       headers = { ...headers, ...authHeaders.headers };
     }
-    const response = await fetch(`${this.url}/settle`, {
+    const response = await this._fetchFn(`${this.url}/settle`, {
       method: "POST",
       headers,
       body: JSON.stringify({
@@ -377,7 +1022,7 @@ var HTTPFacilitatorClient = class {
     }
     let lastError = null;
     for (let attempt = 0; attempt < GET_SUPPORTED_RETRIES; attempt++) {
-      const response = await fetch(`${this.url}/supported`, {
+      const response = await this._fetchFn(`${this.url}/supported`, {
         method: "GET",
         headers
       });
@@ -411,10 +1056,13 @@ var HTTPFacilitatorClient = class {
       const authHeaders = await this.createAuthHeaders("settle/status");
       headers = { ...headers, ...authHeaders.headers };
     }
-    const response = await fetch(`${this.url}/settle/status?txHash=${encodeURIComponent(txHash)}`, {
-      method: "GET",
-      headers
-    });
+    const response = await this._fetchFn(
+      `${this.url}/settle/status?txHash=${encodeURIComponent(txHash)}`,
+      {
+        method: "GET",
+        headers
+      }
+    );
     if (!response.ok) {
       const text = await response.text().catch(() => response.statusText);
       throw new Error(
@@ -453,10 +1101,129 @@ var HTTPFacilitatorClient = class {
       JSON.stringify(obj, (_, value) => typeof value === "bigint" ? value.toString() : value)
     );
   }
+  // ── SubscriptionFacilitatorClient (period) ─────────────
+  //
+  // Generic JSON POST / GET helpers parameterized by `op` so the same code
+  // path covers all five subscription endpoints. The standard OKX envelope
+  // `{ code, msg?, data? }` is returned to the caller unparsed (the
+  // subscription scheme reads `code === "0"` and `data` directly).
+  async subscriptionAuthHeaders(op) {
+    if (!this._createSubscriptionAuthHeaders) return {};
+    return this._createSubscriptionAuthHeaders(op);
+  }
+  async subscriptionPost(op, path, body) {
+    const headers = {
+      "Content-Type": "application/json",
+      ...await this.subscriptionAuthHeaders(op)
+    };
+    const resp = await this._fetchFn(`${this.url}${path}`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(this.toJsonSafe(body))
+    });
+    if (!resp.ok) {
+      throw new Error(`facilitator ${op} returned HTTP ${resp.status}: ${await resp.text()}`);
+    }
+    return await resp.json();
+  }
+  async subscriptionGet(op, path) {
+    const headers = await this.subscriptionAuthHeaders(op);
+    const resp = await this._fetchFn(`${this.url}${path}`, { method: "GET", headers });
+    if (!resp.ok) {
+      throw new Error(`facilitator ${op} returned HTTP ${resp.status}: ${await resp.text()}`);
+    }
+    return await resp.json();
+  }
+  /**
+   * Build the {chainIndex, terms, permit, termsSig, permitSig, syncSettle}
+   * request body shared by subscribe / change endpoints.
+   */
+  buildWriteBody(payload, requirements, syncSettle) {
+    const inner = asSubscriptionPaymentInner(payload);
+    return {
+      chainIndex: parseChainIdFromNetwork(requirements.network),
+      terms: inner.terms,
+      permit: inner.permitSingle,
+      termsSig: inner.termsSignature,
+      permitSig: inner.permitSingleSignature,
+      syncSettle: syncSettle ?? true
+    };
+  }
+  async subscribe(paymentPayload, paymentRequirements, syncSettle) {
+    return this.subscriptionPost(
+      "subscribe",
+      "/api/v6/pay/x402/subscriptions",
+      this.buildWriteBody(paymentPayload, paymentRequirements, syncSettle)
+    );
+  }
+  async changeSubscription(paymentPayload, paymentRequirements, oldSubId, syncSettle) {
+    return this.subscriptionPost(
+      "change",
+      "/api/v6/pay/x402/subscriptions/change",
+      {
+        ...this.buildWriteBody(paymentPayload, paymentRequirements, syncSettle),
+        // `oldSubId` is informational — server reads
+        // newTerms.changeFromSubId for the authoritative value.
+        oldSubId,
+        // change body uses `newTerms` not `terms`.
+        newTerms: asSubscriptionPaymentInner(paymentPayload).terms,
+        terms: void 0
+      }
+    );
+  }
+  async cancelSubscription(subId, cancelAuth, syncSettle) {
+    return this.subscriptionPost(
+      "cancel",
+      "/api/v6/pay/x402/subscriptions/cancel",
+      { subId, cancelAuth, syncSettle: syncSettle ?? true }
+    );
+  }
+  async cancelPendingChange(subId, cancelAuth, syncSettle) {
+    return this.subscriptionPost(
+      "cancel-pending-change",
+      "/api/v6/pay/x402/subscriptions/cancel-pending-change",
+      { subId, cancelAuth, syncSettle: syncSettle ?? true }
+    );
+  }
+  async chargeSubscription(subId, syncSettle) {
+    return this.subscriptionPost(
+      "charge",
+      "/api/v6/pay/x402/subscriptions/charge",
+      { subId, syncSettle: syncSettle ?? true }
+    );
+  }
+  async finalizeExpired(subId, syncSettle) {
+    return this.subscriptionPost(
+      "finalize-expired",
+      "/api/v6/pay/x402/subscriptions/finalize-expired",
+      { subId, syncSettle: syncSettle ?? true }
+    );
+  }
+  async getCharges(subId, limit = 50, offset = 0) {
+    const q = new URLSearchParams({ subId, limit: String(limit), offset: String(offset) });
+    return this.subscriptionGet(
+      "getCharges",
+      `/api/v6/pay/x402/subscriptions/charges?${q.toString()}`
+    );
+  }
+  async getPendingChange(subId) {
+    return this.subscriptionGet(
+      "getPendingChange",
+      `/api/v6/pay/x402/subscriptions/pending?subId=${encodeURIComponent(subId)}`
+    );
+  }
+  async getSubscription(subId) {
+    return this.subscriptionGet(
+      "getSubscription",
+      `/api/v6/pay/x402/subscriptions/detail?subId=${encodeURIComponent(subId)}`
+    );
+  }
 };
 
 // src/facilitator/OKXFacilitatorClient.ts
 var import_node_crypto = __toESM(require("crypto"));
+init_typed_data();
+init_payload();
 
 // src/index.ts
 var x402Version = 2;
@@ -532,6 +1299,21 @@ var x402ResourceServer = class {
   hasRegisteredScheme(network, scheme) {
     return !!findByNetworkAndScheme(this.registeredServerSchemes, scheme, network);
   }
+  /**
+   * Look up the registered SchemeNetworkServer for a given network + scheme.
+   * Exposed so the HTTP dispatch layer can perform capability detection
+   * (e.g. `hasSubscriptionCapability(scheme)`) on the actual instance.
+   *
+   * Pattern matching follows the same CAIP-style rules as `verifyPayment`:
+   * registered keys may use wildcards like `eip155:*`.
+   *
+   * @param network - The network identifier
+   * @param scheme - The payment scheme name
+   * @returns The registered scheme server, or undefined if none matches.
+   */
+  findScheme(network, scheme) {
+    return findByNetworkAndScheme(this.registeredServerSchemes, scheme, network);
+  }
   /**
    * Registers a resource service extension that can enrich extension declarations.
    *
@@ -1224,6 +2006,7 @@ var x402HTTPResourceServer = class {
   constructor(ResourceServer, routes) {
     this.compiledRoutes = [];
     this.protectedRequestHooks = [];
+    this.beforeAccessHooks = [];
     this.pollDeadlineMs = DEFAULT_POLL_DEADLINE_MS;
     this.ResourceServer = ResourceServer;
     this.routesConfig = routes;
@@ -1298,6 +2081,22 @@ var x402HTTPResourceServer = class {
     this.protectedRequestHooks.push(hook);
     return this;
   }
+  /**
+   * Register a seller-global `onBeforeAccess` hook fired on every access-
+   * verified subscription request, AFTER `verifyAccess` (signature + payer
+   * + plan allowlist + period math) but BEFORE the handler runs. Seller
+   * uses it for cross-cutting access policy (quota / ban list / feature
+   * gating). Hooks are executed in order of registration; the first one
+   * to return `{ ok: false }` denies (→ 402). Route-level
+   * `RouteConfig.onBeforeAccess` runs AFTER all global hooks.
+   *
+   * @param hook - The hook function
+   * @returns The x402HTTPResourceServer instance for chaining
+   */
+  onBeforeAccess(hook) {
+    this.beforeAccessHooks.push(hook);
+    return this;
+  }
   /**
    * Register a hook to call when the facilitator returns status="timeout".
    * The hook should verify the tx on-chain and return { confirmed: boolean }.
@@ -1355,6 +2154,14 @@ var x402HTTPResourceServer = class {
     }
     const paymentOptions = this.normalizePaymentOptions(routeConfig);
     const paymentPayload = this.extractPayment(adapter);
+    if (routeConfig.operation === "cancel") {
+      const cancelResult = await this.tryDispatchCancelFlow(adapter, routeConfig, paymentOptions);
+      if (cancelResult) return cancelResult;
+    }
+    if (routeConfig.operation === "cancel-pending-change") {
+      const r = await this.tryDispatchCancelPendingChangeFlow(adapter, routeConfig, paymentOptions);
+      if (r) return r;
+    }
     const resourceInfo = {
       url: routeConfig.resource || enrichedContext.adapter.getUrl(),
       description: routeConfig.description || "",
@@ -1364,6 +2171,89 @@ var x402HTTPResourceServer = class {
       paymentOptions,
       enrichedContext
     );
+    if (routeConfig.operation === "change") {
+      let scheme = null;
+      for (const opt of paymentOptions) {
+        if (!opt.network || !opt.scheme) continue;
+        scheme = await this.resolveSubscriptionScheme(opt.network, opt.scheme);
+        if (scheme) break;
+      }
+      if (!scheme) {
+        return {
+          type: "payment-error",
+          response: {
+            status: 500,
+            headers: { "Content-Type": "application/json" },
+            body: { error: "change route: no subscription scheme registered" }
+          }
+        };
+      }
+      let currentSubId;
+      if (paymentPayload) {
+        const innerTerms = paymentPayload.payload?.terms;
+        currentSubId = innerTerms?.changeFromSubId;
+      } else {
+        const accessHeader = this.extractAccessProofHeader(enrichedContext.adapter);
+        if (!accessHeader) {
+          return {
+            type: "payment-error",
+            response: {
+              status: 401,
+              headers: { "Content-Type": "application/json" },
+              body: { error: "change route: missing APP-Access header" }
+            }
+          };
+        }
+        const { decodeAccessProof: decodeAccessProof2 } = await this.loadSubscriptionModule();
+        let proof;
+        try {
+          proof = decodeAccessProof2(accessHeader);
+        } catch {
+          return {
+            type: "payment-error",
+            response: {
+              status: 400,
+              headers: { "Content-Type": "application/json" },
+              body: { error: "change route: invalid APP-Access header" }
+            }
+          };
+        }
+        const verify = await scheme.verifyOwnership(proof);
+        if (!verify.ok) {
+          return {
+            type: "payment-error",
+            response: {
+              status: 401,
+              headers: { "Content-Type": "application/json" },
+              body: { error: verify.error }
+            }
+          };
+        }
+        currentSubId = verify.subId;
+      }
+      if (!currentSubId) {
+        return {
+          type: "payment-error",
+          response: {
+            status: 400,
+            headers: { "Content-Type": "application/json" },
+            body: { error: "change route: cannot resolve currentSubId" }
+          }
+        };
+      }
+      const enriched = await scheme.enrichAcceptsForChange(requirements, currentSubId);
+      if (enriched === null) {
+        return {
+          type: "payment-error",
+          response: {
+            status: 404,
+            headers: { "Content-Type": "application/json" },
+            body: { error: "sub_not_active_for_change" }
+          }
+        };
+      }
+      requirements = enriched;
+    }
     let extensions = routeConfig.extensions;
     if (extensions) {
       extensions = this.ResourceServer.enrichExtensions(extensions, enrichedContext);
@@ -1376,6 +2266,23 @@ var x402HTTPResourceServer = class {
       extensions,
       transportContext
     );
+    if (routeConfig.operation !== "change") {
+      const accessResult = await this.tryDispatchAccessFlow(
+        adapter,
+        routeConfig,
+        paymentOptions,
+        paymentRequired
+      );
+      if (accessResult) return accessResult;
+    }
+    if (paymentPayload) {
+      const subResult = await this.tryDispatchSubscriptionPresettle(
+        paymentPayload,
+        paymentRequired.accepts,
+        routeConfig.operation === "change" ? "change" : "subscribe"
+      );
+      if (subResult) return subResult;
+    }
     if (!paymentPayload) {
       const unpaidBody = routeConfig.unpaidResponseBody ? await routeConfig.unpaidResponseBody(enrichedContext) : void 0;
       return {
@@ -1597,6 +2504,322 @@ var x402HTTPResourceServer = class {
   requiresPayment(context) {
     return this.getRouteConfig(context.path, context.method) !== void 0;
   }
+  /**
+   * Lazy loader for the subscription submodule. The `import()` cache makes
+   * this effectively free after the first hit; isolating it in one place
+   * keeps dispatch helpers free of dynamic-import boilerplate and lets
+   * bundlers tree-shake the entire subscription path when no caller touches
+   * it.
+   */
+  loadSubscriptionModule() {
+    return Promise.resolve().then(() => (init_subscription(), subscription_exports));
+  }
+  /**
+   * Single chokepoint for "is this (network, scheme) backed by a
+   * SubscriptionCapability-implementing scheme?". Returns the narrowed
+   * capability (so callers get full typing on `verifyAccess` / `verifySubscribe`
+   * / etc.) or null if not registered or not a subscription scheme.
+   */
+  async resolveSubscriptionScheme(network, schemeName) {
+    const registered = this.ResourceServer.findScheme(network, schemeName);
+    if (!registered) return null;
+    const { hasSubscriptionCapability: hasSubscriptionCapability2 } = await this.loadSubscriptionModule();
+    return hasSubscriptionCapability2(registered) ? registered : null;
+  }
+  /**
+   * period dispatch helper — Access flow.
+   *
+   * Returns an `access-verified` (or `payment-error`) HTTPProcessResult when
+   * the request carries `APP-Access` AND a subscription-capable scheme is
+   * registered for one of the route's accepted (scheme, network) pairs.
+   * Returns `null` to indicate the dispatcher should fall through to classic
+   * pay-per-request handling.
+   */
+  async tryDispatchAccessFlow(adapter, routeConfig, paymentOptions, paymentRequired) {
+    const headerB64 = this.extractAccessProofHeader(adapter);
+    if (!headerB64) return null;
+    const { decodeAccessProof: decodeAccessProof2 } = await this.loadSubscriptionModule();
+    let proof;
+    try {
+      proof = decodeAccessProof2(headerB64);
+    } catch (err) {
+      return {
+        type: "payment-error",
+        response: {
+          status: 401,
+          headers: { "Content-Type": "application/json" },
+          body: { error: `invalid APP-Access: ${err.message}` }
+        }
+      };
+    }
+    const acceptedPlanIds = collectAcceptedPlanIds(paymentOptions);
+    for (const opt of paymentOptions) {
+      if (!opt.network || !opt.scheme) continue;
+      const scheme = await this.resolveSubscriptionScheme(opt.network, opt.scheme);
+      if (!scheme) continue;
+      const result = await scheme.verifyAccess(proof, { acceptedPlanIds });
+      if (!result.ok) {
+        return {
+          type: "payment-error",
+          response: {
+            status: 402,
+            headers: {
+              "Content-Type": "application/json",
+              "PAYMENT-REQUIRED": encodePaymentRequiredHeader(paymentRequired)
+            },
+            body: { error: result.error }
+          }
+        };
+      }
+      const hooks = [
+        ...this.beforeAccessHooks,
+        ...routeConfig.onBeforeAccess ? [routeConfig.onBeforeAccess] : []
+      ];
+      for (const hook of hooks) {
+        const decision = await hook({
+          subscription: result.subscription,
+          request: {
+            path: adapter.getPath(),
+            method: adapter.getMethod(),
+            headers: adapter.getHeaders?.() ?? {}
+          },
+          route: { acceptedPlanIds, accepts: paymentRequired.accepts }
+        });
+        if (!decision.ok) {
+          return {
+            type: "payment-error",
+            response: {
+              status: 402,
+              headers: { "Content-Type": "application/json" },
+              body: {
+                error: decision.error ?? "access_denied",
+                retryAfter: decision.retryAfter,
+                upgradeOffers: decision.upgradeOffers
+              }
+            }
+          };
+        }
+      }
+      return {
+        type: "access-verified",
+        subscription: result.subscription,
+        headers: {}
+      };
+    }
+    return {
+      type: "payment-error",
+      response: {
+        status: 401,
+        headers: { "Content-Type": "application/json" },
+        body: { error: "no subscription scheme registered for this route" }
+      }
+    };
+  }
+  /**
+   * period dispatch helper — Subscribe presettle flow.
+   *
+   * When the buyer presents a PaymentPayload whose `accepted.scheme` is a
+   * subscription scheme with `settlementMode === "pre"`, this runs verify +
+   * (settle on demand) and returns `payment-presettle`. The middleware is
+   * expected to call `result.settle()` AFTER decision-time but BEFORE
+   * `next()` so handler only runs when the chain creation succeeded.
+   *
+   * Returns `null` to fall through to classic post-settle path-verified flow.
+   */
+  async tryDispatchSubscriptionPresettle(paymentPayload, serverAccepts, operation) {
+    const { accepted } = paymentPayload;
+    const scheme = await this.resolveSubscriptionScheme(accepted.network, accepted.scheme);
+    if (!scheme) return null;
+    const serverReq = this.ResourceServer.findMatchingRequirements(serverAccepts, paymentPayload);
+    if (!serverReq) {
+      return {
+        type: "payment-error",
+        response: {
+          status: 402,
+          headers: { "Content-Type": "application/json" },
+          body: { error: "no_matching_requirements" }
+        }
+      };
+    }
+    if (operation === "change") {
+      const verifyResult2 = await scheme.verifyChange(paymentPayload, serverReq);
+      if (!verifyResult2.ok) {
+        return {
+          type: "payment-error",
+          response: {
+            status: 402,
+            headers: { "Content-Type": "application/json" },
+            body: { error: verifyResult2.error }
+          }
+        };
+      }
+      return {
+        type: "payment-presettle",
+        paymentPayload,
+        paymentRequirements: serverReq,
+        operation: "change",
+        settle: async () => {
+          const r = await scheme.settleChange(paymentPayload, serverReq);
+          return r.success ? {
+            success: true,
+            headers: r.headers,
+            data: {
+              newSubId: r.newSubId,
+              oldSubId: r.oldSubId,
+              operationType: r.operationType,
+              scheduledFromPeriod: r.scheduledFromPeriod
+            }
+          } : { success: false, error: r.error };
+        }
+      };
+    }
+    const verifyResult = await scheme.verifySubscribe(paymentPayload, serverReq);
+    if (!verifyResult.ok) {
+      return {
+        type: "payment-error",
+        response: {
+          status: 402,
+          headers: { "Content-Type": "application/json" },
+          body: { error: verifyResult.error }
+        }
+      };
+    }
+    return {
+      type: "payment-presettle",
+      paymentPayload,
+      paymentRequirements: serverReq,
+      operation: "subscribe",
+      settle: async () => {
+        const r = await scheme.settleSubscribe(paymentPayload, serverReq);
+        return r.success ? {
+          success: true,
+          headers: r.headers,
+          data: { subId: r.subId, subscription: r.subscription }
+        } : { success: false, error: r.error };
+      }
+    };
+  }
+  /**
+   * period dispatch helper — Cancel flow.
+   *
+   * Reads JSON body { auth: CancelAuth, subId: string }, runs verifyCancel
+   * then wraps settleCancel as a payment-presettle (settle-before-handler so
+   * the cancelation is on-chain before the seller's response).
+   */
+  async tryDispatchCancelFlow(adapter, routeConfig, paymentOptions) {
+    let scheme = null;
+    for (const opt of paymentOptions) {
+      if (!opt.network || !opt.scheme) continue;
+      const resolved = await this.resolveSubscriptionScheme(opt.network, opt.scheme);
+      if (resolved) {
+        scheme = resolved;
+        break;
+      }
+    }
+    if (!scheme) return null;
+    const body = adapter.getBody?.() ?? {};
+    if (!body.auth || !body.subId) {
+      return {
+        type: "payment-error",
+        response: {
+          status: 400,
+          headers: { "Content-Type": "application/json" },
+          body: { error: "cancel: body must include auth and subId" }
+        }
+      };
+    }
+    const verifyResult = await scheme.verifyCancel(body.auth, body.subId);
+    if (!verifyResult.ok) {
+      return {
+        type: "payment-error",
+        response: {
+          status: 402,
+          headers: { "Content-Type": "application/json" },
+          body: { error: verifyResult.error }
+        }
+      };
+    }
+    void routeConfig;
+    const settleScheme = scheme;
+    const auth = body.auth;
+    const subId = body.subId;
+    return {
+      type: "payment-presettle",
+      paymentPayload: { x402Version: 2, accepted: null, payload: {} },
+      paymentRequirements: null,
+      operation: "cancel",
+      settle: async () => {
+        const r = await settleScheme.settleCancel(auth, subId);
+        return r.success ? { success: true, headers: r.headers, data: { subId } } : { success: false, error: r.error };
+      }
+    };
+  }
+  /**
+   * period dispatch helper — Cancel-Pending-Change flow.
+   *
+   * Reads JSON body `{ auth: PendingChangeCancelAuth, subId: string }`. The
+   * auth must carry `newSubId` (matches the currently PENDING downgrade
+   * target). Runs verifyCancelPendingChange then wraps
+   * settleCancelPendingChange as a payment-presettle.
+   */
+  async tryDispatchCancelPendingChangeFlow(adapter, routeConfig, paymentOptions) {
+    let scheme = null;
+    for (const opt of paymentOptions) {
+      if (!opt.network || !opt.scheme) continue;
+      const resolved = await this.resolveSubscriptionScheme(opt.network, opt.scheme);
+      if (resolved) {
+        scheme = resolved;
+        break;
+      }
+    }
+    if (!scheme) return null;
+    const body = adapter.getBody?.() ?? {};
+    if (!body.auth || !body.subId) {
+      return {
+        type: "payment-error",
+        response: {
+          status: 400,
+          headers: { "Content-Type": "application/json" },
+          body: { error: "cancel-pending-change: body must include auth and subId" }
+        }
+      };
+    }
+    if (!body.auth.newSubId) {
+      return {
+        type: "payment-error",
+        response: {
+          status: 400,
+          headers: { "Content-Type": "application/json" },
+          body: { error: "cancel-pending-change: auth.newSubId is required" }
+        }
+      };
+    }
+    const verifyResult = await scheme.verifyCancelPendingChange(body.auth, body.subId);
+    if (!verifyResult.ok) {
+      return {
+        type: "payment-error",
+        response: {
+          status: 402,
+          headers: { "Content-Type": "application/json" },
+          body: { error: verifyResult.error }
+        }
+      };
+    }
+    void routeConfig;
+    const settleScheme = scheme;
+    const auth = body.auth;
+    const subId = body.subId;
+    return {
+      type: "payment-presettle",
+      paymentPayload: { x402Version: 2, accepted: null, payload: {} },
+      paymentRequirements: null,
+      operation: "cancel-pending-change",
+      settle: async () => {
+        const r = await settleScheme.settleCancelPendingChange(auth, subId);
+        return r.success ? { success: true, headers: r.headers, data: { subId: r.subId } } : { success: false, error: r.error };
+      }
+    };
+  }
   /**
    * Build HTTPResponseInstructions for settlement failure.
    * Uses settlementFailedResponseBody hook if configured, otherwise defaults to empty body.
@@ -1708,8 +2931,25 @@ var x402HTTPResourceServer = class {
         console.warn("Failed to decode PAYMENT-SIGNATURE header:", error);
       }
     }
+    const subHeader = adapter.getHeader("app-payment") || adapter.getHeader("APP-PAYMENT");
+    if (subHeader) {
+      try {
+        const json = Buffer.from(subHeader, "base64").toString("utf8");
+        return JSON.parse(json);
+      } catch (error) {
+        console.warn("Failed to decode APP-PAYMENT header:", error);
+      }
+    }
     return null;
   }
+  /**
+   * Extract `APP-Access` header (subscription access-flow). Returns the raw
+   * base64 string so callers can pass it through to `decodeAccessProof` in
+   * the subscription codec.
+   */
+  extractAccessProofHeader(adapter) {
+    return adapter.getHeader("app-access") || adapter.getHeader("APP-Access") || null;
+  }
   /**
    * Check if request is from a web browser
    *
@@ -1865,6 +3105,15 @@ var x402HTTPResourceServer = class {
     return 0;
   }
 };
+function collectAcceptedPlanIds(options) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const opt of options) {
+    const extra = opt.extra;
+    const id = extra?.plan?.id;
+    if (typeof id === "string" && id.length > 0) seen.add(id);
+  }
+  return Array.from(seen);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_POLL_DEADLINE_MS,