@reinconsole/gate 0.1.0

package/dist/index.js

@@ -0,0 +1,844 @@
+import { EventEmitter } from 'events';
+import { createHash } from 'crypto';
+import { globMatch, isValidDecimal, GateReceipt, newId, sumDecimal, gt } from '@reinconsole/core';
+import { PaymentRequirement, decimalToAtomic, atomicToDecimal } from '@reinconsole/sdk';
+import { z } from 'zod';
+
+// src/gate.ts
+
+// src/errors.ts
+var GateError = class extends Error {
+  constructor(code, message, options = {}) {
+    super(message);
+    this.code = code;
+    this.name = "GateError";
+    this.retryAfterSeconds = options.retryAfterSeconds;
+  }
+  code;
+  /** Seconds until the refused payment could be admitted (throttle codes). */
+  retryAfterSeconds;
+};
+
+// src/v2.ts
+var CAIP2_ALIASES = {
+  base: "eip155:8453",
+  "base-sepolia": "eip155:84532",
+  polygon: "eip155:137",
+  "polygon-amoy": "eip155:80002",
+  bnb: "eip155:56",
+  bsc: "eip155:56",
+  solana: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+  "solana-devnet": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"
+};
+function caip2Of(network) {
+  const key = network.toLowerCase();
+  return CAIP2_ALIASES[key] ?? key;
+}
+function sameNetwork(a, b) {
+  return caip2Of(a) === caip2Of(b);
+}
+function v2Requirements(requirement) {
+  return {
+    scheme: requirement.scheme,
+    network: caip2Of(requirement.network),
+    amount: requirement.maxAmountRequired,
+    asset: requirement.asset,
+    payTo: requirement.payTo,
+    ...requirement.maxTimeoutSeconds !== void 0 ? { maxTimeoutSeconds: requirement.maxTimeoutSeconds } : {},
+    ...requirement.extra ? { extra: requirement.extra } : {}
+  };
+}
+function buildPaymentRequiredV2(requirement, error) {
+  return {
+    x402Version: 2,
+    error,
+    ...requirement.resource ? {
+      resource: {
+        url: requirement.resource,
+        ...requirement.description ? { description: requirement.description } : {},
+        ...requirement.mimeType ? { mimeType: requirement.mimeType } : {}
+      }
+    } : {},
+    accepts: [v2Requirements(requirement)],
+    extensions: {}
+  };
+}
+function encodeBase64Json(value) {
+  return Buffer.from(JSON.stringify(value)).toString("base64");
+}
+var UintString = z.string().regex(/^\d+$/, "must be a decimal integer string");
+var Transfer = z.object({
+  from: z.string().min(1),
+  to: z.string().min(1),
+  /** Atomic-unit amount, mirroring the requirement's maxAmountRequired. */
+  value: UintString
+});
+var Envelope = z.object({
+  x402Version: z.literal(1),
+  scheme: z.string(),
+  network: z.string(),
+  payload: z.record(z.unknown())
+});
+var AcceptedV2 = z.object({
+  scheme: z.string(),
+  network: z.string(),
+  amount: UintString,
+  asset: z.string().min(1),
+  payTo: z.string().min(1)
+}).passthrough();
+var EnvelopeV2 = z.object({
+  x402Version: z.literal(2),
+  accepted: AcceptedV2,
+  payload: z.record(z.unknown())
+}).passthrough();
+function inspectPaymentHeader(raw) {
+  let json;
+  try {
+    json = JSON.parse(Buffer.from(raw, "base64").toString("utf8"));
+  } catch {
+    throw new GateError("malformed_payment", "the payment header is not base64-encoded JSON");
+  }
+  const claimed = json?.x402Version;
+  if (claimed === 2) {
+    const envelope2 = EnvelopeV2.safeParse(json);
+    if (!envelope2.success) {
+      throw new GateError(
+        "malformed_payment",
+        `invalid v2 payment envelope: ${envelope2.error.message}`
+      );
+    }
+    const transfer2 = extractTransfer(envelope2.data.payload, "PAYMENT-SIGNATURE");
+    if (transfer2.value !== envelope2.data.accepted.amount) {
+      throw new GateError(
+        "malformed_payment",
+        `v2 envelope contradicts itself: accepted.amount ${envelope2.data.accepted.amount} vs signed value ${transfer2.value}`
+      );
+    }
+    return {
+      version: 2,
+      scheme: envelope2.data.accepted.scheme,
+      network: envelope2.data.accepted.network,
+      payer: transfer2.from,
+      to: transfer2.to,
+      value: transfer2.value,
+      envelope: json
+    };
+  }
+  const envelope = Envelope.safeParse(json);
+  if (!envelope.success) {
+    throw new GateError("malformed_payment", `invalid X-PAYMENT envelope: ${envelope.error.message}`);
+  }
+  const transfer = extractTransfer(envelope.data.payload, "X-PAYMENT");
+  return {
+    version: 1,
+    scheme: envelope.data.scheme,
+    network: envelope.data.network,
+    payer: transfer.from,
+    to: transfer.to,
+    value: transfer.value,
+    envelope: json
+  };
+}
+function extractTransfer(payload, headerName) {
+  const source = payload["authorization"] ?? payload;
+  const transfer = Transfer.safeParse(source);
+  if (!transfer.success) {
+    throw new GateError(
+      "malformed_payment",
+      `${headerName} carries no recognizable transfer: ${transfer.error.message}`
+    );
+  }
+  return transfer.data;
+}
+function encodeSettlementHeader(response) {
+  return Buffer.from(JSON.stringify(response)).toString("base64");
+}
+
+// src/rails.ts
+var RailsUnreachableError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "RailsUnreachableError";
+  }
+};
+var NEVER_SENT_CODES = /* @__PURE__ */ new Set(["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN"]);
+function isNeverSent(err) {
+  for (let e = err; e !== null && e !== void 0; e = e.cause) {
+    const code = e.code;
+    if (typeof code === "string" && NEVER_SENT_CODES.has(code)) return true;
+    if (e instanceof AggregateError && e.errors.some(isNeverSent)) return true;
+  }
+  return false;
+}
+function classifyTransport(err) {
+  if (isNeverSent(err)) {
+    throw new RailsUnreachableError(messageOf(err), { cause: err });
+  }
+  throw err;
+}
+function messageOf(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function mockFacilitatorRails(facilitator) {
+  return {
+    async verify(paymentHeader, requirement) {
+      try {
+        facilitator.verify(paymentHeader, requirement);
+      } catch (err) {
+        throw new GateError("verify_failed", messageOf(err));
+      }
+    },
+    async settle(paymentHeader, requirement) {
+      let settled;
+      try {
+        settled = facilitator.settle(paymentHeader, requirement);
+      } catch (err) {
+        throw new GateError("settle_failed", messageOf(err));
+      }
+      return {
+        header: settled.header,
+        transaction: settled.response.transaction,
+        network: settled.response.network,
+        payer: settled.response.payer
+      };
+    }
+  };
+}
+function facilitatorClientRails(client) {
+  const dialectRequirements = (paymentHeader, requirement) => {
+    const { envelope, version } = inspectPaymentHeader(paymentHeader);
+    return { envelope, requirements: version === 2 ? v2Requirements(requirement) : requirement };
+  };
+  return {
+    async verify(paymentHeader, requirement) {
+      const { envelope, requirements } = dialectRequirements(paymentHeader, requirement);
+      let verified;
+      try {
+        verified = await client.verify(envelope, requirements);
+      } catch (err) {
+        classifyTransport(err);
+      }
+      if (!verified.isValid) {
+        throw new GateError("verify_failed", verified.invalidReason ?? "payment verification failed");
+      }
+    },
+    async settle(paymentHeader, requirement) {
+      const { envelope, requirements } = dialectRequirements(paymentHeader, requirement);
+      let settled;
+      try {
+        settled = await client.settle(envelope, requirements);
+      } catch (err) {
+        classifyTransport(err);
+      }
+      if (!settled.success) {
+        throw new GateError("settle_failed", settled.errorReason ?? "payment settlement failed");
+      }
+      return {
+        header: encodeSettlementHeader(settled),
+        transaction: settled.transaction,
+        network: settled.network,
+        payer: settled.payer
+      };
+    }
+  };
+}
+function matchRoute(routes, method, pathname) {
+  return routes.find(
+    (route) => (route.method === void 0 || route.method.toUpperCase() === method.toUpperCase()) && globMatch(route.path, pathname)
+  );
+}
+function routeDecimals(route, defaults) {
+  return route.decimals ?? defaults.decimals ?? 6;
+}
+function requirementFor(route, defaults, resourceUrl) {
+  const decimals = routeDecimals(route, defaults);
+  const extra = {
+    ...defaults.extra ?? {},
+    ...route.extra ?? {},
+    // Non-standard decimals must travel with the quote or payers misprice.
+    ...decimals !== 6 ? { decimals } : {}
+  };
+  return PaymentRequirement.parse({
+    scheme: "exact",
+    network: route.network ?? defaults.network,
+    maxAmountRequired: decimalToAtomic(route.price, decimals),
+    resource: resourceUrl,
+    description: route.description ?? "",
+    mimeType: route.mimeType ?? "application/json",
+    payTo: route.payTo ?? defaults.payTo,
+    maxTimeoutSeconds: route.maxTimeoutSeconds ?? defaults.maxTimeoutSeconds ?? 300,
+    asset: route.asset ?? defaults.asset,
+    extra: Object.keys(extra).length > 0 ? extra : void 0
+  });
+}
+
+// src/stores.ts
+var InMemoryGateStore = class {
+  seenPayments = /* @__PURE__ */ new Set();
+  receiptLog = [];
+  quotedCount = 0;
+  refusedCount = 0;
+  burnReplay(key) {
+    if (this.seenPayments.has(key)) return false;
+    this.seenPayments.add(key);
+    return true;
+  }
+  /**
+   * Release a burned slot — on the port (optional) since the rails-unreachable
+   * path, and still what a persist-then-cache impl uses to leave memory
+   * untouched when its own INSERT fails.
+   */
+  releaseReplay(key) {
+    this.seenPayments.delete(key);
+  }
+  appendReceipt(receipt) {
+    this.receiptLog.push(receipt);
+  }
+  recordQuote() {
+    this.quotedCount += 1;
+  }
+  recordRefusal() {
+    this.refusedCount += 1;
+  }
+  /** Hydration primitive for durable stores: set the resumed counter totals. */
+  loadCounters(quoted, refused) {
+    this.quotedCount = quoted;
+    this.refusedCount = refused;
+  }
+  receipts() {
+    return this.receiptLog;
+  }
+  quoted() {
+    return this.quotedCount;
+  }
+  refused() {
+    return this.refusedCount;
+  }
+};
+function validateVelocity(velocity) {
+  if (!Number.isFinite(velocity.windowMs) || velocity.windowMs <= 0) {
+    throw new TypeError(`velocity.windowMs must be a positive number, got ${velocity.windowMs}`);
+  }
+  if (velocity.maxPayments === void 0 && velocity.maxAmount === void 0 && velocity.maxAttempts === void 0) {
+    throw new TypeError("velocity needs at least one of maxPayments, maxAmount, maxAttempts");
+  }
+  for (const key of ["maxPayments", "maxAttempts"]) {
+    const value = velocity[key];
+    if (value !== void 0 && (!Number.isInteger(value) || value <= 0)) {
+      throw new TypeError(`velocity.${key} must be a positive integer, got ${value}`);
+    }
+  }
+  if (velocity.maxAmount !== void 0 && !isValidDecimal(velocity.maxAmount)) {
+    throw new TypeError(`velocity.maxAmount must be a decimal string, got ${JSON.stringify(velocity.maxAmount)}`);
+  }
+}
+var SWEEP_THRESHOLD = 1e4;
+var AttemptWindow = class {
+  constructor(windowMs) {
+    this.windowMs = windowMs;
+  }
+  windowMs;
+  hits = /* @__PURE__ */ new Map();
+  /** Record a presentation at `nowMs`; returns the in-window count (incl. it). */
+  record(key, nowMs) {
+    if (this.hits.size >= SWEEP_THRESHOLD && !this.hits.has(key)) this.sweep(nowMs);
+    const since = nowMs - this.windowMs;
+    const kept = (this.hits.get(key) ?? []).filter((at) => at > since);
+    kept.push(nowMs);
+    this.hits.set(key, kept);
+    return kept.length;
+  }
+  /**
+   * Ms until the in-window count drops below `maxAttempts` — i.e. until enough
+   * of the oldest hits expire that one more presentation would be admitted.
+   */
+  msUntilSlot(key, nowMs, maxAttempts) {
+    const since = nowMs - this.windowMs;
+    const inWindow = (this.hits.get(key) ?? []).filter((at) => at > since);
+    const gatingHit = inWindow[inWindow.length - maxAttempts];
+    if (gatingHit === void 0) return 0;
+    return Math.max(1, gatingHit + this.windowMs - nowMs);
+  }
+  /** Drop keys with no in-window hits (unbounded-payer protection). */
+  sweep(nowMs) {
+    const since = nowMs - this.windowMs;
+    for (const [key, times] of this.hits) {
+      const kept = times.filter((at) => at > since);
+      if (kept.length === 0) this.hits.delete(key);
+      else this.hits.set(key, kept);
+    }
+  }
+};
+function payerReceiptsSince(receipts, payer, sinceMs) {
+  const key = payer.toLowerCase();
+  return receipts.filter((r) => r.payer.toLowerCase() === key && r.at.getTime() >= sinceMs);
+}
+
+// src/gate.ts
+var Gate = class {
+  routes;
+  rails;
+  defaults;
+  allowPayers;
+  denyPayers;
+  screenCheck;
+  advertiseV2;
+  velocity;
+  attempts;
+  retryPolicy;
+  now;
+  bus = new EventEmitter();
+  store;
+  constructor(options) {
+    this.routes = options.routes;
+    this.rails = options.rails;
+    this.defaults = {
+      payTo: options.payTo,
+      network: options.network,
+      asset: options.asset,
+      decimals: options.decimals,
+      maxTimeoutSeconds: options.maxTimeoutSeconds,
+      extra: options.extra
+    };
+    this.allowPayers = options.screen?.allowPayers ? new Set(options.screen.allowPayers.map((a) => a.toLowerCase())) : void 0;
+    this.denyPayers = new Set((options.screen?.denyPayers ?? []).map((a) => a.toLowerCase()));
+    this.screenCheck = options.screen?.check;
+    this.advertiseV2 = options.advertiseV2 ?? false;
+    if (options.velocity) validateVelocity(options.velocity);
+    this.velocity = options.velocity;
+    this.attempts = options.velocity?.maxAttempts ? new AttemptWindow(options.velocity.windowMs) : void 0;
+    this.retryPolicy = {
+      attempts: options.retry?.attempts ?? 2,
+      backoffMs: options.retry?.backoffMs ?? 250
+    };
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+    this.store = options.store ?? new InMemoryGateStore();
+  }
+  onEvent(handler) {
+    this.bus.on("event", handler);
+  }
+  get receipts() {
+    return this.store.receipts();
+  }
+  /** Drain trailing telemetry writes; throws the first failure (durable stores). */
+  async flush() {
+    await this.store.flush?.();
+  }
+  /** Telemetry writes may trail (cache-then-persist) — a store failure,
+   *  rejected OR thrown synchronously, must surface through flush() and can
+   *  never alter a payment outcome (a receipt write turning a SETTLED payment
+   *  into a 500 would charge the payer and serve nothing). */
+  fire(write) {
+    try {
+      void Promise.resolve(write()).catch(() => void 0);
+    } catch {
+    }
+  }
+  /** The requirement a given request would be quoted (or undefined if free). */
+  quoteFor(method, url) {
+    const route = matchRoute(this.routes, method, new URL(url).pathname);
+    return route && requirementFor(route, this.defaults, url);
+  }
+  async handle(request) {
+    const url = new URL(request.url);
+    const method = (request.method || "GET").toUpperCase();
+    const route = matchRoute(this.routes, method, url.pathname);
+    if (!route) return { kind: "open" };
+    const requirement = requirementFor(route, this.defaults, request.url);
+    const amount = atomicToDecimal(
+      requirement.maxAmountRequired,
+      routeDecimals(route, this.defaults)
+    );
+    if (request.payment === null) {
+      this.fire(() => this.store.recordQuote());
+      this.emit({
+        type: "gate.quoted",
+        at: this.now(),
+        resource: url.pathname,
+        method,
+        amount,
+        asset: requirement.asset,
+        network: requirement.network
+      });
+      return {
+        kind: "quote",
+        status: 402,
+        body: { x402Version: 1, accepts: [requirement], error: "X-PAYMENT header is required" },
+        ...this.v2Quote(requirement, "PAYMENT-SIGNATURE header is required")
+      };
+    }
+    let payer;
+    try {
+      const payment = inspectPaymentHeader(request.payment);
+      payer = payment.payer;
+      this.checkRate(payment.payer);
+      this.checkConsistency(payment, requirement);
+      this.screenPayer(payment.payer);
+      this.checkVelocity(payment.payer, requirement, amount);
+      await this.burnReplay(request.payment);
+      const settlement = await this.settleThroughRails(request.payment, requirement);
+      const receipt = GateReceipt.parse({
+        id: newId("grc"),
+        at: this.now(),
+        route: route.path,
+        resource: url.pathname,
+        method,
+        payer: payment.payer,
+        payTo: requirement.payTo,
+        amount,
+        amountAtomic: requirement.maxAmountRequired,
+        asset: requirement.asset,
+        network: requirement.network,
+        transaction: settlement.transaction
+      });
+      this.fire(() => this.store.appendReceipt(receipt));
+      this.emit({ type: "gate.settled", at: receipt.at, receipt });
+      return { kind: "paid", receipt, settlementHeader: settlement.header };
+    } catch (err) {
+      if (!(err instanceof GateError)) throw err;
+      return this.refuse(err, url.pathname, requirement, payer);
+    }
+  }
+  stats() {
+    const receipts = this.store.receipts();
+    const revenue = {};
+    const routes = {};
+    const payers = {};
+    for (const receipt of receipts) {
+      (revenue[receipt.asset] ??= []).push(receipt.amount);
+      const routeLine = routes[receipt.route] ??= { settled: 0, amounts: [] };
+      routeLine.settled += 1;
+      routeLine.amounts.push(receipt.amount);
+      const payerLine = payers[receipt.payer.toLowerCase()] ??= { settled: 0, amounts: [] };
+      payerLine.settled += 1;
+      payerLine.amounts.push(receipt.amount);
+    }
+    const sumLines = (lines) => Object.fromEntries(
+      Object.entries(lines).map(([key, line]) => [
+        key,
+        { settled: line.settled, revenue: sumDecimal(line.amounts) }
+      ])
+    );
+    return {
+      quoted: this.store.quoted(),
+      settled: receipts.length,
+      refused: this.store.refused(),
+      revenue: Object.fromEntries(
+        Object.entries(revenue).map(([asset, amounts]) => [asset, sumDecimal(amounts)])
+      ),
+      routes: sumLines(routes),
+      payers: sumLines(payers)
+    };
+  }
+  emit(event) {
+    this.bus.emit("event", event);
+  }
+  checkConsistency(payment, requirement) {
+    if (payment.scheme.toLowerCase() !== requirement.scheme.toLowerCase()) {
+      throw new GateError(
+        "scheme_mismatch",
+        `payment scheme "${payment.scheme}" does not match the quoted "${requirement.scheme}"`
+      );
+    }
+    if (!sameNetwork(payment.network, requirement.network)) {
+      throw new GateError(
+        "network_mismatch",
+        `payment is on "${payment.network}" but the quote wants "${requirement.network}"`
+      );
+    }
+    if (payment.value !== requirement.maxAmountRequired) {
+      throw new GateError(
+        "amount_mismatch",
+        `payment of ${payment.value} does not match the quoted ${requirement.maxAmountRequired}`
+      );
+    }
+    if (payment.to.toLowerCase() !== requirement.payTo.toLowerCase()) {
+      throw new GateError(
+        "recipient_mismatch",
+        `payment pays "${payment.to}" but the quote pays "${requirement.payTo}"`
+      );
+    }
+  }
+  /**
+   * Presentation rate limit — first check after decode, so a hammering payer
+   * is shed before any further work. Every presentation counts, including
+   * ones that would go on to fail consistency or screening.
+   */
+  checkRate(payer) {
+    const max = this.velocity?.maxAttempts;
+    if (!max || !this.attempts) return;
+    const key = payer.toLowerCase();
+    const nowMs = this.now().getTime();
+    if (this.attempts.record(key, nowMs) > max) {
+      const retryAfterSeconds = Math.ceil(this.attempts.msUntilSlot(key, nowMs, max) / 1e3);
+      throw new GateError(
+        "rate_limited",
+        `payer ${payer} exceeded ${max} payment presentations per ${this.velocity.windowMs}ms`,
+        { retryAfterSeconds }
+      );
+    }
+  }
+  /**
+   * Settled-spend velocity caps, derived from receipts at check time (restart
+   * -safe on durable stores). Runs BEFORE the replay burn on purpose: a
+   * velocity refusal is temporal, not a payment defect, so the same signed
+   * header may come back once the window clears.
+   */
+  checkVelocity(payer, requirement, amount) {
+    const v = this.velocity;
+    if (!v || v.maxPayments === void 0 && v.maxAmount === void 0) return;
+    const nowMs = this.now().getTime();
+    const recent = payerReceiptsSince(this.store.receipts(), payer, nowMs - v.windowMs);
+    const oldest = recent[0];
+    if (v.maxPayments !== void 0 && oldest !== void 0 && recent.length >= v.maxPayments) {
+      const retryAfterSeconds = secondsUntil(oldest.at.getTime() + v.windowMs, nowMs);
+      throw new GateError(
+        "velocity_exceeded",
+        `payer ${payer} already settled ${recent.length} payments in the last ${v.windowMs}ms; the cap is ${v.maxPayments}`,
+        { retryAfterSeconds }
+      );
+    }
+    if (v.maxAmount !== void 0) {
+      const sameAsset = recent.filter((r) => r.asset === requirement.asset);
+      const oldestSameAsset = sameAsset[0];
+      const wouldBe = sumDecimal([...sameAsset.map((r) => r.amount), amount]);
+      if (gt(wouldBe, v.maxAmount)) {
+        const retryAfterSeconds = oldestSameAsset !== void 0 ? secondsUntil(oldestSameAsset.at.getTime() + v.windowMs, nowMs) : void 0;
+        throw new GateError(
+          "velocity_exceeded",
+          `settling ${amount} ${requirement.asset} would put payer ${payer} at ${wouldBe} in the last ${v.windowMs}ms; the cap is ${v.maxAmount}`,
+          { retryAfterSeconds }
+        );
+      }
+    }
+  }
+  /**
+   * Drive both rails legs under the retry policy (see GateRails for the error
+   * taxonomy). GateErrors are semantic verdicts and pass straight through.
+   * Transport failures:
+   *
+   * - verify (read-only): every transport failure is retried; exhausted ->
+   *   `rails_unavailable`, and the slot is released (settle never ran).
+   * - settle: only RailsUnreachableError (provably never sent) is retried;
+   *   exhausted -> `rails_unavailable` + release (still provably unsettled).
+   *   Anything else is ambiguous — the money MAY have moved — so it refuses
+   *   `settle_unknown` immediately and the slot STAYS burned: on real rails a
+   *   re-present would misreport (nonce already used -> settle_failed), and on
+   *   the mock ledger it would double-spend. Vendors reconcile ambiguous
+   *   settles against transaction records (e.g. the on-chain indexer).
+   */
+  async settleThroughRails(paymentHeader, requirement) {
+    await this.railsLeg(
+      "verify",
+      paymentHeader,
+      () => this.rails.verify(paymentHeader, requirement)
+    );
+    return this.railsLeg(
+      "settle",
+      paymentHeader,
+      () => this.rails.settle(paymentHeader, requirement)
+    );
+  }
+  async railsLeg(leg, paymentHeader, fn) {
+    const { attempts, backoffMs } = this.retryPolicy;
+    let lastErr;
+    for (let attempt = 0; attempt <= attempts; attempt++) {
+      if (attempt > 0 && backoffMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, backoffMs * attempt));
+      }
+      try {
+        return await fn();
+      } catch (err) {
+        if (err instanceof GateError) throw err;
+        if (leg === "settle" && !(err instanceof RailsUnreachableError)) {
+          throw new GateError(
+            "settle_unknown",
+            `settlement fate unknown (${messageOf2(err)}); do not re-pay before reconciling`
+          );
+        }
+        lastErr = err;
+      }
+    }
+    try {
+      await this.store.releaseReplay?.(replayKey(paymentHeader));
+    } catch {
+    }
+    throw new GateError(
+      "rails_unavailable",
+      `payment rails unreachable after ${attempts + 1} attempts (${messageOf2(lastErr)}); the payment was NOT settled`
+    );
+  }
+  screenPayer(payer) {
+    const key = payer.toLowerCase();
+    if (this.denyPayers.has(key)) {
+      throw new GateError("payer_denied", `payer ${payer} is blocked by this gate`);
+    }
+    if (this.allowPayers && !this.allowPayers.has(key)) {
+      throw new GateError("payer_not_allowed", `payer ${payer} is not on this gate's allowlist`);
+    }
+    const reason = this.screenCheck?.(payer);
+    if (reason) {
+      throw new GateError("payer_denied", reason);
+    }
+  }
+  /**
+   * Burn the replay slot. The store's check-and-set is sync at call time
+   * (concurrent copies cannot both pass); the await is the durability barrier
+   * — on a durable store the burn is on disk before verify/settle run, so a
+   * crash mid-settle cannot resurrect the slot on restart. A store WRITE
+   * failure is not a GateError: it escapes as a 500, because "we cannot
+   * guarantee replay protection" must never settle a payment.
+   */
+  async burnReplay(paymentHeader) {
+    if (!await this.store.burnReplay(replayKey(paymentHeader))) {
+      throw new GateError(
+        "payment_replayed",
+        "this exact payment was already presented; one settlement per payment"
+      );
+    }
+  }
+  refuse(err, resource, requirement, payer) {
+    this.fire(() => this.store.recordRefusal());
+    this.emit({
+      type: "gate.refused",
+      at: this.now(),
+      code: err.code,
+      reason: err.message,
+      resource,
+      payer
+    });
+    const retry = err.retryAfterSeconds !== void 0 ? { retryAfterSeconds: err.retryAfterSeconds } : {};
+    if (err.code === "payer_denied" || err.code === "payer_not_allowed") {
+      return {
+        kind: "refused",
+        status: 403,
+        code: err.code,
+        reason: err.message,
+        body: { error: "refused", code: err.code, reason: err.message }
+      };
+    }
+    if (err.code === "rate_limited" || err.code === "velocity_exceeded") {
+      return {
+        kind: "refused",
+        status: 429,
+        code: err.code,
+        reason: err.message,
+        body: { error: "refused", code: err.code, reason: err.message, ...retry },
+        ...retry
+      };
+    }
+    if (err.code === "rails_unavailable" || err.code === "settle_unknown") {
+      return {
+        kind: "refused",
+        status: 503,
+        code: err.code,
+        reason: err.message,
+        body: {
+          error: "refused",
+          code: err.code,
+          reason: err.message,
+          retriable: err.code === "rails_unavailable"
+        }
+      };
+    }
+    return {
+      kind: "refused",
+      status: 402,
+      code: err.code,
+      reason: err.message,
+      body: { x402Version: 1, accepts: [requirement], error: err.message },
+      ...this.v2Quote(requirement, err.message)
+    };
+  }
+  /** The v2 half of a dual-stack 402 (see advertiseV2), or nothing. */
+  v2Quote(requirement, error) {
+    if (!this.advertiseV2) return {};
+    return {
+      paymentRequiredHeader: encodeBase64Json(buildPaymentRequiredV2(requirement, error))
+    };
+  }
+};
+function createGate(options) {
+  return new Gate(options);
+}
+function replayKey(paymentHeader) {
+  return createHash("sha256").update(paymentHeader).digest("hex");
+}
+function messageOf2(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function secondsUntil(atMs, nowMs) {
+  return Math.max(1, Math.ceil((atMs - nowMs) / 1e3));
+}
+
+// src/node.ts
+function gateMiddleware(gate, options = {}) {
+  return (req, res, next) => {
+    void (async () => {
+      const origin = options.origin ?? `http://${req.headers.host ?? "localhost"}`;
+      const url = new URL(req.url ?? "/", origin).toString();
+      const raw = req.headers["payment-signature"] ?? req.headers["x-payment"];
+      const payment = (Array.isArray(raw) ? raw[0] : raw) ?? null;
+      const outcome = await gate.handle({ method: req.method ?? "GET", url, payment });
+      options.onOutcome?.(outcome, req);
+      if (outcome.kind === "open") return next();
+      if (outcome.kind === "paid") {
+        res.setHeader("X-PAYMENT-RESPONSE", outcome.settlementHeader);
+        res.setHeader("PAYMENT-RESPONSE", outcome.settlementHeader);
+        return next();
+      }
+      res.writeHead(outcome.status, {
+        "content-type": "application/json",
+        ...outcome.paymentRequiredHeader !== void 0 ? { "payment-required": outcome.paymentRequiredHeader } : {},
+        ...outcome.kind === "refused" && outcome.retryAfterSeconds !== void 0 ? { "retry-after": String(outcome.retryAfterSeconds) } : {}
+      });
+      res.end(JSON.stringify(outcome.body));
+    })().catch((err) => {
+      const message = err instanceof Error ? err.message : String(err);
+      if (!res.headersSent) res.writeHead(500, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: "internal_error", message }));
+    });
+  };
+}
+
+// src/fetch.ts
+var defaultServe = () => new Response(JSON.stringify({ ok: true }), {
+  status: 200,
+  headers: { "content-type": "application/json" }
+});
+function createGatedFetch(gate, options = {}) {
+  const serve = options.serve ?? defaultServe;
+  return async (input, init) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+    const method = init?.method ?? (input instanceof Request ? input.method : "GET");
+    const headers = new Headers(
+      init?.headers ?? (input instanceof Request ? input.headers : void 0)
+    );
+    const outcome = await gate.handle({
+      method,
+      url,
+      // Dual-stack: v2 payers send PAYMENT-SIGNATURE, v1 payers X-PAYMENT.
+      payment: headers.get("PAYMENT-SIGNATURE") ?? headers.get("X-PAYMENT")
+    });
+    if (outcome.kind === "open") return serve({ url, method });
+    if (outcome.kind === "paid") {
+      const response = await serve({ url, method });
+      const merged = new Headers(response.headers);
+      merged.set("X-PAYMENT-RESPONSE", outcome.settlementHeader);
+      merged.set("PAYMENT-RESPONSE", outcome.settlementHeader);
+      return new Response(response.body, { status: response.status, headers: merged });
+    }
+    return new Response(JSON.stringify(outcome.body), {
+      status: outcome.status,
+      headers: {
+        "content-type": "application/json",
+        ...outcome.paymentRequiredHeader !== void 0 ? { "payment-required": outcome.paymentRequiredHeader } : {},
+        ...outcome.kind === "refused" && outcome.retryAfterSeconds !== void 0 ? { "retry-after": String(outcome.retryAfterSeconds) } : {}
+      }
+    });
+  };
+}
+
+export { Gate, GateError, InMemoryGateStore, RailsUnreachableError, buildPaymentRequiredV2, caip2Of, createGate, createGatedFetch, encodeBase64Json, facilitatorClientRails, gateMiddleware, inspectPaymentHeader, matchRoute, mockFacilitatorRails, requirementFor, routeDecimals, sameNetwork, v2Requirements, validateVelocity };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map