@reclaimprotocol/agent 0.1.1 → 0.1.2

package/src/mcp/tools/verification/result.ts

@@ -2,10 +2,10 @@ import {
 	createReclaim,
 	decryptCallback,
 	type DecryptionKey,
-	DEFAULT_BASE_URL,
 	verifyResultFull,
 } from '@reclaimprotocol/client'
 import assert from 'node:assert'
+import { apiUrl, orgSecret } from '../../../consts.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 import { resolveDecryptionKey } from '../authenticate/decrypt-key.ts'
 
@@ -19,7 +19,7 @@ const TERMINAL = new Set(['success', 'rejected', 'error'])
  * `RECLAIM_ORG_SECRET`.
  */
 function resolveOrgSecret(): string {
-	const secret = process.env.RECLAIM_ORG_SECRET?.trim()
+	const secret = orgSecret()?.trim()
 	assert(
 		secret,
 		new Error(
@@ -35,11 +35,10 @@ function resolveOrgSecret(): string {
  * `get_verification_result` — check a session's status and, once a result has
  * been submitted, pull the stored payload(s) and verify locally. Auth is the
  * org token; delivery is org-scoped. Each stored payload is either the
- * plaintext signed JWS (when the org has no encryption credential) or a compact
- * JWE (RFC 7516, ECDH-ES+A256GCM over X25519) that we decrypt here with the
- * optional X25519 key (the `reclaim-decrypt.pem` PEM in the project). The
- * Builder only ever relays the payload — decryption, when needed, happens
- * here.
+ * plaintext signed JWS (when the org's encryption is off) or an ECIES
+ * ciphertext that we decrypt here with the optional eth key
+ * (`RECLAIM_DECRYPT_KEY` or the `reclaim-decrypt.key` hex file). The Builder
+ * only ever relays the payload — decryption, when needed, happens here.
  */
 export function verificationResultTool(): RegisteredTool {
 	return defineTool<{ sessionId: string }>(
@@ -50,9 +49,9 @@ export function verificationResultTool(): RegisteredTool {
 				'Authenticates with the org secret (RECLAIM_ORG_SECRET). Fetches the ' +
 				'session status; if it is terminal and a result has been submitted, ' +
 				'pulls the stored result(s) and verifies them locally. Encrypted ' +
-				'deliveries (compact JWE over X25519) are decrypted with your ' +
-				'optional decryption key (the reclaim-decrypt.pem PEM in the ' +
-				'project); plaintext deliveries are read directly. Returns ' +
+				'deliveries (ECIES over secp256k1) are decrypted with your optional ' +
+				'eth key (RECLAIM_DECRYPT_KEY or reclaim-decrypt.key); plaintext ' +
+				'deliveries are read directly. Returns ' +
 				'`ready: false` while the session is still pending or no result has ' +
 				'been delivered yet. Use list_verification_events for the full ' +
 				'lifecycle log.',
@@ -69,14 +68,14 @@ export function verificationResultTool(): RegisteredTool {
 			},
 		},
 		async(args) => {
-			const orgSecret = resolveOrgSecret()
-			// Optional X25519 decryption key — absent ⇒ plaintext-only.
+			const secret = resolveOrgSecret()
+			// Optional eth decryption key — absent ⇒ plaintext-only.
 			const decryptionKey: DecryptionKey | undefined =
 				await resolveDecryptionKey()
 
 			const reclaim = createReclaim({
-				baseUrl: process.env.RECLAIM_API_URL || DEFAULT_BASE_URL,
-				orgSecret,
+				baseUrl: apiUrl(),
+				orgSecret: secret,
 			})
 
 			const sessionRes = await reclaim.api('GetVerificationSession', {
@@ -137,9 +136,9 @@ export function verificationResultTool(): RegisteredTool {
 					ready: false,
 					note:
 						'A result was stored, but no payload could be read — it is ' +
-						'corrupt, or encrypted (JWE) to a key this consumer does not ' +
-						'hold. Place an X25519 PEM (reclaim-decrypt.pem) in the ' +
-						'project matching the org credential.',
+						'corrupt, or encrypted (ECIES) to a key this consumer does not ' +
+						'hold. Set RECLAIM_DECRYPT_KEY (or reclaim-decrypt.key) to the ' +
+						'eth private key matching the org keypair.',
 				}
 			}
 

package/src/old/flag.ts

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

package/src/old/identity.ts

@@ -1,5 +1,6 @@
 import { deriveFromPrivateKey } from '@reclaimprotocol/client'
 import { ConfigStore } from '../config/store.ts'
+import { oldApiToken, oldEthUid, privateKey } from '../consts.ts'
 import type { OldIdentity } from './client.ts'
 
 /** Normalize an eth uid input to `eth:<lowercase-address>`. Accepts a bare
@@ -17,27 +18,27 @@ export function toEthUid(addressOrUid: string): OldIdentity {
  *   3. `RECLAIM_PRIVATE_KEY`   — derive the eth uid from the local app key.
  * Returns undefined when none is set.
  */
-export function resolveIdentityFromEnv(): OldIdentity | undefined {
-	const token = process.env.RECLAIM_OLD_API_TOKEN?.trim()
+function resolveIdentityFromEnv(): OldIdentity | undefined {
+	const token = oldApiToken()?.trim()
 	if(token) {
 		return { kind: 'bearer', token }
 	}
 
-	const ethUid = process.env.RECLAIM_OLD_ETH_UID?.trim()
+	const ethUid = oldEthUid()?.trim()
 	if(ethUid) {
 		return toEthUid(ethUid)
 	}
 
-	const privateKey = process.env.RECLAIM_PRIVATE_KEY?.trim()
-	if(privateKey) {
-		return toEthUid(deriveFromPrivateKey(privateKey).address)
+	const key = privateKey()?.trim()
+	if(key) {
+		return toEthUid(deriveFromPrivateKey(key).address)
 	}
 
 	return undefined
 }
 
 /** Read the identity persisted by a prior `reclaim_authenticate` call. */
-export function loadPersistedIdentity(): OldIdentity | undefined {
+function loadPersistedIdentity(): OldIdentity | undefined {
 	return new ConfigStore().read()?.old_devtools
 }
 

package/src/old/login-cdp.ts

@@ -5,10 +5,7 @@ import {
 	waitForCdpReady,
 } from '../cdp/launcher.ts'
 import { ConfigStore } from '../config/store.ts'
-
-/** The devtools dashboard login page. Override per-call or via
- *  `RECLAIM_OLD_LOGIN_URL`. */
-export const DEFAULT_LOGIN_URL = 'https://dev.reclaimprotocol.org'
+import { DEFAULT_LOGIN_URL, oldLoginUrl } from '../consts.ts'
 
 /**
  * Read the Firebase ID token the dashboard persisted after login.
@@ -84,7 +81,7 @@ export async function captureFirebaseTokenViaCdp(opts: {
 	pollMs?: number
 }): Promise<CdpLoginResult> {
 	const loginUrl =
-		opts.loginUrl || process.env.RECLAIM_OLD_LOGIN_URL || DEFAULT_LOGIN_URL
+		opts.loginUrl || oldLoginUrl() || DEFAULT_LOGIN_URL
 	const timeoutMs = opts.timeoutMs ?? 180_000
 	const pollMs = opts.pollMs ?? 1000
 

package/src/old/to-register.ts

@@ -1,4 +1,4 @@
-import type { ReclaimProvider, ResponseRedaction } from '../provider/schema.ts'
+import type { ReclaimProvider } from '../provider/schema.ts'
 import type {
 	RegisterProviderBody,
 	UpdateProviderConfigBody,
@@ -97,15 +97,12 @@ function requestDataFromProvider(provider: ReclaimProvider): OldRequestData {
 	)
 
 	// Old devtools wants `responseMatches` and `responseRedactions` as PARALLEL
-	// arrays. A drafted provider may instead carry each redaction nested in its
-	// match's `extract` (the builder shape). Prefer the explicit parallel array;
-	// fall back to the nested `extract`s so redactions are never dropped.
-	const nestedRedactions = provider.responseMatches
-		.map((m) => (m as { extract?: ResponseRedaction }).extract)
-		.filter((e): e is ResponseRedaction => Boolean(e))
-	const sourceRedactions = provider.responseRedactions?.length
-		? provider.responseRedactions
-		: nestedRedactions
+	// arrays — same shape the builder uses, so pass them through directly. We do
+	// NOT enforce any match/redaction count relationship here (and never pad —
+	// empty placeholder matches break proof generation): the author keeps full
+	// control. The publish tool surfaces a non-blocking warning when matches <
+	// redactions (see `matchRedactionWarnings`), and the dev decides.
+	const sourceRedactions = provider.responseRedactions ?? []
 
 	const responseRedactions: OldResponseRedaction[] = sourceRedactions.map(
 		(r, i) => {

package/src/old/tools/authenticate.ts

@@ -1,3 +1,4 @@
+import { agentDisabled } from '../../consts.ts'
 import { defineTool, type RegisteredTool } from '../../mcp/server.ts'
 import type { OldIdentity, ReclaimOldClient } from '../client.ts'
 import { persistIdentity, toEthUid } from '../identity.ts'
@@ -128,7 +129,7 @@ export function authenticateTool(client: ReclaimOldClient): RegisteredTool {
 			}
 
 			// CDP browser login (the default headline flow).
-			if(process.env.RECLAIM_AGENT_DISABLED === '1') {
+			if(agentDisabled()) {
 				throw new Error(
 					'Browser login is unavailable (RECLAIM_AGENT_DISABLED=1). Pass a ' +
 					'`token` (Firebase ID token) or `ethAddress` instead.',

package/src/old/tools/publish.ts

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

package/src/paths.ts

@@ -1,13 +1,13 @@
 import { existsSync } from 'node:fs'
-import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
+import { reclaimHome } from './consts.ts'
 
 /**
  * Resolve the Reclaim cache directory (`~/.reclaim`). Honours the
  * `RECLAIM_HOME` env var as an override so tests can sandbox writes.
  */
 export function reclaimHomeDirPath() {
-	return process.env.RECLAIM_HOME || join(homedir(), '.reclaim')
+	return reclaimHome()
 }
 
 /**

package/src/proof/attestor.ts

@@ -10,6 +10,7 @@ import { bytesToHex } from '@noble/hashes/utils.js'
 import {
 	createClaimOnAttestor, type Logger,
 } from '@reclaimprotocol/attestor-core'
+import { agentTraceEnabled } from '../consts.ts'
 import { resolveEthKey } from '../mcp/tools/authenticate/eth-key.ts'
 import type { ReclaimProvider } from '../provider/schema.ts'
 import {
@@ -244,7 +245,7 @@ export async function runAttestorProof(
 		// trace/debug entries during ZK setup). Flip RECLAIM_AGENT_TRACE=1 to
 		// turn it back on when something's broken; logs flow into the proof
 		// response and into the on-disk proof-runs dump.
-		const traceEnabled = process.env['RECLAIM_AGENT_TRACE'] === '1'
+		const traceEnabled = agentTraceEnabled()
 		const capture = traceEnabled ? makeCaptureLogger() : undefined
 		const attestorLogs = capture?.entries
 

package/src/proof/proof-core.ts

@@ -9,9 +9,9 @@
 import type { ProviderParams } from '@reclaimprotocol/attestor-core'
 import { setCryptoImplementation } from '@reclaimprotocol/tls'
 import { webcryptoCrypto } from '@reclaimprotocol/tls/webcrypto'
+import { attestorUrlOverride, FALLBACK_ATTESTOR_URL } from '../consts.ts'
 import type { ReclaimProvider } from '../provider/schema.ts'
-
-const FALLBACK_ATTESTOR_URL = 'wss://attestor.reclaimprotocol.org:444/ws'
+import { normalizeGeoLocation } from '../provider/schema.ts'
 
 let cryptoInitialized = false
 
@@ -34,7 +34,7 @@ export function ensureAttestorCrypto(): void {
  *  effect without restarting. */
 export function resolveAttestorUrl(override?: string): string {
 	return (
-		override ?? process.env['RECLAIM_ATTESTOR_URL'] ?? FALLBACK_ATTESTOR_URL
+		override ?? attestorUrlOverride() ?? FALLBACK_ATTESTOR_URL
 	)
 }
 
@@ -43,6 +43,9 @@ export function resolveAttestorUrl(override?: string): string {
 export function buildHttpParams(
 	provider: ReclaimProvider,
 ): ProviderParams<'http'> {
+	// A blank egress is treated as unset: omit it so the local proof uses the
+	// tester's own egress rather than shipping a blank or an unresolved template.
+	const geoLocation = normalizeGeoLocation(provider.geoLocation)
 	return {
 		url: provider.url,
 		method: provider.method,
@@ -53,6 +56,13 @@ export function buildHttpParams(
 		...(provider.paramValues !== undefined && {
 			paramValues: provider.paramValues,
 		}),
+		...(provider.writeRedactionMode !== undefined && {
+			writeRedactionMode: provider.writeRedactionMode,
+		}),
+		...(provider.additionalClientOptions !== undefined && {
+			additionalClientOptions: provider.additionalClientOptions,
+		}),
+		...(geoLocation !== undefined && { geoLocation }),
 	}
 }
 

package/src/provider/injection-doc.ts

@@ -0,0 +1,21 @@
+/**
+ * Guidance for authoring page-injection scripts (`webSettings.jsUserScripts` on
+ * the builder, `customInjection` on old-devtools), surfaced to the authoring
+ * model from the publish tool description. The prose lives in
+ * `skill/injection-api.md` so it can be edited as markdown without touching
+ * code — the same pattern as `mcp/instructions.ts`. The path resolves the same
+ * from `src/provider` (dev) and `lib/provider` (published): both are two levels
+ * below the package root.
+ *
+ * The guide leads with plain browser JavaScript (navigation/interaction via
+ * standard APIs; the client already intercepts page requests) and treats
+ * `window.Reclaim` as a rarely-needed edge-case bridge, pointing at the
+ * authoritative `src/support/env.d.ts` rather than reproducing its surface.
+ */
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+export const INJECTION_GUIDE = readFileSync(
+	fileURLToPath(new URL('../../skill/injection-api.md', import.meta.url)),
+	'utf8',
+).trim()

package/src/provider/match-redaction-warning.ts

@@ -0,0 +1,53 @@
+/**
+ * Non-blocking advisory for a request whose `responseMatches` count is less
+ * than its `responseRedactions` count.
+ *
+ * Some verification clients (notably the InApp SDK) pair the two arrays by
+ * index and may not behave correctly when there are fewer matches than
+ * redactions. This is NOT enforced — the author keeps full control over what
+ * they publish in either old-devtools or builder mode. The tools surface these
+ * strings so the dev can make an informed decision (e.g. add a functional match
+ * per redaction) rather than being blocked.
+ */
+
+/** One request's match/redaction counts, with a human label for the message. */
+export interface RequestCounts {
+	label: string
+	matchCount: number
+	redactionCount: number
+}
+
+/** Build advisory warnings for any request with matchCount < redactionCount.
+ *  Returns an empty array when everything is fine. */
+export function matchRedactionWarnings(requests: RequestCounts[]): string[] {
+	const warnings: string[] = []
+	for(const req of requests) {
+		if(req.matchCount < req.redactionCount) {
+			warnings.push(
+				`${req.label}: ${req.matchCount} response match(es) but ` +
+				`${req.redactionCount} response redaction(s). Some verification ` +
+				'clients (e.g. the InApp SDK) may not work correctly when ' +
+				'responseMatches is shorter than responseRedactions — they pair the ' +
+				'two by index. This is allowed; add a functional match per redaction ' +
+				'if you hit verification issues.',
+			)
+		}
+	}
+
+	return warnings
+}
+
+/** Counts for a single drafted request shape (provider or injected request). */
+export function countsFor(
+	label: string,
+	req: {
+		responseMatches?: unknown[]
+		responseRedactions?: unknown[]
+	},
+): RequestCounts {
+	return {
+		label,
+		matchCount: req.responseMatches?.length ?? 0,
+		redactionCount: req.responseRedactions?.length ?? 0,
+	}
+}

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. */