@kaditang/402sentinel-mcp 0.4.0 → 0.6.0

package/README.md

@@ -14,8 +14,9 @@ Tools — vet the **seller**:
 - `report_outcome` (free) — after paying, report delivery to train the reliability flywheel
 
 Tools — vet the **payment itself** (buyer-side):
-- `firewall` ($0.002) — should YOUR agent make THIS payment now? Catches fraudulent routing (payTo swapped vs the address you usually pay), drain velocity, overcharge, and injection-sourced instructions. Pass your payer wallet as `agent_id`.
+- `firewall` ($0.002) — should YOUR agent make THIS payment now? Catches fraudulent routing (payTo swapped vs the address you usually pay), drain velocity, overcharge, and injection-sourced instructions. `agent_id` + a wallet-ownership signature are attached automatically from your configured wallet — trusted routing history with no extra steps.
 - `firewall_record` (free) — seed your agent's payment history so the firewall has a behavioural baseline.
+- `firewall_outcome` (free) — after a verdict, report what actually happened (fraud / legit / …) so the firewall learns which signals are predictive and downweights noisy ones (safety signals stay deterministic).
 
 It's a thin client for the hosted service at **https://402sentinel.com** — the
 scoring model and facilitator-identification logic live server-side (closed); this

package/dist/index.js

@@ -24,8 +24,27 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { GatewayClient } from "@circle-fin/x402-batching/client";
+import { privateKeyToAccount } from "viem/accounts";
 const BASE = (process.env.SENTINEL_URL ?? "https://402sentinel.com").replace(/\/$/, "");
 const RAW_PK = process.env.CLIENT_PRIVATE_KEY ?? "";
+const PK = (!RAW_PK || RAW_PK.startsWith("0xYour"))
+    ? null
+    : (RAW_PK.startsWith("0x") ? RAW_PK : `0x${RAW_PK}`);
+const account = PK ? privateKeyToAccount(PK) : null;
+// Tools whose writes build TRUSTED history → auto-attach a wallet-ownership proof.
+// SAFETY: we sign ONLY this exact namespaced template (never arbitrary or server-
+// supplied content — no blind signing). It's an EIP-191 message signature, NOT a
+// transaction: it can't move funds, isn't replayable as a tx, and only proves the
+// signer controls its OWN agent_id. Scoped, harmless.
+const SIGN_TOOLS = new Set(["firewall", "firewall_record", "firewall_outcome"]);
+async function ownerProof(action) {
+    if (!account)
+        return {};
+    const owner_ts = Math.floor(Date.now() / 1000);
+    const agent = account.address.toLowerCase();
+    const owner_sig = await account.signMessage({ message: `402sentinel:${action}:${agent}:${owner_ts}` });
+    return { owner_sig, owner_ts };
+}
 const targetSchema = {
     type: "object",
     required: ["payto_address"],
@@ -113,10 +132,10 @@ const TOOLS = [
     },
     {
         name: "firewall",
-        description: "Buyer-side payment firewall: should YOUR agent make THIS payment now? Where assess_counterparty vets the seller, this vets the payment instruction in the context of your agent's own history + provenance. Returns allow/hold/block + signals: routing_anomaly (payTo swapped vs the address you usually pay = fraudulent routing), velocity_anomaly (drain), amount_anomaly (overcharge), provenance_flag, counterparty_risk, injection_destination (if the payTo appears in the untrusted page/tool-output you're acting on, the destination was injected — pass it as context.untrusted_text), intent_mismatch (pass context.intended={payto,max_amount} so a mid-flight redirect is caught), new_counterparty_burst, recurring_flagged (poisoned-memory loop). STRONGLY recommended: pass untrusted_text + intended to catch prompt-injection payments. Pass your payer wallet as agent_id. Costs $0.002. Seed history free with firewall_record.",
+        description: "Buyer-side payment firewall: should YOUR agent make THIS payment now? Where assess_counterparty vets the seller, this vets the payment instruction in the context of your agent's own history + provenance. Returns allow/hold/block + signals: routing_anomaly (payTo swapped vs the address you usually pay = fraudulent routing), velocity_anomaly (drain), amount_anomaly (overcharge), provenance_flag, counterparty_risk, injection_destination (if the payTo appears in the untrusted page/tool-output you're acting on, the destination was injected — pass it as context.untrusted_text), intent_mismatch (pass context.intended={payto,max_amount} so a mid-flight redirect is caught), new_counterparty_burst, recurring_flagged (poisoned-memory loop). STRONGLY recommended: pass untrusted_text + intended to catch prompt-injection payments. agent_id and a wallet-ownership signature are attached AUTOMATICALLY from your configured wallet — you don't pass agent_id, and your routing history is trusted with no extra steps. Costs $0.002. Seed history free with firewall_record.",
         inputSchema: {
             type: "object",
-            required: ["agent_id", "payment"],
+            required: ["payment"],
             properties: {
                 agent_id: { type: "string", description: "stable id for your agent — use your payer wallet address" },
                 payment: {
@@ -156,10 +175,10 @@ const TOOLS = [
     },
     {
         name: "firewall_record",
-        description: "FREE. Seed your agent's payment history so the firewall has a behavioural baseline (record past/known-good payments). Pass your payer wallet as agent_id.",
+        description: "FREE. Seed your agent's payment history so the firewall has a behavioural baseline (record past/known-good payments). agent_id and the wallet-ownership signature are attached automatically from your configured wallet, so the seeded history is trusted.",
         inputSchema: {
             type: "object",
-            required: ["agent_id", "payment"],
+            required: ["payment"],
             properties: {
                 agent_id: { type: "string", description: "use your payer wallet address" },
                 payment: {
@@ -177,15 +196,28 @@ const TOOLS = [
         endpoint: "/api/firewall/record",
         paid: false,
     },
+    {
+        name: "firewall_outcome",
+        description: "FREE. After a firewall verdict, report what actually happened so 402Sentinel learns which signals are predictive and downweights noisy ones (hard-block safety signals stay deterministic). Pass the assessment_id (fw_…) from a prior firewall call.",
+        inputSchema: {
+            type: "object",
+            required: ["assessment_id", "outcome"],
+            properties: {
+                assessment_id: { type: "string", description: "the fw_… id from a prior firewall call" },
+                outcome: { type: "string", enum: ["fraud", "confirmed_fraud", "not_delivered", "overcharged", "drained", "scam", "delivered", "legit", "fine"], description: "bad: fraud/confirmed_fraud/not_delivered/overcharged/drained/scam · good: delivered/legit/fine" },
+            },
+        },
+        endpoint: "/api/firewall/outcome",
+        paid: false,
+    },
 ];
 function clientOrNull() {
-    if (!RAW_PK || RAW_PK.startsWith("0xYour"))
+    if (!PK)
         return null;
-    const pk = (RAW_PK.startsWith("0x") ? RAW_PK : `0x${RAW_PK}`);
-    return new GatewayClient({ chain: "base", privateKey: pk });
+    return new GatewayClient({ chain: "base", privateKey: PK });
 }
 async function main() {
-    const server = new Server({ name: "402sentinel", version: "0.4.0" }, { capabilities: { tools: {} } });
+    const server = new Server({ name: "402sentinel", version: "0.6.0" }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
     }));
@@ -196,6 +228,15 @@ async function main() {
             return { content: [{ type: "text", text: `unknown tool: ${name}` }], isError: true };
         }
         try {
+            // Build the request body; auto-attach the ownership proof + set agent_id = own
+            // wallet for the signable tools, so the agent's history is trusted automatically.
+            let body = (args ?? {});
+            if (account && SIGN_TOOLS.has(tool.name)) {
+                body = { ...body, ...(await ownerProof(tool.name)) };
+                if (tool.name === "firewall" || tool.name === "firewall_record") {
+                    body = { ...body, agent_id: account.address }; // the wallet IS the agent identity
+                }
+            }
             let data;
             if (tool.paid) {
                 const client = clientOrNull();
@@ -210,14 +251,14 @@ async function main() {
                         isError: true,
                     };
                 }
-                ({ data } = await client.pay(`${BASE}${tool.endpoint}`, { method: "POST", body: args }));
+                ({ data } = await client.pay(`${BASE}${tool.endpoint}`, { method: "POST", body }));
             }
             else {
                 // free endpoint — plain POST, no payment
                 const res = await fetch(`${BASE}${tool.endpoint}`, {
                     method: "POST",
                     headers: { "Content-Type": "application/json" },
-                    body: JSON.stringify(args ?? {}),
+                    body: JSON.stringify(body),
                 });
                 data = await res.json().catch(() => ({}));
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaditang/402sentinel-mcp",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "MCP tools for x402 payment safety — vet the counterparty (risk score, allow/review/block, spending policy) AND vet the payment itself (buyer-side firewall: routing/drain/injection). Thin client for 402sentinel.com.",
   "type": "module",
   "bin": { "402sentinel-mcp": "./dist/index.js" },