@reclaimprotocol/agent 0.1.0-dev.1

package/lib/old/tools/publish.js

@@ -0,0 +1,97 @@
+import { defineTool } from "../../mcp/server.js";
+import { bumpPatchString, extractVersions, providerToConfigBody, providerToRegisterBody, } from "../to-register.js";
+const DEFAULT_VERSION_INFO = 'Updated from MCP browser capture';
+/**
+ * Publish a drafted provider to the OLD devtools backend. Keeps the builder
+ * tool NAME (`create_provider_version_from_capture`) so the skill flow is
+ * unchanged, but the behaviour differs:
+ *
+ *   - WITHOUT `providerId` → `POST /api/providers/register`: creates a
+ *     brand-new provider + version 1.0.0. Re-running creates a DUPLICATE.
+ *   - WITH `providerId` → `POST /api/providers/:providerId/config`: adds a
+ *     new version to an existing provider (auto-bumps the patch above the
+ *     highest existing version).
+ *
+ * Get a `providerId` from `get_me_providers`.
+ */
+export function createVersionFromCaptureTool(client) {
+    return defineTool({
+        name: 'create_provider_version_from_capture',
+        description: 'Publish a drafted ReclaimProvider to the OLD devtools backend. ' +
+            'Pass the `provider` object from propose_provider VERBATIM and the ' +
+            '`initialUrl` the user landed on (the login/landing page, NOT the ' +
+            'API url). \n\n' +
+            'Omit `providerId` to REGISTER A NEW provider (creates it + version ' +
+            '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' +
+            'Captured requests must be GET/POST. OPRF redactions are supported.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                provider: {
+                    type: 'object',
+                    description: 'The `provider` object from propose_provider, verbatim.',
+                    properties: {
+                        name: { type: 'string' },
+                        url: { type: 'string' },
+                        method: { type: 'string' },
+                        headers: { type: 'object' },
+                        body: { type: 'string' },
+                        responseMatches: { type: 'array' },
+                        responseRedactions: { type: 'array' },
+                        paramValues: { type: 'object' },
+                    },
+                    required: ['name', 'url', 'method', 'responseMatches'],
+                },
+                initialUrl: {
+                    type: 'string',
+                    description: 'The website URL the user landed on to trigger the request ' +
+                        '(maps to the provider `loginUrl`).',
+                },
+                providerId: {
+                    type: 'string',
+                    description: 'Existing provider to add a new version to. Omit to register ' +
+                        'a brand-new provider.',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Provider description (new-provider register only).',
+                },
+                geoLocation: { type: 'string' },
+                providerType: { type: 'string', enum: ['PRIVATE', 'PUBLIC'] },
+                notes: {
+                    type: 'string',
+                    description: 'Change note for the new version (update only; must be ≥10 ' +
+                        'chars or a default is used).',
+                },
+            },
+            required: ['provider', 'initialUrl'],
+        },
+    }, async (args) => {
+        const opts = { initialUrl: args.initialUrl };
+        if (args.description !== undefined) {
+            opts.description = args.description;
+        }
+        if (args.geoLocation !== undefined) {
+            opts.geoLocation = args.geoLocation;
+        }
+        if (args.providerType !== undefined) {
+            opts.providerType = args.providerType;
+        }
+        // New provider.
+        if (!args.providerId) {
+            const body = providerToRegisterBody(args.provider, opts);
+            return 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);
+    });
+}

package/lib/paths.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolve the Reclaim cache directory (`~/.reclaim`). Honours the
+ * `RECLAIM_HOME` env var as an override so tests can sandbox writes.
+ */
+export declare function reclaimHomeDirPath(): string;
+/**
+ * Walk up from `start` until we find a directory containing one of
+ * the project-root markers, then return that directory. Falls back
+ * to `start` if no marker is found within 8 levels.
+ */
+export declare function findProjectRoot(start?: string): string;

package/lib/paths.js

@@ -0,0 +1,32 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+/**
+ * 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');
+}
+/**
+ * Walk up from `start` until we find a directory containing one of
+ * the project-root markers, then return that directory. Falls back
+ * to `start` if no marker is found within 8 levels.
+ */
+export function findProjectRoot(start = process.cwd()) {
+    const markers = ['.git', 'package.json', 'pyproject.toml', 'Cargo.toml'];
+    let dir = resolve(start);
+    for (let i = 0; i < 8; i++) {
+        for (const m of markers) {
+            if (existsSync(join(dir, m))) {
+                return dir;
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return start;
+}

package/lib/pkg.d.ts

@@ -0,0 +1,3 @@
+export declare const NAME: string;
+export declare const VERSION: string;
+export declare const DESCRIPTION: string;

package/lib/pkg.js

@@ -0,0 +1,13 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// package.json lives outside `rootDir: src`, so we can't `import` it
+// directly without widening rootDir and corrupting the build output
+// tree. Read it at runtime instead — relative to this module's URL so
+// the path resolves identically in dev (src/pkg.ts) and after build
+// (build/pkg.js), both one level below the package root.
+const PKG_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+const pkg = JSON.parse(readFileSync(PKG_PATH, 'utf8'));
+export const NAME = pkg.name;
+export const VERSION = pkg.version;
+export const DESCRIPTION = pkg.description || '';

package/lib/proof/attestor.d.ts

@@ -0,0 +1,39 @@
+import type { ReclaimProvider } from '../provider/schema.ts';
+export interface AttestorLogEntry {
+    level: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+    msg: string;
+    ctx?: Record<string, unknown>;
+}
+export interface ProofResult {
+    proof: unknown;
+    extractedValue: string;
+    extractedParameters: Record<string, string>;
+    identifier?: string;
+    owner?: string;
+    verified: boolean;
+    error?: string;
+    /** 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` /
+     *  `list_cached_credentials` rather than guessing. */
+    errorKind?: 'missing-owner-key';
+    /** Pino-style log entries captured from the attestor SDK during the
+     *  proof attempt. Full stream on the result; the MCP layer trims it
+     *  for the LLM-visible response and dumps the whole thing to disk
+     *  via `runLogPath`. */
+    attestorLogs?: AttestorLogEntry[];
+    /** The exact `params` object passed to `createClaimOnAttestor` for
+     *  this attempt. Only included on error so the LLM/dev can confirm
+     *  what the attestor actually saw vs what they thought they sent
+     *  (catches mutation bugs / template-substitution surprises). Never
+     *  carries the captured secrets — those live in `secretParams` which
+     *  is not echoed here. */
+    sentParams?: unknown;
+}
+/** 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. */
+export declare function tailLogs(entries: AttestorLogEntry[], n?: number): AttestorLogEntry[];
+/** 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>;

package/lib/proof/attestor.js

@@ -0,0 +1,207 @@
+// src/proof/attestor.ts
+//
+// Adapter over @reclaimprotocol/attestor-core's createClaimOnAttestor.
+//
+// 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 { createClaimOnAttestor, } from '@reclaimprotocol/attestor-core';
+import { resolveOwnerPrivateKey } from "../mcp/tools/credentials/cache.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. */
+export function tailLogs(entries, n = LOG_TAIL_LINES) {
+    if (entries.length <= n) {
+        return entries;
+    }
+    return entries.slice(entries.length - n);
+}
+/** Filter to just warn/error/fatal — for the LLM-visible response on
+ *  successful proofs, where chatty trace/info would just waste context. */
+export function warnsAndErrors(entries) {
+    return entries.filter((e) => e.level === 'warn' || e.level === 'error' || e.level === 'fatal');
+}
+/** How many log entries to keep from the attestor SDK on an error. The
+ *  early ones describe TLS setup; the late ones (right before the
+ *  throw) usually pinpoint the actual failure. Keeping the tail covers
+ *  the latter; the cap stops a chatty session from blowing the LLM's
+ *  context window. */
+const LOG_TAIL_LINES = 80;
+/** Build a pino-compatible capturing logger. Each `trace`/`debug`/…
+ *  call records an entry; `child` returns a derived capturer bound to
+ *  the parent's entries array so nested SDK loggers all flow into one
+ *  ordered list. */
+function makeCaptureLogger() {
+    const entries = [];
+    const make = (baseCtx) => {
+        const log = (level) => (...args) => {
+            if (args.length === 0) {
+                return;
+            }
+            let msg = '';
+            let ctx;
+            if (args[0] instanceof Error) {
+                // pino-style `logger.error(err, 'msg')` — Error objects
+                // don't JSON-serialize on their own, so extract the
+                // useful fields manually.
+                const err = args[0];
+                ctx = {
+                    error: { name: err.name, message: err.message, stack: err.stack },
+                };
+                msg = typeof args[1] === 'string' ? args[1] : err.message;
+            }
+            else if (typeof args[0] === 'string') {
+                msg = args[0];
+            }
+            else if (args[0] && typeof args[0] === 'object') {
+                ctx = args[0];
+                msg = typeof args[1] === 'string' ? args[1] : '';
+            }
+            const merged = Object.keys(baseCtx).length || ctx
+                ? { ...baseCtx, ...(ctx ?? {}) }
+                : undefined;
+            const entry = { level, msg };
+            if (merged) {
+                entry.ctx = merged;
+            }
+            entries.push(entry);
+        };
+        return {
+            trace: log('trace'),
+            debug: log('debug'),
+            info: log('info'),
+            warn: log('warn'),
+            error: log('error'),
+            fatal: log('fatal'),
+            child: (childCtx) => {
+                return make({ ...baseCtx, ...childCtx });
+            },
+        };
+    };
+    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',
+        };
+    }
+    try {
+        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,
+            }),
+        };
+        // 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 capture = traceEnabled ? makeCaptureLogger() : undefined;
+        const attestorLogs = capture?.entries;
+        let claim;
+        try {
+            claim = await createClaimOnAttestor({
+                name: 'http',
+                params,
+                secretParams: {
+                    headers: secrets,
+                },
+                ownerPrivateKey,
+                client: { url: resolveAttestorUrl(attestorUrl) },
+                zkEngine: 'snarkjs',
+                ...(capture !== undefined && { logger: capture.logger }),
+            });
+        }
+        catch (err) {
+            const errorResult = {
+                proof: undefined,
+                extractedValue: '',
+                extractedParameters: {},
+                verified: false,
+                error: err instanceof Error ? err.message : String(err),
+                sentParams: params,
+            };
+            if (attestorLogs !== undefined) {
+                errorResult.attestorLogs = attestorLogs;
+            }
+            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 result = {
+            proof: claim,
+            extractedValue,
+            extractedParameters,
+            verified: true,
+        };
+        const identifier = claimData?.['identifier'];
+        if (typeof identifier === 'string') {
+            result.identifier = identifier;
+        }
+        const owner = claimData?.['owner'];
+        if (typeof owner === 'string') {
+            result.owner = owner;
+        }
+        // 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) {
+            result.attestorLogs = attestorLogs;
+        }
+        return result;
+    }
+    catch (err) {
+        return {
+            proof: undefined,
+            extractedValue: '',
+            extractedParameters: {},
+            verified: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}

package/lib/proof/replay.d.ts

@@ -0,0 +1,8 @@
+import type { ReclaimProvider } from '../provider/schema.ts';
+export interface ReplayResult {
+    status: number;
+    body: string;
+    matchesOriginal: boolean;
+    hints?: string[];
+}
+export declare function replayProvider(provider: ReclaimProvider, secrets: Record<string, string>): Promise<ReplayResult>;

package/lib/proof/replay.js

@@ -0,0 +1,73 @@
+/** Expand `{{name}}` placeholders from `paramValues`. Matches the attestor
+ *  SDK's behavior so replay and proof both hit the same final URL. */
+function expandTemplate(s, params) {
+    if (!params) {
+        return s;
+    }
+    return s.replace(/\{\{([^{}]+)\}\}/g, (match, name) => {
+        const v = params[name];
+        return v !== undefined ? v : match;
+    });
+}
+export async function replayProvider(provider, secrets) {
+    const params = provider.paramValues;
+    const url = expandTemplate(provider.url, params);
+    const expandedHeaders = {};
+    for (const [k, v] of Object.entries(provider.headers ?? {})) {
+        expandedHeaders[k] = expandTemplate(v, params);
+    }
+    const headers = { ...expandedHeaders, ...secrets };
+    const fetchInit = {
+        method: provider.method,
+        headers,
+        redirect: 'manual',
+    };
+    if (provider.body !== undefined) {
+        fetchInit.body = expandTemplate(provider.body, params);
+    }
+    const res = await fetch(url, fetchInit);
+    const body = await res.text();
+    const hints = [];
+    if (res.status === 401 || res.status === 403) {
+        hints.push('auth/permission failed');
+    }
+    if (res.status >= 500) {
+        hints.push('upstream server error');
+    }
+    for (const m of provider.responseMatches) {
+        // The attestor substitutes paramValues into responseMatches.value
+        // at proof time (`{{name}}` → the value, or → the OPRF nullifier
+        // when the matching redaction has `hash`). Replay can't OPRF, but
+        // it can do the plain substitution so a paramValues-templated match
+        // is meaningful here.
+        const expanded = {
+            ...m,
+            value: expandTemplate(m.value, params),
+        };
+        if (!matchesBody(body, expanded)) {
+            if (res.status >= 200 && res.status < 300) {
+                hints.push(`matcher ${expanded.type} did not match — ` +
+                    'value may have changed or matcher is too tight');
+            }
+            const result = {
+                status: res.status,
+                body,
+                matchesOriginal: false,
+            };
+            if (hints.length > 0) {
+                result.hints = hints;
+            }
+            return result;
+        }
+    }
+    return { status: res.status, body, matchesOriginal: res.status < 400 };
+}
+function matchesBody(body, m) {
+    if (m.type === 'regex') {
+        return new RegExp(m.value).test(body);
+    }
+    if (m.type === 'contains') {
+        return body.includes(m.value);
+    }
+    return false;
+}

package/lib/provider/constraints.d.ts

@@ -0,0 +1,2 @@
+import type { CapturedRequest, RequestConcern } from './schema.ts';
+export declare function detectConcerns(req: CapturedRequest): RequestConcern[];

package/lib/provider/constraints.js

@@ -0,0 +1,122 @@
+import { looksLikeGraphqlEndpoint } from "./graphql.js";
+const SIGNATURE_HEADERS = [
+    'x-signature',
+    'x-amz-signature',
+    'x-hub-signature',
+    'x-hmac',
+    'signature',
+    'x-request-signature',
+];
+const CSRF_HEADERS = [
+    'x-csrf-token',
+    'x-xsrf-token',
+    'csrf-token',
+    'xsrf-token',
+];
+export function detectConcerns(req) {
+    const concerns = [];
+    const reqHeadersLower = lowerKeys(req.requestHeaders);
+    const respHeadersLower = lowerKeys(req.responseHeaders);
+    // Signed requests
+    for (const h of SIGNATURE_HEADERS) {
+        if (reqHeadersLower[h]) {
+            concerns.push({
+                code: 'signedRequest',
+                message: `Request includes a "${h}" header — ` +
+                    'providers will break when the signing scheme rotates.',
+            });
+            break;
+        }
+    }
+    // Bot challenge
+    const cfMitigated = respHeadersLower['cf-mitigated'];
+    const server = respHeadersLower['server'] ?? '';
+    if ((req.status === 403 || req.status === 503) &&
+        (cfMitigated === 'challenge' || /cloudflare/i.test(server))) {
+        concerns.push({
+            code: 'botChallenge',
+            message: 'Response looks like a bot-mitigation challenge (Cloudflare). ' +
+                'Capture again after solving the challenge in the browser.',
+        });
+    }
+    // GraphQL
+    if (looksLikeGraphqlEndpoint(req.url)) {
+        concerns.push({
+            code: 'graphql',
+            message: 'Endpoint is GraphQL — ' +
+                'match on operationName + variables, not URL path.',
+        });
+    }
+    // CSRF dependency
+    for (const h of CSRF_HEADERS) {
+        if (reqHeadersLower[h]) {
+            concerns.push({
+                code: 'csrfDependency',
+                message: `Request includes a "${h}" header — ` +
+                    'a prior request fetched this token. ' +
+                    'Replay will fail unless the token is still valid; ' +
+                    'expect to re-capture for proof.',
+            });
+            break;
+        }
+    }
+    // Short-lived token (JWT exp < 30 min from finishedAt)
+    const auth = reqHeadersLower['authorization'];
+    if (auth) {
+        const jwtMatch = auth.match(/^[Bb]earer\s+([A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)/);
+        if (jwtMatch) {
+            const exp = jwtExpSeconds(jwtMatch[1]);
+            const issuedAtMs = req.finishedAt || Date.now();
+            if (exp && exp * 1000 - issuedAtMs < 30 * 60 * 1000) {
+                concerns.push({
+                    code: 'shortLivedToken',
+                    message: 'Authorization is a JWT expiring in under 30 minutes — ' +
+                        'provider may stop working soon. Re-capture closer to proof time.',
+                });
+            }
+        }
+    }
+    // Encrypted / binary body
+    if (looksBinary(req.contentType, req.responseBody)) {
+        concerns.push({
+            code: 'encryptedBody',
+            message: `Response content-type "${req.contentType}" is binary/opaque —` +
+                ' Reclaim providers need plain-text (JSON/HTML) responses.',
+        });
+    }
+    return concerns;
+}
+function lowerKeys(h) {
+    return Object.fromEntries(Object.entries(h).map(([k, v]) => [k.toLowerCase(), v]));
+}
+function jwtExpSeconds(jwt) {
+    const parts = jwt.split('.');
+    if (parts.length !== 3) {
+        return undefined;
+    }
+    try {
+        const decoded = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+        return typeof decoded.exp === 'number' ? decoded.exp : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function looksBinary(contentType, body) {
+    if (!body) {
+        return false;
+    }
+    if (/octet-stream|protobuf|msgpack|cbor/i.test(contentType)) {
+        return true;
+    }
+    // Heuristic: significant control-char density in first 256 bytes.
+    const sample = body.slice(0, 256);
+    let ctrl = 0;
+    for (const ch of sample) {
+        const code = ch.charCodeAt(0);
+        if (code < 9 || (code > 13 && code < 32)) {
+            ctrl++;
+        }
+    }
+    return ctrl / sample.length > 0.1;
+}

package/lib/provider/draft.d.ts

@@ -0,0 +1,6 @@
+import type { CapturedRequest, OprfMode, ReclaimProvider, SecretParamRef } from './schema.ts';
+export interface DraftResult {
+    provider: ReclaimProvider;
+    secretRefs: SecretParamRef[];
+}
+export declare function draftProvider(req: CapturedRequest, target: string, name: string, hash?: OprfMode): DraftResult;