@reclaimprotocol/agent 0.1.13 → 0.1.15

package/lib/old/tools/publish.js

@@ -189,15 +189,86 @@ export function createVersionFromCaptureTool(client) {
                     description: 'Extra requests the customInjection script is allowed to ' +
                         'fire (e.g. pagination) — add-version ONLY, the register ' +
                         'endpoint ignores this. Each item has the same shape as ' +
-                        '`provider`, plus `multiple`/`required` (default true).',
+                        '`provider`, plus `multiple`/`required` (default true). ' +
+                        'IMPORTANT whenever a claim\'s request HAS a body: set `body` ' +
+                        'here (see its own description below) — if only a small part ' +
+                        'of the real body varies per user/run (e.g. one id field, not ' +
+                        'the whole payload), template just that part with ' +
+                        '`{{paramName}}` and keep the rest as fixed literal text; see ' +
+                        'the "bodySniff" section of the customInjection field\'s guide ' +
+                        'for the exact mechanics and a worked example.',
                     items: {
                         type: 'object',
                         properties: {
                             url: { type: 'string' },
                             method: { type: 'string' },
-                            body: { type: 'string' },
-                            responseMatches: { type: 'array' },
-                            responseRedactions: { type: 'array' },
+                            body: {
+                                type: 'string',
+                                description: 'Becomes `bodySniff: { enabled: true, template: <this ' +
+                                    'string> }` — set this whenever the request has a ' +
+                                    'body at all (skip only for a genuinely bodyless ' +
+                                    'request, typically GET). If the real body is FIXED ' +
+                                    '(identical for every user/run), put that literal body ' +
+                                    'text here verbatim. If only PART of it varies (e.g. ' +
+                                    '`{"request":1,"type":"user_info","id":"12345"}` where ' +
+                                    'only `id` differs per user), template ONLY that part: ' +
+                                    '`{"request":1,"type":"user_info",' +
+                                    '"id":"{{REQ_BODY_USER_ID}}"}` — keep everything else ' +
+                                    'as fixed literal text rather than templating the whole ' +
+                                    'body. Confirmed directly against attestor-core\'s ' +
+                                    '`hashProviderParams`: the hash embeds this string ' +
+                                    'LITERALLY, unresolved braces and all, never the real ' +
+                                    'substituted body, so a claim built with the SAME ' +
+                                    'literal template (plus a witness/extracted param per ' +
+                                    'placeholder, supplying the real value for ' +
+                                    'verification) hashes identically regardless of what ' +
+                                    'those real values are. This is the OPPOSITE of ' +
+                                    '`templateParams`\' `${var}` syntax below, which ' +
+                                    'genuinely IS substituted before hashing — do not ' +
+                                    'confuse `{{param}}` (body, never resolved) with ' +
+                                    '`${var}` (responseMatches/responseRedactions, resolved ' +
+                                    'at verify time). Before publishing, hand-verify that ' +
+                                    'substituting real sample values into this template ' +
+                                    'reproduces the real captured request body ' +
+                                    'byte-for-byte. Fallback if per-field templating keeps ' +
+                                    'mismatching (more fields vary than expected, unstable ' +
+                                    'key order, etc.) and you can\'t pin down every ' +
+                                    'variable field: template the WHOLE body as one ' +
+                                    'placeholder instead, `{{REQ_BODY_GRD}}` — the `GRD` ' +
+                                    'suffix makes it a greedy match (captures everything) ' +
+                                    'rather than the default non-greedy match, which is ' +
+                                    'needed when nothing fixed follows the placeholder. ' +
+                                    'This pins down nothing about body structure, so prefer ' +
+                                    'minimal per-field placeholders whenever you can ' +
+                                    'actually identify which fields vary.',
+                            },
+                            responseMatches: {
+                                type: 'array',
+                                description: 'Each item: `{ value: string, type?: "contains" | ' +
+                                    '"regex", invert?: boolean, isOptional?: boolean }`. ' +
+                                    '`value` must literally appear (or match, if `regex`) ' +
+                                    'somewhere in the response body for the claim to be ' +
+                                    'accepted; it commonly embeds one or more ' +
+                                    '`{{paramName}}` extraction placeholders (e.g. ' +
+                                    '`"name":"{{name_0}}"`) whose real value is redacted ' +
+                                    'out and supplied separately as a witness/extracted ' +
+                                    'param. Use `${var}` (not `{{var}}`) inside this string ' +
+                                    'only if you also declare that name in this entry\'s ' +
+                                    'own `templateParams` below — that\'s a DIFFERENT, ' +
+                                    'verify-time-substituted placeholder, resolved from the ' +
+                                    'submitted proof before hashing (unlike a body ' +
+                                    '`{{param}}`, which never resolves — see `body` above).',
+                            },
+                            responseRedactions: {
+                                type: 'array',
+                                description: 'Each item: `{ jsonPath?: string, xPath?: string, ' +
+                                    'regex?: string, hash?: string }`. Identifies WHICH ' +
+                                    'part of the response the matching `{{paramName}}` in ' +
+                                    '`responseMatches` actually redacts/extracts — e.g. ' +
+                                    '`jsonPath: "$.data.items[0].name"` for a JSON response. ' +
+                                    'Order/count should line up with `responseMatches`\' ' +
+                                    'placeholders one-to-one for a typical claim.',
+                            },
                             multiple: {
                                 type: 'boolean',
                                 description: 'Allow matching many requests. Default true.',

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.13",
+	"version": "0.1.15",
 	"description": "Reclaim Protocol's tools for agents — Reclaim Protocol lets your app verify **data points** about its users — a follower count, an account balance, an order history. This package gives your AI coding agent the tools to **find, build, test and fix the _data verification providers_** (the recipes that verify a data point) by inspecting and replaying captured requests, checking sessions, evaluate proofs, publishing updates, and much more.",
 	"type": "module",
 	"main": "./lib/index.js",
@@ -86,7 +86,7 @@
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@noble/hashes": "^2.2.0",
 		"@reclaimprotocol/attestor-core": "^5.0.8",
-		"@reclaimprotocol/client": "*",
+		"@reclaimprotocol/client": "0.1.15",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
 		"domhandler": "^6.0.0",

package/skill/injection-api.md

@@ -133,13 +133,104 @@ field isn't touched by `create_provider_version_from_capture` at all).
 ## `bodySniff` — unrelated to the above
 
 A per-request field (sits next to `url`/`method` on each `requestData` entry,
-not a version-level setting): `{ enabled: boolean, template: string }`. Per
-the InApp SDK's own type comment, it's "the template used for matching and
-extracting params from `requestBody`" — the REQUEST-body counterpart of
-`responseMatches`/`responseRedactions`, which only ever look at the response.
-It applies regardless of `injectionType`/`interceptorType`. Both publish
-tools in this package already set it for you from `provider.body` — you
-should not need to touch it directly.
+not a version-level setting): `{ enabled: boolean, template: string }`.
+
+**`bodySniff.enabled` should be `true` whenever the request HAS a body at
+all** — this isn't a special case reserved for dynamic bodies. Only skip it
+(leave `enabled: false` / template empty) when the request genuinely sends
+no body (typically a GET). Both publish tools in this package already set
+`enabled`/`template` for you from `provider.body` for a normal
+capture-and-replay provider — you don't need to touch it directly there.
+Read the rest of this section if you're authoring a claim via live
+interception (`window.Reclaim.requestClaim`) whose body isn't simply the
+one literal string you captured once — most commonly because some SMALL
+part of it is dynamic per user/run (e.g. a user id, not necessarily the
+whole payload).
+
+**What actually gets hashed.** Confirmed directly from attestor-core
+(`hashProviderParams` in `@reclaimprotocol/attestor-core`): the claim/spec
+hash is `keccak256(canonicalStringify({ url, method, body, responseMatches,
+responseRedactions }))`, where `body` is whatever plain string sits in
+`params.body` — attestor-core does **no** template resolution, substitution,
+or `{{}}`-stripping on it; it hashes exactly the string it's given, verbatim.
+`bodySniff` as a concept (the `{enabled, template}` wrapper) doesn't exist
+inside attestor-core at all — it's translated to a plain `body: string`
+one layer up (old-devtools' `providerUtils.ts`: `body: bodySniff.enabled ?
+bodySniff.template : ''`), and THAT literal string — including any
+unresolved `{{paramName}}` text still in it — is what reaches
+`hashProviderParams`.
+
+**The consequence — and why this differs from `templateParams`.** A live
+claim's own `body` field (submitted via `requestClaim`) can ALSO be set to
+a literal template string containing `{{paramName}}`, rather than the real
+substituted content, with the real value supplied separately as a witness
+param. Since attestor-core hashes `body` as an opaque string with no
+resolution, a claim whose `body` is the literal template `T` and a spec
+whose `body`/`bodySniff.template` is that SAME literal template `T` hash
+identically — regardless of what real value the `{{paramName}}` hole stood
+for. This is the OPPOSITE of `templateParams`/`${var}` (used in
+`responseMatches`/`responseRedactions`), which — per the JS SDK's
+`generateSpecsFromRequestSpecTemplate` — genuinely gets substituted with a
+real value at verify time before hashing. Don't conflate the two: `${var}`
+in a match/redaction template IS resolved before hashing;  `{{var}}` in a
+body template is NEVER resolved before hashing, on either side.
+
+**Practical use**: check exactly which part of the body actually changes
+across users/runs — usually it's one small field (an id, a token, a short
+list), not the whole payload. Template ONLY that minimal changing part;
+leave everything else as fixed literal text. For a body like
+`{"request":1,"type":"user_info","id":"12345"}` where only `id` varies, the
+template is `{"request":1,"type":"user_info","id":"{{REQ_BODY_USER_ID}}"}`
+— NOT e.g. `{{whole_body}}` wrapping the entire object, which would throw
+away the ability to structurally pin down everything else about the
+request. Then:
+1. In the claim you build for `requestClaim`, set `bodySniff: { enabled:
+   true, template: '{"request":1,"type":"user_info","id":"{{REQ_BODY_USER_ID}}"}' }`
+   and add a matching witness/extracted param
+   `REQ_BODY_USER_ID: theRealUserId` so the real value is still
+   independently verifiable, just not part of the hash.
+2. In the corresponding `allowedInjectedRequestData` entry, set `body` to
+   that EXACT SAME literal template string (byte-for-byte, same
+   `{{REQ_BODY_USER_ID}}` placeholder, same everything else) — NOT a
+   `${var}` substitution, since `body` doesn't go through that substitution
+   step.
+3. Before publishing, sanity-check by hand that
+   `template.replace('{{REQ_BODY_USER_ID}}', 'a real sample id')`
+   reproduces the real captured/expected request body byte-for-byte — if it
+   doesn't (extra whitespace, different key order, a field that turned out
+   to ALSO vary but wasn't templated, etc.), the hashes won't match either,
+   since the SPEC side uses the literal template as-is and the real claim's
+   body must independently be built to match that same shape when the
+   placeholder(s) are filled in. If MULTIPLE fields vary independently,
+   template each one with its own `{{placeholder}}` and its own witness
+   param — you're not limited to one hole per template.
+
+**Fallback — whole-body placeholder.** If precise per-field templating
+keeps causing hash mismatches (e.g. more fields turn out to vary than
+expected, key order isn't stable, whitespace differs run-to-run) and you
+can't pin down every variable field individually, fall back to templating
+the ENTIRE body as one placeholder instead: `{{REQ_BODY_GRD}}`. The `GRD`
+suffix matters — per the response-matching template engine
+(`convertTemplateToRegex`), a placeholder name ending in `GRD` is treated as
+a GREEDY match (`(.*)`, matching everything including embedded delimiters)
+rather than the default non-greedy `(.*?)` (which stops at the first
+occurrence of whatever comes after it in the template) — for a placeholder
+covering the entire remaining body with nothing fixed after it, greedy is
+what you want. This is strictly a fallback: it means NOTHING about the
+body's structure is pinned down by the hash anymore (any body at all would
+hash the same), so prefer the minimal-placeholder approach above whenever
+you can actually identify which fields vary.
+
+Caveat: I confirmed `hashProviderParams` treats `body` as an opaque string
+with no `{{}}` resolution directly from the attestor-core bundle shipped in
+this repo's `node_modules`. I did NOT find, in this same bundle, the code
+path that actually invokes `hashProviderParams` against a live submitted
+claim to gate proof acceptance — that caller lives elsewhere (the mobile/
+InApp SDK client and/or a server-side verifier not checked into this repo).
+So this is strong but not 100% end-to-end-traced confirmation; treat it as
+"very likely correct, empirically consistent with real proof/verifyProof
+behavior observed in practice" rather than "certain from first-hand
+tracing of the whole call chain."
 
 ## Recognizing this on a provider you didn't author
 

package/src/old/tools/publish.ts

@@ -240,15 +240,89 @@ export function createVersionFromCaptureTool(
 							'Extra requests the customInjection script is allowed to ' +
 							'fire (e.g. pagination) — add-version ONLY, the register ' +
 							'endpoint ignores this. Each item has the same shape as ' +
-							'`provider`, plus `multiple`/`required` (default true).',
+							'`provider`, plus `multiple`/`required` (default true). ' +
+							'IMPORTANT whenever a claim\'s request HAS a body: set `body` ' +
+							'here (see its own description below) — if only a small part ' +
+							'of the real body varies per user/run (e.g. one id field, not ' +
+							'the whole payload), template just that part with ' +
+							'`{{paramName}}` and keep the rest as fixed literal text; see ' +
+							'the "bodySniff" section of the customInjection field\'s guide ' +
+							'for the exact mechanics and a worked example.',
 						items: {
 							type: 'object',
 							properties: {
 								url: { type: 'string' },
 								method: { type: 'string' },
-								body: { type: 'string' },
-								responseMatches: { type: 'array' },
-								responseRedactions: { type: 'array' },
+								body: {
+									type: 'string',
+									description:
+										'Becomes `bodySniff: { enabled: true, template: <this ' +
+										'string> }` — set this whenever the request has a ' +
+										'body at all (skip only for a genuinely bodyless ' +
+										'request, typically GET). If the real body is FIXED ' +
+										'(identical for every user/run), put that literal body ' +
+										'text here verbatim. If only PART of it varies (e.g. ' +
+										'`{"request":1,"type":"user_info","id":"12345"}` where ' +
+										'only `id` differs per user), template ONLY that part: ' +
+										'`{"request":1,"type":"user_info",' +
+										'"id":"{{REQ_BODY_USER_ID}}"}` — keep everything else ' +
+										'as fixed literal text rather than templating the whole ' +
+										'body. Confirmed directly against attestor-core\'s ' +
+										'`hashProviderParams`: the hash embeds this string ' +
+										'LITERALLY, unresolved braces and all, never the real ' +
+										'substituted body, so a claim built with the SAME ' +
+										'literal template (plus a witness/extracted param per ' +
+										'placeholder, supplying the real value for ' +
+										'verification) hashes identically regardless of what ' +
+										'those real values are. This is the OPPOSITE of ' +
+										'`templateParams`\' `${var}` syntax below, which ' +
+										'genuinely IS substituted before hashing — do not ' +
+										'confuse `{{param}}` (body, never resolved) with ' +
+										'`${var}` (responseMatches/responseRedactions, resolved ' +
+										'at verify time). Before publishing, hand-verify that ' +
+										'substituting real sample values into this template ' +
+										'reproduces the real captured request body ' +
+										'byte-for-byte. Fallback if per-field templating keeps ' +
+										'mismatching (more fields vary than expected, unstable ' +
+										'key order, etc.) and you can\'t pin down every ' +
+										'variable field: template the WHOLE body as one ' +
+										'placeholder instead, `{{REQ_BODY_GRD}}` — the `GRD` ' +
+										'suffix makes it a greedy match (captures everything) ' +
+										'rather than the default non-greedy match, which is ' +
+										'needed when nothing fixed follows the placeholder. ' +
+										'This pins down nothing about body structure, so prefer ' +
+										'minimal per-field placeholders whenever you can ' +
+										'actually identify which fields vary.',
+								},
+								responseMatches: {
+									type: 'array',
+									description:
+										'Each item: `{ value: string, type?: "contains" | ' +
+										'"regex", invert?: boolean, isOptional?: boolean }`. ' +
+										'`value` must literally appear (or match, if `regex`) ' +
+										'somewhere in the response body for the claim to be ' +
+										'accepted; it commonly embeds one or more ' +
+										'`{{paramName}}` extraction placeholders (e.g. ' +
+										'`"name":"{{name_0}}"`) whose real value is redacted ' +
+										'out and supplied separately as a witness/extracted ' +
+										'param. Use `${var}` (not `{{var}}`) inside this string ' +
+										'only if you also declare that name in this entry\'s ' +
+										'own `templateParams` below — that\'s a DIFFERENT, ' +
+										'verify-time-substituted placeholder, resolved from the ' +
+										'submitted proof before hashing (unlike a body ' +
+										'`{{param}}`, which never resolves — see `body` above).',
+								},
+								responseRedactions: {
+									type: 'array',
+									description:
+										'Each item: `{ jsonPath?: string, xPath?: string, ' +
+										'regex?: string, hash?: string }`. Identifies WHICH ' +
+										'part of the response the matching `{{paramName}}` in ' +
+										'`responseMatches` actually redacts/extracts — e.g. ' +
+										'`jsonPath: "$.data.items[0].name"` for a JSON response. ' +
+										'Order/count should line up with `responseMatches`\' ' +
+										'placeholders one-to-one for a typical claim.',
+								},
 								multiple: {
 									type: 'boolean',
 									description: 'Allow matching many requests. Default true.',