@reclaimprotocol/agent 0.1.1-dev.1 → 0.1.2

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
@@ -33,6 +67,7 @@ export function createVersionFromCaptureTool(
 		providerId?: string
 		description?: string
 		geoLocation?: string
+		useProxy?: boolean
 		providerType?: 'PRIVATE' | 'PUBLIC'
 		notes?: string
 	}>(
@@ -47,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',
@@ -83,7 +122,18 @@ export function createVersionFromCaptureTool(
 						type: 'string',
 						description: 'Provider description (new-provider register only).',
 					},
-					geoLocation: { type: 'string' },
+					geoLocation: {
+						type: 'string',
+						description:
+							'Geo the verification appears to originate from. Defaults to ' +
+							"'{{DYNAMIC_GEO}}' (the user's geo) when omitted.",
+					},
+					useProxy: {
+						type: 'boolean',
+						description:
+							'Route portal/attestation traffic through a proxy. Defaults to ' +
+							'true when omitted. Applied on register only.',
+					},
 					providerType: { type: 'string', enum: ['PRIVATE', 'PUBLIC'] },
 					notes: {
 						type: 'string',
@@ -105,31 +155,57 @@ export function createVersionFromCaptureTool(
 				opts.geoLocation = args.geoLocation
 			}
 
+			if(args.useProxy !== undefined) {
+				opts.useProxy = args.useProxy
+			}
+
 			if(args.providerType !== undefined) {
 				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

@@ -6,11 +6,16 @@
 // revealed slice; jsonPath/xPath live on responseRedactions (what the prover
 // reveals), never on responseMatches.
 
+import { bytesToHex } from '@noble/hashes/utils.js'
 import {
-	createClaimOnAttestor, type Logger, type ProviderParams,
+	createClaimOnAttestor, type Logger,
 } from '@reclaimprotocol/attestor-core'
-import { resolveOwnerPrivateKey } from '../mcp/tools/credentials/cache.ts'
+import { agentTraceEnabled } from '../consts.ts'
+import { resolveEthKey } from '../mcp/tools/authenticate/eth-key.ts'
 import type { ReclaimProvider } from '../provider/schema.ts'
+import {
+	buildHttpParams, ensureAttestorCrypto, parseClaim, resolveAttestorUrl,
+} from './proof-core.ts'
 import { ensureZkFiles } from './zk-files.ts'
 
 export interface AttestorLogEntry {
@@ -19,6 +24,37 @@ export interface AttestorLogEntry {
 	ctx?: Record<string, unknown>
 }
 
+/** The attestor's signed claim data + signature, for building the nested proof
+ *  JWS a Consumer verifies against the attestor's key. Populated when
+ *  `includeAttestorClaim` is set (the app's verification runner needs it; the
+ *  MCP `run_proof` tool ignores it). */
+export interface AttestorClaim {
+	/** ProviderClaimData: provider, parameters, context (JSON string), owner,
+	 *  timestampS, epoch, identifier. */
+	claim: Record<string, unknown>
+	/** Hex (0x) attestor ETH address that signed the claim (the nested `kid`). */
+	attestorAddress: string
+	/** Hex (0x) attestor claim signature (EIP-191 over the claim sign-data). */
+	claimSignature: string
+}
+
+/** Options for {@link runAttestorProof}. */
+export interface RunAttestorProofOptions {
+	attestorUrl?: string
+	/** When resolving the key from env/.env/file, the address the caller expects
+	 *  to sign with (sanity check). Ignored when `ownerPrivateKey` is given. */
+	ownerAddress?: string
+	/** Sign with this key directly (e.g. the app/VC's ephemeral per-session key)
+	 *  instead of resolving from env/.env/file. */
+	ownerPrivateKey?: string
+	/** ZK engine for `createClaimOnAttestor`. Defaults to `'gnark'`; the app's
+	 *  server-side verification runner uses `'snarkjs'`. */
+	zkEngine?: 'gnark' | 'snarkjs'
+	/** Extract the structured {@link AttestorClaim} (claim + attestor signature)
+	 *  onto the result for nested-proof construction. */
+	includeAttestorClaim?: boolean
+}
+
 export interface ProofResult {
 	proof: unknown
 	extractedValue: string
@@ -27,6 +63,9 @@ export interface ProofResult {
 	owner?: string
 	verified: boolean
 	error?: string
+	/** Structured claim + signature for nested-proof verification. Set only when
+	 *  `includeAttestorClaim` was requested and the claim carries signatures. */
+	attestorClaim?: AttestorClaim
 	/** 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` /
@@ -139,16 +178,6 @@ function makeCaptureLogger(): {
 	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?: string): string {
-	return (
-		override ?? process.env['RECLAIM_ATTESTOR_URL'] ?? FALLBACK_ATTESTOR_URL
-	)
-}
-
 // ---------------------------------------------------------------------------
 // Main entry point
 // ---------------------------------------------------------------------------
@@ -156,52 +185,67 @@ function resolveAttestorUrl(override?: string): string {
 export async function runAttestorProof(
 	provider: ReclaimProvider,
 	secrets: Record<string, string>,
-	attestorUrl?: string,
-	ownerAddress?: string,
+	opts: RunAttestorProofOptions = {},
 ): Promise<ProofResult> {
-	// 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',
+	// Sign with the caller-supplied key (the app/VC's ephemeral per-session
+	// key) when given; otherwise resolve env/.env/file. `ownerAddress` is a
+	// sanity check on the resolved key (ignored when a key is supplied).
+	let ownerPrivateKey: string
+	if(opts.ownerPrivateKey) {
+		ownerPrivateKey = opts.ownerPrivateKey
+	} else {
+		const resolved = resolveEthKey()
+		if(!resolved) {
+			return {
+				proof: undefined,
+				extractedValue: '',
+				extractedParameters: {},
+				verified: false,
+				error:
+					'No eth proof-owner key available (no RECLAIM_PRIVATE_KEY in env, ' +
+					'.env, or RECLAIM_PRIVATE_KEY_FILE). Call resolve_owner_key, then ' +
+					'issue_credentials (generate) or import_credentials (provide one), ' +
+					'and retry run_proof.',
+				errorKind: 'missing-owner-key',
+			}
 		}
+
+		if(
+			opts.ownerAddress
+			&& opts.ownerAddress.toLowerCase() !== resolved.address
+		) {
+			return {
+				proof: undefined,
+				extractedValue: '',
+				extractedParameters: {},
+				verified: false,
+				error:
+					`Requested ownerAddress "${opts.ownerAddress}" does not match ` +
+					`the resolved eth key (${resolved.address}, source: ` +
+					`${resolved.source}). ` +
+					'Call resolve_owner_key to get the current address, or update the ' +
+					'configured key.',
+				errorKind: 'missing-owner-key',
+			}
+		}
+
+		ownerPrivateKey = resolved.privateKey
 	}
 
 	try {
-		// Circuits aren't downloaded at install time (that blocked the MCP
-		// server's first launch). Fetch them lazily on the first proof.
+		// Init the TLS crypto backend (idempotent), then fetch ZK circuits
+		// lazily on the first proof (not at install time).
+		ensureAttestorCrypto()
 		await ensureZkFiles()
 
-		const params: ProviderParams<'http'> = {
-			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,
-			}),
-		}
+		const params = buildHttpParams(provider)
 
 		// 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 traceEnabled = agentTraceEnabled()
 		const capture = traceEnabled ? makeCaptureLogger() : undefined
 		const attestorLogs = capture?.entries
 
@@ -214,8 +258,8 @@ export async function runAttestorProof(
 					headers: secrets,
 				},
 				ownerPrivateKey,
-				client: { url: resolveAttestorUrl(attestorUrl) },
-				zkEngine: 'snarkjs',
+				client: { url: resolveAttestorUrl(opts.attestorUrl) },
+				zkEngine: opts.zkEngine ?? 'gnark',
 				...(capture !== undefined && { logger: capture.logger as Logger }),
 			})
 		} catch(err) {
@@ -234,27 +278,8 @@ export async function runAttestorProof(
 			return errorResult
 		}
 
-		// ClaimTunnelResponse carries the claim under `.claim`.
-		const claimRecord = claim as Record<string, unknown>
-		const claimData =
-			claimRecord['claim'] as Record<string, unknown> | undefined
-
-		// claimData.context is a JSON-encoded string carrying
-		// { extractedParameters: {...}, providerHash, ... }.
-		let context: Record<string, unknown> = {}
-		const rawContext = claimData?.['context']
-		if(typeof rawContext === 'string') {
-			try {
-				context = JSON.parse(rawContext) as Record<string, unknown>
-			} catch{
-				// Leave context empty if it isn't valid JSON.
-			}
-		}
-
-		const extractedParameters =
-			(context['extractedParameters'] as Record<string, string> | undefined) ??
-			{}
-		const extractedValue = Object.values(extractedParameters)[0] ?? ''
+		const { extractedValue, extractedParameters, identifier, owner, claimData }
+			= parseClaim(claim)
 
 		const result: ProofResult = {
 			proof: claim,
@@ -262,16 +287,33 @@ export async function runAttestorProof(
 			extractedParameters,
 			verified: true,
 		}
-		const identifier = claimData?.['identifier']
-		if(typeof identifier === 'string') {
+		if(identifier !== undefined) {
 			result.identifier = identifier
 		}
 
-		const owner = claimData?.['owner']
-		if(typeof owner === 'string') {
+		if(owner !== undefined) {
 			result.owner = owner
 		}
 
+		// Structured claim + signature so the result JWS can carry a nested,
+		// attestor-signed proof the Consumer verifies independently.
+		if(opts.includeAttestorClaim) {
+			const sigs = (claim as {
+				signatures?: { attestorAddress?: unknown, claimSignature?: unknown }
+			}).signatures
+			if(
+				claimData
+				&& typeof sigs?.attestorAddress === 'string'
+				&& sigs.claimSignature instanceof Uint8Array
+			) {
+				result.attestorClaim = {
+					claim: claimData,
+					attestorAddress: sigs.attestorAddress,
+					claimSignature: '0x' + bytesToHex(sigs.claimSignature),
+				}
+			}
+		}
+
 		// 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) {

package/src/proof/index.ts

@@ -0,0 +1,21 @@
+// Proof primitives shared with the app's verification runner: the attestor
+// param/claim plumbing, the ZK-file bootstrap, and the agent's own
+// `runAttestorProof`. Exposed as `@reclaimprotocol/agent/proof`.
+export type {
+	AttestorClaim,
+	AttestorLogEntry,
+	ProofResult,
+	RunAttestorProofOptions,
+} from './attestor.ts'
+export { runAttestorProof, tailLogs, warnsAndErrors } from './attestor.ts'
+export {
+	buildHttpParams,
+	ensureAttestorCrypto,
+	type ParsedClaim,
+	parseClaim,
+	resolveAttestorUrl,
+} from './proof-core.ts'
+export { ensureZkFiles } from './zk-files.ts'
+// Re-exported attestor-core claim primitive so the agent is the single
+// integration point with @reclaimprotocol/attestor-core across the builder.
+export { createClaimOnAttestor } from '@reclaimprotocol/attestor-core'

package/src/proof/proof-core.ts

@@ -0,0 +1,119 @@
+/**
+ * Shared attestor-claim plumbing used by both proof callers: the agent's MCP
+ * `run_proof` (which resolves the owner key from the credential cache and
+ * captures trace logs) and the app's verification runner (which signs with an
+ * ephemeral per-session key and builds a nested-proof claim). Only those
+ * concerns differ — building the HTTP params, resolving the attestor URL, and
+ * parsing the claim response are identical, so they live here.
+ */
+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'
+import { normalizeGeoLocation } from '../provider/schema.ts'
+
+let cryptoInitialized = false
+
+/** One-time crypto backend init for `@reclaimprotocol/tls` (idempotent). The
+ *  package ships with an empty `crypto = {}` and defers the backend to the
+ *  caller; without this the first proof dies inside the TLS client with
+ *  `crypto.randomBytes is not a function`. Shared by every attestor caller —
+ *  the agent MCP `run_proof` tool and the app's verification runner. */
+export function ensureAttestorCrypto(): void {
+	if(cryptoInitialized) {
+		return
+	}
+
+	setCryptoImplementation(webcryptoCrypto)
+	cryptoInitialized = true
+}
+
+/** Resolve the attestor websocket URL: explicit override → env → public
+ *  default. Resolved per-call so an env change or per-request override takes
+ *  effect without restarting. */
+export function resolveAttestorUrl(override?: string): string {
+	return (
+		override ?? attestorUrlOverride() ?? FALLBACK_ATTESTOR_URL
+	)
+}
+
+/** Map a verification's provider recipe straight to the attestor's HTTP
+ *  params — never synthesized from captured traffic. */
+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,
+		...(provider.headers !== undefined && { headers: provider.headers }),
+		...(provider.body !== undefined && { body: provider.body }),
+		responseMatches: provider.responseMatches,
+		responseRedactions: provider.responseRedactions ?? [],
+		...(provider.paramValues !== undefined && {
+			paramValues: provider.paramValues,
+		}),
+		...(provider.writeRedactionMode !== undefined && {
+			writeRedactionMode: provider.writeRedactionMode,
+		}),
+		...(provider.additionalClientOptions !== undefined && {
+			additionalClientOptions: provider.additionalClientOptions,
+		}),
+		...(geoLocation !== undefined && { geoLocation }),
+	}
+}
+
+export interface ParsedClaim {
+	/** ProviderClaimData: provider, parameters, context, owner, identifier, … */
+	claimData?: Record<string, unknown>
+	extractedParameters: Record<string, string>
+	extractedValue: string
+	identifier?: string
+	owner?: string
+}
+
+/** Pull claimData + decoded `context.extractedParameters` (plus identifier /
+ *  owner) out of a `createClaimOnAttestor` result. The full result still
+ *  carries signatures the caller may need for nested-proof building. */
+export function parseClaim(claim: unknown): ParsedClaim {
+	const claimRecord = claim as Record<string, unknown>
+	const claimData = claimRecord['claim'] as Record<string, unknown> | undefined
+
+	// claimData.context is a JSON-encoded string carrying
+	// { extractedParameters: {...}, providerHash, ... }.
+	let context: Record<string, unknown> = {}
+	const rawContext = claimData?.['context']
+	if(typeof rawContext === 'string') {
+		try {
+			context = JSON.parse(rawContext) as Record<string, unknown>
+		} catch{
+			// Leave context empty if it isn't valid JSON.
+		}
+	}
+
+	const extractedParameters =
+		(context['extractedParameters'] as Record<string, string> | undefined) ?? {}
+
+	const parsed: ParsedClaim = {
+		extractedParameters,
+		extractedValue: Object.values(extractedParameters)[0] ?? '',
+	}
+	if(claimData) {
+		parsed.claimData = claimData
+	}
+
+	const identifier = claimData?.['identifier']
+	if(typeof identifier === 'string') {
+		parsed.identifier = identifier
+	}
+
+	const owner = claimData?.['owner']
+	if(typeof owner === 'string') {
+		parsed.owner = owner
+	}
+
+	return parsed
+}

package/src/provider/index.ts

@@ -0,0 +1,20 @@
+// Provider primitives shared with the app's capture pipeline:
+// the attestor-derived recipe types, secret classification, and the GraphQL
+// op parser. Exposed as `@reclaimprotocol/agent/provider`.
+export { extractGraphqlOp, looksLikeGraphqlEndpoint } from './graphql.ts'
+export type {
+	CapturedRequest,
+	HttpMethod,
+	OprfMode,
+	ReclaimProvider,
+	RequestConcern,
+	ResponseMatch,
+	ResponseRedaction,
+	SecretParamRef,
+} from './schema.ts'
+export { classifyHeader, splitSecrets } from './secrets.ts'
+// Re-exported attestor-core provider primitives (the registry, the param hash,
+// and the param type) so the builder imports them via the agent rather than
+// depending on @reclaimprotocol/attestor-core directly.
+export { hashProviderParams, providers } from '@reclaimprotocol/attestor-core'
+export type { ProviderParams } from '@reclaimprotocol/attestor-core'

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,
+	}
+}