@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,178 @@
|
|
|
1
|
+
// MCP receipt references (Workstream A). Ported unchanged in behaviour from
|
|
2
|
+
// examples/mcp-trust-receipts/src/receipt-meta.mjs. The server side stays
|
|
3
|
+
// behind engine work (assessment §5.A, owner item §9.3).
|
|
4
|
+
//
|
|
5
|
+
// A server that already obtained an Intentrax proof for a tool call can hand
|
|
6
|
+
// the client a POINTER to it, in the result's `_meta`, without touching the
|
|
7
|
+
// tool's own output:
|
|
8
|
+
//
|
|
9
|
+
// result._meta["com.intentrax/receipt"] = {
|
|
10
|
+
// schema, proof_id, verify_url, record_kind, tool_name,
|
|
11
|
+
// arguments_digest, tool_manifest_digest?, limitations[]
|
|
12
|
+
// }
|
|
13
|
+
//
|
|
14
|
+
// Design rules (see docs/architecture/INTENTRAX_MCP_TRUST_VISIBILITY_ASSESSMENT.md §5.A):
|
|
15
|
+
// - `content` and `structuredContent` are never modified, so structured
|
|
16
|
+
// output stays valid against the tool's outputSchema.
|
|
17
|
+
// - No text footer. Text appended to tool output is model-visible and
|
|
18
|
+
// indistinguishable from prompt injection; it is deliberately not offered.
|
|
19
|
+
// - An optional `resource_link` content block (opt-in) points at the public
|
|
20
|
+
// verify page with neutral, non-imperative wording.
|
|
21
|
+
// - The reference is UNAUTHENTICATED. Anyone can write any `_meta`. It is a
|
|
22
|
+
// claim to check, never evidence: a client must fetch/verify the proof and
|
|
23
|
+
// compare the proof's own fields with the call it actually made.
|
|
24
|
+
// - `record_kind` is fixed to "decision_record": production proofs record an
|
|
25
|
+
// admission/policy decision. They do not attest execution or its effect.
|
|
26
|
+
//
|
|
27
|
+
// Pure: no I/O, no network, no clock.
|
|
28
|
+
|
|
29
|
+
import { domainDigest } from "./canonical.mjs";
|
|
30
|
+
|
|
31
|
+
export const RECEIPT_META_KEY = "com.intentrax/receipt";
|
|
32
|
+
export const RECEIPT_REF_SCHEMA = "intentrax.mcp.receipt_ref/0.1";
|
|
33
|
+
export const ARGUMENTS_DIGEST_DOMAIN = "INTENTRAX_MCP_TOOL_ARGUMENTS_V0_1";
|
|
34
|
+
export const DEFAULT_VERIFY_HOSTS = Object.freeze(["verify.intentrax.com"]);
|
|
35
|
+
|
|
36
|
+
// Fixed limitation strings. Kept short, factual and non-imperative because a
|
|
37
|
+
// host may show `_meta` (or the resource link) to the model.
|
|
38
|
+
export const RECEIPT_LIMITATIONS = Object.freeze([
|
|
39
|
+
"Decision record: shows what was submitted for admission and the recorded decision.",
|
|
40
|
+
"Does not show that the tool ran, what it returned, or what changed downstream.",
|
|
41
|
+
"This reference is unauthenticated until the proof is verified against pinned keys.",
|
|
42
|
+
]);
|
|
43
|
+
|
|
44
|
+
const PROOF_ID_RE = /^[A-Za-z0-9_.-]{1,128}$/;
|
|
45
|
+
const DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
|
|
46
|
+
|
|
47
|
+
function isPlainObject(value) {
|
|
48
|
+
if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
|
|
49
|
+
const proto = Object.getPrototypeOf(value);
|
|
50
|
+
return proto === Object.prototype || proto === null;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
function isSafeProofId(value) {
|
|
54
|
+
return typeof value === "string" && PROOF_ID_RE.test(value) && !value.includes("..");
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
function checkVerifyUrl(value, allowedHosts) {
|
|
58
|
+
let url;
|
|
59
|
+
try {
|
|
60
|
+
url = new URL(value);
|
|
61
|
+
} catch {
|
|
62
|
+
return null;
|
|
63
|
+
}
|
|
64
|
+
if (url.protocol !== "https:" || url.username !== "" || url.password !== "" || url.port !== "") return null;
|
|
65
|
+
if (!allowedHosts.includes(url.hostname)) return null;
|
|
66
|
+
return url.toString();
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
// argumentsDigest — digest of the arguments object the SERVER received. The
|
|
70
|
+
// client computes the same value over the arguments it SENT and compares.
|
|
71
|
+
// NOTE: this is this prototype's own rule. The engine's
|
|
72
|
+
// MCPToolCallEnvelope.arguments_hash has no published rule: it is supplied
|
|
73
|
+
// by the caller and only checked to be 64-hex. Binding the two needs the
|
|
74
|
+
// engine to publish one rule as a cross-language vector (owner approval item).
|
|
75
|
+
export function argumentsDigest(args) {
|
|
76
|
+
if (!isPlainObject(args)) {
|
|
77
|
+
throw new Error("receipt: tool arguments must be an object");
|
|
78
|
+
}
|
|
79
|
+
return domainDigest(ARGUMENTS_DIGEST_DOMAIN, args);
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
export function buildReceiptRef({ proofId, verifyUrl, toolName, args, toolManifestDigest, allowedHosts = DEFAULT_VERIFY_HOSTS } = {}) {
|
|
83
|
+
if (!isSafeProofId(proofId)) throw new Error("receipt: unsafe proof id");
|
|
84
|
+
const url = checkVerifyUrl(verifyUrl, allowedHosts);
|
|
85
|
+
if (url === null) throw new Error("receipt: verify_url must be https on an allowed host");
|
|
86
|
+
if (typeof toolName !== "string" || toolName.length === 0 || toolName.length > 128) {
|
|
87
|
+
throw new Error("receipt: tool name is required");
|
|
88
|
+
}
|
|
89
|
+
const ref = {
|
|
90
|
+
schema: RECEIPT_REF_SCHEMA,
|
|
91
|
+
proof_id: proofId,
|
|
92
|
+
verify_url: url,
|
|
93
|
+
record_kind: "decision_record",
|
|
94
|
+
tool_name: toolName,
|
|
95
|
+
arguments_digest: argumentsDigest(args),
|
|
96
|
+
limitations: [...RECEIPT_LIMITATIONS],
|
|
97
|
+
};
|
|
98
|
+
if (toolManifestDigest !== undefined) {
|
|
99
|
+
if (typeof toolManifestDigest !== "string" || !DIGEST_RE.test(toolManifestDigest)) {
|
|
100
|
+
throw new Error("receipt: tool_manifest_digest must be sha256:<64 hex>");
|
|
101
|
+
}
|
|
102
|
+
ref.tool_manifest_digest = toolManifestDigest;
|
|
103
|
+
}
|
|
104
|
+
return ref;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
// attachReceiptMeta(result, ref, { resourceLink }) -> a NEW CallToolResult.
|
|
108
|
+
// Never mutates `result`; never changes `content` entries, `structuredContent`
|
|
109
|
+
// or `isError`; refuses to overwrite an existing receipt key.
|
|
110
|
+
export function attachReceiptMeta(result, ref, { resourceLink = false } = {}) {
|
|
111
|
+
if (!isPlainObject(result) || !Array.isArray(result.content)) {
|
|
112
|
+
throw new Error("receipt: result must be a CallToolResult with a content array");
|
|
113
|
+
}
|
|
114
|
+
if (!isPlainObject(ref) || ref.schema !== RECEIPT_REF_SCHEMA) {
|
|
115
|
+
throw new Error("receipt: ref must come from buildReceiptRef");
|
|
116
|
+
}
|
|
117
|
+
const existingMeta = result._meta === undefined ? {} : result._meta;
|
|
118
|
+
if (!isPlainObject(existingMeta)) {
|
|
119
|
+
throw new Error("receipt: existing _meta must be an object");
|
|
120
|
+
}
|
|
121
|
+
if (Object.prototype.hasOwnProperty.call(existingMeta, RECEIPT_META_KEY)) {
|
|
122
|
+
throw new Error("receipt: result already carries " + RECEIPT_META_KEY);
|
|
123
|
+
}
|
|
124
|
+
const content = [...result.content];
|
|
125
|
+
if (resourceLink) {
|
|
126
|
+
content.push({
|
|
127
|
+
type: "resource_link",
|
|
128
|
+
uri: ref.verify_url,
|
|
129
|
+
name: "intentrax-decision-record-" + ref.proof_id,
|
|
130
|
+
title: "Intentrax decision record",
|
|
131
|
+
description: "Signed record of the admission decision for this call. It does not show the call's outcome.",
|
|
132
|
+
mimeType: "text/html",
|
|
133
|
+
});
|
|
134
|
+
}
|
|
135
|
+
return {
|
|
136
|
+
...result,
|
|
137
|
+
content,
|
|
138
|
+
_meta: { ...existingMeta, [RECEIPT_META_KEY]: structuredClone(ref) },
|
|
139
|
+
};
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
// readReceiptMeta(result, { allowedHosts }) — the CLIENT side. Returns
|
|
143
|
+
// { status: "ABSENT" } | { status: "MALFORMED", reasons[] } |
|
|
144
|
+
// { status: "UNVERIFIED_REFERENCE", ref }. It never returns anything that
|
|
145
|
+
// reads as verified: verification is a separate step against the proof.
|
|
146
|
+
export function readReceiptMeta(result, { allowedHosts = DEFAULT_VERIFY_HOSTS } = {}) {
|
|
147
|
+
const meta = isPlainObject(result) ? result._meta : undefined;
|
|
148
|
+
if (!isPlainObject(meta) || !Object.prototype.hasOwnProperty.call(meta, RECEIPT_META_KEY)) {
|
|
149
|
+
return { status: "ABSENT" };
|
|
150
|
+
}
|
|
151
|
+
const ref = meta[RECEIPT_META_KEY];
|
|
152
|
+
const reasons = [];
|
|
153
|
+
if (!isPlainObject(ref)) {
|
|
154
|
+
return { status: "MALFORMED", reasons: ["not_an_object"] };
|
|
155
|
+
}
|
|
156
|
+
if (ref.schema !== RECEIPT_REF_SCHEMA) reasons.push("schema");
|
|
157
|
+
if (!isSafeProofId(ref.proof_id)) reasons.push("proof_id");
|
|
158
|
+
if (typeof ref.verify_url !== "string" || checkVerifyUrl(ref.verify_url, allowedHosts) === null) reasons.push("verify_url");
|
|
159
|
+
if (ref.record_kind !== "decision_record") reasons.push("record_kind");
|
|
160
|
+
if (typeof ref.tool_name !== "string" || ref.tool_name.length === 0) reasons.push("tool_name");
|
|
161
|
+
if (typeof ref.arguments_digest !== "string" || !DIGEST_RE.test(ref.arguments_digest)) reasons.push("arguments_digest");
|
|
162
|
+
if (ref.tool_manifest_digest !== undefined && (typeof ref.tool_manifest_digest !== "string" || !DIGEST_RE.test(ref.tool_manifest_digest))) {
|
|
163
|
+
reasons.push("tool_manifest_digest");
|
|
164
|
+
}
|
|
165
|
+
if (reasons.length > 0) return { status: "MALFORMED", reasons };
|
|
166
|
+
return { status: "UNVERIFIED_REFERENCE", ref: structuredClone(ref) };
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
// matchReceiptToCall — the cheap local check a client can do BEFORE fetching
|
|
170
|
+
// the proof: does the reference even claim to be about the call it made?
|
|
171
|
+
// A match proves nothing on its own (the server wrote both sides); a mismatch
|
|
172
|
+
// is a definite red flag.
|
|
173
|
+
export function matchReceiptToCall(ref, { toolName, args }) {
|
|
174
|
+
const mismatches = [];
|
|
175
|
+
if (ref.tool_name !== toolName) mismatches.push("tool_name");
|
|
176
|
+
if (ref.arguments_digest !== argumentsDigest(args)) mismatches.push("arguments_digest");
|
|
177
|
+
return { consistent: mismatches.length === 0, mismatches };
|
|
178
|
+
}
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
// Types for tool-manifest.mjs: MCP tool-manifest digests and drift diffs.
|
|
2
|
+
// A manifest digest shows the tools/list definitions matched a pin. It does
|
|
3
|
+
// not show that the server's code or behaviour is unchanged.
|
|
4
|
+
|
|
5
|
+
import type { JsonValue } from "./canonical.js";
|
|
6
|
+
|
|
7
|
+
export const TOOL_MANIFEST_PROFILE: "intentrax.mcp.tool_manifest/0.1";
|
|
8
|
+
export const TOOL_DIGEST_DOMAIN: "INTENTRAX_MCP_TOOL_DEFINITION_V0_1";
|
|
9
|
+
export const TOOL_MANIFEST_DIGEST_DOMAIN: "INTENTRAX_MCP_TOOL_MANIFEST_V0_1";
|
|
10
|
+
export const EXCLUDED_TOOL_FIELDS: readonly ["_meta"];
|
|
11
|
+
|
|
12
|
+
export type Digest = `sha256:${string}`;
|
|
13
|
+
|
|
14
|
+
/** An MCP Tool definition as received from tools/list (any extra fields are hashed too). */
|
|
15
|
+
export interface McpToolDefinition {
|
|
16
|
+
name: string;
|
|
17
|
+
title?: string;
|
|
18
|
+
description?: string;
|
|
19
|
+
inputSchema?: { [key: string]: JsonValue };
|
|
20
|
+
outputSchema?: { [key: string]: JsonValue };
|
|
21
|
+
annotations?: {
|
|
22
|
+
title?: string;
|
|
23
|
+
readOnlyHint?: boolean;
|
|
24
|
+
destructiveHint?: boolean;
|
|
25
|
+
idempotentHint?: boolean;
|
|
26
|
+
openWorldHint?: boolean;
|
|
27
|
+
[key: string]: JsonValue | undefined;
|
|
28
|
+
};
|
|
29
|
+
_meta?: { [key: string]: JsonValue };
|
|
30
|
+
[key: string]: JsonValue | undefined;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
export interface ManifestDigest {
|
|
34
|
+
profile: typeof TOOL_MANIFEST_PROFILE;
|
|
35
|
+
excluded_fields: string[];
|
|
36
|
+
tool_count: number;
|
|
37
|
+
tools: Array<{ name: string; digest: Digest }>;
|
|
38
|
+
manifest_digest: Digest;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export type ChangeCategory =
|
|
42
|
+
| "identity"
|
|
43
|
+
| "model_visible_text"
|
|
44
|
+
| "input_schema"
|
|
45
|
+
| "output_schema"
|
|
46
|
+
| "annotations"
|
|
47
|
+
| "presentation"
|
|
48
|
+
| "execution"
|
|
49
|
+
| "other";
|
|
50
|
+
|
|
51
|
+
export interface ToolChange {
|
|
52
|
+
name: string;
|
|
53
|
+
fields: string[];
|
|
54
|
+
categories: ChangeCategory[];
|
|
55
|
+
/** e.g. "readOnlyHint became true": the tool now looks safer to a host's permission UI. */
|
|
56
|
+
annotation_weakenings: string[];
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
export interface ManifestDiff {
|
|
60
|
+
profile: typeof TOOL_MANIFEST_PROFILE;
|
|
61
|
+
drift: boolean;
|
|
62
|
+
manifest_digest_pinned: Digest;
|
|
63
|
+
manifest_digest_current: Digest;
|
|
64
|
+
added: string[];
|
|
65
|
+
removed: string[];
|
|
66
|
+
changed: ToolChange[];
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** The exact object hashed for one tool: every field except `_meta`. Throws on non-canonical input. */
|
|
70
|
+
export function normalizeToolDefinition(tool: McpToolDefinition): { [key: string]: JsonValue };
|
|
71
|
+
export function toolDefinitionDigest(tool: McpToolDefinition): Digest;
|
|
72
|
+
/** `tools` must be the COMPLETE list across every tools/list page. Duplicate names throw. */
|
|
73
|
+
export function toolManifestDigest(tools: McpToolDefinition[]): ManifestDigest;
|
|
74
|
+
export function diffToolManifests(pinnedTools: McpToolDefinition[], currentTools: McpToolDefinition[]): ManifestDiff;
|
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
// Tool-manifest pinning for MCP servers (R1b). Ported unchanged in behaviour
|
|
2
|
+
// from examples/mcp-trust-receipts/src/tool-manifest.mjs.
|
|
3
|
+
//
|
|
4
|
+
// WHAT A MANIFEST DIGEST SHOWS: the tool definitions a client received from
|
|
5
|
+
// `tools/list` at one moment were byte-for-byte (after canonicalization) the
|
|
6
|
+
// ones that were pinned. Nothing more.
|
|
7
|
+
//
|
|
8
|
+
// WHAT IT DOES NOT SHOW: that the server's code, its upstream APIs, or what a
|
|
9
|
+
// tool actually does at call time are unchanged. A server can keep an
|
|
10
|
+
// identical manifest and change its behaviour. A manifest digest detects
|
|
11
|
+
// "rug-pull" edits to descriptions, schemas and annotations — the text and
|
|
12
|
+
// hints the model and the host's permission UI act on — and nothing else.
|
|
13
|
+
//
|
|
14
|
+
// This module is pure: no I/O, no network, no clock. It signs nothing and
|
|
15
|
+
// asserts no verdict.
|
|
16
|
+
|
|
17
|
+
import { canonicalJson, domainDigest } from "./canonical.mjs";
|
|
18
|
+
|
|
19
|
+
export const TOOL_MANIFEST_PROFILE = "intentrax.mcp.tool_manifest/0.1";
|
|
20
|
+
export const TOOL_DIGEST_DOMAIN = "INTENTRAX_MCP_TOOL_DEFINITION_V0_1";
|
|
21
|
+
export const TOOL_MANIFEST_DIGEST_DOMAIN = "INTENTRAX_MCP_TOOL_MANIFEST_V0_1";
|
|
22
|
+
|
|
23
|
+
// `_meta` is excluded: the MCP spec reserves it for implementation metadata
|
|
24
|
+
// that servers may legitimately vary (trace ids, cache hints). Every other
|
|
25
|
+
// field, known or unknown, is included, so a field added by a future spec
|
|
26
|
+
// revision is covered by default instead of silently ignored.
|
|
27
|
+
export const EXCLUDED_TOOL_FIELDS = Object.freeze(["_meta"]);
|
|
28
|
+
|
|
29
|
+
// Field -> change category, used only to explain a diff. Unknown fields fall
|
|
30
|
+
// into "other".
|
|
31
|
+
const FIELD_CATEGORY = Object.freeze({
|
|
32
|
+
name: "identity",
|
|
33
|
+
title: "model_visible_text",
|
|
34
|
+
description: "model_visible_text",
|
|
35
|
+
inputSchema: "input_schema",
|
|
36
|
+
outputSchema: "output_schema",
|
|
37
|
+
annotations: "annotations",
|
|
38
|
+
icons: "presentation",
|
|
39
|
+
execution: "execution",
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
const TOOL_NAME_MAX = 128;
|
|
43
|
+
|
|
44
|
+
function isPlainObject(value) {
|
|
45
|
+
if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
|
|
46
|
+
const proto = Object.getPrototypeOf(value);
|
|
47
|
+
return proto === Object.prototype || proto === null;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
// normalizeToolDefinition -> the exact object that is hashed for one tool.
|
|
51
|
+
export function normalizeToolDefinition(tool) {
|
|
52
|
+
if (!isPlainObject(tool)) {
|
|
53
|
+
throw new Error("tool_manifest: tool definition must be an object");
|
|
54
|
+
}
|
|
55
|
+
if (typeof tool.name !== "string" || tool.name.length === 0 || tool.name.length > TOOL_NAME_MAX) {
|
|
56
|
+
throw new Error("tool_manifest: tool name must be a non-empty string of at most " + TOOL_NAME_MAX + " characters");
|
|
57
|
+
}
|
|
58
|
+
// Null prototype: an own "__proto__" member (possible in JSON.parse output)
|
|
59
|
+
// must be stored as data and hashed, not routed to the prototype setter.
|
|
60
|
+
const normalized = Object.create(null);
|
|
61
|
+
for (const key of Object.keys(tool)) {
|
|
62
|
+
if (EXCLUDED_TOOL_FIELDS.includes(key)) continue;
|
|
63
|
+
if (tool[key] === undefined) continue;
|
|
64
|
+
normalized[key] = tool[key];
|
|
65
|
+
}
|
|
66
|
+
// Throws on anything non-canonical (NaN, functions, class instances).
|
|
67
|
+
canonicalJson(normalized);
|
|
68
|
+
return normalized;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
export function toolDefinitionDigest(tool) {
|
|
72
|
+
return domainDigest(TOOL_DIGEST_DOMAIN, normalizeToolDefinition(tool));
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
// toolManifestDigest(tools) — `tools` is the COMPLETE list across every
|
|
76
|
+
// `tools/list` page (follow `nextCursor` before calling this). Order does not
|
|
77
|
+
// matter; duplicate names are an error because a client cannot tell which
|
|
78
|
+
// definition the model will be shown.
|
|
79
|
+
export function toolManifestDigest(tools) {
|
|
80
|
+
if (!Array.isArray(tools)) {
|
|
81
|
+
throw new Error("tool_manifest: tools must be an array");
|
|
82
|
+
}
|
|
83
|
+
const entries = tools.map((tool) => ({ name: normalizeToolDefinition(tool).name, digest: toolDefinitionDigest(tool) }));
|
|
84
|
+
const seen = new Set();
|
|
85
|
+
for (const entry of entries) {
|
|
86
|
+
if (seen.has(entry.name)) {
|
|
87
|
+
throw new Error("tool_manifest: duplicate tool name " + JSON.stringify(entry.name));
|
|
88
|
+
}
|
|
89
|
+
seen.add(entry.name);
|
|
90
|
+
}
|
|
91
|
+
entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
|
|
92
|
+
return {
|
|
93
|
+
profile: TOOL_MANIFEST_PROFILE,
|
|
94
|
+
excluded_fields: [...EXCLUDED_TOOL_FIELDS],
|
|
95
|
+
tool_count: entries.length,
|
|
96
|
+
tools: entries,
|
|
97
|
+
manifest_digest: domainDigest(TOOL_MANIFEST_DIGEST_DOMAIN, { profile: TOOL_MANIFEST_PROFILE, tools: entries }),
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
// A change that makes a tool look safer to the host's permission UI than it
|
|
102
|
+
// was when pinned. Annotations are untrusted hints, but hosts use them to
|
|
103
|
+
// decide what to auto-approve, so flipping them is the most security-relevant
|
|
104
|
+
// drift a manifest can show.
|
|
105
|
+
function annotationWeakenings(before, after) {
|
|
106
|
+
const a = isPlainObject(before) ? before : {};
|
|
107
|
+
const b = isPlainObject(after) ? after : {};
|
|
108
|
+
const out = [];
|
|
109
|
+
if (a.readOnlyHint !== true && b.readOnlyHint === true) out.push("readOnlyHint became true");
|
|
110
|
+
if (a.destructiveHint !== false && b.destructiveHint === false) out.push("destructiveHint became false");
|
|
111
|
+
if (a.idempotentHint !== true && b.idempotentHint === true) out.push("idempotentHint became true");
|
|
112
|
+
if (a.openWorldHint !== false && b.openWorldHint === false) out.push("openWorldHint became false");
|
|
113
|
+
return out;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
// diffToolManifests(pinnedTools, currentTools) — explains drift between two
|
|
117
|
+
// complete tool lists. Returns { drift, manifest_digest_pinned,
|
|
118
|
+
// manifest_digest_current, added[], removed[], changed[] }.
|
|
119
|
+
export function diffToolManifests(pinnedTools, currentTools) {
|
|
120
|
+
const pinned = toolManifestDigest(pinnedTools);
|
|
121
|
+
const current = toolManifestDigest(currentTools);
|
|
122
|
+
const pinnedByName = new Map(pinnedTools.map((tool) => [tool.name, normalizeToolDefinition(tool)]));
|
|
123
|
+
const currentByName = new Map(currentTools.map((tool) => [tool.name, normalizeToolDefinition(tool)]));
|
|
124
|
+
|
|
125
|
+
const added = [...currentByName.keys()].filter((name) => !pinnedByName.has(name)).sort();
|
|
126
|
+
const removed = [...pinnedByName.keys()].filter((name) => !currentByName.has(name)).sort();
|
|
127
|
+
const changed = [];
|
|
128
|
+
for (const [name, before] of [...pinnedByName.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
|
|
129
|
+
const after = currentByName.get(name);
|
|
130
|
+
if (!after) continue;
|
|
131
|
+
const fields = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort();
|
|
132
|
+
const changedFields = fields.filter((field) => {
|
|
133
|
+
const x = field in before ? canonicalJson(before[field]) : null;
|
|
134
|
+
const y = field in after ? canonicalJson(after[field]) : null;
|
|
135
|
+
return x !== y;
|
|
136
|
+
});
|
|
137
|
+
if (changedFields.length === 0) continue;
|
|
138
|
+
changed.push({
|
|
139
|
+
name,
|
|
140
|
+
fields: changedFields,
|
|
141
|
+
categories: [...new Set(changedFields.map((field) => (Object.hasOwn(FIELD_CATEGORY, field) ? FIELD_CATEGORY[field] : "other")))].sort(),
|
|
142
|
+
annotation_weakenings: annotationWeakenings(before.annotations, after.annotations),
|
|
143
|
+
});
|
|
144
|
+
}
|
|
145
|
+
return {
|
|
146
|
+
profile: TOOL_MANIFEST_PROFILE,
|
|
147
|
+
drift: pinned.manifest_digest !== current.manifest_digest,
|
|
148
|
+
manifest_digest_pinned: pinned.manifest_digest,
|
|
149
|
+
manifest_digest_current: current.manifest_digest,
|
|
150
|
+
added,
|
|
151
|
+
removed,
|
|
152
|
+
changed,
|
|
153
|
+
};
|
|
154
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@intentrax/sdk",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.8.0",
|
|
4
4
|
"description": "Intentrax deterministic public SDK for proof verification and API-wrapper execution.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -18,6 +18,13 @@
|
|
|
18
18
|
"./http": {
|
|
19
19
|
"types": "./http.d.ts",
|
|
20
20
|
"default": "./http.js"
|
|
21
|
+
},
|
|
22
|
+
"./mcp": {
|
|
23
|
+
"types": "./mcp/index.d.ts",
|
|
24
|
+
"default": "./mcp/index.mjs"
|
|
25
|
+
},
|
|
26
|
+
"./readback": {
|
|
27
|
+
"default": "./readback/index.mjs"
|
|
21
28
|
}
|
|
22
29
|
},
|
|
23
30
|
"types": "./index.d.ts",
|
|
@@ -32,6 +39,17 @@
|
|
|
32
39
|
"http.ts",
|
|
33
40
|
"http.d.ts",
|
|
34
41
|
"README.md",
|
|
42
|
+
"mcp/*.mjs",
|
|
43
|
+
"mcp/*.d.ts",
|
|
44
|
+
"mcp/README.md",
|
|
45
|
+
"readback/*.mjs",
|
|
46
|
+
"readback/recipes/*.mjs",
|
|
47
|
+
"readback/README.md",
|
|
48
|
+
"sandbox/*.mjs",
|
|
49
|
+
"sandbox/examples",
|
|
50
|
+
"sandbox/README.md",
|
|
51
|
+
"scan/*.mjs",
|
|
52
|
+
"scan/README.md",
|
|
35
53
|
"trust"
|
|
36
54
|
],
|
|
37
55
|
"keywords": [
|