@absol-labs/agent 0.9.1 → 0.11.0

package/dist/x402/relayer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relayer.js","sourceRoot":"","sources":["../../src/x402/relayer.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,IAAI,EACJ,aAAa,GAGd,MAAM,MAAM,CAAC;AACd,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAa9E;;;;;;;;;GASG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAoC,MAAM,CAAC,MAAM,CAAC;IACxE,IAAI,EAAE,IAAI;IACV,KAAK,EAAE,WAAW;CACnB,CAAC,CAAC;AASH,SAAS,QAAQ,CAAC,OAAe;IAC/B,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,sCAAsC,OAAO,EAAE,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAyB;IAEzB,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,IAAI,KAAK,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,kBAAkB,CAAC;QAChC,KAAK;QACL,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;KAChC,CAAC,CAAC;IACH,OAAO;QACL,MAAM,CACJ,OAAuB,EACvB,YAAiC;YAEjC,OAAO,UAAU,CACf,MAA0C,EAC1C,OAAO,EACP,YAAY,CACb,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAYD;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAA2B;IAE3B,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,IAAI,KAAK,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,mBAAmB,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,kBAAkB,CAAC;QAChC,OAAO;QACP,KAAK;QACL,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;KAChC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IACzB,OAAO;QACL,MAAM,CACJ,OAAuB,EACvB,YAAiC;YAEjC,OAAO,UAAU,CACf,MAA0C,EAC1C,OAAO,EACP,YAAY,CACb,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,cAAc,CAAC,UAAe;IAC5C,OAAO,mBAAmB,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC;AACjD,CAAC"}

package/dist/x402/resource-index.d.ts

@@ -0,0 +1,75 @@
+import { type DiscoverServicesOptions, type ServiceListing } from "../discovery/registry.js";
+import type { SignedListingPayee } from "./payment-requirements.js";
+/**
+ * Maps an x402 `PaymentRequirements.resource` URL onto the Metrik listing that
+ * serves it — the step that decides whether Metrik has any business having an
+ * opinion about a payment at all.
+ *
+ * ## Derived, never supplied
+ *
+ * The only thing taken from the request is the `resource` URL itself, because
+ * the x402 wire format gives the facilitator nothing else to key on. Everything
+ * the verdict is actually computed from — which listing that URL belongs to, the
+ * operator address on it, and the delivery record for it — is resolved HERE,
+ * from Metrik's own verified view of the registry. In particular the
+ * `extra.metrikServiceRef` hint that `buildMetrikPaymentRequirements` publishes
+ * is deliberately ignored: it rides inside a caller-supplied body, and reading
+ * it would let a caller choose which service's delivery record gets checked.
+ *
+ * ## Origin matching, and why not path matching
+ *
+ * A listing owns an ORIGIN (scheme + host + port). Matching on origin means a
+ * seller does not have to re-register every route, and it cannot over-reach: two
+ * listings never share an origin, because the origin is what the oracle probes
+ * and what `serviceRef` is derived from. A resource whose origin matches no
+ * listing is simply not ours.
+ */
+export interface ResolvedMetrikResource extends SignedListingPayee {
+    /** The listing, as verified by `discoverServices` (EIP-712 signer recovered). */
+    readonly listing: ServiceListing;
+    /** Which of the listing's signed origins the resource matched. */
+    readonly matchedOrigin: string;
+}
+export type ResourceIndexStatus = "resolved" | "not-listed"
+/**
+ * Two or more signed listings claim this origin, so there is no single right
+ * answer about whose delivery record applies.
+ *
+ * Picking one — which "first claimant wins" did — is the origin-squatting
+ * primitive: a second listing claiming a victim's origin could take over the
+ * victim's gate and permanently refuse their payments. Not exploitable while
+ * listing insertion requires an operator-held key, but "unresolvable" costs
+ * nothing and removes the primitive before registration ever opens.
+ */
+ | "ambiguous" | "registry-unavailable";
+export interface ResourceLookup {
+    readonly status: ResourceIndexStatus;
+    readonly resource?: ResolvedMetrikResource;
+}
+export interface MetrikResourceIndex {
+    /** Never throws: an unreachable registry is a status, not an exception. */
+    lookup(resourceUrl: string): Promise<ResourceLookup>;
+}
+/** How long a registry snapshot is reused before a refresh is attempted. */
+export declare const DEFAULT_RESOURCE_INDEX_REFRESH_MS = 60000;
+/**
+ * How long a stale snapshot keeps being served after refreshes start failing.
+ * Serving a stale listing is safe in a way that serving a stale DELIVERY verdict
+ * is not: listings change on a human timescale (a new signed descriptor), and
+ * the fields used from them — `operator`, `serviceRef` — are the stable ones. The
+ * live verdict is always fetched fresh by the delivery oracle.
+ */
+export declare const DEFAULT_RESOURCE_INDEX_MAX_STALE_MS: number;
+export interface RegistryResourceIndexOptions {
+    readonly discover?: () => Promise<readonly ServiceListing[]>;
+    readonly discoverOptions?: DiscoverServicesOptions;
+    readonly refreshMs?: number;
+    readonly maxStaleMs?: number;
+    readonly now?: () => number;
+}
+export declare function createRegistryResourceIndex(options?: RegistryResourceIndexOptions): MetrikResourceIndex;
+/** Every origin the SIGNED record claims for a listing. */
+export declare function signedOriginsOf(listing: ServiceListing): readonly string[];
+/** Normalized `scheme://host[:port]`, or `undefined` if not a usable URL. */
+export declare function originOf(url: string): string | undefined;
+//# sourceMappingURL=resource-index.d.ts.map

package/dist/x402/resource-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-index.d.ts","sourceRoot":"","sources":["../../src/x402/resource-index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,kEAAkE;IAClE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,MAAM,mBAAmB,GAC3B,UAAU,GACV,YAAY;AACd;;;;;;;;;GASG;GACD,WAAW,GACX,sBAAsB,CAAC;AAE3B,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;CAC5C;AAED,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACtD;AAED,4EAA4E;AAC5E,eAAO,MAAM,iCAAiC,QAAS,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,mCAAmC,QAAc,CAAC;AAE/D,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC,CAAC;IAC7D,QAAQ,CAAC,eAAe,CAAC,EAAE,uBAAuB,CAAC;IACnD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,wBAAgB,2BAA2B,CACzC,OAAO,GAAE,4BAAiC,GACzC,mBAAmB,CA+FrB;AAED,2DAA2D;AAC3D,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,MAAM,EAAE,CA6B1E;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUxD"}

package/dist/x402/resource-index.js

@@ -0,0 +1,126 @@
+import { discoverServices, } from "../discovery/registry.js";
+/** How long a registry snapshot is reused before a refresh is attempted. */
+export const DEFAULT_RESOURCE_INDEX_REFRESH_MS = 60_000;
+/**
+ * How long a stale snapshot keeps being served after refreshes start failing.
+ * Serving a stale listing is safe in a way that serving a stale DELIVERY verdict
+ * is not: listings change on a human timescale (a new signed descriptor), and
+ * the fields used from them — `operator`, `serviceRef` — are the stable ones. The
+ * live verdict is always fetched fresh by the delivery oracle.
+ */
+export const DEFAULT_RESOURCE_INDEX_MAX_STALE_MS = 15 * 60_000;
+export function createRegistryResourceIndex(options = {}) {
+    const refreshMs = options.refreshMs ?? DEFAULT_RESOURCE_INDEX_REFRESH_MS;
+    const maxStaleMs = options.maxStaleMs ?? DEFAULT_RESOURCE_INDEX_MAX_STALE_MS;
+    const now = options.now ?? (() => Date.now());
+    const discover = options.discover ??
+        (() => discoverServices(options.discoverOptions ?? {}));
+    let snapshot;
+    let inFlight;
+    async function refresh() {
+        try {
+            const listings = await discover();
+            const byOrigin = new Map();
+            const ambiguous = new Set();
+            for (const listing of listings) {
+                for (const origin of signedOriginsOf(listing)) {
+                    const claimed = byOrigin.get(origin);
+                    if (claimed === undefined) {
+                        byOrigin.set(origin, {
+                            serviceRef: listing.serviceRef,
+                            operator: listing.operator,
+                            listing,
+                            matchedOrigin: origin,
+                        });
+                        continue;
+                    }
+                    // A DIFFERENT service claiming an origin another already claims makes
+                    // the origin unresolvable, not first-come-first-served. See the
+                    // `ambiguous` doc on `ResourceIndexStatus`. A listing re-claiming its
+                    // OWN origin (e.g. publicUrl and baseUrl agreeing) is not a conflict.
+                    if (claimed.serviceRef.toLowerCase() !==
+                        listing.serviceRef.toLowerCase()) {
+                        ambiguous.add(origin);
+                    }
+                }
+            }
+            for (const origin of ambiguous) {
+                byOrigin.delete(origin);
+            }
+            return { loadedAtMs: now(), byOrigin, ambiguous };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async function currentSnapshot() {
+        const cached = snapshot;
+        if (cached !== undefined && now() - cached.loadedAtMs < refreshMs) {
+            return cached;
+        }
+        inFlight ??= refresh().finally(() => {
+            inFlight = undefined;
+        });
+        const loaded = await inFlight;
+        if (loaded !== undefined) {
+            snapshot = loaded;
+            return loaded;
+        }
+        if (cached !== undefined && now() - cached.loadedAtMs <= maxStaleMs) {
+            return cached;
+        }
+        return undefined;
+    }
+    return {
+        async lookup(resourceUrl) {
+            const origin = originOf(resourceUrl);
+            if (origin === undefined) {
+                return { status: "not-listed" };
+            }
+            const loaded = await currentSnapshot();
+            if (loaded === undefined) {
+                return { status: "registry-unavailable" };
+            }
+            if (loaded.ambiguous.has(origin)) {
+                return { status: "ambiguous" };
+            }
+            const resource = loaded.byOrigin.get(origin);
+            return resource === undefined
+                ? { status: "not-listed" }
+                : { status: "resolved", resource };
+        },
+    };
+}
+/** Every origin the SIGNED record claims for a listing. */
+export function signedOriginsOf(listing) {
+    const candidates = [
+        listing.publicUrl,
+        listing.accessUrl,
+    ];
+    const descriptor = listing.signed.descriptor;
+    if (descriptor !== undefined) {
+        candidates.push(descriptor.publicUrl, descriptor.interface?.baseUrl, descriptor.callerAuth?.accessUrl);
+    }
+    const origins = new Set();
+    for (const candidate of candidates) {
+        const origin = candidate === undefined ? undefined : originOf(candidate);
+        if (origin !== undefined) {
+            origins.add(origin);
+        }
+    }
+    return [...origins];
+}
+/** Normalized `scheme://host[:port]`, or `undefined` if not a usable URL. */
+export function originOf(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            return undefined;
+        }
+        return `${parsed.protocol}//${parsed.host.toLowerCase()}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=resource-index.js.map

package/dist/x402/resource-index.js.map

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

package/dist/x402/verified-delivery-facilitator.d.ts

@@ -0,0 +1,285 @@
+import { type PaymentPayload, type PaymentRequirements, type SettleResponse, type VerifyResponse } from "x402/types";
+import type { DeliveryVerdict, DeliveryVerdictReason, MetrikDeliveryOracle } from "./delivery-oracle.js";
+import type { MetrikResourceIndex } from "./resource-index.js";
+/**
+ * Metrik's x402 facilitator: a fully conformant `exact` facilitator that ALSO
+ * refuses to settle payment for a service its own oracle says is not delivering.
+ *
+ * ## Why this is spec-legal
+ *
+ * `VerifyResponse` is `{ isValid: boolean, invalidReason?, payer? }`. Nothing in
+ * the x402 specification constrains WHY a facilitator answers `false`. A
+ * facilitator is the party a resource server delegates its "should this payment
+ * go through" decision to; Metrik simply knows one more thing than every other
+ * facilitator, because it runs a prober.
+ *
+ * ## What this is NOT
+ *
+ * **This is strictly weaker buyer protection than a Metrik escrow stream.** A
+ * stream holds the buyer's money and releases it only for intervals that
+ * verified, so money already spent on a service that stopped delivering is
+ * recoverable. This gate holds nothing. It can only prevent a payment that has
+ * not happened yet; it can never recover one that has. An `exact` payment that
+ * Metrik lets through is gone, exactly as it would be through any other
+ * facilitator.
+ *
+ * And `isValid: true` from this facilitator is NOT an endorsement. It means only
+ * "the payment is well-formed and Metrik has no fresh evidence that this service
+ * is failing". The gate subtracts; it never adds.
+ *
+ * ## Scope: only services Metrik actually tracks
+ *
+ * A resource that maps to no Metrik listing gets the ordinary facilitator
+ * answer, unchanged. Refusing payments for services Metrik has no opinion about
+ * would not be caution, it would be a broken facilitator.
+ */
+/** What the delivery gate did to a payment. */
+export type MetrikGateOutcome = 
+/** The resource is not a Metrik listing — ordinary facilitator behaviour. */
+"not-applicable"
+/** Fresh evidence the service is delivering; payment allowed to proceed. */
+ | "passed"
+/** Fresh evidence the service is failing; payment refused. */
+ | "refused"
+/** No fresh evidence; `indeterminatePolicy` decided. */
+ | "indeterminate"
+/** The resource's payee is not the operator who signed the listing. */
+ | "payee-mismatch"
+/** Metrik could not tell whether the resource is one of its listings. */
+ | "registry-unavailable";
+/** The delivery gate's own verdict, before settlement policy is applied. */
+export interface MetrikGateVerdict {
+    readonly gate: MetrikGateOutcome;
+    /** Human-readable explanation. See "Where the explanation goes" below. */
+    readonly detail: string;
+    readonly serviceRef?: string;
+    readonly deliveryVerdict?: DeliveryVerdict;
+    readonly deliveryReason?: DeliveryVerdictReason;
+    readonly lastCheckedAt?: number | null;
+    readonly verdictAgeSeconds?: number | null;
+    readonly freshnessWindowSeconds?: number;
+}
+export interface MetrikGateAnnotation extends MetrikGateVerdict {
+    /**
+     * Whether THIS facilitator would broadcast this payment if asked.
+     *
+     * Distinct from `isValid`, and deliberately reported on `/verify`: a payment
+     * can be perfectly valid and still be one this relayer will not spend its own
+     * gas on (see {@link SettlementRefusalReason}). Reporting it up front lets a
+     * resource server refuse BEFORE it executes the request, instead of doing the
+     * work and then failing to get paid for it.
+     */
+    readonly settleable: boolean;
+    /** Why `settleable` is false. Absent when it is true. */
+    readonly settlementRefusal?: SettlementRefusalReason;
+}
+export declare const SETTLEMENT_REFUSAL_DETAIL: Readonly<Record<SettlementRefusalReason, string>>;
+/**
+ * A `VerifyResponse` with Metrik's reasoning attached.
+ *
+ * ### Where the explanation goes
+ *
+ * `invalidReason` is a CLOSED enum in the x402 spec and there is no member for
+ * "this service is not delivering". Inventing one would break every conformant
+ * client that parses the field. So the enum carries the closest honest member
+ * (see {@link DELIVERY_REFUSAL_REASON}) and the real explanation travels in a
+ * `metrik` object alongside it.
+ *
+ * `VerifyResponseSchema` is a `strip` (not `strict`) Zod object, so this extra
+ * key is spec-tolerated: a conformant client parses the response successfully
+ * and simply drops `metrik`. A client that wants the reason can read it off the
+ * raw body. Nothing about the standard fields changes.
+ */
+export type MetrikVerifyResponse = VerifyResponse & {
+    readonly metrik: MetrikGateAnnotation;
+};
+export type MetrikSettleResponse = SettleResponse & {
+    readonly metrik: MetrikGateAnnotation;
+};
+/**
+ * Why this facilitator will not BROADCAST a payment, independent of whether the
+ * payment is valid.
+ *
+ * `/settle` makes the operator's relayer sign and broadcast a call to
+ * `paymentRequirements.asset` and pay the gas for it. Every field of
+ * `PaymentRequirements` arrives in the request body, and `PaymentRequirementsSchema`
+ * accepts ANY `asset` address, ANY `payTo`, `maxAmountRequired: "0"`, and any
+ * valid-URL `resource`. The library's `verify` only checks the payload against
+ * those same caller-supplied requirements — signature recovers to
+ * `authorization.from`, `to === payTo`, window valid, and
+ * `balanceOf(from) >= maxAmountRequired` **on the caller-supplied asset**. An
+ * attacker signing from their own key to their own address satisfies all of it.
+ *
+ * Without the checks below, `/settle` is a permissionless "make the relayer
+ * broadcast a call to a contract of my choosing" endpoint: deploy something
+ * whose `balanceOf` returns a huge number and whose `transferWithAuthorization`
+ * burns gas, and drain the relayer until legitimate settlement stops. No funds
+ * are stolen — but it is the operator's money, and it induces the operator's key
+ * to sign transactions to contracts they never chose.
+ *
+ * The asset allowlist is the one that removes the arbitrary-contract-call
+ * primitive outright; the rest are defence in depth.
+ */
+export type SettlementRefusalReason = 
+/** `asset` is not an operator-approved settlement token. */
+"asset-not-allowed"
+/** The payload or the requirements name a chain this facilitator does not settle. */
+ | "network-mismatch"
+/** A zero-value settlement moves nothing and only burns the relayer's gas. */
+ | "zero-amount"
+/** The relayer only pays gas for resources Metrik actually tracks. */
+ | "resource-not-tracked";
+/**
+ * Which resources this facilitator will spend the relayer's gas on.
+ *
+ * `tracked-resources` (default) is a deliberate ASYMMETRY with the delivery
+ * gate's allow-by-default policy, and the asymmetry is the point: an OPINION
+ * about a service costs nothing and should be given freely, so `/verify` stays
+ * universal and fails open. BROADCASTING costs the operator real gas, so
+ * `/settle` fails closed and is scoped to Metrik's own marketplace.
+ *
+ * This is not a censorship lever. Metrik declining to spend its own gas does
+ * not stop anyone being paid — any other facilitator (or the payer's own
+ * relayer) can settle the same payment.
+ *
+ * `any-resource` is for an operator deliberately running a general-purpose
+ * facilitator on a relayer they are content to fund for anyone's traffic. The
+ * asset allowlist still applies.
+ */
+export type SettlementScope = "tracked-resources" | "any-resource";
+export declare const DEFAULT_SETTLEMENT_SCOPE: SettlementScope;
+/**
+ * The `invalidReason` used when the delivery gate refuses.
+ *
+ * The enum has no member for "the resource is not delivering", so the choice is
+ * between members that are all imperfect. Every payer-side member
+ * (`invalid_payload`, `invalid_exact_evm_payload_signature`,
+ * `insufficient_funds`) would be an active lie: it sends the developer to debug
+ * a wallet that is working correctly. `unexpected_verify_error` is also false —
+ * this refusal is deliberate and expected, not an error.
+ *
+ * `invalid_payment_requirements` is the only member that points at the
+ * REQUIREMENTS side of the exchange, which is exactly where the problem is:
+ * Metrik will not settle a payment quoted for THIS resource to THIS payee right
+ * now. It is the honest member, and the `metrik.detail` string carries the rest.
+ */
+export declare const DELIVERY_REFUSAL_REASON: "invalid_payment_requirements";
+/** What to do when Metrik has no fresh delivery evidence. */
+export type IndeterminatePolicy = "allow" | "deny";
+/**
+ * Default: `allow`.
+ *
+ * The standing Metrik rule is buyer-favouring, and it still is — but it applies
+ * where Metrik HOLDS the buyer's money and must decide whether to release it.
+ * Here Metrik holds nothing, so refusing does not protect a buyer's funds; it
+ * only denies them a service they asked to buy, on a rail that works fine
+ * without Metrik. Four things make `allow` the right default:
+ *
+ * 1. **Absent evidence is the normal case, not the exception.** The oracle's
+ *    `/services` projection is built from ACTIVE STREAMS. A service with no live
+ *    Metrik stream has no row at all — on the live oracle today that is every
+ *    service. Failing closed would refuse 100% of payments, which is a broken
+ *    facilitator rather than a careful one.
+ * 2. **Fail-closed is a censorship lever.** If "oracle down" meant "no payments",
+ *    anyone who could degrade Metrik's oracle could block payments to a
+ *    competitor listed on it. `allow` removes that lever entirely.
+ * 3. **The harms are asymmetric.** A wrong refusal denies a service outright. A
+ *    wrong allowance passes one `exact` payment, at a price the buyer already
+ *    agreed to, which by construction is one call's worth.
+ * 4. **A pass never claims anything.** `isValid: true` with
+ *    `gate: "indeterminate"` says "no fresh evidence", and the annotation says
+ *    so in the response. Nobody has to infer an endorsement that was not made.
+ *
+ * Set `indeterminatePolicy: "deny"` for a deployment that would rather refuse
+ * than proceed without positive fresh evidence. That is a real, supported
+ * choice — it is just not a safe default.
+ */
+export declare const DEFAULT_INDETERMINATE_POLICY: IndeterminatePolicy;
+/** The payment-validity half of the facilitator (signature, amount, funds, window). */
+export interface PaymentVerifier {
+    verify(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResponse>;
+}
+/** The broadcast half. Requires a funded relayer wallet. */
+export interface PaymentSettler {
+    settle(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
+}
+export declare class RelayerNotConfiguredError extends Error {
+    constructor();
+}
+export interface MetrikVerifiedDeliveryFacilitatorOptions {
+    readonly paymentVerifier: PaymentVerifier;
+    /** Omit to run a verify-only facilitator: `/settle` then fails loudly. */
+    readonly paymentSettler?: PaymentSettler;
+    readonly resourceIndex: MetrikResourceIndex;
+    readonly deliveryOracle: MetrikDeliveryOracle;
+    /** Default {@link DEFAULT_INDETERMINATE_POLICY}. */
+    readonly indeterminatePolicy?: IndeterminatePolicy;
+    /** Chain this facilitator settles on. Default `84532` (Base Sepolia). */
+    readonly chainId?: number;
+    /**
+     * Token contracts the relayer may be asked to call. Defaults to the single
+     * canonical USDC for `chainId`. An empty array is rejected: a settling
+     * facilitator with no allowed asset can never settle anything, and silently
+     * accepting that would hide a misconfiguration.
+     *
+     * THIS IS THE CONTROL that stops `/settle` being an arbitrary-contract-call
+     * primitive. See {@link SettlementRefusalReason}.
+     */
+    readonly settlementAssetAllowlist?: readonly string[];
+    /** Default {@link DEFAULT_SETTLEMENT_SCOPE}. */
+    readonly settlementScope?: SettlementScope;
+}
+export interface FacilitatorSupported {
+    readonly x402Version: number;
+    readonly kind: readonly {
+        readonly scheme: string;
+        readonly networkId: string;
+        readonly extra: object;
+    }[];
+}
+export declare class MetrikVerifiedDeliveryFacilitator {
+    private readonly paymentVerifier;
+    private readonly paymentSettler;
+    private readonly resourceIndex;
+    private readonly deliveryOracle;
+    private readonly indeterminatePolicy;
+    private readonly network;
+    private readonly settlementAssets;
+    private readonly settlementScope;
+    constructor(options: MetrikVerifiedDeliveryFacilitatorOptions);
+    /** The assets this relayer may be asked to call, for logging at startup. */
+    get allowedSettlementAssets(): readonly string[];
+    supported(): FacilitatorSupported;
+    /** `POST /verify`. Takes an unvalidated body; never throws on bad input. */
+    verify(body: unknown): Promise<MetrikVerifyResponse>;
+    /**
+     * `POST /settle`. Re-runs the full gate before broadcasting: a facilitator
+     * must never settle something it would not verify, and `/settle` is reachable
+     * without `/verify` ever having been called.
+     */
+    settle(body: unknown): Promise<MetrikSettleResponse>;
+    /**
+     * Settlement constraints checkable from the request alone — no RPC, no
+     * registry, no oracle. Returns the refusal, or `undefined` if the request
+     * clears them.
+     */
+    private settlementPreflight;
+    /** Builds the standard-shaped refusal for a settlement the relayer declines. */
+    private refuseSettlement;
+    private evaluate;
+    /** Does this gate outcome name a resource the relayer will pay gas for? */
+    private scopeRefusal;
+    private evaluateGate;
+    private applyIndeterminate;
+}
+interface ParsedFacilitatorRequest {
+    readonly paymentPayload: PaymentPayload;
+    readonly paymentRequirements: PaymentRequirements;
+}
+/**
+ * Parses the facilitator wire body with the REAL x402 schemas. Both `/verify`
+ * and `/settle` take the same `{paymentPayload, paymentRequirements}` pair.
+ */
+export declare function parseFacilitatorRequest(body: unknown): ParsedFacilitatorRequest | undefined;
+export {};
+//# sourceMappingURL=verified-delivery-facilitator.d.ts.map

package/dist/x402/verified-delivery-facilitator.d.ts.map

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