devx-address-poisoning-check 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Made by DevX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# Address Poisoning Check
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Is this the address you meant?** Address poisoning plants a lookalike address (same first and last characters, different middle) in a wallet's history with a zero-value, dust or fake-token transfer, and waits for the owner (or their AI agent) to copy it. Bitquery counted about **$76M stolen on Ethereum alone in the 12 months to July 2026**.
+
+This repo has three pieces, all read-only (we never ask for keys and never move funds):
+
+| | What | Cost |
+|---|---|---|
+| **CLI / stdio MCP** `devx-address-poisoning-check` | Offline: is the recipient a lookalike of any address you trust? Is its EIP-55 checksum valid? Nothing leaves your machine. | free |
+| **Remote MCP** `https://address-poisoning-check.nextill-pos.workers.dev/mcp` | Same offline check as a hosted MCP tool | free |
+| **HTTP API** `GET /v1/check?from=<sender>&to=<recipient>` | On-chain: scans the sender's real transfer history (Ethereum + Base, optional Avalanche) and flags lookalikes of real counterparties, zero-value / dust / fake-token poisoning transfers (with tx hashes), recipients that only ever appeared through such transfers, and senders that were already poisoned. Returns `ok \| caution \| danger` and the address you probably meant. | 0.005 USDC via [x402](https://x402.org) on Base |
+
+Live: https://address-poisoning-check.nextill-pos.workers.dev
+
+## CLI
+
+```sh
+npx devx-address-poisoning-check 0xd9A1C3788D81257612E2581A6ea0aDa244853a91 --known 0xd9A1b0B1e1aE382DbDc898Ea68012FfcB2853a91
+# DANGER: Looks like 0xd9a1...3a91 (same first 4 / last 6 hex chars) but is a different address. Classic address-poisoning lookalike.
+```
+
+Exit code `2` on danger, so it can gate scripts and agent payment flows.
+
+## MCP
+
+Claude Desktop / Cursor (stdio):
+
+```json
+{ "mcpServers": { "address-poisoning-check": { "command": "npx", "args": ["-y", "devx-address-poisoning-check", "mcp"] } } }
+```
+
+Or remote (streamable HTTP): `https://address-poisoning-check.nextill-pos.workers.dev/mcp`
+
+Tools: `check_recipient_lookalike` (free), `onchain_check_info` (how to buy the on-chain check; does not pay).
+
+## Paid on-chain check (x402)
+
+```
+GET https://address-poisoning-check.nextill-pos.workers.dev/v1/check?from=0x...&to=0x...[&chains=ethereum,base,avalanche]
+```
+
+* Answers `402` with an x402 v1 body (`X-PAYMENT`, network `base`) and a v2 `PAYMENT-REQUIRED` header (`PAYMENT-SIGNATURE`, `eip155:8453`). Both work.
+* 5000 atomic USDC (0.005 USDC) to `0xB3cDDccEe6B150c8efFD55B961afc0Ecefe7f247`, settled through the Coinbase CDP facilitator, listed in the CDP x402 Bazaar.
+* Settled only **after** the report is produced; bad input or data-source errors are not charged.
+* Data: Ethereum/Avalanche via the Routescan explorer API (last 300 token transfers + 150 transactions of the sender); Base via public RPC logs (about the last 4-5 days of USDC, USDbC, USDT, EURC, WETH, cbBTC transfers). It is a heuristic over a window of public data: always confirm the full address with the payee.
+
+Example (the May 2024 $68M WBTC case): `from=0x1E227979f0b5BC691a70DEAed2e0F39a6F538FD5&to=0xd9A1C3788D81257612E2581A6ea0aDa244853a91` returns `danger` / `possibly_already_poisoned`: the victim did send real value to that address, but it first appeared in their history through a zero-value transfer.
+
+OpenAPI: [/openapi.json](https://address-poisoning-check.nextill-pos.workers.dev/openapi.json) · Terms: [/terms](https://address-poisoning-check.nextill-pos.workers.dev/terms)
+
+## Related DevX tools
+
+* [7702 Sweeper Check](https://github.com/devx-agent/7702-sweeper-check): is an EIP-7702 sweeper delegation set on a wallet?
+* [Crypto Link Check](https://github.com/devx-agent/crypto-link-check): is a crypto URL a phishing / drainer lookalike?
+* [Repo Run Check](https://github.com/devx-agent/repo-run-check): is a GitHub repo safe to clone and run?
+
+## Layout
+
+* `cli/`: npm package `devx-address-poisoning-check` (CLI + stdio MCP), `npm test`
+* `worker/`: the Cloudflare Worker behind the hosted API (`npm run build`)
+
+MIT. Made by [DevX](https://madebydevx.com) · madebydevx@gmail.com

package/bin/cli.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { checkRecipient, onchainPrice } from "../src/index.js";
+const args = process.argv.slice(2);
+if (args[0] === "mcp") {
+  const { createServer } = await import("../src/mcp.js");
+  const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+  await createServer().connect(new StdioServerTransport());
+} else if (!args.length || args[0] === "-h" || args[0] === "--help") {
+  process.stdout.write(`Usage:
+  devx-address-poisoning-check <recipient> --known 0xA,0xB [--json]   offline lookalike + checksum check
+  devx-address-poisoning-check onchain <from> <to>                     price/URL of the hosted on-chain check (does not pay)
+  devx-address-poisoning-check mcp                                     run as an MCP server (stdio)
+Exit codes: 0 match/unknown, 2 danger, 1 error. Never asks for keys.
+`);
+} else if (args[0] === "onchain") {
+  try { process.stdout.write(JSON.stringify(await onchainPrice(args[1], args[2]), null, 2) + "\n"); } catch (e) { process.stderr.write(e.message + "\n"); process.exitCode = 1; }
+} else {
+  const ki = args.indexOf("--known"); const known = ki >= 0 ? String(args[ki + 1] || "").split(/[\s,]+/).filter(Boolean) : [];
+  const json = args.includes("--json");
+  try { const r = checkRecipient(args[0], known); process.stdout.write(json ? JSON.stringify(r, null, 2) + "\n" : `${r.verdict.toUpperCase()}: ${r.note}\n${r.lookalikes.map((l) => "  lookalike of " + l.address).join("\n")}\n`); process.exitCode = r.verdict === "danger" ? 2 : 0; }
+  catch (e) { process.stderr.write(e.message + "\n"); process.exitCode = 1; }
+}

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "devx-address-poisoning-check",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Free CLI + MCP server: before you send crypto, check the recipient for address poisoning (lookalike of an address you trust, bad EIP-55 checksum). Offline, no keys. Optional hosted on-chain check via x402.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Made by DevX (madebydevx.com)",
+  "repository": { "type": "git", "url": "git+https://github.com/devx-agent/address-poisoning-check.git" },
+  "homepage": "https://address-poisoning-check.nextill-pos.workers.dev",
+  "bugs": { "url": "https://github.com/devx-agent/address-poisoning-check/issues" },
+  "keywords": ["address-poisoning", "wallet-security", "ethereum", "base", "usdc", "mcp", "x402", "agents", "lookalike", "scam"],
+  "engines": { "node": ">=20" },
+  "main": "./src/index.js",
+  "bin": { "devx-address-poisoning-check": "bin/cli.js" },
+  "files": ["src", "bin", "README.md", "LICENSE"],
+  "scripts": { "test": "node --test test/*.test.js" },
+  "mcpName": "io.github.devx-agent/address-poisoning-check",
+  "dependencies": { "@modelcontextprotocol/sdk": "^1.32.1", "@noble/hashes": "^1.8.0", "zod": "^3.25.0" }
+}

package/src/index.js

@@ -0,0 +1,50 @@
+// devx-address-poisoning-check: offline lookalike + EIP-55 checks, and a client for the hosted on-chain check.
+import { keccak_256 } from "@noble/hashes/sha3";
+export const DEFAULT_BASE = "https://address-poisoning-check.nextill-pos.workers.dev";
+export const ADDR_RE = /^0x[0-9a-fA-F]{40}$/;
+const lc = (a) => String(a || "").trim().toLowerCase();
+export const isAddr = (a) => ADDR_RE.test(String(a || "").trim());
+
+/** Shared leading / trailing hex characters (after 0x). */
+export function similarity(a, b) {
+  a = lc(a).slice(2); b = lc(b).slice(2);
+  let prefix = 0; while (prefix < 40 && a[prefix] === b[prefix]) prefix++;
+  let suffix = 0; while (suffix < 40 && a[39 - suffix] === b[39 - suffix]) suffix++;
+  return { prefix, suffix, identical: a === b };
+}
+/** True when b looks like a (same first/last characters, different middle): the shape address poisoners generate. */
+export function isLookalike(a, b) {
+  const s = similarity(a, b); if (s.identical) return false;
+  return (s.prefix >= 3 && s.suffix >= 3) || (s.prefix + s.suffix >= 8 && Math.min(s.prefix, s.suffix) >= 2);
+}
+/** EIP-55: true valid, false invalid, null when the address is all lower/upper case (no checksum). */
+export function checksumOk(a) {
+  a = String(a).trim(); const h = a.slice(2);
+  if (h === h.toLowerCase() || h === h.toUpperCase()) return null;
+  const hash = Array.from(keccak_256(new TextEncoder().encode(h.toLowerCase())), (x) => x.toString(16).padStart(2, "0")).join("");
+  for (let i = 0; i < 40; i++) { const c = h[i]; if (/[a-f]/i.test(c) && ((parseInt(hash[i], 16) >= 8) !== (c === c.toUpperCase()))) return false; }
+  return true;
+}
+const short = (a) => lc(a).slice(0, 6) + "..." + lc(a).slice(-4);
+
+/** Offline check of a recipient against addresses you trust. Nothing leaves your machine. */
+export function checkRecipient(to, known = []) {
+  if (!isAddr(to)) throw new Error("to must be 0x + 40 hex characters");
+  const bad = known.find((k) => !isAddr(k)); if (bad) throw new Error("invalid known address: " + bad);
+  const out = { to: lc(to), checksum_valid: checksumOk(to), compared: known.length, matches: [], lookalikes: [] };
+  for (const k of known) { const s = similarity(to, k); if (s.identical) out.matches.push(lc(k)); else if (isLookalike(to, k)) out.lookalikes.push({ address: lc(k), shared_prefix: s.prefix, shared_suffix: s.suffix, shown_as: short(k) }); }
+  out.verdict = out.checksum_valid === false ? "danger" : out.lookalikes.length && !out.matches.length ? "danger" : out.matches.length ? "match" : "unknown";
+  out.note = out.verdict === "danger" ? (out.checksum_valid === false ? "Checksum is invalid: the address was mistyped or altered." : `Looks like ${out.lookalikes[0].shown_as} (same first ${out.lookalikes[0].shared_prefix} / last ${out.lookalikes[0].shared_suffix} hex chars) but is a different address. Classic address-poisoning lookalike.`)
+    : out.verdict === "match" ? "Exactly matches an address you supplied." : "No lookalike among the supplied addresses.";
+  out.onchain_check = `${DEFAULT_BASE}/v1/check?from=<your wallet>&to=${lc(to)}`;
+  return out;
+}
+
+/** Info for the paid on-chain check (x402). Fetches the 402 challenge, does not pay. */
+export async function onchainPrice(from, to, { baseUrl = DEFAULT_BASE, fetch: f = globalThis.fetch } = {}) {
+  if (!isAddr(from) || !isAddr(to)) throw new Error("from and to must be 0x + 40 hex characters");
+  const url = `${baseUrl.replace(/\/$/, "")}/v1/check?from=${lc(from)}&to=${lc(to)}`;
+  const r = await f(url, { headers: { accept: "application/json", "user-agent": "devx-address-poisoning-check" } });
+  const body = await r.json(); const a = (body.accepts || [])[0] || {};
+  return { url, status: r.status, price_usdc: Number(a.maxAmountRequired || a.amount || 0) / 1e6, payTo: a.payTo, network: a.network, note: "Pay with any x402 client (v1 X-PAYMENT or v2 PAYMENT-SIGNATURE). Settled only after the report is produced." };
+}

package/src/mcp.js

@@ -0,0 +1,12 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { checkRecipient, DEFAULT_BASE } from "./index.js";
+export function createServer() {
+  const server = new McpServer({ name: "devx-address-poisoning-check", version: "1.0.0" }, { instructions: "Before sending crypto, check the recipient for address poisoning (lookalike of an address you trust, bad EIP-55 checksum). Runs offline; never asks for keys." });
+  server.tool("check_recipient_lookalike", "Free, offline: is the recipient a lookalike (same first/last hex chars, different middle) of any trusted address, and is its EIP-55 checksum valid? Call before every transfer to a pasted or copied address.",
+    { to: z.string().regex(/^0x[0-9a-fA-F]{40}$/).describe("recipient you are about to pay"), known: z.array(z.string().regex(/^0x[0-9a-fA-F]{40}$/)).max(200).default([]).describe("trusted addresses: address book, previous real payees") },
+    async ({ to, known }) => { try { const r = checkRecipient(to, known); return { content: [{ type: "text", text: `Verdict: ${r.verdict}. ${r.note}\n\n${JSON.stringify(r)}` }] }; } catch (e) { return { isError: true, content: [{ type: "text", text: String(e.message || e) }] }; } });
+  server.tool("onchain_check_info", "How to buy the hosted on-chain check that scans the sender's real transfer history (Ethereum, Base, Avalanche) for poisoning transfers and lookalikes: x402, 0.005 USDC on Base. Does not pay.", {},
+    async () => ({ content: [{ type: "text", text: `GET ${DEFAULT_BASE}/v1/check?from=<sending wallet>&to=<recipient> returns HTTP 402 (x402 v1 body + v2 PAYMENT-REQUIRED header), 5000 units USDC on Base = 0.005 USDC. Settled only after the report is produced. Docs: ${DEFAULT_BASE}/openapi.json` }] }));
+  return server;
+}