@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.
- package/README.md +56 -3
- package/cli/intentrax.mjs +57 -1
- package/index.js +4 -2
- package/index.ts +4 -2
- package/mcp/README.md +138 -0
- package/mcp/canonical.d.ts +12 -0
- package/mcp/canonical.mjs +70 -0
- package/mcp/cli.d.ts +16 -0
- package/mcp/cli.mjs +214 -0
- package/mcp/client.d.ts +131 -0
- package/mcp/client.mjs +955 -0
- package/mcp/commands.d.ts +113 -0
- package/mcp/commands.mjs +575 -0
- package/mcp/index.d.ts +12 -0
- package/mcp/index.mjs +12 -0
- package/mcp/proxy.d.ts +47 -0
- package/mcp/proxy.mjs +434 -0
- package/mcp/receipt-meta.d.ts +59 -0
- package/mcp/receipt-meta.mjs +178 -0
- package/mcp/tool-manifest.d.ts +74 -0
- package/mcp/tool-manifest.mjs +154 -0
- package/package.json +19 -1
- package/readback/README.md +352 -0
- package/readback/bridge.mjs +71 -0
- package/readback/cli.mjs +150 -0
- package/readback/confirm.mjs +404 -0
- package/readback/index.mjs +12 -0
- package/readback/recipe-worker.mjs +33 -0
- package/readback/recipes/_shared.mjs +126 -0
- package/readback/recipes/email-delivery.mjs +136 -0
- package/readback/recipes/github-issue.mjs +88 -0
- package/readback/recipes/http-json.mjs +109 -0
- package/readback/recipes/sql-row.mjs +96 -0
- package/readback/recipes/stripe-refund.mjs +73 -0
- package/readback/redact.mjs +68 -0
- package/sandbox/README.md +255 -0
- package/sandbox/authority.mjs +66 -0
- package/sandbox/bundle.mjs +93 -0
- package/sandbox/canonical.mjs +64 -0
- package/sandbox/check-runner.mjs +50 -0
- package/sandbox/check-worker.mjs +30 -0
- package/sandbox/cli.mjs +376 -0
- package/sandbox/effect-verifier.mjs +242 -0
- package/sandbox/effects.mjs +80 -0
- package/sandbox/envelope.mjs +174 -0
- package/sandbox/examples/read-only-check.example.mjs +32 -0
- package/sandbox/external-decision.mjs +364 -0
- package/sandbox/keys.mjs +179 -0
- package/sandbox/model.mjs +170 -0
- package/sandbox/run.mjs +324 -0
- package/sandbox/time.mjs +18 -0
- package/sandbox/verifier.mjs +503 -0
- package/scan/README.md +211 -0
- package/scan/classify.mjs +276 -0
- package/scan/cli.mjs +102 -0
- package/scan/configs.mjs +261 -0
- package/scan/credentials.mjs +121 -0
- package/scan/extract.mjs +323 -0
- package/scan/gates.mjs +94 -0
- package/scan/report.mjs +58 -0
- package/scan/scan.mjs +571 -0
- 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/`),
|
|
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)
|
|
224
|
-
`
|
|
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.
|
|
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 (
|
|
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 (
|
|
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;
|