@absol-labs/agent 0.3.2 → 0.4.0

package/dist/zktls/t2-delivery-proof.js

@@ -0,0 +1,336 @@
+import { canonicalJson, deliveryReceiptSchema, signDeliveryReceipt, } from "@absol-labs/shared";
+import { getHttpProviderClaimParamsFromProof, getProviderHashRequirementsFromSpec, verifyProof, } from "@reclaimprotocol/js-sdk";
+import { keccak256, stringToBytes, } from "viem";
+import { z } from "zod";
+import { asErrorMessage, buildDeliveryContextEnvelopeV2, defaultReclaimClientFactory, deliveryContextEnvelopeV2Schema, parseReclaimProofEnv, ResponseProofUnavailableError, ResponseProofVerificationError, toRequestSpec, } 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]+$/;
+export class PaidRouteNonceInjectionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PaidRouteNonceInjectionError";
+    }
+}
+/** Injects the oracle-issued nonce into the paid-route request (query or body only). */
+function injectNonce(spec, nonce) {
+    if (spec.nonceInjection.in === "query") {
+        let 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) };
+}
+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 {
+    client;
+    config;
+    verifyProofImpl;
+    constructor(config, options = {}) {
+        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) {
+        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,
+                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 = process.env) {
+    const parsed = parseReclaimProofEnv(env);
+    if (parsed === null)
+        return null;
+    return new ReclaimDeliveryProofAttestor(parsed);
+}
+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();
+/** Converts a bigint-typed `DeliveryReceipt` to the oracle's decimal-string wire shape. */
+export function toWireDeliveryReceipt(receipt) {
+    return {
+        streamId: receipt.streamId.toString(),
+        serviceRef: receipt.serviceRef,
+        operator: receipt.operator,
+        intervalIndex: receipt.intervalIndex.toString(),
+        nonce: receipt.nonce,
+        reclaimProofId: receipt.reclaimProofId,
+        reclaimOwner: receipt.reclaimOwner,
+        reclaimTimestamp: receipt.reclaimTimestamp.toString(),
+        reclaimEpoch: receipt.reclaimEpoch.toString(),
+        canonicalRequestHash: receipt.canonicalRequestHash,
+        canonicalBodyHash: receipt.canonicalBodyHash,
+    };
+}
+/** Deterministic keccak256 over the canonical (sorted-key) JSON of `value`. */
+function hashCanonical(value) {
+    return keccak256(stringToBytes(canonicalJson(value)));
+}
+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) {
+    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,
+        reclaimOwner: proof.claimData.owner,
+        reclaimTimestamp: BigInt(proof.claimData.timestampS),
+        reclaimEpoch: BigInt(proof.claimData.epoch),
+        canonicalRequestHash,
+        canonicalBodyHash,
+    });
+    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,
+        },
+    });
+    return { body, receipt, signature, proof, envelope };
+}
+//# sourceMappingURL=t2-delivery-proof.js.map

package/dist/zktls/t2-delivery-proof.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"t2-delivery-proof.js","sourceRoot":"","sources":["../../src/zktls/t2-delivery-proof.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absol-labs/agent",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Metrik agent layer: x402 verified-streaming payments, an MCP server, framework tools, and spend mandates so AI agents can hire and pay verified services safely.",
   "license": "MIT",
   "author": "Absol Labs",
@@ -67,7 +67,7 @@
   },
   "dependencies": {
     "@absol-labs/sdk": "^0.4.0",
-    "@absol-labs/shared": "^0.7.1",
+    "@absol-labs/shared": "^0.11.0",
     "@coinbase/cdp-sdk": "^1.51.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@reclaimprotocol/js-sdk": "^5.6.0",

package/src/index.ts

@@ -117,9 +117,13 @@ export {
   ReclaimConsumerProofService,
   ResponseProofUnavailableError,
   ResponseProofVerificationError,
+  buildDeliveryContextEnvelopeV2,
   createReclaimConsumerProofServiceFromEnv,
+  deliveryContextEnvelopeV2Schema,
   parseReclaimProofEnv,
   type ConsumerDeliveryProofService,
+  type DeliveryContextEnvelopeV2,
+  type DeliveryContextEnvelopeV2Input,
   type DeliveryProofBinding,
   type HttpsResponseMatch,
   type HttpsResponseRedaction,
@@ -132,6 +136,24 @@ export {
   type VerifyProofFn,
 } from "./zktls/reclaim.js";
 
+export {
+  NoDeliveryAttestorConfiguredError,
+  PaidRouteNonceInjectionError,
+  ReclaimDeliveryProofAttestor,
+  buildT2DeliveryProofSubmission,
+  createReclaimT2AttestorFromEnv,
+  deliveryProofRequestBodySchema,
+  toWireDeliveryReceipt,
+  type BuildT2DeliveryProofInput,
+  type BuildT2DeliveryProofResult,
+  type DeliveryProofAttestor,
+  type DeliveryProofRequestBody,
+  type PaidRouteRequestSpec,
+  type ProveDeliveryResponseInput,
+  type T2NonceInjection,
+  type WireDeliveryReceipt,
+} from "./zktls/t2-delivery-proof.js";
+
 // Framework adapters are NOT re-exported from this top-level barrel on purpose.
 // Some of them (notably the Coinbase AgentKit adapter) pull heavy optional
 // dependency graphs, so importing "@absol-labs/agent" must stay light and load

package/src/zktls/reclaim.ts

@@ -94,10 +94,19 @@ export interface ReclaimClientLike {
       body?: string;
       headers?: Record<string, string>;
       geoLocation?: string;
-      context?: {
-        contextAddress: string;
-        contextMessage: string;
-      };
+      /**
+       * Whatever is passed here is canonicalized and stored VERBATIM as the
+       * proof's `claimData.context` (see `@reclaimprotocol/attestor-core`'s
+       * `_createClaimOnAttestor`, which does `context: canonicalStringify(context)`
+       * with no further transformation). The upstream zk-fetch SDK types this
+       * narrower (`{contextAddress, contextMessage}`, the L2 v1 convention used
+       * by `buildRequestContext` below) but nothing downstream requires that
+       * wrapper shape - it is opaque JSON. The T2 delivery-proof path
+       * (`t2-delivery-proof.ts`) passes the FLAT `DeliveryContextEnvelopeV2`
+       * object directly so the oracle's `deliveryContextEnvelopeSchema` can
+       * parse `claimData.context` without an extra unwrap step.
+       */
+      context?: Record<string, unknown>;
       useTee?: boolean;
       zkEngine?: "snarkjs" | "stwo";
     },
@@ -329,7 +338,7 @@ export function createReclaimConsumerProofServiceFromEnv(
   return new ReclaimConsumerProofService(parsed);
 }
 
-function defaultReclaimClientFactory(
+export function defaultReclaimClientFactory(
   applicationId: string,
   applicationSecret: string,
   logs: boolean,
@@ -355,8 +364,79 @@ function buildRequestContext(
   };
 }
 
-function toRequestSpec(
-  input: z.infer<typeof reclaimProofInputSchema>,
+/**
+ * The T2 (issue #24 / #85) `metrik-l2-http-response/v2` Metrik delivery-binding
+ * envelope, folded VERBATIM (not wrapped in `{contextAddress, contextMessage}`)
+ * into a Reclaim proof's `claimData.context`. This mirrors the ORACLE's OWN
+ * `deliveryContextEnvelopeSchema` (`streamproof-oracle/src/delivery/context-envelope.ts`)
+ * field-for-field and MUST stay byte-compatible with it - the oracle re-parses
+ * `claimData.context` through its own copy of this schema and fails closed on
+ * any mismatch.
+ *
+ * Unlike the v1 `buildRequestContext` binding above (used by the x402/MCP
+ * consumer-proof-as-signal path, agent#12), every identity field here is
+ * REQUIRED: a T2 accrual receipt cannot bind to a partially-specified stream.
+ */
+export const deliveryContextEnvelopeV2Schema = z
+  .object({
+    kind: z.literal("metrik-l2-http-response/v2"),
+    streamId: bytes32Schema,
+    operator: addressSchema,
+    serviceRef: bytes32Schema,
+    mandateId: z.string().optional(),
+    nonce: bytes32Schema,
+    intervalIndex: z.number().int().nonnegative(),
+    issuedAt: z.number().int().nonnegative(),
+  })
+  .strict();
+
+export type DeliveryContextEnvelopeV2 = z.infer<
+  typeof deliveryContextEnvelopeV2Schema
+>;
+
+export interface DeliveryContextEnvelopeV2Input {
+  readonly streamId: `0x${string}`;
+  readonly operator: `0x${string}`;
+  readonly serviceRef: `0x${string}`;
+  readonly mandateId?: string;
+  readonly nonce: `0x${string}`;
+  readonly intervalIndex: number;
+  /** Unix seconds. Defaults to `Math.floor(Date.now() / 1000)`. */
+  readonly issuedAt?: number;
+}
+
+/**
+ * Build the flat T2 envelope object to pass as `zkFetch`'s `context` option
+ * (see the widened `ReclaimClientLike.zkFetch` doc above - it is stored
+ * verbatim, no `{contextAddress, contextMessage}` wrapper). Validated against
+ * `deliveryContextEnvelopeV2Schema` before return so a malformed binding fails
+ * loudly here rather than silently producing an envelope the oracle rejects.
+ */
+export function buildDeliveryContextEnvelopeV2(
+  input: DeliveryContextEnvelopeV2Input,
+): DeliveryContextEnvelopeV2 {
+  return deliveryContextEnvelopeV2Schema.parse({
+    kind: "metrik-l2-http-response/v2",
+    streamId: input.streamId,
+    operator: input.operator,
+    serviceRef: input.serviceRef,
+    ...(input.mandateId === undefined ? {} : { mandateId: input.mandateId }),
+    nonce: input.nonce,
+    intervalIndex: input.intervalIndex,
+    issuedAt: input.issuedAt ?? Math.floor(Date.now() / 1000),
+  });
+}
+
+/** Structural input `toRequestSpec` needs - satisfied by both the v1 and T2 request shapes. */
+export interface RequestSpecInput {
+  readonly url: string;
+  readonly body?: string | undefined;
+  readonly responseMatches: readonly HttpsResponseMatch[];
+  readonly responseRedactions?: readonly HttpsResponseRedaction[] | undefined;
+}
+
+export function toRequestSpec(
+  input: RequestSpecInput,
   method: "GET" | "POST" | "PUT",
 ): RequestSpec {
   return {
@@ -384,7 +464,7 @@ function toRequestSpec(
   };
 }
 
-function asErrorMessage(error: unknown): string {
+export function asErrorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }