fix(network-driver): bound tcc query request size and item count

The chaincode's read-only queries — queryStates, queryTokens, areTokensSpent —
performed one ledger read per element of an untrusted JSON array, with no cap on
array length or payload size. Unlike invoke, bounded by driver.ResourceLimits,
they are not reached through the size-limited transaction-submission flow, so
any client able to call them could drive an unbounded number of GetState calls
from a single request.

Add tcc.QueryLimits: MaxQueryRequestBytes (1 MiB, checked before the JSON
decode) and MaxQueryItems (4096, checked before the first ledger read). Defaults
replace any field left unset or negative, so an unconfigured chaincode is still
bounded; the standalone chaincode process overrides them via
TOKEN_QUERY_MAX_REQUEST_BYTES / TOKEN_QUERY_MAX_ITEMS. These limits are not
consensus-relevant: the query path performs no writes and is not an endorsement
boundary.

Also fix a nil-pointer dereference the new fuzzing found: a `null` element in a
queryTokens array decodes to a nil *token.ID that translator.QueryTokens
dereferenced.

Tests cover the exact boundaries, rejection with zero GetState calls for each of
the three query functions, and one fuzz target per function (persisted corpora
plus nightly matrix entries).

Fixes #2050

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

Author: AkramBitar

.github/workflows/nightly-fuzz.yml

@@ -123,6 +123,15 @@ jobs:
           - name: driver-config-key-field-round-trip
             pkg: ./token/driver
             func: FuzzConfigKeyFieldRoundTrip
+          - 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/configuration.md

@@ -551,6 +551,25 @@ out as a coordinated configuration change before any peer relies on the new valu
 
 ---
 
+### Optional: token chaincode query limits (environment only)
+
+The read-only query functions of the token chaincode (`queryStates`, `queryTokens`,
+`areTokensSpent`) perform one ledger read per element of the caller-supplied array, so they are
+bounded independently of `token.validation.limits`. These limits live in the chaincode process, not
+in the FSC node's configuration file, and are read from the environment:
+
+| Environment variable | Default | Bounds |
+| --- | --- | --- |
+| `TOKEN_QUERY_MAX_REQUEST_BYTES` | 1048576 (1 MiB) | Raw size of the query argument, checked before it is decoded |
+| `TOKEN_QUERY_MAX_ITEMS` | 4096 | Number of elements, checked before the first ledger read |
+
+Both are optional; an unset variable resolves to its default, and an unparseable value is a startup
+error. Unlike `token.validation.limits` these values are **not** consensus-relevant — the query path
+performs no writes and is not an endorsement boundary — so they do not need to match across peers.
+See [Token Chaincode Query Limits](security/tcc_query_limits.md).
+
+---
+
 ### Optional: token.fabricx.lookup
 
 If not specified, the default configuration is:

docs/security/tcc_query_limits.md

@@ -0,0 +1,111 @@
+# Token Chaincode Query Limits
+
+This page describes the limits enforced on the token chaincode's read-only query functions, why
+they exist, and how to configure them.
+
+## Why limits exist
+
+The token chaincode (`token/services/network/fabric/tcc`) exposes three read-only query functions:
+
+| Function | Argument | Work per element |
+| --- | --- | --- |
+| `queryStates` | JSON array of state keys | one `GetState` |
+| `queryTokens` | JSON array of `token.ID`s | one `GetState` |
+| `areTokensSpent` | JSON array of token/serial-number keys | one `GetState` |
+
+Every element the caller supplies translates 1:1 into a ledger read inside a *single* chaincode
+invocation. The `invoke` path is bounded by `driver.ResourceLimits` (see
+[Validator Resource Limits](../drivers/validation-resource-limits.md)), which rejects an oversized
+token request before any per-element work. The query path had no analogous guard: a single request
+carrying an arbitrarily long array drove an unbounded number of ledger reads, and — unlike `invoke`
+— it does not go through the size-limited transaction-submission flow. That is a resource-exhaustion
+/ peer-slowdown vector reachable by any client that can call the chaincode's query path, with no
+elevated privileges (issue #2050).
+
+## Configuration mechanism
+
+Limits are held in `tcc.QueryLimits` (`token/services/network/fabric/tcc/querylimits.go`) and read
+from the `QueryLimits` field of `tcc.TokenChaincode`:
+
+| Field | Default | Checked | Enforced |
+| --- | --- | --- | --- |
+| `MaxQueryRequestBytes` | 1 MiB | Raw size of the query argument | Before `json.Unmarshal`, so an oversized payload never reaches an allocation proportional to its own size |
+| `MaxQueryItems` | 4096 | Number of elements in the decoded array | After the decode and **before the first ledger read** |
+
+`MaxQueryItems` is the meaningful bound — it caps how many ledger reads one invocation can perform.
+`MaxQueryRequestBytes` is deliberately high enough that a full 4096-element batch of realistic state
+keys still fits, so the two limits do not shadow each other and the binding limit is predictable; it
+exists to reject a payload before decoding, including one made of few but enormous elements. Both
+defaults are far above the batch sizes produced by any in-tree caller
+(`lookup.DeliveryScanQueryByID`, `tokenFetcher.QueryTokens`, `spentTokenFetcher.QuerySpentTokens`).
+
+Violations return a typed error — `tcc.ErrQueryRequestTooLarge` or `tcc.ErrTooManyQueryItems` —
+wrapping the effective limit, surfaced to the caller as a chaincode error response.
+
+`QueryLimits.WithDefaults()` overlays `DefaultQueryLimits()` onto any field that is not a positive
+value, and the chaincode applies it on every query. Consequently a `TokenChaincode` built without
+setting `QueryLimits` is still bounded by the defaults, and a partially-specified override (or a
+negative value from a configuration typo) can never silently disable a limit.
+
+The standalone chaincode process (`token/services/network/fabric/tcc/main/main.go`) has no
+configuration service wired, so it resolves the limits from the environment via
+`tcc.EnvQueryLimitsProvider` — mirroring `tcc.EnvResourceLimitsProvider` for validation limits:
+
+| Environment variable | Field |
+| --- | --- |
+| `TOKEN_QUERY_MAX_REQUEST_BYTES` | `MaxQueryRequestBytes` |
+| `TOKEN_QUERY_MAX_ITEMS` | `MaxQueryItems` |
+
+Each variable is optional; an unset variable leaves the field at zero, which `WithDefaults` then
+replaces with the default. An unparseable value is a startup error, not a silent fallback.
+
+## Relationship to the consensus-safety contract
+
+Unlike `driver.ResourceLimits`, these limits are **not** consensus-relevant. The query functions
+perform no writes and are reached through the query/evaluate path rather than through endorsement,
+so a peer configured with a stricter value only refuses a request another peer would serve — it
+cannot make two peers disagree on a transaction's validity. Query limits are therefore an
+operational knob per chaincode process, not a value that must be rolled out in lockstep.
+
+## Choosing and changing these values
+
+Clients that legitimately need to look up more than `MaxQueryItems` keys should chunk their
+requests. If a deployment instead raises `TOKEN_QUERY_MAX_ITEMS`, keep in mind that the value
+directly bounds the ledger reads a single unauthenticated request can trigger — raise it only as far
+as observed legitimate batch sizes require, and raise `TOKEN_QUERY_MAX_REQUEST_BYTES` alongside it if
+the larger batch no longer fits.
+
+## Testing
+
+- **Exact-boundary unit tests** (`querylimits_test.go`): every field asserts `limit-1` / `limit`
+  succeed and `limit+1` fails with the specific typed error, against both the defaults and an
+  injected override.
+- **Regression tests** (`queryguard_test.go`): for each of the three query functions, an
+  over-counted request and an oversized payload are both rejected with **zero** `GetState` calls; a
+  request at exactly `MaxQueryItems` is served and performs exactly one read per element; and an
+  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**: 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 |
+
+  In-code `f.Add` seeds cover both limit boundaries plus empty, truncated, wrong-shape and
+  rejected-rune payloads. `testdata/fuzz/<TargetName>/` holds only what benefits from living on disk
+  — the `MaxQueryItems` boundary pair (the limit that bounds ledger reads) and the crash
+  reproducers, which Go writes there itself and whose named files report as named subtests. The
+  corpus fuzzing *generates* is not committed: it lives in `$GOCACHE/fuzz` and CI restores it only
+  best-effort, so these files are the durable floor. All three targets 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 two payloads that triggered it are kept on disk (`nil-elements-panic-regression`,
+  `single-nil-element-panic-regression`), so the panic is caught by a plain `go test` run.

docs/services/network-fabric.md

@@ -48,6 +48,16 @@ The chaincode exposes the following functions:
 | `areTokensSpent` | Check if tokens are spent | Token IDs, metadata      | Boolean array |
 | `queryStates` | Query arbitrary state keys | State keys               | State values |
 
+### Query Limits
+
+`queryTokens`, `areTokensSpent` and `queryStates` each turn every element of the caller-supplied
+array into one ledger read within a single invocation, so both the raw argument size and the number
+of elements are bounded before any read happens (`MaxQueryRequestBytes`, default 1 MiB;
+`MaxQueryItems`, default 4096). The defaults apply even when the chaincode is built without
+configuring them, and the standalone chaincode process can override them via
+`TOKEN_QUERY_MAX_REQUEST_BYTES` / `TOKEN_QUERY_MAX_ITEMS`. Clients that need more keys than the cap
+must chunk their requests. See [Token Chaincode Query Limits](../security/tcc_query_limits.md).
+
 ### Chaincode Deployment
 
 The Token Chaincode must be deployed to the Fabric network before Panurus can operate:

token/services/network/common/rws/translator/querytokens_test.go

@@ -0,0 +1,61 @@
+/*
+Copyright IBM Corp. All Rights Reserved.
+
+SPDX-License-Identifier: Apache-2.0
+*/
+
+package translator_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/LFDT-Panurus/panurus/token/services/network/common/rws/keys"
+	"github.com/LFDT-Panurus/panurus/token/services/network/common/rws/translator"
+	"github.com/LFDT-Panurus/panurus/token/services/network/common/rws/translator/mock"
+	"github.com/LFDT-Panurus/panurus/token/token"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func newQueryTokensTranslator() (*translator.Translator, *mock.RWSet) {
+	rws := &mock.RWSet{}
+	rws.GetStateReturns([]byte("value"), nil)
+
+	return translator.New("0", translator.NewRWSetWrapper(rws, tokenNameSpace, "0"), &keys.Translator{}), rws
+}
+
+// The ids reach QueryTokens straight from a JSON array decoded on the chaincode's query path, where
+// a `null` element decodes to a nil *token.ID. A nil entry must be reported as an invalid request
+// rather than dereferenced, and must not stop the ledger read of the valid ids around it.
+func TestQueryTokens_NilIDIsRejectedNotDereferenced(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		ids  []*token.ID
+	}{
+		{"only a nil id", []*token.ID{nil}},
+		{"nil id first", []*token.ID{nil, {TxId: "tx", Index: 0}}},
+		{"nil id last", []*token.ID{{TxId: "tx", Index: 0}, nil}},
+		{"all nil ids", []*token.ID{nil, nil}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			w, _ := newQueryTokensTranslator()
+
+			var res [][]byte
+			var err error
+			require.NotPanics(t, func() { res, err = w.QueryTokens(context.Background(), tc.ids) })
+			require.Error(t, err)
+			require.ErrorContains(t, err, "nil token id at index")
+			assert.Nil(t, res)
+		})
+	}
+}
+
+func TestQueryTokens_ValidIDsAreRead(t *testing.T) {
+	w, rws := newQueryTokensTranslator()
+
+	res, err := w.QueryTokens(context.Background(), []*token.ID{{TxId: "tx", Index: 0}, {TxId: "tx", Index: 1}})
+	require.NoError(t, err)
+	assert.Len(t, res, 2)
+	assert.Equal(t, 2, rws.GetStateCallCount())
+}

token/services/network/common/rws/translator/translator.go

@@ -134,7 +134,15 @@ func (t *Translator) AddPublicParamsDependency() error {
 func (t *Translator) QueryTokens(ctx context.Context, ids []*token.ID) ([][]byte, error) {
 	var res [][]byte
 	var errs []error
-	for _, id := range ids {
+	for i, id := range ids {
+		if id == nil {
+			// The ids come from an untrusted caller (the chaincode decodes them straight from a
+			// JSON array, where a `null` element decodes to a nil pointer), so a nil entry is an
+			// invalid request, not a programming error to panic on.
+			errs = append(errs, errors.Errorf("nil token id at index [%d]", i))
+
+			continue
+		}
 		outputID, err := t.KeyTranslator.CreateOutputKey(id.TxId, id.Index)
 		if err != nil {
 			errs = append(errs, errors.Errorf("error creating output ID: %s", err))

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

@@ -61,6 +61,9 @@ func main() {
 	limits, err := tcc.NewEnvResourceLimitsProvider().ResourceLimits()
 	assertNoError(err, "cannot resolve validation resource limits")
 
+	queryLimits, err := tcc.NewEnvQueryLimitsProvider().QueryLimits()
+	assertNoError(err, "cannot resolve query limits")
+
 	is := core.NewValidatorDriverService(
 		limits,
 		fabtoken.NewValidatorDriver(),
@@ -73,6 +76,7 @@ func main() {
 		}
 		err := shim.Start(
 			&tcc.TokenChaincode{
+				QueryLimits: queryLimits,
 				TokenServicesFactory: func(bytes []byte) (tcc.PublicParameters, tcc.Validator, error) {
 					ppm, err := is.PublicParametersFromBytes(bytes)
 					if err != nil {
@@ -118,6 +122,7 @@ func main() {
 			CCID:    config.CCID,
 			Address: config.CCaddress,
 			CC: &tcc.TokenChaincode{
+				QueryLimits: queryLimits,
 				TokenServicesFactory: func(bytes []byte) (tcc.PublicParameters, tcc.Validator, error) {
 					ppm, err := is.PublicParametersFromBytes(bytes)
 					if err != nil {