@ic402/mcp 2.5.2

package/dist/guards.js

@@ -0,0 +1,233 @@
+/**
+ * Spend caps, config-escalation guard, dangerous-tool gate, and safe amount parsing
+ * for the ic402 MCP server.
+ *
+ * Extracted from index.ts so the security-critical decisions are pure and unit-testable
+ * (see test/mcp-guards.test.ts). The MCP is driven by a possibly prompt-injected LLM
+ * while holding a controller identity, so these guards are the last line between the
+ * model and value movement.
+ */
+/**
+ * Parse a token amount (atomic units) from untrusted input into a bigint, REJECTING
+ * floats and JS numbers that have already lost precision. C5: `value: z.number()`
+ * silently truncated uint256 amounts above 2^53; callers must pass amounts as decimal
+ * strings, and an unsafe number is rejected (not silently used).
+ */
+export function parseAtomicAmount(input, field = 'amount') {
+    if (typeof input === 'bigint') {
+        if (input < 0n)
+            throw new Error(`Invalid negative ${field}: ${input}`);
+        return input;
+    }
+    if (typeof input === 'string') {
+        const t = input.trim();
+        if (!/^\d+$/.test(t)) {
+            throw new Error(`Invalid ${field}: ${JSON.stringify(input)} (expected a non-negative integer string)`);
+        }
+        return BigInt(t);
+    }
+    if (typeof input === 'number') {
+        if (!Number.isSafeInteger(input) || input < 0) {
+            throw new Error(`Unsafe numeric ${field}: ${input}. Pass token amounts as decimal STRINGS — ` +
+                `a JS number cannot represent a uint256 without precision loss.`);
+        }
+        return BigInt(input);
+    }
+    throw new Error(`Invalid ${field}: ${JSON.stringify(input)}`);
+}
+/**
+ * Enforce the per-call and cumulative session spend caps. Throws on violation; never
+ * mutates state. (S1/S9 — the cap logic that every value-moving tool must pass.)
+ */
+export function checkSpend(amountAtomic, caps, sessionSpentAtomic) {
+    if (amountAtomic < 0n) {
+        throw new Error(`Invalid negative amount: ${amountAtomic}`);
+    }
+    if (amountAtomic > caps.perCallMaxAtomic) {
+        throw new Error(`Amount ${amountAtomic} exceeds per-call cap ${caps.perCallMaxAtomic} (atomic units). ` +
+            `Raise perCallMaxAtomic via "configure" (only if the operator enabled security changes).`);
+    }
+    if (sessionSpentAtomic + amountAtomic > caps.sessionMaxAtomic) {
+        throw new Error(`Amount ${amountAtomic} would exceed the cumulative session cap ${caps.sessionMaxAtomic} ` +
+            `(already spent ${sessionSpentAtomic} atomic units).`);
+    }
+}
+/**
+ * S8: Resolve the effective security config from an LLM-supplied `configure` request.
+ * The caps / localDev / autoPayment knobs loosen the server's security posture, so the
+ * LLM may only change them when the OPERATOR opted in at startup (allowSecurityChanges).
+ * Otherwise the request's security fields are IGNORED and the operator/default config
+ * stands — a prompt-injected model cannot raise its own caps or enable localDev.
+ * Returns the resolved config and the list of fields that were ignored (for reporting).
+ */
+export function resolveSecurityConfig(base, req, allowSecurityChanges) {
+    if (allowSecurityChanges) {
+        return {
+            config: {
+                localDev: req.localDev ?? base.localDev,
+                autoPayment: req.autoPayment ?? base.autoPayment,
+                perCallMaxAtomic: req.perCallMaxAtomic !== undefined
+                    ? parseAtomicAmount(req.perCallMaxAtomic, 'perCallMaxAtomic')
+                    : base.perCallMaxAtomic,
+                sessionMaxAtomic: req.sessionMaxAtomic !== undefined
+                    ? parseAtomicAmount(req.sessionMaxAtomic, 'sessionMaxAtomic')
+                    : base.sessionMaxAtomic,
+            },
+            ignored: [],
+        };
+    }
+    const ignored = [];
+    if (req.localDev)
+        ignored.push('localDev');
+    if (req.autoPayment)
+        ignored.push('autoPayment');
+    if (req.perCallMaxAtomic !== undefined)
+        ignored.push('perCallMaxAtomic');
+    if (req.sessionMaxAtomic !== undefined)
+        ignored.push('sessionMaxAtomic');
+    return { config: { ...base }, ignored };
+}
+/**
+ * S1/S9: Tools that are dangerous primitives — the raw EIP-712 signing oracle
+ * (`sign_typed_data`, which can authorize an arbitrary-value transfer and bypasses the
+ * spend caps) and destructive `delete_content` — are DEFAULT-DENIED so a prompt-injected
+ * LLM cannot reach them. An operator enables them explicitly at startup.
+ */
+const DANGEROUS_TOOLS = new Set(['sign_typed_data', 'delete_content']);
+/**
+ * SEC-3: state-changing ADMIN tools — registering/enabling services, claiming + submitting job
+ * results, uploading content. They mutate canister state (and drive the value-moving job lifecycle),
+ * so like the dangerous primitives they are now DEFAULT-DENIED and require an explicit operator
+ * opt-in at startup. An in-band `confirm` flag alone is NOT sufficient — a prompt-injected LLM can
+ * set it. (`delete_content` is already covered by DANGEROUS_TOOLS.)
+ */
+const ADMIN_TOOLS = new Set([
+    'register_service',
+    'enable_service',
+    'claim_job',
+    'submit_job_result',
+    'upload_content',
+]);
+export function isToolAllowed(toolName, allowDangerousTools, allowAdminTools) {
+    if (DANGEROUS_TOOLS.has(toolName))
+        return allowDangerousTools;
+    if (ADMIN_TOOLS.has(toolName))
+        return allowAdminTools;
+    return true;
+}
+/**
+ * Resolve the operator's startup security config from an optional JSON config file and the
+ * environment. BOTH are out-of-band inputs the LLM cannot influence, so the security boundary
+ * stays with the operator (audit S8). Precedence: built-in defaults < config file < env vars
+ * (env wins, so an operator can override a file value at launch). Unparseable values fall back
+ * to the lower-precedence source rather than throwing, so a typo can't crash the server.
+ */
+export function resolveOperatorConfig(file, env, defaults) {
+    const f = file ?? {};
+    const isTrue = (v) => v === '1' || v === 'true';
+    const pickBool = (fileKey, envKey) => {
+        if (env[envKey] !== undefined)
+            return isTrue(env[envKey]);
+        if (typeof f[fileKey] === 'boolean')
+            return f[fileKey];
+        return false;
+    };
+    const pickAmount = (fileKey, envKey, dflt) => {
+        const raw = env[envKey] !== undefined ? env[envKey] : f[fileKey];
+        if (raw === undefined)
+            return dflt;
+        try {
+            return parseAtomicAmount(raw, envKey);
+        }
+        catch {
+            return dflt;
+        }
+    };
+    return {
+        security: {
+            localDev: pickBool('localDev', 'IC402_MCP_LOCAL_DEV'),
+            autoPayment: pickBool('autoPayment', 'IC402_MCP_AUTO_PAYMENT'),
+            perCallMaxAtomic: pickAmount('perCallMaxAtomic', 'IC402_MCP_PER_CALL_MAX_ATOMIC', defaults.perCallMaxAtomic),
+            sessionMaxAtomic: pickAmount('sessionMaxAtomic', 'IC402_MCP_SESSION_MAX_ATOMIC', defaults.sessionMaxAtomic),
+        },
+        allowSecurityChanges: pickBool('allowSecurityChanges', 'IC402_MCP_ALLOW_SECURITY_CHANGES'),
+        allowDangerousTools: pickBool('allowDangerousTools', 'IC402_MCP_ALLOW_DANGEROUS_TOOLS'),
+        allowAdminTools: pickBool('allowAdminTools', 'IC402_MCP_ALLOW_ADMIN_TOOLS'),
+    };
+}
+// ---------------------------------------------------------------------------
+// Generic `call` tool method gating (C3)
+//
+// The generic MCP `call` tool must only reach read-only/query methods; state-changing, signing,
+// payment, and admin methods have dedicated, capped, confirmation-gated tools. This logic lives
+// here (not in index.ts, which boots the server on import and can't be unit-tested) so the decision
+// tree can be exercised directly — see test/mcp-guards.test.ts.
+// ---------------------------------------------------------------------------
+/** Curated read-only allowlist — every entry is a `query` (or otherwise non-state-changing read)
+ *  in the IDL. Authoritative: wins over the substring blocklist, so a genuine read-only getter
+ *  whose name contains a blocked substring (e.g. getPolicyConfig contains 'policy') is still
+ *  admitted. ONLY add verified non-state-changing query methods. */
+export const READONLY_CALL_ALLOWLIST = new Set([
+    'listContent',
+    'getChunk',
+    'getAgentCard',
+    'getAgentId',
+    'verifyGrant',
+    'listServices',
+    'getJobStatus',
+    'getJob',
+    'getJobResult',
+    'keccak256',
+    'getPolicyConfig',
+]);
+/** Substrings that must NEVER be reachable through the generic `call` path — signing/admin/
+ *  value-moving method names that have dedicated tools. */
+export const CALL_BLOCK_SUBSTRINGS = [
+    'sign',
+    'set',
+    'submit',
+    'open',
+    'close',
+    'transfer',
+    'register',
+    'pay',
+    'approve',
+    'policy',
+    'upload',
+    'delete',
+    'claim',
+    'confirm',
+    'dispute',
+    'enable',
+    'disable',
+    'end',
+];
+// M16 (posture note): `getContent` is dual-mode — a read-only 402 challenge fetch with no
+// PaymentSignature, but a SETTLING update when a signature is passed. It is the only content-
+// purchase entry point over MCP, and there is no dedicated capped/confirmed purchase tool, so it
+// stays reachable via the get-prefix fallback below. Settlement pays the operator's own canister
+// (C-1), and spend caps are outbound-signing-only; a future `buy_content` tool is the right fix.
+/** Decide whether a method name may be called through the generic (uncapped, unconfirmed) `call`
+ *  tool. Order: allowlist (authoritative) → substring blocklist → read-only name-prefix fallback. */
+export function isCallMethodAllowed(method) {
+    const lower = method.toLowerCase();
+    if (READONLY_CALL_ALLOWLIST.has(method))
+        return { ok: true };
+    for (const bad of CALL_BLOCK_SUBSTRINGS) {
+        if (lower.includes(bad)) {
+            return {
+                ok: false,
+                reason: `Method "${method}" looks state-changing/signing (contains "${bad}"). Use the dedicated tool for this action.`,
+            };
+        }
+    }
+    // Forward-compat: admit new read-only getters by name prefix, only after the blocklist cleared it.
+    if (/^(get|list|fetch|is)[A-Z]/.test(method) || /^(get|list|fetch|is)$/.test(method)) {
+        return { ok: true };
+    }
+    return {
+        ok: false,
+        reason: `Method "${method}" is not on the read-only allowlist. The generic "call" tool only permits query/read methods; use a dedicated tool for state-changing or signing operations.`,
+    };
+}
+//# sourceMappingURL=guards.js.map

package/dist/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};