@absol-labs/agent 0.1.0

package/src/x402/facilitator.ts

@@ -0,0 +1,336 @@
+import type { StreamProofClientConfig } from "@absol-labs/sdk";
+import { z } from "zod";
+
+import {
+  signedSpendMandateSchema,
+  type SignedSpendMandate,
+} from "../mandates/mandate.js";
+import {
+  VerifiedStreamAgentClient,
+  type VerifiedStreamAgentOpener,
+} from "../sdk/client.js";
+import {
+  type ConsumerDeliveryProofService,
+  type HttpsResponseMatch,
+  type HttpsResponseRedaction,
+  type VerifiedConsumedHttpsResponseProof,
+} from "../zktls/reclaim.js";
+
+export const X402_SCHEME = "streamproof-verified-stream" as const;
+
+const addressSchema = z.string().regex(/^0x[0-9a-fA-F]{40}$/);
+const bytes32Schema = z.string().regex(/^0x[0-9a-fA-F]{64}$/);
+
+export const verifiedStreamRequirementsSchema = z.object({
+  operator: addressSchema,
+  serviceRef: bytes32Schema,
+  chainId: z.number().int().positive(),
+  escrow: addressSchema,
+  ratePerSecondUsdc: z.bigint().positive(),
+  maxDurationSeconds: z.number().int().positive(),
+  maxBudgetUsdc: z.bigint().positive(),
+});
+
+export interface VerifiedStreamRequirements extends z.infer<
+  typeof verifiedStreamRequirementsSchema
+> {}
+
+export const x402StreamChallengeSchema = z.object({
+  scheme: z.literal(X402_SCHEME),
+  requirements: verifiedStreamRequirementsSchema,
+});
+
+export interface X402StreamChallenge extends z.infer<
+  typeof x402StreamChallengeSchema
+> {}
+
+export const x402OpenPayloadSchema = z.object({
+  challenge: x402StreamChallengeSchema,
+  signedMandate: signedSpendMandateSchema,
+});
+
+export interface X402OpenPayload extends z.infer<
+  typeof x402OpenPayloadSchema
+> {}
+
+export interface X402Facilitator {
+  /** Build the 402 challenge a server returns to prompt a verified stream. */
+  challenge(req: VerifiedStreamRequirements): X402StreamChallenge;
+  /** Verify + open the stream from an agent's signed payment payload. */
+  open(payloadHeader: string): Promise<{ streamId: `0x${string}` }>;
+  /** Prove the HTTPS response consumed after opening a verified stream. */
+  proveConsumedHttpsResponse(
+    input: X402ConsumedHttpsResponseProofInput,
+  ): Promise<VerifiedConsumedHttpsResponseProof>;
+}
+
+export interface X402ConsumedHttpsResponseProofInput {
+  readonly signedMandate: SignedSpendMandate;
+  readonly streamId?: `0x${string}`;
+  readonly operator?: `0x${string}`;
+  readonly serviceRef?: `0x${string}`;
+  readonly url: string;
+  readonly method?: "GET" | "POST" | "PUT";
+  readonly headers?: Record<string, string>;
+  readonly body?: string;
+  readonly secretHeaders?: Record<string, string>;
+  readonly responseMatches: readonly HttpsResponseMatch[];
+  readonly responseRedactions?: readonly HttpsResponseRedaction[];
+  readonly cookie?: string;
+  readonly secretParamValues?: Record<string, string>;
+  readonly geoLocation?: string;
+  readonly useTee?: boolean;
+  readonly zkEngine?: "snarkjs" | "stwo";
+}
+
+export interface VerifiedStreamFacilitatorOptions {
+  readonly sdkConfig: StreamProofClientConfig;
+  readonly createAgentClient?: (
+    config: StreamProofClientConfig,
+  ) => VerifiedStreamAgentOpener;
+  readonly deliveryProofs?: ConsumerDeliveryProofService;
+  readonly nowSeconds?: () => number;
+  readonly resolveSpentSoFarUsdc?: (
+    signedMandate: SignedSpendMandate,
+  ) => bigint | Promise<bigint>;
+  readonly resolveRevokedMandateIds?: (
+    signedMandate: SignedSpendMandate,
+  ) => Iterable<`0x${string}`> | Promise<Iterable<`0x${string}`>>;
+}
+
+const warnedFacilitatorGaps = new Set<string>();
+
+/** Emits a stderr warning at most once per process for a given key. */
+function warnFacilitatorOnce(key: string, message: string): void {
+  if (warnedFacilitatorGaps.has(key)) {
+    return;
+  }
+  warnedFacilitatorGaps.add(key);
+  console.error(message);
+}
+
+export class X402PayloadError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "X402PayloadError";
+  }
+}
+
+export class SettlementTargetMismatchError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SettlementTargetMismatchError";
+  }
+}
+
+export class DeliveryProofUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "DeliveryProofUnavailableError";
+  }
+}
+
+export class VerifiedStreamX402Facilitator implements X402Facilitator {
+  private readonly agentClient: VerifiedStreamAgentOpener;
+  private readonly deliveryProofs: ConsumerDeliveryProofService | undefined;
+  private readonly sdkConfig: StreamProofClientConfig;
+  private readonly nowSeconds: () => number;
+  private readonly resolveSpentSoFarUsdc: (
+    signedMandate: SignedSpendMandate,
+  ) => bigint | Promise<bigint>;
+  private readonly resolveRevokedMandateIds: (
+    signedMandate: SignedSpendMandate,
+  ) => Iterable<`0x${string}`> | Promise<Iterable<`0x${string}`>>;
+
+  constructor(options: VerifiedStreamFacilitatorOptions) {
+    this.sdkConfig = options.sdkConfig;
+    this.agentClient = (options.createAgentClient ?? defaultAgentClientFactory)(
+      options.sdkConfig,
+    );
+    this.deliveryProofs = options.deliveryProofs;
+    this.nowSeconds =
+      options.nowSeconds ?? (() => Math.floor(Date.now() / 1000));
+    this.resolveSpentSoFarUsdc = options.resolveSpentSoFarUsdc ?? (() => 0n);
+    this.resolveRevokedMandateIds =
+      options.resolveRevokedMandateIds ?? (() => []);
+
+    // Fail-loud on the two mandate controls that require external state. This
+    // facilitator is stateless (no stream registry), so it cannot enforce the
+    // cumulative-cap or revocation without a wired resolver. Warn once so a
+    // deployment never silently ships with maxTotalUsdc / revocation disabled.
+    if (options.resolveSpentSoFarUsdc === undefined) {
+      warnFacilitatorOnce(
+        "x402-spent",
+        "[metrik] x402 facilitator: no resolveSpentSoFarUsdc wired — the mandate cumulative cap (maxTotalUsdc) is NOT enforced across streams (per-stream/rate/duration/operator/expiry still are).",
+      );
+    }
+    if (options.resolveRevokedMandateIds === undefined) {
+      warnFacilitatorOnce(
+        "x402-revocation",
+        "[metrik] x402 facilitator: no resolveRevokedMandateIds wired — revoked mandates will NOT be rejected until you wire a revocation store.",
+      );
+    }
+  }
+
+  challenge(req: VerifiedStreamRequirements): X402StreamChallenge {
+    const requirements = verifiedStreamRequirementsSchema.parse(req);
+    assertSettlementTarget(requirements, this.sdkConfig);
+    return { scheme: X402_SCHEME, requirements };
+  }
+
+  async open(payloadHeader: string): Promise<{ streamId: `0x${string}` }> {
+    const payload = parseX402PayloadHeader(payloadHeader);
+    assertSettlementTarget(payload.challenge.requirements, this.sdkConfig);
+
+    const spentSoFarUsdc = await this.resolveSpentSoFarUsdc(
+      payload.signedMandate,
+    );
+    const revokedMandateIds = await this.resolveRevokedMandateIds(
+      payload.signedMandate,
+    );
+
+    const result = await this.agentClient.openVerifiedStream({
+      operator: payload.challenge.requirements.operator as `0x${string}`,
+      serviceRef: payload.challenge.requirements.serviceRef as `0x${string}`,
+      budgetUsdc: payload.challenge.requirements.maxBudgetUsdc,
+      ratePerSecondUsdc: payload.challenge.requirements.ratePerSecondUsdc,
+      maxDurationSeconds: payload.challenge.requirements.maxDurationSeconds,
+      signedMandate: payload.signedMandate,
+      spentSoFarUsdc,
+      nowSeconds: this.nowSeconds(),
+      revokedMandateIds,
+    });
+
+    return { streamId: result.streamId };
+  }
+
+  async proveConsumedHttpsResponse(
+    input: X402ConsumedHttpsResponseProofInput,
+  ): Promise<VerifiedConsumedHttpsResponseProof> {
+    if (this.deliveryProofs === undefined) {
+      throw new DeliveryProofUnavailableError(
+        "zkTLS delivery proofs are not configured on this x402 facilitator",
+      );
+    }
+
+    return await this.deliveryProofs.proveConsumedHttpsResponse({
+      url: input.url,
+      ...(input.method === undefined ? {} : { method: input.method }),
+      ...(input.headers === undefined ? {} : { headers: input.headers }),
+      ...(input.body === undefined ? {} : { body: input.body }),
+      ...(input.secretHeaders === undefined
+        ? {}
+        : { secretHeaders: input.secretHeaders }),
+      responseMatches: input.responseMatches,
+      ...(input.responseRedactions === undefined
+        ? {}
+        : { responseRedactions: input.responseRedactions }),
+      ...(input.cookie === undefined ? {} : { cookie: input.cookie }),
+      ...(input.secretParamValues === undefined
+        ? {}
+        : { secretParamValues: input.secretParamValues }),
+      ...(input.geoLocation === undefined
+        ? {}
+        : { geoLocation: input.geoLocation }),
+      ...(input.useTee === undefined ? {} : { useTee: input.useTee }),
+      ...(input.zkEngine === undefined ? {} : { zkEngine: input.zkEngine }),
+      delivery: {
+        owner: input.signedMandate.owner as `0x${string}`,
+        mandateId: input.signedMandate.mandateId as `0x${string}`,
+        ...(input.streamId === undefined ? {} : { streamId: input.streamId }),
+        ...(input.operator === undefined ? {} : { operator: input.operator }),
+        ...(input.serviceRef === undefined
+          ? {}
+          : { serviceRef: input.serviceRef }),
+      },
+    });
+  }
+}
+
+export function encodeX402PayloadHeader(payload: X402OpenPayload): string {
+  const parsed = x402OpenPayloadSchema.parse(payload);
+  const token = Buffer.from(stringifyX402Payload(parsed)).toString("base64url");
+  return `${X402_SCHEME} ${token}`;
+}
+
+export function parseX402ChallengeJson(value: unknown): X402StreamChallenge {
+  const parsed = x402StreamChallengeSchema.safeParse(reviveBigInts(value));
+  if (!parsed.success) {
+    throw new X402PayloadError(
+      parsed.error.issues.map((issue) => issue.message).join("; "),
+    );
+  }
+  return parsed.data;
+}
+
+export function parseX402PayloadHeader(payloadHeader: string): X402OpenPayload {
+  const [scheme, token] = payloadHeader.split(" ", 2);
+  if (scheme !== X402_SCHEME || token === undefined || token.trim() === "") {
+    throw new X402PayloadError("invalid x402 verified-stream payload header");
+  }
+
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(Buffer.from(token, "base64url").toString("utf8"));
+  } catch (error) {
+    throw new X402PayloadError(
+      `invalid x402 verified-stream payload encoding: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+
+  const parsed = x402OpenPayloadSchema.safeParse(reviveBigInts(decoded));
+  if (!parsed.success) {
+    throw new X402PayloadError(
+      parsed.error.issues.map((issue) => issue.message).join("; "),
+    );
+  }
+  return parsed.data;
+}
+
+function defaultAgentClientFactory(
+  config: StreamProofClientConfig,
+): VerifiedStreamAgentOpener {
+  return new VerifiedStreamAgentClient(config);
+}
+
+function assertSettlementTarget(
+  requirements: VerifiedStreamRequirements,
+  sdkConfig: StreamProofClientConfig,
+): void {
+  if (requirements.chainId !== sdkConfig.chain.id) {
+    throw new SettlementTargetMismatchError(
+      `challenge chainId ${requirements.chainId} does not match configured chain ${sdkConfig.chain.id}`,
+    );
+  }
+  if (requirements.escrow.toLowerCase() !== sdkConfig.escrow.toLowerCase()) {
+    throw new SettlementTargetMismatchError(
+      `challenge escrow ${requirements.escrow} does not match configured escrow ${sdkConfig.escrow}`,
+    );
+  }
+}
+
+function stringifyX402Payload(payload: X402OpenPayload): string {
+  return JSON.stringify(payload, (_key, value) =>
+    typeof value === "bigint" ? `${value.toString()}n` : value,
+  );
+}
+
+function reviveBigInts(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((entry) => reviveBigInts(entry));
+  }
+
+  if (typeof value === "string" && /^\d+n$/.test(value)) {
+    return BigInt(value.slice(0, -1));
+  }
+
+  if (typeof value === "object" && value !== null) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, reviveBigInts(entry)]),
+    );
+  }
+
+  return value;
+}