# Sovereign Packet Layer — Build Brief

Also read /home/user/workspace/sentinel/shared/BRIEF.md for design system + legal guardrails.

## Concept (founder's idea, grounded in reality)
"Jurisdictional packet tokenization." Every piece of data carries a token stamping
its ORIGIN and where it is ALLOWED to travel. Domestic data gets a DOMESTIC token and
ideally never touches the public internet (a private/sovereign overlay network). Anything
crossing the national border must be tokenized as INTERNATIONAL, inspected, and logged.
Tokens are minted ONLY by our data centers and are cryptographically bound so they are
worthless outside our infrastructure ("rips up" if it leaves). Other countries can LEASE
the system to run their own sovereign instance.

## Honest engineering framing (must be reflected — do NOT overpromise)
- We CANNOT re-plumb the public internet or force foreign routers to honor our tokens.
- What we CAN build: a SOVEREIGN OVERLAY NETWORK / policy gateway where every packet at
  OUR boundary is classified (domestic vs international), tokenized, policy-checked, logged.
- The token = a signed, scoped credential (JWT-style or HMAC) bound to jurisdiction +
  allowed destinations + expiry. Keys never leave the data center, so a token is useless
  elsewhere. This is real cryptography, not magic.
- This is a MODULE that connects the user's existing "Sovereign Control Tower" (Guardian
  router, egress/airlock/perimeter gate) to the SENTINEL threat platform.

## This connects to the user's EXISTING project (reference it)
Sovereign Control Tower already has: Guardian deterministic router (evaluates
classification, jurisdiction, egress policy), Perimeter export-control gate, Airlock import
pipeline, artifact quarantine, tamper-evident hash-chained audit trails, PKI view,
air-gapped runtime boundary. The Packet Layer is the DATA-PLANE enforcement that these
control-plane policies govern.

## What to BUILD (Python, runnable) — save under /home/user/workspace/sentinel/packet_layer/
1. packet_gateway.py — Flask API acting as the sovereign boundary gateway.
   - POST /route accepts a "packet" {payload_summary, src_region, dst_region, classification}
   - Classifies as DOMESTIC (src+dst both national, e.g. "US") or INTERNATIONAL.
   - DOMESTIC -> mints a domestic token, marks "stays on sovereign overlay, no public internet".
   - INTERNATIONAL (inbound or outbound) -> mints an international token, runs a policy check
     (allow/inspect/block) and logs it for inspection. Inbound-from-foreign = highest scrutiny
     (ties to SENTINEL: quarantine + inspect before entering network).
   - Enforces: nothing crosses the border without a valid international token; blocked packets
     are logged with reason.
2. token_mint.py — real crypto. Mint signed, scoped tokens (use `cryptography` HMAC or
   PyJWT if available; else HMAC-SHA256). Token embeds: id, jurisdiction, scope (allowed
   destinations), classification (DOMESTIC/INTERNATIONAL), issued_at, expiry, issuing_dc.
   verify_token() rejects tokens whose scope/jurisdiction doesn't match the requested move,
   or that are expired, or signed by another data center's key (demonstrating "useless if it
   leaves"). Include a helper showing that a token verified with the wrong DC key FAILS.
3. sovereign_overlay.py — a simple model of the private overlay: a registry of domestic nodes
   that communicate WITHOUT going over the public internet; a function to show that a domestic
   route stays on-overlay and an international route must exit through the boundary gateway.
4. lease.py — multi-tenant "lease to other countries" model: each country/tenant gets its own
   issuing key + jurisdiction code + policy set, fully isolated. Show two tenants (e.g. "US"
   and "ally: CA") each minting tokens that the OTHER cannot verify (sovereign isolation).
5. Dashboard (dark security-console style from BRIEF.md) + / route: show live packet decisions
   (domestic/international/blocked), token ledger, tenants/leases, and a clear diagram-like panel
   explaining domestic-stays-local vs international-tokenized-and-inspected. SQLite for the ledger.
6. README.md (setup + single run command + honest "what this is / isn't" note) and demo_seed.py
   with synthetic packets across domestic, outbound-intl, and inbound-foreign (some blocked).

Make it genuinely runnable (pip install + one command). After building, run it briefly, confirm
seed populates and a domestic vs international vs blocked decision each work, and that a
cross-tenant token verification FAILS as designed. Write BUILD_NOTES.md. Clean, well-commented.
NOTHING that touches or blocks anyone else's real network — this operates only on OUR gateway.
