aipou-mcp-server 0.5.0 → 0.6.0

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.
@@ -107,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

@@ -1,4 +1,4 @@
-type CheckStatus = "pass" | "fail" | "warning";
+type CheckStatus = "pass" | "fail" | "warning" | "not_checked";
 export interface DoctorCheck {
     status: CheckStatus;
     detail: string;

package/dist/doctor.js

@@ -60,7 +60,7 @@ export async function runInstallationDoctor(dataDirInput) {
         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.");
+                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.");

package/dist/doctor.test.js

@@ -24,6 +24,8 @@ test("installation doctor validates init output without exposing or changing the
         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);

package/dist/evidence.d.ts

@@ -0,0 +1,21 @@
+export type EvidenceState = "VERIFIED" | "OBSERVED" | "UNKNOWN" | "ABSENT";
+/**
+ * A compact result vocabulary for displaying receipt-adjacent facts without
+ * letting any one fact become a universal completion claim.
+ */
+export interface EvidenceReport {
+    receiptIntegrity: EvidenceState;
+    walletAuthorization: EvidenceState;
+    collectorSignature: EvidenceState;
+    hostExecution: EvidenceState;
+    delivery: EvidenceState;
+    businessAcceptance: EvidenceState;
+    settlement: EvidenceState;
+    externalEffect: EvidenceState;
+}
+export declare function receiptEvidenceReport(input: {
+    receiptIntegrity: boolean;
+    walletAuthorization: boolean;
+    collectorSignature: boolean;
+    hostExecution?: EvidenceState;
+}): EvidenceReport;

package/dist/evidence.js

@@ -0,0 +1,14 @@
+export function receiptEvidenceReport(input) {
+    return {
+        receiptIntegrity: input.receiptIntegrity ? "VERIFIED" : "UNKNOWN",
+        walletAuthorization: input.walletAuthorization ? "VERIFIED" : "UNKNOWN",
+        collectorSignature: input.collectorSignature ? "VERIFIED" : "UNKNOWN",
+        hostExecution: input.hostExecution ?? "UNKNOWN",
+        // These require their own artifacts and verifiers. AIPOU receipts do not
+        // infer them from a completed local task.
+        delivery: "UNKNOWN",
+        businessAcceptance: "ABSENT",
+        settlement: "ABSENT",
+        externalEffect: "UNKNOWN"
+    };
+}

package/dist/feedback.d.ts

@@ -0,0 +1,17 @@
+/** Explicit local export only. No identifiers, task hashes, keys, paths or uploads. */
+export declare function localFeedbackSummary(): Promise<{
+    schema: string;
+    version: string;
+    platform: NodeJS.Platform;
+    node: string;
+    localReceiptCount: number;
+    localActiveDays: number;
+    completedSessions: number;
+    activeSessions: number;
+    expiredSessions: number;
+    measuredUsageReceipts: number;
+    unmeasuredUsageReceipts: number;
+    unspecifiedUsageReceipts: number;
+    transmission: string;
+    interpretation: string;
+}>;

package/dist/feedback.js

@@ -0,0 +1,24 @@
+import { getPackageVersion } from "./version.js";
+import { exportStoredReceipts, protocolStateCounts } from "./store.js";
+/** Explicit local export only. No identifiers, task hashes, keys, paths or uploads. */
+export async function localFeedbackSummary() {
+    const receipts = await exportStoredReceipts();
+    const counts = await protocolStateCounts();
+    const activeDays = new Set(receipts.map((r) => r.recordedAt.slice(0, 10)));
+    return {
+        schema: "aipou-local-feedback-v1",
+        version: await getPackageVersion(),
+        platform: process.platform,
+        node: process.versions.node,
+        localReceiptCount: receipts.length,
+        localActiveDays: activeDays.size,
+        completedSessions: counts.completedSessions,
+        activeSessions: counts.activeSessions,
+        expiredSessions: counts.expiredSessions,
+        measuredUsageReceipts: receipts.filter((r) => r.tokenUsageMeasurement === "measured").length,
+        unmeasuredUsageReceipts: receipts.filter((r) => r.tokenUsageMeasurement === "unmeasured").length,
+        unspecifiedUsageReceipts: receipts.filter((r) => !r.tokenUsageMeasurement || r.tokenUsageMeasurement === "unspecified").length,
+        transmission: "none; review before sharing voluntarily",
+        interpretation: "one local installation; not unique-user, organic-adoption or revenue metrics",
+    };
+}

package/dist/identity.d.ts

@@ -6,6 +6,9 @@ export declare const authorizationTypes: {
         type: string;
     }[];
 };
+export declare const DEFAULT_TASK_SESSION_TTL_SECONDS: number;
+export declare function taskSessionExpiry(session: Pick<TaskSession, "issuedAt" | "expiresAt">): number;
+export declare function isTaskSessionExpired(session: Pick<TaskSession, "issuedAt" | "expiresAt">, nowSeconds?: number): boolean;
 export declare function agentWallet(): Wallet;
 export declare function createTaskSession(input: {
     provider: string;

package/dist/identity.js

@@ -12,6 +12,23 @@ export const authorizationTypes = {
         { name: "issuedAt", type: "uint256" }
     ]
 };
+export const DEFAULT_TASK_SESSION_TTL_SECONDS = 24 * 60 * 60;
+function taskSessionTtlSeconds() {
+    const configured = process.env.AIPOU_TASK_SESSION_TTL_SECONDS;
+    if (!configured)
+        return DEFAULT_TASK_SESSION_TTL_SECONDS;
+    const value = Number.parseInt(configured, 10);
+    if (!Number.isInteger(value) || value < 60 || value > 7 * DEFAULT_TASK_SESSION_TTL_SECONDS) {
+        throw new Error("AIPOU_TASK_SESSION_TTL_SECONDS must be an integer from 60 through 604800");
+    }
+    return value;
+}
+export function taskSessionExpiry(session) {
+    return session.expiresAt ?? session.issuedAt + taskSessionTtlSeconds();
+}
+export function isTaskSessionExpired(session, nowSeconds = Math.floor(Date.now() / 1000)) {
+    return nowSeconds >= taskSessionExpiry(session);
+}
 function readKeyFile(keyFile) {
     try {
         return readFileSync(path.resolve(keyFile), "utf8").trim();
@@ -52,7 +69,14 @@ export async function createTaskSession(input) {
         issuedAt
     };
     const walletAuthorization = await wallet.signTypedData(domain, authorizationTypes, value);
-    return { ...input, wallet: wallet.address, nonce, issuedAt, walletAuthorization };
+    return {
+        ...input,
+        wallet: wallet.address,
+        nonce,
+        issuedAt,
+        expiresAt: issuedAt + taskSessionTtlSeconds(),
+        walletAuthorization
+    };
 }
 export function verifyTaskAuthorization(session) {
     const domain = {