Adopt PASETO for session transport
Context
The app started with HTTP session cookies via tower-sessions and axum-login. This worked on web but caused persistent lost-session bugs on iOS — cookies in native apps require careful URLSession configuration that's easy to get wrong, and the failure modes are silent (lost sessions with no clear cause).
The instinct was to avoid JWTs (coming from a web background where they're frequently misused for sessions), but the iOS context changes things: tokens can be stored securely in the Keychain/Secure Enclave rather than exposed in cookies. PASETO (Platform-Agnostic Security Tokens) provides the same transport benefits as JWT but with fewer footguns — no algorithm selection vulnerabilities, encrypted by default, and secure-by-default design.
Decision
Adopt PASETO v4.local tokens for authentication transport, replacing cookies. Server-side Redis sessions remain for now — the token carries a session_id claim that links back to the session store.
Token claims include session_id, user_type, exp, and iat. The token footer contains a key identifier (PASERK) to support key rotation without service interruption.
iOS stores the token in the Keychain and sends it via Authorization: Bearer header through Apollo interceptors (ADR-0018).
Why PASETO over JWT
- No algorithm confusion attacks — PASETO has no algorithm selection header
- Payload is encrypted (v4.local), not just signed
- PASERK standard for key identification built in
- Smaller attack surface by design
Consequences
Simpler iOS auth — header-based instead of cookie management. Token presence clearly indicates auth status. Key rotation is possible via the multi-key architecture.
The cost is key management infrastructure (rotation, storage, lifecycle) and a new library dependency. Redis sessions are still required for server-side validation, which is an intermediate step — see ADR-0028 for the eventual move to fully stateless tokens.