# BUILD_NOTES — Sovereign Packet Layer

## What was built

A complete, runnable prototype under `sentinel/packet_layer/` implementing the
"jurisdictional packet tokenization" concept from `../shared/PACKET_BRIEF.md`,
honoring the design system and legal guardrails in `../shared/BRIEF.md`.

- `token_mint.py` — cryptographic core. `TokenMinter` mints JWT-style tokens
  (`header.claims.signature`, base64url) signed with **HMAC-SHA256** using
  Python's stdlib `hmac`/`hashlib`. Claims embed `jti`, `jur` (jurisdiction),
  `scope` (allowed destinations), `class` (DOMESTIC/INTERNATIONAL), `iat`, `exp`,
  `iss`/`dc` (issuing data center), `sum` (payload summary). `verify()` returns a
  structured `VerifyResult(valid, reason, claims)` and rejects: malformed tokens,
  wrong-key signatures (**constant-time** `hmac.compare_digest`), expired tokens,
  out-of-scope destinations, and jurisdiction mismatch. Keys are ≥256-bit and
  generated with `os.urandom`.
- `lease.py` — `LeaseRegistry` + `Tenant`. Each tenant (country) has its own
  minter/key, jurisdiction code, per-destination policy (ALLOW/INSPECT/BLOCK),
  and domestic-region set. `default_registry()` provisions **US** and its ally
  **CA** as two fully isolated instances.
- `sovereign_overlay.py` — `SovereignOverlay` models a private fabric as a node
  registry and decides `route(src, dst)` → on-overlay DOMESTIC vs
  gateway-exit INTERNATIONAL. `default_overlays()` gives US and CA their own
  overlays and boundary gateways.
- `packet_gateway.py` — Flask app. `decide()` is the shared engine (used by both
  the HTTP route and the seed) that classifies, mints, policy-checks, and returns
  a ledger row. Routes: `POST /route`, `POST /verify` (for the isolation demo),
  `GET /api/ledger`, `GET /` (dashboard). SQLite append-only `ledger` table.
- `templates/dashboard.html` — dark security-console UI (bg `#0D1117`, teal
  `#20808D`, Space Grotesk / Inter / JetBrains Mono via CDN) with KPIs, the
  decision ledger, a domestic/international/blocked flow diagram, tenants/leases
  panel, overlay node list, and a **live cross-tenant isolation proof**.
- `demo_seed.py`, `README.md`, `requirements.txt`, `verify_run.py`.

## How classification + policy works

1. The tenant's overlay decides DOMESTIC (both endpoints on-overlay) vs
   INTERNATIONAL. Classification is **derived from topology**, not trusted from
   the caller — the honest behaviour.
2. DOMESTIC → mint a DOMESTIC token scoped to own regions, `on_overlay=1`,
   "stays on sovereign overlay, no public internet."
3. INTERNATIONAL → look up the tenant's policy for the foreign peer.
   - **Inbound-from-foreign** with an ALLOW policy is **upgraded to INSPECT**
     (quarantine + inspect before entering the network — the SENTINEL Airlock /
     highest-scrutiny tie-in).
   - **BLOCK** → no token is issued; logged with a reason. Nothing crosses.
   - **ALLOW / INSPECT** → mint an INTERNATIONAL token scoped to `[home, peer]`,
     verify it, log the decision.

## Verification performed (all passed — see `verify_run.py`)

- Seed populates the SQLite ledger: 4 domestic, 9 international, 3 blocked (13
  seed rows; 17 after live tests).
- `POST /route` DOMESTIC → `DOMESTIC / ALLOW / on_overlay=1 / verified=1`.
- `POST /route` US→CA INTERNATIONAL → `INTERNATIONAL / ALLOW`.
- `POST /route` GB→US inbound → `INTERNATIONAL / INSPECT / direction=inbound`.
- `POST /route` US→RU → `BLOCK`, no token minted.
- Cross-tenant: a US-minted token verifies at US (`valid=True`) but **FAILS** at
  tenant CA (`valid=False`, "signature mismatch … useless outside its home
  infrastructure") — sovereign isolation proven.
- Dashboard renders (~30 KB HTML) and the live server answers HTTP 200 on `/`
  and `POST /route` over the wire (curl-tested on `127.0.0.1:5055`).

## Design decisions & trade-offs

- **HMAC (symmetric) not asymmetric**: the brief allowed HMAC or JWT; PyJWT was
  not installed and `cryptography` is present, but stdlib `hmac` is sufficient
  and dependency-light for the "key never leaves the DC" model. Symmetric keys
  make the "wrong key → fails" isolation demonstration crisp. A production build
  would likely move to per-DC asymmetric keys (Ed25519) so verifiers can check
  signatures without holding the minting secret; the `TokenMinter` interface is
  structured to allow swapping the `_sign`/`verify` internals.
- **Per-tenant overlays**: each tenant enforces on its own overlay so a leased
  instance (CA) correctly treats CA→CA as domestic. The gateway selects the
  overlay by tenant inside `decide()`.
- **Classification derived, not trusted**: even though the packet schema accepts
  an optional `classification`, the gateway recomputes it from topology.

## Honest limits (kept out of every claim)

- We do not and cannot control the public internet or foreign routers. "Overlay"
  = infrastructure we own end-to-end; "isolation" = cryptographic key separation.
- No network egress anywhere. All data synthetic. Nothing touches or blocks any
  system we do not own. Fully compliant with the CFAA guardrails in `BRIEF.md`.

## Run

```bash
pip install -r requirements.txt
python demo_seed.py
python packet_gateway.py     # http://127.0.0.1:5055
# or: python verify_run.py   # one-shot end-to-end proof
```
