# SENTINEL — Sovereign Identity Fabric

A universal, **rotating, structurally-typed identity fabric** so no one can ever
impersonate anyone: *a fake token never matches*. Every entity type carries a
structurally different, constantly-rotating HMAC-SHA256 credential across two
axes plus a cloud-transit axis, and everything leaving the boundary is sealed +
tracked by the Outbound Egress module.

Part of the **Sovereign Cyber System** (connects to the Sovereign Control Tower
/ BB2G Sovereign AI Cluster ideas). Sibling of the inbound *Cyber Caller ID &
Blocker* in `../forensics_lab_unified/`.

## What it does

- **Two-axis typed tokens.** Jurisdiction (`DOMESTIC` / `INTERNATIONAL`) ×
  entity kind (`government` / `business` / `person`) yield six structurally
  distinct token prefixes:
  `GOV-DOM- GOV-INT- BIZ-DOM- BIZ-INT- PSN-DOM- PSN-INT-`.
- **Cloud in-transit tokens.** A rotating token going **into** the cloud
  (`CLD-IN-`) and a *different* rotating token coming **out** (`CLD-OUT-`), each
  on its own independent rotation stream, so data in the cloud can never be
  "touched"/impersonated.
- **Outbound Egress Tokenization & Tracking** (`egress_guard.py`, ADD-B).
  Anything leaving OUR system is sealed with a rotating `EGR-<KIND>-<JUR>-`
  token binding origin, allowed destination scope, sensitivity
  (`PUBLIC`/`SENSITIVE`/`TOP`), expiry, rotation epoch, and a unique tracking id.
  `trace(tracking_id)` returns the full hash-chained provenance ("where did this
  go, when, under what token"). A re-signed/forged copy fails; a replayed old
  token fails after rotation; **TOP** items expire faster and rotate faster.
- **Verification** rejects: forged secret, wrong kind, wrong jurisdiction, a
  **stale token minted before a rotation**, and expired tokens.
- **Rotation** (`scheduled` or `breach`) bumps the rotation epoch *and*
  re-derives the per-entity secret, so every previously-issued token instantly
  stops verifying.
- **Tamper-evident ledger** (`fabric_ledger.py`): every mint/verify/rotate/
  cloud/egress event is appended to a hash-chained SQLite log; `verify_chain()`
  detects any retroactive edit.

## Files

| File | Purpose |
|------|---------|
| `identity_fabric.py` | Core: register / mint / verify / rotate + cloud IN/OUT |
| `egress_guard.py`    | Outbound egress: seal / verify / rotate / trace |
| `fabric_ledger.py`   | Hash-chained SQLite audit ledger |
| `fabric_server.py`   | Flask dashboard on 127.0.0.1:5070 (black + teal) |
| `verify_run.py`      | 20 headless PASS/FAIL checks |
| `demo_seed.py`       | Seeds all 6 combos + cloud + egress demo data |

## Run

```bash
pip install -r requirements.txt
python demo_seed.py        # seed synthetic data
python verify_run.py       # 20 PASS/FAIL proof checks
python fabric_server.py    # dashboard at http://127.0.0.1:5070
```

## Full token-prefix list

Entity (6): `GOV-DOM- GOV-INT- BIZ-DOM- BIZ-INT- PSN-DOM- PSN-INT-`
Cloud (2): `CLD-IN- CLD-OUT-`
Egress (6): `EGR-GOV-DOM- EGR-GOV-INT- EGR-BIZ-DOM- EGR-BIZ-INT- EGR-PSN-DOM- EGR-PSN-INT-`

## Honest scope note

- **Track-back, never hack-back.** ZERO network egress: no sockets, no
  `requests`/`urllib` to any external host. All local HMAC-SHA256 crypto + JSON +
  SQLite. Flask binds `127.0.0.1` only.
- What this proves is **real and modest**: at OUR boundary we cryptographically
  bind identity to *kind + jurisdiction + rotation epoch* and reject anything
  that does not match. It cannot re-plumb the public internet or force foreign
  systems to honor these tokens. Real crypto, not magic.
- All entities and secrets are **synthetic demo data**. Not independently
  audited; do not use as-is to protect real classified/life-critical material.
