ADR-001: PASETO v4.local for Authentication

Date: 2024-01-15

Status: Accepted

Context

SynDB exposes two server protocols from the same binary: an Axum HTTP API and an Apache Arrow Flight gRPC service. Both require stateless authentication that can be validated without a database round-trip on every request.

JSON Web Tokens (JWT) are the industry default, but they carry well-documented pitfalls: algorithm confusion attacks (alg: none), RSA/HMAC substitution, and an overly flexible header that increases the attack surface. Because both servers run in the same process and share an AppState, there is no need for public-key cryptography or third-party token verification – a symmetric scheme is simpler and sufficient.

Decision

Use PASETO v4.local (symmetric authenticated encryption with XChaCha20-Poly1305) via the rusty_paseto crate. Tokens carry user claims encrypted with a shared 256-bit secret key.

• Access tokens are short-lived (15 minutes).
• Refresh tokens are rotated on each use and stored in PostgreSQL, enabling server-side revocation.
• The shared secret is loaded once at startup from the application settings and held in AppState.

Consequences

Positive:

• Eliminates the entire class of JWT algorithm confusion vulnerabilities.
• Symmetric encryption means tokens are opaque to clients – no claim leakage.
• Single shared secret is trivial to manage when both protocols live in one binary.
• Short-lived access tokens plus refresh rotation limit the blast radius of a leaked token.

Negative:

• Tokens cannot be decoded or inspected on the client side (by design, but complicates client-side debugging).
• If SynDB ever splits into multiple independently deployed services, the shared secret must be distributed securely to each service.
• Refresh token storage adds a PostgreSQL dependency to the auth flow.