# SENTINEL — Sovereign Packet Layer

Data-plane boundary gateway for the SENTINEL Track-Back Defense Platform. It
implements the founder's **"jurisdictional packet tokenization"** idea in a way
that is real and honest: at **our** sovereign boundary, every packet is
classified, cryptographically tokenized, policy-checked, and logged.

- **DOMESTIC** data (both endpoints inside our jurisdiction) stays on a private
  **sovereign overlay** and never needs a public-internet hop.
- **INTERNATIONAL** data (an endpoint is outside) must exit through the boundary
  gateway, where it is minted an international token, policy-checked
  (**allow / inspect / block**), and logged. Inbound-from-foreign gets the
  highest scrutiny (quarantine + inspect, the SENTINEL Airlock tie-in).
- Tokens are **HMAC-SHA256 signed, scoped credentials** bound to a jurisdiction,
  an allowed destination scope, and an expiry. The signing key **never leaves the
  data center**, so a token is **useless if it leaves** — a token verified with
  another data center's key **fails**.
- The platform can be **leased** to other countries: each tenant gets its own
  key, jurisdiction, and policy set, and its tokens **cannot** be verified by any
  other tenant (**sovereign isolation**).

## What this is / isn't (honest engineering)

- **Is:** a sovereign overlay / policy gateway that enforces classification +
  tokenization + policy on infrastructure **we own end-to-end**. The token is a
  signed, scoped credential — real cryptography, not magic.
- **Isn't:** a way to re-plumb the public internet or force foreign routers to
  honor our tokens. This is the **data plane** that the Sovereign Control Tower's
  control plane (Guardian router, Perimeter export gate, Airlock import pipeline,
  quarantine, hash-chained audit) governs.
- **Never** touches, blocks, corrupts, or reaches into anyone else's real network.
  All demo data is synthetic. No PII, no real IPs, no network egress.

## Setup + run (one command each)

```bash
pip install -r requirements.txt      # flask, cryptography (HMAC uses stdlib)

python demo_seed.py                  # populate the SQLite ledger (synthetic packets)
python packet_gateway.py             # serve the dashboard at http://127.0.0.1:5055
```

Open <http://127.0.0.1:5055> for the dark security-console dashboard: live packet
decisions, the token ledger, tenants/leases, the domestic-vs-international
diagram, and a live cross-tenant isolation proof.

### One-shot end-to-end check

```bash
python verify_run.py     # seeds, exercises domestic/international/blocked,
                         # and proves cross-tenant verification FAILS
```

## Components

| File                   | Role |
| ---------------------- | ---- |
| `token_mint.py`        | Real crypto. Mints/verifies HMAC-SHA256 signed, scoped, expiring tokens. Wrong-key verification fails. |
| `lease.py`             | Multi-tenant model. Each country = own key + jurisdiction + policy set; tokens are cross-tenant-isolated. |
| `sovereign_overlay.py` | Private overlay: registry of domestic nodes; decides domestic-stays-local vs international-exits-gateway. |
| `packet_gateway.py`    | Flask boundary gateway. `POST /route`, `POST /verify`, `/api/ledger`, `/` dashboard. SQLite ledger. |
| `templates/dashboard.html` | Dark security-console dashboard. |
| `demo_seed.py`         | Synthetic packets: domestic, outbound-intl, inbound-foreign, blocked, plus a leased CA tenant. |

## HTTP API

`POST /route` — classify + tokenize + policy-check + log one packet.

```json
{ "src_region": "US", "dst_region": "CA",
  "payload_summary": "shared threat-intel feed", "tenant": "US" }
```

Returns the ledger row: `classification` (DOMESTIC/INTERNATIONAL), `decision`
(ALLOW/INSPECT/BLOCK), `on_overlay`, minted `token`, `token_verified`, reasons.

`POST /verify` — verify a token against a chosen tenant's key (used to demonstrate
cross-tenant failure): `{ "token": "...", "tenant": "CA", "dst": "US" }`.

`GET /api/ledger` — recent ledger rows as JSON.
```
