Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion docs/audit-non-issues.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,11 +98,14 @@ observing an append error.
| Proof encoding truncates keys ≥ 256 bytes | Unreachable: every public insert path (direct + batch) enforces the 255-byte key limit (PR #506), so oversized keys cannot reach proof encoding. The `debug_assert!` is sufficient. Raw-Merk hardening exists separately (#728). |
| `feature_type` forgery in `KVValueHashFeatureType` proof nodes | The decoded `_feature_type` is discarded by the verifier; the canonical type/sum/count lives in the hash-verified `Element` bytes. Forged values never reach callers. Documented in `verify.rs` comments and `proof_exploit_tests.rs`. |
| `saturating_sub` on negative `SumItem` values corrupts `sum_limit` | Correct as written: `sum_limit` tracks the remaining **net sum** budget; +7 and −4 must consume 3, not 11. Absolute-value math would be the bug. |
| The merk-level V1 guard (`execute_proof`, proof version 1) rejects items on `KVValueHash` / `KVValueHashFeatureType` nodes but lets **reference** elements through, so reference bytes on those nodes are unbound at the Merk level | True at the Merk level and deliberate. A reference row past the query limit legitimately stays a bare `KVValueHash` in released V1 proofs (the GroveDB post-pass only rewrites rows within the limit into `KVRefValueHash*`), so refusing references there would reject honest proofs. The only consumer of those rows, `verify_layer_proof_v1`, rejects any raw `Reference` / `ReferenceWithSumItem` row it consumes — before the element type is used for a result or a descent decision — and its limit accounting stops it before the beyond-limit node is ever read. The exploitable half of this claim (forged reference row returned as a result; forged reference hiding a populated subtree by skipping its descent) was real and is fixed via [#862](https://github.com/dashpay/grovedb/issues/862); see `docs/book/src/proof-system.md` "Which node forms bind their value bytes" and `grovedb/src/tests/unbound_reference_row_tests.rs`. |
| [#691](https://github.com/dashpay/grovedb/issues/691) (closed) — a dense proof carrying only `node_hashes: [(0, root)]` and no entries verifies against a non-empty tree | The behavior is real but no in-repo verifier accepts it as an absence claim. `verify_for_query` (`grovedb-dense-fixed-sized-merkle-tree/src/verify.rs:86`) derives `expected_positions` from the query and errors on any missing position (`:108`); GroveDB uses exactly this when `report_contents == true` (`proof/verify.rs:2669`). When `report_contents == false` (`verify.rs:2644`) the entries are discarded and the root is forced to the parent-committed child hash by `combine_hash` (`verify.rs:2018`). The BulkAppend/CommitmentTree path calls the unbound `verify_and_get_root`, but the prover-chosen `dense_root` must satisfy `compute_state_root` against the trusted root (`grovedb-bulk-append-tree/src/proof/mod.rs:517`), and both `verify_against_query` (`:592-610`) and `verify_bulk_append_lower_layer` (`proof/verify.rs:2498-2515`) run their own missing-position check. The sibling bypasses from the same audit batch were already pinned by `test_vuln1_node_hashes_{root,ancestor}_bypass_rejected` (`tests.rs:247,270`), which date to the crate's first commit `6e4855f6` (2026-02-23) and so predate the filing. |

**Becomes real if:** a new write path bypasses the 255-byte key check, a
verifier starts trusting a decoded field instead of the hash-verified
element bytes, or a consumer calls the dense crate's
element bytes, a V1 code path other than `verify_layer_proof_v1` starts
reading the value bytes of a `KVValueHash*` row (the merk-level guard does
not cover reference bytes there), or a consumer calls the dense crate's
`verify_against_expected_root` / `verify_and_get_root` directly and treats
"verified, zero entries" as proof of absence without a completeness check.

Expand Down
36 changes: 36 additions & 0 deletions docs/book/src/proof-system.md
Original file line number Diff line number Diff line change
Expand Up @@ -381,6 +381,42 @@ impl Tree {
}
```

### Which node forms bind their value bytes

A proof node's value bytes reach the caller as the proven element, so the
verifier has to know, for every node form, *what* binds those bytes to the
root hash. Two forms — `KVValueHash` and `KVValueHashFeatureType` — hash
only `(key, value_hash)`: the bytes they carry are not covered by the Merk
chain at all, and a prover can pair any bytes with a genuine `value_hash`.
The V1 verifier therefore admits only elements whose bytes are bound
somewhere else onto them:

| Element family on a `KVValueHash*` node | Verdict | What binds the bytes |
|---|---|---|
| Tree (any Merk or non-Merk tree) | accepted | The GroveDB layer recomputes `combine_hash(H(value), child)` from the lower layer, from `NULL_HASH` for an empty tree, or from the `child_hash` carried by `KVValueHashFeatureTypeWithChildHash`. |
| Item (`Item`, `SumItem`, `ItemWithSumItem`) | rejected by the Merk verifier at proof version 1 | Nothing — items commit the plain `H(value)` and must ride on `KV` / `KVCount` / `KVSum` / `KVCountSum`, where the verifier recomputes the hash from the bytes. |
| Reference (`Reference`, `ReferenceWithSumItem`, wrapped or not) | passes the Merk verifier; **rejected by `verify_layer_proof_v1` the moment it is consumed as a row** | Nothing on the node — references commit `combine_hash(H(reference), H(target))` and every row the GroveDB verifier consumes is served as `KVRefValueHash{,Count,Sum,CountSum}`, which hashes the **target** bytes and carries only `H(reference)`. Inside a sum-budget window a reference row rides on `KVValueHashFeatureTypeWithChildHash`, whose own `combine_hash(H(value), child_hash)` check binds it. |

The reference rule lives in the GroveDB layer rather than the Merk
verifier on purpose. A reference row that lies *past* the query limit
legitimately stays a bare `KVValueHash` in released V1 proofs: the GroveDB
post-pass only rewrites rows within the limit, and the GroveDB verifier
stops consuming rows the moment its limit accounting is exhausted, so that
node is never read. Refusing references at the Merk level would therefore
reject honest proofs; refusing them at the row consumer covers every row
that can influence a result or a descent.

Without that rule an attacker could take an honest
`KVRefValueHash(key, target, H(reference))` node, recompute the combined
value hash it commits to, and re-present the row as
`KVValueHash(key, <forged reference bytes>, combined)`. The Merk root still
reconstructs, and the GroveDB layer would either return the forged
reference — an attacker-chosen target path — as the proven element, or,
when the query descends at that key, silently skip the descent (a reference
has no lower layer) and verify a proof that hides a populated subtree
(issue #862). `verify_layer_proof_v1` now refuses any raw reference row
before the row's element type is consulted for either purpose.

## Absence Proofs

GroveDB can prove that a key does **not** exist. This uses boundary nodes —
Expand Down
32 changes: 32 additions & 0 deletions grovedb/src/operations/proof/verify.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1665,6 +1665,38 @@ impl GroveDb {
let element =
Element::deserialize(value_bytes, grove_version)?.into_underlying();

// A raw reference can never be an honest V1 row. The
// prover rewrites every reference the verifier will
// consume into a `KVRefValueHash*` node carrying the
// dereferenced TARGET bytes, so the bytes surfaced
// here are the target's — never the reference's own.
// A `KVValueHash` / `KVValueHashFeatureType` node
// hashes only `(key, value_hash)`, and the merk-level
// V1 guard refuses only *items* on those forms (it
// cannot refuse references: a reference row past the
// query limit legitimately stays bare there, and this
// loop stops before reading it). So a forged proof can
// pair genuine `value_hash` with arbitrary reference
// bytes and still reconstruct the root. This is the
// check that binds the row: refuse before the element
// type can be returned as unauthenticated reference
// metadata, or make "a reference has no lower layer"
// silently skip a descent the query asked for
// (issue #862).
if element.is_reference() {
return Err(Error::InvalidProof(
query.clone(),
format!(
"V1 proof surfaces a raw {} at key {}: the prover serves \
references as KVRefValueHash nodes carrying the dereferenced \
target, so an unresolved reference row is unbound and \
malformed",
element.type_str(),
hex::encode(key),
),
));
}

verified_keys.insert(key.clone());

// Axis-ordered read: resolved from the QUERY first —
Expand Down
1 change: 1 addition & 0 deletions grovedb/src/tests/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,7 @@ mod test_compaction_sizes;
mod test_provable_count_fresh;
mod tree_hashes_tests;
mod trunk_proof_tests;
mod unbound_reference_row_tests;
mod v1_cidx_descent_tests;
mod v1_proof_tests;
mod verify_grovedb_indexed_tests;
Expand Down
7 changes: 6 additions & 1 deletion grovedb/src/tests/unbound_empty_tree_tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -532,8 +532,13 @@ fn unbound_non_tree_classification_under_a_subquery_is_rejected() {
match outcome {
Err(e) => {
let message = format!("{e}");
// Since #862 a raw reference row is refused as soon as
// it is deserialized — before the arm chain can classify
// it — so the specific rejection fires ahead of the
// last-resort one. Either way the forgery is rejected.
assert!(
message.contains("neither descended into nor bound"),
message.contains("raw reference")
|| message.contains("neither descended into nor bound"),
"include_empty={include_empty}: got: {message}"
);
}
Expand Down
Loading
Loading