# Security model

## Credentials

- Handoff tickets and session tokens contain 256 bits of randomness.
- Only SHA-256 digests are stored by the API.
- Handoffs expire after 10 minutes by default and are redeemed atomically once.
- Device VPN request data is encrypted at rest with AES-256-GCM using a key
  derived from the REST API secret.
- Native session credentials are stored with Android Keystore-backed AES-GCM or
  an iOS shared Keychain item marked `AfterFirstUnlockThisDeviceOnly`.
- Tickets, n3n keys, and bearer tokens must never be logged or included in crash
  metadata. The fallback site has no analytics and makes no network request.

The mobile bearer is valid only for its own session endpoints and WebSocket. It
is not an HT Portal user token and cannot enumerate users or devices.

## Network

- The OS always presents its standard VPN consent UI.
- Only the overlay and non-conflicting runtime-provided IPv4 routes are included.
- A route overlapping a physical local network is omitted. An overlay conflict
  is fatal because it would make route ownership ambiguous.
- n3n attempts UDP/P2P on each configured supernode before TCP relay fallback.
- Supernode sockets bypass the Android VPN or are explicit iOS excluded routes.
- Runtime TLS accepts normal platform trust, a supplied private CA, or an exact
  SHA-256 leaf-certificate fingerprint when provided by the runtime.

## Lifecycle and revocation

- Foreground/background tunnel lifecycle is owned by `VpnService` or
  `NEPacketTunnelProvider`, not by the web page.
- Network changes trigger a serialized reconnect.
- Session heartbeats update both the mobile session and underlying connection.
- Portal cancellation, terminal runtime state, explicit app disconnect, or
  credential expiry tears down the native tunnel and clears local credentials.
- Android uses a persistent foreground notification while connected.

## Residual risks before production

- Perform mobile penetration testing on release-signed artifacts.
- Validate route overlap on dual-stack and unusual OEM network stacks; IPv6 is
  currently intentionally not routed.
- Add certificate/key rotation operational tests.
- Complete store privacy declarations and Android Data Safety answers.
- The iOS public release remains legally blocked as documented separately.
