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

package/src/gateway/caller-auth-gateway.ts

@@ -1,4 +1,3 @@
-import { MetrikClient } from "@absol-labs/sdk";
 import { isAddress, isHex, type Address, type Hex } from "viem";
 
 import {
@@ -10,6 +9,29 @@ import {
   type InvocationCapabilityDomainInput,
   type SignedInvocationCapability,
 } from "../capability/invocation-capability.js";
+import {
+  decodeProbeCapabilityHeader,
+  hashProbePath,
+  InvalidProbeCapabilityHeaderError,
+  PROBE_CAPABILITY_HEADER_NAME,
+  recoverProbeCapabilitySigner,
+  type ProbeCapabilityDomainInput,
+  type SignedProbeCapability,
+} from "../capability/probe-capability.js";
+import {
+  CachedOracleSignerSet,
+  createSdkOracleSignerSetReader,
+  FixedWindowProbeRateLimiter,
+  type GatewayProbeMode,
+  type ProbeAuthorization,
+  type ProbeRateLimiter,
+} from "./probe-auth.js";
+import { defaultNetwork, readOnlyMetrikClient } from "../network.js";
+import {
+  isVerifiedSignedRateBounds,
+  rateOutsideBounds,
+  type SignedRateBounds,
+} from "./signed-rate-bounds.js";
 
 /**
  * Seller-side caller-auth gateway (metrik-agent#63, impl of #62 part 1/2).
@@ -69,7 +91,45 @@ export type CallerAuthDenialReason =
   | "stream-not-active"
   | "stream-expired"
   | "stream-not-funded"
-  | "stream-state-stale";
+  | "stream-state-stale"
+  /**
+   * The stream's on-chain `ratePerSecond` is outside the operator-SIGNED
+   * `minRatePerSecond`/`maxRatePerSecond` of this service's descriptor
+   * (metrik-contracts#41: the escrow accepts any non-zero rate, so a buyer
+   * calling it directly could otherwise open an underpriced stream and be
+   * served). Irreversible: the rate is fixed at open.
+   */
+  | "stream-rate-out-of-bounds"
+  /**
+   * Signed rate bounds are configured but the stream view carries no
+   * `ratePerSecond`, so the band cannot be checked. Fail closed.
+   */
+  | "stream-rate-unknown"
+  /**
+   * The request carried an oracle probe capability AND a buyer capability or an
+   * `X-PAYMENT` header. Refused rather than guessed: a probe is free and unbilled,
+   * a buyer call is neither, and the two must never be conflated.
+   */
+  | "ambiguous-probe-mode"
+  /**
+   * A probe capability was presented but this gateway has probe verification
+   * turned off. Distinct from the malformed/invalid reasons: it tells the
+   * oracle the paid route is UNVERIFIABLE here, not that it failed.
+   */
+  | "probe-not-enabled"
+  | "malformed-probe-capability"
+  | "probe-capability-expired"
+  | "probe-invalid-signature"
+  | "probe-method-mismatch"
+  | "probe-path-mismatch"
+  | "probe-service-ref-mismatch"
+  | "probe-nonce-replayed"
+  /** The recovered signer is not in the escrow's `getOracleSigners()` set. */
+  | "probe-signer-not-authorized"
+  /** The signer set could not be read fresh enough to decide. Fail closed. */
+  | "probe-signer-set-unavailable"
+  /** The free-probe budget for this window is spent. */
+  | "probe-rate-limited";
 
 /**
  * Default freshness bound for on-chain stream state, in seconds. Base blocks
@@ -92,7 +152,9 @@ const DENIAL_PRECEDENCE: readonly CallerAuthDenialReason[] = [
   "stream-expired",
   "buyer-mismatch",
   "service-ref-mismatch",
+  "stream-rate-out-of-bounds",
   "stream-not-funded",
+  "stream-rate-unknown",
   "stream-state-stale",
   "stream-not-found",
 ];
@@ -110,15 +172,36 @@ const DENIAL_PRECEDENCE: readonly CallerAuthDenialReason[] = [
 const TERMINAL_DENIALS: ReadonlySet<CallerAuthDenialReason> = new Set([
   "stream-not-active",
   "stream-not-funded",
+  // `ratePerSecond` is fixed at open and the signed band is this process's
+  // configuration, so an out-of-band stream stays out of band.
+  "stream-rate-out-of-bounds",
 ]);
 
+/**
+ * A probe carrying an `X-PAYMENT` header is refused as `ambiguous-probe-mode`.
+ * This gateway implements no per-call payment mode (the x402 v1 integration was
+ * removed in metrik-agent#115), but the refusal is kept deliberately: a probe
+ * is free, unbilled verification traffic and must never be mixed with anything
+ * that looks like a payment, and keeping it leaves the deployed gateway's
+ * behaviour byte-for-byte unchanged.
+ */
+const PAYMENT_HEADER_REFUSED_ON_PROBES = "x-payment";
+
 export interface CallerAuthDecision {
   readonly authorized: boolean;
   readonly reason?: CallerAuthDenialReason;
   /** Set only when `authorized === false`. */
-  readonly httpStatus?: 402 | 403;
-  /** Set only when `authorized === true`. */
+  readonly httpStatus?: 400 | 402 | 403 | 429;
+  /** Set only when `authorized === true` via the Metrik stream path. */
   readonly stream?: GatewayStreamView;
+  /**
+   * Set only when `authorized === true` via the ORACLE PROBE path. Mutually
+   * exclusive with {@link stream} by construction: the probe branch returns
+   * before a stream is ever produced, so an authorized probe can never draw on
+   * a stream's budget. It is
+   * verification traffic and MUST NOT be metered or billed.
+   */
+  readonly probe?: ProbeAuthorization;
   /** The decoded (but not necessarily valid) capability, when one was present. */
   readonly capability?: SignedInvocationCapability;
 }
@@ -131,6 +214,13 @@ export interface GatewayStreamView {
   readonly claimedCumulative: bigint;
   readonly expiresAt: number;
   readonly status: "active" | "closed";
+  /**
+   * The stream's contracted `ratePerSecond` (USDC base units per verified
+   * second), fixed at open. Required when the gateway enforces operator-signed
+   * rate bounds; a view without it is refused (`stream-rate-unknown`) there.
+   * The default SDK reader always reports it.
+   */
+  readonly ratePerSecond?: bigint;
   /**
    * The chain head this view was observed against. Readers SHOULD report it:
    * when present, the gateway rejects the view outright if the block is older
@@ -203,11 +293,10 @@ export class UnknownStreamGatewayError extends Error {
 export function createSdkStreamReader(options: {
   readonly escrowAddress: Address;
   readonly rpcUrl: string;
+  /** Chain of the escrow; must be a registered network. Default: the registry default. */
+  readonly chainId?: number;
 }): StreamReader {
-  const metrik = MetrikClient.baseSepolia({
-    escrow: options.escrowAddress,
-    rpcUrl: options.rpcUrl,
-  });
+  const metrik = readOnlyMetrikClient(options);
   return {
     async getStream(streamId) {
       try {
@@ -226,6 +315,7 @@ export function createSdkStreamReader(options: {
           claimedCumulative: stream.claimedCumulative,
           expiresAt: stream.expiresAt,
           status: stream.status,
+          ratePerSecond: stream.ratePerSecond,
           observedAt: {
             blockNumber: block.number,
             blockTimestamp: Number(block.timestamp),
@@ -284,7 +374,7 @@ export interface CallerAuthGatewayConfig {
   readonly serviceRef: Hex;
   /** Additional service refs accepted during signed-descriptor migrations. */
   readonly serviceRefs?: readonly Hex[];
-  /** Chain id for EIP-712 domain separation. Default `84532` (Base Sepolia). */
+  /** Chain id for EIP-712 domain separation and the default readers. Default: the registry's default network. */
   readonly chainId?: number;
   /** Capability header name. Default {@link CAPABILITY_HEADER_NAME}. */
   readonly headerName?: string;
@@ -316,6 +406,28 @@ export interface CallerAuthGatewayConfig {
   readonly nonceCache?: NonceReplayCache;
   /** Injectable clock (unix seconds), for tests. */
   readonly now?: () => number;
+  /**
+   * Optional ORACLE PROBE mode. When set, a request carrying a valid
+   * oracle-signed `ProbeCapability` is authorized and proxied WITHOUT any
+   * stream, payment or metering, so the neutral verifier can exercise this
+   * gateway's PAID route even though the listing is gated.
+   *
+   * OFF by default. A gateway that leaves it unset behaves byte for byte as
+   * before and answers a probe with `probe-not-enabled` / `403` — which the
+   * oracle reports as UNVERIFIABLE (health-route-only), never as passing.
+   */
+  readonly probe?: GatewayProbeMode;
+  /**
+   * Operator-SIGNED rate bounds to enforce on the capability path, one per
+   * served serviceRef (metrik-contracts#41). Each entry must come from
+   * {@link verifySignedRateBounds} (or `loadSignedRateBoundsFile`) and name one
+   * of this gateway's service refs. A stream whose serviceRef has bounds is
+   * served only while its on-chain `ratePerSecond` lies inside them.
+   *
+   * Unset = no rate enforcement here (the previous behaviour); the reference
+   * server warns when it starts without them.
+   */
+  readonly signedRateBounds?: readonly SignedRateBounds[];
 }
 
 export interface CallerAuthRequestInput {
@@ -341,6 +453,11 @@ export class CallerAuthGateway {
   private readonly domain: InvocationCapabilityDomainInput;
   private readonly serviceRefs: ReadonlySet<string>;
   private readonly now: () => number;
+  private readonly probeHeaderName: string;
+  private readonly probeDomain: ProbeCapabilityDomainInput;
+  private readonly probeSigners: CachedOracleSignerSet | undefined;
+  private readonly probeRateLimiter: ProbeRateLimiter | undefined;
+  private readonly rateBounds: ReadonlyMap<string, SignedRateBounds>;
 
   constructor(config: CallerAuthGatewayConfig) {
     if (!isAddress(config.escrowAddress)) {
@@ -358,7 +475,29 @@ export class CallerAuthGateway {
       );
     }
 
+    const chainId = config.chainId ?? defaultNetwork().chain.id;
     this.serviceRefs = new Set(serviceRefs.map((value) => value.toLowerCase()));
+    const rateBounds = new Map<string, SignedRateBounds>();
+    for (const bounds of config.signedRateBounds ?? []) {
+      if (!isVerifiedSignedRateBounds(bounds)) {
+        throw new Error(
+          "signedRateBounds entries must come from verifySignedRateBounds() / loadSignedRateBoundsFile(); an unverified object is not operator-signed",
+        );
+      }
+      const key = bounds.serviceRef.toLowerCase();
+      if (!this.serviceRefs.has(key)) {
+        throw new Error(
+          `signed rate bounds for ${bounds.serviceRef} are not a service ref this gateway serves`,
+        );
+      }
+      if (rateBounds.has(key)) {
+        throw new Error(
+          `more than one set of signed rate bounds for ${bounds.serviceRef}`,
+        );
+      }
+      rateBounds.set(key, bounds);
+    }
+    this.rateBounds = rateBounds;
     this.headerName = (
       config.headerName ?? CAPABILITY_HEADER_NAME
     ).toLowerCase();
@@ -367,6 +506,7 @@ export class CallerAuthGateway {
       createSdkStreamReader({
         escrowAddress: config.escrowAddress,
         rpcUrl: config.rpcUrl as string,
+        chainId,
       });
     const corroborating =
       config.corroboratingStreamReaders ??
@@ -374,6 +514,7 @@ export class CallerAuthGateway {
         createSdkStreamReader({
           escrowAddress: config.escrowAddress,
           rpcUrl,
+          chainId,
         }),
       );
     if (corroborating.length > MAX_CORROBORATING_STREAM_READERS) {
@@ -393,23 +534,105 @@ export class CallerAuthGateway {
       config.revocationSet ?? new InMemoryStreamRevocationSet();
     this.nonceCache = config.nonceCache ?? new InMemoryNonceReplayCache();
     this.domain = {
-      chainId: config.chainId ?? 84532,
+      chainId,
       verifyingContract: config.escrowAddress,
     };
     this.now = config.now ?? (() => Math.floor(Date.now() / 1000));
+
+    // Probe mode shares the chain binding with the invocation domain (same
+    // escrow, same chain) but a DIFFERENT EIP-712 domain name, so neither
+    // signature is ever valid as the other.
+    this.probeDomain = {
+      chainId,
+      verifyingContract: config.escrowAddress,
+    };
+    this.probeHeaderName = (
+      config.probe?.headerName ?? PROBE_CAPABILITY_HEADER_NAME
+    ).toLowerCase();
+    if (this.probeHeaderName === this.headerName) {
+      throw new Error(
+        "the probe capability header must differ from the invocation capability header",
+      );
+    }
+    if (config.probe === undefined) {
+      this.probeSigners = undefined;
+      this.probeRateLimiter = undefined;
+    } else {
+      const reader =
+        config.probe.signerSetReader ??
+        (config.rpcUrl === undefined
+          ? undefined
+          : createSdkOracleSignerSetReader({
+              escrowAddress: config.escrowAddress,
+              rpcUrl: config.rpcUrl,
+              chainId,
+            }));
+      if (reader === undefined) {
+        throw new Error(
+          "probe mode requires rpcUrl unless an explicit signerSetReader is supplied",
+        );
+      }
+      this.probeSigners = new CachedOracleSignerSet(
+        reader,
+        config.probe.signerCacheSeconds,
+        this.now,
+      );
+      this.probeRateLimiter =
+        config.probe.rateLimiter ??
+        new FixedWindowProbeRateLimiter(
+          config.probe.maxProbesPerMinute,
+          this.now,
+        );
+    }
+  }
+
+  /** Lower-cased header name that carries the buyer's invocation capability. */
+  get capabilityHeaderName(): string {
+    return this.headerName;
+  }
+
+  /** Lower-cased header name that carries an oracle probe capability. */
+  get probeCapabilityHeaderName(): string {
+    return this.probeHeaderName;
   }
 
   async authorize(
     request: CallerAuthRequestInput,
   ): Promise<CallerAuthDecision> {
     const headerValue = lookupHeader(request.headers, this.headerName);
-    if (headerValue === undefined || headerValue.length === 0) {
+    const hasCapabilityHeader =
+      headerValue !== undefined && headerValue.length > 0;
+
+    // ── Oracle probe path ────────────────────────────────────────────────
+    // Evaluated FIRST and returning unconditionally, so an authorized probe can
+    // never fall through into the stream branch. That ordering is the
+    // structural guarantee that a probe consumes no budget: no `stream` is ever
+    // produced on this path.
+    const probeHeaderValue = lookupHeader(
+      request.headers,
+      this.probeHeaderName,
+    );
+    if (probeHeaderValue !== undefined && probeHeaderValue.length > 0) {
+      const paymentHeader = lookupHeader(
+        request.headers,
+        PAYMENT_HEADER_REFUSED_ON_PROBES,
+      );
+      if (
+        hasCapabilityHeader ||
+        (paymentHeader !== undefined && paymentHeader.trim().length > 0)
+      ) {
+        return deny("ambiguous-probe-mode", 400);
+      }
+      return this.authorizeProbe(probeHeaderValue, request);
+    }
+
+    if (!hasCapabilityHeader) {
       return deny("missing-capability-header", 403);
     }
 
     let capability: SignedInvocationCapability;
     try {
-      capability = decodeCapabilityHeader(headerValue);
+      capability = decodeCapabilityHeader(headerValue as string);
     } catch (error) {
       if (error instanceof InvalidCapabilityHeaderError) {
         return deny("malformed-capability-header", 403);
@@ -501,6 +724,95 @@ export class CallerAuthGateway {
     return { authorized: true, stream: freshestView(views), capability };
   }
 
+  /**
+   * Authorize one oracle probe. Cheapest, most local gates first; the on-chain
+   * signer-set read is last so an unsigned or replayed flood cannot amplify
+   * into RPC load. Every failure mode is distinct and fail-closed.
+   */
+  private async authorizeProbe(
+    headerValue: string,
+    request: CallerAuthRequestInput,
+  ): Promise<CallerAuthDecision> {
+    const signerSet = this.probeSigners;
+    const rateLimiter = this.probeRateLimiter;
+    if (signerSet === undefined || rateLimiter === undefined) {
+      // Probe mode is off. Say so precisely: the oracle distinguishes
+      // "unverifiable here" from "the paid route failed".
+      return deny("probe-not-enabled", 403);
+    }
+
+    let capability: SignedProbeCapability;
+    try {
+      capability = decodeProbeCapabilityHeader(headerValue);
+    } catch (error) {
+      if (error instanceof InvalidProbeCapabilityHeaderError) {
+        return deny("malformed-probe-capability", 403);
+      }
+      throw error;
+    }
+
+    const nowSeconds = this.now();
+    if (nowSeconds >= capability.expiry) {
+      return deny("probe-capability-expired", 403);
+    }
+
+    let signer: Address;
+    try {
+      signer = await recoverProbeCapabilitySigner(
+        capability,
+        this.probeDomain,
+        capability.signature as Hex,
+      );
+    } catch {
+      return deny("probe-invalid-signature", 403);
+    }
+    if (signer.toLowerCase() !== capability.oracle.toLowerCase()) {
+      return deny("probe-invalid-signature", 403);
+    }
+
+    if (capability.method.toUpperCase() !== request.method.toUpperCase()) {
+      return deny("probe-method-mismatch", 403);
+    }
+    if (
+      hashProbePath(request.path).toLowerCase() !==
+      capability.pathHash.toLowerCase()
+    ) {
+      return deny("probe-path-mismatch", 403);
+    }
+    if (!this.serviceRefs.has(capability.serviceRef.toLowerCase())) {
+      return deny("probe-service-ref-mismatch", 403);
+    }
+
+    // Replay BEFORE the budget check: a captured capability replayed at volume
+    // must be rejected as a replay, not silently eat the honest probe budget.
+    // The SAME nonce cache as the buyer path, so a nonce can never be spent
+    // once as a probe and once as an invocation.
+    if (!this.nonceCache.consume(capability.nonce as Hex, capability.expiry)) {
+      return deny("probe-nonce-replayed", 403);
+    }
+
+    if (!rateLimiter.tryConsume()) {
+      return deny("probe-rate-limited", 429);
+    }
+
+    const signers = await signerSet.resolve();
+    if (signers === undefined) {
+      return deny("probe-signer-set-unavailable", 403);
+    }
+    if (!signers.has(signer.toLowerCase())) {
+      return deny("probe-signer-not-authorized", 403);
+    }
+
+    return {
+      authorized: true,
+      probe: {
+        oracle: signer,
+        serviceRef: capability.serviceRef as Hex,
+        expiry: capability.expiry,
+      },
+    };
+  }
+
   /** Returns the denial reason this single view produces, or `undefined` if it authorizes. */
   private evaluateView(
     stream: GatewayStreamView,
@@ -524,6 +836,17 @@ export class CallerAuthGateway {
     ) {
       return "service-ref-mismatch";
     }
+    // Operator-signed price band (metrik-contracts#41). Checked against the
+    // STREAM's serviceRef, which equals the capability's by the check above.
+    const bounds = this.rateBounds.get(stream.serviceRef.toLowerCase());
+    if (bounds !== undefined) {
+      if (stream.ratePerSecond === undefined) {
+        return "stream-rate-unknown";
+      }
+      if (rateOutsideBounds(stream.ratePerSecond, bounds) !== undefined) {
+        return "stream-rate-out-of-bounds";
+      }
+    }
     if (stream.status !== "active") {
       return "stream-not-active";
     }
@@ -569,7 +892,7 @@ function freshestView(views: readonly GatewayStreamView[]): GatewayStreamView {
 
 function deny(
   reason: CallerAuthDenialReason,
-  httpStatus: 402 | 403,
+  httpStatus: 400 | 402 | 403 | 429,
   capability?: SignedInvocationCapability,
 ): CallerAuthDecision {
   return {