@absol-labs/agent 0.7.2 → 0.8.0

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

@@ -22,6 +22,36 @@ import {
  * called. Revocation is automatic: once a stream is closed/expired/reclaimed,
  * the on-chain read step below fails closed and access stops with no extra
  * bookkeeping.
+ *
+ * ## Stream state must never be trusted from a single unverified view (#87)
+ *
+ * A capability presented seconds after the buyer's `close()` was mined was
+ * served, because authorization read the stream from ONE unpinned `latest`
+ * view and believed it unconditionally: the exposure window was exactly
+ * "however stale that view happened to be" - unbounded and unobservable.
+ * Provider replica lag, an unsafe-head reorg, provider response caching, or a
+ * cache added later for performance all land in the same failure mode, and it
+ * fails OPEN on the one transition that must be immediate.
+ *
+ * Three fail-closed properties remove that trust:
+ *
+ * 1. **Corroboration** - every configured view is read (bounded: one read per
+ *    view, in parallel) and the request is authorized ONLY if EVERY view
+ *    authorizes. Any view reporting a non-authorizable stream - or failing to
+ *    read at all - denies. Independent endpoints go stale independently, so
+ *    configuring one corroborating RPC collapses the window to the freshest of
+ *    them.
+ * 2. **Freshness bound** - a view that reports the block it observed
+ *    ({@link GatewayStreamView.observedAt}) is rejected outright when that
+ *    block is older than {@link CallerAuthGatewayConfig.maxStateStalenessSeconds},
+ *    turning silent staleness into an explicit `stream-state-stale` denial.
+ * 3. **Monotonic revocation** - `StreamEscrowV2` only ever assigns
+ *    `status = Closed` (never resets it), only ever decreases `deposit` (there
+ *    is no top-up), and fixes `expiresAt` at open. "Not active", "expired" and
+ *    "fully claimed" are therefore irreversible, so an observed terminal state
+ *    is remembered and a later view reporting ACTIVE - which is provably stale
+ *    - can never re-authorize. This is the only correctness-preserving caching
+ *    direction here: negative, never positive.
  */
 
 /** Machine-readable, closed set of rejection reasons - every failure mode is distinct. */
@@ -38,7 +68,49 @@ export type CallerAuthDenialReason =
   | "buyer-mismatch"
   | "stream-not-active"
   | "stream-expired"
-  | "stream-not-funded";
+  | "stream-not-funded"
+  | "stream-state-stale";
+
+/**
+ * Default freshness bound for on-chain stream state, in seconds. Base blocks
+ * are ~2s, so a healthy endpoint is a few seconds stale at most; this is a
+ * generous ceiling whose job is to reject GROSS staleness rather than to
+ * micro-manage a healthy provider.
+ */
+export const DEFAULT_MAX_STATE_STALENESS_SECONDS = 30;
+
+/** Maximum corroborating views the bounded hot path accepts (excludes the primary). */
+export const MAX_CORROBORATING_STREAM_READERS = 3;
+
+/**
+ * Denial precedence when views disagree: the most authoritative statement about
+ * the stream wins, so a single fresh "closed" is never masked by another view's
+ * read error or staleness.
+ */
+const DENIAL_PRECEDENCE: readonly CallerAuthDenialReason[] = [
+  "stream-not-active",
+  "stream-expired",
+  "buyer-mismatch",
+  "service-ref-mismatch",
+  "stream-not-funded",
+  "stream-state-stale",
+  "stream-not-found",
+];
+
+/**
+ * Denials that reflect an IRREVERSIBLE on-chain state (see the class docs):
+ * once observed, they hold forever, so they are remembered and a stale ACTIVE
+ * read can never re-authorize.
+ *
+ * Deliberately limited to states derived PURELY from on-chain values. Expiry is
+ * equally irreversible but is derived from the local clock, and a skewed clock
+ * must not be able to permanently revoke a live stream - expiry re-denies on
+ * every request anyway, at no extra cost.
+ */
+const TERMINAL_DENIALS: ReadonlySet<CallerAuthDenialReason> = new Set([
+  "stream-not-active",
+  "stream-not-funded",
+]);
 
 export interface CallerAuthDecision {
   readonly authorized: boolean;
@@ -59,6 +131,18 @@ export interface GatewayStreamView {
   readonly claimedCumulative: bigint;
   readonly expiresAt: number;
   readonly status: "active" | "closed";
+  /**
+   * 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
+   * than its freshness bound (`stream-state-stale`) instead of trusting
+   * unbounded staleness. Optional only so `StreamReader` implementations
+   * predating this field keep working; the default SDK reader always reports it.
+   */
+  readonly observedAt?: {
+    readonly blockNumber: bigint;
+    /** Unix seconds of the observed block. */
+    readonly blockTimestamp: number;
+  };
 }
 
 /** Pluggable on-chain stream reader, so the gateway is testable without a live RPC. */
@@ -66,6 +150,48 @@ export interface StreamReader {
   getStream(streamId: Hex): Promise<GatewayStreamView>;
 }
 
+/**
+ * Remembers streams observed in an irreversible terminal state, so a later
+ * stale view cannot re-authorize them. Negative-only by construction: nothing
+ * that would GRANT access is ever cached.
+ */
+export interface StreamRevocationSet {
+  /** The remembered terminal denial for this stream, if any. */
+  get(streamId: Hex): CallerAuthDenialReason | undefined;
+  /** Records an irreversible terminal denial for this stream. */
+  record(streamId: Hex, reason: CallerAuthDenialReason): void;
+}
+
+/**
+ * In-memory {@link StreamRevocationSet}. Bounded (oldest entries are evicted
+ * past {@link maxEntries}) so a hostile caller cannot grow it without limit;
+ * eviction is safe because the on-chain read still denies an evicted stream -
+ * it only loses the short-circuit.
+ */
+export class InMemoryStreamRevocationSet implements StreamRevocationSet {
+  private readonly revoked = new Map<string, CallerAuthDenialReason>();
+
+  constructor(private readonly maxEntries = 10_000) {}
+
+  get(streamId: Hex): CallerAuthDenialReason | undefined {
+    return this.revoked.get(streamId.toLowerCase());
+  }
+
+  record(streamId: Hex, reason: CallerAuthDenialReason): void {
+    const key = streamId.toLowerCase();
+    if (this.revoked.has(key)) {
+      return;
+    }
+    if (this.revoked.size >= this.maxEntries) {
+      const oldest = this.revoked.keys().next();
+      if (!oldest.done) {
+        this.revoked.delete(oldest.value);
+      }
+    }
+    this.revoked.set(key, reason);
+  }
+}
+
 export class UnknownStreamGatewayError extends Error {
   constructor(message: string, options?: { readonly cause?: unknown }) {
     super(message, options);
@@ -85,7 +211,14 @@ export function createSdkStreamReader(options: {
   return {
     async getStream(streamId) {
       try {
-        const stream = await metrik.getStreamV2(streamId);
+        // Read the stream and the chain head this endpoint is serving in one
+        // round trip (concurrent, same transport) so the view can be
+        // freshness-checked. A failed head read is treated as an unusable view
+        // (fail closed) rather than silently dropping the freshness signal.
+        const [stream, block] = await Promise.all([
+          metrik.getStreamV2(streamId),
+          metrik.publicClient.getBlock({ blockTag: "latest" }),
+        ]);
         return {
           buyer: stream.buyer,
           serviceRef: stream.serviceRef,
@@ -93,6 +226,10 @@ export function createSdkStreamReader(options: {
           claimedCumulative: stream.claimedCumulative,
           expiresAt: stream.expiresAt,
           status: stream.status,
+          observedAt: {
+            blockNumber: block.number,
+            blockTimestamp: Number(block.timestamp),
+          },
         };
       } catch (cause) {
         throw new UnknownStreamGatewayError(
@@ -153,6 +290,28 @@ export interface CallerAuthGatewayConfig {
   readonly headerName?: string;
   /** Override the on-chain reader (tests inject a fake; default is the real SDK reader). */
   readonly streamReader?: StreamReader;
+  /**
+   * Independent corroborating views of the SAME escrow. Every view is read per
+   * request (in parallel) and the request is authorized only if EVERY view
+   * authorizes - so a stale primary cannot serve a closed stream. Bounded to
+   * {@link MAX_CORROBORATING_STREAM_READERS}.
+   */
+  readonly corroboratingStreamReaders?: readonly StreamReader[];
+  /**
+   * Corroborating RPC endpoints for the default SDK reader path. One reader is
+   * built per URL; ignored when `corroboratingStreamReaders` is supplied.
+   * Use endpoints on DIFFERENT providers - two URLs on one provider share its
+   * staleness.
+   */
+  readonly corroboratingRpcUrls?: readonly string[];
+  /**
+   * Reject stream state observed more than this many seconds behind the wall
+   * clock. Default {@link DEFAULT_MAX_STATE_STALENESS_SECONDS}. Enforced only
+   * for views that report {@link GatewayStreamView.observedAt}.
+   */
+  readonly maxStateStalenessSeconds?: number;
+  /** Override the terminal-state memory (default in-memory, bounded). */
+  readonly revocationSet?: StreamRevocationSet;
   /** Override the replay cache (tests inject a fake; default is in-memory). */
   readonly nonceCache?: NonceReplayCache;
   /** Injectable clock (unix seconds), for tests. */
@@ -174,7 +333,9 @@ export interface CallerAuthRequestInput {
  * See `./http-server.ts` for a ready-to-run reverse-proxy reference server.
  */
 export class CallerAuthGateway {
-  private readonly streamReader: StreamReader;
+  private readonly streamReaders: readonly StreamReader[];
+  private readonly maxStateStalenessSeconds: number;
+  private readonly revocationSet: StreamRevocationSet;
   private readonly nonceCache: NonceReplayCache;
   private readonly headerName: string;
   private readonly domain: InvocationCapabilityDomainInput;
@@ -201,12 +362,35 @@ export class CallerAuthGateway {
     this.headerName = (
       config.headerName ?? CAPABILITY_HEADER_NAME
     ).toLowerCase();
-    this.streamReader =
+    const primaryReader =
       config.streamReader ??
       createSdkStreamReader({
         escrowAddress: config.escrowAddress,
         rpcUrl: config.rpcUrl as string,
       });
+    const corroborating =
+      config.corroboratingStreamReaders ??
+      (config.corroboratingRpcUrls ?? []).map((rpcUrl) =>
+        createSdkStreamReader({
+          escrowAddress: config.escrowAddress,
+          rpcUrl,
+        }),
+      );
+    if (corroborating.length > MAX_CORROBORATING_STREAM_READERS) {
+      throw new Error(
+        `at most ${MAX_CORROBORATING_STREAM_READERS} corroborating stream readers are supported (bounded hot path)`,
+      );
+    }
+    this.streamReaders = [primaryReader, ...corroborating];
+
+    const maxStaleness =
+      config.maxStateStalenessSeconds ?? DEFAULT_MAX_STATE_STALENESS_SECONDS;
+    if (!Number.isFinite(maxStaleness) || maxStaleness <= 0) {
+      throw new Error("maxStateStalenessSeconds must be a positive number");
+    }
+    this.maxStateStalenessSeconds = maxStaleness;
+    this.revocationSet =
+      config.revocationSet ?? new InMemoryStreamRevocationSet();
     this.nonceCache = config.nonceCache ?? new InMemoryNonceReplayCache();
     this.domain = {
       chainId: config.chainId ?? 84532,
@@ -272,33 +456,115 @@ export class CallerAuthGateway {
       return deny("nonce-replayed", 403, capability);
     }
 
-    let stream: GatewayStreamView;
-    try {
-      stream = await this.streamReader.getStream(capability.streamId as Hex);
-    } catch {
-      return deny("stream-not-found", 403, capability);
+    const streamId = capability.streamId as Hex;
+
+    // An irreversible terminal state already observed for this stream holds
+    // forever: no read can un-close it, so short-circuit (and never re-read a
+    // dead stream).
+    const revoked = this.revocationSet.get(streamId);
+    if (revoked !== undefined) {
+      return deny(revoked, httpStatusFor(revoked), capability);
     }
 
+    // Read EVERY configured view (bounded: one read per view, all in parallel).
+    const results = await Promise.allSettled(
+      this.streamReaders.map((reader) => reader.getStream(streamId)),
+    );
+
+    // Strictest view wins. A view that fails to read, is measurably stale, or
+    // reports a non-authorizable stream denies the request - authorization
+    // requires unanimous consent from every view.
+    const denials: CallerAuthDenialReason[] = [];
+    const views: GatewayStreamView[] = [];
+    for (const result of results) {
+      if (result.status === "rejected") {
+        denials.push("stream-not-found");
+        continue;
+      }
+      const reason = this.evaluateView(result.value, capability, nowSeconds);
+      if (reason === undefined) {
+        views.push(result.value);
+      } else {
+        denials.push(reason);
+      }
+    }
+
+    if (denials.length > 0) {
+      const reason = strictestDenial(denials);
+      if (TERMINAL_DENIALS.has(reason)) {
+        this.revocationSet.record(streamId, reason);
+      }
+      return deny(reason, httpStatusFor(reason), capability);
+    }
+
+    // Report the freshest corroborated view to the caller.
+    return { authorized: true, stream: freshestView(views), capability };
+  }
+
+  /** Returns the denial reason this single view produces, or `undefined` if it authorizes. */
+  private evaluateView(
+    stream: GatewayStreamView,
+    capability: SignedInvocationCapability,
+    nowSeconds: number,
+  ): CallerAuthDenialReason | undefined {
+    // Freshness first: a measurably stale view is not evidence of anything, so
+    // it must not be able to vouch for an ACTIVE stream.
+    if (
+      stream.observedAt !== undefined &&
+      nowSeconds - stream.observedAt.blockTimestamp >
+        this.maxStateStalenessSeconds
+    ) {
+      return "stream-state-stale";
+    }
     if (stream.buyer.toLowerCase() !== capability.buyer.toLowerCase()) {
-      return deny("buyer-mismatch", 403, capability);
+      return "buyer-mismatch";
     }
     if (
       stream.serviceRef.toLowerCase() !== capability.serviceRef.toLowerCase()
     ) {
-      return deny("service-ref-mismatch", 403, capability);
+      return "service-ref-mismatch";
     }
     if (stream.status !== "active") {
-      return deny("stream-not-active", 403, capability);
+      return "stream-not-active";
     }
     if (nowSeconds >= stream.expiresAt) {
-      return deny("stream-expired", 403, capability);
+      return "stream-expired";
     }
     if (stream.deposit <= stream.claimedCumulative) {
-      return deny("stream-not-funded", 402, capability);
+      return "stream-not-funded";
+    }
+    return undefined;
+  }
+}
+
+function httpStatusFor(reason: CallerAuthDenialReason): 402 | 403 {
+  return reason === "stream-not-funded" ? 402 : 403;
+}
+
+function strictestDenial(
+  denials: readonly CallerAuthDenialReason[],
+): CallerAuthDenialReason {
+  for (const candidate of DENIAL_PRECEDENCE) {
+    if (denials.includes(candidate)) {
+      return candidate;
     }
+  }
+  return denials[0] as CallerAuthDenialReason;
+}
 
-    return { authorized: true, stream, capability };
+function freshestView(views: readonly GatewayStreamView[]): GatewayStreamView {
+  let freshest = views[0] as GatewayStreamView;
+  for (const view of views.slice(1)) {
+    const current = freshest.observedAt?.blockNumber;
+    const candidate = view.observedAt?.blockNumber;
+    if (
+      candidate !== undefined &&
+      (current === undefined || candidate > current)
+    ) {
+      freshest = view;
+    }
   }
+  return freshest;
 }
 
 function deny(

package/src/gateway/http-server.ts

@@ -10,6 +10,8 @@ import { isAddress, isHex, type Address, type Hex } from "viem";
 
 import {
   CallerAuthGateway,
+  DEFAULT_MAX_STATE_STALENESS_SECONDS,
+  MAX_CORROBORATING_STREAM_READERS,
   type CallerAuthDenialReason,
 } from "./caller-auth-gateway.js";
 
@@ -236,6 +238,10 @@ export interface CallerAuthGatewayEnvConfig {
   readonly chainId: number;
   readonly upstreamUrl: string;
   readonly headerName?: string;
+  /** Independent RPCs used to corroborate stream state (see `CallerAuthGateway`). */
+  readonly corroboratingRpcUrls: readonly string[];
+  /** Freshness bound for on-chain stream state, in seconds. */
+  readonly maxStateStalenessSeconds: number;
 }
 
 /**
@@ -246,6 +252,14 @@ export interface CallerAuthGatewayEnvConfig {
  * - `METRIK_GATEWAY_SERVICE_REF` (required) - primary bytes32 service ref.
  * - `METRIK_GATEWAY_SERVICE_REFS` (optional) - comma-separated migration aliases.
  * - `METRIK_GATEWAY_UPSTREAM_URL` (required) - the real service to proxy to on pass.
+ * - `METRIK_GATEWAY_CORROBORATING_RPC_URLS` (optional, STRONGLY recommended) -
+ *   comma-separated INDEPENDENT RPC endpoints for the same escrow. Stream state
+ *   is authorized only if every configured view agrees, so a stale primary view
+ *   cannot serve a stream that has just been closed. At most
+ *   {@link MAX_CORROBORATING_STREAM_READERS}.
+ * - `METRIK_GATEWAY_MAX_STATE_STALENESS_SECONDS` (optional) - reject stream
+ *   state observed more than N seconds behind the wall clock. Default
+ *   {@link DEFAULT_MAX_STATE_STALENESS_SECONDS}.
  * - `METRIK_GATEWAY_CHAIN_ID` (optional) - default `84532` (Base Sepolia).
  * - `METRIK_GATEWAY_HEADER_NAME` (optional) - default `x-metrik-capability`.
  * - `PORT` / `METRIK_GATEWAY_PORT` (optional) - default `8787`.
@@ -295,6 +309,43 @@ export function parseCallerAuthGatewayEnvConfig(
   const host = env.METRIK_GATEWAY_HOST ?? "0.0.0.0";
   const headerName = env.METRIK_GATEWAY_HEADER_NAME;
 
+  const corroboratingRpcUrls = [
+    ...new Set(
+      (env.METRIK_GATEWAY_CORROBORATING_RPC_URLS ?? "")
+        .split(",")
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0),
+    ),
+  ];
+  for (const candidate of corroboratingRpcUrls) {
+    try {
+      // eslint-disable-next-line no-new -- validates the URL is well-formed.
+      new URL(candidate);
+    } catch {
+      throw new Error(
+        `METRIK_GATEWAY_CORROBORATING_RPC_URLS must contain only valid URLs (got ${candidate})`,
+      );
+    }
+  }
+  if (corroboratingRpcUrls.length > MAX_CORROBORATING_STREAM_READERS) {
+    throw new Error(
+      `METRIK_GATEWAY_CORROBORATING_RPC_URLS accepts at most ${MAX_CORROBORATING_STREAM_READERS} URLs (bounded hot path)`,
+    );
+  }
+
+  const stalenessRaw =
+    env.METRIK_GATEWAY_MAX_STATE_STALENESS_SECONDS ??
+    String(DEFAULT_MAX_STATE_STALENESS_SECONDS);
+  const maxStateStalenessSeconds = Number(stalenessRaw);
+  if (
+    !Number.isInteger(maxStateStalenessSeconds) ||
+    maxStateStalenessSeconds <= 0
+  ) {
+    throw new Error(
+      `invalid METRIK_GATEWAY_MAX_STATE_STALENESS_SECONDS: ${stalenessRaw}`,
+    );
+  }
+
   return {
     host,
     port,
@@ -306,6 +357,8 @@ export function parseCallerAuthGatewayEnvConfig(
     ] as Hex[],
     chainId,
     upstreamUrl,
+    corroboratingRpcUrls,
+    maxStateStalenessSeconds,
     ...(headerName === undefined ? {} : { headerName }),
   };
 }
@@ -329,10 +382,21 @@ export async function startCallerAuthGatewayServerFromEnv(
     serviceRef: config.serviceRef,
     serviceRefs: config.serviceRefs,
     chainId: config.chainId,
+    corroboratingRpcUrls: config.corroboratingRpcUrls,
+    maxStateStalenessSeconds: config.maxStateStalenessSeconds,
     ...(config.headerName === undefined
       ? {}
       : { headerName: config.headerName }),
   });
+  if (config.corroboratingRpcUrls.length === 0) {
+    console.error(
+      "[metrik-caller-auth-gateway] WARNING: no METRIK_GATEWAY_CORROBORATING_RPC_URLS " +
+        "configured — stream state is authorized from a single RPC view. A stale view " +
+        "can authorize a stream that has just been closed (bounded to " +
+        `${config.maxStateStalenessSeconds}s by the freshness check). Configure at least ` +
+        "one INDEPENDENT provider to close that window.",
+    );
+  }
   const server = createCallerAuthGatewayServer({
     gateway,
     upstreamUrl: config.upstreamUrl,

package/src/index.ts

@@ -154,26 +154,41 @@ export {
 export {
   AUTONOMOUS_WALLET_CAIP2,
   AUTONOMOUS_WALLET_CHAIN_ID,
+  AUTONOMOUS_WALLET_KEYCHAIN_SERVICE,
   AUTONOMOUS_WALLET_VERSION,
   METRIK_AUTONOMOUS_WALLET_BROKER_URL,
+  METRIK_WALLET_ENCRYPTION_KEY_ENV,
+  METRIK_WALLET_STORE_DIR_ENV,
   AutonomousWalletError,
+  EncryptedFileCredentialStore,
   HttpAutonomousWalletBroker,
   InMemoryAutonomousWalletStore,
   OsCredentialStore,
+  assertDurableCredentialStore,
   autonomousProofBytes,
   createAutonomousWalletAccount,
   createAutonomousWalletProvider,
   createDefaultAutonomousWalletStore,
+  probeSecretServiceAvailable,
   provisionAutonomousWallet,
   provisionMetrikAutonomousWallet,
+  type AssertDurableCredentialStoreOptions,
   type AutonomousWalletBroker as AutonomousWalletClientBroker,
   type AutonomousWalletCredentialStore,
   type AutonomousWalletProof,
   type AutonomousWalletRecord,
   type CreateAutonomousWalletProviderOptions,
+  type CredentialStoreDurability,
+  type CredentialStoreDurabilityReport,
+  type EncryptedFileCredentialStoreOptions,
+  type OsCredentialStoreOptions,
   type PreparedPrivyRequest,
+  type ProbeSecretServiceOptions,
   type ProvisionAutonomousWalletOptions,
   type ProvisionMetrikAutonomousWalletOptions,
+  type SecretEntryFactory,
+  type SecretEntryLike,
+  type SecretServiceProbeResult,
 } from "./wallet/autonomous-wallet.js";
 
 export {
@@ -271,7 +286,10 @@ export {
 
 export {
   CallerAuthGateway,
+  DEFAULT_MAX_STATE_STALENESS_SECONDS,
   InMemoryNonceReplayCache,
+  InMemoryStreamRevocationSet,
+  MAX_CORROBORATING_STREAM_READERS,
   UnknownStreamGatewayError,
   createSdkStreamReader,
   type CallerAuthDecision,
@@ -281,6 +299,7 @@ export {
   type GatewayStreamView,
   type NonceReplayCache,
   type StreamReader,
+  type StreamRevocationSet,
 } from "./gateway/caller-auth-gateway.js";
 
 export {