aipou-mcp-server 0.4.0 → 0.6.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

@@ -1,5 +1,11 @@
 # AIPOU MCP Server
 
+Version 0.6.0: see the [release notes](https://github.com/0xddneto/AI-Proof-of-Us/blob/main/CHANGELOG.md) and [independent pilot guide](https://github.com/0xddneto/AI-Proof-of-Us/blob/main/docs/independent-pilot.md).
+
+`--init` uses the current absolute entrypoint from a source checkout and pins this package version when installed from npm. Windows `--doctor` marks uninspected ACLs as `not_checked`. `complete_ai_task` accepts optional `tokenUsageMeasurement` (`measured`, `unmeasured`, `unspecified`); unmeasured counts must be zero. Legacy receipts remain verifiable. Invalid verification results expose only an unverified `claimedWorkReceiptId`, with `workReceiptId: null`.
+
+After a lost completion response, recover the persisted receipt with `export_ai_receipts` by nonce. `--feedback` prints optional local aggregate counts without sending anything. See [claim recovery and operating limits](https://github.com/0xddneto/AI-Proof-of-Us/blob/main/docs/settlement-recovery.md) before validator operation.
+
 `aipou-mcp-server` records private, signed receipts for authorized AI tasks. It supports local receipt collection, reward status checks, and optional claims for validated work on Base.
 
 It does not detect hidden AI use, prove task quality, replace payment rails, or require raw prompts and outputs to leave the user's machine.
@@ -26,6 +32,17 @@ 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
@@ -96,6 +113,7 @@ Publication details: [docs/npm-publication.md](https://github.com/0xddneto/AI-Pr
 - [Local Receipt Mode](https://github.com/0xddneto/AI-Proof-of-Us/tree/main/examples/local-receipt-mode)
 - [Lifecycle Adapter Example](https://github.com/0xddneto/AI-Proof-of-Us/tree/main/examples/lifecycle-adapter)
 - [Evidence Boundaries](https://github.com/0xddneto/AI-Proof-of-Us/blob/main/docs/evidence-boundaries.md)
+- [Flop and Technocore Interoperability](https://github.com/0xddneto/AI-Proof-of-Us/blob/main/docs/flop-technocore-interoperability.md)
 - [Claim Validation Policy](https://github.com/0xddneto/AI-Proof-of-Us/blob/main/docs/claim-validation-policy.md)
 - [Tokenomics](https://github.com/0xddneto/AI-Proof-of-Us/blob/main/docs/tokenomics.md)
 - [Security Policy](https://github.com/0xddneto/AI-Proof-of-Us/blob/main/SECURITY.md)

package/dist/bounded-input.d.ts

@@ -0,0 +1,8 @@
+import { Transform, type TransformCallback } from "node:stream";
+/** Bound each JSON-RPC line before the SDK parses or validates it. */
+export declare class BoundedStdioInput extends Transform {
+    private readonly maxLineBytes;
+    private bytes;
+    constructor(maxLineBytes?: number);
+    _transform(chunk: Buffer, _encoding: BufferEncoding, callback: TransformCallback): void;
+}

package/dist/bounded-input.js

@@ -0,0 +1,21 @@
+import { Transform } from "node:stream";
+/** Bound each JSON-RPC line before the SDK parses or validates it. */
+export class BoundedStdioInput extends Transform {
+    maxLineBytes;
+    bytes = 0;
+    constructor(maxLineBytes = 1024 * 1024) {
+        super();
+        this.maxLineBytes = maxLineBytes;
+    }
+    _transform(chunk, _encoding, callback) {
+        for (const byte of chunk) {
+            if (byte === 10)
+                this.bytes = 0;
+            else if (++this.bytes > this.maxLineBytes) {
+                callback(new Error("AIPOU_INPUT_TOO_LARGE: JSON-RPC line exceeds 1 MiB"));
+                return;
+            }
+        }
+        callback(null, chunk);
+    }
+}

package/dist/bounded-input.test.d.ts

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

package/dist/bounded-input.test.js

@@ -0,0 +1,24 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { BoundedStdioInput } from "./bounded-input.js";
+test("stdio accepts a bounded fragmented line and resets its byte count at newline", async () => {
+    const stream = new BoundedStdioInput(6);
+    const chunks = [];
+    stream.on("data", (b) => chunks.push(b));
+    stream.write(Buffer.from("123"));
+    stream.write(Buffer.from("456\n123456\n"));
+    stream.end();
+    await new Promise((resolve, reject) => {
+        stream.on("end", resolve);
+        stream.on("error", reject);
+    });
+    assert.equal(Buffer.concat(chunks).toString(), "123456\n123456\n");
+});
+test("oversized fragmented JSON is rejected before the offending chunk is parsed", async () => {
+    const stream = new BoundedStdioInput(4);
+    const error = new Promise((resolve) => stream.once("error", resolve));
+    stream.resume();
+    stream.write(Buffer.from("123"));
+    stream.end(Buffer.from("45"));
+    assert.match((await error).message, /INPUT_TOO_LARGE/);
+});

package/dist/claims.js

@@ -1,18 +1,25 @@
 import { MerkleTree } from "merkletreejs";
-import { AbiCoder, Contract, JsonRpcProvider, Wallet, concat, getAddress, getBytes, keccak256, parseUnits } from "ethers";
-import { readFile } from "node:fs/promises";
+import { AbiCoder, Contract, JsonRpcProvider, Transaction, Wallet, concat, getAddress, getBytes, keccak256, parseUnits, } from "ethers";
+import { mkdir, readFile, rm } from "node:fs/promises";
 import path from "node:path";
 import { collectorFingerprint, verifyCollectorPayload } from "./collector.js";
 import { verifyTaskAuthorization } from "./identity.js";
-import { DAY_MS, filterEligibleReceipts, settlementPolicyFromEnv } from "./policy.js";
+import { DAY_MS, filterEligibleReceipts, settlementPolicyFromEnv, } from "./policy.js";
 import { deriveTrustTier } from "./providers.js";
-import { markBatchSettled, settledReceiptsSince, unsettledReceipts } from "./store.js";
+import { exportStoredReceipts, markBatchSettled, settledReceiptsSince, unsettledReceipts, } from "./store.js";
+import { withFileLock } from "./lock.js";
+import { readOptionalJson, writePrivateJson } from "./private-json.js";
+import { executeSettlementPlan, } from "./settlement-runner.js";
+import { createSettlementDriver } from "./settlement-driver.js";
+import { canonicalJson } from "./canonical.js";
+import { verifyAipouReceipt } from "./receipt-verifier.js";
 const claimsAbi = [
     "function token() view returns (address)",
     "function validator() view returns (address)",
     "function approvedRoots(bytes32 root) view returns (bool)",
+    "function claimedReceipts(bytes32 receiptId) view returns (bool)",
     "function publishRoot(bytes32 root)",
-    "function claimBatch(bytes32 root, address[] accounts, uint256[] amounts, bytes32[] receiptIds, bytes32[][] proofs)"
+    "function claimBatch(bytes32 root, address[] accounts, uint256[] amounts, bytes32[] receiptIds, bytes32[][] proofs)",
 ];
 const tokenAbi = ["function emissionController() view returns (address)"];
 function claimsAddress() {
@@ -51,6 +58,8 @@ async function trustedCollectorFingerprints() {
     return new Set(content.fingerprints);
 }
 async function verifyReceipt(receipt, trustedCollectors) {
+    if (!verifyAipouReceipt(receipt).valid)
+        throw new Error("Invalid receipt integrity or signature; settlement stopped before submission");
     const fingerprint = collectorFingerprint(receipt.collectorPublicKey);
     if (!trustedCollectors.has(fingerprint)) {
         throw new Error(`Untrusted collector ${fingerprint} for ${receipt.receiptId}`);
@@ -70,7 +79,7 @@ async function verifyReceipt(receipt, trustedCollectors) {
         chainId: receipt.authorizationChainId,
         verifyingContract: receipt.authorizationContract,
         walletAuthorization: receipt.walletAuthorization,
-        completedAt: receipt.recordedAt
+        completedAt: receipt.recordedAt,
     };
     if (!verifyTaskAuthorization(session))
         throw new Error(`Invalid wallet authorization for ${receipt.receiptId}`);
@@ -80,23 +89,61 @@ async function verifyReceipt(receipt, trustedCollectors) {
         outputTokens: receipt.outputTokens,
         durationSeconds: receipt.durationSeconds,
         outputHash: receipt.outputHash,
-        providerEvidence: receipt.providerEvidence
+        tokenUsageMeasurement: receipt.tokenUsageMeasurement,
+        providerEvidence: receipt.providerEvidence,
     }, receipt.providerEvidence);
     if (derivedTier !== receipt.trustTier)
         throw new Error(`Invalid trust tier for ${receipt.receiptId}`);
 }
 export async function settleRewards(maxReceipts = 25) {
+    if (!Number.isInteger(maxReceipts) || maxReceipts < 1 || maxReceipts > 100)
+        throw new Error("Batch size must be 1 through 100");
+    const directory = path.resolve(process.env.AIPOU_DATA_DIR || ".aipou");
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    try {
+        return await withFileLock(path.join(directory, "settlement.lock"), () => settleRewardsLocked(maxReceipts, directory));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "";
+        if (message.startsWith("SETTLEMENT_") ||
+            message === "There are no unsettled receipts" ||
+            message.startsWith("No receipts pass the settlement policy"))
+            throw error;
+        throw new Error("SETTLEMENT_FAILED: inspect local configuration and saved settlement state before retrying; private RPC and transaction details are withheld.");
+    }
+}
+async function settleRewardsLocked(maxReceipts, directory) {
+    const journalPath = path.join(directory, "settlement-pending.json");
+    const pending = await readOptionalJson(journalPath);
     const candidates = await unsettledReceipts(Number.MAX_SAFE_INTEGER);
-    if (candidates.length === 0)
+    if (candidates.length === 0 && !pending)
         throw new Error("There are no unsettled receipts");
     const policy = settlementPolicyFromEnv();
     const recentlySettled = await settledReceiptsSince(Date.now() - DAY_MS);
     const { eligible, skipped } = filterEligibleReceipts(candidates, recentlySettled, policy);
-    if (eligible.length === 0) {
-        const reasons = skipped.map((item) => `${item.receiptId.slice(0, 10)}…: ${item.reason}`).join("; ");
+    if (eligible.length === 0 && !pending) {
+        const reasons = skipped
+            .map((item) => `${item.receiptId.slice(0, 10)}…: ${item.reason}`)
+            .join("; ");
         throw new Error(`No receipts pass the settlement policy. Skipped: ${reasons}`);
     }
-    const receipts = eligible.slice(0, maxReceipts);
+    let receipts = eligible.slice(0, maxReceipts);
+    if (pending) {
+        if (pending.version !== 1 ||
+            pending.chainId !== 8453 ||
+            !Array.isArray(pending.receiptIds) ||
+            pending.receiptIds.length < 1 ||
+            pending.receiptIds.length > 100) {
+            throw new Error("SETTLEMENT_JOURNAL_INVALID: invalid saved batch");
+        }
+        const stored = await exportStoredReceipts();
+        receipts = pending.receiptIds.map((id) => {
+            const receipt = stored.find((item) => item.receiptId === id);
+            if (!receipt)
+                throw new Error("SETTLEMENT_JOURNAL_INVALID: saved receipt is missing");
+            return receipt;
+        });
+    }
     const trustedCollectors = await trustedCollectorFingerprints();
     for (const receipt of receipts)
         await verifyReceipt(receipt, trustedCollectors);
@@ -115,6 +162,8 @@ export async function settleRewards(maxReceipts = 25) {
     const proofs = leaves.map((leaf) => tree.getHexProof(leaf));
     const signer = await validatorWallet();
     const address = claimsAddress();
+    if ((await signer.provider.getNetwork()).chainId !== 8453n)
+        throw new Error("Settlement requires Base mainnet (8453)");
     const claims = new Contract(address, claimsAbi, signer);
     const configuredValidator = getAddress(await claims.validator());
     if (configuredValidator !== signer.address) {
@@ -125,28 +174,59 @@ export async function settleRewards(maxReceipts = 25) {
     if (getAddress(await token.emissionController()) !== address) {
         throw new Error("AIPOUClaims is not the token emission controller");
     }
-    const publish = await claims.publishRoot(root);
-    const publishReceipt = await publish.wait();
-    let rootApproved = false;
-    for (let attempt = 0; attempt < 10 && !rootApproved; attempt += 1) {
-        rootApproved = await claims.approvedRoots(root);
-        if (!rootApproved)
-            await new Promise((resolve) => setTimeout(resolve, 3_000));
+    const expected = {
+        version: 1,
+        chainId: 8453,
+        contract: address,
+        root,
+        accounts,
+        amounts: amounts.map(String),
+        receiptIds,
+        proofs,
+    };
+    if (pending) {
+        const { publish: _publish, claim: _claim, ...saved } = pending;
+        if (canonicalJson(saved) !== canonicalJson(expected))
+            throw new Error("SETTLEMENT_JOURNAL_INVALID: batch does not match verified receipts and configured contract");
+    }
+    const plan = pending ?? expected;
+    for (const kind of ["publish", "claim"]) {
+        const saved = plan[kind];
+        if (!saved)
+            continue;
+        const transaction = Transaction.from(saved.raw);
+        const expectedData = kind === "publish"
+            ? claims.interface.encodeFunctionData("publishRoot", [root])
+            : claims.interface.encodeFunctionData("claimBatch", [
+                root,
+                accounts,
+                amounts,
+                receiptIds,
+                proofs,
+            ]);
+        if (transaction.hash !== saved.hash ||
+            transaction.from !== signer.address ||
+            transaction.chainId !== 8453n ||
+            transaction.to?.toLowerCase() !== address.toLowerCase() ||
+            transaction.value !== 0n ||
+            transaction.data !== expectedData) {
+            throw new Error("SETTLEMENT_JOURNAL_INVALID: saved transaction does not match the verified batch");
+        }
     }
-    if (!rootApproved)
-        throw new Error("Published Merkle root was not visible through the RPC after 30 seconds");
-    const claim = await claims.claimBatch(root, accounts, amounts, receiptIds, proofs);
-    const claimReceipt = await claim.wait();
-    if (!publishReceipt || !claimReceipt)
-        throw new Error("Settlement transaction receipt is unavailable");
+    const persist = (value) => writePrivateJson(journalPath, value);
+    await persist(plan);
+    const transactions = await executeSettlementPlan(plan, createSettlementDriver(signer, address), persist);
+    const confirmations = await Promise.all(receiptIds.map((id) => claims.claimedReceipts(id)));
+    if (!confirmations.every(Boolean))
+        throw new Error("SETTLEMENT_CLAIMS_UNCONFIRMED: receipt flags are not visible; journal retained for reconciliation");
     const batch = {
         root,
         receiptIds,
-        publishTransaction: publishReceipt.hash,
-        claimTransaction: claimReceipt.hash,
-        settledAt: new Date().toISOString()
+        ...transactions,
+        settledAt: new Date().toISOString(),
     };
     await markBatchSettled(batch);
+    await rm(journalPath, { force: true });
     return { ...batch, skippedReceipts: skipped };
 }
 export async function settleAllRewards(batchSize = 100, maxBatches = 20) {
@@ -162,7 +242,12 @@ export async function settleAllRewards(batchSize = 100, maxBatches = 20) {
             }
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            // Never return signed raw transactions, RPC credentials or local collector paths.
+            const raw = error instanceof Error ? error.message : "Settlement failed";
+            const message = raw.startsWith("SETTLEMENT_") ||
+                raw === "There are no unsettled receipts"
+                ? raw.slice(0, 400)
+                : "SETTLEMENT_FAILED: inspect local diagnostics and saved settlement state before retrying; no private transaction payload is returned.";
             if (message === "There are no unsettled receipts")
                 break;
             stoppedReason = message;
@@ -172,7 +257,8 @@ export async function settleAllRewards(batchSize = 100, maxBatches = 20) {
     if (!stoppedReason && batches.length === maxBatches) {
         stoppedReason = `Stopped after maxBatches=${maxBatches}; run settle_all_ai_rewards again for any remaining receipts`;
     }
-    const pendingReceiptCount = (await unsettledReceipts(Number.MAX_SAFE_INTEGER)).length;
+    const pendingReceiptCount = (await unsettledReceipts(Number.MAX_SAFE_INTEGER))
+        .length;
     const skippedReceipts = [...skippedByReceiptId.values()];
     return {
         batches,
@@ -180,9 +266,11 @@ export async function settleAllRewards(batchSize = 100, maxBatches = 20) {
         settledReceiptCount: batches.reduce((total, batch) => total + batch.receiptIds.length, 0),
         skippedReceipts,
         pendingReceiptCount,
-        publishTransactions: batches.map((batch) => batch.publishTransaction),
+        publishTransactions: batches
+            .map((batch) => batch.publishTransaction)
+            .filter(Boolean),
         claimTransactions: batches.map((batch) => batch.claimTransaction),
         stoppedReason,
-        settledAt: new Date().toISOString()
+        settledAt: new Date().toISOString(),
     };
 }

package/dist/doctor.d.ts

@@ -0,0 +1,32 @@
+type CheckStatus = "pass" | "fail" | "warning" | "not_checked";
+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 = { status: "not_checked", detail: "Windows ACLs are not inspected by this read-only doctor. This is not a detected permission failure; init reports whether it successfully applied access restrictions." };
+            }
+            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,164 @@
+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");
+        if (process.platform === "win32")
+            assert.equal(result.checks.keyPermissions.status, "not_checked");
+        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 });
+    }
+});