@absol-labs/agent 0.11.0 → 0.12.0-rc.1

package/src/x402-opener/terms.ts

@@ -0,0 +1,300 @@
+import { getAddress, isAddress, isHex, type Address, type Hex } from "viem";
+
+/**
+ * Shared vocabulary of the x402 v2 escrow-opener path (metrik-agent#116).
+ *
+ * A standard x402 v2 `exact` payment (an EIP-3009 `transferWithAuthorization`)
+ * is settled through the ownerless `X402StreamOpenerFactory`
+ * (metrik-contracts#48): the x402 `payTo` is the CREATE2 address of the opener
+ * for one immutable set of stream {@link OpenerTerms}, so the payer's signature
+ * (which binds `to`) commits to those terms, and the opener turns the payment
+ * into an ordinary `StreamEscrowV2` stream with `deposit = amount`.
+ *
+ * This module has no network or package side effects: it is the pure,
+ * dependency-free part shared by the facilitator and the gateway.
+ */
+
+/** Scheme name. The standard x402 `exact` scheme, nothing Metrik-specific. */
+export const OPENER_SCHEME = "exact" as const;
+
+/*
+ * Network, USDC, escrow, factory and oracle defaults are NOT constants here:
+ * they come from the `@absol-labs/sdk` network registry (see `../network.ts`),
+ * so a new deployment is a registry change, never an edit to this module.
+ */
+
+/** Public docs for the x402 opener path, linked from the 402. */
+export const DEFAULT_OPENER_DOCS_URL =
+  "https://github.com/Absol-Labs/metrik-agent/blob/main/docs/x402.md";
+
+/** Longest informational link accepted in `extra.metrikStreamOpener`. */
+const MAX_LINK_LENGTH = 2048;
+
+/**
+ * Key under `PaymentRequirements.extra` that carries the opener terms. The
+ * facilitator reads the terms ONLY from here, recomputes the opener address
+ * on-chain and requires it to equal `payTo`, so a tampered value can never
+ * redirect funds: it just fails verification.
+ */
+export const OPENER_EXTRA_KEY = "metrikStreamOpener" as const;
+
+/** `uint64` ceiling for `maxDuration`. */
+const MAX_UINT64 = (1n << 64n) - 1n;
+
+/** Immutable per-listing stream terms, mirroring the Solidity `Terms` struct. */
+export interface OpenerTerms {
+  readonly operator: Address;
+  readonly serviceRef: Hex;
+  /** USDC base units per second. */
+  readonly ratePerSecond: bigint;
+  /** Seconds. */
+  readonly maxDuration: bigint;
+}
+
+/** JSON-safe projection of {@link OpenerTerms} plus the factory that prices them. */
+export interface OpenerTermsExtra {
+  readonly factory: Address;
+  readonly operator: Address;
+  readonly serviceRef: Hex;
+  readonly ratePerSecond: string;
+  readonly maxDuration: string;
+  /**
+   * Informational only (metrik-agent#119): where the payer gets unearned money
+   * back without ETH, as a template containing `{streamId}`. Never used for
+   * settlement; the facilitator validates it is an http(s) link and ignores it.
+   */
+  readonly refundUrl?: string;
+  /** Informational only: docs for this payment path. */
+  readonly docsUrl?: string;
+}
+
+/** True for an absolute http(s) URL of sane length. */
+export function isHttpLink(value: unknown): value is string {
+  if (typeof value !== "string" || value.length > MAX_LINK_LENGTH) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" || url.protocol === "http:";
+  } catch {
+    return false;
+  }
+}
+
+export class InvalidOpenerTermsError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidOpenerTermsError";
+  }
+}
+
+/** Parses a non-negative base-10 integer string. Throws on anything else. */
+export function parseUintString(value: unknown, field: string): bigint {
+  if (typeof value !== "string" || !/^(0|[1-9]\d*)$/.test(value)) {
+    throw new InvalidOpenerTermsError(
+      `${field} must be a base-10 integer string without sign or leading zeros`,
+    );
+  }
+  return BigInt(value);
+}
+
+/**
+ * Validates terms the way the factory's `deploy` does (non-zero operator, rate
+ * and duration, `maxDuration` within `uint64`) plus the shape checks the
+ * contract cannot do for us (32-byte serviceRef).
+ */
+export function assertValidTerms(terms: OpenerTerms): void {
+  if (!isAddress(terms.operator, { strict: false })) {
+    throw new InvalidOpenerTermsError("operator must be an EVM address");
+  }
+  if (/^0x0{40}$/i.test(terms.operator)) {
+    throw new InvalidOpenerTermsError("operator must not be the zero address");
+  }
+  if (
+    !isHex(terms.serviceRef, { strict: true }) ||
+    terms.serviceRef.length !== 66
+  ) {
+    throw new InvalidOpenerTermsError("serviceRef must be a 32-byte hex value");
+  }
+  if (terms.ratePerSecond <= 0n) {
+    throw new InvalidOpenerTermsError("ratePerSecond must be > 0");
+  }
+  if (terms.maxDuration <= 0n || terms.maxDuration > MAX_UINT64) {
+    throw new InvalidOpenerTermsError(
+      "maxDuration must be > 0 and fit in uint64",
+    );
+  }
+}
+
+/** The largest deposit a stream on these terms can ever earn out: `rate * maxDuration`. */
+export function maxEarnable(terms: OpenerTerms): bigint {
+  return terms.ratePerSecond * terms.maxDuration;
+}
+
+/**
+ * The price (= stream deposit) must be positive and must not exceed what the
+ * stream can ever accrue. A deposit above `rate * maxDuration` would lock money
+ * the seller can never earn, reclaimable only by a second buyer action.
+ */
+export function assertValidPrice(price: bigint, terms: OpenerTerms): void {
+  if (price <= 0n) {
+    throw new InvalidOpenerTermsError("price must be > 0");
+  }
+  if (price > maxEarnable(terms)) {
+    throw new InvalidOpenerTermsError(
+      `price ${price} exceeds ratePerSecond * maxDuration (${maxEarnable(terms)})`,
+    );
+  }
+}
+
+export function termsToExtra(
+  factory: Address,
+  terms: OpenerTerms,
+): OpenerTermsExtra {
+  return {
+    factory: getAddress(factory),
+    operator: getAddress(terms.operator),
+    serviceRef: terms.serviceRef.toLowerCase() as Hex,
+    ratePerSecond: terms.ratePerSecond.toString(),
+    maxDuration: terms.maxDuration.toString(),
+  };
+}
+
+/**
+ * Reads opener terms from an untrusted `PaymentRequirements.extra`. Every field
+ * is re-validated; unknown keys under the opener object are rejected so the
+ * wire shape cannot drift silently.
+ */
+export function termsFromExtra(extra: unknown): {
+  readonly factory: Address;
+  readonly terms: OpenerTerms;
+} {
+  if (typeof extra !== "object" || extra === null) {
+    throw new InvalidOpenerTermsError("requirements.extra is missing");
+  }
+  const raw = (extra as Record<string, unknown>)[OPENER_EXTRA_KEY];
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new InvalidOpenerTermsError(
+      `requirements.extra.${OPENER_EXTRA_KEY} is missing`,
+    );
+  }
+  const record = raw as Record<string, unknown>;
+  const allowed = new Set([
+    "factory",
+    "operator",
+    "serviceRef",
+    "ratePerSecond",
+    "maxDuration",
+    "refundUrl",
+    "docsUrl",
+  ]);
+  for (const key of Object.keys(record)) {
+    if (!allowed.has(key)) {
+      throw new InvalidOpenerTermsError(
+        `unknown key ${key} in requirements.extra.${OPENER_EXTRA_KEY}`,
+      );
+    }
+  }
+  for (const link of ["refundUrl", "docsUrl"] as const) {
+    if (record[link] !== undefined && !isHttpLink(record[link])) {
+      throw new InvalidOpenerTermsError(
+        `${link} in requirements.extra.${OPENER_EXTRA_KEY} must be an http(s) URL`,
+      );
+    }
+  }
+  const { factory, operator, serviceRef } = record;
+  if (typeof factory !== "string" || !isAddress(factory, { strict: false })) {
+    throw new InvalidOpenerTermsError("factory must be an EVM address");
+  }
+  if (typeof operator !== "string" || !isAddress(operator, { strict: false })) {
+    throw new InvalidOpenerTermsError("operator must be an EVM address");
+  }
+  if (typeof serviceRef !== "string") {
+    throw new InvalidOpenerTermsError("serviceRef must be a string");
+  }
+  const terms: OpenerTerms = {
+    operator: getAddress(operator),
+    serviceRef: serviceRef as Hex,
+    ratePerSecond: parseUintString(record.ratePerSecond, "ratePerSecond"),
+    maxDuration: parseUintString(record.maxDuration, "maxDuration"),
+  };
+  assertValidTerms(terms);
+  return { factory: getAddress(factory), terms };
+}
+
+/** Chain id encoded in an `eip155:<id>` CAIP-2 identifier. Throws otherwise. */
+export function chainIdFromNetwork(network: string): number {
+  const match = /^eip155:([1-9]\d*)$/.exec(network);
+  if (match === null) {
+    throw new InvalidOpenerTermsError(
+      `network must be an eip155 CAIP-2 identifier, got ${network}`,
+    );
+  }
+  const chainId = Number(match[1]);
+  if (!Number.isSafeInteger(chainId)) {
+    throw new InvalidOpenerTermsError(`unsupported chain id in ${network}`);
+  }
+  return chainId;
+}
+
+/** Solidity-tuple view of terms for viem contract calls. */
+export function termsTuple(terms: OpenerTerms): {
+  readonly operator: Address;
+  readonly serviceRef: Hex;
+  readonly ratePerSecond: bigint;
+  readonly maxDuration: bigint;
+} {
+  return {
+    operator: getAddress(terms.operator),
+    serviceRef: terms.serviceRef,
+    ratePerSecond: terms.ratePerSecond,
+    maxDuration: terms.maxDuration,
+  };
+}
+
+/** A bazaar-shaped `{info: {input, output?}, schema?}` declaration. */
+export interface X402SchemaDeclaration {
+  readonly info: {
+    readonly input: { readonly type: "http" } & Record<string, unknown>;
+    readonly output?: Record<string, unknown>;
+  };
+  readonly schema?: Record<string, unknown>;
+}
+
+/** Largest accepted schema declaration, serialized bytes. */
+export const MAX_SCHEMA_DECLARATION_BYTES = 16 * 1024;
+
+/** Validates a bazaar-shaped schema declaration. Throws on anything else. */
+export function assertSchemaDeclaration(
+  value: unknown,
+): asserts value is X402SchemaDeclaration {
+  if (JSON.stringify(value ?? null).length > MAX_SCHEMA_DECLARATION_BYTES) {
+    throw new Error(
+      `the schema declaration exceeds ${MAX_SCHEMA_DECLARATION_BYTES} bytes`,
+    );
+  }
+  const record = value as Record<string, unknown> | null;
+  const info = record?.info as Record<string, unknown> | undefined;
+  const input = info?.input as Record<string, unknown> | undefined;
+  if (
+    typeof record !== "object" ||
+    record === null ||
+    Array.isArray(record) ||
+    typeof info !== "object" ||
+    info === null ||
+    typeof input !== "object" ||
+    input === null ||
+    input.type !== "http" ||
+    (info.output !== undefined &&
+      (typeof info.output !== "object" || info.output === null)) ||
+    (record.schema !== undefined &&
+      (typeof record.schema !== "object" || record.schema === null))
+  ) {
+    throw new Error(
+      'the schema declaration must be {info: {input: {type: "http", ...}, output?}, schema?}',
+    );
+  }
+  for (const key of Object.keys(record)) {
+    if (key !== "info" && key !== "schema") {
+      throw new Error(`unknown key ${key} in the schema declaration`);
+    }
+  }
+}

package/dist/gateway/x402-mode.d.ts

@@ -1,123 +0,0 @@
-import type { PaymentRequirements, SettleResponse, VerifyResponse } from "x402/types";
-import { type SignedListingPayee, type X402AssetConfig, type X402PaymentRequiredBody } from "../x402/payment-requirements.js";
-/**
- * Standard x402 mode for the seller-side gateway (Tier 1).
- *
- * The gateway already authorizes requests that carry a Metrik
- * `InvocationCapability` — a buyer with an open, funded, verified stream. That
- * path is untouched. This module adds a SECOND, independent way in: a request
- * with no capability gets an ordinary HTTP `402` carrying real x402
- * `PaymentRequirements`, so an agent holding nothing but `x402-fetch` can pay
- * per call without knowing Metrik exists.
- *
- * ## The two paths never overlap
- *
- * - capability header present -> stream path, exactly as before;
- * - capability header absent, x402 mode on -> `402` + `PaymentRequirements`;
- * - BOTH present -> rejected. A request that looks like both is ambiguous about
- *   which one is paying for it, and the failure mode of guessing is charging the
- *   caller twice for one call. Better a loud `400` than a silent double charge.
- *
- * ## The per-call price is the seller's, and is not signed
- *
- * `payTo` comes from the operator-signed descriptor (see
- * `../x402/payment-requirements.ts`). The price does not — the descriptor has no
- * per-call price field. It is the seller's own number on the seller's own
- * gateway, which is legitimate, but a buyer cannot cross-check it against the
- * registry the way they can cross-check the payee.
- */
-/** Request header carrying the x402 payment payload (x402 v1). */
-export declare const X402_PAYMENT_HEADER: "x-payment";
-/** Response header carrying the settlement result (x402 v1). */
-export declare const X402_PAYMENT_RESPONSE_HEADER: "x-payment-response";
-/** The facilitator the gateway delegates verify/settle to. */
-export interface X402FacilitatorClient {
-    verify(payload: unknown, requirements: PaymentRequirements): Promise<VerifyResponse>;
-    settle(payload: unknown, requirements: PaymentRequirements): Promise<SettleResponse>;
-}
-export interface HttpFacilitatorClientOptions {
-    /** Base URL of a facilitator exposing `/verify` and `/settle`. */
-    readonly url: string;
-    /**
-     * Shared secret for the facilitator's `/settle`. Sent as
-     * `Authorization: Bearer`. Metrik's own facilitator refuses to start a
-     * settling deployment without one, because `/settle` spends its gas.
-     */
-    readonly token?: string;
-    readonly headers?: Readonly<Record<string, string>>;
-    readonly timeoutMs?: number;
-    readonly fetch?: typeof globalThis.fetch;
-}
-/**
- * Talks to any x402 facilitator over HTTP — including Metrik's own
- * (`../x402/facilitator-server.ts`), which is the point: a seller who wires this
- * gateway to the Metrik facilitator gets a paywall whose payments stop when
- * their own delivery stops being verifiable.
- */
-export declare function createHttpFacilitatorClient(options: HttpFacilitatorClientOptions): X402FacilitatorClient;
-/** Builds the `PaymentRequirements` quoted for a given request. */
-export type X402Quoter = (request: {
-    readonly method: string;
-    readonly path: string;
-}) => readonly PaymentRequirements[] | Promise<readonly PaymentRequirements[]>;
-export interface ListingPriceQuoterOptions {
-    /** Projected from the OPERATOR-SIGNED descriptor. `payTo` comes from here. */
-    readonly listing: SignedListingPayee;
-    /** Public origin buyers reach this gateway on, e.g. `https://svc.example.com`. */
-    readonly resourceBaseUrl: string;
-    /** Per-call price in the asset's base units (micro-USDC). Seller-set, unsigned. */
-    readonly pricePerCallBaseUnits: bigint;
-    readonly chainId: number;
-    readonly description?: string;
-    readonly mimeType?: string;
-    readonly maxTimeoutSeconds?: number;
-    readonly asset?: X402AssetConfig;
-}
-/** One flat price per call, quoted against the request's own path. */
-export declare function createListingPriceQuoter(options: ListingPriceQuoterOptions): X402Quoter;
-export interface GatewayX402Mode {
-    readonly quote: X402Quoter;
-    readonly facilitator: X402FacilitatorClient;
-}
-/** Decoded, still-untrusted `X-PAYMENT` payload plus the quote it answers. */
-export interface AcceptedX402Payment {
-    readonly payload: unknown;
-    readonly requirements: PaymentRequirements;
-    readonly payer?: string;
-    /**
-     * Unix seconds after which the signed authorization is no longer settleable
-     * (`validBefore`), when the payload carried one.
-     *
-     * The upstream runs BEFORE settlement, so an upstream slower than this window
-     * would produce its side effects and then fail to be paid for. The server
-     * bounds the upstream call by this instead of letting that happen.
-     */
-    readonly validBefore?: number;
-}
-export type X402EvaluationOutcome = {
-    readonly outcome: "payment-required";
-    readonly body: X402PaymentRequiredBody;
-} | {
-    readonly outcome: "accepted";
-    readonly payment: AcceptedX402Payment;
-};
-/**
- * Evaluates the x402 half of a request. Returns either the `402` body to send or
- * an accepted payment to settle after the upstream has been called.
- */
-export declare function evaluateX402Request(request: {
-    readonly method: string;
-    readonly path: string;
-}, paymentHeader: string | undefined, mode: GatewayX402Mode): Promise<X402EvaluationOutcome>;
-/**
- * Seconds of headroom the settlement leg needs after the upstream returns.
- *
- * The x402 `exact` verifier rejects an authorization whose `validBefore` is less
- * than 6 s away, so an upstream allowed to run right up to the deadline would
- * hand back a response that can never be settled. This leaves room for that
- * check plus the settle round trip.
- */
-export declare const X402_SETTLEMENT_HEADROOM_SECONDS = 10;
-export declare function decodePaymentHeader(header: string): unknown;
-export declare function encodeSettleResponseHeader(response: SettleResponse): string;
-//# sourceMappingURL=x402-mode.d.ts.map

package/dist/gateway/x402-mode.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"x402-mode.d.ts","sourceRoot":"","sources":["../../src/gateway/x402-mode.ts"],"names":[],"mappings":"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"}

package/dist/gateway/x402-mode.js

@@ -1,212 +0,0 @@
-import { buildMetrikPaymentRequirements, buildX402PaymentRequiredBody, } from "../x402/payment-requirements.js";
-/**
- * Standard x402 mode for the seller-side gateway (Tier 1).
- *
- * The gateway already authorizes requests that carry a Metrik
- * `InvocationCapability` — a buyer with an open, funded, verified stream. That
- * path is untouched. This module adds a SECOND, independent way in: a request
- * with no capability gets an ordinary HTTP `402` carrying real x402
- * `PaymentRequirements`, so an agent holding nothing but `x402-fetch` can pay
- * per call without knowing Metrik exists.
- *
- * ## The two paths never overlap
- *
- * - capability header present -> stream path, exactly as before;
- * - capability header absent, x402 mode on -> `402` + `PaymentRequirements`;
- * - BOTH present -> rejected. A request that looks like both is ambiguous about
- *   which one is paying for it, and the failure mode of guessing is charging the
- *   caller twice for one call. Better a loud `400` than a silent double charge.
- *
- * ## The per-call price is the seller's, and is not signed
- *
- * `payTo` comes from the operator-signed descriptor (see
- * `../x402/payment-requirements.ts`). The price does not — the descriptor has no
- * per-call price field. It is the seller's own number on the seller's own
- * gateway, which is legitimate, but a buyer cannot cross-check it against the
- * registry the way they can cross-check the payee.
- */
-/** Request header carrying the x402 payment payload (x402 v1). */
-export const X402_PAYMENT_HEADER = "x-payment";
-/** Response header carrying the settlement result (x402 v1). */
-export const X402_PAYMENT_RESPONSE_HEADER = "x-payment-response";
-/**
- * Talks to any x402 facilitator over HTTP — including Metrik's own
- * (`../x402/facilitator-server.ts`), which is the point: a seller who wires this
- * gateway to the Metrik facilitator gets a paywall whose payments stop when
- * their own delivery stops being verifiable.
- */
-export function createHttpFacilitatorClient(options) {
-    const base = options.url.replace(/\/+$/, "");
-    const timeoutMs = options.timeoutMs ?? 10_000;
-    const doFetch = options.fetch ?? globalThis.fetch;
-    async function post(path, body) {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), timeoutMs);
-        try {
-            const response = await doFetch(`${base}${path}`, {
-                method: "POST",
-                headers: {
-                    "content-type": "application/json",
-                    ...(options.token === undefined
-                        ? {}
-                        : { authorization: `Bearer ${options.token}` }),
-                    ...(options.headers ?? {}),
-                },
-                body: JSON.stringify(body),
-                signal: controller.signal,
-            });
-            return await response.json();
-        }
-        finally {
-            clearTimeout(timer);
-        }
-    }
-    return {
-        async verify(payload, requirements) {
-            const result = (await post("/verify", {
-                x402Version: 1,
-                paymentPayload: payload,
-                paymentRequirements: requirements,
-            }));
-            // Fail closed: an unreadable facilitator answer is not a pass.
-            if (typeof result !== "object" || result === null) {
-                return { isValid: false, invalidReason: "unexpected_verify_error" };
-            }
-            return result;
-        },
-        async settle(payload, requirements) {
-            return (await post("/settle", {
-                x402Version: 1,
-                paymentPayload: payload,
-                paymentRequirements: requirements,
-            }));
-        },
-    };
-}
-/** One flat price per call, quoted against the request's own path. */
-export function createListingPriceQuoter(options) {
-    const base = new URL(options.resourceBaseUrl);
-    return (request) => [
-        buildMetrikPaymentRequirements({
-            listing: options.listing,
-            resource: new URL(request.path, base).toString(),
-            priceBaseUnits: options.pricePerCallBaseUnits,
-            chainId: options.chainId,
-            ...(options.description === undefined
-                ? {}
-                : { description: options.description }),
-            ...(options.mimeType === undefined ? {} : { mimeType: options.mimeType }),
-            ...(options.maxTimeoutSeconds === undefined
-                ? {}
-                : { maxTimeoutSeconds: options.maxTimeoutSeconds }),
-            ...(options.asset === undefined ? {} : { asset: options.asset }),
-        }),
-    ];
-}
-/**
- * Evaluates the x402 half of a request. Returns either the `402` body to send or
- * an accepted payment to settle after the upstream has been called.
- */
-export async function evaluateX402Request(request, paymentHeader, mode) {
-    const accepts = await mode.quote(request);
-    if (paymentHeader === undefined || paymentHeader.trim().length === 0) {
-        return {
-            outcome: "payment-required",
-            body: buildX402PaymentRequiredBody(accepts),
-        };
-    }
-    const payload = decodePaymentHeader(paymentHeader);
-    if (payload === undefined) {
-        return {
-            outcome: "payment-required",
-            body: buildX402PaymentRequiredBody(accepts, "X-PAYMENT header is not base64-encoded JSON"),
-        };
-    }
-    const requirements = selectRequirements(accepts, payload);
-    if (requirements === undefined) {
-        return {
-            outcome: "payment-required",
-            body: buildX402PaymentRequiredBody(accepts, "X-PAYMENT does not match any offered payment requirements"),
-        };
-    }
-    let verified;
-    try {
-        verified = await mode.facilitator.verify(payload, requirements);
-    }
-    catch (error) {
-        // An unreachable facilitator is a refusal, never a free call.
-        return {
-            outcome: "payment-required",
-            body: buildX402PaymentRequiredBody(accepts, `payment could not be verified: ${error instanceof Error ? error.message : "facilitator unreachable"}`),
-        };
-    }
-    if (!verified.isValid) {
-        return {
-            outcome: "payment-required",
-            body: buildX402PaymentRequiredBody(accepts, verified.invalidReason ?? "payment rejected by facilitator"),
-        };
-    }
-    // A Metrik facilitator reports up front whether it would actually broadcast
-    // this payment (asset allowlist, settlement scope, ...). Refusing HERE — before
-    // the upstream runs — is the difference between "the caller gets nothing" and
-    // "the caller gets the upstream's side effects for free and we cannot charge
-    // for them". A non-Metrik facilitator omits the field and nothing changes.
-    const annotation = verified.metrik;
-    if (annotation?.settleable === false) {
-        return {
-            outcome: "payment-required",
-            body: buildX402PaymentRequiredBody(accepts, `facilitator will not settle this payment: ${annotation.detail ?? "refused"}`),
-        };
-    }
-    const validBefore = readValidBefore(payload);
-    return {
-        outcome: "accepted",
-        payment: {
-            payload,
-            requirements,
-            ...(verified.payer === undefined ? {} : { payer: verified.payer }),
-            ...(validBefore === undefined ? {} : { validBefore }),
-        },
-    };
-}
-/** Reads the exact-EVM authorization deadline, if the payload has one. */
-function readValidBefore(payload) {
-    const authorization = payload?.payload?.authorization;
-    const raw = authorization?.validBefore;
-    if (typeof raw !== "string" && typeof raw !== "number") {
-        return undefined;
-    }
-    const parsed = Number(raw);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
-}
-/**
- * Seconds of headroom the settlement leg needs after the upstream returns.
- *
- * The x402 `exact` verifier rejects an authorization whose `validBefore` is less
- * than 6 s away, so an upstream allowed to run right up to the deadline would
- * hand back a response that can never be settled. This leaves room for that
- * check plus the settle round trip.
- */
-export const X402_SETTLEMENT_HEADROOM_SECONDS = 10;
-/** Matches the payload's scheme+network against the quotes actually offered. */
-function selectRequirements(accepts, payload) {
-    if (typeof payload !== "object" || payload === null) {
-        return undefined;
-    }
-    const { scheme, network } = payload;
-    return accepts.find((candidate) => candidate.scheme === scheme && candidate.network === network);
-}
-export function decodePaymentHeader(header) {
-    try {
-        const decoded = Buffer.from(header.trim(), "base64").toString("utf8");
-        const parsed = JSON.parse(decoded);
-        return typeof parsed === "object" && parsed !== null ? parsed : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-export function encodeSettleResponseHeader(response) {
-    return Buffer.from(JSON.stringify(response), "utf8").toString("base64");
-}
-//# sourceMappingURL=x402-mode.js.map

package/dist/gateway/x402-mode.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"x402-mode.js","sourceRoot":"","sources":["../../src/gateway/x402-mode.ts"],"names":[],"mappings":"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"}