feat(detector): flag BLS12-381 proof points reaching a pairing without a subgroup check

Adds `bls_subgroup_check` (SANCT_BLS_SUBGROUP_UNCHECKED), which flags
BLS12-381 pairing usage where a proof point reaches the pairing call with
nothing having established subgroup or curve membership.

The pairing e: G1 x G2 -> GT is defined on the prime-order subgroups, not the
full curve. BLS12-381 has a cofactor in both groups (~2^64 in G1, ~2^318 in
G2), so the curve holds plenty of points outside the subgroup a proof system
reasons about. Pairing one of those evaluates the map outside the domain the
soundness argument covers, and two things follow:

- Malleability. Given a valid proof point P, an attacker can often produce
  P + T for a small-order T such that the verification equation still holds.
  The proof serializes differently but verifies identically, so any replay
  defence keyed on the proof bytes — a used-proof set, a nullifier derived
  from the encoding — is bypassed with a fresh-looking submission.
- Forgery. Off-subgroup, the relations the verifier checks no longer pin the
  witness down. This is the mechanism behind the small-subgroup attacks that
  made subgroup checks mandatory in the BLS signature standard.

The check costs a scalar multiplication per point, which is exactly why
implementations reach for the _unchecked variants and why this survives
review. Skipping it is safe only for points the contract produced itself.

Two shapes are reported, both of which put an unvalidated point in front of a
pairing:

1. A point built with an _unchecked constructor or deserializer
   (deserialize_uncompressed_unchecked, from_compressed_unchecked,
   new_unchecked, ...). In arkworks these are precisely the entry points that
   skip the subgroup check.
2. A point arriving already typed as G1Affine / G2Affine / G1Projective /
   G2Projective. Deserialization happened elsewhere, so nothing in this
   function establishes membership.

False positives are held down three ways. The rule gates on the file actually
using BLS12-381 before parsing at all, so an _unchecked constructor in
unrelated code means nothing here. It requires a pairing, miller_loop,
final_exponentiation or verify call to be reached — deserializing a point for
storage makes no verification claim. And any membership check in the function
silences it, including the correct arkworks idiom of unchecked deserialization
followed by an explicit is_in_correct_subgroup_assuming_on_curve. Mapping into
the subgroup with clear_cofactor / mul_by_cofactor is accepted too, since
that is a valid remedy where rejecting is not appropriate.

`#[cfg(test)]` modules are skipped and inline
`sanctifier:ignore[SANCT_BLS_SUBGROUP_UNCHECKED]` is honoured, matching the
conventions of the surrounding rules.

Documented in docs/detectors/bls_subgroup_check.md with the cofactor figures,
the vulnerable shape, the fix (both conditions — is_in_correct_subgroup_-
assuming_on_curve assumes on-curve, as the name says), and references: the
CFRG BLS signature draft's KeyValidate requirement, Sean Bowe on BLS12-381's
cofactor structure, the 0xPARC ZK Bug Tracker, Trail of Bits on proof
malleability, and arkworks' Validate::Yes/No documentation for what the
_unchecked variants actually skip. Rows added to the detector catalog and the
finding-code table; the docs-coverage test enforces both.

Tests: 7 unit tests covering both flagged shapes, both accepted check forms,
the non-BLS and never-pairs cases, and suppression.

Note for reviewers: two pre-existing failures in `memory::tests` reproduce on
an unmodified checkout of main on macOS (memory sampling) and are unrelated to
this change.

Author: Alheriii

docs/detectors/README.md

@@ -28,6 +28,7 @@ detector page and to the relevant [Glossary](../glossary.md) term.
 | [`unhandled_result`](unhandled_result.md) | [`S009`](../error-codes.md) | logic | Medium | A `Result` that is silently dropped |
 | [`hardcoded_addr`](hardcoded_addr.md) | [`S012`](../error-codes.md) | code_hygiene | High | Hardcoded admin address / secret literal in an auth context |
 | [`edge_amount`](edge_amount.md) | [`S013`](../error-codes.md) | code_hygiene | Medium | `transfer`/`mint`/`burn` missing `amount > 0` / `from != to` guards |
+| [`bls_subgroup_check`](bls_subgroup_check.md) | [`SANCT_BLS_SUBGROUP_UNCHECKED`](../error-codes.md) | cryptography | Error | BLS12-381 proof point reaches a pairing call with no subgroup or curve membership check |
 | [`balance_equality`](balance_equality.md) | [`SANCT_BALANCE_EQ`](../error-codes.md) | logic | Info | Balance gated with `==`/`!=` where `>=`/`<=` was intended |
 | [`unused_variable`](unused_variable.md) | [`S015`](../error-codes.md) | code_hygiene | Info | Unused local bindings (dead code) |
 | [`error_code_collision`](error_code_collision.md) | [`S016`](../error-codes.md) | code_hygiene | Medium | Duplicate/inconsistent `#[contracterror]` discriminants |

docs/detectors/bls_subgroup_check.md

@@ -0,0 +1,97 @@
+# `bls_subgroup_check` — BLS12-381 point reaches a pairing without a subgroup check
+
+| | |
+| --- | --- |
+| **Finding code** | [`SANCT_BLS_SUBGROUP_UNCHECKED`](../error-codes.md) |
+| **Category** | cryptography |
+| **Severity** | Error |
+| **Source rule** | [`rules/bls_subgroup_check.rs`](../../tooling/sanctifier-core/src/rules/bls_subgroup_check.rs) |
+| **Glossary** | [Proof](../glossary.md#proof) · [Pairing](../glossary.md#pairing) |
+
+## What it catches
+
+In a file that uses BLS12-381, a function that reaches a pairing call
+(`pairing`, `miller_loop`, `final_exponentiation`, or any `verify`) with a
+proof point that nothing has checked for subgroup membership. Two shapes:
+
+1. **An `_unchecked` constructor or deserializer** —
+   `deserialize_uncompressed_unchecked`, `from_compressed_unchecked`,
+   `new_unchecked`, and friends. In arkworks these are precisely the entry
+   points that skip the subgroup check.
+2. **A point arriving as a typed parameter** — `G1Affine`, `G2Affine`,
+   `G1Projective`, `G2Projective`. Deserialization happened elsewhere, so
+   nothing in this function establishes membership.
+
+## Why it matters
+
+The pairing `e: G1 × G2 → GT` is defined on the **prime-order subgroups**, not
+on the full curve. BLS12-381 has a cofactor in both groups — `h₁ ≈ 2⁶⁴` in G1
+and `h₂ ≈ 2^318` in G2 — so the curve contains plenty of points outside the
+subgroup a proof system reasons about. Feeding one to the pairing evaluates it
+outside the domain the soundness argument covers, and two things follow:
+
+**Malleability.** Given a valid proof point `P`, an attacker can often produce
+`P + T` for a small-order `T` such that the verification equation still holds.
+The proof serializes differently but verifies identically, so any replay
+defence keyed on the proof bytes — a "this proof was already used" set, a
+nullifier derived from the encoding — is bypassed with a fresh-looking
+submission.
+
+**Forgery.** Off-subgroup, the algebraic relations the verifier checks no
+longer pin the witness down. This is the mechanism behind the small-subgroup
+attacks that motivated mandatory subgroup checks in the BLS signature standard,
+and the same reasoning applies to any pairing-based proof verifier.
+
+The check is not free — it is a scalar multiplication per point — which is
+exactly why implementations reach for the `_unchecked` variants and why this
+bug survives review. Skipping the check is safe only for points the contract
+itself produced, never for anything a caller supplied.
+
+## Vulnerable example
+
+```rust
+use ark_bls12_381::{Bls12_381, G1Affine, G2Affine};
+
+fn verify_proof(proof_bytes: &[u8], vk: &VerifyingKey) -> bool {
+    // `_unchecked` skips the subgroup check by design, and nothing here
+    // performs it afterwards.
+    let a = G1Affine::deserialize_uncompressed_unchecked(proof_bytes).unwrap();
+    let b = G2Affine::deserialize_uncompressed_unchecked(proof_bytes).unwrap();
+    Bls12_381::pairing(a, b) == vk.alpha_beta
+}
+```
+
+## The fix
+
+Either use the checked deserializer, or keep the fast path and do the check
+explicitly:
+
+```rust
+let a = G1Affine::deserialize_uncompressed_unchecked(proof_bytes)?;
+if !a.is_on_curve() || !a.is_in_correct_subgroup_assuming_on_curve() {
+    return Err(Error::InvalidProofPoint);
+}
+```
+
+Both conditions are needed: `is_in_correct_subgroup_assuming_on_curve`, as its
+name says, assumes the point is on the curve to begin with. Mapping into the
+subgroup with `clear_cofactor()` / `mul_by_cofactor()` is also accepted by the
+detector where rejecting is not appropriate.
+
+## What it does *not* flag
+
+- Files that do not use BLS12-381 at all.
+- BLS code that never reaches a pairing — deserializing a point for storage
+  makes no verification claim.
+- Any function where a membership check is present.
+- `#[cfg(test)]` modules, and lines carrying
+  `// sanctifier:ignore[SANCT_BLS_SUBGROUP_UNCHECKED]`.
+
+## References
+
+- [RFC 9380 §2.1 / IRTF CFRG BLS signatures draft, "Subgroup checks"](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-bls-signature-05#section-5.2) — mandatory `KeyValidate` / subgroup validation and why
+- [Sean Bowe — *BLS12-381: New zk-SNARK Elliptic Curve Construction*](https://electriccoin.co/blog/new-snark-curve/) — cofactor structure of G1 and G2
+- [0xPARC — *ZK Bug Tracker*: "Missing curve/subgroup checks"](https://github.com/0xPARC/zk-bug-tracker)
+- [Trail of Bits — *Breaking the Shield*](https://blog.trailofbits.com/2022/04/13/part-1-coordinated-disclosure-of-vulnerabilities-affecting-girault-bulletproofs-and-plonk/) — proof malleability from unchecked group elements
+- [arkworks `CanonicalDeserialize` — `Validate::Yes` vs `Validate::No`](https://docs.rs/ark-serialize/latest/ark_serialize/enum.Validate.html) — what the `_unchecked` variants actually skip
+- [`verifier-checklist.md`](../verifier-checklist.md) — the wider verifier integration checklist

docs/error-codes.md

@@ -22,6 +22,7 @@ the fix, and references.
 | `S016` | code_hygiene | Duplicate/inconsistent `#[contracterror]` discriminants | [`error_code_collision`](detectors/error_code_collision.md) |
 | `S017` | arithmetic | Fee/interest integer division that rounds to zero for micro-amounts | [`fee_rounding`](detectors/fee_rounding.md) |
 | `SANCT_ARG_DOS` | denial_of_service | `Vec`/`Map` argument iterated without a length cap | [`arg_dos`](detectors/arg_dos.md) |
+| `SANCT_BLS_SUBGROUP_UNCHECKED` | cryptography | BLS12-381 proof point reaches a pairing call with no subgroup or curve membership check | [`bls_subgroup_check`](detectors/bls_subgroup_check.md) |
 | `SANCT_UNWRAP` | panic_handling | `unwrap` / `expect` / risky `unwrap_or_default` inside `#[contractimpl]` entrypoints; replace with typed errors or explicit domain defaults | [`sanct_unwrap`](detectors/sanct_unwrap.md) |
 | `SANCT_VISIBILITY` | authentication | Helper-shaped state mutator exposed through `#[contractimpl]` without authorization | [`sanct_visibility`](detectors/sanct_visibility.md) |
 | `SANCT_UNBOUNDED_STORAGE` | denial_of_service | Persistent/instance collection grows via append/insert with no removal or length cap | [`unbounded_storage`](detectors/unbounded_storage.md) |

tooling/sanctifier-core/src/finding_codes.rs

@@ -23,6 +23,7 @@ pub const LEDGER_SECONDS: &str = "S021";
 pub const EXCESSIVE_CLONE: &str = "S020";
 pub const ARG_DOS: &str = "SANCT_ARG_DOS";
 pub const BALANCE_EQUALITY: &str = "SANCT_BALANCE_EQ";
+pub const BLS_SUBGROUP_UNCHECKED: &str = "SANCT_BLS_SUBGROUP_UNCHECKED";
 pub const SANCT_UNWRAP: &str = "SANCT_UNWRAP";
 pub const INIT_HARDCODED_ADMIN: &str = "SANCT_INIT_HARDCODED_ADMIN";
 pub const SANCT_VISIBILITY: &str = "SANCT_VISIBILITY";
@@ -127,6 +128,12 @@ pub fn all_finding_codes() -> Vec<FindingCode> {
             description:
                 "Balance gated against an amount with `==`/`!=` where `>=`/`<=` was likely intended",
         },
+        FindingCode {
+            code: BLS_SUBGROUP_UNCHECKED,
+            category: "cryptography",
+            description:
+                "BLS12-381 proof point reaches a pairing call with no subgroup or curve membership check",
+        },
         FindingCode {
             code: DEPRECATED_SDK,
             category: "code_hygiene",