fix(multisig,boolpolicy): verify spend tx matches approved SpendRequest

EndorseSpendView in both token/services/ttx/multisig/spend.go and
token/services/ttx/boolpolicy/spend.go received a transaction from the
initiator and signed it without checking that the transaction actually
consumed the token referenced by the SpendRequest the co-owner
approved. The multisig variant carried an explicit
'TODO: check tx matches request' marker; the policy variant had the
same gap without a marker.

A malicious or buggy initiator could ask a co-owner to approve a
SpendRequest for one token and then deliver a transaction that consumes
a different token co-owned by the same group. The co-owner would sign
the substituted transaction with no diagnostic, breaking the consent
property that multisig and AND-policy spends rely on.

This change adds a verifySpendTxMatchesRequest helper in each package.
After ttx.ReceiveTransaction returns, the helper extracts the input
ids from the transaction's audit record and rejects the flow before
EndorseView is invoked unless every input id equals
request.Token.Id. The comparison rule is split into a pure helper
verifyInputIDsMatchExpected so it can be unit-tested without
constructing a full ttx.Transaction.

Documentation in docs/services/ttx.md gains a new 'Spend Coordination
Wire Flow' section with a Mermaid diagram describing the request,
delivery, and verification phases shared by the multisig and policy
variants.

Closes #1682

Signed-off-by: SuyashAlphaC <suyashagrawal862@gmail.com>

Author: SuyashAlphaC

docs/services/ttx.md

@@ -208,6 +208,43 @@ _, err = context.RunView(ttx.NewCollectEndorsementsView(tx))
 
 Co-owners run `EndorseSpendView` (via `EndorseSpend`) on their side, which ACKs the spend request and then endorses the assembled transaction.
 
+#### Spend Coordination Wire Flow
+
+The same coordination protocol is implemented in `token/services/ttx/multisig/spend.go` (for AND multisig) and in `token/services/ttx/boolpolicy/spend.go` (for AND policies). Both follow the shape below; the responder must verify that the assembled transaction actually consumes the token referenced by the `SpendRequest` it approved.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant I as Initiator (RequestSpendView)
+    participant R as Co-owner (EndorseSpendView)
+
+    rect rgba(230, 230, 250, 0.35)
+        Note over I,R: Phase 1 - Spend approval request
+        I->>R: SpendRequest{Token: UnspentToken to spend}
+        R->>R: ReceiveSpendRequest, decide to approve
+        R-->>I: SpendResponse{}
+    end
+
+    rect rgba(255, 245, 238, 0.5)
+        Note over I,R: Phase 2 - Transaction assembly and delivery
+        I->>I: Assemble transaction consuming SpendRequest.Token
+        I->>R: Transaction (via ttx.ReceiveTransaction)
+    end
+
+    rect rgba(240, 255, 240, 0.45)
+        Note over R: Phase 3 - Verification (required before signing)
+        R->>R: Extract input IDs from tx.Request().AuditRecord
+        alt every input id == SpendRequest.Token.Id
+            R->>R: Run EndorseView(tx) and sign
+            R-->>I: Signed transaction
+        else mismatch
+            R-->>I: Reject with error; no signature is produced
+        end
+    end
+```
+
+The Phase 3 check is what links the artifact a co-owner approves (the `SpendRequest`) to the artifact they sign (the assembled `tx`). Without it, a co-owner who reviews and approves a spend for token `T_a` could be made to sign a transaction consuming a different token `T_b` co-owned by the same group.
+
 #### Wallet and Authorization
 
 The `boolpolicy.OwnerWallet` (in `token/services/ttx/boolpolicy/wallet.go`) wraps a standard owner wallet and filters the token list to policy-type tokens.  `VerifyApprover` can be used to assert that a given identity is one of the named component identities before allowing a spend.

token/services/ttx/boolpolicy/spend.go

@@ -11,6 +11,7 @@ SPDX-License-Identifier: Apache-2.0
 package boolpolicy
 
 import (
+	"context"
 	"slices"
 	"time"
 
@@ -223,9 +224,48 @@ func (a *EndorseSpendView) Call(context view.Context) (interface{}, error) {
 	if err != nil {
 		return nil, errors.Wrap(err, "failed to receive transaction")
 	}
+	// Reject any received tx that consumes a different token from the one this
+	// co-owner approved in SpendRequest. The same gap was tracked for the
+	// multisig variant; the policy variant has the identical issue.
+	if err := verifySpendTxMatchesRequest(context.Context(), tx, a.request); err != nil {
+		return nil, errors.Wrap(err, "rejected spend transaction")
+	}
 	if _, err = context.RunView(ttx.NewEndorseView(tx)); err != nil {
 		return nil, errors.Wrap(err, "failed to endorse transaction")
 	}
 
 	return tx, nil
 }
+
+// verifySpendTxMatchesRequest fails if the received transaction does not consume
+// exactly the token referenced by the SpendRequest.
+func verifySpendTxMatchesRequest(ctx context.Context, tx *ttx.Transaction, request *SpendRequest) error {
+	if request == nil || request.Token == nil {
+		return errors.New("spend request is missing the token to authorize")
+	}
+	record, err := tx.Request().AuditRecord(ctx)
+	if err != nil {
+		return errors.Wrap(err, "failed to extract audit record from transaction")
+	}
+
+	return verifyInputIDsMatchExpected(record.Inputs.IDs(), request.Token.Id)
+}
+
+// verifyInputIDsMatchExpected returns nil when every entry in inputIDs equals expected.
+// It is split out from verifySpendTxMatchesRequest so the comparison rule can be
+// exercised in unit tests without constructing a full ttx.Transaction.
+func verifyInputIDsMatchExpected(inputIDs []*token.ID, expected token.ID) error {
+	if len(inputIDs) == 0 {
+		return errors.Errorf("transaction has no inputs to validate against approved token [%s]", expected)
+	}
+	for _, id := range inputIDs {
+		if id == nil || !id.Equal(expected) {
+			return errors.Errorf(
+				"transaction does not match approved spend request: expected token [%s], got input [%s]",
+				expected, id,
+			)
+		}
+	}
+
+	return nil
+}

token/services/ttx/boolpolicy/spend_internal_test.go

@@ -0,0 +1,58 @@
+/*
+Copyright IBM Corp. All Rights Reserved.
+
+SPDX-License-Identifier: Apache-2.0
+*/
+
+package boolpolicy
+
+import (
+	"testing"
+
+	"github.com/hyperledger-labs/fabric-token-sdk/token/token"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestVerifyInputIDsMatchExpected(t *testing.T) {
+	expected := token.ID{TxId: "tx-1", Index: 0}
+	other := token.ID{TxId: "tx-2", Index: 0}
+
+	t.Run("single matching input passes", func(t *testing.T) {
+		err := verifyInputIDsMatchExpected([]*token.ID{{TxId: "tx-1", Index: 0}}, expected)
+		require.NoError(t, err)
+	})
+
+	t.Run("single mismatched input is rejected", func(t *testing.T) {
+		err := verifyInputIDsMatchExpected([]*token.ID{&other}, expected)
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "does not match approved spend request")
+	})
+
+	t.Run("any mismatch in a set is rejected", func(t *testing.T) {
+		err := verifyInputIDsMatchExpected([]*token.ID{
+			{TxId: "tx-1", Index: 0},
+			&other,
+		}, expected)
+		require.Error(t, err)
+	})
+
+	t.Run("nil input id is rejected", func(t *testing.T) {
+		err := verifyInputIDsMatchExpected([]*token.ID{nil}, expected)
+		require.Error(t, err)
+	})
+
+	t.Run("empty input list is rejected", func(t *testing.T) {
+		err := verifyInputIDsMatchExpected(nil, expected)
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "no inputs")
+	})
+
+	t.Run("differing index alone is rejected", func(t *testing.T) {
+		err := verifyInputIDsMatchExpected(
+			[]*token.ID{{TxId: "tx-1", Index: 1}},
+			token.ID{TxId: "tx-1", Index: 0},
+		)
+		require.Error(t, err)
+	})
+}

token/services/ttx/multisig/spend.go

@@ -7,6 +7,7 @@ SPDX-License-Identifier: Apache-2.0
 package multisig
 
 import (
+	"context"
 	"slices"
 	"time"
 
@@ -251,7 +252,13 @@ func (a *EndorseSpendView) Call(context view.Context) (interface{}, error) {
 	}
 	logger.DebugfContext(context.Context(), "multisig tx received with id [%s]", tx.ID())
 
-	// TODO: check tx matches request
+	// Verify the received transaction actually consumes the token this co-owner
+	// approved. Without this check, a malicious or buggy initiator could obtain
+	// approval for one token and submit a transaction spending a different one,
+	// breaking the multisig consent property.
+	if err := verifySpendTxMatchesRequest(context.Context(), tx, a.request); err != nil {
+		return nil, errors.Wrap(err, "rejected spend transaction")
+	}
 
 	// If everything is fine, the recipient accepts and sends back her signature.
 	// Notice that, a signature from the recipient might or might not be required to make the transaction valid.
@@ -266,3 +273,36 @@ func (a *EndorseSpendView) Call(context view.Context) (interface{}, error) {
 
 	return tx, nil
 }
+
+// verifySpendTxMatchesRequest fails if the received transaction does not consume
+// exactly the token referenced by the SpendRequest.
+func verifySpendTxMatchesRequest(ctx context.Context, tx *ttx.Transaction, request *SpendRequest) error {
+	if request == nil || request.Token == nil {
+		return errors.New("spend request is missing the token to authorize")
+	}
+	record, err := tx.Request().AuditRecord(ctx)
+	if err != nil {
+		return errors.Wrap(err, "failed to extract audit record from transaction")
+	}
+
+	return verifyInputIDsMatchExpected(record.Inputs.IDs(), request.Token.Id)
+}
+
+// verifyInputIDsMatchExpected returns nil when every entry in inputIDs equals expected.
+// It is split out from verifySpendTxMatchesRequest so the comparison rule can be
+// exercised in unit tests without constructing a full ttx.Transaction.
+func verifyInputIDsMatchExpected(inputIDs []*token.ID, expected token.ID) error {
+	if len(inputIDs) == 0 {
+		return errors.Errorf("transaction has no inputs to validate against approved token [%s]", expected)
+	}
+	for _, id := range inputIDs {
+		if id == nil || !id.Equal(expected) {
+			return errors.Errorf(
+				"transaction does not match approved spend request: expected token [%s], got input [%s]",
+				expected, id,
+			)
+		}
+	}
+
+	return nil
+}

token/services/ttx/multisig/spend_internal_test.go

@@ -0,0 +1,66 @@
+/*
+Copyright IBM Corp. All Rights Reserved.
+
+SPDX-License-Identifier: Apache-2.0
+*/
+
+package multisig
+
+import (
+	"testing"
+
+	"github.com/hyperledger-labs/fabric-token-sdk/token/token"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestVerifyInputIDsMatchExpected(t *testing.T) {
+	expected := token.ID{TxId: "tx-1", Index: 0}
+	other := token.ID{TxId: "tx-2", Index: 0}
+
+	t.Run("single matching input passes", func(t *testing.T) {
+		err := verifyInputIDsMatchExpected([]*token.ID{{TxId: "tx-1", Index: 0}}, expected)
+		require.NoError(t, err)
+	})
+
+	t.Run("multiple matching inputs pass", func(t *testing.T) {
+		err := verifyInputIDsMatchExpected([]*token.ID{
+			{TxId: "tx-1", Index: 0},
+			{TxId: "tx-1", Index: 0},
+		}, expected)
+		require.NoError(t, err)
+	})
+
+	t.Run("single mismatched input is rejected", func(t *testing.T) {
+		err := verifyInputIDsMatchExpected([]*token.ID{&other}, expected)
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "does not match approved spend request")
+	})
+
+	t.Run("any mismatch in a set is rejected", func(t *testing.T) {
+		err := verifyInputIDsMatchExpected([]*token.ID{
+			{TxId: "tx-1", Index: 0},
+			&other,
+		}, expected)
+		require.Error(t, err)
+	})
+
+	t.Run("nil input id is rejected", func(t *testing.T) {
+		err := verifyInputIDsMatchExpected([]*token.ID{nil}, expected)
+		require.Error(t, err)
+	})
+
+	t.Run("empty input list is rejected", func(t *testing.T) {
+		err := verifyInputIDsMatchExpected(nil, expected)
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "no inputs")
+	})
+
+	t.Run("differing index alone is rejected", func(t *testing.T) {
+		err := verifyInputIDsMatchExpected(
+			[]*token.ID{{TxId: "tx-1", Index: 1}},
+			token.ID{TxId: "tx-1", Index: 0},
+		)
+		require.Error(t, err)
+	})
+}