Harden incoming token validation and overlap watcher coverage

Author: warmidris

packages/stackflow-agent/README.md

@@ -135,4 +135,5 @@ const result = await agent.acceptIncomingTransfer({
 4. Watcher retries are idempotent for already-disputed closures (same closure txid is skipped on later polls).
 5. Read-only polling isolates per-pipe failures (`getPipeState` errors on one pipe do not stop others).
 6. Event scan mode intentionally holds the cursor when any dispute submission errors occur, so failed disputes are retried on next run.
-7. For production hardening, add alerting, signer balance checks, and idempotency audit logs.
+7. Incoming transfer validation enforces tracked contract/principals/token consistency; mismatched token payloads are rejected.
+8. For production hardening, add alerting, signer balance checks, and idempotency audit logs.

packages/stackflow-agent/src/agent-service.js

@@ -187,6 +187,17 @@ export class StackflowAgentService {
         reason: "with-principal-mismatch",
       };
     }
+
+    const trackedToken =
+      tracked.token == null ? null : String(tracked.token).trim();
+    const payloadToken =
+      data.token == null ? trackedToken : String(data.token).trim();
+    if (payloadToken !== trackedToken) {
+      return {
+        valid: false,
+        reason: "token-mismatch",
+      };
+    }
     const theirSignature = (() => {
       try {
         return normalizeHex(data.theirSignature, "theirSignature");
@@ -256,7 +267,7 @@ export class StackflowAgentService {
         pipeKey: tracked.pipeKey,
         forPrincipal,
         withPrincipal,
-        token: data.token == null ? tracked.token : String(data.token).trim(),
+        token: trackedToken,
         myBalance,
         theirBalance,
         nonce,

tests/stackflow-agent.test.ts

@@ -510,6 +510,73 @@ describe("stackflow agent", () => {
     store.close();
   });
 
+  it("skips overlapping readonly watcher runs", async () => {
+    const dbFile = tempDbFile("agent-readonly-overlap");
+    const store = new AgentStateStore({ dbFile });
+
+    const contractId = "ST1TESTABC.contract";
+    const pipeKey = {
+      "principal-1": "ST1LOCAL",
+      "principal-2": "ST1OTHER",
+      token: null,
+    };
+    const pipeId = buildPipeId({ contractId, pipeKey });
+
+    store.upsertTrackedPipe({
+      pipeId,
+      contractId,
+      pipeKey,
+      localPrincipal: "ST1LOCAL",
+      counterpartyPrincipal: "ST1OTHER",
+      token: null,
+    });
+
+    let resolveFetch: ((value: unknown) => void) | null = null;
+
+    const agent = new StackflowAgentService({
+      stateStore: store,
+      signer: {
+        async submitDispute() {
+          return { txid: "0xnoop" };
+        },
+        async sip018Sign() {
+          return "0x" + "44".repeat(65);
+        },
+        async callContract() {
+          return { ok: true };
+        },
+      },
+      network: "devnet",
+    });
+
+    const watcher = new HourlyClosureWatcher({
+      agentService: agent,
+      getPipeState: () =>
+        new Promise((resolve) => {
+          resolveFetch = resolve;
+        }),
+    });
+
+    const firstRunPromise = watcher.runOnce();
+    const overlapping = await watcher.runOnce();
+
+    expect(overlapping.ok).toBe(true);
+    expect(overlapping.skipped).toBe(true);
+    expect(overlapping.reason).toBe("already-running");
+
+    resolveFetch?.({
+      "balance-1": "20",
+      "balance-2": "80",
+      "expires-at": "200",
+      nonce: "5",
+      closer: "ST1OTHER",
+    });
+
+    await firstRunPromise;
+    watcher.stop();
+    store.close();
+  });
+
   it("validates and signs incoming transfer requests", async () => {
     const dbFile = tempDbFile("agent-sign");
     const store = new AgentStateStore({ dbFile });
@@ -568,6 +635,62 @@ describe("stackflow agent", () => {
     store.close();
   });
 
+  it("rejects incoming transfer requests with token mismatch", () => {
+    const dbFile = tempDbFile("agent-sign-token-mismatch");
+    const store = new AgentStateStore({ dbFile });
+    const contractId = "ST1TESTABC.contract";
+    const pipeKey = {
+      "principal-1": "ST1LOCAL",
+      "principal-2": "ST1OTHER",
+      token: "ST1TOKEN.token-1",
+    };
+    const pipeId = buildPipeId({ contractId, pipeKey });
+    store.upsertTrackedPipe({
+      pipeId,
+      contractId,
+      pipeKey,
+      localPrincipal: "ST1LOCAL",
+      counterpartyPrincipal: "ST1OTHER",
+      token: "ST1TOKEN.token-1",
+    });
+
+    const agent = new StackflowAgentService({
+      stateStore: store,
+      signer: {
+        async sip018Sign() {
+          return "0x" + "44".repeat(65);
+        },
+        async submitDispute() {
+          return { txid: "0x1" };
+        },
+        async callContract() {
+          return { ok: true };
+        },
+      },
+      network: "devnet",
+    });
+
+    const validation = agent.validateIncomingTransfer({
+      pipeId,
+      payload: {
+        contractId,
+        forPrincipal: "ST1LOCAL",
+        withPrincipal: "ST1OTHER",
+        token: "ST1TOKEN.token-2",
+        myBalance: "90",
+        theirBalance: "10",
+        nonce: "1",
+        action: "1",
+        actor: "ST1OTHER",
+        theirSignature: "0x" + "22".repeat(65),
+      },
+    });
+
+    expect(validation.valid).toBe(false);
+    expect(validation.reason).toBe("token-mismatch");
+    store.close();
+  });
+
   it("opens a pipe via signer adapter with expected contract call", async () => {
     const dbFile = tempDbFile("agent-open");
     const store = new AgentStateStore({ dbFile });