aipou-mcp-server 0.3.1 → 0.5.0

package/dist/init.d.ts

@@ -0,0 +1,32 @@
+export declare const AIPOU_TOKEN_ADDRESS = "0x55f0Cc5e51A1284D20337d6cbb18938C8A1ABCbB";
+export declare const AIPOU_CLAIMS_ADDRESS = "0x4ca4C98fB784D20EdC8E2A7F531dAab4c6e53058";
+export interface InitializationResult {
+    mode: "persistent_identity_initialized" | "persistent_identity_already_initialized";
+    wallet: string;
+    dataDir: string;
+    keyFile: string;
+    platformAccessRestricted: true;
+    mcpConfig: {
+        mcpServers: {
+            aipou: {
+                command: "npx";
+                args: ["-y", "aipou-mcp-server"];
+                env: {
+                    AIPOU_AGENT_KEY_FILE: string;
+                    AIPOU_DATA_DIR: string;
+                    AIPOU_CONTRACT_ADDRESS: string;
+                    AIPOU_CLAIMS_ADDRESS: string;
+                };
+            };
+        };
+    };
+    safety: {
+        dedicatedWalletCreated: boolean;
+        privateKeyPrinted: false;
+        existingKeyOverwritten: false;
+        fundsMoved: false;
+        claimSubmitted: false;
+    };
+}
+export declare function initializePersistentIdentity(dataDirInput?: string): Promise<InitializationResult>;
+export declare function describeExistingIdentity(dataDirInput?: string): Promise<InitializationResult>;

package/dist/init.js

@@ -0,0 +1,69 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Wallet } from "ethers";
+import { restrictToCurrentUser } from "./secure-file.js";
+export const AIPOU_TOKEN_ADDRESS = "0x55f0Cc5e51A1284D20337d6cbb18938C8A1ABCbB";
+export const AIPOU_CLAIMS_ADDRESS = "0x4ca4C98fB784D20EdC8E2A7F531dAab4c6e53058";
+function identityPaths(dataDirInput) {
+    const dataDir = path.resolve(dataDirInput || path.join(os.homedir(), ".aipou"));
+    return { dataDir, keyFile: path.join(dataDir, "agent-wallet.key") };
+}
+function buildResult(mode, walletAddress, dataDir, keyFile) {
+    return {
+        mode,
+        wallet: walletAddress,
+        dataDir,
+        keyFile,
+        platformAccessRestricted: true,
+        mcpConfig: {
+            mcpServers: {
+                aipou: {
+                    command: "npx",
+                    args: ["-y", "aipou-mcp-server"],
+                    env: {
+                        AIPOU_AGENT_KEY_FILE: keyFile,
+                        AIPOU_DATA_DIR: dataDir,
+                        AIPOU_CONTRACT_ADDRESS: AIPOU_TOKEN_ADDRESS,
+                        AIPOU_CLAIMS_ADDRESS
+                    }
+                }
+            }
+        },
+        safety: {
+            dedicatedWalletCreated: mode === "persistent_identity_initialized",
+            privateKeyPrinted: false,
+            existingKeyOverwritten: false,
+            fundsMoved: false,
+            claimSubmitted: false
+        }
+    };
+}
+export async function initializePersistentIdentity(dataDirInput) {
+    const { dataDir, keyFile } = identityPaths(dataDirInput);
+    const wallet = Wallet.createRandom();
+    await mkdir(dataDir, { recursive: true, mode: 0o700 });
+    await writeFile(keyFile, `${wallet.privateKey}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+        flag: "wx"
+    });
+    const platformAccessRestricted = await restrictToCurrentUser(keyFile);
+    if (!platformAccessRestricted) {
+        await rm(keyFile, { force: true });
+        throw new Error("Could not restrict dedicated-wallet key access to the current user");
+    }
+    return buildResult("persistent_identity_initialized", wallet.address, dataDir, keyFile);
+}
+// Second-run UX: an existing key is reported, never regenerated or printed.
+// Re-applying the ACL heals a broken restriction; the existing key is never removed.
+export async function describeExistingIdentity(dataDirInput) {
+    const { dataDir, keyFile } = identityPaths(dataDirInput);
+    const privateKey = (await readFile(keyFile, "utf8")).trim();
+    const wallet = new Wallet(privateKey);
+    const platformAccessRestricted = await restrictToCurrentUser(keyFile);
+    if (!platformAccessRestricted) {
+        throw new Error("Existing dedicated-wallet key found, but its access could not be restricted to the current user");
+    }
+    return buildResult("persistent_identity_already_initialized", wallet.address, dataDir, keyFile);
+}

package/dist/init.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/init.test.js

@@ -0,0 +1,113 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { agentWallet } from "./identity.js";
+import { describeExistingIdentity, initializePersistentIdentity } from "./init.js";
+const execFileAsync = promisify(execFile);
+function parseTextResult(result) {
+    const content = result.content;
+    const text = content?.find((part) => part.type === "text")?.text;
+    if (!text)
+        throw new Error("Tool result did not include a text JSON payload");
+    return JSON.parse(text);
+}
+test("persistent init creates a dedicated key file without printing the secret", async () => {
+    const dataDir = await mkdtemp(path.join(os.tmpdir(), "aipou-init-test-"));
+    const previousInlineKey = process.env.AIPOU_AGENT_PRIVATE_KEY;
+    const previousKeyFile = process.env.AIPOU_AGENT_KEY_FILE;
+    try {
+        const result = await initializePersistentIdentity(dataDir);
+        const privateKey = (await readFile(result.keyFile, "utf8")).trim();
+        assert.equal(result.mode, "persistent_identity_initialized");
+        assert.equal(result.platformAccessRestricted, true);
+        assert.match(result.wallet, /^0x[0-9a-fA-F]{40}$/);
+        assert.match(privateKey, /^0x[0-9a-fA-F]{64}$/);
+        assert.equal(JSON.stringify(result).includes(privateKey), false);
+        assert.equal(result.mcpConfig.mcpServers.aipou.env.AIPOU_AGENT_KEY_FILE, result.keyFile);
+        assert.deepEqual(result.safety, {
+            dedicatedWalletCreated: true,
+            privateKeyPrinted: false,
+            existingKeyOverwritten: false,
+            fundsMoved: false,
+            claimSubmitted: false
+        });
+        delete process.env.AIPOU_AGENT_PRIVATE_KEY;
+        process.env.AIPOU_AGENT_KEY_FILE = result.keyFile;
+        assert.equal(agentWallet().address, result.wallet);
+        await assert.rejects(initializePersistentIdentity(dataDir), /EEXIST|file already exists/i);
+        assert.equal((await readFile(result.keyFile, "utf8")).trim(), privateKey);
+        const existing = await describeExistingIdentity(dataDir);
+        assert.equal(existing.mode, "persistent_identity_already_initialized");
+        assert.equal(existing.wallet, result.wallet);
+        assert.equal(existing.safety.dedicatedWalletCreated, false);
+        assert.equal(JSON.stringify(existing).includes(privateKey), false);
+        assert.equal((await readFile(result.keyFile, "utf8")).trim(), privateKey);
+    }
+    finally {
+        if (previousInlineKey === undefined)
+            delete process.env.AIPOU_AGENT_PRIVATE_KEY;
+        else
+            process.env.AIPOU_AGENT_PRIVATE_KEY = previousInlineKey;
+        if (previousKeyFile === undefined)
+            delete process.env.AIPOU_AGENT_KEY_FILE;
+        else
+            process.env.AIPOU_AGENT_KEY_FILE = previousKeyFile;
+        await rm(dataDir, { recursive: true, force: true });
+    }
+});
+test("re-running CLI init reports the existing identity cleanly", async () => {
+    const dataDir = await mkdtemp(path.join(os.tmpdir(), "aipou-init-rerun-test-"));
+    const indexPath = fileURLToPath(new URL("./index.js", import.meta.url));
+    try {
+        const first = JSON.parse((await execFileAsync(process.execPath, [indexPath, "--init", "--data-dir", dataDir])).stdout);
+        const { stdout, stderr } = await execFileAsync(process.execPath, [indexPath, "--init", "--data-dir", dataDir]);
+        const second = JSON.parse(stdout);
+        const privateKey = (await readFile(second.keyFile, "utf8")).trim();
+        assert.equal(second.mode, "persistent_identity_already_initialized");
+        assert.equal(second.wallet, first.wallet);
+        assert.equal(second.safety.dedicatedWalletCreated, false);
+        assert.equal(second.safety.existingKeyOverwritten, false);
+        assert.equal(stdout.includes(privateKey), false);
+        assert.equal(stderr.includes("EEXIST"), false);
+    }
+    finally {
+        await rm(dataDir, { recursive: true, force: true });
+    }
+});
+test("CLI init output starts an MCP server with the generated key file", async () => {
+    const dataDir = await mkdtemp(path.join(os.tmpdir(), "aipou-init-cli-test-"));
+    const indexPath = fileURLToPath(new URL("./index.js", import.meta.url));
+    let transport;
+    try {
+        const { stdout } = await execFileAsync(process.execPath, [indexPath, "--init", "--data-dir", dataDir]);
+        const result = JSON.parse(stdout);
+        const privateKey = (await readFile(result.keyFile, "utf8")).trim();
+        assert.equal(stdout.includes(privateKey), false);
+        const config = result.mcpConfig.mcpServers.aipou;
+        transport = new StdioClientTransport({
+            command: process.execPath,
+            args: [indexPath],
+            stderr: "pipe",
+            env: { ...process.env, ...config.env }
+        });
+        const client = new Client({ name: "aipou-init-cli-test", version: "1.0.0" });
+        await client.connect(transport);
+        const identity = parseTextResult(await client.callTool({
+            name: "get_aipou_identity",
+            arguments: {}
+        }));
+        assert.equal(identity.wallet, result.wallet);
+    }
+    finally {
+        if (transport)
+            await transport.close();
+        await rm(dataDir, { recursive: true, force: true });
+    }
+});

package/dist/receipt-metadata.d.ts

@@ -0,0 +1,5 @@
+export declare const AIPOU_RECEIPT_META_KEY = "io.github.0xddneto/aipou-receipt";
+export declare function buildReceiptResultMeta(receipt: {
+    receiptId: string;
+    collectorPublicKey: string;
+}): Record<string, unknown>;

package/dist/receipt-metadata.js

@@ -0,0 +1,16 @@
+import { collectorFingerprint } from "./collector.js";
+export const AIPOU_RECEIPT_META_KEY = "io.github.0xddneto/aipou-receipt";
+export function buildReceiptResultMeta(receipt) {
+    const digest = receipt.receiptId.replace(/^0x/, "").toLowerCase();
+    return {
+        [AIPOU_RECEIPT_META_KEY]: {
+            id: receipt.receiptId,
+            uri: `aipou://receipts/${receipt.receiptId}`,
+            issuer: collectorFingerprint(receipt.collectorPublicKey),
+            digest: `sha256:${digest}`,
+            evidenceClass: "issuer_asserted",
+            scheme: "aipou-receipt-v1",
+            status: "local"
+        }
+    };
+}

package/dist/receipt-metadata.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/receipt-metadata.test.js

@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import { generateKeyPairSync } from "node:crypto";
+import test from "node:test";
+import { AIPOU_RECEIPT_META_KEY, buildReceiptResultMeta } from "./receipt-metadata.js";
+test("receipt result metadata is compact, namespaced, and contains no claim authority", () => {
+    const pair = generateKeyPairSync("ed25519");
+    const collectorPublicKey = pair.publicKey.export({ format: "pem", type: "spki" }).toString();
+    const receiptId = `0x${"ab".repeat(32)}`;
+    const metadata = buildReceiptResultMeta({ receiptId, collectorPublicKey });
+    const projection = metadata[AIPOU_RECEIPT_META_KEY];
+    assert.deepEqual(Object.keys(metadata), [AIPOU_RECEIPT_META_KEY]);
+    assert.equal(projection.id, receiptId);
+    assert.equal(projection.uri, `aipou://receipts/${receiptId}`);
+    assert.match(String(projection.issuer), /^sha256:[0-9a-f]{64}$/);
+    assert.equal(projection.digest, `sha256:${"ab".repeat(32)}`);
+    assert.equal(projection.evidenceClass, "issuer_asserted");
+    assert.equal(projection.scheme, "aipou-receipt-v1");
+    assert.equal(projection.status, "local");
+    assert.equal("wallet" in projection, false);
+    assert.equal("reward" in projection, false);
+    assert.equal("claimStatus" in projection, false);
+});

package/dist/secure-file.d.ts

@@ -0,0 +1 @@
+export declare function restrictToCurrentUser(filePath: string): Promise<boolean>;

package/dist/secure-file.js

@@ -0,0 +1,21 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+// mode 0o600 is a no-op on NTFS, so Windows also needs an explicit ACL.
+// A false result is surfaced by onboarding; existing receipt collection keeps
+// its historical best-effort behavior.
+export async function restrictToCurrentUser(filePath) {
+    if (process.platform !== "win32")
+        return true;
+    const user = process.env.USERNAME;
+    if (!user)
+        return false;
+    const principal = process.env.USERDOMAIN ? `${process.env.USERDOMAIN}\\${user}` : user;
+    try {
+        await execFileAsync("icacls", [filePath, "/inheritance:r", "/grant:r", `${principal}:F`]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aipou-mcp-server",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "mcpName": "io.github.0xddneto/ai-proof-of-us",
   "description": "MCP server for private, signed AI task receipts and optional validated AIPOU claims.",
   "author": "0xddneto",
@@ -29,14 +29,15 @@
   "files": [
     "dist",
     "README.md",
+    "NOTICE",
     "server.json"
   ],
   "bin": {
     "aipou-mcp": "dist/index.js"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test dist/protocol.test.js dist/rewards.test.js dist/canonical.test.js dist/demo.test.js dist/version.test.js",
+    "build": "tsc -p tsconfig.json && esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/index.js --external:dotenv --external:dotenv/* --external:ethers --external:merkletreejs --external:zod --external:zod/*",
+    "test": "npm run build && node --test dist/protocol.test.js dist/rewards.test.js dist/canonical.test.js dist/demo.test.js dist/doctor.test.js dist/init.test.js dist/receipt-metadata.test.js dist/version.test.js",
     "pack:check": "npm test && npm pack --dry-run",
     "demo": "npm run build && node dist/index.js --demo",
     "dev": "tsx src/index.ts",
@@ -50,14 +51,15 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.13.0",
     "dotenv": "^16.6.1",
     "ethers": "^6.17.0",
     "merkletreejs": "^0.6.0",
-    "zod": "^3.23.8"
+    "zod": "^3.25.0"
   },
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
     "@types/node": "^22.5.4",
+    "esbuild": "0.28.1",
     "tsx": "^4.19.0",
     "typescript": "^5.5.4"
   }

package/server.json

@@ -9,23 +9,30 @@
     "source": "github",
     "subfolder": "mcp-server"
   },
-  "version": "0.3.1",
+  "version": "0.5.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "aipou-mcp-server",
-      "version": "0.3.1",
+      "version": "0.5.0",
       "transport": {
         "type": "stdio"
       },
       "environmentVariables": [
         {
-          "description": "Private key for a new dedicated farming wallet. Never use a primary wallet.",
-          "isRequired": true,
+          "description": "Optional inline private key for a dedicated farming wallet. Prefer AIPOU_AGENT_KEY_FILE and never use a primary wallet.",
+          "isRequired": false,
           "format": "string",
           "isSecret": true,
           "name": "AIPOU_AGENT_PRIVATE_KEY"
         },
+        {
+          "description": "Path to the protected dedicated-wallet key created by aipou-mcp --init.",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false,
+          "name": "AIPOU_AGENT_KEY_FILE"
+        },
         {
           "description": "AIPOU token contract address on the configured network.",
           "isRequired": true,