@reclaimprotocol/agent 0.1.0 → 0.1.1

package/src/mcp/api/to-zod.ts

@@ -0,0 +1,115 @@
+import { z } from 'zod'
+import type { JSONSchema } from 'zod/v4/core'
+
+/**
+ * JSON Schema → zod for the generated MCP tool inputs.
+ *
+ * The generator (`packages/app/scripts/mcp-tools-gen.ts`) inlines `$ref`s it
+ * walks through `properties`/`items`, but it does NOT recurse into `allOf` /
+ * `anyOf` / `oneOf`. So a schema composed with `allOf` (e.g.
+ * `RequestSelectionTemplate =
+ * allOf[ RequestSelection, { multiple, required } ]`,
+ * surfaced by the proof tools' `allowedJsRequests`) can carry a dangling
+ * `#/components/schemas/…` `$ref` that points outside the standalone schema
+ * object handed to `z.fromJSONSchema`. zod then throws `Reference not found`
+ * at module-load time, taking down every tool.
+ *
+ * We pre-process here (rather than hand-editing the generated file, which
+ * regen would clobber): flatten `allOf` compositions into a single object
+ * schema and neutralize any remaining unresolvable `#/components/schemas/…`
+ * `$ref` to a permissive `{}`. The schemas affected are deep proof-tool inputs
+ * the model rarely hand-builds, so loosening leaf validation there is
+ * acceptable; the common tool inputs (uuids, version patterns, contexts) keep
+ * their full constraints.
+ */
+export function toZod(schema: JSONSchema.Schema) {
+	return z.fromJSONSchema(sanitize(schema) as JSONSchema.Schema)
+}
+
+type AnySchema = Record<string, unknown>
+
+/** True for a `$ref` that can't be resolved in a standalone schema object. */
+function isDanglingComponentRef(node: AnySchema): boolean {
+	return (
+		typeof node.$ref === 'string' &&
+		(node.$ref).startsWith('#/components/')
+	)
+}
+
+/**
+ * Recursively (a) merge `allOf` members into their parent so composition
+ * resolves locally, and (b) replace any dangling `#/components/…` `$ref` with
+ * a permissive empty schema. Pure — returns a fresh tree, never mutates input.
+ */
+function sanitize(input: unknown): unknown {
+	if(Array.isArray(input)) {
+		return input.map(sanitize)
+	}
+
+	if(input === null || typeof input !== 'object') {
+		return input
+	}
+
+	const node = input as AnySchema
+
+	if(isDanglingComponentRef(node)) {
+		// Drop the ref; keep any sibling keys (rare) sanitized.
+		const { $ref: _ref, ...rest } = node
+		void _ref
+		return sanitizeEntries(rest)
+	}
+
+	// Flatten allOf into the parent object. Each member is sanitized first so
+	// its own refs/allOf collapse; object members merge their `properties`,
+	// `required`, and scalar keys upward.
+	if(Array.isArray(node.allOf)) {
+		const { allOf, ...rest } = node
+		let merged: AnySchema = sanitizeEntries(rest)
+		for(const member of allOf as unknown[]) {
+			merged = mergeObjectSchemas(merged, sanitize(member) as AnySchema)
+		}
+
+		return merged
+	}
+
+	return sanitizeEntries(node)
+}
+
+/** Sanitize every value of an object schema's keys. */
+function sanitizeEntries(node: AnySchema): AnySchema {
+	const out: AnySchema = {}
+	for(const [k, v] of Object.entries(node)) {
+		out[k] = sanitize(v)
+	}
+
+	return out
+}
+
+/**
+ * Merge two (already-sanitized) object schemas for `allOf` flattening: union
+ * `properties`, union `required`, and let later members win on scalar keys.
+ * Both sides are expected to be object-shaped; non-object members fall back to
+ * a plain key spread (the rare case).
+ */
+function mergeObjectSchemas(a: AnySchema, b: AnySchema): AnySchema {
+	const out: AnySchema = { ...a, ...b }
+
+	const aProps = a.properties as AnySchema | undefined
+	const bProps = b.properties as AnySchema | undefined
+	if(aProps || bProps) {
+		out.properties = { ...aProps, ...bProps }
+	}
+
+	const aReq = Array.isArray(a.required) ? (a.required as string[]) : []
+	const bReq = Array.isArray(b.required) ? (b.required as string[]) : []
+	if(aReq.length || bReq.length) {
+		out.required = Array.from(new Set([...aReq, ...bReq]))
+	}
+
+	// `type` should stay `object` after merging two object schemas.
+	if(a.type === 'object' || b.type === 'object' || out.properties) {
+		out.type = 'object'
+	}
+
+	return out
+}

package/src/mcp/api/tools.ts

@@ -1,7 +1,10 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import type {
-	IOperationArgs, IOperationId, ReclaimClient
+	ReclaimClient
 } from '@reclaimprotocol/client'
+import type {
+	IOperationArgs, IOperationId
+} from '@reclaimprotocol/client/openapi'
 import { remapErrorAsResponse } from '../remap_errors.ts'
 import { MCP_TOOLS } from './operations.gen.ts'
 
@@ -28,9 +31,12 @@ export function registerTools(server: McpServer, client: ReclaimClient) {
 		server.registerTool(
 			toSnakeCase(opId),
 			shape,
-			async(args: IOperationArgs<IOperationId>) => {
+			async(args: unknown) => {
 				try {
-					const result = (await client.call(opId as IOperationId, args))
+					const result = await client.call(
+						opId as IOperationId,
+						args as IOperationArgs<IOperationId>,
+					)
 					return {
 						content: [{
 							type: 'text' as const, text: JSON.stringify(result.data, null, 2)

package/src/mcp/instructions.ts

@@ -0,0 +1,15 @@
+/**
+ * MCP server instructions shown to the LLM when running in BUILDER mode
+ * (`USE_OLD_DEVTOOLS=false`). The prose lives in `skill/builder-mode.md`
+ * (published via the `files` array) so it can be edited as markdown without
+ * touching code. The path resolves identically from `src/mcp` (dev) and
+ * `lib/mcp` (published) — both are two levels below the package root.
+ * Old-devtools mode has its own reduced set in `../old/instructions.ts`.
+ */
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+export const BUILDER_MODE_INSTRUCTIONS = readFileSync(
+	fileURLToPath(new URL('../../skill/builder-mode.md', import.meta.url)),
+	'utf8',
+).trim()

package/src/mcp/server.ts

@@ -6,13 +6,14 @@ import {
 	CallToolRequestSchema,
 	ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js'
-import { convertJsonSchemaToZod, type JSONSchema } from 'zod-from-json-schema'
+import type { JSONSchema } from 'zod/v4/core'
+import { toZod } from './api/to-zod.ts'
 import { remapErrorAsResponse } from './remap_errors.ts'
 
 export interface ToolDefinition {
 	name: string
 	description: string
-	inputSchema: JSONSchema
+	inputSchema: JSONSchema.ObjectSchema
 }
 
 export interface RegisteredTool {
@@ -38,7 +39,7 @@ export function defineTool<TArgs>(
 	definition: ToolDefinition,
 	handler: (args: TArgs) => Promise<unknown>,
 ): RegisteredTool {
-	const schema = convertJsonSchemaToZod(definition.inputSchema)
+	const schema = toZod(definition.inputSchema)
 	return {
 		definition,
 		handler: async(raw) => {
@@ -59,7 +60,7 @@ export function registerToolList(server: McpServer, tools: RegisteredTool[]) {
 			tool.definition.name,
 			{
 				description: tool.definition.description,
-				inputSchema: convertJsonSchemaToZod(tool.definition.inputSchema),
+				inputSchema: toZod(tool.definition.inputSchema),
 			},
 			async(args) => {
 				try {

package/src/mcp/start.ts

@@ -8,12 +8,14 @@ import { OLD_MODE_INSTRUCTIONS } from '../old/instructions.ts'
 import { buildOldBackendTools } from '../old/tools/build.ts'
 import { NAME, VERSION } from '../pkg.ts'
 import { registerTools } from './api/tools.ts'
-import { buildAgentTools } from './tools/agent/build.ts'
 import {
+	buildAgentTools,
 	buildCredentialTools,
 	buildLocalCredentialTools,
-} from './tools/credentials/build.ts'
-import { readSession } from './tools/credentials/session-cache.ts'
+	buildVerificationTools,
+	readSession,
+} from './tools/index.ts'
+import { BUILDER_MODE_INSTRUCTIONS } from './instructions.ts'
 import { registerToolList } from './server.ts'
 
 export async function startMcpServer() {
@@ -21,7 +23,11 @@ export async function startMcpServer() {
 
 	const server = new McpServer(
 		{ name: NAME, version: VERSION },
-		oldMode ? { instructions: OLD_MODE_INSTRUCTIONS } : undefined,
+		{
+			instructions: oldMode
+				? OLD_MODE_INSTRUCTIONS
+				: BUILDER_MODE_INSTRUCTIONS,
+		},
 	)
 
 	// Agent tools (Chrome CDP capture, provider synthesis, replay, proof) are
@@ -64,6 +70,10 @@ export async function startMcpServer() {
 		// Register credential tools for ETH credential management.
 		registerToolList(server, buildCredentialTools(client))
 
+		// Higher-level verification orchestrations (e.g. fetch + decrypt result).
+		// Authenticates with RECLAIM_ORG_SECRET, not the session client.
+		registerToolList(server, buildVerificationTools())
+
 		// Add auto-generated tools with snake_case wrappers
 		// for every MCP-tagged operation.
 		registerTools(server, client)

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

@@ -13,9 +13,8 @@
  */
 
 import type { ReclaimClient } from '@reclaimprotocol/client'
-import { setCryptoImplementation } from '@reclaimprotocol/tls'
-import { webcryptoCrypto } from '@reclaimprotocol/tls/webcrypto'
 import { ConfigStore } from '../../../config/store.ts'
+import { ensureAttestorCrypto } from '../../../proof/proof-core.ts'
 import { type RegisteredTool } from '../../server.ts'
 import { analyzeTool } from './analyze.ts'
 import { type AttachState, attachTool } from './attach.ts'
@@ -38,21 +37,6 @@ export interface AgentState {
 	secrets: SecretStore
 }
 
-let cryptoInitialized = false
-
-/** One-time crypto backend init for @reclaimprotocol/tls. The package
- *  ships with an empty `crypto = {}` and defers backend choice to the
- *  caller; without this, the first proof call dies inside the SDK with
- *  `crypto.randomBytes is not a function`. */
-function ensureCryptoInit() {
-	if(cryptoInitialized) {
-		return
-	}
-
-	setCryptoImplementation(webcryptoCrypto)
-	cryptoInitialized = true
-}
-
 function buildAgentState(): AgentState {
 	return {
 		attach: { config: new ConfigStore() },
@@ -70,7 +54,7 @@ export function buildAgentTools(
 	client?: ReclaimClient,
 ): RegisteredTool[] {
 	const state = buildAgentState()
-	ensureCryptoInit()
+	ensureAttestorCrypto()
 	const tools: RegisteredTool[] = []
 	tools.push(attachTool(state.attach))
 	for(const t of captureTools(state.attach, state.captures)) {

package/src/mcp/tools/agent/index.ts

@@ -0,0 +1,4 @@
+// Barrel for the agent tool group (Chrome CDP capture, provider synthesis,
+// replay, zkTLS proof). Import from here, not the individual files.
+export { buildAgentTools } from './build.ts'
+export type { AgentState } from './build.ts'

package/src/mcp/tools/agent/proof.ts

@@ -135,11 +135,6 @@ export function proofTool(secrets: SecretStore): RegisteredTool {
 			inputSchema: {
 				type: 'object',
 				properties: {
-					// `type: 'object'` is required so MCP clients (the LLM)
-					// serialize the value as an object, not a JSON-stringified
-					// string. `properties: {}` is required so zod-from-json-schema
-					// compiles to a passthrough instead of strict-strip — leaving
-					// it off makes the server receive `{}`.
 					provider: { type: 'object', properties: {} },
 					secretParamsRef: { type: 'string' },
 					attestorUrl: { type: 'string' },
@@ -173,8 +168,7 @@ export function proofTool(secrets: SecretStore): RegisteredTool {
 			const result = await runAttestorProof(
 				provider as ReclaimProvider,
 				resolved,
-				attestorUrl,
-				ownerAddress,
+				{ attestorUrl, ownerAddress },
 			)
 
 			// Persist the full claim to disk for the dev to inspect/share.

package/src/mcp/tools/agent/propose.ts

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto'
 import { draftProvider } from '../../../provider/draft.ts'
 import { OPRF_MAX_BYTES } from '../../../provider/matcher.ts'
 import type { OprfMode } from '../../../provider/schema.ts'
+import { verificationWarnings } from '../../../provider/verification-checks.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import type { CaptureStore } from './capture.ts'
 
@@ -48,7 +49,11 @@ export function proposeTool(
 				'cleartext. Skill should ask the dev first. `oprf-raw` ' +
 				'is the only variant that runs ' +
 				'without external deps; `oprf` needs gnark (Linux/macOS), ' +
-				'`oprf-mpc` needs a TEE attestor.',
+				'`oprf-mpc` needs a TEE attestor. ' +
+				'The response may include `verificationWarnings` — advisory ' +
+				'author-only decisions (e.g. a user-specific URL part needing ' +
+				'the {{context.<name>}}-vs-bare call). Surface each to the ' +
+				'dev verbatim and resolve before publishing.',
 			inputSchema: {
 				type: 'object',
 				properties: {
@@ -105,7 +110,13 @@ export function proposeTool(
 			}
 
 			const secretParamsRef = secrets.put(realSecrets)
-			return { provider, secretRefs, secretParamsRef }
+			const warnings = verificationWarnings(provider)
+			return {
+				provider,
+				secretRefs,
+				secretParamsRef,
+				...(warnings.length ? { verificationWarnings: warnings } : {}),
+			}
 		},
 	)
 }

package/src/mcp/tools/agent/publish.ts

@@ -26,8 +26,16 @@ export function createVersionFromCaptureTool(
 				'hand-construct that shape or call create_provider_version directly. ' +
 				'Omit `version` to have the tool auto-select the next available ' +
 				'version (it lists existing versions and bumps past the highest). ' +
-				'For PRIVATE verifications the version goes live immediately; ' +
-				'for PUBLIC ones call submit_provider_version_for_review afterwards.',
+				'The version lands on the draft branch — to go live, call ' +
+				'`publish_provider_version` (PRIVATE) or ' +
+				'`submit_provider_version_for_review` (PUBLIC) afterwards. ' +
+				'`requiredContext` is derived from any {{context.<name>}} ' +
+				'placeholders and returned on the created version — when ' +
+				'present, tell the dev verbatim which context fields consumers ' +
+				'MUST send when creating sessions (verification matches those ' +
+				'values exactly; a missing field is a 400 at session create). ' +
+				'Refine types/descriptions via `update_provider_version` while ' +
+				'still on draft.',
 			inputSchema: {
 				type: 'object',
 				properties: {

package/src/mcp/tools/agent/replay.ts

@@ -16,11 +16,6 @@ export function replayTool(secrets: SecretStore): RegisteredTool {
 			inputSchema: {
 				type: 'object',
 				properties: {
-					// `type: 'object'` is required so MCP clients (the LLM)
-					// serialize the value as an object, not a JSON-stringified
-					// string. `properties: {}` is required so zod-from-json-schema
-					// compiles to a passthrough instead of strict-strip — leaving
-					// it off makes the server receive `{}`.
 					provider: { type: 'object', properties: {} },
 					secretParamsRef: { type: 'string' },
 				},

package/src/mcp/tools/{credentials → authenticate}/authenticate.ts

@@ -1,7 +1,7 @@
 import type { ReclaimClient } from '@reclaimprotocol/client'
 import type {
-	CredentialAttachSession as Session
-} from '../../../types/openapi.ts'
+	CredentialAttachSession
+} from '@reclaimprotocol/client/openapi'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import { writeSession } from './session-cache.ts'
 
@@ -21,10 +21,9 @@ export function authenticateTool(client: ReclaimClient): RegisteredTool {
 				'Returns `LINKED` with a 2-day bearer token when confirmed, ' +
 				'`PENDING` if not yet, or `EXPIRED` if too long has passed.\n\n' +
 				'The token is cached in ~/.reclaim/config.json automatically.\n\n' +
-				'To then link a credential to an org (needed only to use it ' +
-				'for verification in production), use the token with the ' +
-				'generated tools: `list_orgs` → `link_credential` with the ' +
-				"credential's `address` and the target `orgId`.",
+				'This bearer token authenticates dashboard/org-management calls ' +
+				'(e.g. list_orgs, issuing an org secret). Programmatic verification ' +
+				'calls use a separate org secret (rorg_…, set as RECLAIM_ORG_SECRET).',
 			inputSchema: {
 				type: 'object',
 				properties: {
@@ -68,7 +67,7 @@ async function checkSession(
 	client: ReclaimClient,
 	code: string,
 ): Promise<unknown> {
-	let session: Session
+	let session: CredentialAttachSession
 	try {
 		const sessionResult = (await client.call('GetAttachSession', {
 			params: { code }
@@ -93,7 +92,9 @@ async function checkSession(
 		if(token) {
 			writeSession({
 				token,
-				expiresAt: new Date(Date.now() + 2 * 24 * 60 * 60 * 1000).toISOString(),
+				expiresAt: new Date(
+					Date.now() + 2 * 24 * 60 * 60 * 1000
+				).toISOString(),
 			})
 			client.setToken(token)
 			return {

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

@@ -0,0 +1,32 @@
+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 { resolveOwnerKeyTool } from './resolve-owner-key.ts'
+
+/**
+ * Local-only key tools — no backend client needed. These manage the eth
+ * proof-owner key entirely on disk (as a secp256k1 PEM) or via env: generate,
+ * import, and resolve which key to sign proofs with. No `~/.reclaim` caching;
+ * useful in BOTH builder and OLD-devtools mode.
+ */
+export function buildLocalCredentialTools(): RegisteredTool[] {
+	return [
+		resolveOwnerKeyTool(),
+		issueTool(),
+		importTool(),
+	]
+}
+
+/**
+ * Full builder-mode credential set: the local key tools plus the backend
+ * `reclaim_authenticate` device-code flow. Old mode does NOT use the
+ * authenticate tool — it has its own.
+ */
+export function buildCredentialTools(client: ReclaimClient): RegisteredTool[] {
+	return [
+		authenticateTool(client),
+		...buildLocalCredentialTools(),
+	]
+}

package/src/mcp/tools/authenticate/decrypt-key.ts

@@ -0,0 +1,64 @@
+/**
+ * Optional X25519 decryption key — only needed when testing ENCRYPTED callback
+ * payloads in the consumer role. Resolution is file-only (no env var, no path
+ * override, no `~/.reclaim` caching):
+ *
+ *   1. An X25519 PKCS#8 PEM file named `reclaim-decrypt.pem` in the project
+ *      root. Mint it with openssl:
+ *
+ *        openssl genpkey -algorithm X25519 -out reclaim-decrypt.pem
+ *
+ *   2. Absent — plaintext-only testing (no decryption key; encrypted
+ *      deliveries surface a clear error).
+ *
+ * The PEM *content* is loaded via the client's `loadDecryptionKey` (jose
+ * `ECDH-ES`) and passed straight through as `ReclaimConfig.credential` / to
+ * `decryptCallback`.
+ */
+import {
+	type DecryptionKey,
+	loadDecryptionKey,
+} from '@reclaimprotocol/client'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { findProjectRoot } from '../../../paths.ts'
+
+/** Default X25519 PEM filename the agent looks for in the project root. */
+export const DEFAULT_DECRYPT_PEM = 'reclaim-decrypt.pem'
+
+/** Resolve the decrypt-PEM path (the default file in the project root). */
+export function decryptPemPath(
+	projectDir = findProjectRoot(process.cwd()),
+): string {
+	return join(projectDir, DEFAULT_DECRYPT_PEM)
+}
+
+/**
+ * Read the raw decryption-key PEM string from the default file, without loading
+ * it. Returns `undefined` when the file is absent (plaintext-only).
+ */
+export function resolveDecryptKeyInput(
+	projectDir = findProjectRoot(process.cwd()),
+): string | undefined {
+	const pemPath = decryptPemPath(projectDir)
+	if(existsSync(pemPath)) {
+		return readFileSync(pemPath, 'utf8')
+	}
+
+	return undefined
+}
+
+/**
+ * Load the optional decryption key. Returns `undefined` when the PEM file is
+ * absent (the consumer then handles only plaintext deliveries).
+ */
+export async function resolveDecryptionKey(
+	projectDir = findProjectRoot(process.cwd()),
+): Promise<DecryptionKey | undefined> {
+	const input = resolveDecryptKeyInput(projectDir)
+	if(input === undefined) {
+		return undefined
+	}
+
+	return loadDecryptionKey(input)
+}