@absol-labs/agent 0.3.2 → 0.4.0

package/src/zktls/t2-delivery-proof.ts

@@ -0,0 +1,559 @@
+import {
+  canonicalJson,
+  deliveryReceiptSchema,
+  signDeliveryReceipt,
+  type DeliveryReceipt,
+  type DeliveryReceiptDomainInput,
+} from "@absol-labs/shared";
+import {
+  getHttpProviderClaimParamsFromProof,
+  getProviderHashRequirementsFromSpec,
+  verifyProof,
+} from "@reclaimprotocol/js-sdk";
+import {
+  keccak256,
+  stringToBytes,
+  type Address,
+  type Hex,
+  type LocalAccount,
+} from "viem";
+import { z } from "zod";
+
+import {
+  asErrorMessage,
+  buildDeliveryContextEnvelopeV2,
+  defaultReclaimClientFactory,
+  deliveryContextEnvelopeV2Schema,
+  parseReclaimProofEnv,
+  ResponseProofUnavailableError,
+  ResponseProofVerificationError,
+  toRequestSpec,
+  type DeliveryContextEnvelopeV2,
+  type HttpsResponseMatch,
+  type HttpsResponseRedaction,
+  type ReclaimClientLike,
+  type ReclaimProof,
+  type ReclaimProofServiceConfig,
+  type VerifiedConsumedHttpsResponseProof,
+  type VerifyProofFn,
+} from "./reclaim.js";
+
+/**
+ * T2 consumer zkTLS delivery envelope (issue #24, metrik-protocol#67 DECISION).
+ *
+ * This is the BUYER-side counterpart to `streamproof-oracle`'s T2 accrue-on-proof
+ * ingest (`src/delivery/proof-ingest.ts`). Given the stream identity, an
+ * oracle-issued nonce (`GET /delivery/nonce`), and the paid-route request spec,
+ * it: (1) proves the paid route via a pluggable zkTLS attestor with the nonce
+ * bound into the request and the Metrik v2 envelope bound into
+ * `claimData.context`; (2) signs a `DeliveryReceipt` (`@absol-labs/shared`)
+ * committing to that proof; and (3) returns the exact `POST /delivery/proof`
+ * request body the oracle's `deliveryProofRequestSchema` expects.
+ *
+ * The attestor is pluggable (`DeliveryProofAttestor`) specifically so this can
+ * be tested WITHOUT a live Reclaim App Secret (agent#22 is the human-intervention
+ * issue for that credential) - the default production attestor
+ * (`createReclaimT2AttestorFromEnv`) still requires it.
+ */
+
+const bytes32Hex = /^0x[0-9a-fA-F]{64}$/;
+const evmAddress = /^0x[0-9a-fA-F]{40}$/;
+const hexSignature = /^0x[0-9a-fA-F]+$/;
+
+/**
+ * WHERE the oracle-issued nonce is injected into the outbound paid-route
+ * request. T2 disallows header injection (`proof-ingest.ts` rejects it) since
+ * a header is not part of what the Reclaim proof's `claimData.parameters`
+ * commits to - the oracle can only verify a nonce carried in the URL query or
+ * the request body.
+ */
+export type T2NonceInjection =
+  | { readonly in: "query"; readonly name: string }
+  | { readonly in: "body"; readonly placeholder: string };
+
+export interface PaidRouteRequestSpec {
+  readonly url: string;
+  readonly method?: "GET" | "POST" | "PUT";
+  readonly headers?: Record<string, string>;
+  /** For `nonceInjection.in === "body"`, MUST contain `nonceInjection.placeholder`. */
+  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";
+  readonly nonceInjection: T2NonceInjection;
+}
+
+export class PaidRouteNonceInjectionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PaidRouteNonceInjectionError";
+  }
+}
+
+/** Injects the oracle-issued nonce into the paid-route request (query or body only). */
+function injectNonce(
+  spec: PaidRouteRequestSpec,
+  nonce: `0x${string}`,
+): { readonly url: string; readonly body: string | undefined } {
+  if (spec.nonceInjection.in === "query") {
+    let url: URL;
+    try {
+      url = new URL(spec.url);
+    } catch (cause) {
+      throw new PaidRouteNonceInjectionError(
+        `paid route url is not a valid absolute URL: ${asErrorMessage(cause)}`,
+      );
+    }
+    url.searchParams.set(spec.nonceInjection.name, nonce);
+    return { url: url.toString(), body: spec.body };
+  }
+
+  const placeholder = spec.nonceInjection.placeholder;
+  const body = spec.body ?? "";
+  if (!body.includes(placeholder)) {
+    throw new PaidRouteNonceInjectionError(
+      `paid route body does not contain the nonce placeholder "${placeholder}"`,
+    );
+  }
+  return { url: spec.url, body: body.split(placeholder).join(nonce) };
+}
+
+/**
+ * Input to a `DeliveryProofAttestor`. `context` becomes `claimData.context`
+ * VERBATIM (see `ReclaimClientLike.zkFetch`'s doc in `reclaim.ts`) - it is the
+ * flat T2 envelope, never wrapped.
+ */
+export interface ProveDeliveryResponseInput {
+  readonly url: string;
+  readonly method?: "GET" | "POST" | "PUT" | undefined;
+  readonly headers?: Record<string, string> | undefined;
+  readonly body?: string | undefined;
+  readonly secretHeaders?: Record<string, string> | undefined;
+  readonly responseMatches: readonly HttpsResponseMatch[];
+  readonly responseRedactions?: readonly HttpsResponseRedaction[] | undefined;
+  readonly cookie?: string | undefined;
+  readonly secretParamValues?: Record<string, string> | undefined;
+  readonly geoLocation?: string | undefined;
+  readonly useTee?: boolean | undefined;
+  readonly zkEngine?: "snarkjs" | "stwo" | undefined;
+  readonly context: DeliveryContextEnvelopeV2;
+}
+
+/**
+ * Pluggable zkTLS attestor abstraction for the T2 delivery proof. The default
+ * (`createReclaimT2AttestorFromEnv`) drives the real Reclaim zkFetch + verify
+ * pipeline; tests inject a mock/real-crypto-fixture implementation instead so
+ * this module is testable without a live `RECLAIM_APP_SECRET` (agent#22).
+ */
+export interface DeliveryProofAttestor {
+  proveDeliveryResponse(
+    input: ProveDeliveryResponseInput,
+  ): Promise<VerifiedConsumedHttpsResponseProof>;
+}
+
+const reclaimT2UrlSchema = z.string().url();
+
+/**
+ * Production `DeliveryProofAttestor`: drives the real Reclaim zkFetch + proof
+ * verification pipeline (mirrors `ReclaimConsumerProofService` in `reclaim.ts`,
+ * but binds the FLAT T2 v2 envelope directly as `context` instead of the v1
+ * `{contextAddress, contextMessage}` wrapper).
+ */
+export class ReclaimDeliveryProofAttestor implements DeliveryProofAttestor {
+  private readonly client: ReclaimClientLike;
+  private readonly config: ReclaimProofServiceConfig;
+  private readonly verifyProofImpl: VerifyProofFn;
+
+  constructor(
+    config: ReclaimProofServiceConfig,
+    options: {
+      readonly createClient?: (
+        applicationId: string,
+        applicationSecret: string,
+        logs: boolean,
+      ) => ReclaimClientLike;
+      readonly verifyProof?: VerifyProofFn;
+    } = {},
+  ) {
+    this.config = {
+      ...config,
+      logs: config.logs ?? false,
+    };
+    this.client = (options.createClient ?? defaultReclaimClientFactory)(
+      this.config.applicationId,
+      this.config.applicationSecret,
+      this.config.logs ?? false,
+    );
+    this.verifyProofImpl = options.verifyProof ?? verifyProof;
+  }
+
+  async proveDeliveryResponse(
+    input: ProveDeliveryResponseInput,
+  ): Promise<VerifiedConsumedHttpsResponseProof> {
+    reclaimT2UrlSchema.parse(input.url);
+    if (input.responseMatches.length === 0) {
+      throw new Error("at least one response match is required");
+    }
+    const context = deliveryContextEnvelopeV2Schema.parse(input.context);
+    const parsed = { ...input, context };
+    const method = parsed.method ?? "GET";
+
+    const proof = await this.client
+      .zkFetch(
+        parsed.url,
+        {
+          method,
+          ...(parsed.body === undefined ? {} : { body: parsed.body }),
+          ...(parsed.headers === undefined ? {} : { headers: parsed.headers }),
+          ...(parsed.geoLocation === undefined
+            ? {}
+            : { geoLocation: parsed.geoLocation }),
+          context: parsed.context,
+          ...(parsed.useTee === undefined ? {} : { useTee: parsed.useTee }),
+          ...(parsed.zkEngine === undefined
+            ? {}
+            : { zkEngine: parsed.zkEngine }),
+        },
+        {
+          ...(parsed.secretHeaders === undefined
+            ? {}
+            : { headers: parsed.secretHeaders }),
+          responseMatches: parsed.responseMatches,
+          ...(parsed.responseRedactions === undefined
+            ? {}
+            : { responseRedactions: parsed.responseRedactions }),
+          ...(parsed.cookie === undefined ? {} : { cookieStr: parsed.cookie }),
+          ...(parsed.secretParamValues === undefined
+            ? {}
+            : { paramValues: parsed.secretParamValues }),
+        },
+      )
+      .catch((error) => {
+        throw new ResponseProofUnavailableError(
+          `failed to generate T2 zkTLS delivery proof: ${asErrorMessage(error)}`,
+        );
+      });
+
+    if (proof === undefined) {
+      throw new ResponseProofUnavailableError(
+        "reclaim returned no zkTLS delivery proof",
+      );
+    }
+
+    const verification = await this.verifyProofImpl(proof, {
+      ...getProviderHashRequirementsFromSpec({
+        requests: [toRequestSpec(parsed, method)],
+      }),
+      ...(parsed.useTee === true
+        ? { teeAttestation: { appSecret: this.config.applicationSecret } }
+        : {}),
+    });
+    if (!verification.isVerified) {
+      throw new ResponseProofVerificationError(
+        `T2 zkTLS delivery proof verification failed: ${asErrorMessage(verification.error)}`,
+      );
+    }
+
+    const trusted = verification.data[0];
+    if (trusted === undefined) {
+      throw new ResponseProofVerificationError(
+        "T2 zkTLS delivery proof verification returned no trusted data",
+      );
+    }
+
+    const request = getHttpProviderClaimParamsFromProof(proof);
+    return {
+      proof,
+      request: {
+        url: request.url,
+        method: request.method as "GET" | "POST" | "PUT",
+        body: request.body === "" ? null : (request.body ?? null),
+        responseMatches: request.responseMatches.map((match) => ({
+          value: match.value,
+          type: match.type,
+          invert: match.invert,
+          isOptional: match.isOptional,
+        })),
+        responseRedactions: request.responseRedactions.map((redaction) => ({
+          regex: redaction.regex,
+          jsonPath: redaction.jsonPath,
+          xPath: redaction.xPath,
+          hash: redaction.hash,
+        })),
+      },
+      verification: {
+        context: trusted.context,
+        extractedParameters: trusted.extractedParameters,
+        publicData: verification.publicData[0] ?? null,
+        isTeeAttestationVerified:
+          verification.isTeeAttestationVerified ?? false,
+        isAttestorTeeAttestationVerified:
+          verification.isAttestorTeeAttestationVerified ?? false,
+      },
+    };
+  }
+}
+
+/** `null` when `RECLAIM_APP_ID`/`RECLAIM_APP_SECRET` are not configured (see agent#22). */
+export function createReclaimT2AttestorFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): ReclaimDeliveryProofAttestor | null {
+  const parsed = parseReclaimProofEnv(env);
+  if (parsed === null) return null;
+  return new ReclaimDeliveryProofAttestor(parsed);
+}
+
+/** Wire (JSON-safe) form of `DeliveryReceipt` - bigints as decimal strings, hex as `0x`. */
+export interface WireDeliveryReceipt {
+  readonly streamId: string;
+  readonly serviceRef: `0x${string}`;
+  readonly operator: `0x${string}`;
+  readonly intervalIndex: string;
+  readonly nonce: `0x${string}`;
+  readonly reclaimProofId: `0x${string}`;
+  readonly reclaimOwner: `0x${string}`;
+  readonly reclaimTimestamp: string;
+  readonly reclaimEpoch: string;
+  readonly canonicalRequestHash: `0x${string}`;
+  readonly canonicalBodyHash: `0x${string}`;
+}
+
+const wireDeliveryReceiptSchema = z
+  .object({
+    streamId: z.union([
+      z.string().regex(bytes32Hex),
+      z.string().regex(/^\d+$/),
+    ]),
+    serviceRef: z
+      .string()
+      .regex(bytes32Hex, "must be a 32-byte hex serviceRef"),
+    operator: z.string().regex(evmAddress, "must be an EVM address"),
+    intervalIndex: z
+      .string()
+      .regex(/^\d+$/, "must be a non-negative integer string"),
+    nonce: z.string().regex(bytes32Hex, "must be a 32-byte hex nonce"),
+    reclaimProofId: z
+      .string()
+      .regex(bytes32Hex, "must be a 32-byte hex identifier"),
+    reclaimOwner: z.string().regex(evmAddress, "must be an EVM address"),
+    reclaimTimestamp: z
+      .string()
+      .regex(/^\d+$/, "must be a non-negative integer string"),
+    reclaimEpoch: z
+      .string()
+      .regex(/^\d+$/, "must be a non-negative integer string"),
+    canonicalRequestHash: z
+      .string()
+      .regex(bytes32Hex, "must be a 32-byte hex hash"),
+    canonicalBodyHash: z
+      .string()
+      .regex(bytes32Hex, "must be a 32-byte hex hash"),
+  })
+  .strict();
+
+const reclaimProviderClaimDataSchema = z
+  .object({
+    provider: z.string().min(1),
+    parameters: z.string().min(1),
+    context: z.string(),
+    owner: z.string().regex(evmAddress, "must be an EVM address"),
+    timestampS: z.number().int().nonnegative(),
+    epoch: z.number().int().nonnegative(),
+    identifier: z
+      .string()
+      .regex(bytes32Hex, "must be a 32-byte hex identifier"),
+  })
+  .strict();
+
+const reclaimProofWireSchema = z
+  .object({
+    identifier: z
+      .string()
+      .regex(bytes32Hex, "must be a 32-byte hex identifier"),
+    claimData: reclaimProviderClaimDataSchema,
+    signatures: z.array(z.string().regex(hexSignature)).min(1),
+  })
+  .strict();
+
+/**
+ * `POST /delivery/proof` request body - mirrors the oracle's own
+ * `deliveryProofRequestSchema` (`streamproof-oracle/src/delivery/dto.ts`)
+ * field-for-field. Kept as a local copy (same convention the oracle itself
+ * uses for `@absol-labs/shared` shapes) rather than an import, since the two
+ * repos do not share a package for this DTO.
+ */
+export const deliveryProofRequestBodySchema = z
+  .object({
+    receipt: wireDeliveryReceiptSchema,
+    signature: z.string().regex(hexSignature, "must be a hex signature"),
+    proof: reclaimProofWireSchema,
+  })
+  .strict();
+
+export type DeliveryProofRequestBody = z.infer<
+  typeof deliveryProofRequestBodySchema
+>;
+
+/** Converts a bigint-typed `DeliveryReceipt` to the oracle's decimal-string wire shape. */
+export function toWireDeliveryReceipt(
+  receipt: DeliveryReceipt,
+): WireDeliveryReceipt {
+  return {
+    streamId: receipt.streamId.toString(),
+    serviceRef: receipt.serviceRef as `0x${string}`,
+    operator: receipt.operator as `0x${string}`,
+    intervalIndex: receipt.intervalIndex.toString(),
+    nonce: receipt.nonce as `0x${string}`,
+    reclaimProofId: receipt.reclaimProofId as `0x${string}`,
+    reclaimOwner: receipt.reclaimOwner as `0x${string}`,
+    reclaimTimestamp: receipt.reclaimTimestamp.toString(),
+    reclaimEpoch: receipt.reclaimEpoch.toString(),
+    canonicalRequestHash: receipt.canonicalRequestHash as `0x${string}`,
+    canonicalBodyHash: receipt.canonicalBodyHash as `0x${string}`,
+  };
+}
+
+/** Deterministic keccak256 over the canonical (sorted-key) JSON of `value`. */
+function hashCanonical(value: unknown): `0x${string}` {
+  return keccak256(stringToBytes(canonicalJson(value)));
+}
+
+export interface BuildT2DeliveryProofInput {
+  /** 32-byte hex, byte-identical to the on-chain `streamId`. */
+  readonly streamId: `0x${string}`;
+  readonly operator: `0x${string}`;
+  readonly serviceRef: `0x${string}`;
+  readonly mandateId?: string;
+  readonly intervalIndex: bigint;
+  /** From `GET /delivery/nonce`. */
+  readonly nonce: `0x${string}`;
+  /** Unix seconds. Defaults to `Math.floor(Date.now() / 1000)`. */
+  readonly issuedAt?: number;
+  /** Signs the `DeliveryReceipt`. Never the Reclaim proof's `claimData.owner`. */
+  readonly buyer: LocalAccount;
+  /** `{chainId, verifyingContract}` - the StreamEscrowV2 the stream settles on. */
+  readonly domain: DeliveryReceiptDomainInput;
+  readonly request: PaidRouteRequestSpec;
+  /** Defaults to `createReclaimT2AttestorFromEnv()`. */
+  readonly attestor?: DeliveryProofAttestor;
+}
+
+export interface BuildT2DeliveryProofResult {
+  /** The exact `POST /delivery/proof` request body. */
+  readonly body: DeliveryProofRequestBody;
+  /** Natural (bigint-typed) receipt, for callers that want it directly. */
+  readonly receipt: DeliveryReceipt;
+  readonly signature: Hex;
+  readonly proof: ReclaimProof;
+  readonly envelope: DeliveryContextEnvelopeV2;
+}
+
+export class NoDeliveryAttestorConfiguredError extends Error {
+  constructor() {
+    super(
+      "no zkTLS delivery attestor configured: set RECLAIM_APP_ID/RECLAIM_APP_SECRET " +
+        "(see agent#22) or pass an explicit `attestor`",
+    );
+    this.name = "NoDeliveryAttestorConfiguredError";
+  }
+}
+
+/**
+ * Produces a complete T2 delivery proof envelope: proves the paid route with
+ * the oracle-issued nonce bound into both the request and the Reclaim
+ * `claimData.context`, signs a `DeliveryReceipt` committing to that proof, and
+ * returns the exact body for `POST /delivery/proof`.
+ */
+export async function buildT2DeliveryProofSubmission(
+  input: BuildT2DeliveryProofInput,
+): Promise<BuildT2DeliveryProofResult> {
+  const issuedAt = input.issuedAt ?? Math.floor(Date.now() / 1000);
+  if (input.intervalIndex > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new RangeError("intervalIndex exceeds Number.MAX_SAFE_INTEGER");
+  }
+
+  const envelope = buildDeliveryContextEnvelopeV2({
+    streamId: input.streamId,
+    operator: input.operator,
+    serviceRef: input.serviceRef,
+    ...(input.mandateId === undefined ? {} : { mandateId: input.mandateId }),
+    nonce: input.nonce,
+    intervalIndex: Number(input.intervalIndex),
+    issuedAt,
+  });
+
+  const injected = injectNonce(input.request, input.nonce);
+
+  const attestor = input.attestor ?? createReclaimT2AttestorFromEnv();
+  if (attestor === null) {
+    throw new NoDeliveryAttestorConfiguredError();
+  }
+
+  const proved = await attestor.proveDeliveryResponse({
+    url: injected.url,
+    method: input.request.method,
+    body: injected.body,
+    headers: input.request.headers,
+    secretHeaders: input.request.secretHeaders,
+    responseMatches: input.request.responseMatches,
+    responseRedactions: input.request.responseRedactions,
+    cookie: input.request.cookie,
+    secretParamValues: input.request.secretParamValues,
+    geoLocation: input.request.geoLocation,
+    useTee: input.request.useTee,
+    zkEngine: input.request.zkEngine,
+    context: envelope,
+  });
+
+  const { proof } = proved;
+
+  // Deterministically bind BOTH the exact proven request (method/url/body, post
+  // nonce-injection) and the exact PROVEN (redacted/extracted) response content
+  // into the receipt, so the receipt is verifiable dispute evidence even though
+  // the oracle itself does not re-derive these hashes today.
+  const canonicalRequestHash = hashCanonical({
+    method: proved.request.method,
+    url: proved.request.url,
+    body: proved.request.body,
+  });
+  const canonicalBodyHash = hashCanonical({
+    extractedParameters: proved.verification.extractedParameters,
+  });
+
+  const receipt = deliveryReceiptSchema.parse({
+    streamId: BigInt(input.streamId),
+    serviceRef: input.serviceRef,
+    operator: input.operator,
+    intervalIndex: input.intervalIndex,
+    nonce: input.nonce,
+    reclaimProofId: proof.identifier as Hex,
+    reclaimOwner: proof.claimData.owner as Address,
+    reclaimTimestamp: BigInt(proof.claimData.timestampS),
+    reclaimEpoch: BigInt(proof.claimData.epoch),
+    canonicalRequestHash,
+    canonicalBodyHash,
+  } satisfies DeliveryReceipt);
+
+  const signature = await signDeliveryReceipt(
+    receipt,
+    input.domain,
+    input.buyer,
+  );
+
+  const body = deliveryProofRequestBodySchema.parse({
+    receipt: toWireDeliveryReceipt(receipt),
+    signature,
+    proof: {
+      identifier: proof.identifier,
+      claimData: proof.claimData,
+      signatures: proof.signatures,
+    },
+  } satisfies z.input<typeof deliveryProofRequestBodySchema>);
+
+  return { body, receipt, signature, proof, envelope };
+}