@reclaimprotocol/agent 0.1.1-dev.1 → 0.1.2

package/src/provider/schema.ts

@@ -69,6 +69,29 @@ export interface ReclaimProvider {
 	responseRedactions?: ResponseRedaction[]
 	/** Public param refs (templated into URL/body), populated by draft layer. */
 	paramValues?: Record<string, string>
+	/** Redaction mode for the transcript (attestor default: 'key-update'). */
+	writeRedactionMode?: HttpParams['writeRedactionMode']
+	/** TLS client options applied to the attestor tunnel. */
+	additionalClientOptions?: HttpParams['additionalClientOptions']
+	/** Proxy egress: 2-letter ISO country or `{{param}}`. Blank/omitted ⇒
+	 *  `{{DYNAMIC_GEO}}` on publish (resolved to the verifying user's country).
+	 */
+	geoLocation?: HttpParams['geoLocation']
+}
+
+/** Egress placeholder resolved to the verifying user's country at
+ *  verification time — the default when a provider declares no explicit egress.
+ */
+export const DYNAMIC_GEO = '{{DYNAMIC_GEO}}'
+
+/** `geoLocation` must never be blank. Trims the input and treats an empty
+ *  string as unset so callers apply their own default (publish → `DYNAMIC_GEO`;
+ *  a local proof omits it and uses the tester's egress). */
+export function normalizeGeoLocation(
+	value: string | undefined,
+): string | undefined {
+	const trimmed = value?.trim()
+	return trimmed ? trimmed : undefined
 }
 
 /** A reference to a secret param. Raw value lives only in server memory. */

package/src/provider/to-version.ts

@@ -1,9 +1,53 @@
 import type { ReclaimClient } from '@reclaimprotocol/client'
 import type {
-	CreateProviderVersionRequest as CreateVersionBody,
-	ProviderVersionRef as VersionRef,
-} from '../types/openapi.ts'
-import type { ReclaimProvider } from './schema.ts'
+	CreateProviderVersionRequest,
+	ProviderVersionRef,
+} from '@reclaimprotocol/client/openapi'
+import type {
+	HttpMethod,
+	ReclaimProvider,
+	ResponseMatch,
+	ResponseRedaction,
+} from './schema.ts'
+import { DYNAMIC_GEO, normalizeGeoLocation } from './schema.ts'
+
+/** One entry of the version's `requests[]` (a `RequestSelection`), derived
+ *  from the openapi type so it can't drift from what the server accepts. */
+type RequestSelection = CreateProviderVersionRequest['requests'][number]
+
+/** The subset of a draft a request selection is built from — the only fields
+ *  `providerToRequestSelection` reads. A full `ReclaimProvider` satisfies it,
+ *  as does a lighter injected-request draft (no `name`/`paramValues`). */
+export interface DraftRequest {
+	url: string
+	method: HttpMethod
+	body?: string
+	writeRedactionMode?: ReclaimProvider['writeRedactionMode']
+	additionalClientOptions?: ReclaimProvider['additionalClientOptions']
+	responseMatches?: ResponseMatch[]
+	responseRedactions?: ResponseRedaction[]
+}
+
+/** A request the page's injection script is allowed to fire, plus the
+ *  pagination/optionality flags of `RequestSelectionTemplate`. Reuses the
+ *  shared `DraftRequest` shape — no provider `name`/`paramValues` required. */
+export interface AllowedJsRequest extends DraftRequest {
+	/** Allow the template to match many requests (e.g. pagination). Default
+	 *  true. */
+	multiple?: boolean
+	/** Fail validation if no request matches this template. Default true. */
+	required?: boolean
+}
+
+/** Optional extras for a create-version body beyond the request list. */
+export interface CreateVersionOptions {
+	notes?: string
+	version?: ProviderVersionRef
+	/** JS injected before every page load (`webSettings.jsUserScripts`). */
+	jsUserScripts?: string
+	/** Requests the injection script may fire, as `RequestSelectionTemplate`s. */
+	allowedJsRequests?: AllowedJsRequest[]
+}
 
 /**
  * Translate a drafted ReclaimProvider into the body for
@@ -16,40 +60,143 @@ 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 across EVERY request's url/body (plus any
+ * injected requests and the injection script) — mechanical, so a published
+ * recipe can never reference a context value the Builder doesn't require.
+ * Returns undefined when nothing references context (the field is optional).
+ * Authors can refine types/descriptions in the version editor.
+ */
+export function deriveRequiredContext(
+	providers: ReclaimProvider[],
+	injection: {
+		allowedJsRequests?: AllowedJsRequest[]
+		jsUserScripts?: string
+	} = {},
+): CreateProviderVersionRequest['requiredContext'] {
+	const parts: string[] = []
+	for(const p of [...providers, ...(injection.allowedJsRequests ?? [])]) {
+		parts.push(p.url, p.body ?? '')
+	}
+
+	if(injection.jsUserScripts) {
+		parts.push(injection.jsUserScripts)
+	}
+
+	const haystack = parts.join('\n')
+	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 }
+}
+
+/**
+ * Translate one drafted request into a `RequestSelection`. Shared by the
+ * top-level `requests` and by `allowedJsRequests`.
+ *
+ * `responseMatches`/`responseRedactions` are INDEPENDENT parallel arrays,
+ * isomorphic to the attestor's `ProviderParams<'http'>` (no nested fold).
+ * `responseRedactions` decide which portions of the response are revealed;
+ * `responseMatches` then run against the union of the revealed content. Neither
+ * depends on the other's length or order, so both pass through untouched.
+ * (The old-devtools translator has its own opt-in index-pairing concern; the
+ * builder deliberately does not.)
+ */
+export function providerToRequestSelection(
+	provider: DraftRequest,
+): RequestSelection {
+	const responseMatches = (provider.responseMatches ?? []).map((match) => ({
+		type: match.type,
+		value: match.value,
+		isOptional: false,
+	}))
+	const responseRedactions = provider.responseRedactions ?? []
+
+	return {
+		url: provider.url,
+		method: provider.method,
+		credentials: 'include',
+		...(provider.body ? { requestBodyTemplate: provider.body } : {}),
+		...(provider.writeRedactionMode
+			? { writeRedactionMode: provider.writeRedactionMode }
+			: {}),
+		...(provider.additionalClientOptions
+			? { additionalClientOptions: provider.additionalClientOptions }
+			: {}),
+		...(responseMatches.length > 0 ? { responseMatches } : {}),
+		...(responseRedactions.length > 0 ? { responseRedactions } : {}),
+	}
+}
+
+/** First provider that declares an explicit (non-default) egress wins; if none
+ *  do, fall back to DYNAMIC_GEO (resolved to the verifying user's country). */
+function pickGeoLocation(providers: ReclaimProvider[]): string {
+	for(const provider of providers) {
+		const geo = normalizeGeoLocation(provider.geoLocation)
+		if(geo) {
+			return geo
+		}
+	}
+
+	return DYNAMIC_GEO
+}
+
 export function providerToCreateVersionRequest(
-	provider: ReclaimProvider,
+	providers: ReclaimProvider[],
 	initialUrl: string,
-	notes?: string,
-	version?: VersionRef,
-): CreateVersionBody {
-	// Inline responseRedactions into matches[*].extract (1-to-1 by index).
-	const matches = (provider.responseMatches ?? []).map((match, i) => {
-		const redaction = provider.responseRedactions?.[i]
-		return {
-			type: match.type,
-			value: match.value,
-			isOptional: false,
-			...(redaction ? { extract: redaction } : {}),
-		}
+	opts: CreateVersionOptions = {},
+): CreateProviderVersionRequest {
+	const { notes, version, jsUserScripts, allowedJsRequests } = opts
+	const requiredContext = deriveRequiredContext(providers, {
+		allowedJsRequests,
+		jsUserScripts,
 	})
 
+	// Each injected request carries its template flags (default true/true per
+	// RequestSelectionTemplate) on top of the shared request shape.
+	const allowedJs = (allowedJsRequests ?? []).map((req) => ({
+		...providerToRequestSelection(req),
+		multiple: req.multiple ?? true,
+		required: req.required ?? true,
+	}))
+	const script = jsUserScripts?.trim()
+
 	return {
 		version: version ?? { major: 1, minor: 0, patch: 0 },
 		initialUrl,
-		requests: [
-			{
-				url: provider.url,
-				method: provider.method,
-				credentials: 'include',
-				...(provider.body ? { requestBodyTemplate: provider.body } : {}),
-				...(matches.length > 0 ? { matches } : {}),
-			},
-		],
-		allowedJsRequests: [],
-		webSettings: { geoLocation: '{{DYNAMIC_GEO}}' },
-		...(provider.paramValues
-			? { requiredParameters: provider.paramValues }
-			: {}),
+		// Every drafted provider becomes one request — the recipe runs them all.
+		requests: providers.map(providerToRequestSelection),
+		allowedJsRequests: allowedJs,
+		// Mirror the builder openapi defaults explicitly — the server does not
+		// apply schema defaults to request bodies.
+		webSettings: {
+			geoLocation: pickGeoLocation(providers),
+			clientOptions: { portal: { useProxy: true } },
+			// Only set when non-empty; an empty string would store a no-op script.
+			...(script ? { jsUserScripts: script } : {}),
+		},
+		// 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 +210,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
-}