aipou-mcp-server 0.3.1 → 0.5.0

package/NOTICE

@@ -0,0 +1,8 @@
+AI Proof of Us (AIPOU) MCP Server
+Copyright (c) 2026 0xddneto and AI Proof of Us contributors
+
+This package bundles the stdio runtime from the Model Context Protocol
+TypeScript SDK, Copyright (c) 2024 Anthropic, PBC, under the MIT License.
+Source: https://github.com/modelcontextprotocol/typescript-sdk
+
+The software and bundled dependency are distributed under the MIT License.

package/README.md

@@ -16,6 +16,27 @@ The command needs no wallet setup, funds, network, or claims. It prints a
 framework-ready `workReceiptId` object and deletes its ephemeral wallet,
 collector key, and receipt state before exiting.
 
+To create a persistent dedicated wallet without printing its private key:
+
+```bash
+npx -y aipou-mcp-server --init
+```
+
+The command writes a protected `agent-wallet.key` and prints an MCP
+configuration using `AIPOU_AGENT_KEY_FILE`. Re-running it reports the existing
+identity instead of overwriting the key.
+
+Verify the persistent setup without writing files, contacting an RPC, moving
+funds, or submitting a claim:
+
+```bash
+npx -y aipou-mcp-server --doctor
+```
+
+The diagnostic returns structured checks for Node.js, storage, identity,
+contract addresses, and chain. It prints only the public wallet address, never
+the private key.
+
 From a source checkout, the same check runs with:
 
 ```bash
@@ -69,6 +90,10 @@ AIPOU_CONTRACT_ADDRESS=0x55f0Cc5e51A1284D20337d6cbb18938C8A1ABCbB
 AIPOU_CLAIMS_ADDRESS=0x4ca4C98fB784D20EdC8E2A7F531dAab4c6e53058
 ```
 
+`AIPOU_AGENT_KEY_FILE=/protected/path/agent-wallet.key` is the recommended
+alternative to the inline private-key variable. One of the two identity options
+is required for persistent receipt collection.
+
 Use a new dedicated farming wallet, never a primary wallet. Do not commit the private key. Status checks can show already claimed and pending AIPOU without moving funds. Optional claims and settlement occur only after an explicit user request.
 
 Do not configure `AIPOU_VALIDATOR_PRIVATE_KEY` on a user installation. That key is only for the separate protocol validator service. The local Ed25519 collector key and receipt metadata are stored unencrypted under `AIPOU_DATA_DIR`; restrict that directory with operating-system permissions and use encrypted backups.

package/dist/collector.js

@@ -1,27 +1,8 @@
-import { execFile } from "node:child_process";
 import { createHash, createPublicKey, generateKeyPairSync, sign, verify } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { promisify } from "node:util";
 import { canonicalJson } from "./canonical.js";
-const execFileAsync = promisify(execFile);
-// mode 0o600 is a no-op on NTFS, so on Windows the private key would keep the
-// permissive inherited ACL. Strip inheritance and grant only the current user.
-// Best-effort: an ACL failure must not block receipt collection.
-async function restrictToCurrentUser(filePath) {
-    if (process.platform !== "win32")
-        return;
-    const user = process.env.USERNAME;
-    if (!user)
-        return;
-    const principal = process.env.USERDOMAIN ? `${process.env.USERDOMAIN}\\${user}` : user;
-    try {
-        await execFileAsync("icacls", [filePath, "/inheritance:r", "/grant:r", `${principal}:F`]);
-    }
-    catch {
-        // keep the inherited ACL rather than failing key creation
-    }
-}
+import { restrictToCurrentUser } from "./secure-file.js";
 function dataDir() {
     return path.resolve(process.env.AIPOU_DATA_DIR || ".aipou");
 }

package/dist/doctor.d.ts

@@ -0,0 +1,32 @@
+type CheckStatus = "pass" | "fail" | "warning";
+export interface DoctorCheck {
+    status: CheckStatus;
+    detail: string;
+}
+export interface InstallationDoctorResult {
+    mode: "installation_doctor";
+    ready: boolean;
+    version: string;
+    wallet: string | null;
+    dataDir: string;
+    keyFile: string | null;
+    keySource: "key_file" | "inline_private_key" | "missing";
+    checks: {
+        node: DoctorCheck;
+        dataDirectory: DoctorCheck;
+        identity: DoctorCheck;
+        keyPermissions: DoctorCheck;
+        tokenAddress: DoctorCheck;
+        claimsAddress: DoctorCheck;
+        chain: DoctorCheck;
+    };
+    safety: {
+        privateKeyPrinted: false;
+        filesWritten: false;
+        networkRequestsMade: false;
+        fundsMoved: false;
+        claimSubmitted: false;
+    };
+}
+export declare function runInstallationDoctor(dataDirInput?: string): Promise<InstallationDoctorResult>;
+export {};

package/dist/doctor.js

@@ -0,0 +1,112 @@
+import { constants } from "node:fs";
+import { access, readFile, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Wallet, isAddress } from "ethers";
+import { AIPOU_CLAIMS_ADDRESS, AIPOU_TOKEN_ADDRESS } from "./init.js";
+import { getPackageVersion } from "./version.js";
+function pass(detail) {
+    return { status: "pass", detail };
+}
+function fail(detail) {
+    return { status: "fail", detail };
+}
+function warning(detail) {
+    return { status: "warning", detail };
+}
+export async function runInstallationDoctor(dataDirInput) {
+    const dataDir = path.resolve(dataDirInput || process.env.AIPOU_DATA_DIR || path.join(os.homedir(), ".aipou"));
+    // An explicit directory is an operator choice and must not be shadowed by
+    // inherited client or dotenv identity variables.
+    const configuredKeyFile = dataDirInput ? undefined : process.env.AIPOU_AGENT_KEY_FILE?.trim();
+    const inlinePrivateKey = dataDirInput ? undefined : process.env.AIPOU_AGENT_PRIVATE_KEY?.trim();
+    const keyFile = inlinePrivateKey ? null : path.resolve(configuredKeyFile || path.join(dataDir, "agent-wallet.key"));
+    const nodeMajor = Number(process.versions.node.split(".")[0]);
+    const tokenAddress = process.env.AIPOU_CONTRACT_ADDRESS?.trim() || AIPOU_TOKEN_ADDRESS;
+    const claimsAddress = process.env.AIPOU_CLAIMS_ADDRESS?.trim() || AIPOU_CLAIMS_ADDRESS;
+    const chainId = Number(process.env.AIPOU_CHAIN_ID || 8453);
+    let dataDirectory = pass("Receipt directory is readable and writable.");
+    try {
+        await access(dataDir, constants.R_OK | constants.W_OK);
+    }
+    catch {
+        dataDirectory = fail(`Receipt directory is unavailable (${dataDir}); run aipou-mcp --init first.`);
+    }
+    let wallet = null;
+    let identity;
+    let keySource;
+    try {
+        const privateKey = inlinePrivateKey || (keyFile ? (await readFile(keyFile, "utf8")).trim() : "");
+        if (!privateKey)
+            throw new Error("missing");
+        wallet = new Wallet(privateKey).address;
+        keySource = inlinePrivateKey ? "inline_private_key" : "key_file";
+        identity = inlinePrivateKey
+            ? warning("Dedicated wallet key is valid, but a protected key file is safer than an inline environment variable.")
+            : pass("Dedicated-wallet key file is readable and valid; its secret was not returned.");
+    }
+    catch {
+        keySource = "missing";
+        identity = fail(`Dedicated wallet key is missing or invalid${keyFile ? ` (${keyFile})` : ""}; run aipou-mcp --init.`);
+    }
+    let keyPermissions;
+    if (inlinePrivateKey) {
+        keyPermissions = warning("Inline private-key permissions cannot be checked; use the key file created by aipou-mcp --init.");
+    }
+    else if (!keyFile) {
+        keyPermissions = fail("No dedicated-wallet key file is configured.");
+    }
+    else {
+        try {
+            const keyStat = await stat(keyFile);
+            if (process.platform === "win32") {
+                keyPermissions = warning("Key file exists; Windows ACLs were not changed or re-applied by this read-only diagnostic.");
+            }
+            else if ((keyStat.mode & 0o077) === 0) {
+                keyPermissions = pass("Key file has no group or other permission bits.");
+            }
+            else {
+                keyPermissions = fail("Key file is accessible by group or other users; restrict it to mode 0600.");
+            }
+        }
+        catch {
+            keyPermissions = fail(`Key file permissions could not be inspected (${keyFile}).`);
+        }
+    }
+    const checks = {
+        node: Number.isInteger(nodeMajor) && nodeMajor >= 20
+            ? pass(`Node.js ${process.versions.node} satisfies the required major version (20+).`)
+            : fail(`Node.js ${process.versions.node} is unsupported; install Node.js 20 or newer.`),
+        dataDirectory,
+        identity,
+        keyPermissions,
+        tokenAddress: isAddress(tokenAddress)
+            ? pass(`AIPOU token address is valid (${tokenAddress}).`)
+            : fail("AIPOU_CONTRACT_ADDRESS is not a valid EVM address."),
+        claimsAddress: isAddress(claimsAddress)
+            ? pass(`AIPOU claims address is valid (${claimsAddress}).`)
+            : fail("AIPOU_CLAIMS_ADDRESS is not a valid EVM address."),
+        chain: Number.isSafeInteger(chainId) && chainId > 0
+            ? (chainId === 8453
+                ? pass("Chain ID is Base Mainnet (8453).")
+                : warning(`Chain ID ${chainId} is configured instead of Base Mainnet (8453).`))
+            : fail("AIPOU_CHAIN_ID must be a positive integer.")
+    };
+    return {
+        mode: "installation_doctor",
+        ready: Object.values(checks).every((check) => check.status !== "fail"),
+        version: await getPackageVersion(),
+        wallet,
+        dataDir,
+        keyFile,
+        keySource,
+        checks,
+        safety: {
+            privateKeyPrinted: false,
+            filesWritten: false,
+            networkRequestsMade: false,
+            fundsMoved: false,
+            claimSubmitted: false
+        }
+    };
+}

package/dist/doctor.test.d.ts

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

package/dist/doctor.test.js

@@ -0,0 +1,162 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { access, 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 { Wallet } from "ethers";
+import { runInstallationDoctor } from "./doctor.js";
+import { initializePersistentIdentity } from "./init.js";
+const execFileAsync = promisify(execFile);
+test("installation doctor validates init output without exposing or changing the key", async () => {
+    const dataDir = await mkdtemp(path.join(os.tmpdir(), "aipou-doctor-test-"));
+    const previousInlineKey = process.env.AIPOU_AGENT_PRIVATE_KEY;
+    const previousKeyFile = process.env.AIPOU_AGENT_KEY_FILE;
+    try {
+        delete process.env.AIPOU_AGENT_PRIVATE_KEY;
+        delete process.env.AIPOU_AGENT_KEY_FILE;
+        const initialized = await initializePersistentIdentity(dataDir);
+        const privateKeyBefore = await readFile(initialized.keyFile, "utf8");
+        const result = await runInstallationDoctor(dataDir);
+        const privateKeyAfter = await readFile(initialized.keyFile, "utf8");
+        assert.equal(result.ready, true);
+        assert.equal(result.wallet, initialized.wallet);
+        assert.equal(result.keySource, "key_file");
+        assert.equal(result.version.length > 0, true);
+        assert.equal(Object.values(result.checks).every((check) => check.status !== "fail"), true);
+        assert.equal(privateKeyAfter, privateKeyBefore);
+        assert.equal(JSON.stringify(result).includes(privateKeyBefore.trim()), false);
+        assert.deepEqual(result.safety, {
+            privateKeyPrinted: false,
+            filesWritten: false,
+            networkRequestsMade: false,
+            fundsMoved: false,
+            claimSubmitted: false
+        });
+    }
+    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("installation doctor fails closed without creating a missing directory", async () => {
+    const parent = await mkdtemp(path.join(os.tmpdir(), "aipou-doctor-missing-test-"));
+    const dataDir = path.join(parent, "missing");
+    const previousInlineKey = process.env.AIPOU_AGENT_PRIVATE_KEY;
+    const previousKeyFile = process.env.AIPOU_AGENT_KEY_FILE;
+    try {
+        delete process.env.AIPOU_AGENT_PRIVATE_KEY;
+        delete process.env.AIPOU_AGENT_KEY_FILE;
+        const result = await runInstallationDoctor(dataDir);
+        assert.equal(result.ready, false);
+        assert.equal(result.wallet, null);
+        assert.equal(result.keySource, "missing");
+        assert.equal(result.checks.dataDirectory.status, "fail");
+        assert.equal(result.checks.identity.status, "fail");
+        await assert.rejects(access(dataDir));
+    }
+    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(parent, { recursive: true, force: true });
+    }
+});
+test("installation doctor supports the legacy inline key without exposing it", async () => {
+    const dataDir = await mkdtemp(path.join(os.tmpdir(), "aipou-doctor-inline-test-"));
+    const previousInlineKey = process.env.AIPOU_AGENT_PRIVATE_KEY;
+    const previousKeyFile = process.env.AIPOU_AGENT_KEY_FILE;
+    const previousDataDir = process.env.AIPOU_DATA_DIR;
+    const wallet = Wallet.createRandom();
+    try {
+        process.env.AIPOU_AGENT_PRIVATE_KEY = wallet.privateKey;
+        process.env.AIPOU_DATA_DIR = dataDir;
+        delete process.env.AIPOU_AGENT_KEY_FILE;
+        const result = await runInstallationDoctor();
+        assert.equal(result.ready, true);
+        assert.equal(result.wallet, wallet.address);
+        assert.equal(result.keySource, "inline_private_key");
+        assert.equal(result.keyFile, null);
+        assert.equal(result.checks.identity.status, "warning");
+        assert.equal(result.checks.keyPermissions.status, "warning");
+        assert.equal(JSON.stringify(result).includes(wallet.privateKey), false);
+    }
+    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;
+        if (previousDataDir === undefined)
+            delete process.env.AIPOU_DATA_DIR;
+        else
+            process.env.AIPOU_DATA_DIR = previousDataDir;
+        await rm(dataDir, { recursive: true, force: true });
+    }
+});
+test("installation doctor rejects invalid addresses and chain IDs without throwing", async () => {
+    const dataDir = await mkdtemp(path.join(os.tmpdir(), "aipou-doctor-config-test-"));
+    const previousContract = process.env.AIPOU_CONTRACT_ADDRESS;
+    const previousChainId = process.env.AIPOU_CHAIN_ID;
+    try {
+        await initializePersistentIdentity(dataDir);
+        process.env.AIPOU_CONTRACT_ADDRESS = "not-an-address";
+        process.env.AIPOU_CHAIN_ID = "not-a-chain";
+        const result = await runInstallationDoctor(dataDir);
+        assert.equal(result.ready, false);
+        assert.equal(result.checks.tokenAddress.status, "fail");
+        assert.equal(result.checks.chain.status, "fail");
+    }
+    finally {
+        if (previousContract === undefined)
+            delete process.env.AIPOU_CONTRACT_ADDRESS;
+        else
+            process.env.AIPOU_CONTRACT_ADDRESS = previousContract;
+        if (previousChainId === undefined)
+            delete process.env.AIPOU_CHAIN_ID;
+        else
+            process.env.AIPOU_CHAIN_ID = previousChainId;
+        await rm(dataDir, { recursive: true, force: true });
+    }
+});
+test("CLI doctor reports a ready persistent identity without printing its secret", async () => {
+    const dataDir = await mkdtemp(path.join(os.tmpdir(), "aipou-doctor-cli-test-"));
+    const indexPath = fileURLToPath(new URL("./index.js", import.meta.url));
+    try {
+        const initialized = await initializePersistentIdentity(dataDir);
+        const privateKey = (await readFile(initialized.keyFile, "utf8")).trim();
+        const inheritedWallet = Wallet.createRandom();
+        const { stdout, stderr } = await execFileAsync(process.execPath, [indexPath, "--doctor", "--data-dir", dataDir], {
+            env: {
+                ...process.env,
+                AIPOU_AGENT_PRIVATE_KEY: inheritedWallet.privateKey,
+                AIPOU_AGENT_KEY_FILE: path.join(dataDir, "wrong-key-file")
+            }
+        });
+        const result = JSON.parse(stdout);
+        assert.equal(result.ready, true);
+        assert.equal(result.wallet, initialized.wallet);
+        assert.equal(stdout.includes(privateKey), false);
+        assert.equal(stderr, "");
+    }
+    finally {
+        await rm(dataDir, { recursive: true, force: true });
+    }
+});

package/dist/identity.js

@@ -1,4 +1,6 @@
 import { randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
 import { Wallet, getAddress, hexlify, isAddress, verifyTypedData } from "ethers";
 export const authorizationTypes = {
     TaskAuthorization: [
@@ -10,10 +12,22 @@ export const authorizationTypes = {
         { name: "issuedAt", type: "uint256" }
     ]
 };
+function readKeyFile(keyFile) {
+    try {
+        return readFileSync(path.resolve(keyFile), "utf8").trim();
+    }
+    catch {
+        throw new Error(`AIPOU_AGENT_KEY_FILE could not be read (${keyFile}); ` +
+            "run aipou-mcp --init to create a dedicated wallet key");
+    }
+}
 export function agentWallet() {
-    const privateKey = process.env.AIPOU_AGENT_PRIVATE_KEY;
+    const inlinePrivateKey = process.env.AIPOU_AGENT_PRIVATE_KEY?.trim();
+    const keyFile = process.env.AIPOU_AGENT_KEY_FILE;
+    const privateKey = inlinePrivateKey || (keyFile ? readKeyFile(keyFile) : undefined);
     if (!privateKey) {
-        throw new Error("AIPOU_AGENT_PRIVATE_KEY is required; use a dedicated farming wallet, never a primary wallet");
+        throw new Error("AIPOU_AGENT_PRIVATE_KEY or AIPOU_AGENT_KEY_FILE is required; " +
+            "run aipou-mcp --init to create a dedicated wallet, never use a primary wallet");
     }
     return new Wallet(privateKey);
 }