aipou-mcp-server 0.3.0 → 0.4.0

package/README.md

@@ -6,21 +6,31 @@ It does not detect hidden AI use, prove task quality, replace payment rails, or
 
 ## Fast Local Adoption Test
 
-From a source checkout, create and verify one disposable local receipt:
+Create and verify one disposable local receipt without cloning anything:
 
 ```bash
-npm install
-npm run demo -w mcp-server
+npx -y aipou-mcp-server --demo
 ```
 
 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.
 
-After the next npm release, the same check will run without cloning:
+To create a persistent dedicated wallet without printing its private key:
 
 ```bash
-npx -y aipou-mcp-server --demo
+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.
+
+From a source checkout, the same check runs with:
+
+```bash
+npm install
+npm run demo -w mcp-server
 ```
 
 For a complete framework lifecycle example, continue with the adapter below.
@@ -69,6 +79,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/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);
 }

package/dist/index.js

@@ -8,16 +8,18 @@ import { collectorFingerprint, getCollectorPublicKey } from "./collector.js";
 import { aipouClaimsAbi, aipouTokenAbi, getTokenContractConfig } from "./contract.js";
 import { runLocalReceiptDemo } from "./demo.js";
 import { agentWallet } from "./identity.js";
+import { describeExistingIdentity, initializePersistentIdentity } from "./init.js";
 import { beginTask, completeTask, exportReceipts } from "./receipts.js";
 import { estimateReward } from "./rewards.js";
 import { getAipouStatus } from "./status.js";
+import { getPackageVersion } from "./version.js";
 const bytes32 = z.string().regex(/^0x[a-fA-F0-9]{64}$/);
 const usageCounts = {
     inputTokens: z.number().int().min(0).max(10_000_000),
     outputTokens: z.number().int().min(0).max(10_000_000),
     durationSeconds: z.number().int().min(0).max(86_400)
 };
-const server = new McpServer({ name: "aipou-mcp", version: "0.2.2" }, {
+const server = new McpServer({ name: "aipou-mcp", version: await getPackageVersion() }, {
     instructions: "For meaningful AI tasks, call begin_ai_task before work and complete_ai_task after work using hashes, never raw prompts or outputs. " +
         "Use the dedicated farming identity only. Never reveal private keys or local collector state. " +
         "Call settle_all_ai_rewards after a broad user request such as 'claim my AIPOU' or 'settle all pending AIPOU'. " +
@@ -95,19 +97,51 @@ server.tool("settle_all_ai_rewards", "After an explicit broad claim request, set
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 });
 const cliArguments = new Set(process.argv.slice(2));
+function cliValue(name) {
+    const args = process.argv.slice(2);
+    const inline = args.find((argument) => argument.startsWith(`${name}=`));
+    if (inline)
+        return inline.slice(name.length + 1);
+    const index = args.indexOf(name);
+    if (index === -1)
+        return undefined;
+    const value = args[index + 1];
+    return value && !value.startsWith("--") ? value : undefined;
+}
 if (cliArguments.has("--demo")) {
     console.log(JSON.stringify(await runLocalReceiptDemo(), null, 2));
 }
+else if (cliArguments.has("--init")) {
+    const dataDir = cliValue("--data-dir");
+    try {
+        console.log(JSON.stringify(await initializePersistentIdentity(dataDir), null, 2));
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            console.log(JSON.stringify(await describeExistingIdentity(dataDir), null, 2));
+        }
+        else {
+            console.error(`aipou-mcp --init failed: ${error instanceof Error ? error.message : String(error)}`);
+            process.exitCode = 1;
+        }
+    }
+}
 else if (cliArguments.has("--help") || cliArguments.has("-h")) {
     console.log(`AIPOU MCP Server
 
 Usage:
   aipou-mcp                 Start the MCP stdio server
   aipou-mcp --demo          Create and verify one disposable local receipt
+  aipou-mcp --init          Create a protected persistent farming identity
+  aipou-mcp --init --data-dir <path>
+                            Initialize in a specific directory
   aipou-mcp --help          Show this help
 
 The demo needs no wallet, funds, network, or configuration. Its temporary
-wallet, collector key, and receipt state are removed before the command exits.`);
+wallet, collector key, and receipt state are removed before the command exits.
+Init writes a new dedicated-wallet key with restricted access and never prints
+the secret. Re-running init reports the existing identity instead of
+overwriting it.`);
 }
 else {
     const transport = new StdioServerTransport();

package/dist/init.d.ts

@@ -0,0 +1,30 @@
+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";
+const TOKEN_ADDRESS = "0x55f0Cc5e51A1284D20337d6cbb18938C8A1ABCbB";
+const 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: TOKEN_ADDRESS,
+                        AIPOU_CLAIMS_ADDRESS: 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/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/dist/version.d.ts

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

package/dist/version.js

@@ -0,0 +1,10 @@
+import { readFile } from "node:fs/promises";
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+export async function getPackageVersion() {
+    const packageUrl = new URL("../package.json", import.meta.url);
+    const metadata = JSON.parse(await readFile(packageUrl, "utf8"));
+    if (typeof metadata.version !== "string" || !SEMVER.test(metadata.version)) {
+        throw new Error("mcp-server/package.json must contain a valid semantic version");
+    }
+    return metadata.version;
+}

package/dist/version.test.d.ts

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

package/dist/version.test.js

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { getPackageVersion } from "./version.js";
+test("MCP handshake version comes from the published package metadata", async () => {
+    const metadata = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+    assert.equal(await getPackageVersion(), metadata.version);
+});
+test("MCP initialization advertises the published package version", async () => {
+    const transport = new StdioClientTransport({
+        command: process.execPath,
+        args: [fileURLToPath(new URL("./index.js", import.meta.url))],
+        stderr: "pipe"
+    });
+    const client = new Client({ name: "aipou-version-test", version: "1.0.0" });
+    await client.connect(transport);
+    try {
+        assert.equal(client.getServerVersion()?.version, await getPackageVersion());
+    }
+    finally {
+        await transport.close();
+    }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aipou-mcp-server",
-  "version": "0.3.0",
+  "version": "0.4.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",
@@ -36,7 +36,7 @@
   },
   "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",
+    "test": "npm run build && node --test dist/protocol.test.js dist/rewards.test.js dist/canonical.test.js dist/demo.test.js dist/init.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",

package/server.json

@@ -9,23 +9,30 @@
     "source": "github",
     "subfolder": "mcp-server"
   },
-  "version": "0.3.0",
+  "version": "0.4.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "aipou-mcp-server",
-      "version": "0.3.0",
+      "version": "0.4.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,