@absol-labs/agent 0.10.0 → 0.11.0

package/src/mcp/service-invoker.ts

@@ -0,0 +1,285 @@
+import {
+  RegistryUnavailableError,
+  type DiscoverServicesOptions,
+  type ServiceListing,
+} from "../discovery/registry.js";
+import {
+  invoke as defaultInvoke,
+  type InvokeStreamReader,
+} from "../sdk/invoke.js";
+import type {
+  HttpMethod,
+  InvocationCapabilityDomainInput,
+  InvocationCapabilitySigner,
+} from "../capability/invocation-capability.js";
+
+/**
+ * The "use" half of the MCP tool surface.
+ *
+ * The MCP server could open a stream and settle it but could not CALL the
+ * service the stream paid for — an agent that hired an endpoint through this
+ * server had no way to reach it, which made every other tool a payment rail
+ * with no product on the other end. This module is the same path
+ * `metrik invoke` takes (`../cli/commands/invoke.ts`): resolve the stream's
+ * VERIFIED listing, sign a single-use `InvocationCapability` as the stream's
+ * buyer, and call the operator's gateway-fronted origin.
+ *
+ * It moves no funds and signs no transaction. Billing is a function of elapsed
+ * verified time, not of calls (see {@link METERING_MODEL} in `./server.ts`), so
+ * an invocation is authorized by the stream alone and is deliberately NOT
+ * gated by the spend mandate — there is no spend to bound.
+ */
+
+/**
+ * Cap on the response body handed back to the MCP caller.
+ *
+ * An MCP tool result is pasted into a model's context. A seller can return a
+ * body of any size, and an unbounded one would blow the context (or the host's
+ * message limit) on a single call. Truncation is reported explicitly rather
+ * than silently, so an agent can tell a short answer from a clipped one.
+ */
+export const MAX_INVOCATION_RESPONSE_BYTES = 64 * 1024;
+
+/** Raised when no verified listing in the registry matches the stream's `serviceRef`. */
+export class ServiceListingNotFoundError extends Error {
+  readonly serviceRef: `0x${string}`;
+
+  constructor(serviceRef: `0x${string}`) {
+    super(`no verified listing matches serviceRef ${serviceRef}`);
+    this.name = "ServiceListingNotFoundError";
+    this.serviceRef = serviceRef;
+  }
+}
+
+export interface ServiceInvocationRequest {
+  readonly streamId: `0x${string}`;
+  readonly method: HttpMethod;
+  /** Origin-relative path, e.g. `/price?symbol=BTC`. */
+  readonly path: string;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly body?: string;
+  readonly ttlSeconds?: number;
+}
+
+export interface ServiceInvocationResult {
+  readonly streamId: `0x${string}`;
+  readonly method: HttpMethod;
+  readonly path: string;
+  readonly status: number;
+  readonly ok: boolean;
+  readonly headers: Record<string, string>;
+  readonly body: string;
+  readonly bodyTruncated: boolean;
+  /** The single-use capability this call was authorized by. */
+  readonly capability: {
+    readonly nonce: `0x${string}`;
+    readonly expiry: number;
+  };
+  readonly routing: {
+    readonly serviceRef: `0x${string}`;
+    readonly operator: `0x${string}`;
+    readonly access: "public" | "gated";
+    /** The signed origin the call went to — never an unsigned caller-supplied URL. */
+    readonly origin: string;
+  };
+  /**
+   * The caller-auth gateway's machine-readable rejection reason when it refused
+   * the capability, or `null`. Distinguishes "the seller's app returned 403"
+   * from "the gateway would not let the call through, and here is why".
+   */
+  readonly gatewayDenialReason: string | null;
+}
+
+export interface ServiceInvoker {
+  invokeService(
+    request: ServiceInvocationRequest,
+  ): Promise<ServiceInvocationResult>;
+}
+
+/** Discovery driver — same shape as the server's, kept local to avoid an import cycle. */
+type DiscoverServicesFn = (
+  opts?: DiscoverServicesOptions,
+) => Promise<ServiceListing[]>;
+
+export interface CreateServiceInvokerOptions {
+  /** Reads the stream's buyer/serviceRef/status/expiry. */
+  readonly streamReader: InvokeStreamReader;
+  /** The server's own wallet. Must BE the stream's buyer or the call fails closed. */
+  readonly buyer: InvocationCapabilitySigner;
+  /** `{chainId, verifyingContract}` of the escrow the stream settles on. */
+  readonly domain: InvocationCapabilityDomainInput;
+  readonly discoverServices: DiscoverServicesFn;
+  /** Registry read options (URL/apikey). Passed through to discovery. */
+  readonly discoverOptions?: DiscoverServicesOptions;
+  /**
+   * Clock for the capability's expiry and the stream's liveness check.
+   * Defaults to the wall clock; injectable so a test can pin it.
+   */
+  readonly now?: () => number;
+  /** Injectable for tests. Defaults to the real `invoke()`. */
+  readonly invokeImpl?: typeof defaultInvoke;
+  readonly maxResponseBytes?: number;
+}
+
+export function createServiceInvoker(
+  options: CreateServiceInvokerOptions,
+): ServiceInvoker {
+  const invokeImpl = options.invokeImpl ?? defaultInvoke;
+  const maxBytes = options.maxResponseBytes ?? MAX_INVOCATION_RESPONSE_BYTES;
+
+  return {
+    async invokeService(request) {
+      // ONE read, used twice. The listing lookup needs the stream's serviceRef
+      // and `invoke()` re-reads the stream to authorize the call; memoizing
+      // makes both decisions come from the SAME snapshot (no window where the
+      // listing is resolved from one state and the capability signed against
+      // another) and costs one RPC round trip instead of two.
+      const reader = memoizeStreamReader(options.streamReader);
+      const stream = await reader.getStreamV2(request.streamId);
+      const listing = await resolveVerifiedListing(
+        stream.serviceRef as `0x${string}`,
+        options,
+      );
+
+      const result = await invokeImpl(
+        request.streamId,
+        {
+          method: request.method,
+          path: request.path,
+          ...(request.headers === undefined
+            ? {}
+            : { headers: request.headers }),
+          ...(request.body === undefined ? {} : { body: request.body }),
+        },
+        {
+          streamReader: reader,
+          buyer: options.buyer,
+          domain: options.domain,
+          listing,
+          ...(request.ttlSeconds === undefined
+            ? {}
+            : { ttlSeconds: request.ttlSeconds }),
+          ...(options.now === undefined ? {} : { nowSeconds: options.now() }),
+        },
+      );
+
+      const raw = await result.response.text();
+      const truncated = Buffer.byteLength(raw, "utf8") > maxBytes;
+      const body = truncated
+        ? Buffer.from(raw, "utf8").subarray(0, maxBytes).toString("utf8")
+        : raw;
+
+      return {
+        streamId: request.streamId,
+        method: request.method,
+        path: request.path,
+        status: result.response.status,
+        ok: result.response.ok,
+        headers: Object.fromEntries(result.response.headers.entries()),
+        body,
+        bodyTruncated: truncated,
+        capability: {
+          nonce: result.capability.nonce as `0x${string}`,
+          expiry: result.capability.expiry,
+        },
+        routing: {
+          serviceRef: listing.serviceRef,
+          operator: listing.operator,
+          access: listing.access,
+          origin: safeOrigin(listing.accessUrl),
+        },
+        gatewayDenialReason: readGatewayDenialReason(
+          result.response.status,
+          raw,
+        ),
+      };
+    },
+  };
+}
+
+/**
+ * Finds the operator-signed listing for a `serviceRef`.
+ *
+ * The registry is an untrusted transport: `discoverServices` re-derives every
+ * `serviceRef` from the signed record and recovers the operator's signature, so
+ * a compromised registry can neither invent an operator nor redirect an
+ * invocation to an origin its operator never signed. That verification is why
+ * this tool routes through discovery instead of accepting a caller-supplied URL
+ * — an LLM-chosen base URL is exactly the injection this design refuses.
+ */
+async function resolveVerifiedListing(
+  serviceRef: `0x${string}`,
+  options: CreateServiceInvokerOptions,
+): Promise<ServiceListing> {
+  const listings = await options.discoverServices(options.discoverOptions);
+  const wanted = serviceRef.toLowerCase();
+  const match = listings.find(
+    (listing) => listing.serviceRef.toLowerCase() === wanted,
+  );
+  if (match === undefined) {
+    throw new ServiceListingNotFoundError(serviceRef);
+  }
+  return match;
+}
+
+/** Wraps a reader so repeated reads of the SAME stream id reuse one result. */
+function memoizeStreamReader(reader: InvokeStreamReader): InvokeStreamReader {
+  const cache = new Map<
+    string,
+    ReturnType<InvokeStreamReader["getStreamV2"]>
+  >();
+  return {
+    getStreamV2(streamId) {
+      const key = streamId.toLowerCase();
+      const cached = cache.get(key);
+      if (cached !== undefined) {
+        return cached;
+      }
+      const pending = reader.getStreamV2(streamId);
+      cache.set(key, pending);
+      return pending;
+    },
+  };
+}
+
+/**
+ * Extracts the caller-auth gateway's `reason` from a 402/403 body.
+ *
+ * The gateway answers a refused capability with
+ * `{"authorized":false,"reason":"<closed-set reason>"}`
+ * (`../gateway/http-server.ts`). Surfacing that verbatim turns "403" into
+ * something an agent can act on — `stream-expired` and `nonce-replayed` call
+ * for opposite responses.
+ */
+function readGatewayDenialReason(status: number, body: string): string | null {
+  if (status !== 402 && status !== 403) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(body) as {
+      readonly authorized?: unknown;
+      readonly reason?: unknown;
+    } | null;
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      parsed.authorized === false &&
+      typeof parsed.reason === "string"
+    ) {
+      return parsed.reason;
+    }
+  } catch {
+    // Not the gateway's JSON shape — a plain upstream 403. Nothing to add.
+  }
+  return null;
+}
+
+function safeOrigin(url: string): string {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return url;
+  }
+}
+
+export { RegistryUnavailableError };

package/src/sdk/invoke.ts

@@ -24,6 +24,7 @@ import {
   hashInvocationPath,
   signInvocationCapability,
   type HttpMethod,
+  type InvocationCapabilitySigner,
   type InvocationCapability,
   type InvocationCapabilityDomainInput,
   type SignedInvocationCapability,
@@ -115,16 +116,14 @@ export class InvokeAccessUrlError extends Error {
 }
 
 export class InvokePathError extends Error {
-  constructor(path: string) {
-    super(
-      `invocation path must be origin-relative and start with one slash: ${path}`,
-    );
+  constructor(message: string) {
+    super(message);
     this.name = "InvokePathError";
   }
 }
 
 export interface CapabilityForOptions {
-  readonly buyer: LocalAccount;
+  readonly buyer: InvocationCapabilitySigner;
   readonly domain: InvocationCapabilityDomainInput;
   readonly serviceRef: Hex;
   /** Default {@link DEFAULT_CAPABILITY_TTL_SECONDS}. */
@@ -173,7 +172,7 @@ export interface InvokeOptions {
   /** Reads the stream's current serviceRef/operator/status/expiry. Real default: a `MetrikClient` instance. */
   readonly streamReader: InvokeStreamReader;
   /** The buyer's own wallet - signs the capability, never broadcasts a transaction. */
-  readonly buyer: LocalAccount;
+  readonly buyer: InvocationCapabilitySigner;
   /** `{chainId, verifyingContract}` - the `StreamEscrowV2` the stream settles on. */
   readonly domain: InvocationCapabilityDomainInput;
   /** Preferred: a cryptographically verified result from discoverServices(). */
@@ -226,6 +225,10 @@ export async function invoke(
     stream.serviceRef,
     options,
   );
+  // Resolve BEFORE signing. A path that escapes the signed base must never
+  // cause a buyer-signed capability to exist at all, let alone be sent
+  // somewhere the operator did not sign.
+  const url = resolveInvocationUrl(serviceBaseUrl, request.path);
 
   const capability = await capabilityFor(streamId, request, {
     buyer: options.buyer,
@@ -239,10 +242,6 @@ export async function invoke(
   });
 
   const header = encodeCapabilityHeader(capability);
-  const url = new URL(
-    request.path,
-    ensureTrailingSlash(serviceBaseUrl),
-  ).toString();
   const fetchImpl = options.fetchImpl ?? fetch;
   const response = await fetchImpl(url, {
     method: request.method,
@@ -484,10 +483,89 @@ function requireHttpUrl(value: string, label: string): string {
   return parsed.toString();
 }
 
+/**
+ * Characters that must never appear in an invocation path.
+ *
+ * The backslash is the important one. The WHATWG URL parser treats `\` as `/`
+ * for special schemes, so `/\evil.com/x` resolved against `https://good/`
+ * yields `https://evil.com/x` — a prefix check for `//` does not see it. C0
+ * controls and DEL are rejected alongside it because a header- or log-splitting
+ * character has no business in a path either.
+ */
+const FORBIDDEN_PATH_CHARACTERS = /[\\\u0000-\u001f\u007f]/;
+
 function assertOriginRelativePath(path: string): void {
-  if (!path.startsWith("/") || path.startsWith("//") || path.includes("#")) {
-    throw new InvokePathError(path);
+  if (!path.startsWith("/") || path.startsWith("//")) {
+    throw new InvokePathError(
+      `invocation path must be origin-relative and start with one slash: ${JSON.stringify(path)}`,
+    );
+  }
+  if (path.includes("#")) {
+    throw new InvokePathError(
+      `invocation path must not contain a fragment: ${JSON.stringify(path)}`,
+    );
+  }
+  if (FORBIDDEN_PATH_CHARACTERS.test(path)) {
+    throw new InvokePathError(
+      `invocation path must not contain a backslash or a control character: ${JSON.stringify(path)}`,
+    );
+  }
+}
+
+/**
+ * Resolves `path` against the operator-signed base URL and PROVES the result
+ * did not leave it.
+ *
+ * Prefix checks on the raw path are not sufficient and never were: the URL
+ * parser decides where a string points, so the only trustworthy check is to
+ * resolve first and then compare what came out. `/\evil.com/x` and
+ * `/a/../../b` both look origin-relative and both leave the signed base.
+ *
+ * What escaping would cost, concretely: the buyer's signed EIP-712 capability
+ * is handed to an attacker-controlled host, the attacker's response is
+ * returned to the caller as if it were the paid service's answer, and the
+ * MCP host's own network becomes reachable from a tool argument.
+ */
+export function resolveInvocationUrl(
+  serviceBaseUrl: string,
+  path: string,
+): string {
+  assertOriginRelativePath(path);
+  const base = new URL(ensureTrailingSlash(serviceBaseUrl));
+  let resolved: URL;
+  try {
+    resolved = new URL(path, base);
+  } catch {
+    throw new InvokePathError(
+      `invocation path does not resolve against the signed service URL: ${JSON.stringify(path)}`,
+    );
+  }
+  if (resolved.origin !== base.origin || resolved.origin === "null") {
+    throw new InvokePathError(
+      `invocation path resolves to ${resolved.origin}, which is not the operator-signed origin ${base.origin}`,
+    );
+  }
+  if (resolved.username !== "" || resolved.password !== "") {
+    throw new InvokePathError(
+      "invocation path must not carry credentials in the resolved URL",
+    );
+  }
+  // `base.pathname` always ends in `/` (ensureTrailingSlash), so a prefix match
+  // on the RESOLVED pathname is a true containment check — `..` segments have
+  // already been collapsed by the parser.
+  //
+  // An absolute-path reference replaces the whole path, so this ALSO rejects a
+  // signed base URL carrying a sub-path (`https://host/base/`). That is
+  // deliberate: the previous behaviour silently discarded the operator's signed
+  // `/base/` and called the origin root instead — an origin path the operator
+  // never signed, and one the gateway's own pathHash check could not match.
+  // Refusing says so instead of quietly calling the wrong place.
+  if (!resolved.pathname.startsWith(base.pathname)) {
+    throw new InvokePathError(
+      `invocation path ${JSON.stringify(path)} resolves to ${resolved.pathname}, which is outside the operator-signed base path ${base.pathname}. An origin-relative path replaces the whole path, so a signed base URL with a sub-path cannot be addressed this way.`,
+    );
   }
+  return resolved.toString();
 }
 
 function ensureTrailingSlash(value: string): string {