fix(ttx): harden responder views against adversarial input (#1944) (#1946)

Signed-off-by: Angelo De Caro <adc@zurich.ibm.com>

Author: adecaro

.gitignore

@@ -13,3 +13,4 @@ cmd/token_validation_service/out/
 /.antigravitycli/
 /site/
 coverage.out
+/.codex/

docs/services/ttx.md

@@ -56,6 +56,28 @@ When a transaction is created, it:
 *   Assigns a unique Transaction ID.
 *   Registers a cleanup hook in the FSC view context to ensure resources (like locked tokens) are released if the transaction fails.
 
+## Responder Threat Model
+
+TTX responder views cross a network trust boundary. A remote initiator can control envelope bytes, transaction encodings, TMS and wallet identifiers, recipient and composite-identity structures, signature requests, spend requests, and the timing or omission of protocol messages. Responders must treat all of these inputs as hostile.
+
+The assets protected at this boundary are:
+
+- service availability, including freedom from panics and disproportionate parsing work;
+- token-owner, auditor, and node signing capabilities;
+- recipient identities, audit information, and other response data;
+- local transaction, wallet, signer, and endpoint-binding state.
+
+Responder processing follows four security requirements:
+
+1. Validate message type, encoding, structure, and protocol state before using nested fields.
+2. Authenticate the party or identity authorized for an operation before releasing signatures or recipient data.
+3. Validate the complete structure before mutating local state, and bind acknowledgements to the transaction that was reviewed.
+4. Return errors for malformed or inconsistent input instead of panicking.
+
+TMS implementations, token drivers, local wallets, and configured infrastructure services are trusted. Application code remains responsible for business-policy decisions, such as confirming that a multisig or policy spend transaction consumes exactly the token named in the earlier request. Applications also control which callers can invoke responder views and which local wallets those callers may select.
+
+The complete boundary inventory and security goals are in the [TTX Responder Threat Model](ttx/ttx_responder_security.md).
+
 ## Identity Management
 
 To issue or transfer tokens, the initiator must acquire the recipient's identity. The TTX service provides interactive protocols for this purpose.
@@ -78,9 +100,9 @@ Wire messages use JSON sessions (`token/services/utils/json/session`); the diagr
 - If `recipientRequest.RecipientData != nil`, the responder checks `OwnerWallet.Contains` for `RecipientData.Identity`, then sends a **slim acknowledgement** (`RecipientResponse` with no `RecipientData`, only a `Signature`) back on the session (echo path). The initiator already holds the full `RecipientData` and uses its own copy.
 - If `recipientRequest.RecipientData == nil`, the responder calls `OwnerWallet.GetRecipientData` and sends a full `RecipientResponse` carrying the wallet-produced `RecipientData` plus a `Signature` (fresh path).
 
-**Nonce / Signature Binding.** Every `RecipientRequest` (and `ExchangeRecipientRequest`) carries a cryptographic nonce (`NonceSize` bytes) generated by the initiator. The responder signs an *attestation message* — a DER-encoded (`encoding/asn1`) structure that captures every field of the received request (TMSID, wallet id, identity, multisig flag, policy, nonce) together with the session id and the context id — using the private key corresponding to the returned identity (obtained via `tms.SigService().GetSigner`). The initiator rebuilds the same structure and verifies the signature with `tms.SigService().OwnerVerifier` **before** registering the identity. The session id and context id are propagated in the message header, so both parties reconstruct identical bytes. ASN.1's tag-length-value framing keeps field boundaries explicit, removing the concatenation ambiguity a flat `nonce || identity` message would allow (an extension attack). This binds the attestation to one specific request, session, and context, preventing identity-spoofing and replay where a compromised session substitutes a different party's identity bytes.
+**Nonce / Signature Binding.** Every `RecipientRequest` (and `ExchangeRecipientRequest`) carries a cryptographic nonce (`NonceSize` bytes) generated by the initiator. The responder signs an *attestation message* — a DER-encoded (`encoding/asn1`) structure that captures every field of the received request (TMSID, wallet id, identity, multisig flag, policy, nonce) together with the session id and the context id — using the private key corresponding to the returned identity (obtained via `tms.SigService().GetSigner`). The initiator rebuilds the same structure and verifies the signature with `tms.SigService().OwnerVerifier` **before** registering the identity. The exchange flow is mutual: `ExchangeRecipientRequest.Signature` proves that the initiator owns the recipient identity it asks the responder to register and bind. The session id and context id are propagated in the message header, so both parties reconstruct identical bytes. ASN.1's tag-length-value framing keeps field boundaries explicit, removing the concatenation ambiguity a flat nonce/identity message would allow. This binds the attestation to one specific request, session, and context, preventing identity-spoofing and replay where a compromised session substitutes a different party's identity bytes.
 
-**Multisig.** When `RecipientRequest.MultiSig` is true, the initiator may send an additional `MultisigRecipientData` after the first exchange; the responder registers identities and updates bindings as in code. Each individual component identity is already attested through nonce/signature binding during the single-recipient phase.
+**Multisig and policy follow-ups.** When a composite identity was requested, the initiator sends `MultisigRecipientData` or `PolicyRecipientData` after the first exchange. Before changing local state, the responder checks that component identities, audit information, nodes, and recipients have equal cardinality; that ordered recipients match the composite components; that the responder's attested identity is included; and that a policy identity matches the policy requested in phase one.
 
 #### `RequestRecipientIdentityView` / `RespondRequestRecipientIdentityView`
 
@@ -144,12 +166,14 @@ sequenceDiagram
     rect rgba(230, 230, 250, 0.35)
         Note over I,R: Phase 1 - Exchange request (with nonce)
         I->>I: nonce = GetRandomNonce()
-        I->>R: ExchangeRecipientRequest{TMSID, WalletID, RecipientData(local), Nonce}
+        I->>I: initiatorSig = Sign(attestation for RecipientData(local))
+        I->>R: ExchangeRecipientRequest{TMSID, WalletID, RecipientData(local), Nonce, Signature: initiatorSig}
     end
 
     rect rgba(255, 245, 238, 0.5)
         Note over R: Phase 2 - Responder processing with attestation
-        R->>R: Reject if Nonce is empty
+        R->>R: Reject if Nonce, RecipientData, or initiator Signature is empty
+        R->>R: Verify initiator attestation before state mutation or disclosure
         R->>R: RegisterRecipientIdentity(request.RecipientData)
         R->>R: recipientData = wallet.GetRecipientData()
         R->>R: msg = asn1(request fields + session id + context id + recipientData.Identity)
@@ -412,7 +436,7 @@ sequenceDiagram
     end
 ```
 
-`EndorseView` (`endorse.go`) is the responder for the signature-request leg; `AcceptView` (`accept.go`) responds to the transaction-distribution leg with a signed acknowledgement. `ReceiveTransactionView` (`receivetx.go`) unwraps the envelope and accepts `TypeTransaction`, `TypeTransactionResponse`, or `TypeSignatureRequest`.
+`EndorseView` (`endorse.go`) is the responder for the signature-request leg; before acknowledging the final distribution it requires the token actions, TMS identity, network transaction creator/nonce, signer, and transient data to match the transaction it reviewed. `AcceptView` (`accept.go`) responds to the transaction-distribution leg with a signed acknowledgement. `ReceiveTransactionView` (`receivetx.go`) unwraps the envelope and accepts `TypeTransaction`, `TypeTransactionResponse`, or `TypeSignatureRequest`. Transaction and transient ASN.1 decoders reject trailing data, duplicate transient keys, and key/value cardinality mismatches.
 
 ## Auditor Approval Flow
 
@@ -501,7 +525,7 @@ Waiting is push-first: each waiter registers a status listener on the local data
 
 ### Transaction Recovery
 
-Panurus includes an automatic recovery mechanism to handle pending transactions that may have lost their finality listeners due to node restarts, network interruptions, or other failures. 
+Panurus includes an automatic recovery mechanism to handle pending transactions that may have lost their finality listeners due to node restarts, network interruptions, or other failures.
 The recovery service is part of the **Storage Service** and is instantiated by the **Network Service** to recover transactions from either `TTXDB` (for regular transactions) or `AuditDB` (for auditor nodes).
 
 For detailed information about the recovery mechanism, see:

docs/services/ttx/ttx_responder_security.md

@@ -0,0 +1,25 @@
+# TTX Responder Threat Model
+
+This document defines the responder-side threat model for the interactive protocols under `../../../token/services/ttx`. Every session envelope, transaction byte string, recipient structure, and spend request received from a remote initiator is hostile.
+
+## Security Goals
+
+A responder must:
+
+- reject malformed input with an error rather than panic;
+- release signatures or recipient data only after the protocol's authentication and consistency checks pass;
+- avoid mutating identity, endpoint, wallet, or transaction state before validating the structures that authorize the mutation;
+- bind acknowledgements to the transaction that the responder actually reviewed;
+- reject ambiguous encodings rather than accepting multiple byte strings for the same logical message.
+
+The application still decides whether a valid transaction satisfies its business rules. In particular, the multisig and policy spend flows deliberately return the assembled transaction so that application code can verify that it consumes the token named in the earlier `SpendRequest` before calling `EndorseView`.
+
+## Trust Boundaries
+
+| Boundary | Hostile input | Security-sensitive operation |
+|----------|---------------|------------------------------|
+| `ReceiveTransactionView` | Envelope body and ASN.1 transaction bytes | TMS lookup, request validation, persistence, later signatures |
+| `EndorseView` | Signature request and final distributed transaction | Token-owner signature and node acknowledgement signature |
+| Recipient responders | TMS ID, wallet ID, recipient data, nonce, composite follow-up | Recipient/audit-data release, signer registration, endpoint binding |
+| Withdrawal and upgrade responders | Recipient data, token/proof material | Recipient registration and endpoint binding |
+| Multisig/policy spend responders | Serialized `SpendRequest` and assembled transaction | Application approval followed by token-owner endorsement |

token/services/ttx/boolpolicy/spend.go

@@ -80,6 +80,9 @@ func (f *ReceiveSpendRequestView) Call(context view.Context) (any, error) {
 
 		return nil, err
 	}
+	if tx.Token == nil {
+		return nil, errors.New("invalid policy spend request: token is nil")
+	}
 
 	return tx, nil
 }

token/services/ttx/boolpolicy/spend_test.go

@@ -110,6 +110,26 @@ func newSilentSession(t *testing.T) *dep_mock.Session {
 	return s
 }
 
+func TestReceiveSpendRequestViewRejectsNilToken(t *testing.T) {
+	env, err := jsession.WrapEnvelope(&SpendRequest{}, ttx.TypeSpendRequest)
+	require.NoError(t, err)
+	raw, err := json.Marshal(env)
+	require.NoError(t, err)
+
+	s := &dep_mock.Session{}
+	messages := make(chan *view.Message, 1)
+	messages <- &view.Message{Payload: raw}
+	s.ReceiveReturns(messages)
+	ctx := &dep_mock.Context{}
+	ctx.ContextReturns(t.Context())
+	ctx.SessionReturns(s)
+	ctx.GetServiceReturns(nil, errors.New("service not registered in test"))
+
+	_, err = NewReceiveSpendRequestView().Call(ctx)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "token is nil")
+}
+
 func TestRequestSpendView_Call_TimesOutOnUnresponsiveParty(t *testing.T) {
 	partyA := view.Identity("party-a")
 	partyB := view.Identity("party-b")

token/services/ttx/endorse.go

@@ -154,20 +154,59 @@ func (s *EndorseView) receiveTransaction(context view.Context) ([]byte, error) {
 		return nil, errors.Wrapf(err, "failed receiving transaction")
 	}
 
-	// check that the content of the token request match
-	m1, err := s.tx.TokenRequest.MarshalToSign()
+	if err := validateEndorsedTransaction(s.tx, tx); err != nil {
+		return nil, err
+	}
+
+	return tx.FromRaw, nil
+}
+
+func validateEndorsedTransaction(expected, received *Transaction) error {
+	if expected == nil || expected.Payload == nil || received == nil || received.Payload == nil {
+		return errors.New("invalid endorsed transaction: transaction or payload is nil")
+	}
+	if expected.TokenRequest == nil || received.TokenRequest == nil {
+		return errors.New("invalid endorsed transaction: token request is nil")
+	}
+	m1, err := expected.TokenRequest.MarshalToSign()
 	if err != nil {
-		return nil, errors.Wrap(err, "failed to marshal token request to sign from the local transaction")
+		return errors.Wrap(err, "failed to marshal token request to sign from the local transaction")
 	}
-	m2, err := tx.TokenRequest.MarshalToSign()
+	m2, err := received.TokenRequest.MarshalToSign()
 	if err != nil {
-		return nil, errors.Wrap(err, "failed to marshal token request to sign from the remote transaction")
+		return errors.Wrap(err, "failed to marshal token request to sign from the remote transaction")
 	}
 	if !bytes.Equal(m1, m2) {
-		return nil, errors.Errorf("token request's signer does not match the expected signer")
+		return errors.New("invalid endorsed transaction: token request changed")
+	}
+	if expected.ID() != received.ID() || !expected.TMSID().Equal(received.TMSID()) {
+		return errors.New("invalid endorsed transaction: transaction identity changed")
+	}
+	if !bytes.Equal(expected.TxID.Nonce, received.TxID.Nonce) || !bytes.Equal(expected.TxID.Creator, received.TxID.Creator) {
+		return errors.New("invalid endorsed transaction: network transaction identity changed")
+	}
+	if !bytes.Equal(expected.Signer, received.Signer) {
+		return errors.New("invalid endorsed transaction: network signer changed")
+	}
+	if !equalTransient(expected.Transient, received.Transient) {
+		return errors.New("invalid endorsed transaction: transient data changed")
 	}
 
-	return tx.FromRaw, nil
+	return nil
+}
+
+func equalTransient(left, right map[string][]byte) bool {
+	if len(left) != len(right) {
+		return false
+	}
+	for key, value := range left {
+		other, ok := right[key]
+		if !ok || !bytes.Equal(value, other) {
+			return false
+		}
+	}
+
+	return true
 }
 
 // ack sends back an acknowledgement message to the initiator of the endorsement collection process.

token/services/ttx/endorse_security_test.go

@@ -0,0 +1,68 @@
+/*
+Copyright IBM Corp. All Rights Reserved.
+
+SPDX-License-Identifier: Apache-2.0
+*/
+
+package ttx
+
+import (
+	"testing"
+
+	"github.com/LFDT-Panurus/panurus/token"
+	"github.com/LFDT-Panurus/panurus/token/services/network"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func endorsementTransaction() *Transaction {
+	return &Transaction{Payload: &Payload{
+		TxID:         network.TxID{Nonce: []byte("nonce"), Creator: []byte("creator")},
+		ID:           "anchor",
+		tmsID:        token.TMSID{Network: "network", Channel: "channel", Namespace: "namespace"},
+		Signer:       []byte("signer"),
+		Transient:    network.TransientMap{"key": []byte("value")},
+		TokenRequest: token.NewRequest(nil, "anchor"),
+	}}
+}
+
+func cloneEndorsementTransaction(tx *Transaction) *Transaction {
+	payload := *tx.Payload
+	payload.TxID.Nonce = append([]byte(nil), tx.TxID.Nonce...)
+	payload.TxID.Creator = append([]byte(nil), tx.TxID.Creator...)
+	payload.Signer = append([]byte(nil), tx.Signer...)
+	payload.Transient = network.TransientMap{}
+	for key, value := range tx.Transient {
+		payload.Transient[key] = append([]byte(nil), value...)
+	}
+
+	return &Transaction{Payload: &payload}
+}
+
+func TestValidateEndorsedTransactionRejectsImmutableFieldSubstitution(t *testing.T) {
+	expected := endorsementTransaction()
+	require.NoError(t, validateEndorsedTransaction(expected, cloneEndorsementTransaction(expected)))
+
+	tests := []struct {
+		name   string
+		mutate func(*Transaction)
+		match  string
+	}{
+		{name: "network signer", mutate: func(tx *Transaction) { tx.Signer = []byte("mallory") }, match: "network signer changed"},
+		{name: "network creator", mutate: func(tx *Transaction) { tx.TxID.Creator = []byte("mallory") }, match: "network transaction identity changed"},
+		{name: "network nonce", mutate: func(tx *Transaction) { tx.TxID.Nonce = []byte("mallory") }, match: "network transaction identity changed"},
+		{name: "transient value", mutate: func(tx *Transaction) { tx.Transient["key"] = []byte("malicious") }, match: "transient data changed"},
+		{name: "transient key", mutate: func(tx *Transaction) { tx.Transient["extra"] = []byte("malicious") }, match: "transient data changed"},
+		{name: "tms", mutate: func(tx *Transaction) { tx.tmsID.Namespace = "other" }, match: "transaction identity changed"},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			received := cloneEndorsementTransaction(expected)
+			test.mutate(received)
+			err := validateEndorsedTransaction(expected, received)
+			require.Error(t, err)
+			assert.Contains(t, err.Error(), test.match)
+		})
+	}
+}

token/services/ttx/envelope_protocol_test.go

@@ -51,9 +51,10 @@ func TestVersionedRecipientResponseAckRoundTrip(t *testing.T) {
 
 func TestVersionedExchangeRecipientRoundTrip(t *testing.T) {
 	original := &ExchangeRecipientRequest{
-		TMSID:    token.TMSID{Network: "net", Channel: "ch", Namespace: "ns"},
-		WalletID: []byte("wallet"),
-		Nonce:    []byte("exchange-nonce-32bytes-pad-xxxxx"),
+		TMSID:     token.TMSID{Network: "net", Channel: "ch", Namespace: "ns"},
+		WalletID:  []byte("wallet"),
+		Nonce:     []byte("exchange-nonce-32bytes-pad-xxxxx"),
+		Signature: []byte("initiator-signature"),
 	}
 	roundTripTTXMessage(t, TypeExchangeRecipientRequest, original, &ExchangeRecipientRequest{})
 }

token/services/ttx/marshaller.go

@@ -54,12 +54,25 @@ func MarshalMeta(v map[string][]byte) ([]byte, error) {
 
 func UnmarshalMeta(raw []byte) (map[string][]byte, error) {
 	var metaSer metaSer
-	_, err := asn1.Unmarshal(raw, &metaSer)
+	rest, err := asn1.Unmarshal(raw, &metaSer)
 	if err != nil {
 		return nil, err
 	}
+	if len(rest) != 0 {
+		return nil, errors.Errorf("invalid transient metadata: trailing data [%d] bytes", len(rest))
+	}
+	if len(metaSer.Keys) != len(metaSer.Vals) {
+		return nil, errors.Errorf(
+			"invalid transient metadata: key/value count mismatch [%d]!=[%d]",
+			len(metaSer.Keys),
+			len(metaSer.Vals),
+		)
+	}
 	v := make(map[string][]byte, len(metaSer.Keys))
 	for i, k := range metaSer.Keys {
+		if _, ok := v[k]; ok {
+			return nil, errors.Errorf("invalid transient metadata: duplicate key [%s]", k)
+		}
 		v[k] = metaSer.Vals[i]
 	}
 
@@ -153,8 +166,12 @@ func marshal(t *Transaction, eIDs ...string) ([]byte, error) {
 
 func unmarshal(getNetwork GetNetworkFunc, p *Payload, raw []byte) error {
 	var ser TransactionSer
-	if _, err := asn1.Unmarshal(raw, &ser); err != nil {
-		return errors.Wrapf(err, "failed unmarshalling transaction [%s]", string(raw))
+	rest, err := asn1.Unmarshal(raw, &ser)
+	if err != nil {
+		return errors.Wrap(err, "failed unmarshalling transaction")
+	}
+	if len(rest) != 0 {
+		return errors.Errorf("failed unmarshalling transaction: trailing data [%d] bytes", len(rest))
 	}
 	// sanity checks
 	if len(ser.Network) == 0 {