@intentrax/sdk 1.6.0 → 1.8.0

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 (62) hide show
  1. package/README.md +56 -3
  2. package/cli/intentrax.mjs +57 -1
  3. package/index.js +4 -2
  4. package/index.ts +4 -2
  5. package/mcp/README.md +138 -0
  6. package/mcp/canonical.d.ts +12 -0
  7. package/mcp/canonical.mjs +70 -0
  8. package/mcp/cli.d.ts +16 -0
  9. package/mcp/cli.mjs +214 -0
  10. package/mcp/client.d.ts +131 -0
  11. package/mcp/client.mjs +955 -0
  12. package/mcp/commands.d.ts +113 -0
  13. package/mcp/commands.mjs +575 -0
  14. package/mcp/index.d.ts +12 -0
  15. package/mcp/index.mjs +12 -0
  16. package/mcp/proxy.d.ts +47 -0
  17. package/mcp/proxy.mjs +434 -0
  18. package/mcp/receipt-meta.d.ts +59 -0
  19. package/mcp/receipt-meta.mjs +178 -0
  20. package/mcp/tool-manifest.d.ts +74 -0
  21. package/mcp/tool-manifest.mjs +154 -0
  22. package/package.json +19 -1
  23. package/readback/README.md +352 -0
  24. package/readback/bridge.mjs +71 -0
  25. package/readback/cli.mjs +150 -0
  26. package/readback/confirm.mjs +404 -0
  27. package/readback/index.mjs +12 -0
  28. package/readback/recipe-worker.mjs +33 -0
  29. package/readback/recipes/_shared.mjs +126 -0
  30. package/readback/recipes/email-delivery.mjs +136 -0
  31. package/readback/recipes/github-issue.mjs +88 -0
  32. package/readback/recipes/http-json.mjs +109 -0
  33. package/readback/recipes/sql-row.mjs +96 -0
  34. package/readback/recipes/stripe-refund.mjs +73 -0
  35. package/readback/redact.mjs +68 -0
  36. package/sandbox/README.md +255 -0
  37. package/sandbox/authority.mjs +66 -0
  38. package/sandbox/bundle.mjs +93 -0
  39. package/sandbox/canonical.mjs +64 -0
  40. package/sandbox/check-runner.mjs +50 -0
  41. package/sandbox/check-worker.mjs +30 -0
  42. package/sandbox/cli.mjs +376 -0
  43. package/sandbox/effect-verifier.mjs +242 -0
  44. package/sandbox/effects.mjs +80 -0
  45. package/sandbox/envelope.mjs +174 -0
  46. package/sandbox/examples/read-only-check.example.mjs +32 -0
  47. package/sandbox/external-decision.mjs +364 -0
  48. package/sandbox/keys.mjs +179 -0
  49. package/sandbox/model.mjs +170 -0
  50. package/sandbox/run.mjs +324 -0
  51. package/sandbox/time.mjs +18 -0
  52. package/sandbox/verifier.mjs +503 -0
  53. package/scan/README.md +211 -0
  54. package/scan/classify.mjs +276 -0
  55. package/scan/cli.mjs +102 -0
  56. package/scan/configs.mjs +261 -0
  57. package/scan/credentials.mjs +121 -0
  58. package/scan/extract.mjs +323 -0
  59. package/scan/gates.mjs +94 -0
  60. package/scan/report.mjs +58 -0
  61. package/scan/scan.mjs +571 -0
  62. package/scan/text.mjs +186 -0
package/README.md CHANGED
@@ -9,7 +9,8 @@ npm install @intentrax/sdk
9
9
  The package is public on npm (Apache-2.0). Everything below that says
10
10
  "offline" or "local" runs today with no API key: `init --dry-run`,
11
11
  `check-init`, `verify-proof` (sandbox sample proofs, including tampered ones,
12
- are bundled at `examples/sandbox/`), and `verify-pdf-receipt`. Live execution
12
+ are bundled at `examples/sandbox/`), `verify-pdf-receipt`, `sandbox` (the
13
+ local assurance sandbox below), `scan`, `readback` and `mcp`. Live execution
13
14
  keys and your sandbox base URL are issued after an architectural review at
14
15
  <https://www.intentrax.com/request-architectural-review>.
15
16
 
@@ -31,10 +32,60 @@ Public surfaces:
31
32
  and signer pinning against published key sets
32
33
  - `intentrax verify-pdf-receipt <receipt.pdf>` for local downloaded PDF receipt
33
34
  byte/hash verification
35
+ - `intentrax sandbox` for the local assurance sandbox: a signed decision, an
36
+ executor report, an independent read-only outcome check (`--check` runs your
37
+ own) and offline verification with ephemeral local keys, no account and no
38
+ network. Verdicts are capped at `LOCAL_NON_TRUST_BEARING`: never production
39
+ assurance. See [sandbox/README.md](sandbox/README.md) for the limitations.
40
+ - `intentrax scan [dir]` (1.8.0) lists the destructive or consequential actions
41
+ an agent can reach in a project and flags broad credentials, missing gates
42
+ and success reported without a read-back. Heuristic and static: nothing is
43
+ run or sent. See [scan/README.md](scan/README.md).
44
+ - `intentrax readback` and `@intentrax/sdk/readback` (1.8.0): `confirmThenReport`
45
+ reads the system of record with your read-only check before anyone reports
46
+ success (`CONFIRMED`, `CAUGHT …`, `PENDING`, `UNKNOWN`). Results are
47
+ `SELF_REPORTED`, not an Intentrax attestation. See
48
+ [readback/README.md](readback/README.md).
49
+ - `intentrax mcp pin|check|proxy` and `@intentrax/sdk/mcp` (1.8.0) pin a
50
+ third-party MCP server's tool definitions, report changes (exit 10,
51
+ `CHANGED …`) and block changed or new tools in a stdio proxy. Offline; tool
52
+ descriptions never leave your machine. Covers tool definitions only. It does
53
+ not show that the server's code or behaviour is unchanged. See
54
+ [mcp/README.md](mcp/README.md).
34
55
 
35
56
  The published package exports Node-runnable `.js` modules with `.d.ts` type
36
57
  declarations and is gated on Node 20 and Node 24.
37
58
 
59
+ ## Local assurance sandbox (no key, no network)
60
+
61
+ `intentrax sandbox` runs one consequential action through the whole flow,
62
+ in-process: a signed decision before execution, an executor report (a
63
+ self-report), an independent read-only check of the outcome, a sealed bundle,
64
+ and offline verification (eight per-dimension assessments and the verdict rule).
65
+
66
+ ```bash
67
+ npx @intentrax/sdk sandbox # sample action; outcome confirmed
68
+ npx @intentrax/sdk sandbox --scenario contradicted # ALLOW + "SUCCEEDED", but the read disagrees
69
+ npx @intentrax/sdk sandbox --check ./my-check.mjs # a read-only check of YOUR system
70
+ ```
71
+
72
+ What it is not:
73
+ - **Not production assurance.** Every signature is made by an ephemeral key
74
+ generated on your machine (`environment: "local"`, `trust_bearing: false`,
75
+ written under the gitignored `.intentrax/local/`). The best possible verdict
76
+ is `LOCAL_NON_TRUST_BEARING`, never `VERIFIED_FOR_SCOPE`, whatever key set
77
+ you pin. A contradiction is still reported as `CONFLICTING_EVIDENCE`.
78
+ - **Not a production proof.** The bundle uses the preview effect-assurance
79
+ format. `verify-proof`, hosted verify and the Verification Mark reject it.
80
+ - **Your check is yours.** A `--check` read is labelled `SELF_REPORTED`, not an
81
+ Intentrax-pulled authoritative read. It runs in a worker thread, is
82
+ read-only by contract only, and is the only code in a run that could touch
83
+ a network.
84
+ - It never reads, derives or requests a production or published sandbox key.
85
+
86
+ Limitations, exit codes and the `verify` options (`--keys`, `--issuer-keys`,
87
+ `--require-external-issuer`): [sandbox/README.md](sandbox/README.md).
88
+
38
89
  One-command adapter onboarding:
39
90
 
40
91
  ```bash
@@ -220,8 +271,10 @@ table. It states what the proof establishes and what it does not:
220
271
  `NOT_ASSESSED` for a legacy proof.
221
272
  - `verdict`: derived from the rows by a fixed rule, never asserted by a signer.
222
273
  `VERIFIED_FOR_SCOPE` (record intact, trusted signers; the scope is the
223
- required dimensions only), `INTEGRITY_ONLY` (signer not established) or
224
- `VERIFICATION_FAILED` (for example a revoked signer).
274
+ required dimensions only), `INTEGRITY_ONLY` (signer not established),
275
+ `CONFLICTING_EVIDENCE` (since 1.7.0: any dimension is `CONTRADICTED`, required
276
+ or not, for example a sealed `NON_COMPLIANT` policy decision on a trusted
277
+ proof) or `VERIFICATION_FAILED` (for example a revoked signer).
225
278
  - `limitations[]`: machine-readable codes with text. A legacy proof always lists
226
279
  `EXECUTION_NOT_ATTESTED`, `EFFECT_NOT_VERIFIED`, `POLICY_BINDING_SYNTHETIC` and
227
280
  `COMPLETENESS_NOT_ESTABLISHED`, plus `SIGNER_AUTHENTICITY_REQUIRES_PINNED_ANCHORS`
package/cli/intentrax.mjs CHANGED
@@ -5,7 +5,7 @@ import { dirname, isAbsolute, join, relative, resolve } from "node:path";
5
5
  import { pathToFileURL } from "node:url";
6
6
  import { buildAgentGatewayAdmissionEnvelope, buildLegacyVerificationAssessment, compilePolicyDocument, evaluateCompiledPolicy, policyReevaluationMismatches } from "../index.js";
7
7
 
8
- const VERSION = "1.6.0";
8
+ const VERSION = "1.8.0";
9
9
  const ADMISSION_SCHEMA_VERSION = "intentrax.runtime.agent_admission_request/1.0";
10
10
  const INIT_SCHEMA_VERSION = "intentrax.onboarding.agent_adapter_init/1.0";
11
11
  const ACTION_RECEIPT_SCHEMA_VERSION = "intentrax.onboarding.agent_adapter_action_receipt/1.0";
@@ -249,6 +249,30 @@ async function main(argv) {
249
249
  console.log(VERSION);
250
250
  return 0;
251
251
  }
252
+ if (command === "sandbox") {
253
+ // Local assurance sandbox: ephemeral local keys, no network, verdict capped at
254
+ // LOCAL_NON_TRUST_BEARING. Never production assurance. See sandbox/README.md.
255
+ const { sandboxMain } = await import("../sandbox/cli.mjs");
256
+ return sandboxMain([subject, ...rest].filter((value) => value !== undefined));
257
+ }
258
+ if (command === "mcp") {
259
+ // MCP tool pinning: pin a server's tool definitions, check them, or proxy
260
+ // with --on-drift block. Offline; no Intentrax account. See mcp/README.md.
261
+ const { mcpMain } = await import("../mcp/cli.mjs");
262
+ return mcpMain([subject, ...rest].filter((value) => value !== undefined));
263
+ }
264
+ if (command === "readback") {
265
+ // Read the outcome back before reporting success (SELF_REPORTED; not an
266
+ // Intentrax attestation). See readback/README.md.
267
+ const { readbackMain } = await import("../readback/cli.mjs");
268
+ return readbackMain([subject, ...rest].filter((value) => value !== undefined));
269
+ }
270
+ if (command === "scan") {
271
+ // Static, report-only scan for agent actions an agent can reach (exit 0
272
+ // none, 20 findings, 2 error). Nothing is run or sent. See scan/README.md.
273
+ const { scanMain } = await import("../scan/cli.mjs");
274
+ return scanMain([subject, ...rest].filter((value) => value !== undefined));
275
+ }
252
276
  if (command === "check-init") {
253
277
  const options = parseCheckInitOptions([subject, ...rest].filter((value) => value !== undefined));
254
278
  const output = await checkInitCommand(options);
@@ -326,6 +350,7 @@ async function main(argv) {
326
350
  console.log("Note: the default base URL http://127.0.0.1:8080 targets a locally run Intentrax engine; the hosted engine base URL is https://api.intentrax.com (override with --base-url or INTENTRAX_BASE_URL).");
327
351
  console.log("INTENTRAX_API_KEY and your sandbox base URL are issued after an architectural review: https://www.intentrax.com/request-architectural-review");
328
352
  console.log("Offline check that works right now with no key: npx @intentrax/sdk check-init");
353
+ console.log("See the whole assurance flow locally, no key or network (not production assurance): npx @intentrax/sdk sandbox");
329
354
  return 0;
330
355
  }
331
356
 
@@ -2991,6 +3016,13 @@ Usage:
2991
3016
  intentrax check-init --output-dir <dir> [--json]
2992
3017
  intentrax verify-proof <proof-export.json> [--trusted-keys <key-set.json>] [--policy-document <policy.json>] [--json] [--report-out <file>]
2993
3018
  intentrax verify-pdf-receipt <receipt.pdf> --pdf-hash <X-Intentrax-PDF-Hash> [--json] [--report-out <file>]
3019
+ intentrax sandbox [--scenario confirmed|contradicted] [--check <read-only-check.mjs>] [--dir <dir>] [--json]
3020
+ intentrax sandbox verify <bundle.json> [--keys <local-key-set.json>] [--issuer-keys <pinned-external-issuers.json>] [--require-external-issuer <issuer>]... [--json]
3021
+ intentrax readback --check <read-only-check.mjs> --expected <json> [--claimed <json>] [--retries N] [--json]
3022
+ intentrax scan [dir] [--json] [--include-tests] [--max-files N]
3023
+ intentrax mcp pin --server <cmd|url> [--name <name>] [--accept <tool,...> | --replace] [--json]
3024
+ intentrax mcp check [--pins <file>] [--name <name>] [--json]
3025
+ intentrax mcp proxy [--pins <file>] [--name <name>] [--on-drift block|warn]
2994
3026
 
2995
3027
  Adapters:
2996
3028
  ${Object.keys(ADAPTERS).join(", ")}
@@ -3054,6 +3086,23 @@ Proof export verification:
3054
3086
  Add more sets, for example revocations, with --trusted-keys <file>
3055
3087
  (repeatable).
3056
3088
 
3089
+ Read-back (intentrax readback --help):
3090
+ Reads the system of record with your read-only check before anyone reports
3091
+ success. 0 CONFIRMED, 12 CONTRADICTED (CAUGHT), 10 PENDING, 11 UNKNOWN,
3092
+ 64 usage. SELF_REPORTED: not an Intentrax attestation.
3093
+
3094
+ Scan (intentrax scan --help):
3095
+ Lists the destructive or consequential actions an AI agent can reach in a
3096
+ project and flags broad credentials (EXPOSED), missing gates (UNGATED) and
3097
+ success reported without a read-back (SELF-REPORTED). Heuristic and static:
3098
+ nothing is run or sent. 0 no findings, 20 findings, 2 error.
3099
+
3100
+ MCP tool pinning (intentrax mcp --help):
3101
+ pin records a server's tool definitions in .intentrax/mcp-pins.json; check
3102
+ compares them (0 MATCH, 10 CHANGED, 2 UNCHECKED, 1 usage); proxy blocks
3103
+ changed and new tools in a stdio proxy. Covers tool definitions only. It
3104
+ does not show that the server's code or behaviour is unchanged.
3105
+
3057
3106
  PDF receipt verification:
3058
3107
  verify-pdf-receipt reads downloaded PDF receipt bytes, checks the PDF header,
3059
3108
  recomputes SHA-256, and compares it with the X-Intentrax-PDF-Hash response
@@ -3074,6 +3123,13 @@ Examples:
3074
3123
  intentrax verify-proof node_modules/@intentrax/sdk/examples/sandbox/tampered-aep-swap.json
3075
3124
  intentrax verify-proof proof-export.json --trusted-keys intentrax-production-keys.json
3076
3125
  intentrax verify-pdf-receipt .intentrax/proof-001-aep-receipt.pdf --pdf-hash <X-Intentrax-PDF-Hash>
3126
+ intentrax sandbox
3127
+ intentrax sandbox --scenario contradicted
3128
+ intentrax sandbox --check ./my-check.mjs
3129
+ intentrax readback --check ./read-refund.mjs --expected '{"status":"succeeded"}' --claimed '{"status":"processed"}'
3130
+ intentrax scan .
3131
+ intentrax mcp pin --name github --server https://api.example.com/mcp --header 'Authorization: Bearer \${GITHUB_TOKEN}'
3132
+ intentrax mcp check
3077
3133
  `);
3078
3134
  }
3079
3135
 
package/index.js CHANGED
@@ -1116,7 +1116,9 @@ const SATISFYING_ASSESSMENT_RESULTS = new Set(["VERIFIED", "ATTESTED", "OBSERVED
1116
1116
 
1117
1117
  // §5.4, verbatim order. `assessments` is { [dimension]: result }. A required
1118
1118
  // dimension that is missing or NOT_APPLICABLE counts as INSUFFICIENT_EVIDENCE
1119
- // (invariant 4: never a bare pass).
1119
+ // (invariant 4: never a bare pass). A CONTRADICTED result in ANY dimension,
1120
+ // required by the profile or not, yields CONFLICTING_EVIDENCE (finding V-1):
1121
+ // a sealed NON_COMPLIANT policy decision must never read as VERIFIED_FOR_SCOPE.
1120
1122
  export function deriveAssuranceVerdict(assessments, profile) {
1121
1123
  const required = Object.hasOwn(ASSURANCE_PROFILES, profile) ? ASSURANCE_PROFILES[profile] : undefined;
1122
1124
  if (!required) {
@@ -1126,7 +1128,7 @@ export function deriveAssuranceVerdict(assessments, profile) {
1126
1128
  const req = required.map((d) => assessments[d] ?? "INSUFFICIENT_EVIDENCE");
1127
1129
  if (all.includes("FAILED")) return ASSURANCE_VERDICTS.VERIFICATION_FAILED;
1128
1130
  if (assessments.SIGNER_AUTHENTICITY !== "VERIFIED") return ASSURANCE_VERDICTS.INTEGRITY_ONLY;
1129
- if (req.includes("CONTRADICTED")) return ASSURANCE_VERDICTS.CONFLICTING_EVIDENCE;
1131
+ if (all.includes("CONTRADICTED")) return ASSURANCE_VERDICTS.CONFLICTING_EVIDENCE;
1130
1132
  if (req.includes("PENDING")) return ASSURANCE_VERDICTS.PENDING_FINALITY;
1131
1133
  if (req.some((r) => WEAK_ASSESSMENT_RESULTS.has(r) || !SATISFYING_ASSESSMENT_RESULTS.has(r))) return ASSURANCE_VERDICTS.INSUFFICIENT_EVIDENCE;
1132
1134
  return ASSURANCE_VERDICTS.VERIFIED_FOR_SCOPE;
package/index.ts CHANGED
@@ -1116,7 +1116,9 @@ const SATISFYING_ASSESSMENT_RESULTS = new Set(["VERIFIED", "ATTESTED", "OBSERVED
1116
1116
 
1117
1117
  // §5.4, verbatim order. `assessments` is { [dimension]: result }. A required
1118
1118
  // dimension that is missing or NOT_APPLICABLE counts as INSUFFICIENT_EVIDENCE
1119
- // (invariant 4: never a bare pass).
1119
+ // (invariant 4: never a bare pass). A CONTRADICTED result in ANY dimension,
1120
+ // required by the profile or not, yields CONFLICTING_EVIDENCE (finding V-1):
1121
+ // a sealed NON_COMPLIANT policy decision must never read as VERIFIED_FOR_SCOPE.
1120
1122
  export function deriveAssuranceVerdict(assessments, profile) {
1121
1123
  const required = Object.hasOwn(ASSURANCE_PROFILES, profile) ? ASSURANCE_PROFILES[profile] : undefined;
1122
1124
  if (!required) {
@@ -1126,7 +1128,7 @@ export function deriveAssuranceVerdict(assessments, profile) {
1126
1128
  const req = required.map((d) => assessments[d] ?? "INSUFFICIENT_EVIDENCE");
1127
1129
  if (all.includes("FAILED")) return ASSURANCE_VERDICTS.VERIFICATION_FAILED;
1128
1130
  if (assessments.SIGNER_AUTHENTICITY !== "VERIFIED") return ASSURANCE_VERDICTS.INTEGRITY_ONLY;
1129
- if (req.includes("CONTRADICTED")) return ASSURANCE_VERDICTS.CONFLICTING_EVIDENCE;
1131
+ if (all.includes("CONTRADICTED")) return ASSURANCE_VERDICTS.CONFLICTING_EVIDENCE;
1130
1132
  if (req.includes("PENDING")) return ASSURANCE_VERDICTS.PENDING_FINALITY;
1131
1133
  if (req.some((r) => WEAK_ASSESSMENT_RESULTS.has(r) || !SATISFYING_ASSESSMENT_RESULTS.has(r))) return ASSURANCE_VERDICTS.INSUFFICIENT_EVIDENCE;
1132
1134
  return ASSURANCE_VERDICTS.VERIFIED_FOR_SCOPE;
package/mcp/README.md ADDED
@@ -0,0 +1,138 @@
1
+ # `@intentrax/sdk/mcp`: "A tool you approved changed" (R1b)
2
+
3
+ Pins the tool definitions of a third-party MCP server and catches changes made after you approved them: rug pulls, rewritten descriptions, widened schemas, and annotations flipped to look safer. It also blocks those changes in a proxy.
4
+
5
+ Everything runs **offline and in private**. It needs no Intentrax account or token. Tool descriptions never leave your machine.
6
+
7
+ > Covers tool definitions only. It does not show that the server's code or behaviour is unchanged.
8
+
9
+ **Status:** shipped in `@intentrax/sdk` 1.8.0 as `intentrax mcp pin|check|proxy` and the
10
+ `@intentrax/sdk/mcp` subpath export (with types). Run `npx @intentrax/sdk mcp --help`.
11
+
12
+ ## Commands
13
+
14
+ ```
15
+ intentrax mcp pin --server <cmd|url> [--name <name>] [--out .intentrax/mcp-pins.json]
16
+ intentrax mcp pin --name <name> --accept <tool,...> # re-pin named tools on purpose
17
+ intentrax mcp pin --name <name> --replace # re-pin everything
18
+ intentrax mcp check [--pins .intentrax/mcp-pins.json] [--name <name>] [--json]
19
+ intentrax mcp proxy [--pins ...] [--name <name>] [--on-drift block|warn]
20
+ ```
21
+
22
+ Server options:
23
+ - `--server <cmd|url>` takes a command line or an MCP URL; `-- <command> [args...]` gives a stdio server as argv instead.
24
+ - `--header "Name: value"` (HTTP) and `--env KEY=value` (stdio) are repeatable. Put credentials in `${ENV_VAR}` placeholders, for example `--header 'Authorization: Bearer ${GITHUB_TOKEN}'` (single quotes, so a POSIX shell does not expand it; Intentrax expands it when connecting).
25
+ - `--registry-name` records the MCP Registry name with the pin; `--timeout-ms` sets the per-request timeout (default 15000).
26
+
27
+ In a host's MCP config, run the proxy in place of the server:
28
+
29
+ ```json
30
+ { "command": "npx", "args": ["-y", "@intentrax/sdk", "mcp", "proxy", "--name", "github"] }
31
+ ```
32
+
33
+ ### `check` exit codes
34
+
35
+ | Exit | Result | Meaning |
36
+ | --- | --- | --- |
37
+ | 0 | `MATCH` | Every pinned server's tools match its pin. |
38
+ | 10 | `CHANGED` | Drift. The first line starts with `CHANGED` and lists, for each tool, the change categories and any annotation weakening (e.g. `readOnlyHint became true`). |
39
+ | 2 | `UNCHECKED` | The check failed closed. The tools couldn't be listed (timeout, exit, HTTP error, a failing or looping page), or the pin file is missing, invalid or hand-edited. |
40
+ | 1 | `USAGE` | Bad arguments. |
41
+
42
+ **Several servers:**
43
+ - When drift and an unreachable server occur together, the exit code is 10.
44
+ - Both cases are non-zero.
45
+
46
+ **Every report:**
47
+ - includes the cloaking note;
48
+ - ends with the fixed limitation line.
49
+
50
+ ### `pin`
51
+
52
+ - **A first pin follows every `nextCursor`.** A partial list is an error and writes nothing.
53
+ - **Re-running `pin` on a changed server:**
54
+ - refuses to overwrite and exits 10;
55
+ - `--accept` re-pins only the tools you name: changed, new or removed;
56
+ - every other tool keeps its pinned definition.
57
+ - **Credentials are never stored.** Literal values in sensitive headers, env entries, URL query parameters or URL user-info are refused. Use `${ENV_VAR}` placeholders. They are expanded only when connecting and never logged.
58
+
59
+ ### `proxy`
60
+
61
+ A stdio proxy that sits between the host and the server. The server can be a stdio command or Streamable HTTP. The proxy:
62
+
63
+ - **Re-checks on connect and on `notifications/tools/list_changed`.** It runs on the host's own session.
64
+ - **Compares every `tools/list` response the host receives, tool by tool.** This is what defeats cloaking. `check` cannot do it, because it only sees what its own client is sent.
65
+ - **With `--on-drift block` (the default):**
66
+ - changed and new tools are removed from `tools/list`;
67
+ - `tools/call` to them is refused with JSON-RPC error `-32090`, which explains how to re-pin;
68
+ - calls wait while a re-check runs;
69
+ - if the tools cannot be listed, calls are refused.
70
+ - **With `--on-drift warn`:** it forwards everything and only logs.
71
+ - **Logs go to stderr only.** The protocol stream stays pure JSON-RPC.
72
+
73
+ ## Pin file: `.intentrax/mcp-pins.json` (`intentrax.mcp.pin/0.1`, unsigned)
74
+
75
+ ```json
76
+ {
77
+ "schema": "intentrax.mcp.pin/0.1",
78
+ "note": "Unsigned v0.1 pin file: ...",
79
+ "servers": {
80
+ "github": {
81
+ "profile": "intentrax.mcp.tool_manifest/0.1",
82
+ "server": { "registry_name": "com.example/github", "transport": "streamable-http",
83
+ "url": "https://…", "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" },
84
+ "server_info": { "name": "…", "version": "…" } },
85
+ "protocol_version": "2026-07-28",
86
+ "manifest_digest": "sha256:…",
87
+ "tools": [{ "name": "…", "digest": "sha256:…", "definition": { "name": "…", "…": "…" } }],
88
+ "pinned_at": "2026-11-19T12:00:00Z",
89
+ "pinned_by": "local"
90
+ }
91
+ }
92
+ }
93
+ ```
94
+
95
+ **How it relates to assessment §5.A:**
96
+ - The fields are the §5.A fields.
97
+ - Each tool also keeps its normalized definition, so `check` can say *which* fields changed.
98
+ - On load, every definition is re-hashed. A hand-edited entry is reported as inconsistent (exit 2), never trusted.
99
+ - The digests are the prototype's rules, unchanged:
100
+ - `INTENTRAX_MCP_TOOL_DEFINITION_V0_1`;
101
+ - `INTENTRAX_MCP_TOOL_MANIFEST_V0_1`;
102
+ - RFC 8785 canonical JSON;
103
+ - `_meta` is excluded.
104
+
105
+ ## Protocol support
106
+
107
+ **2026-07-28 (stateless):**
108
+ - `server/discover` first, with `_meta` on every request.
109
+ - Over HTTP, the `MCP-Protocol-Version`, `Mcp-Method` and `Mcp-Name` headers are set.
110
+
111
+ **Fallback to legacy `initialize`:** for 2025-11-25, 2025-06-18 and 2025-03-26.
112
+ - The fallback is used if discover is refused, times out, or the process dies on it. In that last case, the process is restarted once.
113
+ - 2024-11-05 is not accepted (fail closed).
114
+
115
+ **Streamable HTTP:**
116
+ - JSON and SSE responses;
117
+ - `Mcp-Session-Id`;
118
+ - a GET notification stream (the proxy uses it for `list_changed`).
119
+
120
+ **Not covered:**
121
+ - 2026-07-28 `subscriptions/listen` is forwarded by the proxy but not opened by it.
122
+ - Batches are refused by the proxy.
123
+
124
+ ## Modules
125
+
126
+ | File | Purpose |
127
+ | --- | --- |
128
+ | `canonical.mjs`, `tool-manifest.mjs`, `receipt-meta.mjs` | Ported from `examples/mcp-trust-receipts/src/`, with the same behaviour and profile strings. |
129
+ | `client.mjs` | Minimal MCP client: stdio and Streamable HTTP transports, discover/initialize, `tools/list` pagination, timeouts. |
130
+ | `commands.mjs` | `pin`, `check`: pure functions returning `{ exitCode, result, lines, report }`. |
131
+ | `proxy.mjs` | `startProxy` / `runProxy`. |
132
+ | `index.mjs` | Barrel for the future `@intentrax/sdk/mcp` export. |
133
+
134
+ ## Tests
135
+
136
+ ```bash
137
+ cd sdk/typescript/mcp && node --test test/*.test.mjs
138
+ ```
@@ -0,0 +1,12 @@
1
+ // Types for canonical.mjs: RFC 8785 canonical JSON and domain-separated SHA-256.
2
+
3
+ export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
4
+
5
+ /** RFC 8785 canonical JSON. Throws on NaN, Infinity, undefined members, non-plain objects, bigint. */
6
+ export function canonicalJson(value: JsonValue): string;
7
+
8
+ /** Lower-case hex SHA-256 of a string or bytes. */
9
+ export function sha256Hex(data: string | Uint8Array): string;
10
+
11
+ /** "sha256:" + hex(SHA-256(domain || canonicalJson(value))). */
12
+ export function domainDigest(domain: string, value: JsonValue): `sha256:${string}`;
@@ -0,0 +1,70 @@
1
+ // Canonical JSON for MCP tool manifests (RFC 8785 / JCS profile).
2
+ //
3
+ // The SDK's `canonicalJson` (sdk/typescript/index.ts) accepts integers only,
4
+ // because every Intentrax-signed structure is integer-only. MCP tool
5
+ // definitions are third-party JSON Schema and routinely carry non-integer
6
+ // numbers (`"minimum": 0.5`), so this module uses the full RFC 8785 rule
7
+ // instead (this file is ported unchanged in behaviour from
8
+ // examples/mcp-trust-receipts/src/canonical.mjs):
9
+ // - object keys sorted by UTF-16 code unit (JS default sort);
10
+ // - no insignificant whitespace;
11
+ // - strings via JSON.stringify (ES2019 well-formed escaping);
12
+ // - numbers via the ECMAScript Number-to-String rule (JSON.stringify),
13
+ // which is exactly the RFC 8785 number serialization; -0 becomes 0;
14
+ // - NaN, Infinity, undefined, functions, symbols, bigint and non-plain
15
+ // objects are rejected (fail closed: an unhashable manifest is an error,
16
+ // never a silent partial digest).
17
+ //
18
+ // For integer-only input this produces the same bytes as the SDK rule.
19
+
20
+ import { createHash } from "node:crypto";
21
+
22
+ export function canonicalJson(value) {
23
+ if (value === null) {
24
+ return "null";
25
+ }
26
+ if (Array.isArray(value)) {
27
+ return "[" + value.map((item) => canonicalJson(item)).join(",") + "]";
28
+ }
29
+ switch (typeof value) {
30
+ case "string":
31
+ return JSON.stringify(value);
32
+ case "boolean":
33
+ return value ? "true" : "false";
34
+ case "number":
35
+ if (!Number.isFinite(value)) {
36
+ throw new Error("canonical_json: non-finite number");
37
+ }
38
+ return JSON.stringify(value === 0 ? 0 : value);
39
+ case "object": {
40
+ const proto = Object.getPrototypeOf(value);
41
+ if (proto !== Object.prototype && proto !== null) {
42
+ throw new Error("canonical_json: only plain objects are allowed");
43
+ }
44
+ return "{" + Object.keys(value).sort().map((key) => {
45
+ const member = value[key];
46
+ if (member === undefined) {
47
+ throw new Error("canonical_json: undefined member " + JSON.stringify(key));
48
+ }
49
+ return JSON.stringify(key) + ":" + canonicalJson(member);
50
+ }).join(",") + "}";
51
+ }
52
+ default:
53
+ throw new Error("canonical_json: unsupported value of type " + typeof value);
54
+ }
55
+ }
56
+
57
+ export function sha256Hex(data) {
58
+ return createHash("sha256").update(data).digest("hex");
59
+ }
60
+
61
+ // Domain-separated digest: sha256(domain || canonical_json(value)), returned
62
+ // as "sha256:<hex>". The domain string stops a digest computed for one
63
+ // purpose being replayed as another (same pattern as the SDK's
64
+ // *_HASH_DOMAIN constants).
65
+ export function domainDigest(domain, value) {
66
+ if (typeof domain !== "string" || domain.length === 0) {
67
+ throw new Error("domain_digest: domain is required");
68
+ }
69
+ return "sha256:" + sha256Hex(Buffer.from(domain + canonicalJson(value), "utf8"));
70
+ }
package/mcp/cli.d.ts ADDED
@@ -0,0 +1,16 @@
1
+ /** `intentrax mcp pin|check|proxy`. Resolves to the exit code (0 match, 10 drift, 2 unchecked, 1 usage). */
2
+ export function mcpMain(
3
+ argv?: string[],
4
+ io?: {
5
+ out?: (text: string) => unknown;
6
+ err?: (text: string) => unknown;
7
+ cwd?: string;
8
+ env?: Record<string, string | undefined>;
9
+ invokedAs?: string;
10
+ input?: NodeJS.ReadableStream;
11
+ output?: NodeJS.WritableStream;
12
+ errorOutput?: { write(chunk: string | Uint8Array): unknown };
13
+ },
14
+ ): Promise<number>;
15
+ export function parseMcpArgs(argv: string[]): { sub: "pin" | "check" | "proxy" | "help"; opts: Record<string, unknown> };
16
+ export function usage(invokedAs?: string): string;