@reclaimprotocol/agent 0.1.1-dev.1 → 0.1.2

package/lib/old/client.d.ts

@@ -24,6 +24,9 @@ export interface RegisterProviderBody {
     description?: string;
     loginUrl: string;
     geoLocation?: string;
+    /** Provider-level flag on the old backend (defaults false there; the
+     *  translator sends `true` to match the builder default). */
+    useProxy?: boolean;
     providerType?: 'PRIVATE' | 'PUBLIC';
     requestData: unknown[];
 }

package/lib/old/flag.d.ts

@@ -7,5 +7,8 @@
  * EXPLICITLY by setting `USE_OLD_DEVTOOLS=false`. Anything else — unset,
  * empty, `true`, `1`, a typo — keeps old mode on, so a forgotten env var
  * can never silently route a developer at the half-built builder backend.
+ *
+ * The actual env read lives in `../consts.ts` (the single env-access module);
+ * this widely-imported path re-exports it for back-compat.
  */
-export declare function useOldDevtools(): boolean;
+export { useOldDevtools } from '../consts.ts';

package/lib/old/flag.js

@@ -7,7 +7,8 @@
  * EXPLICITLY by setting `USE_OLD_DEVTOOLS=false`. Anything else — unset,
  * empty, `true`, `1`, a typo — keeps old mode on, so a forgotten env var
  * can never silently route a developer at the half-built builder backend.
+ *
+ * The actual env read lives in `../consts.ts` (the single env-access module);
+ * this widely-imported path re-exports it for back-compat.
  */
-export function useOldDevtools() {
-    return (process.env.USE_OLD_DEVTOOLS ?? '').trim().toLowerCase() !== 'false';
-}
+export { useOldDevtools } from "../consts.js";

package/lib/old/identity.d.ts

@@ -2,16 +2,6 @@ import type { OldIdentity } from './client.ts';
 /** Normalize an eth uid input to `eth:<lowercase-address>`. Accepts a bare
  *  `0x…` address or an already-prefixed `eth:0x…`. */
 export declare function toEthUid(addressOrUid: string): OldIdentity;
-/**
- * Resolve a caller identity from the environment, in priority order:
- *   1. `RECLAIM_OLD_API_TOKEN` — a dashboard Firebase bearer token.
- *   2. `RECLAIM_OLD_ETH_UID`   — an `eth:<addr>` (or bare `0x…`) uid.
- *   3. `RECLAIM_PRIVATE_KEY`   — derive the eth uid from the local app key.
- * Returns undefined when none is set.
- */
-export declare function resolveIdentityFromEnv(): OldIdentity | undefined;
-/** Read the identity persisted by a prior `reclaim_authenticate` call. */
-export declare function loadPersistedIdentity(): OldIdentity | undefined;
 /** Persist the identity so it survives an MCP-server restart. */
 export declare function persistIdentity(identity: OldIdentity): void;
 /**

package/lib/old/identity.js

@@ -1,5 +1,6 @@
 import { deriveFromPrivateKey } from '@reclaimprotocol/client';
 import { ConfigStore } from "../config/store.js";
+import { oldApiToken, oldEthUid, privateKey } from "../consts.js";
 /** Normalize an eth uid input to `eth:<lowercase-address>`. Accepts a bare
  *  `0x…` address or an already-prefixed `eth:0x…`. */
 export function toEthUid(addressOrUid) {
@@ -14,23 +15,23 @@ export function toEthUid(addressOrUid) {
  *   3. `RECLAIM_PRIVATE_KEY`   — derive the eth uid from the local app key.
  * Returns undefined when none is set.
  */
-export function resolveIdentityFromEnv() {
-    const token = process.env.RECLAIM_OLD_API_TOKEN?.trim();
+function resolveIdentityFromEnv() {
+    const token = oldApiToken()?.trim();
     if (token) {
         return { kind: 'bearer', token };
     }
-    const ethUid = process.env.RECLAIM_OLD_ETH_UID?.trim();
+    const ethUid = oldEthUid()?.trim();
     if (ethUid) {
         return toEthUid(ethUid);
     }
-    const privateKey = process.env.RECLAIM_PRIVATE_KEY?.trim();
-    if (privateKey) {
-        return toEthUid(deriveFromPrivateKey(privateKey).address);
+    const key = privateKey()?.trim();
+    if (key) {
+        return toEthUid(deriveFromPrivateKey(key).address);
     }
     return undefined;
 }
 /** Read the identity persisted by a prior `reclaim_authenticate` call. */
-export function loadPersistedIdentity() {
+function loadPersistedIdentity() {
     return new ConfigStore().read()?.old_devtools;
 }
 /** Persist the identity so it survives an MCP-server restart. */

package/lib/old/instructions.d.ts

@@ -1,7 +1 @@
-/**
- * MCP server instructions shown to the LLM when running in OLD-devtools mode
- * (`USE_OLD_DEVTOOLS` unset or not `false`). Describes the REDUCED tool
- * surface — there are no org/credential-link/review flows and no generated
- * API tools here. Must not mention disabled tools.
- */
 export declare const OLD_MODE_INSTRUCTIONS: string;

package/lib/old/instructions.js

@@ -2,28 +2,10 @@
  * MCP server instructions shown to the LLM when running in OLD-devtools mode
  * (`USE_OLD_DEVTOOLS` unset or not `false`). Describes the REDUCED tool
  * surface — there are no org/credential-link/review flows and no generated
- * API tools here. Must not mention disabled tools.
+ * API tools here. The prose lives in `skill/old-mode.md` (published via the
+ * `files` array); the path resolves identically from `src/old` (dev) and
+ * `lib/old` (published).
  */
-export const OLD_MODE_INSTRUCTIONS = 'This server is running against the LEGACY Reclaim devtools backend ' +
-    '(temporary, while the new builder backend is in development), so its ' +
-    'capabilities are intentionally limited.\n\n' +
-    'Provider-authoring flow:\n' +
-    '1. `reclaim_authenticate` — by default opens the dashboard in Chrome, ' +
-    'waits for you to sign in, captures the token automatically, and closes ' +
-    'the tab (or paste a `token` / pass an eth `ethAddress` to skip the ' +
-    'browser). Do this once before publishing or listing.\n' +
-    '2. `attach_chrome` → `start_capture` → drive the page (`navigate`, ' +
-    '`wait_for_page`) → inspect (`list_requests`, `get_request`, ' +
-    '`find_requests_containing`).\n' +
-    '3. `propose_provider` to draft a provider, `replay_request` to ' +
-    'pre-flight, `run_proof` to verify with the attestor. OPRF/`hash` ' +
-    'redactions are optional and supported.\n' +
-    '4. `create_provider_version_from_capture` to publish. With NO ' +
-    '`providerId` it REGISTERS A NEW provider (re-running creates a ' +
-    'duplicate); pass a ' +
-    '`providerId` from `get_me_providers` to add a new version to an existing ' +
-    'provider instead.\n' +
-    '5. `get_me_providers` lists the providers you own (the only ' +
-    'provider-listing tool available in this mode).\n\n' +
-    'Only GET/POST endpoints can be captured into providers here. There is no ' +
-    'organization, credential-linking, or public-review workflow in this mode.';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+export const OLD_MODE_INSTRUCTIONS = readFileSync(fileURLToPath(new URL('../../skill/old-mode.md', import.meta.url)), 'utf8').trim();

package/lib/old/login-cdp.d.ts

@@ -1,6 +1,3 @@
-/** The devtools dashboard login page. Override per-call or via
- *  `RECLAIM_OLD_LOGIN_URL`. */
-export declare const DEFAULT_LOGIN_URL = "https://dev.reclaimprotocol.org";
 export interface CdpLoginResult {
     token: string;
     /** True when we launched (and then closed) a dedicated Chrome just for

package/lib/old/login-cdp.js

@@ -1,9 +1,7 @@
 import { connectCdp } from "../cdp/client.js";
 import { defaultProfileDir, launchChrome, waitForCdpReady, } from "../cdp/launcher.js";
 import { ConfigStore } from "../config/store.js";
-/** The devtools dashboard login page. Override per-call or via
- *  `RECLAIM_OLD_LOGIN_URL`. */
-export const DEFAULT_LOGIN_URL = 'https://dev.reclaimprotocol.org';
+import { DEFAULT_LOGIN_URL, oldLoginUrl } from "../consts.js";
 /**
  * Read the Firebase ID token the dashboard persisted after login.
  *
@@ -64,7 +62,7 @@ const EXTRACT_TOKEN_JS = `(async () => {
  * disrupt it.
  */
 export async function captureFirebaseTokenViaCdp(opts) {
-    const loginUrl = opts.loginUrl || process.env.RECLAIM_OLD_LOGIN_URL || DEFAULT_LOGIN_URL;
+    const loginUrl = opts.loginUrl || oldLoginUrl() || DEFAULT_LOGIN_URL;
     const timeoutMs = opts.timeoutMs ?? 180_000;
     const pollMs = opts.pollMs ?? 1000;
     const cfg = new ConfigStore().read()?.browser_agent;

package/lib/old/to-register.d.ts

@@ -17,7 +17,10 @@ import type { RegisterProviderBody, UpdateProviderConfigBody } from './client.ts
 export interface OldProviderOpts {
     initialUrl: string;
     description?: string;
+    /** Defaults to `{{DYNAMIC_GEO}}` when omitted. */
     geoLocation?: string;
+    /** Defaults to `true` when omitted. Register only (Provider-level flag). */
+    useProxy?: boolean;
     providerType?: 'PRIVATE' | 'PUBLIC';
 }
 /** Body for `POST /api/providers/register` — new provider + v1.0.0. */

package/lib/old/to-register.js

@@ -1,3 +1,9 @@
+/** Default web settings, mirroring the builder openapi defaults
+ *  (`ProviderWebSettings.geoLocation`, `PortalClientOptions.useProxy`). The old
+ *  backend accepts both: `geoLocation` lives on the providerConfig, `useProxy`
+ *  is a Provider-level flag (register only). */
+const DEFAULT_GEO_LOCATION = '{{DYNAMIC_GEO}}';
+const DEFAULT_USE_PROXY = true;
 /** Build the single `requestData` entry shared by register + update. */
 function requestDataFromProvider(provider) {
     const method = String(provider.method).toUpperCase();
@@ -5,13 +11,31 @@ function requestDataFromProvider(provider) {
         throw new Error('Old devtools supports only GET/POST requests; got ' +
             `"${provider.method}". Re-capture against a GET/POST endpoint.`);
     }
+    // The old backend has no dotted interpolation: consumer-supplied params
+    // must use the `{{context_<name>}}` form here, not the builder's
+    // `{{context.<name>}}`. Catch the mix-up at publish with a clear error
+    // instead of a template that silently never resolves.
+    const dotted = `${provider.url}\n${provider.body ?? ''}`
+        .match(/\{\{context\.[A-Za-z_][A-Za-z0-9_]*\}\}/);
+    if (dotted) {
+        throw new Error(`Old devtools does not support ${dotted[0]} — rename ` +
+            'consumer-supplied params to the {{context_<name>}} form ' +
+            'for this backend.');
+    }
     const responseMatches = provider.responseMatches.map((m, i) => ({
         value: m.value,
         type: m.type ?? 'contains',
         isOptional: false,
         order: i,
     }));
-    const responseRedactions = (provider.responseRedactions ?? []).map((r, i) => {
+    // Old devtools wants `responseMatches` and `responseRedactions` as PARALLEL
+    // arrays — same shape the builder uses, so pass them through directly. We do
+    // NOT enforce any match/redaction count relationship here (and never pad —
+    // empty placeholder matches break proof generation): the author keeps full
+    // control. The publish tool surfaces a non-blocking warning when matches <
+    // redactions (see `matchRedactionWarnings`), and the dev decides.
+    const sourceRedactions = provider.responseRedactions ?? [];
+    const responseRedactions = sourceRedactions.map((r, i) => {
         const out = { order: i };
         if (r.xPath !== undefined) {
             out.xPath = r.xPath;
@@ -54,27 +78,28 @@ export function providerToRegisterBody(provider, opts) {
         name: provider.name,
         loginUrl: opts.initialUrl,
         providerType: opts.providerType ?? 'PRIVATE',
+        // Web-settings defaults mirror the builder openapi defaults.
+        geoLocation: opts.geoLocation ?? DEFAULT_GEO_LOCATION,
+        useProxy: opts.useProxy ?? DEFAULT_USE_PROXY,
         requestData: [requestDataFromProvider(provider)],
     };
     if (opts.description !== undefined) {
         body.description = opts.description;
     }
-    if (opts.geoLocation !== undefined) {
-        body.geoLocation = opts.geoLocation;
-    }
     return body;
 }
 /** Body for `POST /api/providers/:providerId/config` — adds a new version to
  *  an EXISTING provider. `version` must not already exist; `versionInfo` is
  *  required and must be ≥10 chars (enforced by the backend). */
 export function providerToConfigBody(provider, opts, version, versionInfo) {
+    // `useProxy` is a Provider-level flag on the old backend, not part of a
+    // version's providerConfig — so the config (new-version) path only carries
+    // `geoLocation`. It defaults the same way as register.
     const providerConfig = {
         loginUrl: opts.initialUrl,
+        geoLocation: opts.geoLocation ?? DEFAULT_GEO_LOCATION,
         requestData: [requestDataFromProvider(provider)],
     };
-    if (opts.geoLocation !== undefined) {
-        providerConfig.geoLocation = opts.geoLocation;
-    }
     return { providerConfig, version, versionInfo };
 }
 /**

package/lib/old/tools/authenticate.js

@@ -1,3 +1,4 @@
+import { agentDisabled } from "../../consts.js";
 import { defineTool } from "../../mcp/server.js";
 import { persistIdentity, toEthUid } from "../identity.js";
 import { captureFirebaseTokenViaCdp } from "../login-cdp.js";
@@ -108,7 +109,7 @@ export function authenticateTool(client) {
             }
         }
         // CDP browser login (the default headline flow).
-        if (process.env.RECLAIM_AGENT_DISABLED === '1') {
+        if (agentDisabled()) {
             throw new Error('Browser login is unavailable (RECLAIM_AGENT_DISABLED=1). Pass a ' +
                 '`token` (Firebase ID token) or `ethAddress` instead.');
         }

package/lib/old/tools/publish.js

@@ -1,6 +1,32 @@
+import { Boom, isBoom } from '@hapi/boom';
 import { defineTool } from "../../mcp/server.js";
+import { countsFor, matchRedactionWarnings, } from "../../provider/match-redaction-warning.js";
 import { bumpPatchString, extractVersions, providerToConfigBody, providerToRegisterBody, } from "../to-register.js";
 const DEFAULT_VERSION_INFO = 'Updated from MCP browser capture';
+/**
+ * The old backend lets you add a version only to a provider YOU own. A
+ * `providerId` for a public provider (or anyone else's) comes back as
+ * 401/403/404 — the dev's likely intent is to publish their OWN version of that
+ * site, which on this backend means registering a separate copy. Rethrow those
+ * failures with that actionable suggestion; leave other errors (e.g. a 400
+ * version collision) untouched so their real detail surfaces.
+ */
+function rethrowOwnershipError(err, providerId) {
+    const status = isBoom(err) ? err.output.statusCode : undefined;
+    if (status !== 401 && status !== 403 && status !== 404) {
+        throw err;
+    }
+    const base = isBoom(err) ? err.message : String(err);
+    throw new Boom(`${base} — could not add a version to provider ${providerId}. You can ` +
+        'only publish new versions on providers you own. If this is a public ' +
+        "provider (or one you don't own), re-run " +
+        'create_provider_version_from_capture WITHOUT `providerId` to register ' +
+        "your own copy. If it IS yours, confirm you're authenticated " +
+        '(reclaim_authenticate) as the account that created it.', {
+        statusCode: status,
+        data: isBoom(err) ? err.data : { status, detail: base },
+    });
+}
 /**
  * Publish a drafted provider to the OLD devtools backend. Keeps the builder
  * tool NAME (`create_provider_version_from_capture`) so the skill flow is
@@ -25,6 +51,10 @@ export function createVersionFromCaptureTool(client) {
             '1.0.0; re-running creates a duplicate). Pass `providerId` (from ' +
             'get_me_providers) to add a NEW VERSION to that existing provider ' +
             '(the patch is auto-bumped). \n\n' +
+            'You can only add versions to a provider YOU own — the `providerId` ' +
+            'must come from get_me_providers. To publish your own version of a ' +
+            "PUBLIC provider you don't own, omit `providerId` to register your " +
+            'own copy (you cannot edit someone else\'s provider here). \n\n' +
             'Captured requests must be GET/POST. OPRF redactions are supported.',
         inputSchema: {
             type: 'object',
@@ -58,7 +88,16 @@ export function createVersionFromCaptureTool(client) {
                     type: 'string',
                     description: 'Provider description (new-provider register only).',
                 },
-                geoLocation: { type: 'string' },
+                geoLocation: {
+                    type: 'string',
+                    description: 'Geo the verification appears to originate from. Defaults to ' +
+                        "'{{DYNAMIC_GEO}}' (the user's geo) when omitted.",
+                },
+                useProxy: {
+                    type: 'boolean',
+                    description: 'Route portal/attestation traffic through a proxy. Defaults to ' +
+                        'true when omitted. Applied on register only.',
+                },
                 providerType: { type: 'string', enum: ['PRIVATE', 'PUBLIC'] },
                 notes: {
                     type: 'string',
@@ -76,22 +115,44 @@ export function createVersionFromCaptureTool(client) {
         if (args.geoLocation !== undefined) {
             opts.geoLocation = args.geoLocation;
         }
+        if (args.useProxy !== undefined) {
+            opts.useProxy = args.useProxy;
+        }
         if (args.providerType !== undefined) {
             opts.providerType = args.providerType;
         }
+        // Non-blocking advisory — never alters or blocks the publish; the
+        // author keeps full control. Attaches under `_notes` when relevant.
+        const notes = matchRedactionWarnings([
+            countsFor('Request', args.provider),
+        ]);
+        const withNotes = (result) => {
+            if (notes.length && result && typeof result === 'object') {
+                return { ...result, _notes: notes };
+            }
+            return result;
+        };
         // New provider.
         if (!args.providerId) {
             const body = providerToRegisterBody(args.provider, opts);
-            return client.registerProvider(body);
+            return withNotes(await client.registerProvider(body));
         }
         // New version of an existing provider — pick the next patch above
-        // the highest existing version.
-        const versionsResp = await client.listVersions(args.providerId);
-        const version = bumpPatchString(extractVersions(versionsResp));
-        const versionInfo = args.notes && args.notes.trim().length >= 10
-            ? args.notes.trim()
-            : DEFAULT_VERSION_INFO;
-        const body = providerToConfigBody(args.provider, opts, version, versionInfo);
-        return client.updateProviderConfig(args.providerId, body);
+        // the highest existing version. A provider you don't own (e.g. a
+        // public one) fails here with 401/403/404; surface the register-a-copy
+        // workaround instead of a bare permission error.
+        const providerId = args.providerId;
+        try {
+            const versionsResp = await client.listVersions(providerId);
+            const version = bumpPatchString(extractVersions(versionsResp));
+            const versionInfo = args.notes && args.notes.trim().length >= 10
+                ? args.notes.trim()
+                : DEFAULT_VERSION_INFO;
+            const body = providerToConfigBody(args.provider, opts, version, versionInfo);
+            return withNotes(await client.updateProviderConfig(providerId, body));
+        }
+        catch (err) {
+            rethrowOwnershipError(err, providerId);
+        }
     });
 }

package/lib/paths.js

@@ -1,12 +1,12 @@
 import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import { reclaimHome } from "./consts.js";
 /**
  * Resolve the Reclaim cache directory (`~/.reclaim`). Honours the
  * `RECLAIM_HOME` env var as an override so tests can sandbox writes.
  */
 export function reclaimHomeDirPath() {
-    return process.env.RECLAIM_HOME || join(homedir(), '.reclaim');
+    return reclaimHome();
 }
 /**
  * Walk up from `start` until we find a directory containing one of

package/lib/proof/attestor.d.ts

@@ -4,6 +4,35 @@ export interface AttestorLogEntry {
     msg: string;
     ctx?: Record<string, unknown>;
 }
+/** The attestor's signed claim data + signature, for building the nested proof
+ *  JWS a Consumer verifies against the attestor's key. Populated when
+ *  `includeAttestorClaim` is set (the app's verification runner needs it; the
+ *  MCP `run_proof` tool ignores it). */
+export interface AttestorClaim {
+    /** ProviderClaimData: provider, parameters, context (JSON string), owner,
+     *  timestampS, epoch, identifier. */
+    claim: Record<string, unknown>;
+    /** Hex (0x) attestor ETH address that signed the claim (the nested `kid`). */
+    attestorAddress: string;
+    /** Hex (0x) attestor claim signature (EIP-191 over the claim sign-data). */
+    claimSignature: string;
+}
+/** Options for {@link runAttestorProof}. */
+export interface RunAttestorProofOptions {
+    attestorUrl?: string;
+    /** When resolving the key from env/.env/file, the address the caller expects
+     *  to sign with (sanity check). Ignored when `ownerPrivateKey` is given. */
+    ownerAddress?: string;
+    /** Sign with this key directly (e.g. the app/VC's ephemeral per-session key)
+     *  instead of resolving from env/.env/file. */
+    ownerPrivateKey?: string;
+    /** ZK engine for `createClaimOnAttestor`. Defaults to `'gnark'`; the app's
+     *  server-side verification runner uses `'snarkjs'`. */
+    zkEngine?: 'gnark' | 'snarkjs';
+    /** Extract the structured {@link AttestorClaim} (claim + attestor signature)
+     *  onto the result for nested-proof construction. */
+    includeAttestorClaim?: boolean;
+}
 export interface ProofResult {
     proof: unknown;
     extractedValue: string;
@@ -12,6 +41,9 @@ export interface ProofResult {
     owner?: string;
     verified: boolean;
     error?: string;
+    /** Structured claim + signature for nested-proof verification. Set only when
+     *  `includeAttestorClaim` was requested and the claim carries signatures. */
+    attestorClaim?: AttestorClaim;
     /** Set to `'missing-owner-key'` when no credential was available to
      *  sign with — distinguishes this recoverable case from other proof
      *  errors so the skill can point the dev at `issue_credentials` /
@@ -36,4 +68,4 @@ export declare function tailLogs(entries: AttestorLogEntry[], n?: number): Attes
 /** Filter to just warn/error/fatal — for the LLM-visible response on
  *  successful proofs, where chatty trace/info would just waste context. */
 export declare function warnsAndErrors(entries: AttestorLogEntry[]): AttestorLogEntry[];
-export declare function runAttestorProof(provider: ReclaimProvider, secrets: Record<string, string>, attestorUrl?: string, ownerAddress?: string): Promise<ProofResult>;
+export declare function runAttestorProof(provider: ReclaimProvider, secrets: Record<string, string>, opts?: RunAttestorProofOptions): Promise<ProofResult>;

package/lib/proof/attestor.js

@@ -5,8 +5,11 @@
 // 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 { agentTraceEnabled } from "../consts.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,56 +83,61 @@ 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
         // turn it back on when something's broken; logs flow into the proof
         // response and into the on-disk proof-runs dump.
-        const traceEnabled = process.env['RECLAIM_AGENT_TRACE'] === '1';
+        const traceEnabled = agentTraceEnabled();
         const capture = traceEnabled ? makeCaptureLogger() : undefined;
         const attestorLogs = capture?.entries;
         let claim;
@@ -141,8 +149,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 +168,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';