@reclaimprotocol/agent 0.1.18 → 0.1.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +6 -2
- package/lib/authoring/backend.d.ts +4 -0
- package/lib/authoring/tools.js +4 -1
- package/lib/cdp/capture.d.ts +2 -2
- package/lib/cdp/capture.js +25 -21
- package/lib/cdp/client.d.ts +39 -1
- package/lib/cdp/client.js +125 -1
- package/lib/mcp/api/operations.gen.js +33 -9
- package/lib/mcp/instructions.js +27 -3
- package/lib/mcp/start.js +12 -8
- package/lib/mcp/tools/agent/attach.d.ts +18 -4
- package/lib/mcp/tools/agent/attach.js +142 -52
- package/lib/mcp/tools/agent/build.d.ts +1 -1
- package/lib/mcp/tools/agent/build.js +5 -3
- package/lib/mcp/tools/agent/capture.d.ts +1 -0
- package/lib/mcp/tools/agent/capture.js +8 -1
- package/lib/mcp/tools/agent/eval.js +2 -3
- package/lib/mcp/tools/agent/how-it-works.d.ts +1 -1
- package/lib/mcp/tools/agent/how-it-works.js +1 -1
- package/lib/mcp/tools/agent/publish.js +22 -1
- package/lib/mcp/tools/agent/session.d.ts +2 -2
- package/lib/mcp/tools/agent/session.js +21 -5
- package/lib/mcp/tools/agent/shared.js +4 -6
- package/lib/mcp/tools/authenticate/authenticate.d.ts +1 -1
- package/lib/mcp/tools/authenticate/authenticate.js +10 -4
- package/lib/mcp/tools/authenticate/builder-access.d.ts +8 -0
- package/lib/mcp/tools/authenticate/builder-access.js +31 -0
- package/lib/mcp/tools/authenticate/index.d.ts +1 -0
- package/lib/mcp/tools/authenticate/index.js +1 -0
- package/lib/old/login-cdp.js +11 -3
- package/lib/old/tools/publish.js +23 -1
- package/lib/provider/draft.d.ts +20 -0
- package/lib/provider/draft.js +75 -51
- package/lib/provider/index.d.ts +1 -1
- package/lib/provider/index.js +1 -1
- package/lib/provider/secrets.d.ts +37 -0
- package/lib/provider/secrets.js +147 -6
- package/lib/provider/to-version.d.ts +7 -0
- package/lib/provider/to-version.js +11 -1
- package/package.json +2 -2
- package/skill/SKILL.builder.md +43 -95
- package/skill/SKILL.common.md +102 -0
- package/skill/SKILL.old.md +20 -74
- package/skill/builder-mode.md +2 -2
- package/skill/injection-api.md +95 -10
- package/skill/old-mode.md +2 -2
- package/src/authoring/backend.ts +4 -0
- package/src/authoring/tools.ts +4 -1
- package/src/cdp/capture.ts +24 -24
- package/src/cdp/client.ts +197 -2
- package/src/mcp/api/operations.gen.ts +33 -9
- package/src/mcp/instructions.ts +36 -3
- package/src/mcp/start.ts +13 -8
- package/src/mcp/tools/agent/attach.ts +198 -57
- package/src/mcp/tools/agent/build.ts +9 -2
- package/src/mcp/tools/agent/capture.ts +10 -1
- package/src/mcp/tools/agent/eval.ts +2 -3
- package/src/mcp/tools/agent/how-it-works.ts +1 -1
- package/src/mcp/tools/agent/publish.ts +22 -1
- package/src/mcp/tools/agent/session.ts +29 -8
- package/src/mcp/tools/agent/shared.ts +5 -10
- package/src/mcp/tools/authenticate/authenticate.ts +14 -4
- package/src/mcp/tools/authenticate/builder-access.ts +42 -0
- package/src/mcp/tools/authenticate/index.ts +4 -0
- package/src/old/login-cdp.ts +13 -3
- package/src/old/tools/publish.ts +25 -3
- package/src/provider/draft.ts +98 -56
- package/src/provider/index.ts +9 -1
- package/src/provider/secrets.ts +171 -6
- package/src/provider/to-version.ts +12 -1
- package/lib/authoring/find.d.ts +0 -3
- package/lib/authoring/find.js +0 -54
- package/lib/authoring/propose.d.ts +0 -3
- package/lib/authoring/propose.js +0 -109
- package/lib/authoring/replay.d.ts +0 -10
- package/lib/authoring/replay.js +0 -34
- package/lib/cli/args.d.ts +0 -14
- package/lib/cli/args.js +0 -19
- package/lib/cli/commands.d.ts +0 -1
- package/lib/cli/commands.js +0 -19
- package/lib/cli.d.ts +0 -1
- package/lib/cli.js +0 -7
- package/lib/mcp/credentials/authenticate.d.ts +0 -3
- package/lib/mcp/credentials/authenticate.js +0 -108
- package/lib/mcp/credentials/build.d.ts +0 -5
- package/lib/mcp/credentials/build.js +0 -18
- package/lib/mcp/credentials/cache.d.ts +0 -70
- package/lib/mcp/credentials/cache.js +0 -131
- package/lib/mcp/credentials/env-file.d.ts +0 -25
- package/lib/mcp/credentials/env-file.js +0 -71
- package/lib/mcp/credentials/import.d.ts +0 -2
- package/lib/mcp/credentials/import.js +0 -52
- package/lib/mcp/credentials/issue.d.ts +0 -2
- package/lib/mcp/credentials/issue.js +0 -84
- package/lib/mcp/credentials/keypair.d.ts +0 -17
- package/lib/mcp/credentials/keypair.js +0 -48
- package/lib/mcp/credentials/link.d.ts +0 -3
- package/lib/mcp/credentials/link.js +0 -107
- package/lib/mcp/credentials/list-cached.d.ts +0 -2
- package/lib/mcp/credentials/list-cached.js +0 -55
- package/lib/mcp/credentials/owner-key.d.ts +0 -23
- package/lib/mcp/credentials/owner-key.js +0 -58
- package/lib/mcp/credentials/paths.d.ts +0 -12
- package/lib/mcp/credentials/paths.js +0 -35
- package/lib/mcp/credentials/poll.d.ts +0 -27
- package/lib/mcp/credentials/poll.js +0 -61
- package/lib/mcp/credentials/register.d.ts +0 -18
- package/lib/mcp/credentials/register.js +0 -30
- package/lib/mcp/credentials/resolve-owner-key.d.ts +0 -12
- package/lib/mcp/credentials/resolve-owner-key.js +0 -68
- package/lib/mcp/credentials/session-cache.d.ts +0 -14
- package/lib/mcp/credentials/session-cache.js +0 -42
- package/lib/mcp/credentials/status.d.ts +0 -3
- package/lib/mcp/credentials/status.js +0 -76
- package/lib/mcp/register.d.ts +0 -38
- package/lib/mcp/register.js +0 -80
- package/lib/mcp/tools/analyze.d.ts +0 -3
- package/lib/mcp/tools/analyze.js +0 -26
- package/lib/mcp/tools/attach.d.ts +0 -11
- package/lib/mcp/tools/attach.js +0 -72
- package/lib/mcp/tools/capture.d.ts +0 -10
- package/lib/mcp/tools/capture.js +0 -142
- package/lib/mcp/tools/eval.d.ts +0 -5
- package/lib/mcp/tools/eval.js +0 -127
- package/lib/mcp/tools/find.d.ts +0 -3
- package/lib/mcp/tools/find.js +0 -60
- package/lib/mcp/tools/owner-key.d.ts +0 -2
- package/lib/mcp/tools/owner-key.js +0 -63
- package/lib/mcp/tools/proof.d.ts +0 -3
- package/lib/mcp/tools/proof.js +0 -214
- package/lib/mcp/tools/propose.d.ts +0 -9
- package/lib/mcp/tools/propose.js +0 -75
- package/lib/mcp/tools/publish.d.ts +0 -3
- package/lib/mcp/tools/publish.js +0 -59
- package/lib/mcp/tools/replay.d.ts +0 -3
- package/lib/mcp/tools/replay.js +0 -46
- package/lib/mcp/tools/session.d.ts +0 -10
- package/lib/mcp/tools/session.js +0 -29
- package/lib/mcp/tools/verification/diagnose.d.ts +0 -11
- package/lib/mcp/tools/verification/diagnose.js +0 -132
- package/lib/mcp/verifications/build.d.ts +0 -5
- package/lib/mcp/verifications/build.js +0 -14
- package/lib/mcp/verifications/create.d.ts +0 -3
- package/lib/mcp/verifications/create.js +0 -57
- package/lib/mcp/verifications/find.d.ts +0 -3
- package/lib/mcp/verifications/find.js +0 -37
- package/lib/mcp/verifications/get.d.ts +0 -3
- package/lib/mcp/verifications/get.js +0 -26
- package/lib/mcp/verifications/update.d.ts +0 -3
- package/lib/mcp/verifications/update.js +0 -78
- package/lib/old/tools/get-version-config.d.ts +0 -17
- package/lib/old/tools/get-version-config.js +0 -47
- package/lib/routes.gen.d.ts +0 -271
- package/lib/routes.gen.js +0 -73
- package/lib/types/openapi.d.ts +0 -4
- package/lib/types/openapi.gen.d.ts +0 -3967
- package/lib/types/openapi.gen.js +0 -5
- package/lib/types/openapi.js +0 -1
package/lib/provider/draft.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { isOprfHashable, OPRF_MAX_BYTES, synthesizeMatcher } from "./matcher.js";
|
|
2
|
-
import {
|
|
2
|
+
import { normalizeCandidates } from "./normalize.js";
|
|
3
|
+
import { secretUrlCharBudget, splitSecrets, stripTransportHeaders, } from "./secrets.js";
|
|
3
4
|
/** OPRF mode for the auto-hash floor — TEE-native (attestor rejects oprf-raw,
|
|
4
5
|
* isn't set up for gnark oprf). */
|
|
5
6
|
const DEFAULT_SENSITIVE_HASH = 'oprf-mpc';
|
|
@@ -29,49 +30,6 @@ export function defaultSensitiveHash(value) {
|
|
|
29
30
|
&& Buffer.byteLength(value, 'utf8') <= OPRF_MAX_BYTES;
|
|
30
31
|
return hashable ? DEFAULT_SENSITIVE_HASH : undefined;
|
|
31
32
|
}
|
|
32
|
-
/** Request headers that must NOT survive into the provider params. Three kinds:
|
|
33
|
-
* - Conditional headers (`if-none-match`/`if-modified-since`/…): a captured
|
|
34
|
-
* cached ETag/date makes the origin answer 304/412 when the attestor
|
|
35
|
-
* re-issues, and the attestor treats non-2xx as failure. We always want the
|
|
36
|
-
* full fresh response.
|
|
37
|
-
* - Transfer headers the ATTESTOR sets itself (`connection: close`,
|
|
38
|
-
* `accept-encoding: identity`). Passing our own duplicates/collides with the
|
|
39
|
-
* request the attestor builds, so leave them out — the attestor already
|
|
40
|
-
* forces `identity` (uncompressed, so its byte-matching works).
|
|
41
|
-
* - Host / framing headers the TRANSPORT owns (`host`, `content-length`,
|
|
42
|
-
* `transfer-encoding`) and HTTP/2 pseudo-headers (`:authority`/`:method`/…,
|
|
43
|
-
* which CDP surfaces on h2 captures). The attestor derives `Host` from the
|
|
44
|
-
* URL and sets its own; a baked `Host` produces a DUPLICATE
|
|
45
|
-
* (`found: h,h`) that fails the receipt check / 400s the origin. A stale
|
|
46
|
-
* `content-length` breaks a re-serialized body. Pseudo-headers aren't valid
|
|
47
|
-
* real headers at all. */
|
|
48
|
-
const STRIP_REQUEST_HEADERS = new Set([
|
|
49
|
-
'if-none-match',
|
|
50
|
-
'if-modified-since',
|
|
51
|
-
'if-match',
|
|
52
|
-
'if-unmodified-since',
|
|
53
|
-
'if-range',
|
|
54
|
-
'connection',
|
|
55
|
-
'accept-encoding',
|
|
56
|
-
'host',
|
|
57
|
-
'content-length',
|
|
58
|
-
'transfer-encoding',
|
|
59
|
-
// Per-session anti-CSRF tokens. Not caught by splitSecrets (no `-token`
|
|
60
|
-
// suffix), so without this they baked in as PUBLIC headers and went stale at
|
|
61
|
-
// verify time — the attestor replayed one user's captured CSRF for everyone,
|
|
62
|
-
// which the origin rejects. A CSRF token is never portable; drop it.
|
|
63
|
-
'csrf',
|
|
64
|
-
'x-csrf',
|
|
65
|
-
'xsrf',
|
|
66
|
-
'x-xsrf',
|
|
67
|
-
'x-csrf-token',
|
|
68
|
-
'xsrf-token',
|
|
69
|
-
]);
|
|
70
|
-
/** True for an HTTP/2 pseudo-header (`:authority`, `:method`, `:path`,
|
|
71
|
-
* `:scheme`) — never a valid request header the attestor can replay. */
|
|
72
|
-
function isPseudoHeader(name) {
|
|
73
|
-
return name.startsWith(':');
|
|
74
|
-
}
|
|
75
33
|
/** A header VALUE that is a per-session/request token — a UUID or a long opaque
|
|
76
34
|
* hex/base64 blob. Such a value is captured-user-specific: baked into the
|
|
77
35
|
* provider it goes stale and the origin rejects the replay for everyone else.
|
|
@@ -84,15 +42,17 @@ function isVolatileHeaderValue(value) {
|
|
|
84
42
|
|| /^[0-9a-f]{16,}$/i.test(v)
|
|
85
43
|
|| /^[A-Za-z0-9_-]{32,}$/.test(v);
|
|
86
44
|
}
|
|
87
|
-
/** Drop
|
|
88
|
-
*
|
|
89
|
-
*
|
|
45
|
+
/** Drop a PUBLIC header whose value is per-session/request volatile (see
|
|
46
|
+
* {@link isVolatileHeaderValue}) — public headers get frozen into the
|
|
47
|
+
* persisted provider, so a volatile one goes stale and fails every other
|
|
48
|
+
* user's replay. Secret headers are re-captured fresh per verification
|
|
49
|
+
* (never persisted), so this doesn't apply to them; keep every other
|
|
50
|
+
* captured public header so the attestor's replay looks like the browser's
|
|
51
|
+
* request. */
|
|
90
52
|
function sanitizeRequestHeaders(headers) {
|
|
91
53
|
const out = {};
|
|
92
54
|
for (const [k, v] of Object.entries(headers)) {
|
|
93
|
-
if (
|
|
94
|
-
|| isPseudoHeader(k)
|
|
95
|
-
|| isVolatileHeaderValue(v)) {
|
|
55
|
+
if (isVolatileHeaderValue(v)) {
|
|
96
56
|
continue;
|
|
97
57
|
}
|
|
98
58
|
out[k] = v;
|
|
@@ -167,6 +127,63 @@ export function assertPortableMatches(matches, redactions, targets) {
|
|
|
167
127
|
}
|
|
168
128
|
}
|
|
169
129
|
}
|
|
130
|
+
/** Reject a draft that OPRF-hashes a target whose value ALSO appears in the
|
|
131
|
+
* request URL. The whole point of `hash` is that the attestor never sees
|
|
132
|
+
* the value in cleartext — but URL `paramValues` are always signed into the
|
|
133
|
+
* attestor's context in the clear (attestor-core: "those in URL... will be
|
|
134
|
+
* put into context and signed"), so a value that's both hashed in the
|
|
135
|
+
* response AND present in the URL is visible there anyway. This isn't a
|
|
136
|
+
* privacy nuance the author can weigh (unlike {@link assertPortableMatches}
|
|
137
|
+
* bare-literal cases) — it doesn't verify. Throwing here, at draft time,
|
|
138
|
+
* surfaces that immediately instead of a confusing later proof failure. */
|
|
139
|
+
export function assertNoOprfUrlConflict(url, targets, effectiveHashes) {
|
|
140
|
+
for (const [i, t] of targets.entries()) {
|
|
141
|
+
const hash = effectiveHashes[i];
|
|
142
|
+
if (!hash) {
|
|
143
|
+
continue;
|
|
144
|
+
}
|
|
145
|
+
const inUrl = [t.value, ...normalizeCandidates(t.value)]
|
|
146
|
+
.some((v) => url.includes(v));
|
|
147
|
+
if (inUrl) {
|
|
148
|
+
throw new Error(`target "${t.name}" is OPRF-hashed (${hash}) but its value also `
|
|
149
|
+
+ `appears in the request URL ("${url}") — the attestor signs URL `
|
|
150
|
+
+ 'param values into context in the clear, so it would see this '
|
|
151
|
+
+ 'value regardless of the hash. Drop `hash` for this target, or '
|
|
152
|
+
+ "capture a request whose URL doesn't carry the value.");
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
/** Reject a draft whose URL bakes in a secret header/cookie's value beyond
|
|
157
|
+
* what write-redaction can actually hide there. A secret value used in the
|
|
158
|
+
* URL is NOT an automatic leak — write-redaction (`key-update`/`zk`) can
|
|
159
|
+
* redact it from the attestor's view up to {@link secretUrlCharBudget}
|
|
160
|
+
* characters, summed across every secret value that appears in that URL
|
|
161
|
+
* (not per-value). Below the budget the header buys real privacy; at or
|
|
162
|
+
* over it, the value is effectively visible regardless of hiding the
|
|
163
|
+
* header (same class of problem as {@link assertNoOprfUrlConflict} for
|
|
164
|
+
* OPRF-hashed targets, which has no such budget at all). */
|
|
165
|
+
export function assertNoSecretUrlConflict(url, secrets, writeRedactionMode) {
|
|
166
|
+
let redactedChars = 0;
|
|
167
|
+
const overlapping = [];
|
|
168
|
+
for (const [name, value] of Object.entries(secrets)) {
|
|
169
|
+
const inUrl = [value, ...normalizeCandidates(value)]
|
|
170
|
+
.some((v) => url.includes(v));
|
|
171
|
+
if (inUrl) {
|
|
172
|
+
redactedChars += value.length;
|
|
173
|
+
overlapping.push(name);
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
const budget = secretUrlCharBudget(writeRedactionMode);
|
|
177
|
+
if (redactedChars > budget) {
|
|
178
|
+
throw new Error(`secret header(s) ${overlapping.map((n) => `"${n}"`).join(', ')} `
|
|
179
|
+
+ `also appear in the request URL ("${url}"), totaling `
|
|
180
|
+
+ `${redactedChars} character(s) to hide — over the ${budget}-`
|
|
181
|
+
+ `character budget write-redaction (${writeRedactionMode
|
|
182
|
+
?? 'key-update'}) can actually hide there. Drop the header, `
|
|
183
|
+
+ "shorten/remove the value's overlap with the URL, or switch to "
|
|
184
|
+
+ "'zk' if that raises the budget enough.");
|
|
185
|
+
}
|
|
186
|
+
}
|
|
170
187
|
/** Derive a `paramValues` key (and capture-group name) from the provider
|
|
171
188
|
* name's last alphanumeric token. `"GitHub Username"` → `"username"`,
|
|
172
189
|
* `"x-followers"` → `"followers"`. */
|
|
@@ -188,6 +205,7 @@ export function draftProvider(req, targets, name, hash) {
|
|
|
188
205
|
const matches = [];
|
|
189
206
|
const redactions = [];
|
|
190
207
|
const extractions = [];
|
|
208
|
+
const effectiveHashes = [];
|
|
191
209
|
let paramValues;
|
|
192
210
|
const seenParams = new Set();
|
|
193
211
|
for (const t of targets) {
|
|
@@ -202,6 +220,7 @@ export function draftProvider(req, targets, name, hash) {
|
|
|
202
220
|
// The model makes the contextual calls (which named fields are sensitive)
|
|
203
221
|
// via an explicit per-target hash; this floor only guarantees the obvious.
|
|
204
222
|
const effectiveHash = t.hash ?? hash ?? defaultSensitiveHash(t.value);
|
|
223
|
+
effectiveHashes.push(effectiveHash);
|
|
205
224
|
const synthesis = synthesizeMatcher(req.responseBody, req.contentType, t.value, paramName, effectiveHash);
|
|
206
225
|
if (!synthesis) {
|
|
207
226
|
throw new Error(`target value "${t.value}" not found in`
|
|
@@ -222,7 +241,12 @@ export function draftProvider(req, targets, name, hash) {
|
|
|
222
241
|
}
|
|
223
242
|
// Portability gate: never ship a draft that bakes a per-user value literally.
|
|
224
243
|
assertPortableMatches(matches, redactions, targets);
|
|
225
|
-
|
|
244
|
+
// OPRF gate: never ship a draft that hashes a value the URL also reveals.
|
|
245
|
+
assertNoOprfUrlConflict(req.url, targets, effectiveHashes);
|
|
246
|
+
const { secrets, publics } = splitSecrets(stripTransportHeaders(req.requestHeaders));
|
|
247
|
+
// Secret-header gate: never ship a draft whose URL reveals the same value a
|
|
248
|
+
// stripped secret header carries — hiding the header buys nothing then.
|
|
249
|
+
assertNoSecretUrlConflict(req.url, secrets);
|
|
226
250
|
// Sanitize the public headers before they enter the provider. Two problems
|
|
227
251
|
// a captured browser request carries: (1) `accept-encoding: gzip, …`, which
|
|
228
252
|
// makes the attestor match against compressed bytes (it does no transparent
|
package/lib/provider/index.d.ts
CHANGED
|
@@ -3,7 +3,7 @@ export type { DraftResult } from './draft.ts';
|
|
|
3
3
|
export { detectConcerns } from './constraints.ts';
|
|
4
4
|
export { extractGraphqlOp, looksLikeGraphqlEndpoint } from './graphql.ts';
|
|
5
5
|
export type { CapturedRequest, HttpMethod, OprfMode, ReclaimProvider, RequestConcern, ResponseMatch, ResponseRedaction, SecretParamRef, } from './schema.ts';
|
|
6
|
-
export { classifyHeader, splitSecrets } from './secrets.ts';
|
|
6
|
+
export { assertSecretParamValuesFitUrlBudget, classifyHeader, classifyParamName, secretUrlCharBudget, splitSecretParamValues, splitSecrets, stripTransportHeaders, } from './secrets.ts';
|
|
7
7
|
export { providerToRequestSelection } from './to-version.ts';
|
|
8
8
|
export { hashProviderParams, providers } from '@reclaimprotocol/attestor-core';
|
|
9
9
|
export type { ProviderParams } from '@reclaimprotocol/attestor-core';
|
package/lib/provider/index.js
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
export { draftProvider } from "./draft.js";
|
|
7
7
|
export { detectConcerns } from "./constraints.js";
|
|
8
8
|
export { extractGraphqlOp, looksLikeGraphqlEndpoint } from "./graphql.js";
|
|
9
|
-
export { classifyHeader, splitSecrets } from "./secrets.js";
|
|
9
|
+
export { assertSecretParamValuesFitUrlBudget, classifyHeader, classifyParamName, secretUrlCharBudget, splitSecretParamValues, splitSecrets, stripTransportHeaders, } from "./secrets.js";
|
|
10
10
|
// Recipe → version `requests[]` (a `RequestSelection`) — the same mapping the
|
|
11
11
|
// MCP publish uses, so the cloud authoring publish stays byte-identical.
|
|
12
12
|
export { providerToRequestSelection } from "./to-version.js";
|
|
@@ -1,5 +1,42 @@
|
|
|
1
|
+
import type { ReclaimProvider } from './schema.ts';
|
|
1
2
|
export declare function classifyHeader(name: string): boolean;
|
|
3
|
+
/** Drop {@link STRIP_REQUEST_HEADERS} and HTTP/2 pseudo-headers. Call this on
|
|
4
|
+
* the RAW captured headers before {@link splitSecrets} — both the draft-time
|
|
5
|
+
* authoring flow and the live per-user verification capture need it, so
|
|
6
|
+
* neither ends up sending a duplicate `Host` or an invalid `:authority` to
|
|
7
|
+
* the attestor via either the public or the secret channel. */
|
|
8
|
+
export declare function stripTransportHeaders(headers: Record<string, string>): Record<string, string>;
|
|
2
9
|
export declare function splitSecrets(headers: Record<string, string>): {
|
|
3
10
|
secrets: Record<string, string>;
|
|
4
11
|
publics: Record<string, string>;
|
|
5
12
|
};
|
|
13
|
+
/** Total characters write-redaction can hide from the attestor, summed
|
|
14
|
+
* ACROSS EVERY secret-classified value used in the URL — not a per-value
|
|
15
|
+
* cap. Default mode (`'key-update'`, also what an unset field resolves to)
|
|
16
|
+
* caps at 2; `'zk'` at 12. At or under the budget the overlap is genuinely
|
|
17
|
+
* hidden; over it, the value (or the combination of values) is effectively
|
|
18
|
+
* still visible to the attestor regardless of secret-marking. */
|
|
19
|
+
export declare function secretUrlCharBudget(writeRedactionMode: ReclaimProvider['writeRedactionMode']): number;
|
|
20
|
+
/** A `paramValues`/context key is secret iff its name contains `SECRET`
|
|
21
|
+
* (case-insensitive) — e.g. `SECRET_apiKey`, `context.SECRET_apiKey`. Same
|
|
22
|
+
* naming-convention classifier reclaim-inapp-sdk and reclaim-portal use for
|
|
23
|
+
* their `witnessParams`/`paramValues` maps (no separate boolean flag). */
|
|
24
|
+
export declare function classifyParamName(name: string): boolean;
|
|
25
|
+
/** Split a `paramValues` map (bare `{{name}}` / `{{context.<name>}}` entries)
|
|
26
|
+
* into public (→ `params.paramValues`, revealed to the attestor) and secret
|
|
27
|
+
* (→ `secretParams.paramValues`) by {@link classifyParamName}. A secret
|
|
28
|
+
* value used in the URL is still hidden — up to {@link secretUrlCharBudget}
|
|
29
|
+
* characters, summed across every such value in that URL. */
|
|
30
|
+
export declare function splitSecretParamValues(paramValues: Record<string, string>): {
|
|
31
|
+
secrets: Record<string, string>;
|
|
32
|
+
publics: Record<string, string>;
|
|
33
|
+
};
|
|
34
|
+
/** Reject a proof attempt whose URL/geoLocation templates SECRET-named
|
|
35
|
+
* context param(s) whose ACTUAL values (now known — the consumer supplied
|
|
36
|
+
* them at session-create) exceed the write-redaction budget once summed.
|
|
37
|
+
* Structural placement (which params end up in the URL) is knowable at
|
|
38
|
+
* publish time and isn't rejected there — only the real values decide
|
|
39
|
+
* whether it fits, and those only exist once a verification session is
|
|
40
|
+
* underway. Checks the placeholder TOKEN (`{{<key>}}`), not a value search —
|
|
41
|
+
* the URL/geoLocation explicitly reference the param by name. */
|
|
42
|
+
export declare function assertSecretParamValuesFitUrlBudget(url: string, geoLocation: string | undefined, secretParamValues: Record<string, string>, writeRedactionMode: ReclaimProvider['writeRedactionMode']): void;
|
package/lib/provider/secrets.js
CHANGED
|
@@ -1,11 +1,89 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
/** Headers safe to reveal to the attestor unredacted — everything else
|
|
2
|
+
* (`Cookie`, `Authorization`, any custom header, even ones that look inert
|
|
3
|
+
* like `Content-Type`) is secret by default. Allowlist, not a denylist:
|
|
4
|
+
* same exact list `reclaim-inapp-sdk` (`_PUBLIC_HEADERS_ALLOW_LIST`,
|
|
5
|
+
* `request.dart`) and `reclaim-portal` (`DEFAULT_PUBLIC_HEADERS`,
|
|
6
|
+
* `claim-builder.ts`) use for their own `witnessParams`/header split. */
|
|
7
|
+
const PUBLIC_HEADERS = new Set([
|
|
8
|
+
'user-agent',
|
|
9
|
+
'accept',
|
|
10
|
+
'accept-language',
|
|
11
|
+
'accept-encoding',
|
|
12
|
+
'sec-fetch-mode',
|
|
13
|
+
'sec-fetch-site',
|
|
14
|
+
'sec-fetch-user',
|
|
15
|
+
'origin',
|
|
16
|
+
'x-requested-with',
|
|
17
|
+
'sec-ch-ua',
|
|
18
|
+
'sec-ch-ua-mobile',
|
|
19
|
+
]);
|
|
3
20
|
export function classifyHeader(name) {
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
21
|
+
return !PUBLIC_HEADERS.has(name.toLowerCase());
|
|
22
|
+
}
|
|
23
|
+
/** Headers that must NOT survive into EITHER the public or secret side —
|
|
24
|
+
* structural/transport, never a credential. Three kinds:
|
|
25
|
+
* - Conditional headers (`if-none-match`/`if-modified-since`/…): a captured
|
|
26
|
+
* cached ETag/date makes the origin answer 304/412 when the attestor
|
|
27
|
+
* re-issues, and the attestor treats non-2xx as failure. We always want
|
|
28
|
+
* the full fresh response.
|
|
29
|
+
* - Transfer headers the ATTESTOR sets itself (`connection: close`,
|
|
30
|
+
* `accept-encoding: identity`). Passing our own duplicates/collides with
|
|
31
|
+
* the request the attestor builds, so leave them out.
|
|
32
|
+
* - Host / framing headers the TRANSPORT owns (`host`, `content-length`,
|
|
33
|
+
* `transfer-encoding`). The attestor derives `Host` from the URL and sets
|
|
34
|
+
* its own; a baked `Host` produces a DUPLICATE that fails the receipt
|
|
35
|
+
* check / 400s the origin. A stale `content-length` breaks a
|
|
36
|
+
* re-serialized body.
|
|
37
|
+
* Must be stripped BEFORE `splitSecrets`, not after: under the allowlist
|
|
38
|
+
* classifier these all fall into `secrets` (none are on `PUBLIC_HEADERS`),
|
|
39
|
+
* and a header like `Host` — whose value trivially mirrors the URL's
|
|
40
|
+
* hostname, by definition — would trip a URL-conflict check on a
|
|
41
|
+
* structural, not a privacy, coincidence. */
|
|
42
|
+
const STRIP_REQUEST_HEADERS = new Set([
|
|
43
|
+
'if-none-match',
|
|
44
|
+
'if-modified-since',
|
|
45
|
+
'if-match',
|
|
46
|
+
'if-unmodified-since',
|
|
47
|
+
'if-range',
|
|
48
|
+
'connection',
|
|
49
|
+
'accept-encoding',
|
|
50
|
+
'host',
|
|
51
|
+
'content-length',
|
|
52
|
+
'transfer-encoding',
|
|
53
|
+
// Per-session anti-CSRF tokens: never portable (baking one in replays a
|
|
54
|
+
// single captured user's token for everyone, which the origin rejects).
|
|
55
|
+
// The allowlist classifier already routes these to `secrets` — a proof
|
|
56
|
+
// attempt sends the CURRENT user's own captured value, which is correct —
|
|
57
|
+
// but stripping them here means they never even take that path, and
|
|
58
|
+
// definitely never survive into a persisted, public recipe.
|
|
59
|
+
'csrf',
|
|
60
|
+
'x-csrf',
|
|
61
|
+
'xsrf',
|
|
62
|
+
'x-xsrf',
|
|
63
|
+
'x-csrf-token',
|
|
64
|
+
'xsrf-token',
|
|
65
|
+
]);
|
|
66
|
+
/** True for an HTTP/2 pseudo-header (`:authority`, `:method`, `:path`,
|
|
67
|
+
* `:scheme`, which CDP surfaces on h2 captures) — never a valid request
|
|
68
|
+
* header the attestor can replay. Same BEFORE-the-split reasoning as
|
|
69
|
+
* {@link STRIP_REQUEST_HEADERS}. */
|
|
70
|
+
function isPseudoHeader(name) {
|
|
71
|
+
return name.startsWith(':');
|
|
72
|
+
}
|
|
73
|
+
/** Drop {@link STRIP_REQUEST_HEADERS} and HTTP/2 pseudo-headers. Call this on
|
|
74
|
+
* the RAW captured headers before {@link splitSecrets} — both the draft-time
|
|
75
|
+
* authoring flow and the live per-user verification capture need it, so
|
|
76
|
+
* neither ends up sending a duplicate `Host` or an invalid `:authority` to
|
|
77
|
+
* the attestor via either the public or the secret channel. */
|
|
78
|
+
export function stripTransportHeaders(headers) {
|
|
79
|
+
const out = {};
|
|
80
|
+
for (const [k, v] of Object.entries(headers)) {
|
|
81
|
+
if (STRIP_REQUEST_HEADERS.has(k.toLowerCase()) || isPseudoHeader(k)) {
|
|
82
|
+
continue;
|
|
83
|
+
}
|
|
84
|
+
out[k] = v;
|
|
7
85
|
}
|
|
8
|
-
return
|
|
86
|
+
return out;
|
|
9
87
|
}
|
|
10
88
|
export function splitSecrets(headers) {
|
|
11
89
|
const secrets = {};
|
|
@@ -20,3 +98,66 @@ export function splitSecrets(headers) {
|
|
|
20
98
|
}
|
|
21
99
|
return { secrets, publics };
|
|
22
100
|
}
|
|
101
|
+
/** Total characters write-redaction can hide from the attestor, summed
|
|
102
|
+
* ACROSS EVERY secret-classified value used in the URL — not a per-value
|
|
103
|
+
* cap. Default mode (`'key-update'`, also what an unset field resolves to)
|
|
104
|
+
* caps at 2; `'zk'` at 12. At or under the budget the overlap is genuinely
|
|
105
|
+
* hidden; over it, the value (or the combination of values) is effectively
|
|
106
|
+
* still visible to the attestor regardless of secret-marking. */
|
|
107
|
+
export function secretUrlCharBudget(writeRedactionMode) {
|
|
108
|
+
return writeRedactionMode === 'zk' ? 12 : 2;
|
|
109
|
+
}
|
|
110
|
+
/** A `paramValues`/context key is secret iff its name contains `SECRET`
|
|
111
|
+
* (case-insensitive) — e.g. `SECRET_apiKey`, `context.SECRET_apiKey`. Same
|
|
112
|
+
* naming-convention classifier reclaim-inapp-sdk and reclaim-portal use for
|
|
113
|
+
* their `witnessParams`/`paramValues` maps (no separate boolean flag). */
|
|
114
|
+
export function classifyParamName(name) {
|
|
115
|
+
return name.toUpperCase().includes('SECRET');
|
|
116
|
+
}
|
|
117
|
+
/** Split a `paramValues` map (bare `{{name}}` / `{{context.<name>}}` entries)
|
|
118
|
+
* into public (→ `params.paramValues`, revealed to the attestor) and secret
|
|
119
|
+
* (→ `secretParams.paramValues`) by {@link classifyParamName}. A secret
|
|
120
|
+
* value used in the URL is still hidden — up to {@link secretUrlCharBudget}
|
|
121
|
+
* characters, summed across every such value in that URL. */
|
|
122
|
+
export function splitSecretParamValues(paramValues) {
|
|
123
|
+
const secrets = {};
|
|
124
|
+
const publics = {};
|
|
125
|
+
for (const [k, v] of Object.entries(paramValues)) {
|
|
126
|
+
if (classifyParamName(k)) {
|
|
127
|
+
secrets[k] = v;
|
|
128
|
+
}
|
|
129
|
+
else {
|
|
130
|
+
publics[k] = v;
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
return { secrets, publics };
|
|
134
|
+
}
|
|
135
|
+
/** Reject a proof attempt whose URL/geoLocation templates SECRET-named
|
|
136
|
+
* context param(s) whose ACTUAL values (now known — the consumer supplied
|
|
137
|
+
* them at session-create) exceed the write-redaction budget once summed.
|
|
138
|
+
* Structural placement (which params end up in the URL) is knowable at
|
|
139
|
+
* publish time and isn't rejected there — only the real values decide
|
|
140
|
+
* whether it fits, and those only exist once a verification session is
|
|
141
|
+
* underway. Checks the placeholder TOKEN (`{{<key>}}`), not a value search —
|
|
142
|
+
* the URL/geoLocation explicitly reference the param by name. */
|
|
143
|
+
export function assertSecretParamValuesFitUrlBudget(url, geoLocation, secretParamValues, writeRedactionMode) {
|
|
144
|
+
const haystack = `${url}\n${geoLocation ?? ''}`;
|
|
145
|
+
let redactedChars = 0;
|
|
146
|
+
const used = [];
|
|
147
|
+
for (const [key, value] of Object.entries(secretParamValues)) {
|
|
148
|
+
if (haystack.includes(`{{${key}}}`)) {
|
|
149
|
+
redactedChars += value.length;
|
|
150
|
+
used.push(key);
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
const budget = secretUrlCharBudget(writeRedactionMode);
|
|
154
|
+
if (redactedChars > budget) {
|
|
155
|
+
throw new Error(`secret context param(s) ${used.map((k) => `"${k}"`).join(', ')} `
|
|
156
|
+
+ `are templated into the URL/geoLocation ("${url}") with a `
|
|
157
|
+
+ `combined value length of ${redactedChars} character(s) — over `
|
|
158
|
+
+ `the ${budget}-character budget write-redaction `
|
|
159
|
+
+ `(${writeRedactionMode ?? 'key-update'}) can actually hide there. `
|
|
160
|
+
+ "Ask the consumer for a shorter value, switch to 'zk' if that "
|
|
161
|
+
+ 'raises the budget enough, or move this param to the body.');
|
|
162
|
+
}
|
|
163
|
+
}
|
|
@@ -72,6 +72,13 @@ export interface CreateVersionOptions {
|
|
|
72
72
|
* recipe can never reference a context value the Builder doesn't require.
|
|
73
73
|
* Returns undefined when nothing references context (the field is optional).
|
|
74
74
|
* Authors can refine types/descriptions in the version editor.
|
|
75
|
+
*
|
|
76
|
+
* A SECRET-named context param (see `classifyParamName`) is NOT rejected here
|
|
77
|
+
* even when it's templated into the URL/geoLocation — write-redaction can
|
|
78
|
+
* still hide it there, up to `secretUrlCharBudget` characters (summed across
|
|
79
|
+
* every such value in that URL). Whether it actually fits is only knowable
|
|
80
|
+
* once a real value exists, so that check runs at verification time
|
|
81
|
+
* (`verify/run.ts`), against the consumer's actual supplied value — not here.
|
|
75
82
|
*/
|
|
76
83
|
export declare function deriveRequiredContext(providers: ReclaimProvider[], injection?: {
|
|
77
84
|
allowedJsRequests?: AllowedJsRequest[];
|
|
@@ -22,10 +22,20 @@ const CONTEXT_PARAM_RE = /\{\{context\.([A-Za-z_][A-Za-z0-9_]*)\}\}/g;
|
|
|
22
22
|
* recipe can never reference a context value the Builder doesn't require.
|
|
23
23
|
* Returns undefined when nothing references context (the field is optional).
|
|
24
24
|
* Authors can refine types/descriptions in the version editor.
|
|
25
|
+
*
|
|
26
|
+
* A SECRET-named context param (see `classifyParamName`) is NOT rejected here
|
|
27
|
+
* even when it's templated into the URL/geoLocation — write-redaction can
|
|
28
|
+
* still hide it there, up to `secretUrlCharBudget` characters (summed across
|
|
29
|
+
* every such value in that URL). Whether it actually fits is only knowable
|
|
30
|
+
* once a real value exists, so that check runs at verification time
|
|
31
|
+
* (`verify/run.ts`), against the consumer's actual supplied value — not here.
|
|
25
32
|
*/
|
|
26
33
|
export function deriveRequiredContext(providers, injection = {}) {
|
|
27
34
|
const parts = [];
|
|
28
|
-
for (const p of
|
|
35
|
+
for (const p of providers) {
|
|
36
|
+
parts.push(p.url, p.body ?? '');
|
|
37
|
+
}
|
|
38
|
+
for (const p of injection.allowedJsRequests ?? []) {
|
|
29
39
|
parts.push(p.url, p.body ?? '');
|
|
30
40
|
}
|
|
31
41
|
if (injection.jsUserScripts) {
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@reclaimprotocol/agent",
|
|
3
3
|
"title": "Reclaim Agent",
|
|
4
|
-
"version": "0.1.
|
|
4
|
+
"version": "0.1.20",
|
|
5
5
|
"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.",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"main": "./lib/index.js",
|
|
@@ -83,7 +83,7 @@
|
|
|
83
83
|
"@modelcontextprotocol/sdk": "^1.29.0",
|
|
84
84
|
"@noble/hashes": "^2.2.0",
|
|
85
85
|
"@reclaimprotocol/attestor-core": "^5.0.8",
|
|
86
|
-
"@reclaimprotocol/client": "0.1.
|
|
86
|
+
"@reclaimprotocol/client": "0.1.20",
|
|
87
87
|
"@reclaimprotocol/tls": "^0.1.3",
|
|
88
88
|
"chrome-remote-interface": "^0.33.0",
|
|
89
89
|
"domhandler": "^6.0.0",
|