@obbyx/sdk 0.1.0 → 0.2.0

package/src/seller/paywall.ts

@@ -43,6 +43,17 @@ import {
   operationFingerprint,
 } from './quote.js';
 import type { ConsumedProofsStore, StoredResponse } from './consumed-proofs.js';
+import {
+  type PaywallCorsOptions,
+  allowOrigin,
+  exposePaymentHeaders,
+  preflightHandler,
+} from './cors.js';
+import {
+  DEFAULT_MAX_TIMEOUT_SECONDS,
+  DEFAULT_QUOTE_TTL_SECONDS,
+  DEFAULT_SERVING_LEASE_SECONDS,
+} from './defaults.js';
 
 /**
  * Express paywall for x402 `exact` payments on Obyte (seller side).
@@ -117,11 +128,15 @@ export interface ObytePaywallOptions {
   readonly paymentIdentifier?: { readonly required: boolean };
   /** Enables batch-settlement (AA payment channels) offers; requires a running seller watcher. */
   readonly batch?: { readonly minChannelTimeoutSeconds: number };
+  /**
+   * CORS for browser clients on another origin (x402 HTTP transport, "Browser
+   * clients"). Also mount {@link ObytePaywall.preflight} before the routes.
+   * Without it, same-origin pages and non-browser clients work as before.
+   */
+  readonly cors?: PaywallCorsOptions;
   readonly now?: () => number;
 }
 
-const EXPOSE = 'PAYMENT-REQUIRED, PAYMENT-RESPONSE';
-
 export class ObytePaywall {
   private readonly log: Logger;
   private readonly now: () => number;
@@ -140,6 +155,15 @@ export class ObytePaywall {
     this.now = options.now ?? (() => Math.floor(Date.now() / 1000));
   }
 
+  /**
+   * Answers CORS preflight requests (`app.use(paywall.preflight())`); a no-op
+   * without the `cors` option. Preflights never require payment.
+   */
+  preflight(): RequestHandler {
+    const cors = this.options.cors;
+    return cors === undefined ? (_req, _res, next) => next() : preflightHandler(cors);
+  }
+
   /** Wraps a handler so it only runs after a settled payment. */
   paid(route: PaidRouteOptions, handler: PaidHandler): RequestHandler {
     const asset = route.price.asset ?? 'base';
@@ -160,7 +184,8 @@ export class ObytePaywall {
     price: { asset: string; amount: string },
     handler: PaidHandler,
   ): Promise<void> {
-    res.setHeader('Access-Control-Expose-Headers', EXPOSE);
+    exposePaymentHeaders(res);
+    if (this.options.cors !== undefined) allowOrigin(req, res, this.options.cors);
     res.setHeader('Cache-Control', 'private, no-store');
     const header = req.get('payment-signature');
     if (header === undefined) return this.paymentRequired(req, res, route, price);
@@ -221,12 +246,13 @@ export class ObytePaywall {
       // A proof left in `serving` by a crashed process is recovered after the lease.
       if (
         record.state === 'serving' &&
-        store.reclaimStale(key, this.options.servingLeaseSeconds ?? 300)
+        store.reclaimStale(key, this.options.servingLeaseSeconds ?? DEFAULT_SERVING_LEASE_SECONDS)
       ) {
         this.log.warn('recovered a payment stuck in serving (lease expired)');
         record = store.get(key) ?? record;
       }
       if (!bindingsEqual(record.binding, binding)) {
+        res.setHeader('PAYMENT-RESPONSE', this.refusal('invalid_payment_reused'));
         res.status(402).json({ error: 'invalid_payment_reused' });
         return;
       }
@@ -283,8 +309,12 @@ export class ObytePaywall {
       const settled = await this.settleWithWait(payload, accepted);
       const paymentResponse = encodePaymentResponseHeader(settled);
       if (settled.success) {
-        store.transition(key, 'settling', 'paid_not_served', { paymentResponse });
         this.log.info({ transaction: settled.transaction }, 'payment settled');
+        if (store.markSettled(key, binding, paymentResponse) === 'served') {
+          // A concurrent request with the same payment already served it.
+          const served = store.get(key);
+          return this.send(res, served?.response ?? null, served?.paymentResponse ?? null);
+        }
         return this.serve(req, res, key, paymentResponse, handler);
       }
       if (settled.errorReason === 'settlement_pending') {
@@ -299,7 +329,9 @@ export class ObytePaywall {
       }
       if (settled.transaction === '') {
         // Rejected before reaching the network: the proof was not consumed.
-        store.forget(key, 'settling');
+        // Only the request that created the row removes it: a concurrent
+        // request with the same payment may be settling it right now.
+        if (created) store.forget(key, 'settling');
       } else {
         store.transition(key, 'settling', 'failed', { paymentResponse });
       }
@@ -447,7 +479,14 @@ export class ObytePaywall {
     price: { asset: string; amount: string },
     error?: string,
   ): void {
-    const quote = newQuote(this.now(), this.options.quoteTtlSeconds ?? 300);
+    // A refused payment that was never settled: say so explicitly (success:
+    // false, empty transaction) so the client knows it was NOT used and can
+    // release its budget and its channel voucher. A settle failure already
+    // set its own PAYMENT-RESPONSE.
+    if (error !== undefined && !res.hasHeader('PAYMENT-RESPONSE')) {
+      res.setHeader('PAYMENT-RESPONSE', this.refusal(error));
+    }
+    const quote = newQuote(this.now(), this.options.quoteTtlSeconds ?? DEFAULT_QUOTE_TTL_SECONDS);
     const facts = this.requestFacts(req, route);
     const terms = this.terms(price);
     const accepts: PaymentRequirements[] = this.schemesFor(route).map((scheme) => ({
@@ -456,7 +495,7 @@ export class ObytePaywall {
       asset: price.asset,
       amount: price.amount,
       payTo: this.options.payTo,
-      maxTimeoutSeconds: this.options.maxTimeoutSeconds ?? 300,
+      maxTimeoutSeconds: this.options.maxTimeoutSeconds ?? DEFAULT_MAX_TIMEOUT_SECONDS,
       extra: {
         binding: offerBinding(this.options, scheme, quote, facts, terms),
         ...quote,
@@ -493,6 +532,16 @@ export class ObytePaywall {
     res.status(402).json(body);
   }
 
+  /** PAYMENT-RESPONSE of a payment refused before settlement (not used, nothing charged). */
+  private refusal(errorReason: string): string {
+    return encodePaymentResponseHeader({
+      success: false,
+      errorReason,
+      transaction: '',
+      network: this.options.network as PaymentRequirements['network'],
+    });
+  }
+
   private requestFacts(req: Request, route: PaidRouteOptions): RequestFacts {
     return {
       method: req.method,

package/src/seller/x402-server.ts

@@ -9,6 +9,7 @@ import type {
   SchemeServerHooks,
 } from '@x402/core/types';
 import {
+  CHANNEL_BASE_AA,
   ObbyxError,
   fromDisplay,
   getNetwork,
@@ -17,13 +18,24 @@ import {
   parseAmount,
 } from '@obbyx/obyte';
 import { type Logger, moduleLogger } from '@obbyx/obyte/logger';
-import { EXACT_SCHEME, bindingsEqual, exactExtraSchema } from '@obbyx/x402-obyte';
+import {
+  BATCH_SCHEME,
+  EXACT_SCHEME,
+  batchExtraSchema,
+  bindingsEqual,
+  canonical,
+  exactExtraSchema,
+  sha256Hex,
+} from '@obbyx/x402-obyte';
 import type { ConsumedProofsStore } from './consumed-proofs.js';
+import { DEFAULT_QUOTE_TTL_SECONDS, DEFAULT_SERVING_LEASE_SECONDS } from './defaults.js';
 import { type Quote, bodyHashOf, newQuote, offerBinding } from './quote.js';
 
 /**
- * Obyte `exact` for the OFFICIAL x402 resource server (`@x402/core/server`,
- * `@x402/express`, `@x402/hono`, …): a SchemeNetworkServer.
+ * Obyte schemes for the OFFICIAL x402 resource server (`@x402/core/server`,
+ * `@x402/express`, `@x402/hono`, …): SchemeNetworkServer implementations for
+ * `exact` ({@link ObyteExactServer}) and `batch-settlement`
+ * ({@link ObyteBatchServer}), sharing {@link ObyteSchemeServer}.
  *
  * - Binding (I1/I2): `enrichPaymentRequiredResponse` adds a per-request HMAC
  *   binding + quote to every offer. On a paid request it recomputes the HMAC
@@ -37,7 +49,9 @@ import { type Quote, bodyHashOf, newQuote, offerBinding } from './quote.js';
  *   Unlike `@obbyx/sdk`'s ObytePaywall, a repeated request gets a 402 instead
  *   of the stored response (the official middleware cannot replay responses).
  */
-export interface ObyteExactServerOptions {
+export interface ObyteSchemeServerOptions {
+  /** How long a request may hold a payment in `serving` before a retry takes over (default 300 s). */
+  readonly servingLeaseSeconds?: number;
   readonly sellerId: string;
   /** HMAC key for bindings (≥ 32 bytes). */
   readonly secret: string | Uint8Array;
@@ -69,8 +83,32 @@ function requestOf(transportContext: unknown): RequestLike | undefined {
   };
 }
 
-export class ObyteExactServer implements SchemeNetworkServer {
-  readonly scheme = EXACT_SCHEME;
+/** @deprecated Use {@link ObyteSchemeServerOptions}. */
+export type ObyteExactServerOptions = ObyteSchemeServerOptions;
+
+/** Options of {@link ObyteBatchServer}. */
+export interface ObyteBatchServerOptions extends ObyteSchemeServerOptions {
+  /** Minimum channel dispute window the seller accepts (seconds); must match the facilitator's. */
+  readonly minChannelTimeoutSeconds: number;
+}
+
+/** Per-scheme parts of an Obyte resource-server scheme. */
+export interface ObyteSchemeSpec {
+  readonly scheme: typeof EXACT_SCHEME | typeof BATCH_SCHEME;
+  /** `extra` fields the scheme adds to every offer besides binding and quote. */
+  readonly staticExtra: Record<string, unknown>;
+  /** Parses the quote fields of the accepted offer. */
+  readonly acceptedExtra: (extra: unknown) => {
+    readonly binding: string;
+    readonly quoteId: string;
+    readonly validUntil: number;
+  };
+  /** Proof id and key kind of a payment payload (undefined when malformed). */
+  readonly proofOf: (payload: Record<string, unknown>) => { kind: string; id: string } | undefined;
+}
+
+export abstract class ObyteSchemeServer implements SchemeNetworkServer {
+  readonly scheme: string;
   readonly defaultAssetTransferMethod = 'default';
   readonly paymentFlows = {
     default: { supported: ['upfront'] as const, default: 'upfront' as const },
@@ -80,24 +118,25 @@ export class ObyteExactServer implements SchemeNetworkServer {
   private readonly log: Logger;
   private readonly now: () => number;
 
-  constructor(private readonly options: ObyteExactServerOptions) {
-    this.log = moduleLogger(options.logger, 'sdk.x402-server', { scheme: EXACT_SCHEME });
+  protected constructor(
+    private readonly options: ObyteSchemeServerOptions,
+    private readonly spec: ObyteSchemeSpec,
+  ) {
+    this.scheme = spec.scheme;
+    this.log = moduleLogger(options.logger, 'sdk.x402-server', { scheme: spec.scheme });
     this.now = options.now ?? (() => Math.floor(Date.now() / 1000));
     this.schemeHooks = {
       onBeforeVerify: async (ctx) => {
-        const unit = (ctx.paymentPayload.payload as { unit?: { unit?: unknown } }).unit?.unit;
+        const key = this.keyOf(ctx);
         const binding = (ctx.requirements.extra as { binding?: unknown }).binding;
-        if (typeof unit !== 'string' || typeof binding !== 'string') {
+        if (key === undefined || typeof binding !== 'string') {
           return { abort: true, reason: 'invalid_payload' };
         }
-        const { record } = this.options.proofs.begin(
-          this.key(ctx.requirements.network, unit),
-          binding,
-        );
+        const { record } = this.options.proofs.begin(key, binding);
         if (!bindingsEqual(record.binding, binding))
           return { abort: true, reason: 'invalid_payment_reused' };
         if (record.state === 'served') {
-          this.log.warn({ proofId: unit }, 'payment already served a request; refused');
+          this.log.warn({ proofId: key }, 'payment already served a request; refused');
           return { abort: true, reason: 'payment_already_used' };
         }
         return undefined;
@@ -109,7 +148,16 @@ export class ObyteExactServer implements SchemeNetworkServer {
       onBeforeSettle: async (ctx) => {
         const key = this.keyOf(ctx);
         if (key === undefined) return { abort: true, reason: 'invalid_payload' };
-        if (this.options.proofs.transition(key, 'settling', 'serving')) return undefined;
+        const proofs = this.options.proofs;
+        // A claim left behind by a crashed process is taken over after the lease.
+        proofs.reclaimStale(key, this.options.servingLeaseSeconds ?? DEFAULT_SERVING_LEASE_SECONDS);
+        if (
+          proofs.transition(key, 'settling', 'serving') ||
+          // settled earlier, but the handler failed: serve it now (settle is idempotent)
+          proofs.transition(key, 'paid_not_served', 'serving')
+        ) {
+          return undefined;
+        }
         const state = this.options.proofs.get(key)?.state;
         this.log.warn({ state }, 'payment already in use by another request; refused');
         return {
@@ -125,6 +173,21 @@ export class ObyteExactServer implements SchemeNetworkServer {
         if (ctx.result.success) this.options.proofs.transition(key, 'serving', 'served');
         else this.options.proofs.transition(key, 'serving', 'settling');
       },
+      // The handler failed or threw after the payment was settled (upfront):
+      // the payment stays usable for the SAME operation instead of "already used".
+      onVerifiedPaymentCanceled: async (ctx) => {
+        const key = this.keyOf(ctx);
+        if (key === undefined) return;
+        if (ctx.settledPhases.includes('before-handler')) {
+          this.options.proofs.transition(key, 'served', 'paid_not_served');
+        } else {
+          this.options.proofs.transition(key, 'serving', 'settling');
+        }
+        this.log.warn(
+          { reason: ctx.reason },
+          'paid request not served; the same payment can retry',
+        );
+      },
       onSettleFailure: async (ctx) => {
         const key = this.keyOf(ctx);
         if (key !== undefined) this.options.proofs.transition(key, 'serving', 'settling');
@@ -156,7 +219,7 @@ export class ObyteExactServer implements SchemeNetworkServer {
     return asset === 'base' ? 9 : undefined;
   }
 
-  /** Nothing to add from /supported for exact; the per-request fields come from the enrich hook. */
+  /** Nothing to add from /supported; the per-request fields come from the enrich hook. */
   async enhancePaymentRequirements(
     requirements: PaymentRequirements,
   ): Promise<PaymentRequirements> {
@@ -169,20 +232,21 @@ export class ObyteExactServer implements SchemeNetworkServer {
   ): Promise<PaymentRequirements[]> => {
     const request = requestOf(ctx.transportContext);
     if (request === undefined)
-      throw new ObbyxError('no_request', 'Obyte exact needs the HTTP request context');
+      throw new ObbyxError('no_request', `Obyte ${this.scheme} needs the HTTP request context`);
     const accepted = this.acceptedQuote(request);
     return ctx.requirements.map((req) => {
-      if (req.scheme !== EXACT_SCHEME) return req;
+      if (req.scheme !== this.spec.scheme) return req;
       const quote =
         accepted !== undefined &&
         bindingsEqual(this.bindingFor(req, request, accepted), accepted.binding)
           ? accepted
           : undefined;
-      if (quote !== undefined) return { ...req, extra: { ...req.extra, ...quote } };
-      const fresh = newQuote(this.now(), this.options.quoteTtlSeconds ?? 300);
+      const extra = { ...req.extra, ...this.spec.staticExtra };
+      if (quote !== undefined) return { ...req, extra: { ...extra, ...quote } };
+      const fresh = newQuote(this.now(), this.options.quoteTtlSeconds ?? DEFAULT_QUOTE_TTL_SECONDS);
       return {
         ...req,
-        extra: { ...req.extra, binding: this.bindingFor(req, request, fresh), ...fresh },
+        extra: { ...extra, binding: this.bindingFor(req, request, fresh), ...fresh },
       };
     });
   };
@@ -190,10 +254,10 @@ export class ObyteExactServer implements SchemeNetworkServer {
   private acceptedQuote(request: RequestLike) {
     if (request.paymentHeader === undefined) return undefined;
     try {
-      const extra = exactExtraSchema.safeParse(
-        decodePaymentSignatureHeader(request.paymentHeader).accepted?.extra,
-      );
-      return extra.success ? extra.data : undefined;
+      const accepted = decodePaymentSignatureHeader(request.paymentHeader).accepted;
+      if (accepted?.scheme !== this.spec.scheme) return undefined;
+      const extra = this.spec.acceptedExtra(accepted.extra);
+      return { quoteId: extra.quoteId, validUntil: extra.validUntil, binding: extra.binding };
     } catch {
       return undefined;
     }
@@ -202,7 +266,7 @@ export class ObyteExactServer implements SchemeNetworkServer {
   private bindingFor(req: PaymentRequirements, request: RequestLike, quote: Quote): string {
     return offerBinding(
       this.options,
-      EXACT_SCHEME,
+      this.spec.scheme,
       quote,
       { method: request.method, url: request.url, bodyHash: bodyHashOf(request.body) },
       { network: req.network, asset: req.asset, amount: req.amount, payTo: req.payTo },
@@ -214,11 +278,46 @@ export class ObyteExactServer implements SchemeNetworkServer {
     paymentPayload: { payload: Record<string, unknown> };
     requirements: { network: string };
   }): string | undefined {
-    const unit = (ctx.paymentPayload.payload as { unit?: { unit?: unknown } }).unit?.unit;
-    return typeof unit === 'string' ? this.key(ctx.requirements.network, unit) : undefined;
+    const proof = this.spec.proofOf(ctx.paymentPayload.payload);
+    return proof === undefined
+      ? undefined
+      : networkKey(getNetwork(ctx.requirements.network), proof.kind, proof.id);
   }
+}
 
-  private key(network: string, unit: string): string {
-    return networkKey(getNetwork(network), 'unit', unit);
+/** `exact`: the proof is the unit (key `<network>:unit:<hash>`, as ObytePaywall). */
+export class ObyteExactServer extends ObyteSchemeServer {
+  constructor(options: ObyteSchemeServerOptions) {
+    super(options, {
+      scheme: EXACT_SCHEME,
+      staticExtra: {},
+      acceptedExtra: (extra) => exactExtraSchema.parse(extra),
+      proofOf: (payload) => {
+        const unit = (payload as { unit?: { unit?: unknown } }).unit?.unit;
+        return typeof unit === 'string' ? { kind: 'unit', id: unit } : undefined;
+      },
+    });
+  }
+}
+
+/**
+ * `batch-settlement` (AA payment channels): the proof is the voucher (key
+ * `<network>:voucher:<sha256 of the canonical signed package>`, as
+ * ObytePaywall). Offers carry the channel base AA and the minimum dispute
+ * window. Needs a facilitator with batch-settlement and the seller's watcher.
+ */
+export class ObyteBatchServer extends ObyteSchemeServer {
+  constructor(options: ObyteBatchServerOptions) {
+    super(options, {
+      scheme: BATCH_SCHEME,
+      staticExtra: { baseAa: CHANNEL_BASE_AA, minTimeout: options.minChannelTimeoutSeconds },
+      acceptedExtra: (extra) => batchExtraSchema.parse(extra),
+      proofOf: (payload) => {
+        const pkg = payload['signedPackage'];
+        return pkg !== null && typeof pkg === 'object'
+          ? { kind: 'voucher', id: sha256Hex(canonical(pkg)) }
+          : undefined;
+      },
+    });
   }
 }