test+docs: hinted P-384 review tests and forward-compat documentation

[Willyham]

Follow-up to #28 (hinted P-384 Nitro attestation verification). This PR adds focused tests from a security review of the hinted change, and documents an attestation-parser forward-compatibility limitation that was previously undocumented.

Summary of the review

The hinting change is sound: every off-chain inverse is re-checked on-chain with b·inv ≡ 1 (mod m), the moduli are prime so the inverse is unique, and every later operation reduces mod the correct modulus — so a wrong/non-canonical hint can only revert, never forge. No false-accept path was found. The substantive findings are about liveness and integrator responsibilities, not forgery.

Tests (added to existing files, reusing the real fixture + helpers)

• test/hinted/HintedNitroAttestation.t.sol
  • test_UnreducedInverseHintIsSound — a non-canonical inverse hint (inv + p) passes the on-chain check and yields the identical reduced result, so it can't change the accept decision (exercised at the U384 level via a new U384TestWrapper).
  • test_ModulusConfusionHintReverts — a hint valid mod n is rejected where mod p is expected.
  • test_CorruptedSignatureNeverAccepts — no attacker hint stream (empty / garbage / original-valid / padded) makes a corrupted signature verify.
  • test_MalleableTwinSignatureAccepted — (r, n-s) also verifies (intentional, CURVE_LOW_S_MAX = n-1); decodes to the identical attestation, so signature bytes must not be used as a uniqueness key.
  • test_AttestationReplayHasNoOnChainProtection — the same (tbs, sig) verifies repeatedly; freshness/replay is the integrator's responsibility.
• test/IndefiniteLengthCbor.t.sol — two vm.skip'd forward-compat specs (unknown-key tolerance; nested indefinite-length pcrs parsing), co-located with the regression tests that pin current behaviour.
• test/CertManager.t.sol — vm.skip'd spec documenting the verifiedParent first-writer-wins cache-griefing edge (requires a same-key-renewed CA fixture to realise).

Docs

• docs/hinted-p384-nitro-attestation.md — new "Forward-compatibility (attestation format changes)" section.
• README.md — forward-compatibility note under Security considerations.
• src/NitroValidator.sol — NatSpec on _parseAttestation: the strict key whitelist and lack of nested indefinite-length support are liveness-only (can only revert, never a false accept) but forward-incompatible with AWS attestation-format changes. Tolerating unknown keys would be safe (all fields are under AWS's COSE signature).

Notes

• No production logic changes. src edits are NatSpec/comments only.
• Three tests are intentionally skipped — each carries a descriptive reason and documents a known latent liveness risk / un-fixturable scenario rather than failing the build.
• Full suite: 96 tests — 93 passed, 0 failed, 3 skipped.

🤖 Generated with Claude Code

[leanthebean]

Superseded by #33, which rebases this onto current main and scopes it down to the adversarial hinted-P-384 soundness tests (the genuinely additive part of this review). The rest has landed or moved: revocation in #29, and the forward-compatibility implementation + docs (skip unknown keys / nested indefinite-length CBOR) in #32 — so the L1/L2 skipped specs, README/design-doc forward-compat sections, and _parseAttestation NatSpec here would now duplicate or contradict #32 and are dropped in #33.

[leopoldjoy]

Closing in favour of #33.