@absol-labs/agent 0.5.0 → 0.7.0

package/src/sdk/invoke.ts

@@ -1,7 +1,16 @@
-import { type DeliveryReceiptDomainInput } from "@absol-labs/shared";
+import {
+  deriveServiceRef,
+  recoverServiceBindingSigner,
+  recoverServiceDescriptorSigner,
+  signedServiceBindingSchema,
+  signedServiceDescriptorSchema,
+  type DeliveryReceiptDomainInput,
+} from "@absol-labs/shared";
 import { MetrikClient } from "@absol-labs/sdk";
 import type { Address, Hex, LocalAccount } from "viem";
 
+import type { ServiceListing } from "../discovery/registry.js";
+
 import {
   buildT2DeliveryProofSubmission,
   type BuildT2DeliveryProofResult,
@@ -89,6 +98,31 @@ export class InvokeBuyerMismatchError extends Error {
   }
 }
 
+export class InvokeServiceRefMismatchError extends Error {
+  constructor(streamRef: Hex, listingRef: Hex) {
+    super(
+      `stream serviceRef ${streamRef} does not match listing serviceRef ${listingRef}`,
+    );
+    this.name = "InvokeServiceRefMismatchError";
+  }
+}
+
+export class InvokeAccessUrlError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvokeAccessUrlError";
+  }
+}
+
+export class InvokePathError extends Error {
+  constructor(path: string) {
+    super(
+      `invocation path must be origin-relative and start with one slash: ${path}`,
+    );
+    this.name = "InvokePathError";
+  }
+}
+
 export interface CapabilityForOptions {
   readonly buyer: LocalAccount;
   readonly domain: InvocationCapabilityDomainInput;
@@ -142,8 +176,10 @@ export interface InvokeOptions {
   readonly buyer: LocalAccount;
   /** `{chainId, verifyingContract}` - the `StreamEscrowV2` the stream settles on. */
   readonly domain: InvocationCapabilityDomainInput;
-  /** Base URL of the gateway-fronted service (from the service listing/descriptor). */
-  readonly serviceBaseUrl: string;
+  /** Preferred: a cryptographically verified result from discoverServices(). */
+  readonly listing?: ServiceListing;
+  /** @deprecated Manual escape hatch. Verified listing routing is safer. */
+  readonly serviceBaseUrl?: string;
   readonly ttlSeconds?: number;
   readonly nonce?: Hex;
   readonly nowSeconds?: number;
@@ -168,6 +204,7 @@ export async function invoke(
   request: InvokeServiceInput,
   options: InvokeOptions,
 ): Promise<InvokeResult> {
+  assertOriginRelativePath(request.path);
   const stream = await options.streamReader.getStreamV2(streamId);
   const nowSeconds = options.nowSeconds ?? Math.floor(Date.now() / 1000);
 
@@ -185,6 +222,11 @@ export async function invoke(
     throw new InvokeStreamExpiredError(streamId, stream.expiresAt);
   }
 
+  const serviceBaseUrl = await resolveInvocationBaseUrl(
+    stream.serviceRef,
+    options,
+  );
+
   const capability = await capabilityFor(streamId, request, {
     buyer: options.buyer,
     domain: options.domain,
@@ -197,7 +239,10 @@ export async function invoke(
   });
 
   const header = encodeCapabilityHeader(capability);
-  const url = new URL(request.path, options.serviceBaseUrl).toString();
+  const url = new URL(
+    request.path,
+    ensureTrailingSlash(serviceBaseUrl),
+  ).toString();
   const fetchImpl = options.fetchImpl ?? fetch;
   const response = await fetchImpl(url, {
     method: request.method,
@@ -219,6 +264,8 @@ export interface InvokeWithT2DeliveryProofOptions {
   readonly domain: DeliveryReceiptDomainInput;
   /** The T2 paid-route spec (absolute `url`, `responseMatches`, nonce injection point, ...). */
   readonly request: PaidRouteRequestSpec;
+  /** Verified listing. Gated T2 is rejected until proof-target pinning supports it. */
+  readonly listing?: ServiceListing;
   /** Which billing interval this delivery proof covers. */
   readonly intervalIndex: bigint;
   /** Oracle-issued anti-replay nonce, from `GET /delivery/nonce`. */
@@ -267,6 +314,22 @@ export async function invokeWithT2DeliveryProof(
     throw new InvokeStreamExpiredError(streamId, stream.expiresAt);
   }
 
+  if (options.listing !== undefined) {
+    const route = await verifyListingRoute(stream.serviceRef, options.listing);
+    if (route.access === "gated") {
+      throw new InvokeAccessUrlError(
+        "consumer-attested T2 invocation is not supported for gated listings",
+      );
+    }
+    const requestOrigin = new URL(options.request.url).origin;
+    const signedOrigin = new URL(route.url).origin;
+    if (requestOrigin !== signedOrigin) {
+      throw new InvokeAccessUrlError(
+        `T2 request origin ${requestOrigin} does not match signed listing origin ${signedOrigin}`,
+      );
+    }
+  }
+
   const path = new URL(options.request.url).pathname;
   const capability = await capabilityFor(
     streamId,
@@ -311,3 +374,122 @@ export async function invokeWithT2DeliveryProof(
 
   return { capability, stream, t2 };
 }
+
+async function resolveInvocationBaseUrl(
+  streamRef: Hex,
+  options: InvokeOptions,
+): Promise<string> {
+  if (options.listing !== undefined) {
+    return (await verifyListingRoute(streamRef, options.listing)).url;
+  }
+  if (options.serviceBaseUrl === undefined) {
+    throw new InvokeAccessUrlError(
+      "a verified listing is required (or pass deprecated serviceBaseUrl explicitly)",
+    );
+  }
+  return requireHttpUrl(options.serviceBaseUrl, "serviceBaseUrl");
+}
+
+async function verifyListingRoute(
+  streamRef: Hex,
+  listing: ServiceListing,
+): Promise<{ readonly access: "public" | "gated"; readonly url: string }> {
+  if (streamRef.toLowerCase() !== listing.serviceRef.toLowerCase()) {
+    throw new InvokeServiceRefMismatchError(streamRef, listing.serviceRef);
+  }
+
+  const descriptor = signedServiceDescriptorSchema.safeParse(listing.signed);
+  if (descriptor.success) {
+    const signed = descriptor.data;
+    const derived = deriveServiceRef(signed.descriptor);
+    const signer = await recoverServiceDescriptorSigner(
+      signed.descriptor,
+      signed.signature as Hex,
+    );
+    const access = signed.descriptor.access ?? "public";
+    const url =
+      access === "gated"
+        ? signed.descriptor.callerAuth?.accessUrl
+        : (signed.descriptor.interface?.baseUrl ?? signed.descriptor.publicUrl);
+    if (
+      derived.toLowerCase() !== listing.serviceRef.toLowerCase() ||
+      signed.serviceRef.toLowerCase() !== listing.serviceRef.toLowerCase() ||
+      signer === null ||
+      signer.toLowerCase() !== signed.descriptor.operator.toLowerCase() ||
+      listing.operator.toLowerCase() !==
+        signed.descriptor.operator.toLowerCase() ||
+      listing.publicUrl !== signed.descriptor.publicUrl ||
+      listing.access !== access ||
+      url === undefined ||
+      listing.accessUrl !== url
+    ) {
+      throw new InvokeAccessUrlError(
+        "listing does not match its verified signed descriptor",
+      );
+    }
+    const verifiedUrl = requireHttpUrl(url, "signed listing access URL");
+    if (access === "gated" && new URL(verifiedUrl).protocol !== "https:") {
+      throw new InvokeAccessUrlError(
+        "signed gated listing access URL must use HTTPS",
+      );
+    }
+    return { access, url: verifiedUrl };
+  }
+
+  const binding = signedServiceBindingSchema.safeParse(listing.signed);
+  if (binding.success) {
+    const signed = binding.data;
+    const derived = deriveServiceRef(signed.binding);
+    const signer = await recoverServiceBindingSigner(
+      signed.binding,
+      signed.signature as Hex,
+    );
+    if (
+      derived.toLowerCase() !== listing.serviceRef.toLowerCase() ||
+      signed.serviceRef.toLowerCase() !== listing.serviceRef.toLowerCase() ||
+      signer === null ||
+      signer.toLowerCase() !== signed.binding.operator.toLowerCase() ||
+      listing.operator.toLowerCase() !==
+        signed.binding.operator.toLowerCase() ||
+      listing.publicUrl !== signed.binding.publicUrl ||
+      listing.access !== "public" ||
+      listing.accessUrl !== signed.binding.publicUrl
+    ) {
+      throw new InvokeAccessUrlError(
+        "listing does not match its verified signed binding",
+      );
+    }
+    return {
+      access: "public",
+      url: requireHttpUrl(
+        signed.binding.publicUrl,
+        "signed listing access URL",
+      ),
+    };
+  }
+
+  throw new InvokeAccessUrlError("listing signed record is invalid");
+}
+
+function requireHttpUrl(value: string, label: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new InvokeAccessUrlError(`${label} must be an absolute HTTP(S) URL`);
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new InvokeAccessUrlError(`${label} must be an absolute HTTP(S) URL`);
+  }
+  return parsed.toString();
+}
+
+function assertOriginRelativePath(path: string): void {
+  if (!path.startsWith("/") || path.startsWith("//") || path.includes("#")) {
+    throw new InvokePathError(path);
+  }
+}
+
+function ensureTrailingSlash(value: string): string {
+  return value.endsWith("/") ? value : `${value}/`;
+}