@reclaimprotocol/agent 0.1.1-dev.1 → 0.1.1

package/lib/proof/attestor.js

@@ -5,8 +5,10 @@
 // responseMatches are the regex/contains checks the attestor runs on the
 // revealed slice; jsonPath/xPath live on responseRedactions (what the prover
 // reveals), never on responseMatches.
+import { bytesToHex } from '@noble/hashes/utils.js';
 import { createClaimOnAttestor, } from '@reclaimprotocol/attestor-core';
-import { resolveOwnerPrivateKey } from "../mcp/tools/credentials/cache.js";
+import { resolveEthKey } from "../mcp/tools/authenticate/eth-key.js";
+import { buildHttpParams, ensureAttestorCrypto, parseClaim, resolveAttestorUrl, } from "./proof-core.js";
 import { ensureZkFiles } from "./zk-files.js";
 /** Trim a captured log stream to the last N entries — for shrinking the
  *  LLM-visible response while the full stream stays in the on-disk dump. */
@@ -80,50 +82,55 @@ function makeCaptureLogger() {
     };
     return { logger: make({}), entries };
 }
-/** Default public attestor websocket URL. Resolved per-call so an env-var
- *  change or per-request override takes effect without restarting the
- *  MCP server. */
-const FALLBACK_ATTESTOR_URL = 'wss://attestor.reclaimprotocol.org:444/ws';
-function resolveAttestorUrl(override) {
-    return (override ?? process.env['RECLAIM_ATTESTOR_URL'] ?? FALLBACK_ATTESTOR_URL);
-}
 // ---------------------------------------------------------------------------
 // Main entry point
 // ---------------------------------------------------------------------------
-export async function runAttestorProof(provider, secrets, attestorUrl, ownerAddress) {
-    // The owner is chosen up front (resolve_owner_key) and passed as
-    // `ownerAddress`; here we just fetch its private key and sign.
-    const ownerPrivateKey = ownerAddress
-        ? resolveOwnerPrivateKey(ownerAddress)
-        : undefined;
-    if (!ownerPrivateKey) {
-        return {
-            proof: undefined,
-            extractedValue: '',
-            extractedParameters: {},
-            verified: false,
-            error: `No private key available for ownerAddress "${ownerAddress ?? ''}". ` +
-                'Call resolve_owner_key to pick a credential (or ' +
-                'issue_credentials / import_credentials to set one up), then ' +
-                'retry run_proof with its address as ownerAddress.',
-            errorKind: 'missing-owner-key',
-        };
+export async function runAttestorProof(provider, secrets, opts = {}) {
+    // Sign with the caller-supplied key (the app/VC's ephemeral per-session
+    // key) when given; otherwise resolve env/.env/file. `ownerAddress` is a
+    // sanity check on the resolved key (ignored when a key is supplied).
+    let ownerPrivateKey;
+    if (opts.ownerPrivateKey) {
+        ownerPrivateKey = opts.ownerPrivateKey;
+    }
+    else {
+        const resolved = resolveEthKey();
+        if (!resolved) {
+            return {
+                proof: undefined,
+                extractedValue: '',
+                extractedParameters: {},
+                verified: false,
+                error: 'No eth proof-owner key available (no RECLAIM_PRIVATE_KEY in env, ' +
+                    '.env, or RECLAIM_PRIVATE_KEY_FILE). Call resolve_owner_key, then ' +
+                    'issue_credentials (generate) or import_credentials (provide one), ' +
+                    'and retry run_proof.',
+                errorKind: 'missing-owner-key',
+            };
+        }
+        if (opts.ownerAddress
+            && opts.ownerAddress.toLowerCase() !== resolved.address) {
+            return {
+                proof: undefined,
+                extractedValue: '',
+                extractedParameters: {},
+                verified: false,
+                error: `Requested ownerAddress "${opts.ownerAddress}" does not match ` +
+                    `the resolved eth key (${resolved.address}, source: ` +
+                    `${resolved.source}). ` +
+                    'Call resolve_owner_key to get the current address, or update the ' +
+                    'configured key.',
+                errorKind: 'missing-owner-key',
+            };
+        }
+        ownerPrivateKey = resolved.privateKey;
     }
     try {
-        // Circuits aren't downloaded at install time (that blocked the MCP
-        // server's first launch). Fetch them lazily on the first proof.
+        // Init the TLS crypto backend (idempotent), then fetch ZK circuits
+        // lazily on the first proof (not at install time).
+        ensureAttestorCrypto();
         await ensureZkFiles();
-        const params = {
-            url: provider.url,
-            method: provider.method,
-            ...(provider.headers !== undefined && { headers: provider.headers }),
-            ...(provider.body !== undefined && { body: provider.body }),
-            responseMatches: provider.responseMatches,
-            responseRedactions: provider.responseRedactions ?? [],
-            ...(provider.paramValues !== undefined && {
-                paramValues: provider.paramValues,
-            }),
-        };
+        const params = buildHttpParams(provider);
         // Diagnostic logger capture is gated behind RECLAIM_AGENT_TRACE so the
         // happy path doesn't pay the cost (the attestor SDK emits a *lot* of
         // trace/debug entries during ZK setup). Flip RECLAIM_AGENT_TRACE=1 to
@@ -141,8 +148,8 @@ export async function runAttestorProof(provider, secrets, attestorUrl, ownerAddr
                     headers: secrets,
                 },
                 ownerPrivateKey,
-                client: { url: resolveAttestorUrl(attestorUrl) },
-                zkEngine: 'snarkjs',
+                client: { url: resolveAttestorUrl(opts.attestorUrl) },
+                zkEngine: opts.zkEngine ?? 'gnark',
                 ...(capture !== undefined && { logger: capture.logger }),
             });
         }
@@ -160,38 +167,33 @@ export async function runAttestorProof(provider, secrets, attestorUrl, ownerAddr
             }
             return errorResult;
         }
-        // ClaimTunnelResponse carries the claim under `.claim`.
-        const claimRecord = claim;
-        const claimData = claimRecord['claim'];
-        // claimData.context is a JSON-encoded string carrying
-        // { extractedParameters: {...}, providerHash, ... }.
-        let context = {};
-        const rawContext = claimData?.['context'];
-        if (typeof rawContext === 'string') {
-            try {
-                context = JSON.parse(rawContext);
-            }
-            catch {
-                // Leave context empty if it isn't valid JSON.
-            }
-        }
-        const extractedParameters = context['extractedParameters'] ??
-            {};
-        const extractedValue = Object.values(extractedParameters)[0] ?? '';
+        const { extractedValue, extractedParameters, identifier, owner, claimData } = parseClaim(claim);
         const result = {
             proof: claim,
             extractedValue,
             extractedParameters,
             verified: true,
         };
-        const identifier = claimData?.['identifier'];
-        if (typeof identifier === 'string') {
+        if (identifier !== undefined) {
             result.identifier = identifier;
         }
-        const owner = claimData?.['owner'];
-        if (typeof owner === 'string') {
+        if (owner !== undefined) {
             result.owner = owner;
         }
+        // Structured claim + signature so the result JWS can carry a nested,
+        // attestor-signed proof the Consumer verifies independently.
+        if (opts.includeAttestorClaim) {
+            const sigs = claim.signatures;
+            if (claimData
+                && typeof sigs?.attestorAddress === 'string'
+                && sigs.claimSignature instanceof Uint8Array) {
+                result.attestorClaim = {
+                    claim: claimData,
+                    attestorAddress: sigs.attestorAddress,
+                    claimSignature: '0x' + bytesToHex(sigs.claimSignature),
+                };
+            }
+        }
         // Only set when RECLAIM_AGENT_TRACE=1. Full stream — the MCP layer
         // trims for the LLM-visible response; the on-disk dump gets it all.
         if (attestorLogs !== undefined && attestorLogs.length > 0) {

package/lib/proof/index.d.ts

@@ -0,0 +1,5 @@
+export type { AttestorClaim, AttestorLogEntry, ProofResult, RunAttestorProofOptions, } from './attestor.ts';
+export { runAttestorProof, tailLogs, warnsAndErrors } from './attestor.ts';
+export { buildHttpParams, ensureAttestorCrypto, type ParsedClaim, parseClaim, resolveAttestorUrl, } from './proof-core.ts';
+export { ensureZkFiles } from './zk-files.ts';
+export { createClaimOnAttestor } from '@reclaimprotocol/attestor-core';

package/lib/proof/index.js

@@ -0,0 +1,6 @@
+export { runAttestorProof, tailLogs, warnsAndErrors } from "./attestor.js";
+export { buildHttpParams, ensureAttestorCrypto, parseClaim, resolveAttestorUrl, } from "./proof-core.js";
+export { ensureZkFiles } from "./zk-files.js";
+// Re-exported attestor-core claim primitive so the agent is the single
+// integration point with @reclaimprotocol/attestor-core across the builder.
+export { createClaimOnAttestor } from '@reclaimprotocol/attestor-core';

package/lib/proof/proof-core.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared attestor-claim plumbing used by both proof callers: the agent's MCP
+ * `run_proof` (which resolves the owner key from the credential cache and
+ * captures trace logs) and the app's verification runner (which signs with an
+ * ephemeral per-session key and builds a nested-proof claim). Only those
+ * concerns differ — building the HTTP params, resolving the attestor URL, and
+ * parsing the claim response are identical, so they live here.
+ */
+import type { ProviderParams } from '@reclaimprotocol/attestor-core';
+import type { ReclaimProvider } from '../provider/schema.ts';
+/** One-time crypto backend init for `@reclaimprotocol/tls` (idempotent). The
+ *  package ships with an empty `crypto = {}` and defers the backend to the
+ *  caller; without this the first proof dies inside the TLS client with
+ *  `crypto.randomBytes is not a function`. Shared by every attestor caller —
+ *  the agent MCP `run_proof` tool and the app's verification runner. */
+export declare function ensureAttestorCrypto(): void;
+/** Resolve the attestor websocket URL: explicit override → env → public
+ *  default. Resolved per-call so an env change or per-request override takes
+ *  effect without restarting. */
+export declare function resolveAttestorUrl(override?: string): string;
+/** Map a verification's provider recipe straight to the attestor's HTTP
+ *  params — never synthesized from captured traffic. */
+export declare function buildHttpParams(provider: ReclaimProvider): ProviderParams<'http'>;
+export interface ParsedClaim {
+    /** ProviderClaimData: provider, parameters, context, owner, identifier, … */
+    claimData?: Record<string, unknown>;
+    extractedParameters: Record<string, string>;
+    extractedValue: string;
+    identifier?: string;
+    owner?: string;
+}
+/** Pull claimData + decoded `context.extractedParameters` (plus identifier /
+ *  owner) out of a `createClaimOnAttestor` result. The full result still
+ *  carries signatures the caller may need for nested-proof building. */
+export declare function parseClaim(claim: unknown): ParsedClaim;

package/lib/proof/proof-core.js

@@ -0,0 +1,73 @@
+import { setCryptoImplementation } from '@reclaimprotocol/tls';
+import { webcryptoCrypto } from '@reclaimprotocol/tls/webcrypto';
+const FALLBACK_ATTESTOR_URL = 'wss://attestor.reclaimprotocol.org:444/ws';
+let cryptoInitialized = false;
+/** One-time crypto backend init for `@reclaimprotocol/tls` (idempotent). The
+ *  package ships with an empty `crypto = {}` and defers the backend to the
+ *  caller; without this the first proof dies inside the TLS client with
+ *  `crypto.randomBytes is not a function`. Shared by every attestor caller —
+ *  the agent MCP `run_proof` tool and the app's verification runner. */
+export function ensureAttestorCrypto() {
+    if (cryptoInitialized) {
+        return;
+    }
+    setCryptoImplementation(webcryptoCrypto);
+    cryptoInitialized = true;
+}
+/** Resolve the attestor websocket URL: explicit override → env → public
+ *  default. Resolved per-call so an env change or per-request override takes
+ *  effect without restarting. */
+export function resolveAttestorUrl(override) {
+    return (override ?? process.env['RECLAIM_ATTESTOR_URL'] ?? FALLBACK_ATTESTOR_URL);
+}
+/** Map a verification's provider recipe straight to the attestor's HTTP
+ *  params — never synthesized from captured traffic. */
+export function buildHttpParams(provider) {
+    return {
+        url: provider.url,
+        method: provider.method,
+        ...(provider.headers !== undefined && { headers: provider.headers }),
+        ...(provider.body !== undefined && { body: provider.body }),
+        responseMatches: provider.responseMatches,
+        responseRedactions: provider.responseRedactions ?? [],
+        ...(provider.paramValues !== undefined && {
+            paramValues: provider.paramValues,
+        }),
+    };
+}
+/** Pull claimData + decoded `context.extractedParameters` (plus identifier /
+ *  owner) out of a `createClaimOnAttestor` result. The full result still
+ *  carries signatures the caller may need for nested-proof building. */
+export function parseClaim(claim) {
+    const claimRecord = claim;
+    const claimData = claimRecord['claim'];
+    // claimData.context is a JSON-encoded string carrying
+    // { extractedParameters: {...}, providerHash, ... }.
+    let context = {};
+    const rawContext = claimData?.['context'];
+    if (typeof rawContext === 'string') {
+        try {
+            context = JSON.parse(rawContext);
+        }
+        catch {
+            // Leave context empty if it isn't valid JSON.
+        }
+    }
+    const extractedParameters = context['extractedParameters'] ?? {};
+    const parsed = {
+        extractedParameters,
+        extractedValue: Object.values(extractedParameters)[0] ?? '',
+    };
+    if (claimData) {
+        parsed.claimData = claimData;
+    }
+    const identifier = claimData?.['identifier'];
+    if (typeof identifier === 'string') {
+        parsed.identifier = identifier;
+    }
+    const owner = claimData?.['owner'];
+    if (typeof owner === 'string') {
+        parsed.owner = owner;
+    }
+    return parsed;
+}

package/lib/provider/index.d.ts

@@ -0,0 +1,5 @@
+export { extractGraphqlOp, looksLikeGraphqlEndpoint } from './graphql.ts';
+export type { CapturedRequest, HttpMethod, OprfMode, ReclaimProvider, RequestConcern, ResponseMatch, ResponseRedaction, SecretParamRef, } from './schema.ts';
+export { classifyHeader, splitSecrets } from './secrets.ts';
+export { hashProviderParams, providers } from '@reclaimprotocol/attestor-core';
+export type { ProviderParams } from '@reclaimprotocol/attestor-core';

package/lib/provider/index.js

@@ -0,0 +1,9 @@
+// Provider primitives shared with the app's capture pipeline:
+// the attestor-derived recipe types, secret classification, and the GraphQL
+// op parser. Exposed as `@reclaimprotocol/agent/provider`.
+export { extractGraphqlOp, looksLikeGraphqlEndpoint } from "./graphql.js";
+export { classifyHeader, splitSecrets } from "./secrets.js";
+// Re-exported attestor-core provider primitives (the registry, the param hash,
+// and the param type) so the builder imports them via the agent rather than
+// depending on @reclaimprotocol/attestor-core directly.
+export { hashProviderParams, providers } from '@reclaimprotocol/attestor-core';

package/lib/provider/to-version.d.ts

@@ -1,22 +1,19 @@
 import type { ReclaimClient } from '@reclaimprotocol/client';
-import type { CreateProviderVersionRequest as CreateVersionBody, ProviderVersionRef as VersionRef } from '../types/openapi.ts';
+import type { CreateProviderVersionRequest, ProviderVersionRef } from '@reclaimprotocol/client/openapi';
 import type { ReclaimProvider } from './schema.ts';
 /**
- * Translate a drafted ReclaimProvider into the body for
- * POST /providers/{providerId}/versions.
- *
- * `initialUrl` is the landing page the user navigated to during
- * capture — distinct from `provider.url` which is the specific
- * API URL the attestor replays.
- *
- * Secrets are NOT persisted — the verification client re-supplies
- * them at runtime via `credentials: 'include'`.
+ * Derive the version's `requiredContext` JSON Schema from the
+ * `{{context.<name>}}` placeholders in the provider's url/body — mechanical,
+ * so a published recipe can never reference a context value the Builder
+ * doesn't require. Returns undefined when the recipe has none (the field is
+ * optional). Authors can refine types/descriptions in the version editor.
  */
-export declare function providerToCreateVersionRequest(provider: ReclaimProvider, initialUrl: string, notes?: string, version?: VersionRef): CreateVersionBody;
+export declare function deriveRequiredContext(provider: ReclaimProvider): CreateProviderVersionRequest['requiredContext'];
+export declare function providerToCreateVersionRequest(provider: ReclaimProvider, initialUrl: string, notes?: string, version?: ProviderVersionRef): CreateProviderVersionRequest;
 /**
  * Fetch the current versions for a provider and return the next version above
  * the highest existing one (bumping the patch number), or 1.0.0 when the
  * provider has no versions yet. A failed lookup propagates — silently
  * resetting to 1.0.0 would re-publish a v3 provider as v1.0.0.
  */
-export declare function nextVersion(client: ReclaimClient, providerId: string): Promise<VersionRef>;
+export declare function nextVersion(client: ReclaimClient, providerId: string): Promise<ProviderVersionRef>;

package/lib/provider/to-version.js

@@ -9,7 +9,35 @@
  * Secrets are NOT persisted — the verification client re-supplies
  * them at runtime via `credentials: 'include'`.
  */
+/** `{{context.<name>}}` placeholders in a request URL/body: values the
+ *  CONSUMER supplies at verification time via the session `context`. Bare
+ *  `{{name}}` placeholders (extraction params) are not consumer-supplied
+ *  and are ignored. */
+const CONTEXT_PARAM_RE = /\{\{context\.([A-Za-z_][A-Za-z0-9_]*)\}\}/g;
+/**
+ * Derive the version's `requiredContext` JSON Schema from the
+ * `{{context.<name>}}` placeholders in the provider's url/body — mechanical,
+ * so a published recipe can never reference a context value the Builder
+ * doesn't require. Returns undefined when the recipe has none (the field is
+ * optional). Authors can refine types/descriptions in the version editor.
+ */
+export function deriveRequiredContext(provider) {
+    const haystack = `${provider.url}\n${provider.body ?? ''}`;
+    const names = new Set();
+    for (const m of haystack.matchAll(CONTEXT_PARAM_RE)) {
+        names.add(m[1]);
+    }
+    if (!names.size) {
+        return undefined;
+    }
+    const properties = {};
+    for (const name of names) {
+        properties[name] = { type: 'string' };
+    }
+    return { type: 'object', required: [...names], properties };
+}
 export function providerToCreateVersionRequest(provider, initialUrl, notes, version) {
+    const requiredContext = deriveRequiredContext(provider);
     // Inline responseRedactions into matches[*].extract (1-to-1 by index).
     const matches = (provider.responseMatches ?? []).map((match, i) => {
         const redaction = provider.responseRedactions?.[i];
@@ -33,10 +61,16 @@ export function providerToCreateVersionRequest(provider, initialUrl, notes, vers
             },
         ],
         allowedJsRequests: [],
-        webSettings: { geoLocation: '{{DYNAMIC_GEO}}' },
-        ...(provider.paramValues
-            ? { requiredParameters: provider.paramValues }
-            : {}),
+        // Mirror the builder openapi defaults explicitly — the server does not
+        // apply schema defaults to request bodies.
+        webSettings: {
+            geoLocation: '{{DYNAMIC_GEO}}',
+            clientOptions: { portal: { useProxy: true } },
+        },
+        // Derived from `{{context.<name>}}` placeholders only — a captured
+        // provider's `paramValues` are extracted response parameters, not
+        // consumer context, and never become requiredContext.
+        ...(requiredContext ? { requiredContext } : {}),
         ...(notes ? { notes } : {}),
     };
 }

package/lib/provider/verification-checks.d.ts

@@ -0,0 +1,12 @@
+import type { ReclaimProvider } from './schema.ts';
+/**
+ * Advisory pre-publish lint for a drafted provider — never a gate. Surfaces
+ * only what the AUTHOR must decide; everything testable is tested by the
+ * verification client itself (CDP capture sees all traffic — navigations,
+ * XHRs, fetches — and `checkCandidate` in packages/app src/verify/run.ts
+ * selects the captured request that satisfies the recipe, skipping the
+ * rest). Interpolation and matching are plain text and work for any
+ * captured content; extract selectors apply client-side in spec order
+ * xPath → jsonPath → regex, each to the prior selection.
+ */
+export declare function verificationWarnings(provider: ReclaimProvider): string[];

package/lib/provider/verification-checks.js

@@ -0,0 +1,30 @@
+/**
+ * Advisory pre-publish lint for a drafted provider — never a gate. Surfaces
+ * only what the AUTHOR must decide; everything testable is tested by the
+ * verification client itself (CDP capture sees all traffic — navigations,
+ * XHRs, fetches — and `checkCandidate` in packages/app src/verify/run.ts
+ * selects the captured request that satisfies the recipe, skipping the
+ * rest). Interpolation and matching are plain text and work for any
+ * captured content; extract selectors apply client-side in spec order
+ * xPath → jsonPath → regex, each to the prior selection.
+ */
+export function verificationWarnings(provider) {
+    const out = [];
+    // Untemplated user-specific URL parts: any captured param value baked
+    // literally into the URL makes the provider user-specific. Only the dev
+    // can decide: consumer-supplied → {{context.<name>}} (declared in
+    // requiredContext; consumers then send the exact value and the VC matches
+    // only that value), bare {{<name>}} (resolved from the end-user's own
+    // traffic), or re-capture a non-user-specific endpoint.
+    for (const [name, value] of Object.entries(provider.paramValues ?? {})) {
+        if (value.length >= 3 && provider.url.includes(value)) {
+            out.push(`The URL contains the captured value "${value}" (param ` +
+                `"${name}") as a literal. Decide with the dev: if consumers ` +
+                'supply it, replace with {{context.' + name + '}} (published ' +
+                'requiredContext will require it; verification matches only ' +
+                'the supplied value). Leaving it literal pins the provider ' +
+                'to this user.');
+        }
+    }
+    return out;
+}