Validate incoming transfer actor against tracked counterparty

Author: warmidris

packages/stackflow-agent/README.md

@@ -135,5 +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. Incoming transfer validation enforces tracked contract/pipe/principals/token consistency; mismatched `pipeId`, `pipeKey`, or token payloads are rejected.
+7. Incoming transfer validation enforces tracked contract/pipe/principals/token consistency; mismatched `pipeId`, `pipeKey`, `actor`, or token payloads are rejected.
 8. For production hardening, add alerting, signer balance checks, and idempotency audit logs.

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

@@ -268,6 +268,12 @@ export class StackflowAgentService {
         reason: "actor-missing",
       };
     }
+    if (actor !== tracked.counterpartyPrincipal) {
+      return {
+        valid: false,
+        reason: "actor-mismatch",
+      };
+    }
     const latest = this.stateStore.getLatestSignatureState(
       tracked.pipeId,
       tracked.localPrincipal,

tests/stackflow-agent.test.ts

@@ -691,6 +691,63 @@ describe("stackflow agent", () => {
     store.close();
   });
 
+  it("rejects incoming transfer requests with actor mismatch", () => {
+    const dbFile = tempDbFile("agent-sign-actor-mismatch");
+    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,
+    });
+
+    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: null,
+        myBalance: "90",
+        theirBalance: "10",
+        nonce: "1",
+        action: "1",
+        actor: "ST1THIRD",
+        theirSignature: "0x" + "22".repeat(65),
+      },
+    });
+
+    expect(validation.valid).toBe(false);
+    expect(validation.reason).toBe("actor-mismatch");
+    store.close();
+  });
+
   it("rejects incoming transfer requests with pipe id mismatch", () => {
     const dbFile = tempDbFile("agent-sign-pipeid-mismatch");
     const store = new AgentStateStore({ dbFile });