test(network-driver): fuzz areTokensSpent and queryTokens query limits

FuzzQueryStatesLedgerReadsAreBounded covered only queryStates. The other two
query functions share the same attack surface — an untrusted JSON array whose
length decides how many ledger reads one invocation performs — but not the code
behind it, so the existing target exercised none of it:

- queryStates uses each decoded string as a ledger key verbatim.
- areTokensSpent initializes the validator from the public parameters first and,
  when graph hiding is on, pushes every caller-supplied id through the key
  translator's composite-key builder — UTF-8 validation and rune scanning of
  attacker-controlled text.
- queryTokens decodes an array of token.ID structs (string plus uint64) rather
  than plain strings, and derives an output key from each element.

Add one target per function, each asserting the same invariant: for arbitrary
caller bytes the function never panics and never performs more than
MaxQueryItems ledger reads. Separate targets are also required by Go fuzzing,
which needs one target per input shape; areTokensSpent additionally fuzzes the
graph-hiding branch as a bool argument, so both branches are covered.

Each target gets a persisted seed corpus covering both limit boundaries plus
empty, truncated, wrong-shape and rejected-rune payloads, and a nightly matrix
entry. The queryTokens corpus keeps the two payloads that exposed the nil
*token.ID dereference fixed in the previous commit, so the panic is now caught
by a plain `go test` run and not only under -fuzz.

Deduplicate the public-parameters test fixture: the existing
writePublicParamsFile now delegates to a testing.TB helper the fuzz targets can
use via f.Setenv.

Signed-off-by: AkramBitar <akram@il.ibm.com>

Author: AkramBitar

.github/workflows/nightly-fuzz.yml

@@ -123,9 +123,15 @@ jobs:
           - name: driver-config-key-field-round-trip
             pkg: ./token/driver
             func: FuzzConfigKeyFieldRoundTrip
-          - name: tcc-query-limits
+          - name: tcc-query-states-limits
             pkg: ./token/services/network/fabric/tcc
             func: FuzzQueryStatesLedgerReadsAreBounded
+          - name: tcc-are-tokens-spent-limits
+            pkg: ./token/services/network/fabric/tcc
+            func: FuzzAreTokensSpentLedgerReadsAreBounded
+          - name: tcc-query-tokens-limits
+            pkg: ./token/services/network/fabric/tcc
+            func: FuzzQueryTokensLedgerReadsAreBounded
 
     steps:
       - name: Checkout code

docs/security/tcc_query_limits.md

@@ -86,8 +86,22 @@ the larger batch no longer fits.
   unconfigured `TokenChaincode` is shown to still be bounded by the defaults.
 - **Provider tests**: unset environment (resolves to defaults), partial override (unset fields still
   default), and an unparseable value (returns an error).
-- **Fuzzing**: `FuzzQueryStatesLedgerReadsAreBounded` asserts that for arbitrary caller bytes
-  `queryStates` never panics and never performs more than `MaxQueryItems` ledger reads. Its seed
-  corpus (`testdata/fuzz/FuzzQueryStatesLedgerReadsAreBounded/`) covers both boundaries plus empty,
-  truncated and wrong-shape payloads, and it runs nightly via
-  [`.github/workflows/nightly-fuzz.yml`](../../.github/workflows/nightly-fuzz.yml).
+- **Fuzzing**: one target per query function, each asserting that for arbitrary caller bytes the
+  function never panics and never performs more than `MaxQueryItems` ledger reads. The three are
+  separate targets because the surface behind the shared limit check differs:
+
+  | Target | Covers |
+  | --- | --- |
+  | `FuzzQueryStatesLedgerReadsAreBounded` | array-of-strings decode; each string is used as a ledger key verbatim |
+  | `FuzzAreTokensSpentLedgerReadsAreBounded` | same decode, plus validator initialization from the public parameters and — with graph hiding on, fuzzed as a second argument — the key translator's composite-key builder (UTF-8 validation and rune scanning of attacker-controlled text) |
+  | `FuzzQueryTokensLedgerReadsAreBounded` | array-of-`token.ID` decode (string + `uint64`) and output-key derivation from each element |
+
+  Each has a persisted seed corpus under `testdata/fuzz/<TargetName>/` covering both limit
+  boundaries plus empty, truncated, wrong-shape and rejected-rune payloads, and all three run
+  nightly via [`.github/workflows/nightly-fuzz.yml`](../../.github/workflows/nightly-fuzz.yml).
+
+  `FuzzQueryTokensLedgerReadsAreBounded` found a pre-existing nil-pointer dereference on its first
+  run: a `null` element in the JSON array decodes to a nil `*token.ID`, which
+  `translator.QueryTokens` dereferenced. It now reports a nil entry as an invalid request instead;
+  the payload that triggered it is kept in the corpus
+  (`nil-elements-panic-regression`, `single-nil-element-panic-regression`).

token/services/network/fabric/tcc/queryguard_test.go

@@ -7,6 +7,7 @@ SPDX-License-Identifier: Apache-2.0
 package tcc_test
 
 import (
+	"bytes"
 	"encoding/base64"
 	"encoding/json"
 	"os"
@@ -21,20 +22,29 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
-// newTestChaincode returns a TokenChaincode with the given query limits, a fake ledger stub, and
-// the public parameters wired through a temporary file (the mechanism the real chaincode uses when
-// the parameters are not burnt into the binary).
-func newTestChaincode(t *testing.T, limits tcc.QueryLimits) (*tcc.TokenChaincode, *mock.ChaincodeStubInterface) {
-	t.Helper()
+// publicParamsFile writes public parameters to a temporary file and returns its path. The chaincode
+// resolves its parameters from PublicParamsPathVarEnv when they are not burnt into the binary, and
+// AreTokensSpent needs them: it initializes the validator before serving a request.
+func publicParamsFile(tb testing.TB) string {
+	tb.Helper()
+
+	ppFile := filepath.Join(tb.TempDir(), "pp")
+	require.NoError(tb, os.WriteFile(ppFile, []byte(base64.StdEncoding.EncodeToString([]byte("public parameters"))), 0o600))
 
-	ppFile := filepath.Join(t.TempDir(), "pp")
-	require.NoError(t, os.WriteFile(ppFile, []byte(base64.StdEncoding.EncodeToString([]byte("public parameters"))), 0o600))
-	t.Setenv(tcc.PublicParamsPathVarEnv, ppFile)
+	return ppFile
+}
+
+// newChaincode returns a TokenChaincode with the given query limits and a fake ledger stub that
+// answers every read. graphHiding selects which branch of AreTokensSpent runs: with it on, every
+// caller-supplied id is pushed through the key translator before the read.
+func newChaincode(limits tcc.QueryLimits, graphHiding bool) (*tcc.TokenChaincode, *mock.ChaincodeStubInterface) {
+	ppm := &mock.PublicParametersManager{}
+	ppm.GraphHidingReturns(graphHiding)
 
 	cc := &tcc.TokenChaincode{
 		QueryLimits: limits,
 		TokenServicesFactory: func([]byte) (tcc.PublicParameters, tcc.Validator, error) {
-			return &mock.PublicParametersManager{}, &mock.Validator{}, nil
+			return ppm, &mock.Validator{}, nil
 		},
 	}
 	stub := &mock.ChaincodeStubInterface{}
@@ -44,6 +54,15 @@ func newTestChaincode(t *testing.T, limits tcc.QueryLimits) (*tcc.TokenChaincode
 	return cc, stub
 }
 
+// newTestChaincode returns a TokenChaincode with the given query limits, a fake ledger stub, and
+// the public parameters wired through a temporary file.
+func newTestChaincode(t *testing.T, limits tcc.QueryLimits) (*tcc.TokenChaincode, *mock.ChaincodeStubInterface) {
+	t.Helper()
+	t.Setenv(tcc.PublicParamsPathVarEnv, publicParamsFile(t))
+
+	return newChaincode(limits, false)
+}
+
 // stateKeys returns n state keys of a realistic shape and size.
 func stateKeys(n int) []string {
 	keys := make([]string, n)
@@ -182,28 +201,96 @@ func TestQueryFunctions_UnconfiguredChaincodeStillBounded(t *testing.T) {
 	}
 }
 
+// fuzzLimits are the limits the fuzz targets enforce. They are far tighter than the defaults so a
+// mutator working on short inputs still crosses both boundaries regularly.
+var fuzzLimits = tcc.QueryLimits{MaxQueryRequestBytes: 4096, MaxQueryItems: 8}
+
+// stringArraySeeds returns payload seeds for the query functions that take a JSON array of strings.
+func stringArraySeeds() [][]byte {
+	oversized := append([]byte(`["`), append(bytes.Repeat([]byte("a"), 8192), []byte(`"]`)...)...)
+
+	return [][]byte{
+		[]byte(`["a","b"]`), // valid, under the item cap
+		[]byte(`[]`),        // empty array
+		[]byte(``),          // empty payload
+		[]byte(`["a","b`),   // truncated
+		[]byte(`{"a":1}`),   // wrong JSON shape
+		[]byte(`["a","b","c","d","e","f","g","h"]`),     // exactly at the item cap
+		[]byte(`["a","b","c","d","e","f","g","h","i"]`), // one over the item cap
+		[]byte("[\"\u0000\",\"\U0010ffff\"]"),           // runes the composite-key builder rejects
+		[]byte(`["\udc00"]`),                            // invalid UTF-8 after JSON unescaping
+		oversized,                                       // over the byte cap
+	}
+}
+
 // FuzzQueryStatesLedgerReadsAreBounded asserts the invariant the limits exist to guarantee: whatever
 // bytes an untrusted caller supplies, QueryStates never panics and never performs more ledger reads
-// than MaxQueryItems.
+// than MaxQueryItems. QueryStates uses each decoded string as a ledger key verbatim.
 func FuzzQueryStatesLedgerReadsAreBounded(f *testing.F) {
-	limits := tcc.QueryLimits{MaxQueryRequestBytes: 4096, MaxQueryItems: 8}
+	for _, seed := range stringArraySeeds() {
+		f.Add(seed)
+	}
+
+	f.Fuzz(func(t *testing.T, raw []byte) {
+		cc, stub := newChaincode(fuzzLimits, false)
+
+		require.NotNil(t, cc.QueryStates(raw, stub))
+		require.LessOrEqual(t, stub.GetStateCallCount(), fuzzLimits.MaxQueryItems)
+	})
+}
+
+// FuzzAreTokensSpentLedgerReadsAreBounded fuzzes the same invariant for AreTokensSpent, which shares
+// the array-of-strings attack surface but not the code behind it: it initializes the validator from
+// the public parameters first, and — when graph hiding is on — pushes every caller-supplied id
+// through the key translator's composite-key builder (UTF-8 validation and rune scanning of
+// attacker-controlled text) before the read. The graphHiding argument fuzzes both branches.
+func FuzzAreTokensSpentLedgerReadsAreBounded(f *testing.F) {
+	f.Setenv(tcc.PublicParamsPathVarEnv, publicParamsFile(f))
+
+	for _, seed := range stringArraySeeds() {
+		f.Add(seed, false)
+		f.Add(seed, true)
+	}
+
+	f.Fuzz(func(t *testing.T, raw []byte, graphHiding bool) {
+		cc, stub := newChaincode(fuzzLimits, graphHiding)
+
+		require.NotNil(t, cc.AreTokensSpent(raw, stub))
+		require.LessOrEqual(t, stub.GetStateCallCount(), fuzzLimits.MaxQueryItems)
+	})
+}
+
+// FuzzQueryTokensLedgerReadsAreBounded fuzzes the same invariant for QueryTokens, whose surface is
+// wider again: it decodes an array of token.ID structs (a string plus a uint64) rather than plain
+// strings, and derives an output key from each one, so both the decoder and the key builder see
+// attacker-controlled input.
+func FuzzQueryTokensLedgerReadsAreBounded(f *testing.F) {
+	ids := func(n int) []byte {
+		raw, err := json.Marshal(tokenIDs(n))
+		if err != nil {
+			f.Fatal(err)
+		}
+
+		return raw
+	}
 
-	f.Add([]byte(`["a","b"]`))                                                  // valid, under the item cap
-	f.Add([]byte(`[]`))                                                         // empty array
-	f.Add([]byte(``))                                                           // empty payload
-	f.Add([]byte(`["a","b`))                                                    // truncated
-	f.Add([]byte(`{"a":1}`))                                                    // wrong JSON shape
-	f.Add([]byte(`["a","b","c","d","e","f","g","h"]`))                          // exactly at the item cap
-	f.Add([]byte(`["a","b","c","d","e","f","g","h","i"]`))                      // one over the item cap
-	f.Add(append([]byte(`["`), append(make([]byte, 8192), []byte(`"]`)...)...)) // over the byte cap
+	f.Add(ids(2))                                                                                      // valid, under the item cap
+	f.Add(ids(fuzzLimits.MaxQueryItems))                                                               // exactly at the item cap
+	f.Add(ids(fuzzLimits.MaxQueryItems + 1))                                                           // one over the item cap
+	f.Add([]byte(`[]`))                                                                                // empty array
+	f.Add([]byte(``))                                                                                  // empty payload
+	f.Add([]byte(`[{"tx_id":"a","index":1`))                                                           // truncated
+	f.Add([]byte(`["a"]`))                                                                             // wrong element type
+	f.Add([]byte(`[null,null]`))                                                                       // nil elements
+	f.Add([]byte(`[{"tx_id":"a","index":-1}]`))                                                        // index out of range for uint64
+	f.Add([]byte("[{\"tx_id\":\"\u0000\"}]"))                                                          // a rune the composite-key builder rejects
+	f.Add([]byte(`[{"tx_id":"a","index":18446744073709551615}]`))                                      // max uint64 index
+	f.Add(append([]byte(`[{"tx_id":"`), append(bytes.Repeat([]byte("a"), 8192), []byte(`"}]`)...)...)) // over the byte cap
 
 	f.Fuzz(func(t *testing.T, raw []byte) {
-		cc := &tcc.TokenChaincode{QueryLimits: limits}
-		stub := &mock.ChaincodeStubInterface{}
-		stub.GetTxIDReturns("txid")
+		cc, stub := newChaincode(fuzzLimits, false)
 
-		resp := cc.QueryStates(raw, stub)
-		require.NotNil(t, resp)
-		require.LessOrEqual(t, stub.GetStateCallCount(), limits.MaxQueryItems)
+		require.NotNil(t, cc.QueryTokens(raw, stub))
+		require.LessOrEqual(t, stub.GetStateCallCount(), fuzzLimits.MaxQueryItems)
 	})
 }

token/services/network/fabric/tcc/tcc_init_test.go

@@ -7,9 +7,6 @@ SPDX-License-Identifier: Apache-2.0
 package tcc_test
 
 import (
-	"encoding/base64"
-	"os"
-	"path/filepath"
 	"sync"
 	"sync/atomic"
 	"testing"
@@ -25,10 +22,7 @@ import (
 // parameters, so that TokenChaincode.Params succeeds and initialization reaches the factory.
 func writePublicParamsFile(t *testing.T) {
 	t.Helper()
-
-	path := filepath.Join(t.TempDir(), "pp")
-	require.NoError(t, os.WriteFile(path, []byte(base64.StdEncoding.EncodeToString([]byte("public parameters"))), 0o600))
-	t.Setenv(tcc.PublicParamsPathVarEnv, path)
+	t.Setenv(tcc.PublicParamsPathVarEnv, publicParamsFile(t))
 }
 
 // TestGetValidatorRetriesAfterFailedInitialization checks that a failed initialization attempt is

token/services/network/fabric/tcc/testdata/fuzz/FuzzAreTokensSpentLedgerReadsAreBounded/composite-key-rejected-rune-graph-hiding

@@ -0,0 +1,3 @@
+go test fuzz v1
+[]byte("[\"\\u0000\",\"\\U0010ffff\"]")
+bool(true)

token/services/network/fabric/tcc/testdata/fuzz/FuzzAreTokensSpentLedgerReadsAreBounded/empty-array

@@ -0,0 +1,3 @@
+go test fuzz v1
+[]byte("[]")
+bool(false)

token/services/network/fabric/tcc/testdata/fuzz/FuzzAreTokensSpentLedgerReadsAreBounded/empty-array-graph-hiding

@@ -0,0 +1,3 @@
+go test fuzz v1
+[]byte("[]")
+bool(true)

token/services/network/fabric/tcc/testdata/fuzz/FuzzAreTokensSpentLedgerReadsAreBounded/invalid-utf8-after-unescape-graph-hiding

@@ -0,0 +1,3 @@
+go test fuzz v1
+[]byte("[\"\\udc00\"]")
+bool(true)

token/services/network/fabric/tcc/testdata/fuzz/FuzzAreTokensSpentLedgerReadsAreBounded/max-query-items-boundary

@@ -0,0 +1,3 @@
+go test fuzz v1
+[]byte("[\"k0\",\"k1\",\"k2\",\"k3\",\"k4\",\"k5\",\"k6\",\"k7\"]")
+bool(false)

token/services/network/fabric/tcc/testdata/fuzz/FuzzAreTokensSpentLedgerReadsAreBounded/max-query-items-boundary-graph-hiding

@@ -0,0 +1,3 @@
+go test fuzz v1
+[]byte("[\"k0\",\"k1\",\"k2\",\"k3\",\"k4\",\"k5\",\"k6\",\"k7\"]")
+bool(true)