@absol-labs/agent 0.1.0

package/src/zktls/reclaim.ts

@@ -0,0 +1,424 @@
+import {
+  getHttpProviderClaimParamsFromProof,
+  getProviderHashRequirementsFromSpec,
+  verifyProof,
+  type Proof as ReclaimProtocolProof,
+  type RequestSpec,
+  type VerifyProofResult,
+} from "@reclaimprotocol/js-sdk";
+import { z } from "zod";
+
+const addressSchema = z.string().regex(/^0x[0-9a-fA-F]{40}$/);
+const bytes32Schema = z.string().regex(/^0x[0-9a-fA-F]{64}$/);
+const httpMethodSchema = z.enum(["GET", "POST", "PUT"]);
+const responseMatchSchema = z.object({
+  type: z.enum(["regex", "contains"]),
+  value: z.string().min(1, "response match value is required"),
+  invert: z.boolean().optional(),
+  isOptional: z.boolean().optional(),
+});
+const responseRedactionSchema = z
+  .object({
+    regex: z.string().optional(),
+    jsonPath: z.string().optional(),
+    xPath: z.string().optional(),
+    hash: z.enum(["oprf", "oprf-raw", "oprf-mpc"]).optional(),
+  })
+  .refine(
+    (value) =>
+      value.regex !== undefined ||
+      value.jsonPath !== undefined ||
+      value.xPath !== undefined,
+    "response redaction needs regex, jsonPath, or xPath",
+  );
+
+export type HttpsResponseMatch = z.infer<typeof responseMatchSchema>;
+export type HttpsResponseRedaction = z.infer<typeof responseRedactionSchema>;
+export type ReclaimProof = ReclaimProtocolProof;
+
+export interface DeliveryProofBinding {
+  readonly owner: `0x${string}`;
+  readonly streamId?: `0x${string}`;
+  readonly operator?: `0x${string}`;
+  readonly serviceRef?: `0x${string}`;
+  readonly mandateId?: `0x${string}`;
+}
+
+export interface ProveConsumedHttpsResponseInput {
+  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";
+  readonly delivery: DeliveryProofBinding;
+}
+
+export interface VerifiedConsumedHttpsResponseProof {
+  readonly proof: ReclaimProof;
+  readonly request: {
+    readonly url: string;
+    readonly method: "GET" | "POST" | "PUT";
+    readonly body: string | null;
+    readonly responseMatches: readonly HttpsResponseMatch[];
+    readonly responseRedactions: readonly HttpsResponseRedaction[];
+  };
+  readonly verification: {
+    readonly context: Record<string, unknown>;
+    readonly extractedParameters: Record<string, string>;
+    readonly publicData: unknown;
+    readonly isTeeAttestationVerified: boolean;
+    readonly isAttestorTeeAttestationVerified: boolean;
+  };
+}
+
+export interface ReclaimProofServiceConfig {
+  readonly applicationId: string;
+  readonly applicationSecret: string;
+  readonly logs?: boolean;
+}
+
+export interface ParsedReclaimProofEnv extends ReclaimProofServiceConfig {}
+
+export interface ReclaimClientLike {
+  zkFetch(
+    url: string,
+    options?: {
+      method: string;
+      body?: string;
+      headers?: Record<string, string>;
+      geoLocation?: string;
+      context?: {
+        contextAddress: string;
+        contextMessage: string;
+      };
+      useTee?: boolean;
+      zkEngine?: "snarkjs" | "stwo";
+    },
+    secretOptions?: {
+      headers?: Record<string, string>;
+      responseMatches?: readonly HttpsResponseMatch[];
+      responseRedactions?: readonly HttpsResponseRedaction[];
+      cookieStr?: string;
+      paramValues?: Record<string, string>;
+    },
+  ): Promise<ReclaimProof | undefined>;
+}
+
+export type VerifyProofFn = (
+  proof: ReclaimProof,
+  config: Parameters<typeof verifyProof>[1],
+) => Promise<VerifyProofResult>;
+
+export interface ConsumerDeliveryProofService {
+  proveConsumedHttpsResponse(
+    input: ProveConsumedHttpsResponseInput,
+  ): Promise<VerifiedConsumedHttpsResponseProof>;
+}
+
+export class ResponseProofUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ResponseProofUnavailableError";
+  }
+}
+
+export class ResponseProofVerificationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ResponseProofVerificationError";
+  }
+}
+
+const reclaimProofInputSchema = z.object({
+  url: z.string().url(),
+  method: httpMethodSchema.optional(),
+  headers: z.record(z.string()).optional(),
+  body: z.string().optional(),
+  secretHeaders: z.record(z.string()).optional(),
+  responseMatches: z
+    .array(responseMatchSchema)
+    .min(1, "at least one response match is required"),
+  responseRedactions: z.array(responseRedactionSchema).optional(),
+  cookie: z.string().optional(),
+  secretParamValues: z.record(z.string()).optional(),
+  geoLocation: z.string().optional(),
+  useTee: z.boolean().optional(),
+  zkEngine: z.enum(["snarkjs", "stwo"]).optional(),
+  delivery: z.object({
+    owner: addressSchema,
+    streamId: bytes32Schema.optional(),
+    operator: addressSchema.optional(),
+    serviceRef: bytes32Schema.optional(),
+    mandateId: bytes32Schema.optional(),
+  }),
+});
+
+export class ReclaimConsumerProofService implements ConsumerDeliveryProofService {
+  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 proveConsumedHttpsResponse(
+    input: ProveConsumedHttpsResponseInput,
+  ): Promise<VerifiedConsumedHttpsResponseProof> {
+    const parsed = reclaimProofInputSchema.parse(input);
+    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: buildRequestContext(parsed.delivery),
+          ...(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 zkTLS response proof: ${asErrorMessage(error)}`,
+        );
+      });
+
+    if (proof === undefined) {
+      throw new ResponseProofUnavailableError(
+        "reclaim returned no zkTLS response 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(
+        `zkTLS response proof verification failed: ${asErrorMessage(
+          verification.error,
+        )}`,
+      );
+    }
+
+    const trusted = verification.data[0];
+    if (trusted === undefined) {
+      throw new ResponseProofVerificationError(
+        "zkTLS response 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,
+      },
+    };
+  }
+}
+
+export function parseReclaimProofEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): ParsedReclaimProofEnv | null {
+  const applicationId = env.RECLAIM_APP_ID;
+  const applicationSecret = env.RECLAIM_APP_SECRET;
+  if (applicationId === undefined && applicationSecret === undefined) {
+    return null;
+  }
+  if (
+    applicationId === undefined ||
+    applicationId.trim() === "" ||
+    applicationSecret === undefined ||
+    applicationSecret.trim() === ""
+  ) {
+    throw new Error("RECLAIM_APP_ID and RECLAIM_APP_SECRET must both be set");
+  }
+
+  return {
+    applicationId,
+    applicationSecret,
+    logs: env.METRIK_AGENT_RECLAIM_LOGS === "true",
+  };
+}
+
+export function createReclaimConsumerProofServiceFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): ReclaimConsumerProofService | null {
+  const parsed = parseReclaimProofEnv(env);
+  if (parsed === null) {
+    return null;
+  }
+  return new ReclaimConsumerProofService(parsed);
+}
+
+function defaultReclaimClientFactory(
+  applicationId: string,
+  applicationSecret: string,
+  logs: boolean,
+): ReclaimClientLike {
+  return new LazyReclaimClient(applicationId, applicationSecret, logs);
+}
+
+function buildRequestContext(
+  binding: z.infer<typeof reclaimProofInputSchema>["delivery"],
+): {
+  contextAddress: string;
+  contextMessage: string;
+} {
+  return {
+    contextAddress: binding.owner,
+    contextMessage: JSON.stringify({
+      kind: "metrik-l4-http-response/v1",
+      streamId: binding.streamId ?? null,
+      operator: binding.operator ?? null,
+      serviceRef: binding.serviceRef ?? null,
+      mandateId: binding.mandateId ?? null,
+    }),
+  };
+}
+
+function toRequestSpec(
+  input: z.infer<typeof reclaimProofInputSchema>,
+  method: "GET" | "POST" | "PUT",
+): RequestSpec {
+  return {
+    url: input.url,
+    urlType: "full",
+    method,
+    bodySniff: {
+      enabled: input.body !== undefined,
+      template: input.body ?? "",
+    },
+    responseMatches: input.responseMatches.map((match) => ({
+      value: match.value,
+      type: match.type,
+      invert: match.invert,
+      isOptional: match.isOptional,
+    })),
+    responseRedactions: (input.responseRedactions ?? []).map((redaction) => ({
+      regex: redaction.regex ?? "",
+      jsonPath: redaction.jsonPath ?? "",
+      xPath: redaction.xPath ?? "",
+      ...(redaction.hash === undefined ? {} : { hash: redaction.hash }),
+    })),
+    required: true,
+    multiple: false,
+  };
+}
+
+function asErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+class LazyReclaimClient implements ReclaimClientLike {
+  private clientPromise?: Promise<ReclaimClientLike>;
+
+  constructor(
+    private readonly applicationId: string,
+    private readonly applicationSecret: string,
+    private readonly logs: boolean,
+  ) {}
+
+  async zkFetch(
+    url: string,
+    options?: Parameters<ReclaimClientLike["zkFetch"]>[1],
+    secretOptions?: Parameters<ReclaimClientLike["zkFetch"]>[2],
+  ): Promise<ReclaimProof | undefined> {
+    const client = await this.getClient();
+    return await client.zkFetch(url, options, secretOptions);
+  }
+
+  private async getClient(): Promise<ReclaimClientLike> {
+    if (this.clientPromise === undefined) {
+      this.clientPromise = import("@reclaimprotocol/zk-fetch").then(
+        (module) => {
+          const client = new module.ReclaimClient(
+            this.applicationId,
+            this.applicationSecret,
+            this.logs,
+          );
+          return client as ReclaimClientLike;
+        },
+      );
+    }
+    return await this.clientPromise;
+  }
+}