@absol-labs/agent 0.11.0 → 0.12.0-rc.2

package/src/gateway/probe-auth.ts

@@ -0,0 +1,191 @@
+import { streamEscrowV2Abi } from "@absol-labs/shared";
+import type { Address } from "viem";
+import { readOnlyMetrikClient } from "../network.js";
+
+/**
+ * Seller-side plumbing for oracle-signed probe verification.
+ *
+ * Two pieces, both deliberately small and both fail-closed:
+ *
+ * 1. {@link OracleSignerSetReader} — WHO may mint a `ProbeCapability`. Read
+ *    straight off the escrow's `getOracleSigners()`, which is a public `view`.
+ *    There is no registration step, no shared secret, and no trust in the
+ *    oracle's own say-so: a third-party seller performs the identical read.
+ * 2. {@link ProbeRateLimiter} — how often a probe may be served for free.
+ *    Without a bound, an oracle-signed capability is a licence to consume the
+ *    seller's service indefinitely at no cost.
+ */
+
+/** Resolves the escrow's current oracle signer set (lowercased). */
+export interface OracleSignerSetReader {
+  getOracleSigners(): Promise<readonly Address[]>;
+}
+
+/** Default reader: a read-only `getOracleSigners()` call. No wallet, no writes. */
+export function createSdkOracleSignerSetReader(options: {
+  readonly escrowAddress: Address;
+  readonly rpcUrl: string;
+  /** Chain of the escrow; must be a registered network. Default: the registry default. */
+  readonly chainId?: number;
+}): OracleSignerSetReader {
+  const metrik = readOnlyMetrikClient(options);
+  return {
+    async getOracleSigners() {
+      return (await metrik.publicClient.readContract({
+        address: options.escrowAddress,
+        abi: streamEscrowV2Abi,
+        functionName: "getOracleSigners",
+      })) as readonly Address[];
+    },
+  };
+}
+
+/**
+ * Default freshness bound for the cached signer set, in seconds. The set only
+ * changes by an explicit escrow transaction, so a short cache costs nothing in
+ * correctness while keeping one RPC read off every probe.
+ */
+export const DEFAULT_ORACLE_SIGNER_CACHE_SECONDS = 60;
+
+/**
+ * Bounded-staleness cache over {@link OracleSignerSetReader}.
+ *
+ * FAIL-CLOSED by construction: once the cached set is older than its TTL it is
+ * discarded, and a refresh that fails resolves to `undefined` rather than
+ * serving the stale set. A probe is a free call, so "the RPC is down" must deny
+ * — which the oracle then reports as unverifiable, never as passing.
+ *
+ * Concurrent callers share one in-flight refresh, so a burst of probes cannot
+ * fan out into a burst of RPC reads.
+ */
+export class CachedOracleSignerSet {
+  private cached:
+    | { readonly signers: ReadonlySet<string>; readonly at: number }
+    | undefined;
+  private inFlight: Promise<ReadonlySet<string> | undefined> | undefined;
+
+  constructor(
+    private readonly reader: OracleSignerSetReader,
+    private readonly ttlSeconds: number = DEFAULT_ORACLE_SIGNER_CACHE_SECONDS,
+    private readonly now: () => number = () => Math.floor(Date.now() / 1000),
+  ) {
+    if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0) {
+      throw new Error(
+        "oracle signer cache ttlSeconds must be a positive number",
+      );
+    }
+  }
+
+  /** The current set, or `undefined` when it could not be read fresh enough. */
+  async resolve(): Promise<ReadonlySet<string> | undefined> {
+    const cached = this.cached;
+    if (cached !== undefined && this.now() - cached.at <= this.ttlSeconds) {
+      return cached.signers;
+    }
+    if (this.inFlight !== undefined) {
+      return this.inFlight;
+    }
+    const refresh = (async (): Promise<ReadonlySet<string> | undefined> => {
+      try {
+        const signers = await this.reader.getOracleSigners();
+        const set = new Set(signers.map((signer) => signer.toLowerCase()));
+        // An empty set is a real answer, and it means nobody may probe.
+        this.cached = { signers: set, at: this.now() };
+        return set;
+      } catch {
+        // Drop the stale entry rather than serving it: a signer REMOVED from
+        // the escrow must stop being able to probe within one TTL, not within
+        // "however long the RPC stays down".
+        this.cached = undefined;
+        return undefined;
+      } finally {
+        this.inFlight = undefined;
+      }
+    })();
+    this.inFlight = refresh;
+    return refresh;
+  }
+}
+
+/** Bounds how many probes this gateway will serve for free. */
+export interface ProbeRateLimiter {
+  /** Returns `true` (and consumes budget) IFF a probe may be served now. */
+  tryConsume(): boolean;
+}
+
+/**
+ * Default probe budget, in probes per minute.
+ *
+ * Derived from the real cadence, not picked round: the oracle checkpoints every
+ * ~15-22s, so a single vantage probes a given service at most ~4 times a
+ * minute. T1 multi-vantage fans that out across at most 9 vantages (the
+ * coordinator plus the 8-worker cap in the oracle's vantage config), giving a
+ * worst-case honest load of ~36 probes/minute. 60 leaves headroom for a
+ * re-execution sample and clock jitter while capping the free-service surface
+ * at one request per second — orders of magnitude below what would make this an
+ * economically interesting way to get the service for nothing.
+ */
+export const DEFAULT_MAX_PROBES_PER_MINUTE = 60;
+
+/**
+ * Fixed-window probe limiter. One counter for the whole gateway (which fronts
+ * one service), so the bound holds no matter how many oracle signers exist or
+ * how many vantages a coordinator runs.
+ *
+ * A useful secondary effect: because every probe capability is single-use and
+ * short-lived, this limiter is also what bounds the shared nonce replay cache —
+ * at most `maxPerMinute x ttl/60` probe nonces can be live at once.
+ */
+export class FixedWindowProbeRateLimiter implements ProbeRateLimiter {
+  private windowStart: number;
+  private count = 0;
+
+  constructor(
+    private readonly maxPerMinute: number = DEFAULT_MAX_PROBES_PER_MINUTE,
+    private readonly now: () => number = () => Math.floor(Date.now() / 1000),
+  ) {
+    if (!Number.isInteger(maxPerMinute) || maxPerMinute <= 0) {
+      throw new Error("maxProbesPerMinute must be a positive integer");
+    }
+    this.windowStart = this.now();
+  }
+
+  tryConsume(): boolean {
+    const nowSeconds = this.now();
+    if (nowSeconds - this.windowStart >= 60) {
+      this.windowStart = nowSeconds;
+      this.count = 0;
+    }
+    if (this.count >= this.maxPerMinute) {
+      return false;
+    }
+    this.count += 1;
+    return true;
+  }
+}
+
+/** Opt-in probe verification mode for {@link CallerAuthGateway}. */
+export interface GatewayProbeMode {
+  /**
+   * Who may mint. Defaults to a read-only `getOracleSigners()` reader built
+   * from the gateway's own escrow + RPC.
+   */
+  readonly signerSetReader?: OracleSignerSetReader;
+  /** Freshness bound for the cached signer set. Default {@link DEFAULT_ORACLE_SIGNER_CACHE_SECONDS}. */
+  readonly signerCacheSeconds?: number;
+  /** Probe budget. Default {@link DEFAULT_MAX_PROBES_PER_MINUTE}. */
+  readonly maxProbesPerMinute?: number;
+  /** Override the limiter entirely (tests, or a shared multi-instance store). */
+  readonly rateLimiter?: ProbeRateLimiter;
+  /** Probe capability header name. Default `x-metrik-probe-capability`. */
+  readonly headerName?: string;
+}
+
+/** What an authorized probe tells the caller. Carries NO stream and NO payment. */
+export interface ProbeAuthorization {
+  /** The oracle signer that minted the capability. */
+  readonly oracle: Address;
+  readonly serviceRef: `0x${string}`;
+  /** Unix seconds the capability expires at. */
+  readonly expiry: number;
+}

package/src/gateway/signed-rate-bounds.ts

@@ -0,0 +1,164 @@
+import { readFile } from "node:fs/promises";
+
+import {
+  deriveServiceRef,
+  recoverServiceDescriptorSigner,
+  signedServiceDescriptorSchema,
+} from "@absol-labs/shared";
+import { getAddress, type Address, type Hex } from "viem";
+
+/**
+ * Operator-SIGNED rate bounds for the gateway's capability path
+ * (metrik-agent#121 item 5, metrik-contracts#41).
+ *
+ * `StreamEscrowV2.openStream` only requires `ratePerSecond != 0`; the seller's
+ * signed `minRatePerSecond` / `maxRatePerSecond` are checked by the buyer-side
+ * SDK and the marketplace, not by the contract. A buyer who calls the escrow
+ * directly can therefore open a stream at 1 base unit per second. The gateway
+ * is the seller's own trust boundary, so it refuses to SERVE such a stream:
+ * the on-chain `ratePerSecond` must fall inside the band the operator signed.
+ *
+ * Bounds are only ever taken from a signed descriptor that verifies here — the
+ * serviceRef re-derives from the signed content and the EIP-712 signature
+ * recovers to the descriptor's operator. `CallerAuthGateway` accepts only
+ * objects this module produced, so a hand-built `{ minRatePerSecond: 0n }`
+ * cannot slip through as "signed".
+ */
+export interface SignedRateBounds {
+  /** The serviceRef the bounds were signed for (re-derived, lower-case). */
+  readonly serviceRef: Hex;
+  /** The operator whose EIP-712 signature was recovered. */
+  readonly operator: Address;
+  /** Signed minimum rate, USDC base units per second; `null` = none signed. */
+  readonly minRatePerSecond: bigint | null;
+  /** Signed maximum rate, USDC base units per second; `null` = none signed. */
+  readonly maxRatePerSecond: bigint | null;
+}
+
+export class SignedRateBoundsError extends Error {
+  constructor(message: string, options?: { readonly cause?: unknown }) {
+    super(message, options);
+    this.name = "SignedRateBoundsError";
+  }
+}
+
+const verified = new WeakSet<object>();
+
+/** Whether `bounds` came out of {@link verifySignedRateBounds} in this process. */
+export function isVerifiedSignedRateBounds(
+  bounds: unknown,
+): bounds is SignedRateBounds {
+  return typeof bounds === "object" && bounds !== null && verified.has(bounds);
+}
+
+/**
+ * Verify a signed service descriptor and extract its operator-signed rate band.
+ * Throws {@link SignedRateBoundsError} unless the schema parses, the serviceRef
+ * re-derives from the signed content, and the signature recovers to the
+ * descriptor's operator.
+ */
+export async function verifySignedRateBounds(
+  signedDescriptor: unknown,
+): Promise<SignedRateBounds> {
+  const parsed = signedServiceDescriptorSchema.safeParse(signedDescriptor);
+  if (!parsed.success) {
+    throw new SignedRateBoundsError(
+      `not a signed service descriptor: ${parsed.error.issues
+        .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+        .join("; ")}`,
+    );
+  }
+  const signed = parsed.data;
+  const derived = deriveServiceRef(signed.descriptor).toLowerCase() as Hex;
+  if (signed.serviceRef.toLowerCase() !== derived) {
+    throw new SignedRateBoundsError(
+      `the signed descriptor's serviceRef ${signed.serviceRef} does not derive from its content (${derived}); it was tampered with or re-labelled`,
+    );
+  }
+  let signer: Address | null;
+  try {
+    signer = await recoverServiceDescriptorSigner(
+      signed.descriptor,
+      signed.signature as Hex,
+    );
+  } catch (cause) {
+    throw new SignedRateBoundsError(
+      "the signed descriptor's signature could not be recovered",
+      { cause },
+    );
+  }
+  if (
+    signer === null ||
+    signer.toLowerCase() !== signed.descriptor.operator.toLowerCase()
+  ) {
+    throw new SignedRateBoundsError(
+      `the descriptor for ${derived} is not signed by its operator ${signed.descriptor.operator}`,
+    );
+  }
+  const commercial = signed.descriptor.commercial;
+  const bounds: SignedRateBounds = Object.freeze({
+    serviceRef: derived,
+    operator: getAddress(signed.descriptor.operator),
+    minRatePerSecond:
+      commercial?.minRatePerSecond === undefined
+        ? null
+        : BigInt(commercial.minRatePerSecond),
+    maxRatePerSecond:
+      commercial?.maxRatePerSecond === undefined
+        ? null
+        : BigInt(commercial.maxRatePerSecond),
+  });
+  verified.add(bounds);
+  return bounds;
+}
+
+/**
+ * Load and verify the signed descriptor(s) in a JSON file: one signed
+ * descriptor object, or an array of them (one per served serviceRef, e.g. a
+ * migration alias). Fail closed on any read, parse or verification error.
+ */
+export async function loadSignedRateBoundsFile(
+  path: string,
+): Promise<SignedRateBounds[]> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (cause) {
+    throw new SignedRateBoundsError(
+      `could not read the signed descriptor file ${path}`,
+      { cause },
+    );
+  }
+  let json: unknown;
+  try {
+    json = JSON.parse(raw);
+  } catch (cause) {
+    throw new SignedRateBoundsError(
+      `the signed descriptor file ${path} is not valid JSON`,
+      { cause },
+    );
+  }
+  const entries = Array.isArray(json) ? json : [json];
+  if (entries.length === 0) {
+    throw new SignedRateBoundsError(
+      `the signed descriptor file ${path} holds no descriptor`,
+    );
+  }
+  return await Promise.all(
+    entries.map((entry) => verifySignedRateBounds(entry)),
+  );
+}
+
+/** `undefined` when `rate` is inside the band, otherwise why it is not. */
+export function rateOutsideBounds(
+  rate: bigint,
+  bounds: SignedRateBounds,
+): string | undefined {
+  if (bounds.minRatePerSecond !== null && rate < bounds.minRatePerSecond) {
+    return `rate ${rate} is below the operator-signed minimum ${bounds.minRatePerSecond}`;
+  }
+  if (bounds.maxRatePerSecond !== null && rate > bounds.maxRatePerSecond) {
+    return `rate ${rate} is above the operator-signed maximum ${bounds.maxRatePerSecond}`;
+  }
+  return undefined;
+}