@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
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
// Types for commands.mjs: `intentrax mcp pin` and `intentrax mcp check` as
|
|
2
|
+
// functions returning structured results plus exit codes.
|
|
3
|
+
|
|
4
|
+
import type { ClientOptions, ListedTools, ServerInput, ServerSpec } from "./client.js";
|
|
5
|
+
import type { Digest, McpToolDefinition, ToolChange, TOOL_MANIFEST_PROFILE } from "./tool-manifest.js";
|
|
6
|
+
|
|
7
|
+
export const PIN_FILE_SCHEMA: "intentrax.mcp.pin/0.1";
|
|
8
|
+
export const CHECK_REPORT_SCHEMA: "intentrax.mcp.check_report/0.1";
|
|
9
|
+
export const PIN_REPORT_SCHEMA: "intentrax.mcp.pin_report/0.1";
|
|
10
|
+
export const DEFAULT_PINS_PATH: ".intentrax/mcp-pins.json";
|
|
11
|
+
export const EXIT_MATCH: 0;
|
|
12
|
+
export const EXIT_USAGE: 1;
|
|
13
|
+
export const EXIT_UNCHECKED: 2;
|
|
14
|
+
export const EXIT_DRIFT: 10;
|
|
15
|
+
/** Fixed last line of every report. */
|
|
16
|
+
export const LIMITATION: "Covers tool definitions only. It does not show that the server's code or behaviour is unchanged.";
|
|
17
|
+
export const CLOAKING_NOTE: string;
|
|
18
|
+
export const UNSIGNED_NOTE: string;
|
|
19
|
+
|
|
20
|
+
export class PinFileError extends Error {
|
|
21
|
+
constructor(code: "pins_missing" | "pins_invalid" | "pins_inconsistent" | "pins_ambiguous", message: string);
|
|
22
|
+
readonly code: "pins_missing" | "pins_invalid" | "pins_inconsistent" | "pins_ambiguous";
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** One server in `.intentrax/mcp-pins.json` (assessment §5.A fields plus each tool's definition). */
|
|
26
|
+
export interface PinEntry {
|
|
27
|
+
profile: typeof TOOL_MANIFEST_PROFILE;
|
|
28
|
+
server: {
|
|
29
|
+
registry_name?: string;
|
|
30
|
+
transport: "stdio" | "streamable-http";
|
|
31
|
+
url?: string;
|
|
32
|
+
headers?: Record<string, string>;
|
|
33
|
+
command?: string[];
|
|
34
|
+
env?: Record<string, string>;
|
|
35
|
+
cwd?: string;
|
|
36
|
+
server_info?: { name?: string; version?: string };
|
|
37
|
+
};
|
|
38
|
+
protocol_version: string;
|
|
39
|
+
manifest_digest: Digest;
|
|
40
|
+
tools: Array<{ name: string; digest: Digest; definition: McpToolDefinition }>;
|
|
41
|
+
pinned_at: string;
|
|
42
|
+
pinned_by: "local";
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
export interface PinFile {
|
|
46
|
+
schema: typeof PIN_FILE_SCHEMA;
|
|
47
|
+
note?: string;
|
|
48
|
+
servers: Record<string, PinEntry>;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export interface CommandResult<R extends string, Report> {
|
|
52
|
+
exitCode: 0 | 1 | 2 | 10;
|
|
53
|
+
result: R;
|
|
54
|
+
/** Human report. Line 1 is the verdict (CHANGED / UNCHECKED / MATCH / PINNED / ...); the last line is LIMITATION. */
|
|
55
|
+
lines: string[];
|
|
56
|
+
/** --json report. */
|
|
57
|
+
report: Report;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
export interface CheckServerReport {
|
|
61
|
+
name: string;
|
|
62
|
+
result: "MATCH" | "CHANGED" | "UNCHECKED";
|
|
63
|
+
server?: string;
|
|
64
|
+
protocol_version?: string;
|
|
65
|
+
pinned_at?: string;
|
|
66
|
+
pinned_tool_count?: number;
|
|
67
|
+
current_tool_count?: number;
|
|
68
|
+
pages?: number;
|
|
69
|
+
manifest_digest_pinned?: Digest;
|
|
70
|
+
manifest_digest_current?: Digest;
|
|
71
|
+
added?: string[];
|
|
72
|
+
removed?: string[];
|
|
73
|
+
changed?: ToolChange[];
|
|
74
|
+
error?: string;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
export interface CheckReport {
|
|
78
|
+
schema: typeof CHECK_REPORT_SCHEMA;
|
|
79
|
+
result: "MATCH" | "CHANGED" | "UNCHECKED" | "USAGE";
|
|
80
|
+
exit_code?: number;
|
|
81
|
+
pins?: string;
|
|
82
|
+
servers?: CheckServerReport[];
|
|
83
|
+
notes?: string[];
|
|
84
|
+
limitation?: string;
|
|
85
|
+
error?: string;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
export interface CommandOptions extends Pick<ClientOptions, "timeoutMs" | "log" | "allowInsecureHttp"> {
|
|
89
|
+
cwd?: string;
|
|
90
|
+
env?: Record<string, string | undefined>;
|
|
91
|
+
/** Injectable for tests; defaults to listServerTools. */
|
|
92
|
+
listTools?: (spec: ServerSpec, options: ClientOptions) => Promise<ListedTools>;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** exit 0 = match, 10 = drift (line 1 starts with "CHANGED"), 2 = could not check (fail closed), 1 = usage. */
|
|
96
|
+
export function check(options?: CommandOptions & { pins?: string; name?: string; server?: ServerInput }): Promise<CommandResult<"MATCH" | "CHANGED" | "UNCHECKED" | "USAGE", CheckReport>>;
|
|
97
|
+
|
|
98
|
+
export function pin(options?: CommandOptions & {
|
|
99
|
+
server?: ServerInput;
|
|
100
|
+
name?: string;
|
|
101
|
+
out?: string;
|
|
102
|
+
/** Re-pin only these tools (changed, new or removed), on purpose. */
|
|
103
|
+
accept?: string[];
|
|
104
|
+
/** Re-pin the whole server. */
|
|
105
|
+
replace?: boolean;
|
|
106
|
+
registryName?: string;
|
|
107
|
+
now?: () => Date;
|
|
108
|
+
}): Promise<CommandResult<"PINNED" | "UNCHANGED" | "REPINNED" | "CHANGED" | "UNPINNED" | "USAGE", Record<string, unknown>> & { written: string | null }>;
|
|
109
|
+
|
|
110
|
+
export function validatePinEntry(name: string, entry: unknown): McpToolDefinition[];
|
|
111
|
+
export function loadPinFile(path: string): PinFile;
|
|
112
|
+
export function loadPinnedServer(pinsPath: string, name?: string): { name: string; entry: PinEntry; definitions: McpToolDefinition[]; spec: ServerSpec };
|
|
113
|
+
export function summarizeDiff(diff: { added: string[]; removed: string[]; changed: ToolChange[] }): string;
|
package/mcp/commands.mjs
ADDED
|
@@ -0,0 +1,575 @@
|
|
|
1
|
+
// `intentrax mcp pin` and `intentrax mcp check` as functions (R1b).
|
|
2
|
+
//
|
|
3
|
+
// Each command returns { exitCode, result, lines, report } and never prints
|
|
4
|
+
// or exits: the CLI prints `lines` (or `report` with --json) and exits with
|
|
5
|
+
// `exitCode`.
|
|
6
|
+
//
|
|
7
|
+
// check exit 0 = every pinned server's tools match its pin (MATCH)
|
|
8
|
+
// exit 10 = drift; first line starts with "CHANGED" (CHANGED)
|
|
9
|
+
// exit 2 = could not check: tools not listable, pin file
|
|
10
|
+
// missing/invalid (fail closed) (UNCHECKED)
|
|
11
|
+
// exit 1 = usage error
|
|
12
|
+
// pin exit 0 = pinned / already matching / accepted with no drift left
|
|
13
|
+
// exit 10 = existing pin differs and was NOT re-pinned (or drift
|
|
14
|
+
// remains after --accept)
|
|
15
|
+
// exit 2 = could not list tools, or the pin file is unreadable
|
|
16
|
+
// exit 1 = usage error (bad name, credential in the spec, ...)
|
|
17
|
+
//
|
|
18
|
+
// The pin file (`.intentrax/mcp-pins.json`, schema intentrax.mcp.pin/0.1) is
|
|
19
|
+
// the user's own, UNSIGNED file. Each entry has the assessment §5.A fields
|
|
20
|
+
// plus each tool's normalized definition, so a later check can say which
|
|
21
|
+
// fields changed and not just that a digest differs. On load, every
|
|
22
|
+
// definition is re-hashed against its digest and the manifest digest, so a
|
|
23
|
+
// hand-edited entry is reported as inconsistent rather than trusted.
|
|
24
|
+
|
|
25
|
+
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
|
|
26
|
+
import { dirname, resolve } from "node:path";
|
|
27
|
+
import { randomBytes } from "node:crypto";
|
|
28
|
+
import {
|
|
29
|
+
TOOL_MANIFEST_PROFILE,
|
|
30
|
+
diffToolManifests,
|
|
31
|
+
normalizeToolDefinition,
|
|
32
|
+
toolDefinitionDigest,
|
|
33
|
+
toolManifestDigest,
|
|
34
|
+
} from "./tool-manifest.mjs";
|
|
35
|
+
import { McpClientError, describeServer, findStoredSecrets, listServerTools, parseServerSpec } from "./client.mjs";
|
|
36
|
+
|
|
37
|
+
export const PIN_FILE_SCHEMA = "intentrax.mcp.pin/0.1";
|
|
38
|
+
export const CHECK_REPORT_SCHEMA = "intentrax.mcp.check_report/0.1";
|
|
39
|
+
export const PIN_REPORT_SCHEMA = "intentrax.mcp.pin_report/0.1";
|
|
40
|
+
export const DEFAULT_PINS_PATH = ".intentrax/mcp-pins.json";
|
|
41
|
+
|
|
42
|
+
export const EXIT_MATCH = 0;
|
|
43
|
+
export const EXIT_USAGE = 1;
|
|
44
|
+
export const EXIT_UNCHECKED = 2;
|
|
45
|
+
export const EXIT_DRIFT = 10;
|
|
46
|
+
|
|
47
|
+
export const LIMITATION = "Covers tool definitions only. It does not show that the server's code or behaviour is unchanged.";
|
|
48
|
+
export const CLOAKING_NOTE =
|
|
49
|
+
"This check sees the tools the server sent to this client. A server can send different tools to other clients (cloaking); " +
|
|
50
|
+
"only a check made on the same connection as the host, such as `intentrax mcp proxy`, sees what the host is sent.";
|
|
51
|
+
export const UNSIGNED_NOTE = "Unsigned v0.1 pin file: it records what you approved locally; it is not a signed statement by anyone.";
|
|
52
|
+
|
|
53
|
+
const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
|
|
54
|
+
const DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
|
|
55
|
+
|
|
56
|
+
export class PinFileError extends Error {
|
|
57
|
+
constructor(code, message) {
|
|
58
|
+
super(message);
|
|
59
|
+
this.name = "PinFileError";
|
|
60
|
+
this.code = code;
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function isPlainObject(value) {
|
|
65
|
+
if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
|
|
66
|
+
const proto = Object.getPrototypeOf(value);
|
|
67
|
+
return proto === Object.prototype || proto === null;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
function isoSeconds(date) {
|
|
71
|
+
return date.toISOString().replace(/\.\d{3}Z$/, "Z");
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
function plain(definition) {
|
|
75
|
+
// normalizeToolDefinition returns a null-prototype object; store a plain copy.
|
|
76
|
+
return JSON.parse(JSON.stringify(definition));
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
// ---------------------------------------------------------------------------
|
|
80
|
+
// Pin file
|
|
81
|
+
// ---------------------------------------------------------------------------
|
|
82
|
+
|
|
83
|
+
export function validatePinEntry(name, entry) {
|
|
84
|
+
const where = "pin entry " + JSON.stringify(name);
|
|
85
|
+
if (!NAME_RE.test(name)) throw new PinFileError("pins_invalid", where + " has an invalid name");
|
|
86
|
+
if (!isPlainObject(entry)) throw new PinFileError("pins_invalid", where + " is not an object");
|
|
87
|
+
if (entry.profile !== TOOL_MANIFEST_PROFILE) throw new PinFileError("pins_invalid", where + " has an unknown profile");
|
|
88
|
+
if (!isPlainObject(entry.server)) throw new PinFileError("pins_invalid", where + " has no server");
|
|
89
|
+
try {
|
|
90
|
+
parseServerSpec(serverSpecOf(entry));
|
|
91
|
+
} catch (error) {
|
|
92
|
+
throw new PinFileError("pins_invalid", where + " has an invalid server spec: " + error.message);
|
|
93
|
+
}
|
|
94
|
+
if (typeof entry.manifest_digest !== "string" || !DIGEST_RE.test(entry.manifest_digest)) throw new PinFileError("pins_invalid", where + " has no manifest_digest");
|
|
95
|
+
if (!Array.isArray(entry.tools)) throw new PinFileError("pins_invalid", where + " has no tools array");
|
|
96
|
+
const definitions = [];
|
|
97
|
+
for (const tool of entry.tools) {
|
|
98
|
+
if (!isPlainObject(tool) || typeof tool.name !== "string" || typeof tool.digest !== "string" || !isPlainObject(tool.definition)) {
|
|
99
|
+
throw new PinFileError("pins_invalid", where + " has a malformed tool");
|
|
100
|
+
}
|
|
101
|
+
let digest;
|
|
102
|
+
try {
|
|
103
|
+
if (tool.definition.name !== tool.name) throw new Error("name mismatch");
|
|
104
|
+
digest = toolDefinitionDigest(tool.definition);
|
|
105
|
+
} catch {
|
|
106
|
+
throw new PinFileError("pins_inconsistent", where + ": tool " + JSON.stringify(tool.name) + " has an unusable definition");
|
|
107
|
+
}
|
|
108
|
+
if (digest !== tool.digest) {
|
|
109
|
+
throw new PinFileError("pins_inconsistent", where + ": tool " + JSON.stringify(tool.name) + " definition does not match its digest (file edited?)");
|
|
110
|
+
}
|
|
111
|
+
definitions.push(tool.definition);
|
|
112
|
+
}
|
|
113
|
+
let manifest;
|
|
114
|
+
try {
|
|
115
|
+
manifest = toolManifestDigest(definitions);
|
|
116
|
+
} catch (error) {
|
|
117
|
+
throw new PinFileError("pins_inconsistent", where + ": " + error.message);
|
|
118
|
+
}
|
|
119
|
+
if (manifest.manifest_digest !== entry.manifest_digest) {
|
|
120
|
+
throw new PinFileError("pins_inconsistent", where + ": manifest_digest does not match its tools (file edited?)");
|
|
121
|
+
}
|
|
122
|
+
return definitions;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
export function loadPinFile(path) {
|
|
126
|
+
if (!existsSync(path)) throw new PinFileError("pins_missing", "pin file not found: " + path);
|
|
127
|
+
let doc;
|
|
128
|
+
try {
|
|
129
|
+
doc = JSON.parse(readFileSync(path, "utf8"));
|
|
130
|
+
} catch {
|
|
131
|
+
throw new PinFileError("pins_invalid", "pin file is not valid JSON: " + path);
|
|
132
|
+
}
|
|
133
|
+
if (!isPlainObject(doc) || doc.schema !== PIN_FILE_SCHEMA || !isPlainObject(doc.servers)) {
|
|
134
|
+
throw new PinFileError("pins_invalid", "pin file is not " + PIN_FILE_SCHEMA + ": " + path);
|
|
135
|
+
}
|
|
136
|
+
return doc;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
function serverSpecOf(entry) {
|
|
140
|
+
const server = entry.server;
|
|
141
|
+
if (server.transport === "streamable-http") {
|
|
142
|
+
return { transport: "streamable-http", url: server.url, ...(server.headers ? { headers: server.headers } : {}) };
|
|
143
|
+
}
|
|
144
|
+
return { transport: "stdio", command: server.command, ...(server.env ? { env: server.env } : {}), ...(server.cwd ? { cwd: server.cwd } : {}) };
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
function storedServer(spec, { serverInfo, registryName }) {
|
|
148
|
+
const server = {};
|
|
149
|
+
if (registryName) server.registry_name = registryName;
|
|
150
|
+
server.transport = spec.transport;
|
|
151
|
+
if (spec.transport === "streamable-http") {
|
|
152
|
+
server.url = spec.url;
|
|
153
|
+
if (spec.headers) server.headers = spec.headers;
|
|
154
|
+
} else {
|
|
155
|
+
server.command = spec.command;
|
|
156
|
+
if (spec.env) server.env = spec.env;
|
|
157
|
+
if (spec.cwd) server.cwd = spec.cwd;
|
|
158
|
+
}
|
|
159
|
+
if (isPlainObject(serverInfo)) {
|
|
160
|
+
const info = {};
|
|
161
|
+
if (typeof serverInfo.name === "string") info.name = serverInfo.name.slice(0, 128);
|
|
162
|
+
if (typeof serverInfo.version === "string") info.version = serverInfo.version.slice(0, 64);
|
|
163
|
+
server.server_info = info;
|
|
164
|
+
}
|
|
165
|
+
return server;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
function buildEntry({ server, definitions, protocolVersion, pinnedAt }) {
|
|
169
|
+
const manifest = toolManifestDigest(definitions);
|
|
170
|
+
const byName = new Map(definitions.map((definition) => [definition.name, plain(normalizeToolDefinition(definition))]));
|
|
171
|
+
return {
|
|
172
|
+
profile: TOOL_MANIFEST_PROFILE,
|
|
173
|
+
server,
|
|
174
|
+
protocol_version: protocolVersion,
|
|
175
|
+
manifest_digest: manifest.manifest_digest,
|
|
176
|
+
tools: manifest.tools.map((tool) => ({ name: tool.name, digest: tool.digest, definition: byName.get(tool.name) })),
|
|
177
|
+
pinned_at: pinnedAt,
|
|
178
|
+
pinned_by: "local",
|
|
179
|
+
};
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
function writePinFile(path, doc) {
|
|
183
|
+
const servers = {};
|
|
184
|
+
for (const key of Object.keys(doc.servers).sort()) servers[key] = doc.servers[key];
|
|
185
|
+
const out = { schema: PIN_FILE_SCHEMA, note: UNSIGNED_NOTE, servers };
|
|
186
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
187
|
+
const tmp = path + "." + randomBytes(4).toString("hex") + ".tmp";
|
|
188
|
+
writeFileSync(tmp, JSON.stringify(out, null, 2) + "\n", { encoding: "utf8", mode: 0o644 });
|
|
189
|
+
renameSync(tmp, path);
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
// ---------------------------------------------------------------------------
|
|
193
|
+
// Report formatting
|
|
194
|
+
// ---------------------------------------------------------------------------
|
|
195
|
+
|
|
196
|
+
function describeChange(change) {
|
|
197
|
+
const parts = [change.categories.join(", ")];
|
|
198
|
+
if (change.annotation_weakenings.length > 0) parts.push(change.annotation_weakenings.join(", "));
|
|
199
|
+
return change.name + " (" + parts.join("; ") + ")";
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
// One-line summary of a diff: "changed a (annotations; readOnlyHint became true); new b; removed c".
|
|
203
|
+
export function summarizeDiff(diff) {
|
|
204
|
+
const parts = [];
|
|
205
|
+
if (diff.changed.length > 0) parts.push("changed " + diff.changed.map(describeChange).join(", "));
|
|
206
|
+
if (diff.added.length > 0) parts.push("new " + diff.added.join(", "));
|
|
207
|
+
if (diff.removed.length > 0) parts.push("removed " + diff.removed.join(", "));
|
|
208
|
+
return parts.join("; ");
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
function diffDetailLines(diff) {
|
|
212
|
+
const lines = [];
|
|
213
|
+
for (const change of diff.changed) {
|
|
214
|
+
let line = " changed " + change.name + ": " + change.categories.join(", ") + " (fields: " + change.fields.join(", ") + ")";
|
|
215
|
+
if (change.annotation_weakenings.length > 0) line += "; looks safer now: " + change.annotation_weakenings.join(", ");
|
|
216
|
+
lines.push(line);
|
|
217
|
+
}
|
|
218
|
+
for (const name of diff.added) lines.push(" new " + name + " (not in the pin)");
|
|
219
|
+
for (const name of diff.removed) lines.push(" removed " + name);
|
|
220
|
+
return lines;
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
function driftedNames(diff) {
|
|
224
|
+
return [...diff.changed.map((change) => change.name), ...diff.added, ...diff.removed].sort();
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
function errorText(error) {
|
|
228
|
+
if (error instanceof McpClientError || error instanceof PinFileError) return error.message;
|
|
229
|
+
return "unexpected error (" + (error?.name ?? "Error") + ")";
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
// ---------------------------------------------------------------------------
|
|
233
|
+
// check
|
|
234
|
+
// ---------------------------------------------------------------------------
|
|
235
|
+
|
|
236
|
+
// check({ pins, name?, server?, cwd?, env?, timeoutMs?, listTools? })
|
|
237
|
+
export async function check(options = {}) {
|
|
238
|
+
const cwd = options.cwd ?? process.cwd();
|
|
239
|
+
const pinsPath = resolve(cwd, options.pins ?? DEFAULT_PINS_PATH);
|
|
240
|
+
const listTools = options.listTools ?? listServerTools;
|
|
241
|
+
const clientOptions = { env: options.env ?? process.env, timeoutMs: options.timeoutMs, log: options.log, allowInsecureHttp: options.allowInsecureHttp };
|
|
242
|
+
|
|
243
|
+
let doc;
|
|
244
|
+
try {
|
|
245
|
+
doc = loadPinFile(pinsPath);
|
|
246
|
+
} catch (error) {
|
|
247
|
+
return unchecked([{ name: options.name ?? "*", error: errorText(error) }], pinsPath);
|
|
248
|
+
}
|
|
249
|
+
let names = Object.keys(doc.servers).sort();
|
|
250
|
+
if (options.name !== undefined) {
|
|
251
|
+
if (!Object.hasOwn(doc.servers, options.name)) {
|
|
252
|
+
return unchecked([{ name: options.name, error: "no pin named " + JSON.stringify(options.name) + " in " + pinsPath }], pinsPath);
|
|
253
|
+
}
|
|
254
|
+
names = [options.name];
|
|
255
|
+
}
|
|
256
|
+
if (names.length === 0) return unchecked([{ name: "*", error: "the pin file has no servers" }], pinsPath);
|
|
257
|
+
if (options.server !== undefined && names.length !== 1) {
|
|
258
|
+
return usage("--server needs --name when the pin file has more than one server");
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
const servers = [];
|
|
262
|
+
for (const name of names) {
|
|
263
|
+
const entry = doc.servers[name];
|
|
264
|
+
const item = { name, result: "UNCHECKED" };
|
|
265
|
+
servers.push(item);
|
|
266
|
+
let pinnedDefinitions;
|
|
267
|
+
try {
|
|
268
|
+
pinnedDefinitions = validatePinEntry(name, entry);
|
|
269
|
+
} catch (error) {
|
|
270
|
+
item.error = errorText(error);
|
|
271
|
+
continue;
|
|
272
|
+
}
|
|
273
|
+
item.pinned_at = entry.pinned_at;
|
|
274
|
+
item.manifest_digest_pinned = entry.manifest_digest;
|
|
275
|
+
item.pinned_tool_count = pinnedDefinitions.length;
|
|
276
|
+
let spec;
|
|
277
|
+
try {
|
|
278
|
+
spec = parseServerSpec(options.server ?? serverSpecOf(entry));
|
|
279
|
+
} catch (error) {
|
|
280
|
+
item.error = errorText(error);
|
|
281
|
+
continue;
|
|
282
|
+
}
|
|
283
|
+
item.server = describeServer(spec);
|
|
284
|
+
let listed;
|
|
285
|
+
try {
|
|
286
|
+
listed = await listTools(spec, clientOptions);
|
|
287
|
+
} catch (error) {
|
|
288
|
+
item.error = "could not list tools: " + errorText(error);
|
|
289
|
+
continue;
|
|
290
|
+
}
|
|
291
|
+
let diff;
|
|
292
|
+
try {
|
|
293
|
+
diff = diffToolManifests(pinnedDefinitions, listed.tools);
|
|
294
|
+
} catch (error) {
|
|
295
|
+
item.error = "server tools cannot be hashed: " + clipText(error.message);
|
|
296
|
+
continue;
|
|
297
|
+
}
|
|
298
|
+
item.protocol_version = listed.protocolVersion;
|
|
299
|
+
item.manifest_digest_current = diff.manifest_digest_current;
|
|
300
|
+
item.current_tool_count = listed.tools.length;
|
|
301
|
+
item.pages = listed.pages;
|
|
302
|
+
item.added = diff.added;
|
|
303
|
+
item.removed = diff.removed;
|
|
304
|
+
item.changed = diff.changed;
|
|
305
|
+
item.result = diff.drift ? "CHANGED" : "MATCH";
|
|
306
|
+
}
|
|
307
|
+
return finishCheck(servers, pinsPath);
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
function clipText(text) {
|
|
311
|
+
const s = String(text);
|
|
312
|
+
return s.length > 200 ? s.slice(0, 200) + "…" : s;
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
function usage(message) {
|
|
316
|
+
return { exitCode: EXIT_USAGE, result: "USAGE", lines: ["USAGE " + message], report: { schema: CHECK_REPORT_SCHEMA, result: "USAGE", error: message } };
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
function unchecked(items, pinsPath) {
|
|
320
|
+
return finishCheck(items.map((item) => ({ ...item, result: "UNCHECKED" })), pinsPath);
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
function finishCheck(servers, pinsPath) {
|
|
324
|
+
const changed = servers.filter((item) => item.result === "CHANGED");
|
|
325
|
+
const failed = servers.filter((item) => item.result === "UNCHECKED");
|
|
326
|
+
const matched = servers.filter((item) => item.result === "MATCH");
|
|
327
|
+
// Drift outranks "could not check": both fail closed (non-zero), and the
|
|
328
|
+
// drift is the finding a person must act on.
|
|
329
|
+
const result = changed.length > 0 ? "CHANGED" : failed.length > 0 ? "UNCHECKED" : "MATCH";
|
|
330
|
+
const exitCode = result === "CHANGED" ? EXIT_DRIFT : result === "UNCHECKED" ? EXIT_UNCHECKED : EXIT_MATCH;
|
|
331
|
+
|
|
332
|
+
const lines = [];
|
|
333
|
+
if (changed.length > 0) lines.push("CHANGED " + changed.map((item) => item.name + ": " + summarizeDiff(item)).join(" | "));
|
|
334
|
+
if (failed.length > 0) lines.push("UNCHECKED " + failed.map((item) => item.name + ": " + item.error).join(" | "));
|
|
335
|
+
if (matched.length > 0) {
|
|
336
|
+
lines.push("MATCH " + matched.map((item) => item.name + ": " + item.current_tool_count + " tools match the pin from " + item.pinned_at).join(" | "));
|
|
337
|
+
}
|
|
338
|
+
for (const item of servers) {
|
|
339
|
+
if (item.result === "UNCHECKED" && item.manifest_digest_pinned === undefined) continue;
|
|
340
|
+
lines.push("server " + item.name + (item.server ? ": " + item.server : "") + (item.protocol_version ? " (MCP " + item.protocol_version + ")" : ""));
|
|
341
|
+
if (item.manifest_digest_pinned) lines.push(" pinned " + item.pinned_tool_count + " tools at " + item.pinned_at + ", " + item.manifest_digest_pinned);
|
|
342
|
+
if (item.manifest_digest_current) lines.push(" current " + item.current_tool_count + " tools, " + item.manifest_digest_current);
|
|
343
|
+
if (item.result === "CHANGED") {
|
|
344
|
+
lines.push(...diffDetailLines(item));
|
|
345
|
+
lines.push(" to accept after review: intentrax mcp pin --name " + item.name + " --accept " + driftedNames(item).join(","));
|
|
346
|
+
}
|
|
347
|
+
}
|
|
348
|
+
lines.push("note: " + CLOAKING_NOTE);
|
|
349
|
+
lines.push(LIMITATION);
|
|
350
|
+
return {
|
|
351
|
+
exitCode,
|
|
352
|
+
result,
|
|
353
|
+
lines,
|
|
354
|
+
report: { schema: CHECK_REPORT_SCHEMA, result, exit_code: exitCode, pins: pinsPath, servers, notes: [CLOAKING_NOTE], limitation: LIMITATION },
|
|
355
|
+
};
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
// ---------------------------------------------------------------------------
|
|
359
|
+
// pin
|
|
360
|
+
// ---------------------------------------------------------------------------
|
|
361
|
+
|
|
362
|
+
// pin({ server?, name?, out?, accept?, replace?, registryName?, cwd?, env?, now?, timeoutMs?, listTools? })
|
|
363
|
+
// - first pin of a name: lists every page and writes the entry;
|
|
364
|
+
// - same name, tools unchanged: no write (exit 0);
|
|
365
|
+
// - same name, tools changed: no write, exit 10, unless `accept` names the
|
|
366
|
+
// tools to re-pin on purpose (or `replace` re-pins everything);
|
|
367
|
+
// - accept: [names] re-pins only those tools (changed, new or removed);
|
|
368
|
+
// every other tool keeps its old pinned definition.
|
|
369
|
+
export async function pin(options = {}) {
|
|
370
|
+
const cwd = options.cwd ?? process.cwd();
|
|
371
|
+
const outPath = resolve(cwd, options.out ?? DEFAULT_PINS_PATH);
|
|
372
|
+
const listTools = options.listTools ?? listServerTools;
|
|
373
|
+
const now = options.now ?? (() => new Date());
|
|
374
|
+
const clientOptions = { env: options.env ?? process.env, timeoutMs: options.timeoutMs, log: options.log, allowInsecureHttp: options.allowInsecureHttp };
|
|
375
|
+
const accept = options.accept === undefined ? undefined : [...new Set(options.accept)].sort();
|
|
376
|
+
const fail = (exitCode, result, line, extra = {}) => ({
|
|
377
|
+
exitCode,
|
|
378
|
+
result,
|
|
379
|
+
lines: [line, LIMITATION],
|
|
380
|
+
report: { schema: PIN_REPORT_SCHEMA, result, exit_code: exitCode, pins: outPath, ...extra, limitation: LIMITATION },
|
|
381
|
+
written: null,
|
|
382
|
+
});
|
|
383
|
+
|
|
384
|
+
if (options.name !== undefined && !NAME_RE.test(options.name)) {
|
|
385
|
+
return fail(EXIT_USAGE, "USAGE", "USAGE --name must match " + NAME_RE.source);
|
|
386
|
+
}
|
|
387
|
+
if (accept !== undefined && (accept.length === 0 || accept.some((tool) => typeof tool !== "string" || tool === ""))) {
|
|
388
|
+
return fail(EXIT_USAGE, "USAGE", "USAGE --accept needs one or more tool names");
|
|
389
|
+
}
|
|
390
|
+
if (accept !== undefined && options.replace) return fail(EXIT_USAGE, "USAGE", "USAGE use --accept or --replace, not both");
|
|
391
|
+
|
|
392
|
+
let doc = { schema: PIN_FILE_SCHEMA, servers: {} };
|
|
393
|
+
if (existsSync(outPath)) {
|
|
394
|
+
try {
|
|
395
|
+
doc = loadPinFile(outPath);
|
|
396
|
+
} catch (error) {
|
|
397
|
+
return fail(EXIT_UNCHECKED, "UNPINNED", "UNPINNED " + errorText(error) + " (not overwritten)");
|
|
398
|
+
}
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
if (accept !== undefined && options.name === undefined) {
|
|
402
|
+
const names = Object.keys(doc.servers);
|
|
403
|
+
if (names.length !== 1) return fail(EXIT_USAGE, "USAGE", "USAGE --accept needs --name");
|
|
404
|
+
options = { ...options, name: names[0] };
|
|
405
|
+
}
|
|
406
|
+
let existing = options.name !== undefined && Object.hasOwn(doc.servers, options.name) ? doc.servers[options.name] : undefined;
|
|
407
|
+
let pinnedDefinitions;
|
|
408
|
+
if (existing) {
|
|
409
|
+
try {
|
|
410
|
+
pinnedDefinitions = validatePinEntry(options.name, existing);
|
|
411
|
+
} catch (error) {
|
|
412
|
+
if (!options.replace) return fail(EXIT_UNCHECKED, "UNPINNED", "UNPINNED " + errorText(error) + " (use --replace to pin afresh)");
|
|
413
|
+
existing = undefined;
|
|
414
|
+
}
|
|
415
|
+
}
|
|
416
|
+
if (accept !== undefined && !existing) {
|
|
417
|
+
return fail(EXIT_USAGE, "USAGE", "USAGE nothing is pinned under " + JSON.stringify(options.name ?? "") + " yet; pin it first without --accept");
|
|
418
|
+
}
|
|
419
|
+
|
|
420
|
+
let spec;
|
|
421
|
+
try {
|
|
422
|
+
spec = parseServerSpec(options.server ?? (existing ? serverSpecOf(existing) : undefined));
|
|
423
|
+
} catch (error) {
|
|
424
|
+
return fail(EXIT_USAGE, "USAGE", "USAGE " + (options.server === undefined && !existing ? "--server is required" : errorText(error)));
|
|
425
|
+
}
|
|
426
|
+
const { problems, warnings } = findStoredSecrets(spec);
|
|
427
|
+
if (problems.length > 0) {
|
|
428
|
+
return fail(EXIT_USAGE, "USAGE", "USAGE the pin file would store a credential (" + problems.join(", ") + "); use ${ENV_VAR} placeholders instead");
|
|
429
|
+
}
|
|
430
|
+
|
|
431
|
+
let listed;
|
|
432
|
+
try {
|
|
433
|
+
listed = await listTools(spec, clientOptions);
|
|
434
|
+
} catch (error) {
|
|
435
|
+
return fail(EXIT_UNCHECKED, "UNPINNED", "UNPINNED " + (options.name ?? describeServer(spec)) + ": could not list tools: " + errorText(error));
|
|
436
|
+
}
|
|
437
|
+
let currentManifest;
|
|
438
|
+
try {
|
|
439
|
+
currentManifest = toolManifestDigest(listed.tools);
|
|
440
|
+
} catch (error) {
|
|
441
|
+
return fail(EXIT_UNCHECKED, "UNPINNED", "UNPINNED server tools cannot be hashed: " + clipText(error.message));
|
|
442
|
+
}
|
|
443
|
+
|
|
444
|
+
const name = options.name ?? (typeof listed.serverInfo?.name === "string" ? listed.serverInfo.name : undefined);
|
|
445
|
+
if (name === undefined || !NAME_RE.test(name)) {
|
|
446
|
+
return fail(EXIT_USAGE, "USAGE", "USAGE the server did not give a usable name; pass --name");
|
|
447
|
+
}
|
|
448
|
+
if (options.name === undefined && Object.hasOwn(doc.servers, name) && !options.replace) {
|
|
449
|
+
existing = doc.servers[name];
|
|
450
|
+
try {
|
|
451
|
+
pinnedDefinitions = validatePinEntry(name, existing);
|
|
452
|
+
} catch (error) {
|
|
453
|
+
return fail(EXIT_UNCHECKED, "UNPINNED", "UNPINNED " + errorText(error) + " (use --replace to pin afresh)");
|
|
454
|
+
}
|
|
455
|
+
}
|
|
456
|
+
|
|
457
|
+
const pinnedAt = isoSeconds(now());
|
|
458
|
+
const warningLines = warnings.map((warning) => "warning: " + warning);
|
|
459
|
+
const base = { name, server: describeServer(spec), protocol_version: listed.protocolVersion, pages: listed.pages };
|
|
460
|
+
|
|
461
|
+
if (!existing || options.replace) {
|
|
462
|
+
const entry = buildEntry({
|
|
463
|
+
server: storedServer(spec, { serverInfo: listed.serverInfo, registryName: options.registryName }),
|
|
464
|
+
definitions: listed.tools,
|
|
465
|
+
protocolVersion: listed.protocolVersion,
|
|
466
|
+
pinnedAt,
|
|
467
|
+
});
|
|
468
|
+
doc.servers[name] = entry;
|
|
469
|
+
writePinFile(outPath, doc);
|
|
470
|
+
return {
|
|
471
|
+
exitCode: EXIT_MATCH,
|
|
472
|
+
result: "PINNED",
|
|
473
|
+
lines: [
|
|
474
|
+
"PINNED " + name + ": " + entry.tools.length + " tools (" + listed.pages + " page" + (listed.pages === 1 ? "" : "s") + "), " + entry.manifest_digest + " -> " + outPath,
|
|
475
|
+
...warningLines,
|
|
476
|
+
"note: " + UNSIGNED_NOTE,
|
|
477
|
+
LIMITATION,
|
|
478
|
+
],
|
|
479
|
+
report: { schema: PIN_REPORT_SCHEMA, result: "PINNED", exit_code: EXIT_MATCH, pins: outPath, ...base, manifest_digest: entry.manifest_digest, tool_count: entry.tools.length, limitation: LIMITATION },
|
|
480
|
+
written: outPath,
|
|
481
|
+
};
|
|
482
|
+
}
|
|
483
|
+
|
|
484
|
+
const diff = diffToolManifests(pinnedDefinitions, listed.tools);
|
|
485
|
+
if (accept === undefined) {
|
|
486
|
+
if (!diff.drift) {
|
|
487
|
+
return {
|
|
488
|
+
exitCode: EXIT_MATCH,
|
|
489
|
+
result: "UNCHANGED",
|
|
490
|
+
lines: ["UNCHANGED " + name + ": " + currentManifest.tool_count + " tools already match the pin from " + existing.pinned_at, ...warningLines, LIMITATION],
|
|
491
|
+
report: { schema: PIN_REPORT_SCHEMA, result: "UNCHANGED", exit_code: EXIT_MATCH, pins: outPath, ...base, manifest_digest: existing.manifest_digest, limitation: LIMITATION },
|
|
492
|
+
written: null,
|
|
493
|
+
};
|
|
494
|
+
}
|
|
495
|
+
return {
|
|
496
|
+
exitCode: EXIT_DRIFT,
|
|
497
|
+
result: "CHANGED",
|
|
498
|
+
lines: [
|
|
499
|
+
"CHANGED " + name + ": " + summarizeDiff(diff),
|
|
500
|
+
...diffDetailLines(diff),
|
|
501
|
+
"not re-pinned: review the changes, then run intentrax mcp pin --name " + name + " --accept " + driftedNames(diff).join(","),
|
|
502
|
+
...warningLines,
|
|
503
|
+
LIMITATION,
|
|
504
|
+
],
|
|
505
|
+
report: { schema: PIN_REPORT_SCHEMA, result: "CHANGED", exit_code: EXIT_DRIFT, pins: outPath, ...base, added: diff.added, removed: diff.removed, changed: diff.changed, limitation: LIMITATION },
|
|
506
|
+
written: null,
|
|
507
|
+
};
|
|
508
|
+
}
|
|
509
|
+
|
|
510
|
+
const pinnedByName = new Map(pinnedDefinitions.map((definition) => [definition.name, definition]));
|
|
511
|
+
const currentByName = new Map(listed.tools.map((tool) => [tool.name, tool]));
|
|
512
|
+
const unknown = accept.filter((tool) => !pinnedByName.has(tool) && !currentByName.has(tool));
|
|
513
|
+
if (unknown.length > 0) {
|
|
514
|
+
return fail(EXIT_USAGE, "USAGE", "USAGE not pinned and not offered by the server: " + unknown.join(", "));
|
|
515
|
+
}
|
|
516
|
+
const drifted = new Set(driftedNames(diff));
|
|
517
|
+
const accepted = accept.filter((tool) => drifted.has(tool));
|
|
518
|
+
const alreadyMatching = accept.filter((tool) => !drifted.has(tool));
|
|
519
|
+
const next = new Map(pinnedByName);
|
|
520
|
+
for (const tool of accepted) {
|
|
521
|
+
if (currentByName.has(tool)) next.set(tool, currentByName.get(tool));
|
|
522
|
+
else next.delete(tool);
|
|
523
|
+
}
|
|
524
|
+
const definitions = [...next.values()];
|
|
525
|
+
const entry = buildEntry({
|
|
526
|
+
server: options.server !== undefined ? storedServer(spec, { serverInfo: listed.serverInfo, registryName: options.registryName ?? existing.server.registry_name }) : existing.server,
|
|
527
|
+
definitions,
|
|
528
|
+
protocolVersion: listed.protocolVersion,
|
|
529
|
+
pinnedAt,
|
|
530
|
+
});
|
|
531
|
+
if (accepted.length > 0) {
|
|
532
|
+
doc.servers[name] = entry;
|
|
533
|
+
writePinFile(outPath, doc);
|
|
534
|
+
}
|
|
535
|
+
const remaining = diffToolManifests(definitions, listed.tools);
|
|
536
|
+
const lines = [
|
|
537
|
+
(accepted.length > 0 ? "REPINNED " + name + ": accepted " + accepted.join(", ") : "UNCHANGED " + name + ": nothing to accept") +
|
|
538
|
+
(alreadyMatching.length > 0 ? " (already matching: " + alreadyMatching.join(", ") + ")" : "") +
|
|
539
|
+
"; " + entry.tools.length + " tools, " + entry.manifest_digest,
|
|
540
|
+
];
|
|
541
|
+
if (remaining.drift) {
|
|
542
|
+
lines.push("CHANGED " + name + " (not accepted): " + summarizeDiff(remaining));
|
|
543
|
+
lines.push(...diffDetailLines(remaining));
|
|
544
|
+
}
|
|
545
|
+
lines.push(...warningLines, LIMITATION);
|
|
546
|
+
const exitCode = remaining.drift ? EXIT_DRIFT : EXIT_MATCH;
|
|
547
|
+
return {
|
|
548
|
+
exitCode,
|
|
549
|
+
result: accepted.length > 0 ? "REPINNED" : "UNCHANGED",
|
|
550
|
+
lines,
|
|
551
|
+
report: {
|
|
552
|
+
schema: PIN_REPORT_SCHEMA,
|
|
553
|
+
result: accepted.length > 0 ? "REPINNED" : "UNCHANGED",
|
|
554
|
+
exit_code: exitCode,
|
|
555
|
+
pins: outPath,
|
|
556
|
+
...base,
|
|
557
|
+
accepted,
|
|
558
|
+
manifest_digest: entry.manifest_digest,
|
|
559
|
+
remaining: { added: remaining.added, removed: remaining.removed, changed: remaining.changed },
|
|
560
|
+
limitation: LIMITATION,
|
|
561
|
+
},
|
|
562
|
+
written: accepted.length > 0 ? outPath : null,
|
|
563
|
+
};
|
|
564
|
+
}
|
|
565
|
+
|
|
566
|
+
// For the proxy: the pinned definitions for one server, validated.
|
|
567
|
+
export function loadPinnedServer(pinsPath, name) {
|
|
568
|
+
const doc = loadPinFile(pinsPath);
|
|
569
|
+
const names = Object.keys(doc.servers).sort();
|
|
570
|
+
const chosen = name ?? (names.length === 1 ? names[0] : undefined);
|
|
571
|
+
if (chosen === undefined) throw new PinFileError("pins_ambiguous", "the pin file has " + names.length + " servers; pass --name");
|
|
572
|
+
if (!Object.hasOwn(doc.servers, chosen)) throw new PinFileError("pins_missing", "no pin named " + JSON.stringify(chosen));
|
|
573
|
+
const definitions = validatePinEntry(chosen, doc.servers[chosen]);
|
|
574
|
+
return { name: chosen, entry: doc.servers[chosen], definitions, spec: serverSpecOf(doc.servers[chosen]) };
|
|
575
|
+
}
|