@absol-labs/agent 0.10.0 → 0.11.0

package/src/x402/resource-index.ts

@@ -0,0 +1,228 @@
+import {
+  discoverServices,
+  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 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 interface RegistryResourceIndexOptions {
+  readonly discover?: () => Promise<readonly ServiceListing[]>;
+  readonly discoverOptions?: DiscoverServicesOptions;
+  readonly refreshMs?: number;
+  readonly maxStaleMs?: number;
+  readonly now?: () => number;
+}
+
+export function createRegistryResourceIndex(
+  options: RegistryResourceIndexOptions = {},
+): MetrikResourceIndex {
+  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 ?? {}) as Promise<
+        readonly ServiceListing[]
+      >);
+
+  interface Snapshot {
+    readonly loadedAtMs: number;
+    readonly byOrigin: ReadonlyMap<string, ResolvedMetrikResource>;
+    readonly ambiguous: ReadonlySet<string>;
+  }
+  let snapshot: Snapshot | undefined;
+  let inFlight: Promise<Snapshot | undefined> | undefined;
+
+  async function refresh(): Promise<Snapshot | undefined> {
+    try {
+      const listings = await discover();
+      const byOrigin = new Map<string, ResolvedMetrikResource>();
+      const ambiguous = new Set<string>();
+      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(): Promise<Snapshot | undefined> {
+    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: ServiceListing): readonly string[] {
+  const candidates: (string | undefined)[] = [
+    listing.publicUrl,
+    listing.accessUrl,
+  ];
+  const descriptor = (
+    listing.signed as {
+      descriptor?: {
+        interface?: { baseUrl?: string };
+        callerAuth?: { accessUrl?: string };
+        publicUrl?: string;
+      };
+    }
+  ).descriptor;
+  if (descriptor !== undefined) {
+    candidates.push(
+      descriptor.publicUrl,
+      descriptor.interface?.baseUrl,
+      descriptor.callerAuth?.accessUrl,
+    );
+  }
+  const origins = new Set<string>();
+  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: string): string | undefined {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return undefined;
+    }
+    return `${parsed.protocol}//${parsed.host.toLowerCase()}`;
+  } catch {
+    return undefined;
+  }
+}