docs: add formal threat model for compliance primitives (#112)

[gabrielujelistic-collab]

Formal threat model for allowlist-token, denylist-gate, jurisdiction-flag

Summary

Closes #112

Adds docs/THREAT_MODEL.md, a formal threat-model document distinct from the
pending SPEC.md (#29). It enumerates and analyses attack scenarios for the
three compliance-critical contracts along the three axes the issue requires:

• Griefing — including the call-out about repeatedly calling public reads to
  run up resource fees, and whether any function lets a non-admin write storage.
• Front-running — including the add_to_allowlist vs transfer (and
  denylist/jurisdiction vs gated-action) ordering question within a ledger close.
• Admin-key-compromise — what a compromised admin/issuer can and can't do,
  and how quickly damage is bounded given two-step admin transfer (Implement a two-step admin transfer (propose/accept) for allowlist-token #74/Implement a two-step admin transfer (propose/accept) for denylist-gate #75/Implement a two-step issuer transfer (propose/accept) for jurisdiction-flag #76)
  and pause (Add a pausable trait to denylist-gate (admin can pause add/remove, not check) #84/Add a pausable trait to jurisdiction-flag (issuer can pause set_jurisdiction) #85) once they land.

Coverage vs acceptance criteria

• docs/THREAT_MODEL.md covering griefing, front-running, and
  admin-key-compromise for allowlist-token, denylist-gate, and
  jurisdiction-flag individually (sections 1–3).
• Each scenario is rated for severity × likelihood and cross-referenced to
  an existing mitigation (a function such as pause/unpause, propose_admin/
  accept_admin, multisig signers, or upgrade) or a pending issue number
  (Implement a two-step admin transfer (propose/accept) for allowlist-token #74/Implement a two-step admin transfer (propose/accept) for denylist-gate #75/Implement a two-step issuer transfer (propose/accept) for jurisdiction-flag #76 two-step admin, Add a pausable trait to denylist-gate (admin can pause add/remove, not check) #84/Add a pausable trait to jurisdiction-flag (issuer can pause set_jurisdiction) #85 pause, Add upgradeability pattern (contract migration path) to allowlist-token #113 upgradeability) where the
  mitigation has not yet landed.
• Flagged for review by another contributor before merge (required by the
  issue), and noted explicitly at the bottom of the doc.

Key findings surfaced

1. No non-admin storage writes exist in any of the three contracts, so the
   storage-fill griefing class does not apply (verified by reading each lib.rs
   — every write entry point requires admin/issuer/compliance_officer).
2. Front-running / TOCTOU is the highest real risk: the read gates
   (check, is_permitted_jurisdiction) are evaluated separately from the
   gated action, leaving a one-ledger window. Recommended an in-transaction hook.
3. jurisdiction-flag::upgrade is issuer-only with no multisig/timelock —
   a single-point-of-catastrophe key (scenario J6, rated Critical). This directly
   motivates Add upgradeability pattern (contract migration path) to allowlist-token #113's upgradeability pattern.
4. Noted a possible duplicate add_to_denylist declaration in denylist-gate
   (lib.rs:161 and lib.rs:189) as a follow-up (potential compile error).

Verification

Documentation-only change; no code modified, builds unaffected.

closes #112

[vercel]

@Idaonoli is attempting to deploy a commit to the idaonoli-2655's projects Team on Vercel.

A member of the Team first needs to authorize it.