feat(ttx): recipient wire hardening — slim echo + nonce/signature binding (#1652 M3)

Reduce wire overhead and prevent identity spoofing in the recipient
identity exchange protocol:

- Slim echo: on the echo path the responder now returns only a
  signature (RecipientResponse with nil RecipientData); the initiator
  already holds the full RecipientData and reuses its own copy.

- Nonce/signature binding: every RecipientRequest and
  ExchangeRecipientRequest carries a 32-byte nonce. The responder
  signs nonce||identity with SigService.GetSigner; the initiator
  verifies via SigService.OwnerVerifier before registering.

- New wire types: RecipientResponse, ExchangeRecipientResponse.

- Tests for round-trip, slim ack, malformed JSON, nonce helpers.

- Updated Mermaid diagrams and prose in docs/services/ttx.md.

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

Author: SuyashAlphaC

docs/services/ttx.md

@@ -24,9 +24,9 @@ sequenceDiagram
         participant Network
     end
 
-    Note over Initiator: 1. Request Identities
-    Initiator->>+Recipient: RequestRecipientIdentityView
-    Recipient-->>-Initiator: Recipient Data (Identity + Audit Info)
+    Note over Initiator: 1. Request Identities (with nonce/signature attestation)
+    Initiator->>+Recipient: RequestRecipientIdentityView (includes Nonce)
+    Recipient-->>-Initiator: RecipientResponse (Identity + Audit Info + Signature)
 
     Note over Initiator: 2. Assemble Request
     Initiator->>+Initiator: Issue / Transfer / Redeem operations
@@ -77,14 +77,14 @@ The recipient identity protocols are implemented in `token/services/ttx/recipien
 
 Wire messages use JSON sessions (`token/services/utils/json/session`); the diagrams name the Go types being sent or received.
 
-**Response paths (today).** In `RespondRequestRecipientIdentityView`, after the wallet lookup:
+**Response paths.** In `RespondRequestRecipientIdentityView`, after the wallet lookup:
 
-- If `recipientRequest.RecipientData != nil`, the responder checks `OwnerWallet.Contains` for `RecipientData.Identity`, then sends **the same** `RecipientData` value back on the session (echo path). The responder does **not** substitute wallet-held `AuditInfo` / metadata into that payload; what goes on the wire is the initiator-supplied structure (after the contains check).
-- If `recipientRequest.RecipientData == nil`, the responder calls `OwnerWallet.GetRecipientData` and sends that **wallet-produced** `RecipientData` (fresh path).
+- 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).
 
-In both cases the initiator receives a full `RecipientData` over the wire. The initiator then calls `WalletManager.RegisterRecipientIdentity` with that payload and updates the endpoint resolver. **Protocol hardening** may replace full-object responses with a minimal acknowledgement (or another minimal wire type) so the responder does not ship an entire `RecipientData` when a slimmer response suffices; that is a separate code change from this documentation.
+**Nonce / Signature Binding.** Every `RecipientRequest` (and `ExchangeRecipientRequest`) carries a 32-byte cryptographic nonce generated by the initiator. The responder signs `nonce || recipientIdentity` with the private key corresponding to the returned identity (obtained via `tms.SigService().GetSigner`). The initiator verifies this signature using `tms.SigService().OwnerVerifier` **before** registering the identity. This prevents identity-spoofing attacks where a compromised session could substitute 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.
+**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.
 
 #### `RequestRecipientIdentityView` / `RespondRequestRecipientIdentityView`
 
@@ -95,26 +95,34 @@ sequenceDiagram
     participant R as Responder
 
     rect rgba(230, 230, 250, 0.35)
-        Note over I,R: Phase 1 - Identity request
-        I->>R: RecipientRequest{TMSID, WalletID, RecipientData?, MultiSig}
+        Note over I,R: Phase 1 - Identity request (with nonce)
+        I->>I: nonce = generateNonce() (32 bytes)
+        I->>R: RecipientRequest{TMSID, WalletID, RecipientData?, MultiSig, Nonce}
     end
 
     rect rgba(255, 245, 238, 0.5)
-        Note over R: Phase 2 - Responder decision and reply
-        alt RecipientRequest.RecipientData != nil
+        Note over R: Phase 2 - Responder decision, attestation, and reply
+        R->>R: Reject if Nonce is empty
+        alt RecipientRequest.RecipientData != nil (echo path)
             R->>R: Verify wallet contains RecipientData.Identity
-        else RecipientRequest.RecipientData == nil
-            R->>R: Generate RecipientData from wallet
+            R->>R: sig = Sign(nonce || identity)
+            R->>R: endpoint.Bind(context.Me, identity)
+            R-->>I: RecipientResponse{Signature: sig} (slim ack, no RecipientData)
+        else RecipientRequest.RecipientData == nil (fresh path)
+            R->>R: recipientData = wallet.GetRecipientData()
+            R->>R: sig = Sign(nonce || recipientData.Identity)
+            R->>R: endpoint.Bind(context.Me, recipientData.Identity)
+            R-->>I: RecipientResponse{RecipientData, Signature: sig}
         end
-        R->>R: endpoint.Bind(context.Me, RecipientData.Identity)
-        Note over R,I: Bind before send so local resolver wiring fails before the peer receives RecipientData
-        R-->>I: RecipientData (echo or fresh data path)
     end
 
     rect rgba(240, 255, 240, 0.45)
-        Note over I,R: Phase 3 - Initiator registration and bindings
-        I->>I: RegisterRecipientIdentity(RecipientData)
-        I->>I: endpoint.Bind(requested FSC identity, RecipientData.Identity)
+        Note over I,R: Phase 3 - Initiator verification, registration, bindings
+        I->>I: Determine recipientData (own copy on echo, response on fresh)
+        I->>I: verifier = OwnerVerifier(recipientData.Identity)
+        I->>I: verifier.Verify(nonce || identity, resp.Signature)
+        I->>I: RegisterRecipientIdentity(recipientData)
+        I->>I: endpoint.Bind(requested FSC identity, recipientData.Identity)
     end
 
     rect rgba(245, 245, 245, 0.55)
@@ -125,8 +133,6 @@ sequenceDiagram
             R->>R: endpoint.Bind(each Node -> Recipient)
         end
     end
-
-    Note over I,R: Full RecipientData on wire today (echo of request vs wallet-generated)
 ```
 
 #### `ExchangeRecipientIdentitiesView` / `RespondExchangeRecipientIdentitiesView`
@@ -138,27 +144,29 @@ sequenceDiagram
     participant R as Responder
 
     rect rgba(230, 230, 250, 0.35)
-        Note over I,R: Phase 1 - Exchange request
-        I->>R: ExchangeRecipientRequest{TMSID, WalletID, RecipientData(local)}
+        Note over I,R: Phase 1 - Exchange request (with nonce)
+        I->>I: nonce = generateNonce() (32 bytes)
+        I->>R: ExchangeRecipientRequest{TMSID, WalletID, RecipientData(local), Nonce}
     end
 
     rect rgba(255, 245, 238, 0.5)
-        Note over R: Phase 2 - Responder processing
+        Note over R: Phase 2 - Responder processing with attestation
+        R->>R: Reject if Nonce is empty
         R->>R: RegisterRecipientIdentity(request.RecipientData)
-        R->>R: GetRecipientData(responder wallet)
-        R->>R: endpoint.Bind(context.Me, responder RecipientData.Identity)
+        R->>R: recipientData = wallet.GetRecipientData()
+        R->>R: sig = Sign(nonce || recipientData.Identity)
+        R->>R: endpoint.Bind(context.Me, recipientData.Identity)
         R->>R: endpoint.Bind(session caller, request.RecipientData.Identity)
-        Note over R,I: Binds before send so resolver wiring fails before the initiator receives our RecipientData
-        R-->>I: RecipientData(responder)
+        R-->>I: ExchangeRecipientResponse{RecipientData, Signature: sig}
     end
 
     rect rgba(240, 255, 240, 0.45)
-        Note over I,R: Phase 3 - Initiator registration and bindings
-        I->>I: RegisterRecipientIdentity(remote RecipientData)
-        I->>I: endpoint.Bind(other FSC identity, remote RecipientData.Identity)
+        Note over I,R: Phase 3 - Initiator verification, registration, bindings
+        I->>I: verifier = OwnerVerifier(resp.RecipientData.Identity)
+        I->>I: verifier.Verify(nonce || identity, resp.Signature)
+        I->>I: RegisterRecipientIdentity(resp.RecipientData)
+        I->>I: endpoint.Bind(other FSC identity, resp.RecipientData.Identity)
     end
-
-    Note over I,R: Full RecipientData on wire today (responder sends local wallet RecipientData)
 ```
 
 ### PolicyIdentity — Boolean-Expression-Governed Ownership

token/services/ttx/envelope_protocol_test.go

@@ -26,26 +26,49 @@ func TestVersionedRecipientRequestRoundTrip(t *testing.T) {
 		TMSID:    token.TMSID{Network: "net", Channel: "ch", Namespace: "ns"},
 		WalletID: []byte("wallet"),
 		MultiSig: true,
+		Nonce:    []byte("test-nonce-32bytes-padding-xxxxx"),
 	}
 	roundTripTTXMessage(t, TypeRecipientRequest, original, &RecipientRequest{})
 }
 
 func TestVersionedRecipientResponseRoundTrip(t *testing.T) {
-	original := &RecipientData{
-		Identity:  []byte("recipient"),
-		AuditInfo: []byte("audit"),
+	original := &RecipientResponse{
+		RecipientData: &RecipientData{
+			Identity:  []byte("recipient"),
+			AuditInfo: []byte("audit"),
+		},
+		Signature: []byte("sig-bytes"),
+	}
+	roundTripTTXMessage(t, TypeRecipientResponse, original, &RecipientResponse{})
+}
+
+func TestVersionedRecipientResponseAckRoundTrip(t *testing.T) {
+	original := &RecipientResponse{
+		Signature: []byte("sig-bytes"),
 	}
-	roundTripTTXMessage(t, TypeRecipientResponse, original, &RecipientData{})
+	roundTripTTXMessage(t, TypeRecipientResponse, original, &RecipientResponse{})
 }
 
 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"),
 	}
 	roundTripTTXMessage(t, TypeExchangeRecipientRequest, original, &ExchangeRecipientRequest{})
 }
 
+func TestVersionedExchangeRecipientResponseRoundTrip(t *testing.T) {
+	original := &ExchangeRecipientResponse{
+		RecipientData: &RecipientData{
+			Identity:  []byte("responder"),
+			AuditInfo: []byte("audit"),
+		},
+		Signature: []byte("exchange-sig"),
+	}
+	roundTripTTXMessage(t, TypeExchangeRecipientResp, original, &ExchangeRecipientResponse{})
+}
+
 func TestVersionedMultisigRecipientDataRoundTrip(t *testing.T) {
 	original := &MultisigRecipientData{
 		RecipientData: &token.RecipientData{Identity: []byte("ms")},

token/services/ttx/nonce.go

@@ -0,0 +1,17 @@
+/*
+Copyright IBM Corp. All Rights Reserved.
+
+SPDX-License-Identifier: Apache-2.0
+*/
+
+package ttx
+
+// buildAttestationMessage constructs the message that the responder signs
+// to prove key-ownership: nonce || identity.
+func buildAttestationMessage(nonce []byte, identity []byte) []byte {
+	msg := make([]byte, 0, len(nonce)+len(identity))
+	msg = append(msg, nonce...)
+	msg = append(msg, identity...)
+
+	return msg
+}

token/services/ttx/nonce_test.go

@@ -0,0 +1,150 @@
+/*
+Copyright IBM Corp. All Rights Reserved.
+
+SPDX-License-Identifier: Apache-2.0
+*/
+
+package ttx
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/hyperledger-labs/fabric-smart-client/platform/view/view"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestAttestationNonceViaGetRandomNonce(t *testing.T) {
+	nonce, err := GetRandomNonce()
+	require.NoError(t, err)
+	assert.Len(t, nonce, NonceSize)
+
+	nonce2, err := GetRandomNonce()
+	require.NoError(t, err)
+	assert.NotEqual(t, nonce, nonce2, "two nonces must differ")
+}
+
+func TestBuildAttestationMessage(t *testing.T) {
+	nonce := []byte("nonce-bytes")
+	identity := []byte("identity-bytes")
+
+	msg := buildAttestationMessage(nonce, identity)
+	assert.Equal(t, append([]byte("nonce-bytes"), []byte("identity-bytes")...), msg)
+	assert.Len(t, msg, len(nonce)+len(identity))
+}
+
+func TestBuildAttestationMessage_DifferentInputsProduceDifferentMessages(t *testing.T) {
+	msg1 := buildAttestationMessage([]byte("AB"), []byte("CD"))
+	msg2 := buildAttestationMessage([]byte("ABC"), []byte("D"))
+	// "AB"+"CD" = "ABCD" and "ABC"+"D" = "ABCD" — both produce the same bytes.
+	// This documents the current concatenation approach and can serve as a basis
+	// for future length-prefixed separation if required.
+	assert.Equal(t, msg1, msg2, "simple concatenation does not separate fields")
+}
+
+func TestBuildAttestationMessage_EmptyInputs(t *testing.T) {
+	msg := buildAttestationMessage(nil, nil)
+	assert.Empty(t, msg)
+
+	msg = buildAttestationMessage([]byte("nonce"), nil)
+	assert.Equal(t, []byte("nonce"), msg)
+
+	msg = buildAttestationMessage(nil, []byte("id"))
+	assert.Equal(t, []byte("id"), msg)
+}
+
+func TestRecipientResponse_JSONRoundTrip_FreshPath(t *testing.T) {
+	original := &RecipientResponse{
+		RecipientData: &RecipientData{
+			Identity:               view.Identity("alice"),
+			AuditInfo:              []byte("audit"),
+			TokenMetadata:          []byte("meta"),
+			TokenMetadataAuditInfo: []byte("meta-audit"),
+		},
+		Signature: []byte("sig"),
+	}
+	raw, err := json.Marshal(original)
+	require.NoError(t, err)
+
+	decoded := &RecipientResponse{}
+	require.NoError(t, json.Unmarshal(raw, decoded))
+
+	require.NotNil(t, decoded.RecipientData)
+	assert.Equal(t, original.RecipientData.Identity, decoded.RecipientData.Identity)
+	assert.Equal(t, original.RecipientData.AuditInfo, decoded.RecipientData.AuditInfo)
+	assert.Equal(t, original.Signature, decoded.Signature)
+}
+
+func TestRecipientResponse_JSONRoundTrip_EchoPath(t *testing.T) {
+	original := &RecipientResponse{
+		Signature: []byte("sig-only"),
+	}
+	raw, err := json.Marshal(original)
+	require.NoError(t, err)
+
+	decoded := &RecipientResponse{}
+	require.NoError(t, json.Unmarshal(raw, decoded))
+
+	assert.Nil(t, decoded.RecipientData, "echo path response must have nil RecipientData")
+	assert.Equal(t, original.Signature, decoded.Signature)
+}
+
+func TestExchangeRecipientResponse_JSONRoundTrip(t *testing.T) {
+	original := &ExchangeRecipientResponse{
+		RecipientData: &RecipientData{
+			Identity:  view.Identity("bob"),
+			AuditInfo: []byte("bob-audit"),
+		},
+		Signature: []byte("exchange-sig"),
+	}
+	raw, err := json.Marshal(original)
+	require.NoError(t, err)
+
+	decoded := &ExchangeRecipientResponse{}
+	require.NoError(t, json.Unmarshal(raw, decoded))
+
+	require.NotNil(t, decoded.RecipientData)
+	assert.Equal(t, original.RecipientData.Identity, decoded.RecipientData.Identity)
+	assert.Equal(t, original.Signature, decoded.Signature)
+}
+
+func TestRecipientRequest_NoncePreservedInJSON(t *testing.T) {
+	nonce := []byte("32-byte-nonce-for-testing-xxxxx!")
+	original := &RecipientRequest{
+		Nonce: nonce,
+	}
+	raw, err := json.Marshal(original)
+	require.NoError(t, err)
+
+	decoded := &RecipientRequest{}
+	require.NoError(t, json.Unmarshal(raw, decoded))
+	assert.Equal(t, nonce, decoded.Nonce)
+}
+
+func TestExchangeRecipientRequest_NoncePreservedInJSON(t *testing.T) {
+	nonce := []byte("exchange-nonce-32bytes-pad-xxxxx")
+	original := &ExchangeRecipientRequest{
+		Nonce: nonce,
+	}
+	raw, err := json.Marshal(original)
+	require.NoError(t, err)
+
+	decoded := &ExchangeRecipientRequest{}
+	require.NoError(t, json.Unmarshal(raw, decoded))
+	assert.Equal(t, nonce, decoded.Nonce)
+}
+
+func TestRecipientResponse_MissingSignature(t *testing.T) {
+	raw := []byte(`{"RecipientData":{"Identity":"YWxpY2U="}}`)
+	decoded := &RecipientResponse{}
+	require.NoError(t, json.Unmarshal(raw, decoded))
+	assert.Nil(t, decoded.Signature, "missing Signature field should unmarshal as nil")
+	assert.NotNil(t, decoded.RecipientData)
+}
+
+func TestRecipientResponse_MalformedJSON(t *testing.T) {
+	decoded := &RecipientResponse{}
+	err := json.Unmarshal([]byte("not json {{"), decoded)
+	require.Error(t, err)
+}