@reclaimprotocol/agent 0.1.27 → 0.1.28

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.
Files changed (92) hide show
  1. package/README.md +5 -5
  2. package/lib/authoring/tools.js +2 -1
  3. package/lib/consts.d.ts +1 -1
  4. package/lib/consts.js +1 -1
  5. package/lib/live/tunnel.d.ts +4 -0
  6. package/lib/live/tunnel.js +21 -12
  7. package/lib/mcp/api/operations.gen.d.ts +8 -8
  8. package/lib/mcp/api/operations.gen.js +339 -581
  9. package/lib/mcp/api/tools.d.ts +1 -1
  10. package/lib/mcp/instructions.js +5 -3
  11. package/lib/mcp/remap_errors.js +9 -5
  12. package/lib/mcp/start.js +1 -1
  13. package/lib/mcp/tools/agent/attach.d.ts +2 -2
  14. package/lib/mcp/tools/agent/attach.js +4 -0
  15. package/lib/mcp/tools/agent/build.d.ts +1 -1
  16. package/lib/mcp/tools/agent/live-view-url.d.ts +2 -0
  17. package/lib/mcp/tools/agent/live-view-url.js +11 -0
  18. package/lib/mcp/tools/agent/live-view.d.ts +4 -2
  19. package/lib/mcp/tools/agent/live-view.js +42 -39
  20. package/lib/mcp/tools/agent/propose.js +10 -4
  21. package/lib/mcp/tools/agent/publish.d.ts +1 -1
  22. package/lib/mcp/tools/agent/publish.js +49 -26
  23. package/lib/mcp/tools/agent/shared.js +0 -9
  24. package/lib/mcp/tools/authenticate/authenticate.d.ts +1 -1
  25. package/lib/mcp/tools/authenticate/build.d.ts +1 -1
  26. package/lib/mcp/tools/authenticate/builder-access.d.ts +1 -1
  27. package/lib/mcp/tools/verification/result.js +12 -13
  28. package/lib/old/login-cdp.d.ts +17 -6
  29. package/lib/old/login-cdp.js +28 -11
  30. package/lib/old/to-register.d.ts +6 -0
  31. package/lib/old/to-register.js +35 -5
  32. package/lib/old/tools/authenticate.d.ts +5 -4
  33. package/lib/old/tools/authenticate.js +9 -5
  34. package/lib/old/tools/publish.d.ts +2 -2
  35. package/lib/old/tools/publish.js +47 -21
  36. package/lib/proof/attestor-auth.d.ts +13 -0
  37. package/lib/proof/attestor-auth.js +16 -0
  38. package/lib/proof/attestor.d.ts +7 -4
  39. package/lib/proof/attestor.js +7 -4
  40. package/lib/proof/index.d.ts +1 -0
  41. package/lib/proof/index.js +1 -0
  42. package/lib/proof/pod-prover.d.ts +2 -0
  43. package/lib/proof/pod-prover.js +5 -5
  44. package/lib/provider/injection-doc.d.ts +2 -0
  45. package/lib/provider/injection-doc.js +7 -1
  46. package/lib/provider/post-publish-browser.d.ts +12 -0
  47. package/lib/provider/post-publish-browser.js +40 -0
  48. package/lib/provider/to-version.d.ts +19 -7
  49. package/lib/provider/to-version.js +67 -25
  50. package/lib/tools/registry.d.ts +1 -1
  51. package/lib/tools/registry.js +7 -4
  52. package/package.json +2 -2
  53. package/skill/SKILL.builder.md +118 -13
  54. package/skill/SKILL.common.md +30 -19
  55. package/skill/SKILL.old.md +22 -12
  56. package/skill/builder-mode.md +19 -9
  57. package/skill/community-contributions.md +108 -0
  58. package/skill/hash-validation.md +8 -5
  59. package/skill/interception.md +35 -22
  60. package/skill/old-mode.md +11 -5
  61. package/skill/user-script.md +41 -10
  62. package/src/authoring/tools.ts +2 -1
  63. package/src/consts.ts +1 -2
  64. package/src/live/tunnel.ts +28 -14
  65. package/src/mcp/api/operations.gen.ts +341 -585
  66. package/src/mcp/api/tools.ts +1 -1
  67. package/src/mcp/instructions.ts +5 -3
  68. package/src/mcp/remap_errors.ts +9 -7
  69. package/src/mcp/start.ts +1 -1
  70. package/src/mcp/tools/agent/attach.ts +6 -2
  71. package/src/mcp/tools/agent/build.ts +1 -1
  72. package/src/mcp/tools/agent/live-view-url.ts +13 -0
  73. package/src/mcp/tools/agent/live-view.ts +44 -39
  74. package/src/mcp/tools/agent/propose.ts +10 -4
  75. package/src/mcp/tools/agent/publish.ts +63 -28
  76. package/src/mcp/tools/agent/shared.ts +5 -0
  77. package/src/mcp/tools/authenticate/authenticate.ts +1 -1
  78. package/src/mcp/tools/authenticate/build.ts +1 -1
  79. package/src/mcp/tools/authenticate/builder-access.ts +1 -1
  80. package/src/mcp/tools/verification/result.ts +11 -13
  81. package/src/old/login-cdp.ts +38 -11
  82. package/src/old/to-register.ts +56 -7
  83. package/src/old/tools/authenticate.ts +9 -5
  84. package/src/old/tools/publish.ts +64 -22
  85. package/src/proof/attestor-auth.ts +33 -0
  86. package/src/proof/attestor.ts +14 -8
  87. package/src/proof/index.ts +4 -0
  88. package/src/proof/pod-prover.ts +7 -5
  89. package/src/provider/injection-doc.ts +9 -1
  90. package/src/provider/post-publish-browser.ts +56 -0
  91. package/src/provider/to-version.ts +104 -27
  92. package/src/tools/registry.ts +12 -9
@@ -1,6 +1,6 @@
1
1
  // AUTO-GENERATED by packages/app/scripts/mcp-tools-gen.ts
2
2
  // from packages/app/openapi.yaml.
3
- // Run `npm run openapi:typegen --workspace=packages/agent`
3
+ // Run `npm run openapi:gen --workspace=packages/app`
4
4
  // to regenerate. Do not edit by hand.
5
5
  // @ts-nocheck
6
6
 
@@ -204,12 +204,13 @@ export const MCP_TOOLS = {
204
204
  },
205
205
  "status": {
206
206
  "type": "string",
207
- "description": "Status of a verification session, derived from its events. New values\nmay be added over time; clients MUST tolerate unknown values in\nresponses.\n\n- `pending`: Created, not yet finished; completable until `expiresAt`.\n\n- `success`: Terminal — `verification_success` recorded.\n\n- `rejected`: Terminal — `verification_rejected` recorded.\n\n- `error`: Terminal — `verification_error` recorded.\n\n- `expired`: `expiresAt` passed before a terminal event; the end-user\n can no longer complete it.",
207
+ "description": "Status of a verification session, derived from its events. New values\nmay be added over time; clients MUST tolerate unknown values in\nresponses.\n\n- `pending`: Created, not yet finished; completable until `expiresAt`.\n\n- `success`: Terminal — `verification_success` recorded.\n\n- `rejected`: Terminal — `verification_rejected` recorded.\n\n- `error`: Terminal — `verification_error` recorded.\n\n- `cancelled`: Terminal — `verification_cancelled` recorded.\n\n- `expired`: `expiresAt` passed before a terminal event; the end-user\n can no longer complete it.",
208
208
  "enum": [
209
209
  "pending",
210
210
  "success",
211
211
  "rejected",
212
212
  "error",
213
+ "cancelled",
213
214
  "expired"
214
215
  ]
215
216
  },
@@ -234,6 +235,115 @@ export const MCP_TOOLS = {
234
235
  "additionalProperties": false
235
236
  }),
236
237
  },
238
+ "BindVerificationSessionTeeNonce": {
239
+ description: "Bind a legacy-compatible TEE nonce to a verification session\n\nBinds one immutable legacy TEE nonce context to a pending session. Requires an OrgToken and an EIP-191 signature from the organization's registered verification key. Repeating the exact binding is idempotent; conflicting or terminal sessions return 409.",
240
+ inputSchema: toZod({
241
+ "type": "object",
242
+ "properties": {
243
+ "params": {
244
+ "type": "object",
245
+ "properties": {
246
+ "sessionId": {
247
+ "type": "string",
248
+ "format": "uuid",
249
+ "description": "Verification session id (UUID v7 when supported). Also echoed in the result payload as `reclaimSessionId`."
250
+ }
251
+ },
252
+ "required": [
253
+ "sessionId"
254
+ ],
255
+ "additionalProperties": false
256
+ },
257
+ "query": {
258
+ "type": "object",
259
+ "properties": {
260
+
261
+ }
262
+ },
263
+ "body": {
264
+ "type": "object",
265
+ "additionalProperties": false,
266
+ "description": "One immutable legacy TEE context, signed by the organization verification key. The signature is EIP-191 `personal_sign` over `RECLAIM_BUILDER_TEE_BINDING_V1:{organizationId}:{sessionId}:{applicationId}:{timestamp}:{attestationVersion}:{attestationNonce}`.",
267
+ "required": [
268
+ "attestationNonce",
269
+ "attestationNonceData",
270
+ "signature"
271
+ ],
272
+ "properties": {
273
+ "attestationNonce": {
274
+ "description": "Either the current lowercase 64-hex hash nonce (without `0x`) or the older 65-byte EIP-191 signature nonce (`0x` plus 130 hex characters). Builder preserves either encoding unchanged.",
275
+ "oneOf": [
276
+ {
277
+ "type": "string",
278
+ "pattern": "^[0-9a-f]{64}$",
279
+ "minLength": 64,
280
+ "maxLength": 64
281
+ },
282
+ {
283
+ "type": "string",
284
+ "pattern": "^0x[0-9a-fA-F]{130}$",
285
+ "minLength": 132,
286
+ "maxLength": 132
287
+ }
288
+ ]
289
+ },
290
+ "attestationNonceData": {
291
+ "type": "object",
292
+ "additionalProperties": false,
293
+ "description": "Exact legacy TEE nonce inputs. Builder stores this unchanged in the session context after it verifies the signed binding request.",
294
+ "required": [
295
+ "applicationId",
296
+ "sessionId",
297
+ "timestamp",
298
+ "attestationVersion"
299
+ ],
300
+ "properties": {
301
+ "applicationId": {
302
+ "type": "string",
303
+ "description": "Ethereum application address derived from the organization private key. Its supplied casing is preserved for legacy nonce compatibility.",
304
+ "pattern": "^0x[0-9a-fA-F]{40}$",
305
+ "minLength": 42,
306
+ "maxLength": 42
307
+ },
308
+ "sessionId": {
309
+ "type": "string",
310
+ "format": "uuid",
311
+ "description": "Verification session id (UUID v7 when supported). Also echoed in the result payload as `reclaimSessionId`."
312
+ },
313
+ "timestamp": {
314
+ "type": "string",
315
+ "description": "Decimal Unix timestamp in milliseconds.",
316
+ "pattern": "^[0-9]{13}$",
317
+ "minLength": 13,
318
+ "maxLength": 13
319
+ },
320
+ "attestationVersion": {
321
+ "type": "string",
322
+ "description": "Legacy SDK TEE attestation protocol version.",
323
+ "enum": [
324
+ "v3"
325
+ ]
326
+ }
327
+ }
328
+ },
329
+ "signature": {
330
+ "type": "string",
331
+ "description": "EIP-191 65-byte secp256k1 signature, encoded as 0x-prefixed hex.",
332
+ "pattern": "^0x[0-9a-fA-F]{130}$",
333
+ "minLength": 132,
334
+ "maxLength": 132
335
+ }
336
+ }
337
+ }
338
+ },
339
+ "required": [
340
+ "params",
341
+ "query",
342
+ "body"
343
+ ],
344
+ "additionalProperties": false
345
+ }),
346
+ },
237
347
  "CancelPublicListingRequest": {
238
348
  description: "Cancel a pending public listing review request\n\nCancels a pending public listing request by moving the version from `in_review` back to `draft`. Only org members can cancel their own review requests. This allows users to withdraw a request before admin review if they change their mind.",
239
349
  inputSchema: toZod({
@@ -313,26 +423,65 @@ export const MCP_TOOLS = {
313
423
  "properties": {
314
424
  "callbackUrl": {
315
425
  "type": "string",
316
- "format": "uri",
426
+ "pattern": "^https?://",
427
+ "description": "Callback URL or template. Supported placeholders are `{{sessionId}}` and top-level scalar context keys.",
317
428
  "maxLength": 2000
318
429
  },
319
430
  "events": {
320
431
  "type": "array",
321
432
  "minItems": 1,
322
- "maxItems": 12,
433
+ "maxItems": 50,
323
434
  "items": {
324
435
  "type": "string",
325
- "description": "Lifecycle event reported for a verification session. A healthy run\nproceeds through these in order; reading the gaps locates where a\nsession stalled. Session-level terminal events trigger callback\ndelivery; provider-/request-level events are progress pings carrying a\n`provider_id` (and `request_id` for request-level ones) in their event\ndata. New values may be added over time; clients MUST tolerate unknown\nvalues in responses.\n\n- `session_pending`: Session created; awaiting the end-user.\n\n- `verification_client_opened`: The end-user opened the link. Absent ⇒\n the link was never opened.\n\n- `verification_client_ready`: The client initialized.\n\n- `verification_provider_started`: The client began verifying a provider\n (`provider_id`/`resolved_version`/`ordinal` in `eventData`). One per\n provider, in run order, for multi-provider sessions.\n\n- `request_matched`: The target request was captured on the provider\n site. Absent (after opened) ⇒ the user didn't complete the journey.\n\n- `request_claim_created`: A proof claim was started.\n\n- `request_claim_completed`: A proof claim finished.\n\n- `request_claim_rejected`: A claim was rejected (detail in `eventData`).\n\n- `request_claim_failed`: A claim errored (detail in `eventData`).\n\n- `verification_success`: Terminal — verified. Triggers callback delivery.\n\n- `verification_rejected`: Terminal — rejected (detail in `eventData`).\n\n- `verification_error`: Terminal — errored (detail in `eventData`).\n\n- `session_expired`: `expiresAt` passed before a terminal event.",
436
+ "description": "Canonical Builder lifecycle event. Names use lower snake case; metadata uses camel case. Provider events include providerId, resolvedVersion, and ordinal. Request events also include requestId. New values are additive, so clients must tolerate unknown response values. For field requirements and funnel semantics, see docs/verification-analytics-events.md.",
326
437
  "enum": [
438
+ "billing_required",
327
439
  "session_pending",
328
440
  "verification_client_opened",
329
441
  "verification_client_ready",
442
+ "verification_client_warning",
443
+ "verification_client_visibility_shown",
444
+ "verification_client_visibility_hidden",
445
+ "verification_diagnostics_mode_changed",
446
+ "verification_cancelled",
447
+ "consent_viewed",
448
+ "consent_scrolled",
449
+ "consent_agreed",
450
+ "verification_browser_started",
451
+ "verification_browser_ready",
452
+ "verification_browser_reconnect_started",
453
+ "verification_browser_reconnected",
454
+ "verification_browser_failed",
330
455
  "verification_provider_started",
456
+ "provider_config",
457
+ "provider_script_log",
458
+ "network_request_observed",
459
+ "verification_page_ready",
460
+ "verification_request_interceptor_ready",
461
+ "verification_provider_completed",
462
+ "auth_required",
463
+ "auth_submitted",
464
+ "auth_challenge_remains",
465
+ "auth_rejected",
466
+ "auth_submission_failed",
467
+ "auth_challenge_completed",
468
+ "auth_gate_not_detected",
469
+ "authenticated",
470
+ "user_interaction_started",
471
+ "user_input_started",
472
+ "user_interaction_summary",
473
+ "verification_inactivity_detected",
331
474
  "request_matched",
475
+ "request_match_failed",
476
+ "request_claim_parameters_captured",
332
477
  "request_claim_created",
478
+ "request_claim_retrying",
333
479
  "request_claim_completed",
334
480
  "request_claim_rejected",
335
481
  "request_claim_failed",
482
+ "verification_proofs_completed",
483
+ "verification_result_submitting",
484
+ "verification_result_submission_failed",
336
485
  "verification_success",
337
486
  "verification_rejected",
338
487
  "verification_error",
@@ -393,7 +542,7 @@ export const MCP_TOOLS = {
393
542
  }),
394
543
  },
395
544
  "CreateOrgCallbackSubscription": {
396
- description: "Register a callback subscription on an organization\n\nRegisters a destination for verification results on the organization. Caller must be an active member of the org. The body is just `callbackUrl` and `events`; delivery is scoped to the org and encrypted as a compact JWE to the org's encryption credential when set, else delivered as plaintext.",
545
+ description: "Register a callback subscription on an organization\n\nRegisters an organization callback subscription. Pass the callback URL and events to deliver. Builder encrypts signed results when the organization enables result encryption.",
397
546
  inputSchema: toZod({
398
547
  "type": "object",
399
548
  "properties": {
@@ -427,26 +576,65 @@ export const MCP_TOOLS = {
427
576
  "properties": {
428
577
  "callbackUrl": {
429
578
  "type": "string",
430
- "format": "uri",
579
+ "pattern": "^https?://",
580
+ "description": "Callback URL or template. Supported placeholders are `{{sessionId}}` and top-level scalar context keys.",
431
581
  "maxLength": 2000
432
582
  },
433
583
  "events": {
434
584
  "type": "array",
435
585
  "minItems": 1,
436
- "maxItems": 12,
586
+ "maxItems": 50,
437
587
  "items": {
438
588
  "type": "string",
439
- "description": "Lifecycle event reported for a verification session. A healthy run\nproceeds through these in order; reading the gaps locates where a\nsession stalled. Session-level terminal events trigger callback\ndelivery; provider-/request-level events are progress pings carrying a\n`provider_id` (and `request_id` for request-level ones) in their event\ndata. New values may be added over time; clients MUST tolerate unknown\nvalues in responses.\n\n- `session_pending`: Session created; awaiting the end-user.\n\n- `verification_client_opened`: The end-user opened the link. Absent ⇒\n the link was never opened.\n\n- `verification_client_ready`: The client initialized.\n\n- `verification_provider_started`: The client began verifying a provider\n (`provider_id`/`resolved_version`/`ordinal` in `eventData`). One per\n provider, in run order, for multi-provider sessions.\n\n- `request_matched`: The target request was captured on the provider\n site. Absent (after opened) ⇒ the user didn't complete the journey.\n\n- `request_claim_created`: A proof claim was started.\n\n- `request_claim_completed`: A proof claim finished.\n\n- `request_claim_rejected`: A claim was rejected (detail in `eventData`).\n\n- `request_claim_failed`: A claim errored (detail in `eventData`).\n\n- `verification_success`: Terminal — verified. Triggers callback delivery.\n\n- `verification_rejected`: Terminal — rejected (detail in `eventData`).\n\n- `verification_error`: Terminal — errored (detail in `eventData`).\n\n- `session_expired`: `expiresAt` passed before a terminal event.",
589
+ "description": "Canonical Builder lifecycle event. Names use lower snake case; metadata uses camel case. Provider events include providerId, resolvedVersion, and ordinal. Request events also include requestId. New values are additive, so clients must tolerate unknown response values. For field requirements and funnel semantics, see docs/verification-analytics-events.md.",
440
590
  "enum": [
591
+ "billing_required",
441
592
  "session_pending",
442
593
  "verification_client_opened",
443
594
  "verification_client_ready",
595
+ "verification_client_warning",
596
+ "verification_client_visibility_shown",
597
+ "verification_client_visibility_hidden",
598
+ "verification_diagnostics_mode_changed",
599
+ "verification_cancelled",
600
+ "consent_viewed",
601
+ "consent_scrolled",
602
+ "consent_agreed",
603
+ "verification_browser_started",
604
+ "verification_browser_ready",
605
+ "verification_browser_reconnect_started",
606
+ "verification_browser_reconnected",
607
+ "verification_browser_failed",
444
608
  "verification_provider_started",
609
+ "provider_config",
610
+ "provider_script_log",
611
+ "network_request_observed",
612
+ "verification_page_ready",
613
+ "verification_request_interceptor_ready",
614
+ "verification_provider_completed",
615
+ "auth_required",
616
+ "auth_submitted",
617
+ "auth_challenge_remains",
618
+ "auth_rejected",
619
+ "auth_submission_failed",
620
+ "auth_challenge_completed",
621
+ "auth_gate_not_detected",
622
+ "authenticated",
623
+ "user_interaction_started",
624
+ "user_input_started",
625
+ "user_interaction_summary",
626
+ "verification_inactivity_detected",
445
627
  "request_matched",
628
+ "request_match_failed",
629
+ "request_claim_parameters_captured",
446
630
  "request_claim_created",
631
+ "request_claim_retrying",
447
632
  "request_claim_completed",
448
633
  "request_claim_rejected",
449
634
  "request_claim_failed",
635
+ "verification_proofs_completed",
636
+ "verification_result_submitting",
637
+ "verification_result_submission_failed",
450
638
  "verification_success",
451
639
  "verification_rejected",
452
640
  "verification_error",
@@ -599,7 +787,7 @@ export const MCP_TOOLS = {
599
787
  }),
600
788
  },
601
789
  "CreateProviderVersion": {
602
- description: "Create a new provider version\n\nCreates a new version of the provider. The starting branch\ndepends on the provider's `visibility` and the caller's role:\n\n- `PRIVATE` provider (any caller): the live channel (no review).\n\n- `PUBLIC` provider, admin caller (Reclaim staff): the live channel\n (no review).\n\n- `PUBLIC` provider, non-admin caller: `draft` (or `ai` if\n authored by the AI assistant). Must pass review (see\n `POST /providers/{id}/versions/{version}/review`) before\n reaching the live channel.\n",
790
+ description: "Create a new provider version\n\nCreates a new immutable semantic version of the provider. Provider\nauthoring clients must create another version for every content change;\nthey must not edit a previously created version in place. Use a patch\nbump by default, or use a major/minor bump or exact higher version when\nthe user directs it. The starting branch\ndepends on the provider's `visibility` and the caller's role:\n\n- `PRIVATE` provider (any caller): the live channel (no review).\n\n- `PUBLIC` provider, admin caller (Reclaim staff): the live channel\n (no review).\n\n- `PUBLIC` provider, non-admin caller: `draft` (or `ai` if\n authored by the AI assistant). Must pass review (see\n `POST /providers/{id}/versions/{version}/review`) before\n reaching the live channel.\n",
603
791
  inputSchema: toZod({
604
792
  "type": "object",
605
793
  "properties": {
@@ -725,6 +913,15 @@ export const MCP_TOOLS = {
725
913
  "description": "Template used to match or capture an outgoing request body. Template can use regex templates as placeholders. For example, to match an outgoing request body that contains a request ID, you can use the following template: `(?<requestId>.*)`.",
726
914
  "maxLength": 100000
727
915
  },
916
+ "headers": {
917
+ "type": "object",
918
+ "additionalProperties": {
919
+ "type": "string",
920
+ "maxLength": 16000
921
+ },
922
+ "maxProperties": 100,
923
+ "description": "Static HTTP request headers passed to the attestor. Header values may use the same `{{param}}` and `{{context.key}}` templates as the URL and request body. Cookies captured by the Verification Client are attached separately and don't need to be declared."
924
+ },
728
925
  "credentials": {
729
926
  "type": "string",
730
927
  "description": "Mirrors the Fetch API `RequestCredentials` value used when issuing the request — controls whether cookies and auth headers are sent.",
@@ -808,7 +1005,7 @@ export const MCP_TOOLS = {
808
1005
  },
809
1006
  "responseRedactions": {
810
1007
  "type": "array",
811
- "description": "Portions to select/reveal from the response, applied in order (xPath => jsonPath => regex). Done client-side; only the selected portions (plus the first response line) are sent to the attestor. An independent ordered list — NOT paired 1:1 with `responseMatches`. Mirrors attestor-core `responseRedactions`.",
1008
+ "description": "Portions to select/reveal from the response, applied in order (xPath => jsonPath => regex). Done client-side; only the selected portions (plus the first response line) are sent to the attestor. An independent ordered list — not generally paired 1:1 with `responseMatches`. For legacy proof-hash optional-subset compatibility only, the redaction at the same index is treated as the pair for an optional `ResponseMatch`; this does not pair all redactions with matches. Mirrors attestor-core `responseRedactions`.",
812
1009
  "items": {
813
1010
  "type": "object",
814
1011
  "additionalProperties": false,
@@ -878,6 +1075,15 @@ export const MCP_TOOLS = {
878
1075
  "description": "Template used to match or capture an outgoing request body. Template can use regex templates as placeholders. For example, to match an outgoing request body that contains a request ID, you can use the following template: `(?<requestId>.*)`.",
879
1076
  "maxLength": 100000
880
1077
  },
1078
+ "headers": {
1079
+ "type": "object",
1080
+ "additionalProperties": {
1081
+ "type": "string",
1082
+ "maxLength": 16000
1083
+ },
1084
+ "maxProperties": 100,
1085
+ "description": "Static HTTP request headers passed to the attestor. Values may contain `{{param}}` and `{{context.key}}` templates."
1086
+ },
881
1087
  "credentials": {
882
1088
  "type": "string",
883
1089
  "description": "Mirrors the Fetch API `RequestCredentials` value used when issuing the request — controls whether cookies and auth headers are sent.",
@@ -961,7 +1167,7 @@ export const MCP_TOOLS = {
961
1167
  },
962
1168
  "responseRedactions": {
963
1169
  "type": "array",
964
- "description": "Portions to select/reveal from the response, applied in order (xPath => jsonPath => regex). Done client-side; only the selected portions (plus the first response line) are sent to the attestor. An independent ordered list — NOT paired 1:1 with `responseMatches`. Mirrors attestor-core `responseRedactions`.",
1170
+ "description": "Portions to select/reveal from the response, applied in order (xPath => jsonPath => regex). Done client-side; only the selected portions (plus the first response line) are sent to the attestor. An independent ordered list — not generally paired 1:1 with `responseMatches`. For legacy proof-hash optional-subset compatibility only, the redaction at the same index is treated as the pair for an optional `ResponseMatch`; this does not pair all redactions with matches. Mirrors attestor-core `responseRedactions`.",
965
1171
  "items": {
966
1172
  "type": "object",
967
1173
  "additionalProperties": false,
@@ -1125,7 +1331,7 @@ export const MCP_TOOLS = {
1125
1331
  },
1126
1332
  "requiredContext": {
1127
1333
  "type": "object",
1128
- "description": "Optional JSON Schema describing the `context` a Consumer must supply when creating a verification session for this provider version. Only needed when the recipe expects Consumer-supplied values: those are referenced as `{{context.<key>}}` in recipe requests. Bare `{{parameterName}}` placeholders are provider parameters (extracted / not Consumer-supplied) and need no declaration here. The Builder validates `CreateVerificationSessionRequest.context` against this schema and rejects the request (400) on mismatch. Extra context fields are always allowed regardless of the schema (a root-level `additionalProperties: false` is ignored). Empty/absent accepts any context.",
1334
+ "description": "Optional JSON Schema describing the `context` a Consumer must supply when creating a verification session for this provider version. Only needed when the recipe expects Consumer-supplied values: those are referenced as `{{context.<key>}}` in recipe requests. Bare `{{parameterName}}` placeholders are normally provider parameters extracted from claimant traffic. For old DevTools recipes, Builder-mode Verification Clients seed a missing bare `parameterName` from a same-named scalar session context field when the recipe doesn't use `{{context.parameterName}}`; an explicit parameter always wins. New recipes should use the explicit `{{context.<key>}}` form. Bare parameters need no declaration here. Builder-owned `reclaimSessionId` and `attestationNonce` remain context-only. The Builder validates `CreateVerificationSessionRequest.context` against this schema and rejects the request (400) on mismatch. Extra context fields are always allowed regardless of the schema (a root-level `additionalProperties: false` is ignored). Empty/absent accepts any context.",
1129
1335
  "additionalProperties": true
1130
1336
  },
1131
1337
  "notes": {
@@ -1145,7 +1351,7 @@ export const MCP_TOOLS = {
1145
1351
  }),
1146
1352
  },
1147
1353
  "CreateVerificationSession": {
1148
- description: "Create a verification session\n\nCreates a verification session for an end-user to complete.\nAuthenticated by the consumer's `OrgToken`; the session is scoped to\nthe resolved organization. The request carries no callback URLs —\nresults are delivered to the org's pre-registered callback\nsubscriptions.\n\n curl -X POST $BASE/verifications/sessions \\\n -H \"Authorization: Bearer $ORG_TOKEN\" \\\n -H 'Content-Type: application/json' \\\n -d '{\"providerId\":\"…\",\"context\":{},\n \"verificationClientUrl\":\"'$BASE'/v/{sessionId}\"}'\n\nFails with `409 Conflict` if the organization has no callback\nsubscription (there would be nowhere to deliver the result).\n",
1354
+ description: "Create a verification session\n\nCreates an end-user verification session. Requires an OrgToken and a callback subscription; pass providers, context, and an optional registered verificationClientUrl. Billing refusal returns 402 or 429 with event billing_required and a terminal sessionId.",
1149
1355
  inputSchema: toZod({
1150
1356
  "type": "object",
1151
1357
  "properties": {
@@ -1188,7 +1394,7 @@ export const MCP_TOOLS = {
1188
1394
  },
1189
1395
  "version": {
1190
1396
  "type": "string",
1191
- "description": "Semver constraint; empty resolves to the latest trunk version.",
1397
+ "description": "Empty selects the latest active trunk version. An exact semantic version pins that version. Any other valid npm semantic-version range selects the highest active matching version.",
1192
1398
  "maxLength": 64
1193
1399
  }
1194
1400
  }
@@ -1197,17 +1403,28 @@ export const MCP_TOOLS = {
1197
1403
  "context": {
1198
1404
  "type": "object",
1199
1405
  "additionalProperties": true,
1200
- "description": "Consumer context, shared by all providers. Validated against EACH resolved provider version's `requiredContext` JSON Schema (a 400 is returned on mismatch); extra fields are always allowed. Recipe requests reference these values as `{{context.<key>}}`. Echoed back (plus `reclaimSessionId`) in the result."
1406
+ "description": "Consumer context, shared by all providers. Validated against EACH resolved provider version's `requiredContext` JSON Schema (a 400 is returned on mismatch); extra fields are always allowed. Recipe requests reference these values as `{{context.<key>}}`. To support old DevTools recipes, Builder-mode Verification Clients also use a same-named scalar context value to seed a missing bare `{{key}}` when the recipe doesn't use `{{context.key}}`; an explicit parameter takes precedence. Echoed back (plus `reclaimSessionId`) in the result. Builder-owned `reclaimSessionId` and `attestationNonce` remain context-only."
1201
1407
  },
1202
1408
  "verificationClientUrl": {
1203
1409
  "type": "string",
1204
- "description": "Optional. Must exactly equal the base URL of a registered verification client (see the `verification_clients` registry / `/admin/verification-clients`). Omit to use the default (`builder`) client. The Builder attaches the session id — into a `{sessionId}` placeholder if the registered base has one, otherwise as a `?sessionId=…` query parameter — and returns the ready-to-share result as `verificationUrl`. A URL that is not a registered client's base is rejected with 400.",
1410
+ "description": "Optional. Must exactly equal the base URL of a registered verification client (see the `verification_clients` registry / `/admin/verification-clients`). Omit to use the default (`builder`) client. The Builder resolves and stores the registered client UUID, then returns the ready-to-share `verificationUrl` with the session id and `api=2`. A URL that is not a registered client's base is rejected with 400. Consumers append any client-owned redirect parameters after receiving the URL; Builder does not manage them.",
1205
1411
  "maxLength": 2000,
1206
1412
  "pattern": "^https?://"
1207
1413
  },
1414
+ "themeId": {
1415
+ "type": "string",
1416
+ "format": "uuid"
1417
+ },
1418
+ "preferredLocale": {
1419
+ "type": "string",
1420
+ "description": "Optional locale override for this verification session. It takes precedence over the organization theme's preferred locale.",
1421
+ "minLength": 2,
1422
+ "maxLength": 64,
1423
+ "pattern": "^[A-Za-z]{2,8}(?:[-_][A-Za-z0-9]{1,8})*$"
1424
+ },
1208
1425
  "preferAiAgent": {
1209
1426
  "type": "boolean",
1210
- "description": "Optional. Whether the Verification Client is preferred (allowed) to run this session's providers with an LLM/AI agent instead of the structured recipe. Omit to default per provider from its `verificationType` (`llm` → agent preferred, `structured` → not). The recipe endpoint exposes the effective per-provider value as `preferAiAgent`. A preference, not a hard gate — clients without agent support run the structured recipe regardless."
1427
+ "description": "Legacy-only preference. Builder mode runs the structured recipe and does not enable AI or manual verification. Omit this field for Builder-mode sessions; dual-mode clients may continue to interpret it only on their legacy path."
1211
1428
  }
1212
1429
  }
1213
1430
  }
@@ -1438,57 +1655,6 @@ export const MCP_TOOLS = {
1438
1655
  "additionalProperties": false
1439
1656
  }),
1440
1657
  },
1441
- "DeleteProviderVersion": {
1442
- description: "Delete a provider version\n\nSoft-archives a version on the `draft`, `ai`, or `rejected` branch — sets `status` to `ARCHIVED` so history is preserved. `fixed`, trunk (live), and `in_review` versions cannot be archived this way; archive the parent provider instead. Supports optimistic concurrency via `If-Match`.",
1443
- inputSchema: toZod({
1444
- "type": "object",
1445
- "properties": {
1446
- "params": {
1447
- "type": "object",
1448
- "properties": {
1449
- "providerId": {
1450
- "type": "string",
1451
- "format": "uuid"
1452
- },
1453
- "version": {
1454
- "type": "string",
1455
- "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:-[a-zA-Z0-9_-]+(?:\\.[0-9]+)?)?$",
1456
- "maxLength": 32
1457
- }
1458
- },
1459
- "required": [
1460
- "providerId",
1461
- "version"
1462
- ],
1463
- "additionalProperties": false
1464
- },
1465
- "query": {
1466
- "type": "object",
1467
- "properties": {
1468
-
1469
- }
1470
- },
1471
- "headers": {
1472
- "type": "object",
1473
- "properties": {
1474
- "If-Match": {
1475
- "type": "string",
1476
- "maxLength": 128,
1477
- "description": "Opaque `ETag` from a prior GET on the same resource. When\nsupplied, the server applies optimistic concurrency: the\nmutation fails with `412 Precondition Failed` if the\nresource has been modified since. Omit for last-write-wins.\n"
1478
- }
1479
- }
1480
- },
1481
- "body": {
1482
- "type": "object"
1483
- }
1484
- },
1485
- "required": [
1486
- "params",
1487
- "query"
1488
- ],
1489
- "additionalProperties": false
1490
- }),
1491
- },
1492
1658
  "DiscoverDataPoints": {
1493
1659
  description: "List the verifiable data points on a website\n\nThe data points existing providers can prove on a website — the menu to pick from before `GET /discover/resolve`. Optionally filter by `q`.",
1494
1660
  inputSchema: toZod({
@@ -1850,8 +2016,81 @@ export const MCP_TOOLS = {
1850
2016
  "additionalProperties": false
1851
2017
  }),
1852
2018
  },
2019
+ "GetVerificationFunnel": {
2020
+ description: "Get the verification funnel\n\nCalculates an organization's lifecycle funnel for sessions created between required createdAfter (inclusive) and createdBefore (exclusive). Use providerIds/providerMatch and mode (SESSION or PROVIDER) to scope counts. Missing optional events can reflect telemetry loss.",
2021
+ inputSchema: toZod({
2022
+ "type": "object",
2023
+ "properties": {
2024
+ "params": {
2025
+ "type": "object",
2026
+ "properties": {
2027
+ "orgId": {
2028
+ "type": "string",
2029
+ "format": "uuid"
2030
+ }
2031
+ },
2032
+ "required": [
2033
+ "orgId"
2034
+ ],
2035
+ "additionalProperties": false
2036
+ },
2037
+ "query": {
2038
+ "type": "object",
2039
+ "properties": {
2040
+ "providerIds": {
2041
+ "type": "array",
2042
+ "minItems": 1,
2043
+ "maxItems": 50,
2044
+ "uniqueItems": true,
2045
+ "items": {
2046
+ "type": "string",
2047
+ "format": "uuid"
2048
+ }
2049
+ },
2050
+ "providerMatch": {
2051
+ "type": "string",
2052
+ "enum": [
2053
+ "ANY",
2054
+ "ALL"
2055
+ ],
2056
+ "default": "ANY"
2057
+ },
2058
+ "mode": {
2059
+ "type": "string",
2060
+ "enum": [
2061
+ "SESSION",
2062
+ "PROVIDER"
2063
+ ],
2064
+ "default": "SESSION"
2065
+ },
2066
+ "createdAfter": {
2067
+ "type": "string",
2068
+ "format": "date-time"
2069
+ },
2070
+ "createdBefore": {
2071
+ "type": "string",
2072
+ "format": "date-time"
2073
+ }
2074
+ },
2075
+ "required": [
2076
+ "createdAfter",
2077
+ "createdBefore"
2078
+ ],
2079
+ "additionalProperties": false
2080
+ },
2081
+ "body": {
2082
+ "type": "object"
2083
+ }
2084
+ },
2085
+ "required": [
2086
+ "params",
2087
+ "query"
2088
+ ],
2089
+ "additionalProperties": false
2090
+ }),
2091
+ },
1853
2092
  "GetVerificationSession": {
1854
- description: "Get a verification session\n\nReturns the session. Authenticated by the consumer's `OrgToken` (or the\nVC service token); the resolved org must match the session's.\n\nReading `status`:\n- `pending` — created, not yet finished; the end-user can still\n complete it until `expiresAt`.\n- `success` / `rejected` / `error` — terminal outcomes (the matching\n `verification_*` event was recorded). Only after a terminal status is\n a result delivered to callbacks.\n- `expired` — `expiresAt` passed before a terminal event. A `pending`\n session whose `expiresAt` is in the past has effectively expired and\n flips to `expired` on the next sweep; the end-user can no longer\n complete it — issue a fresh session/link.\n\n`callbackDeliveryStatus` aggregates the session's callback deliveries\nand is only meaningful once the session is terminal. To investigate a\nstuck or failed session, pair this with `list_verification_events` (the\nper-stage lifecycle log) and `list_verification_deliveries` (callback\nhealth).\n",
2093
+ description: "Get a verification session\n\nGets one verification session. Use it to inspect status, resolved providers, context, Verification Client identity, and expiry. Present the owning organization token or the session's x-reclaim-vc-id.",
1855
2094
  inputSchema: toZod({
1856
2095
  "type": "object",
1857
2096
  "properties": {
@@ -1875,6 +2114,15 @@ export const MCP_TOOLS = {
1875
2114
 
1876
2115
  }
1877
2116
  },
2117
+ "headers": {
2118
+ "type": "object",
2119
+ "properties": {
2120
+ "x-reclaim-vc-id": {
2121
+ "type": "string",
2122
+ "description": "UUID of the registered Verification Client selected when the session was created. The Builder binds it to the session's immutable verificationClientId. This header identifies the client; it is not a general bearer credential. Client-reported metadata remains untrusted, and Consumers must verify every signed result with verifyResultFull."
2123
+ }
2124
+ }
2125
+ },
1878
2126
  "body": {
1879
2127
  "type": "object"
1880
2128
  }
@@ -1887,7 +2135,7 @@ export const MCP_TOOLS = {
1887
2135
  }),
1888
2136
  },
1889
2137
  "ImportDevtoolsProvider": {
1890
- description: "Import a provider from devtools\n\nImport the latest version of a public provider from the legacy devtools\nservice. Use this when moving an existing provider to Builder instead\nof recreating it.\n\nThe import preserves the legacy provider UUID. The server reads the\ncurrent configuration from\n`https://api.reclaimprotocol.org/api/providers/{providerId}` and\ntranslates it to the Builder schema.\n\nIf the provider already exists in the seeded anonymous catalog, the\nimport assigns that record to the target organization and adds the\nimported version idempotently. A provider owned by another Builder\norganization returns `409`.\n",
2138
+ description: "Import a provider from devtools\n\nImports a public legacy provider into Builder by UUID. Requires human BearerAuth and a target orgId; preserves the provider UUID and is idempotent for seeded providers. Returns 409 if another Builder org owns the UUID.",
1891
2139
  inputSchema: toZod({
1892
2140
  "type": "object",
1893
2141
  "properties": {
@@ -2153,12 +2401,13 @@ export const MCP_TOOLS = {
2153
2401
  },
2154
2402
  "status": {
2155
2403
  "type": "string",
2156
- "description": "Status of a verification session, derived from its events. New values\nmay be added over time; clients MUST tolerate unknown values in\nresponses.\n\n- `pending`: Created, not yet finished; completable until `expiresAt`.\n\n- `success`: Terminal — `verification_success` recorded.\n\n- `rejected`: Terminal — `verification_rejected` recorded.\n\n- `error`: Terminal — `verification_error` recorded.\n\n- `expired`: `expiresAt` passed before a terminal event; the end-user\n can no longer complete it.",
2404
+ "description": "Status of a verification session, derived from its events. New values\nmay be added over time; clients MUST tolerate unknown values in\nresponses.\n\n- `pending`: Created, not yet finished; completable until `expiresAt`.\n\n- `success`: Terminal — `verification_success` recorded.\n\n- `rejected`: Terminal — `verification_rejected` recorded.\n\n- `error`: Terminal — `verification_error` recorded.\n\n- `cancelled`: Terminal — `verification_cancelled` recorded.\n\n- `expired`: `expiresAt` passed before a terminal event; the end-user\n can no longer complete it.",
2157
2405
  "enum": [
2158
2406
  "pending",
2159
2407
  "success",
2160
2408
  "rejected",
2161
2409
  "error",
2410
+ "cancelled",
2162
2411
  "expired"
2163
2412
  ]
2164
2413
  },
@@ -2234,7 +2483,7 @@ export const MCP_TOOLS = {
2234
2483
  }),
2235
2484
  },
2236
2485
  "ListVerificationDeliveries": {
2237
- description: "Get the callback delivery status for a session\n\nDiagnostic view of the session's callback deliveries: one entry per\n(subscription, terminal event) with its delivery state, attempt\ncount, last error, and whether it was dead-lettered. Lets a consumer\n(or the agent) answer \"did my callback arrive, and if not, why?\"\nwithout org-dashboard access. Only meaningful after the session\nreaches a terminal status (no deliveries exist before then). Auth\nmirrors the events GET: the Verification Client service token, or the\nconsumer's `OrgToken` (the resolved org must match the session).\n\nReading `deliveryStatus` per entry:\n- `delivered` — the callback POST succeeded; nothing to do.\n- `pending` — queued, not yet attempted (or between retries).\n- `attempt_failed` — a delivery attempt failed but retries remain;\n `lastError` holds the reason and `attempts` the count so far.\n- `failed` — all retries exhausted. When `deadLettered` is also true\n the delivery sits in the DLQ.\n\nTo recover a failed/dead-lettered delivery: confirm the `callbackUrl`\nis reachable and answers 2xx, then call `retry_verification_callback`\nto re-enqueue it (an org admin can also retry from the Callback DLQ).\n",
2486
+ description: "Get the callback delivery status for a session\n\nLists callback delivery attempts for a session. Requires an OrgToken or the session-bound x-reclaim-vc-id. Use after terminal status to diagnose pending, failed, or dead-lettered callbacks; retry failures with retry_verification_callback.",
2238
2487
  inputSchema: toZod({
2239
2488
  "type": "object",
2240
2489
  "properties": {
@@ -2258,6 +2507,15 @@ export const MCP_TOOLS = {
2258
2507
 
2259
2508
  }
2260
2509
  },
2510
+ "headers": {
2511
+ "type": "object",
2512
+ "properties": {
2513
+ "x-reclaim-vc-id": {
2514
+ "type": "string",
2515
+ "description": "UUID of the registered Verification Client selected when the session was created. The Builder binds it to the session's immutable verificationClientId. This header identifies the client; it is not a general bearer credential. Client-reported metadata remains untrusted, and Consumers must verify every signed result with verifyResultFull."
2516
+ }
2517
+ }
2518
+ },
2261
2519
  "body": {
2262
2520
  "type": "object"
2263
2521
  }
@@ -2270,7 +2528,7 @@ export const MCP_TOOLS = {
2270
2528
  }),
2271
2529
  },
2272
2530
  "ListVerificationEvents": {
2273
- description: "Get the event log for a session\n\nReturns the append-only event log. Readable by the Verification Client\n(`X-VC-Token`) or the session creator (authenticated by the consumer's\n`OrgToken`; the resolved org must match the session).\n\nThis log is the primary tool for diagnosing a stuck or failed session.\nA healthy run proceeds through this lifecycle (in order):\n\n`session_pending` → `verification_client_opened` →\n`verification_client_ready` → `request_matched` →\n`request_claim_created` → `request_claim_completed` → terminal\n(`verification_success` | `verification_rejected` | `verification_error`),\nor `session_expired` if `expiresAt` passes first.\n\nRead the gaps to locate where the flow stalled:\n- no `verification_client_opened` → the end-user never opened the link.\n- opened but no `request_matched` → the user opened the page but didn't\n complete the login/journey on the provider site, so the target\n request was never captured.\n- `request_matched` but no terminal event → the proof run is still in\n progress (or stalled mid-claim).\n\nFailure detail lives in `eventData` on `request_claim_failed`,\n`request_claim_rejected`, `verification_error`, and\n`verification_rejected` — inspect it for the reason. Request-level\nevents also carry a `request_id` in `eventData`. Pair with\n`get_verification_session` (status/expiry) and\n`list_verification_deliveries` (callback health) for the full picture.\n",
2531
+ description: "Get the event log for a session\n\nLists append-only lifecycle events for a session. Requires an OrgToken or the session-bound x-reclaim-vc-id. Use after get_verification_session to find the first missing or failed milestone; inspect eventData for failure details.",
2274
2532
  inputSchema: toZod({
2275
2533
  "type": "object",
2276
2534
  "properties": {
@@ -2294,6 +2552,15 @@ export const MCP_TOOLS = {
2294
2552
 
2295
2553
  }
2296
2554
  },
2555
+ "headers": {
2556
+ "type": "object",
2557
+ "properties": {
2558
+ "x-reclaim-vc-id": {
2559
+ "type": "string",
2560
+ "description": "UUID of the registered Verification Client selected when the session was created. The Builder binds it to the session's immutable verificationClientId. This header identifies the client; it is not a general bearer credential. Client-reported metadata remains untrusted, and Consumers must verify every signed result with verifyResultFull."
2561
+ }
2562
+ }
2563
+ },
2297
2564
  "body": {
2298
2565
  "type": "object"
2299
2566
  }
@@ -2984,517 +3251,6 @@ export const MCP_TOOLS = {
2984
3251
  "additionalProperties": false
2985
3252
  }),
2986
3253
  },
2987
- "UpdateProviderVersion": {
2988
- description: "Update a provider version\n\nMutable only while the version is on the `draft` or `rejected` branch. Versions on `fixed`, `in_review`, or the live channel reject all writes here. Caller must be a member of the provider's owning organization. Supports optimistic concurrency via `If-Match`.",
2989
- inputSchema: toZod({
2990
- "type": "object",
2991
- "properties": {
2992
- "params": {
2993
- "type": "object",
2994
- "properties": {
2995
- "providerId": {
2996
- "type": "string",
2997
- "format": "uuid"
2998
- },
2999
- "version": {
3000
- "type": "string",
3001
- "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:-[a-zA-Z0-9_-]+(?:\\.[0-9]+)?)?$",
3002
- "maxLength": 32
3003
- }
3004
- },
3005
- "required": [
3006
- "providerId",
3007
- "version"
3008
- ],
3009
- "additionalProperties": false
3010
- },
3011
- "query": {
3012
- "type": "object",
3013
- "properties": {
3014
-
3015
- }
3016
- },
3017
- "headers": {
3018
- "type": "object",
3019
- "properties": {
3020
- "If-Match": {
3021
- "type": "string",
3022
- "maxLength": 128,
3023
- "description": "Opaque `ETag` from a prior GET on the same resource. When\nsupplied, the server applies optimistic concurrency: the\nmutation fails with `412 Precondition Failed` if the\nresource has been modified since. Omit for last-write-wins.\n"
3024
- }
3025
- }
3026
- },
3027
- "body": {
3028
- "type": "object",
3029
- "additionalProperties": false,
3030
- "description": "Partial update of a provider version. Mutable only while the version is on the `draft` or `rejected` branch; versions on `fixed`, `in_review`, or the live channel reject all writes here. The semver does not change on update — `build_number` increments instead, giving callers a monotonic revision counter without touching the (major, minor, patch) PK. `verificationType` and `prompt` may be updated; omit either to carry the prior build's value forward.",
3031
- "properties": {
3032
- "initialUrl": {
3033
- "type": "string",
3034
- "format": "uri"
3035
- },
3036
- "verificationType": {
3037
- "type": "string",
3038
- "description": "How a provider version verifies a claim. `structured` uses the explicit match rules on this version (the `matches` / `allowedJsMatches` and related settings). `llm` defers the verification decision to a language model and requires `prompt` to be set.",
3039
- "enum": [
3040
- "llm",
3041
- "structured"
3042
- ]
3043
- },
3044
- "prompt": {
3045
- "type": "string",
3046
- "description": "Extraction prompt, used when `verificationType` is `llm`. Gated by the prompt guard before it is stored (docs/prompt-guard.md).",
3047
- "minLength": 0,
3048
- "maxLength": 4000
3049
- },
3050
- "requests": {
3051
- "type": "array",
3052
- "minItems": 0,
3053
- "items": {
3054
- "type": "object",
3055
- "additionalProperties": false,
3056
- "description": "A matcher for one HTTP request in observed traffic, together with the response constraints that must hold for a Reclaim proof over that request to be valid. Used by interceptors, in-page injections, and LLM agents.",
3057
- "required": [
3058
- "url",
3059
- "method"
3060
- ],
3061
- "properties": {
3062
- "url": {
3063
- "type": "string",
3064
- "description": "The URL or generic path of the HTTP request."
3065
- },
3066
- "method": {
3067
- "type": "string",
3068
- "description": "The HTTP method used for the request.",
3069
- "enum": [
3070
- "GET",
3071
- "POST",
3072
- "PUT",
3073
- "PATCH",
3074
- "DELETE"
3075
- ]
3076
- },
3077
- "requestBodyTemplate": {
3078
- "type": "string",
3079
- "description": "Template used to match or capture an outgoing request body. Template can use regex templates as placeholders. For example, to match an outgoing request body that contains a request ID, you can use the following template: `(?<requestId>.*)`.",
3080
- "maxLength": 100000
3081
- },
3082
- "credentials": {
3083
- "type": "string",
3084
- "description": "Mirrors the Fetch API `RequestCredentials` value used when issuing the request — controls whether cookies and auth headers are sent.",
3085
- "enum": [
3086
- "omit",
3087
- "same-origin",
3088
- "include"
3089
- ]
3090
- },
3091
- "writeRedactionMode": {
3092
- "type": "string",
3093
- "description": "How the matched portion of the response should be redacted before the transcript is handed to the attestor.\n- `zk`: redact using a zero-knowledge proof over the original\n bytes.\n\n- `key-update`: redact by performing a TLS key update so the\n attestor never observes the matched bytes in cleartext.",
3094
- "enum": [
3095
- "zk",
3096
- "key-update"
3097
- ]
3098
- },
3099
- "additionalClientOptions": {
3100
- "type": "object",
3101
- "additionalProperties": false,
3102
- "description": "Apply TLS configuration when creating the tunnel to the attestor.",
3103
- "properties": {
3104
- "supportedProtocolVersions": {
3105
- "type": "array",
3106
- "description": "TLS protocol versions the client is allowed to negotiate.",
3107
- "minItems": 1,
3108
- "uniqueItems": true,
3109
- "items": {
3110
- "type": "string",
3111
- "enum": [
3112
- "TLS1_2",
3113
- "TLS1_3"
3114
- ]
3115
- }
3116
- }
3117
- }
3118
- },
3119
- "responseMatches": {
3120
- "type": "array",
3121
- "description": "Conditions the (redacted) response must satisfy for the proof to be valid. Each runs against the union of the portions revealed by `responseRedactions` (or the whole response when there are none). Mirrors attestor-core `responseMatches`.",
3122
- "minItems": 1,
3123
- "items": {
3124
- "type": "object",
3125
- "additionalProperties": false,
3126
- "description": "Specifies a rule to match against a string in response to validate proof content.",
3127
- "required": [
3128
- "type",
3129
- "value"
3130
- ],
3131
- "properties": {
3132
- "isOptional": {
3133
- "type": "boolean",
3134
- "description": "If true, the match condition is optional and won't fail if absent",
3135
- "default": false
3136
- },
3137
- "description": {
3138
- "type": "string",
3139
- "description": "The description of the field that is extracted using this match rule",
3140
- "minLength": 1,
3141
- "maxLength": 1000
3142
- },
3143
- "order": {
3144
- "type": "integer",
3145
- "description": "The order in which the field should be displayed to user in UI",
3146
- "minimum": 0
3147
- },
3148
- "type": {
3149
- "type": "string",
3150
- "description": "The matching mechanism to use value as against response. Typically regex or simple string containment",
3151
- "enum": [
3152
- "regex",
3153
- "contains"
3154
- ]
3155
- },
3156
- "value": {
3157
- "type": "string",
3158
- "description": "The pattern or value to look for in the response. When `type` is 'contains', supports template variable declaration using `{{variable}}` syntax. When `type` is 'regex', can be used to extract variables using regex named groups."
3159
- }
3160
- }
3161
- }
3162
- },
3163
- "responseRedactions": {
3164
- "type": "array",
3165
- "description": "Portions to select/reveal from the response, applied in order (xPath => jsonPath => regex). Done client-side; only the selected portions (plus the first response line) are sent to the attestor. An independent ordered list — NOT paired 1:1 with `responseMatches`. Mirrors attestor-core `responseRedactions`.",
3166
- "items": {
3167
- "type": "object",
3168
- "additionalProperties": false,
3169
- "description": "Which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (that is, \"HTTP/1.1 200 OK\")",
3170
- "properties": {
3171
- "xPath": {
3172
- "type": "string",
3173
- "description": "expect an HTML response, and to contain a certain xpath for eg. \"/html/body/div.a1/div.a2/span.a5\""
3174
- },
3175
- "jsonPath": {
3176
- "type": "string",
3177
- "description": "expect a JSON response, retrieve the item at this path using dot notation, for example 'email.addresses.0'."
3178
- },
3179
- "regex": {
3180
- "type": "string",
3181
- "description": "select a regex match from the response"
3182
- },
3183
- "hash": {
3184
- "type": "string",
3185
- "description": "If provided, the value inside will be hashed instead of being redacted. Useful for cases where the data inside is an identifiying piece of information that you don't want to reveal to the attestor, eg. an email address.\nIf the hash function produces more bytes than the original value, the hash will be truncated.\nEg. if hash is enabled, the original value is \"hello\", and hashed is \"a1b2c\", then the attestor will only see \"a1b2c\".\nNote: if a regex with named groups is provided, only the named groups will be hashed.",
3186
- "enum": [
3187
- "oprf",
3188
- "oprf-mpc",
3189
- "oprf-raw"
3190
- ]
3191
- }
3192
- }
3193
- }
3194
- }
3195
- }
3196
- }
3197
- },
3198
- "allowedJsRequests": {
3199
- "type": "array",
3200
- "minItems": 0,
3201
- "items": {
3202
- "type": "object",
3203
- "additionalProperties": false,
3204
- "description": "A template for selecting requests. Same matcher shape as `RequestSelection`, plus template flags (`multiple`/`required`) and optional `templateParams` expansion.",
3205
- "required": [
3206
- "url",
3207
- "method",
3208
- "multiple",
3209
- "required"
3210
- ],
3211
- "properties": {
3212
- "url": {
3213
- "type": "string",
3214
- "description": "The URL or generic path of the HTTP request."
3215
- },
3216
- "method": {
3217
- "type": "string",
3218
- "description": "The HTTP method used for the request.",
3219
- "enum": [
3220
- "GET",
3221
- "POST",
3222
- "PUT",
3223
- "PATCH",
3224
- "DELETE"
3225
- ]
3226
- },
3227
- "requestBodyTemplate": {
3228
- "type": "string",
3229
- "description": "Template used to match or capture an outgoing request body. Template can use regex templates as placeholders. For example, to match an outgoing request body that contains a request ID, you can use the following template: `(?<requestId>.*)`.",
3230
- "maxLength": 100000
3231
- },
3232
- "credentials": {
3233
- "type": "string",
3234
- "description": "Mirrors the Fetch API `RequestCredentials` value used when issuing the request — controls whether cookies and auth headers are sent.",
3235
- "enum": [
3236
- "omit",
3237
- "same-origin",
3238
- "include"
3239
- ]
3240
- },
3241
- "writeRedactionMode": {
3242
- "type": "string",
3243
- "description": "How the matched portion of the response should be redacted before the transcript is handed to the attestor.\n- `zk`: redact using a zero-knowledge proof over the original\n bytes.\n\n- `key-update`: redact by performing a TLS key update so the\n attestor never observes the matched bytes in cleartext.",
3244
- "enum": [
3245
- "zk",
3246
- "key-update"
3247
- ]
3248
- },
3249
- "additionalClientOptions": {
3250
- "type": "object",
3251
- "additionalProperties": false,
3252
- "description": "Apply TLS configuration when creating the tunnel to the attestor.",
3253
- "properties": {
3254
- "supportedProtocolVersions": {
3255
- "type": "array",
3256
- "description": "TLS protocol versions the client is allowed to negotiate.",
3257
- "minItems": 1,
3258
- "uniqueItems": true,
3259
- "items": {
3260
- "type": "string",
3261
- "enum": [
3262
- "TLS1_2",
3263
- "TLS1_3"
3264
- ]
3265
- }
3266
- }
3267
- }
3268
- },
3269
- "responseMatches": {
3270
- "type": "array",
3271
- "description": "Conditions the (redacted) response must satisfy for the proof to be valid. Each runs against the union of the portions revealed by `responseRedactions` (or the whole response when there are none). Mirrors attestor-core `responseMatches`.",
3272
- "minItems": 1,
3273
- "items": {
3274
- "type": "object",
3275
- "additionalProperties": false,
3276
- "description": "Specifies a rule to match against a string in response to validate proof content.",
3277
- "required": [
3278
- "type",
3279
- "value"
3280
- ],
3281
- "properties": {
3282
- "isOptional": {
3283
- "type": "boolean",
3284
- "description": "If true, the match condition is optional and won't fail if absent",
3285
- "default": false
3286
- },
3287
- "description": {
3288
- "type": "string",
3289
- "description": "The description of the field that is extracted using this match rule",
3290
- "minLength": 1,
3291
- "maxLength": 1000
3292
- },
3293
- "order": {
3294
- "type": "integer",
3295
- "description": "The order in which the field should be displayed to user in UI",
3296
- "minimum": 0
3297
- },
3298
- "type": {
3299
- "type": "string",
3300
- "description": "The matching mechanism to use value as against response. Typically regex or simple string containment",
3301
- "enum": [
3302
- "regex",
3303
- "contains"
3304
- ]
3305
- },
3306
- "value": {
3307
- "type": "string",
3308
- "description": "The pattern or value to look for in the response. When `type` is 'contains', supports template variable declaration using `{{variable}}` syntax. When `type` is 'regex', can be used to extract variables using regex named groups."
3309
- }
3310
- }
3311
- }
3312
- },
3313
- "responseRedactions": {
3314
- "type": "array",
3315
- "description": "Portions to select/reveal from the response, applied in order (xPath => jsonPath => regex). Done client-side; only the selected portions (plus the first response line) are sent to the attestor. An independent ordered list — NOT paired 1:1 with `responseMatches`. Mirrors attestor-core `responseRedactions`.",
3316
- "items": {
3317
- "type": "object",
3318
- "additionalProperties": false,
3319
- "description": "Which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (that is, \"HTTP/1.1 200 OK\")",
3320
- "properties": {
3321
- "xPath": {
3322
- "type": "string",
3323
- "description": "expect an HTML response, and to contain a certain xpath for eg. \"/html/body/div.a1/div.a2/span.a5\""
3324
- },
3325
- "jsonPath": {
3326
- "type": "string",
3327
- "description": "expect a JSON response, retrieve the item at this path using dot notation, for example 'email.addresses.0'."
3328
- },
3329
- "regex": {
3330
- "type": "string",
3331
- "description": "select a regex match from the response"
3332
- },
3333
- "hash": {
3334
- "type": "string",
3335
- "description": "If provided, the value inside will be hashed instead of being redacted. Useful for cases where the data inside is an identifiying piece of information that you don't want to reveal to the attestor, eg. an email address.\nIf the hash function produces more bytes than the original value, the hash will be truncated.\nEg. if hash is enabled, the original value is \"hello\", and hashed is \"a1b2c\", then the attestor will only see \"a1b2c\".\nNote: if a regex with named groups is provided, only the named groups will be hashed.",
3336
- "enum": [
3337
- "oprf",
3338
- "oprf-mpc",
3339
- "oprf-raw"
3340
- ]
3341
- }
3342
- }
3343
- }
3344
- },
3345
- "multiple": {
3346
- "type": "boolean",
3347
- "description": "If true, the template is allowed for multiple requests. Useful for requests like paginated API calls.",
3348
- "default": true
3349
- },
3350
- "required": {
3351
- "type": "boolean",
3352
- "description": "If true, a request is required to match with this template. If not requests matches this template in proof, then validation fails.",
3353
- "default": true
3354
- },
3355
- "templateParams": {
3356
- "type": "array",
3357
- "description": "Names of `${param}` placeholders used in this template's `responseMatches` / `responseRedactions`, substituted at verification time from array-valued extracted parameters (each name must resolve to an array of values; all named arrays must have the same length). Absent or empty means the template is used as-is with no expansion.",
3358
- "maxItems": 50,
3359
- "items": {
3360
- "type": "string",
3361
- "minLength": 1,
3362
- "maxLength": 100
3363
- }
3364
- },
3365
- "templateParamsMode": {
3366
- "type": "string",
3367
- "description": "How array values of `templateParams` expand the template: `separate` (default) emits one expanded request — its own claim — per value; `merge` emits a single request whose `responseMatches`/`responseRedactions` contain all substituted entries, proven by one claim.",
3368
- "enum": [
3369
- "separate",
3370
- "merge"
3371
- ],
3372
- "default": "separate"
3373
- }
3374
- }
3375
- }
3376
- },
3377
- "webSettings": {
3378
- "type": "object",
3379
- "additionalProperties": false,
3380
- "description": "Settings used by the web-based verification client.",
3381
- "properties": {
3382
- "geoLocation": {
3383
- "type": "string",
3384
- "description": "Geographic location the verification should appear to originate from: a 2-letter ISO country code, or a parameter the attestor resolves at proof time. `{{DYNAMIC_GEO}}` and `{{DYNAMIC_GEO_SECRET}}` are the Verification Client's standard names for the end-user's own country — the `_SECRET` one is delivered as a secret param, so the attestor never learns which country the proof egressed from.",
3385
- "maxLength": 64,
3386
- "default": "{{DYNAMIC_GEO}}"
3387
- },
3388
- "clientOptions": {
3389
- "type": "object",
3390
- "additionalProperties": false,
3391
- "description": "Options that influence how the web verification client behaves.",
3392
- "properties": {
3393
- "portal": {
3394
- "type": "object",
3395
- "additionalProperties": false,
3396
- "description": "Options that influence how the portal verification client behaves.",
3397
- "properties": {
3398
- "useProxy": {
3399
- "type": "boolean",
3400
- "description": "When true, network traffic from the portal client and attestation is routed through a proxy.",
3401
- "default": true
3402
- },
3403
- "userAgent": {
3404
- "type": "string",
3405
- "description": "User-agent string used for platform verification.",
3406
- "maxLength": 500
3407
- }
3408
- }
3409
- },
3410
- "inapp": {
3411
- "type": "object",
3412
- "additionalProperties": false,
3413
- "description": "Options that influence how the in-app verification client behaves.",
3414
- "properties": {
3415
- "interceptorOptions": {
3416
- "type": "object",
3417
- "additionalProperties": false,
3418
- "required": [
3419
- "interceptorType"
3420
- ],
3421
- "properties": {
3422
- "interceptorType": {
3423
- "type": "string",
3424
- "description": "How traffic interception is implemented.",
3425
- "enum": [
3426
- "HAWKEYE",
3427
- "MSWJS",
3428
- "CDP"
3429
- ]
3430
- },
3431
- "isDocumentRequestReplayEnabled": {
3432
- "type": "boolean",
3433
- "description": "Whether the main document request is replayed via the attestor",
3434
- "default": false
3435
- },
3436
- "interceptorSettings": {
3437
- "type": "string",
3438
- "description": "Free-form configuration passed through to the interceptor implementation selected by `interceptorType`. Keys and value shapes are defined by the chosen interceptor.",
3439
- "contentMediaType": "application/json"
3440
- }
3441
- }
3442
- },
3443
- "userAgents": {
3444
- "type": "object",
3445
- "additionalProperties": false,
3446
- "description": "User-agent strings keyed by platform.",
3447
- "properties": {
3448
- "android": {
3449
- "type": "string",
3450
- "description": "User-agent string used for platform verification.",
3451
- "maxLength": 500
3452
- },
3453
- "ios": {
3454
- "type": "string",
3455
- "description": "User-agent string used for platform verification.",
3456
- "maxLength": 500
3457
- }
3458
- }
3459
- }
3460
- }
3461
- },
3462
- "extension": {
3463
- "type": "object",
3464
- "description": "Free-form key-value configuration for the browser-extension verification client. Keys and value shapes are defined by the extension client; values may be any JSON. Absent by default.",
3465
- "maxProperties": 100,
3466
- "additionalProperties": true
3467
- }
3468
- }
3469
- },
3470
- "jsUserScripts": {
3471
- "type": "string",
3472
- "description": "JavaScript snippets injected into the page which runs before every page load. `window.Reclaim.` APIs are available to these scripts to request actions to the client like claim creation.",
3473
- "maxLength": 1000000
3474
- }
3475
- }
3476
- },
3477
- "requiredContext": {
3478
- "type": "object",
3479
- "description": "Optional JSON Schema describing the `context` a Consumer must supply when creating a verification session for this provider version. Only needed when the recipe expects Consumer-supplied values: those are referenced as `{{context.<key>}}` in recipe requests. Bare `{{parameterName}}` placeholders are provider parameters (extracted / not Consumer-supplied) and need no declaration here. The Builder validates `CreateVerificationSessionRequest.context` against this schema and rejects the request (400) on mismatch. Extra context fields are always allowed regardless of the schema (a root-level `additionalProperties: false` is ignored). Empty/absent accepts any context.",
3480
- "additionalProperties": true
3481
- },
3482
- "notes": {
3483
- "type": "string",
3484
- "description": "Free-form change note recorded on `updateMetadata`.",
3485
- "maxLength": 10000
3486
- }
3487
- }
3488
- }
3489
- },
3490
- "required": [
3491
- "params",
3492
- "query",
3493
- "body"
3494
- ],
3495
- "additionalProperties": false
3496
- }),
3497
- },
3498
3254
  }
3499
3255
 
3500
3256
  export type McpToolName = keyof typeof MCP_TOOLS