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

package/src/x402-opener/index.ts

@@ -0,0 +1,13 @@
+/**
+ * `@absol-labs/agent/x402-opener` — x402 v2 `exact` payments settled into a
+ * `StreamEscrowV2` stream through the ownerless `X402StreamOpenerFactory`
+ * (metrik-agent#116). Kept out of the root barrel so consumers that never use
+ * x402 do not load `@x402/*`. See docs/x402.md.
+ */
+export * from "./abi.js";
+export * from "./terms.js";
+export * from "./listing-resolver.js";
+export * from "./scheme.js";
+export * from "./facilitator-server.js";
+export * from "./refund-relay.js";
+export * from "./relayer-queue.js";

package/src/x402-opener/listing-resolver.ts

@@ -0,0 +1,202 @@
+import {
+  DEFAULT_METRIK_PUBLIC_REGISTRY_URL,
+  discoverServicesDetailed,
+  type DiscoveredService,
+} from "../discovery/registry.js";
+import type { OpenerTerms } from "./terms.js";
+
+/**
+ * Resolves opener terms to exactly ONE operator-signed Metrik listing.
+ *
+ * The trust decision is the existing discovery verification, reused verbatim
+ * ({@link discoverServicesDetailed} → `@absol-labs/sdk`): every registry row is
+ * schema-validated, its `serviceRef` is re-derived from the signed content, and
+ * its operator EIP-712 signature is recovered and matched. Only then is it
+ * compared with the terms. An unsigned registry column, or anything a request
+ * carries, is never consulted — `serviceRef` and `operator` come out of the
+ * verified signed record.
+ *
+ * Fail closed: an unreachable registry, zero matches, or more than one match is
+ * a refusal, never a pass.
+ */
+
+export type ListingResolution =
+  | {
+      readonly ok: true;
+      readonly listing: DiscoveredService;
+    }
+  | {
+      readonly ok: false;
+      readonly reason:
+        | "listing-registry-unavailable"
+        | "listing-not-found"
+        | "listing-ambiguous"
+        | "listing-rate-out-of-bounds";
+      readonly message: string;
+    };
+
+export interface OperatorSignedListingResolver {
+  resolve(
+    terms: Pick<OpenerTerms, "operator" | "serviceRef" | "ratePerSecond">,
+  ): Promise<ListingResolution>;
+}
+
+export interface RegistryListingResolverOptions {
+  /** Default {@link DEFAULT_METRIK_PUBLIC_REGISTRY_URL}. */
+  readonly registryUrl?: string;
+  /**
+   * How long a SUCCESSFUL registry read is reused, in seconds. Failures are
+   * never cached. Default 60. `0` disables caching.
+   */
+  readonly cacheSeconds?: number;
+  readonly timeoutMs?: number;
+  readonly fetch?: typeof fetch;
+  readonly now?: () => number;
+  readonly logger?: { warn: (...args: unknown[]) => void };
+}
+
+export const DEFAULT_LISTING_CACHE_SECONDS = 60;
+
+export class RegistryListingResolver implements OperatorSignedListingResolver {
+  private readonly registryUrl: string;
+  private readonly cacheSeconds: number;
+  private readonly now: () => number;
+  private cache:
+    | { readonly at: number; readonly services: readonly DiscoveredService[] }
+    | undefined;
+  private inFlight: Promise<readonly DiscoveredService[]> | undefined;
+
+  constructor(private readonly options: RegistryListingResolverOptions = {}) {
+    this.registryUrl =
+      options.registryUrl ?? DEFAULT_METRIK_PUBLIC_REGISTRY_URL;
+    // eslint-disable-next-line no-new -- validates the URL is well-formed.
+    new URL(this.registryUrl);
+    const cacheSeconds = options.cacheSeconds ?? DEFAULT_LISTING_CACHE_SECONDS;
+    if (!Number.isFinite(cacheSeconds) || cacheSeconds < 0) {
+      throw new Error("cacheSeconds must be a non-negative number");
+    }
+    this.cacheSeconds = cacheSeconds;
+    this.now = options.now ?? (() => Math.floor(Date.now() / 1000));
+  }
+
+  async resolve(
+    terms: Pick<OpenerTerms, "operator" | "serviceRef" | "ratePerSecond">,
+  ): Promise<ListingResolution> {
+    let services: readonly DiscoveredService[];
+    try {
+      services = await this.services();
+    } catch (error) {
+      return {
+        ok: false,
+        reason: "listing-registry-unavailable",
+        message: error instanceof Error ? error.message : String(error),
+      };
+    }
+    const serviceRef = terms.serviceRef.toLowerCase();
+    const operator = terms.operator.toLowerCase();
+    const matches = services.filter(
+      (service) =>
+        service.serviceRef.toLowerCase() === serviceRef &&
+        service.operator.toLowerCase() === operator,
+    );
+    if (matches.length === 0) {
+      return {
+        ok: false,
+        reason: "listing-not-found",
+        message: `no operator-signed listing for serviceRef ${terms.serviceRef} signed by ${terms.operator}`,
+      };
+    }
+    if (matches.length > 1) {
+      return {
+        ok: false,
+        reason: "listing-ambiguous",
+        message: `${matches.length} listings match serviceRef ${terms.serviceRef}`,
+      };
+    }
+    const listing = matches[0] as DiscoveredService;
+    const bounds = signedRateBounds(listing);
+    if (
+      (bounds.min !== undefined && terms.ratePerSecond < bounds.min) ||
+      (bounds.max !== undefined && terms.ratePerSecond > bounds.max)
+    ) {
+      return {
+        ok: false,
+        reason: "listing-rate-out-of-bounds",
+        message: `ratePerSecond ${terms.ratePerSecond} is outside the listing's signed bounds [${bounds.min ?? "-"}, ${bounds.max ?? "-"}]`,
+      };
+    }
+    return { ok: true, listing };
+  }
+
+  private async services(): Promise<readonly DiscoveredService[]> {
+    const nowSeconds = this.now();
+    if (
+      this.cache !== undefined &&
+      this.cacheSeconds > 0 &&
+      nowSeconds - this.cache.at < this.cacheSeconds
+    ) {
+      return this.cache.services;
+    }
+    if (this.inFlight !== undefined) {
+      return this.inFlight;
+    }
+    const read = discoverServicesDetailed({
+      registryUrl: this.registryUrl,
+      // An explicit empty key pins the credential-free public read: the
+      // METRIK_AGENT_REGISTRY_APIKEY env override must not switch transports.
+      apiKey: "",
+      ...(this.options.fetch === undefined
+        ? {}
+        : { fetch: this.options.fetch }),
+      ...(this.options.timeoutMs === undefined
+        ? {}
+        : { timeoutMs: this.options.timeoutMs }),
+      ...(this.options.logger === undefined
+        ? {}
+        : { logger: this.options.logger }),
+    }).then((result) => {
+      if (!result.registryAvailable) {
+        throw new Error("registry reported itself unavailable");
+      }
+      this.cache = { at: this.now(), services: result.services };
+      return result.services;
+    });
+    this.inFlight = read;
+    try {
+      return await read;
+    } finally {
+      this.inFlight = undefined;
+    }
+  }
+}
+
+/**
+ * Rate bounds from the SIGNED descriptor's `commercial` block, when present.
+ * A legacy binding carries none.
+ */
+function signedRateBounds(listing: DiscoveredService): {
+  readonly min?: bigint;
+  readonly max?: bigint;
+} {
+  const signed = listing.signed as { readonly descriptor?: unknown };
+  const descriptor = signed.descriptor as
+    | {
+        readonly commercial?: {
+          minRatePerSecond?: string;
+          maxRatePerSecond?: string;
+        };
+      }
+    | undefined;
+  const commercial = descriptor?.commercial;
+  if (commercial === undefined) {
+    return {};
+  }
+  return {
+    ...(commercial.minRatePerSecond === undefined
+      ? {}
+      : { min: BigInt(commercial.minRatePerSecond) }),
+    ...(commercial.maxRatePerSecond === undefined
+      ? {}
+      : { max: BigInt(commercial.maxRatePerSecond) }),
+  };
+}