@reclaimprotocol/agent 0.1.0 → 0.1.1

package/src/provider/to-version.ts

@@ -1,8 +1,8 @@
 import type { ReclaimClient } from '@reclaimprotocol/client'
 import type {
-	CreateProviderVersionRequest as CreateVersionBody,
-	ProviderVersionRef as VersionRef,
-} from '../types/openapi.ts'
+	CreateProviderVersionRequest,
+	ProviderVersionRef,
+} from '@reclaimprotocol/client/openapi'
 import type { ReclaimProvider } from './schema.ts'
 
 /**
@@ -16,12 +16,47 @@ import type { ReclaimProvider } from './schema.ts'
  * 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: ReclaimProvider,
+): CreateProviderVersionRequest['requiredContext'] {
+	const haystack = `${provider.url}\n${provider.body ?? ''}`
+	const names = new Set<string>()
+	for(const m of haystack.matchAll(CONTEXT_PARAM_RE)) {
+		names.add(m[1])
+	}
+
+	if(!names.size) {
+		return undefined
+	}
+
+	const properties: Record<string, unknown> = {}
+	for(const name of names) {
+		properties[name] = { type: 'string' }
+	}
+
+	return { type: 'object', required: [...names], properties }
+}
+
 export function providerToCreateVersionRequest(
 	provider: ReclaimProvider,
 	initialUrl: string,
 	notes?: string,
-	version?: VersionRef,
-): CreateVersionBody {
+	version?: ProviderVersionRef,
+): CreateProviderVersionRequest {
+	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]
@@ -46,10 +81,16 @@ export function providerToCreateVersionRequest(
 			},
 		],
 		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 } : {}),
 	}
 }
@@ -63,11 +104,11 @@ export function providerToCreateVersionRequest(
 export async function nextVersion(
 	client: ReclaimClient,
 	providerId: string,
-): Promise<VersionRef> {
+): Promise<ProviderVersionRef> {
 	const list = (await client.call('ListProviderVersions', {
 		params: { providerId },
 		query: {},
-	})) as { items?: Array<{ version: VersionRef }> }
+	})) as { items?: Array<{ version: ProviderVersionRef }> }
 
 	if(!list.items?.length) {
 		return { major: 1, minor: 0, patch: 0 }

package/src/provider/verification-checks.ts

@@ -0,0 +1,36 @@
+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 function verificationWarnings(provider: ReclaimProvider): string[] {
+	const out: string[] = []
+
+	// 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
+}

package/lib/mcp/tools/credentials/build.d.ts

@@ -1,16 +0,0 @@
-import type { ReclaimClient } from '@reclaimprotocol/client';
-import type { RegisteredTool } from '../../server.ts';
-/**
- * Local-only credential tools — no backend client needed. These manage app
- * key-pairs entirely on disk / in the env (mint, import, list, resolve which
- * key to sign proofs with), so they are useful in BOTH builder and
- * OLD-devtools mode.
- */
-export declare function buildLocalCredentialTools(): RegisteredTool[];
-/**
- * Full builder-mode credential set: the local tools plus the two that talk to
- * the builder backend (`reclaim_authenticate` device-code flow,
- * `reclaim_status`). Old mode does NOT use these — it has its own
- * authenticate and no credential-status analog.
- */
-export declare function buildCredentialTools(client: ReclaimClient): RegisteredTool[];

package/lib/mcp/tools/credentials/build.js

@@ -1,33 +0,0 @@
-import { authenticateTool } from "./authenticate.js";
-import { importTool } from "./import.js";
-import { issueTool } from "./issue.js";
-import { listCachedTool } from "./list-cached.js";
-import { resolveOwnerKeyTool } from "./resolve-owner-key.js";
-import { statusTool } from "./status.js";
-/**
- * Local-only credential tools — no backend client needed. These manage app
- * key-pairs entirely on disk / in the env (mint, import, list, resolve which
- * key to sign proofs with), so they are useful in BOTH builder and
- * OLD-devtools mode.
- */
-export function buildLocalCredentialTools() {
-    return [
-        listCachedTool(),
-        resolveOwnerKeyTool(),
-        issueTool(),
-        importTool(),
-    ];
-}
-/**
- * Full builder-mode credential set: the local tools plus the two that talk to
- * the builder backend (`reclaim_authenticate` device-code flow,
- * `reclaim_status`). Old mode does NOT use these — it has its own
- * authenticate and no credential-status analog.
- */
-export function buildCredentialTools(client) {
-    return [
-        authenticateTool(client),
-        statusTool(client),
-        ...buildLocalCredentialTools(),
-    ];
-}

package/lib/mcp/tools/credentials/status.js

@@ -1,62 +0,0 @@
-import { deriveFromPrivateKey, } from '@reclaimprotocol/client';
-import assert from 'node:assert';
-import { findProjectRoot } from "../../../paths.js";
-import { defineTool } from "../../server.js";
-import { suggestCredentialForDir } from "./cache.js";
-export function statusTool(client) {
-    return defineTool({
-        name: 'reclaim_status',
-        description: 'Report the live mode (SANDBOX | PRODUCTION | REVOKED) ' +
-            'of a Reclaim app credential. Pass `address` — or omit it ' +
-            'to derive the address from RECLAIM_PRIVATE_KEY, falling ' +
-            'back to the best cached credential for this directory. ' +
-            'Useful to confirm a credential is linked to an org ' +
-            'with billing before running a production flow.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                address: {
-                    type: 'string',
-                    pattern: '^0x[0-9a-fA-F]{40}$',
-                    description: 'Lowercase ETH address. Defaults to the address ' +
-                        'derived from RECLAIM_PRIVATE_KEY, then the cached ' +
-                        'credential suggested for the current directory.',
-                },
-            },
-        },
-    }, async (args) => {
-        let address = args.address?.toLowerCase();
-        if (!address && process.env.RECLAIM_PRIVATE_KEY) {
-            address = deriveFromPrivateKey(process.env.RECLAIM_PRIVATE_KEY).address;
-        }
-        if (!address) {
-            address = suggestCredentialForDir(findProjectRoot(process.cwd()))
-                ?.credential.address;
-        }
-        assert(address, new Error('No address given, RECLAIM_PRIVATE_KEY is not set, and the ' +
-            'cache is empty. Run issue_credentials or import_credentials ' +
-            'first.'));
-        const credResult = await client
-            .call('GetCredentialByAddress', { params: { address } });
-        const cred = credResult.data;
-        // A registered credential always carries an `id`; its absence means
-        // the server had no row for this address — a local-only credential.
-        const localOnly = !cred.id;
-        return {
-            address: cred.address,
-            mode: cred.mode,
-            orgId: cred.orgId,
-            label: cred.label,
-            revokedAt: cred.revokedAt,
-            lastUsedAt: cred.lastUsedAt,
-            ...(localOnly ? {
-                note: 'Local-only credential — not registered with the server. '
-                    + 'It operates in SANDBOX, which is all you need to publish '
-                    + 'a verification (only an auth token is required — no '
-                    + 'credential link). Linking it to an org with billing (via '
-                    + 'link_credential) is only needed for the upcoming feature '
-                    + 'that runs verifications for your own app’s users.',
-            } : {}),
-        };
-    });
-}

package/src/mcp/tools/credentials/build.ts

@@ -1,37 +0,0 @@
-import type { ReclaimClient } from '@reclaimprotocol/client'
-import type { RegisteredTool } from '../../server.ts'
-import { authenticateTool } from './authenticate.ts'
-import { importTool } from './import.ts'
-import { issueTool } from './issue.ts'
-import { listCachedTool } from './list-cached.ts'
-import { resolveOwnerKeyTool } from './resolve-owner-key.ts'
-import { statusTool } from './status.ts'
-
-/**
- * Local-only credential tools — no backend client needed. These manage app
- * key-pairs entirely on disk / in the env (mint, import, list, resolve which
- * key to sign proofs with), so they are useful in BOTH builder and
- * OLD-devtools mode.
- */
-export function buildLocalCredentialTools(): RegisteredTool[] {
-	return [
-		listCachedTool(),
-		resolveOwnerKeyTool(),
-		issueTool(),
-		importTool(),
-	]
-}
-
-/**
- * Full builder-mode credential set: the local tools plus the two that talk to
- * the builder backend (`reclaim_authenticate` device-code flow,
- * `reclaim_status`). Old mode does NOT use these — it has its own
- * authenticate and no credential-status analog.
- */
-export function buildCredentialTools(client: ReclaimClient): RegisteredTool[] {
-	return [
-		authenticateTool(client),
-		statusTool(client),
-		...buildLocalCredentialTools(),
-	]
-}

package/src/mcp/tools/credentials/cache.ts

@@ -1,161 +0,0 @@
-import { deriveFromPrivateKey } from '@reclaimprotocol/client'
-import { ConfigStore } from '../../../config/store.ts'
-import { findProjectRoot } from '../../../paths.ts'
-import { readPrivateKeyFromEnvFile } from './env-file.ts'
-
-export type CachedCredential = {
-	address: string
-	privateKey: string
-	label?: string
-	orgId?: string
-	createdAt: string
-	/** Project dir where this credential was first created. */
-	createdIn: string
-	/** All project dirs this credential has been used in ("used by"). */
-	projectDirs: string[]
-}
-
-type CacheFile = {
-	version: 1
-	credentials: CachedCredential[]
-}
-
-const EMPTY: CacheFile = { version: 1, credentials: [] }
-
-/**
- * Read the `credentials` section of the unified config. Returns an empty
- * doc if missing or malformed — we'd rather lose the cache than crash the
- * CLI on a corrupted file the user can re-create.
- */
-export function readCredentialsFromCache(): CacheFile {
-	const creds = new ConfigStore().read()?.credentials
-	if(!Array.isArray(creds)) {
-		return { ...EMPTY }
-	}
-
-	return { version: 1, credentials: creds }
-}
-
-/**
- * Persist the `credentials` section, merging into the unified config so
- * other sections (browser_agent, session) survive untouched. We rewrite
- * the whole list each save; it's tiny and the alternative (append-only)
- * loses our ability to deduplicate `projectDirs`.
- */
-export function writeCache(doc: CacheFile) {
-	new ConfigStore().write({ credentials: doc.credentials })
-}
-
-/**
- * Upsert a credential entry. If a row already exists for `address`,
- * we merge the new `projectDirs` into the existing list, refresh
- * mutable fields, and keep the original `createdAt` / `createdIn`
- * (backfilling `createdIn` from the new entry when an old row lacks it).
- */
-export function upsertCredential(entry: CachedCredential) {
-	const doc = readCredentialsFromCache()
-	const idx = doc.credentials.findIndex(
-		(c) => c.address === entry.address.toLowerCase(),
-	)
-	const merged: CachedCredential = {
-		...entry,
-		address: entry.address.toLowerCase(),
-		projectDirs: Array.from(
-			new Set([
-				...(doc.credentials[idx]?.projectDirs ?? []),
-				...entry.projectDirs,
-			]),
-		),
-		createdAt: doc.credentials[idx]?.createdAt ?? entry.createdAt,
-		createdIn: doc.credentials[idx]?.createdIn ?? entry.createdIn,
-	}
-	if(idx >= 0) {
-		doc.credentials[idx] = merged
-	} else {
-		doc.credentials.unshift(merged)
-	}
-
-	writeCache(doc)
-	return merged
-}
-
-/** Look up a cached credential by address. Case-insensitive. */
-export function findCredentialFromCachedBy(
-	address: string
-): CachedCredential | undefined {
-	const doc = readCredentialsFromCache()
-	const lc = address.toLowerCase()
-	return doc.credentials.find((c) => c.address === lc)
-}
-
-export type SuggestionReason = 'createdIn' | 'usedIn' | 'newest'
-
-export type CredentialSuggestion = {
-	credential: CachedCredential
-	reason: SuggestionReason
-}
-
-/**
- * Pick the best cached credential for `dir`. Ranking tiers:
- *   1. created in `dir`           (reason: 'createdIn')
- *   2. previously used in `dir`   (reason: 'usedIn')
- *   3. most recently created      (reason: 'newest')
- * Within every tier, newest `createdAt` wins; address ascending is the
- * final deterministic tie-break. Returns undefined only on an empty cache.
- *
- * Pass a pre-read `creds` array to avoid a redundant `readCache()` (and to
- * rank against the same snapshot the caller already holds).
- */
-export function suggestCredentialForDir(
-	dir: string,
-	creds: CachedCredential[] = readCredentialsFromCache().credentials,
-): CredentialSuggestion | undefined {
-	if(creds.length === 0) {
-		return undefined
-	}
-
-	const byNewest = (a: CachedCredential, b: CachedCredential) => {
-		return (b.createdAt ?? '').localeCompare(a.createdAt ?? '') ||
-			a.address.localeCompare(b.address)
-	}
-
-	const createdHere = creds.filter((c) => c.createdIn === dir).sort(byNewest)
-	if(createdHere[0]) {
-		return { credential: createdHere[0], reason: 'createdIn' }
-	}
-
-	const usedHere = creds
-		.filter((c) => c.projectDirs.includes(dir))
-		.sort(byNewest)
-	if(usedHere[0]) {
-		return { credential: usedHere[0], reason: 'usedIn' }
-	}
-
-	return { credential: [...creds].sort(byNewest)[0], reason: 'newest' }
-}
-
-/**
- * Resolve the private key to sign attestor proofs with (the claim
- * "owner"). Reuses the app credential rather than a dedicated key — for
- * build-time test proofs the developer is both the app and the proof
- * owner, and the owner identity is immaterial to whether the provider's
- * matching works.
- *
- * The owner is chosen up front (see the `resolve_owner_key` tool) and
- * passed by `address`; this just fetches the matching private key:
- *   - the `RECLAIM_PRIVATE_KEY` env / project `.env` key, if it derives
- *     to `address` (the dev pinned it), else
- *   - the cached credential with that address.
- * Returns undefined when no key for `address` is known.
- */
-export function resolveOwnerPrivateKey(address: string): string | undefined {
-	const target = address.toLowerCase()
-	const envKey =
-		process.env.RECLAIM_PRIVATE_KEY ??
-		readPrivateKeyFromEnvFile(findProjectRoot(process.cwd()))
-	if(envKey && deriveFromPrivateKey(envKey).address === target) {
-		return envKey
-	}
-
-	return findCredentialFromCachedBy(target)?.privateKey
-}

package/src/mcp/tools/credentials/env-file.ts

@@ -1,101 +0,0 @@
-import {
-	appendFileSync,
-	chmodSync,
-	existsSync,
-	readFileSync,
-	writeFileSync,
-} from 'node:fs'
-import { join } from 'node:path'
-
-const PRIVATE_KEY = 'RECLAIM_PRIVATE_KEY'
-const GITIGNORE_LINE = '.env'
-
-export type EnvWriteResult = {
-	envPath: string
-	gitignorePath: string
-	gitignoreAppended: boolean
-}
-
-/**
- * Idempotently set `RECLAIM_PRIVATE_KEY` in the project's `.env`, then
- * `chmod 0600` it. The private key is the only secret we write — the
- * ETH address (and public key) are derived from it on demand, so there
- * is no separate address variable to keep in sync. Existing variables
- * are replaced in place; other lines are preserved verbatim so we
- * don't trample on unrelated config the user wrote by hand.
- *
- * Also appends `.env` to the project's `.gitignore` if it isn't
- * already listed.
- */
-export function writeAppCredentialsToEnv(
-	projectDir: string,
-	privateKey: string,
-): EnvWriteResult {
-	const envPath = join(projectDir, '.env')
-	const lines = existsSync(envPath)
-		? readFileSync(envPath, 'utf8').split('\n')
-		: []
-
-	setOrInsert(lines, PRIVATE_KEY, privateKey)
-
-	const body = lines.join('\n').replace(/\n+$/, '') + '\n'
-	writeFileSync(envPath, body, { mode: 0o600 })
-	chmodSync(envPath, 0o600)
-
-	const gitignorePath = join(projectDir, '.gitignore')
-	const gitignoreAppended = ensureLine(gitignorePath, GITIGNORE_LINE)
-
-	return { envPath, gitignorePath, gitignoreAppended }
-}
-
-/**
- * Read `RECLAIM_PRIVATE_KEY` back out of the project's `.env`, if set.
- * Read live (not from `process.env`) so a credential written by
- * `issue_credentials` / `import_credentials` is picked up immediately,
- * without a Claude Code restart. Returns undefined when the file or the
- * variable is absent.
- */
-export function readPrivateKeyFromEnvFile(
-	projectDir: string,
-): string | undefined {
-	const envPath = join(projectDir, '.env')
-	if(!existsSync(envPath)) {
-		return undefined
-	}
-
-	const prefix = `${PRIVATE_KEY}=`
-	const line = readFileSync(envPath, 'utf8')
-		.split('\n')
-		.find((l) => l.startsWith(prefix))
-	const value = line?.slice(prefix.length).trim()
-	return value || undefined
-}
-
-function setOrInsert(lines: string[], key: string, value: string) {
-	const prefix = `${key}=`
-	const idx = lines.findIndex((l) => l.startsWith(prefix))
-	const next = `${key}=${value}`
-	if(idx >= 0) {
-		lines[idx] = next
-		return
-	}
-
-	lines.push(next)
-}
-
-function ensureLine(path: string, line: string): boolean {
-	if(!existsSync(path)) {
-		writeFileSync(path, line + '\n', { mode: 0o644 })
-		return true
-	}
-
-	const body = readFileSync(path, 'utf8')
-	const present = body.split('\n').some((l) => l.trim() === line)
-	if(present) {
-		return false
-	}
-
-	const suffix = body.endsWith('\n') ? '' : '\n'
-	appendFileSync(path, suffix + line + '\n')
-	return true
-}

package/src/mcp/tools/credentials/import.ts

@@ -1,72 +0,0 @@
-import { deriveFromPrivateKey } from '@reclaimprotocol/client'
-import { findProjectRoot } from '../../../paths.ts'
-import { defineTool, type RegisteredTool } from '../../server.ts'
-import { persistCredentialLocally } from './register.ts'
-
-export function importTool(): RegisteredTool {
-	return defineTool<{
-		privateKey: string
-		label?: string
-		projectDir?: string
-		writeEnv?: boolean
-	}>(
-		{
-			name: 'import_credentials',
-			description:
-				'Import an existing Reclaim app credential the user ' +
-				'already holds elsewhere. Provide the private key ' +
-				'(0x-prefixed hex, 64 chars); we derive the address ' +
-				'locally and cache it. By default also writes ' +
-				'RECLAIM_PRIVATE_KEY to the project .env (0600) and appends ' +
-				'.env to .gitignore; pass `writeEnv: false` to keep it in ' +
-				'the local cache (memory) only and leave .env untouched. ' +
-				'ALWAYS ask the dev whether to save to .env before writing. ' +
-				'The credential stays local-only (SANDBOX); link it to an ' +
-				'org to use it in production.',
-			inputSchema: {
-				type: 'object',
-				properties: {
-					privateKey: {
-						type: 'string',
-						pattern: '^0x[0-9a-fA-F]{64}$',
-						description:
-							'0x-prefixed hex private key (64 hex chars / 32 bytes).',
-					},
-					label: {
-						type: 'string',
-						minLength: 1,
-						maxLength: 100,
-					},
-					projectDir: {
-						type: 'string',
-						description:
-							'Project directory to write .env into. Defaults ' +
-							'to the closest ancestor of cwd containing ' +
-							'.git or package.json.',
-					},
-					writeEnv: {
-						type: 'boolean',
-						description:
-							'Write RECLAIM_PRIVATE_KEY to the project .env ' +
-							'(default true). Set false to cache in memory only, ' +
-							'without touching .env.',
-					},
-				},
-				required: ['privateKey'],
-			},
-		},
-		async(args) => {
-			const keypair = deriveFromPrivateKey(args.privateKey)
-			const projectDir = findProjectRoot(args.projectDir || process.cwd())
-
-			const persisted = persistCredentialLocally(
-				keypair,
-				args.label,
-				projectDir,
-				args.writeEnv ?? true,
-			)
-
-			return { ...persisted }
-		},
-	)
-}