286
specs/features/003-bff-sessions.md
Normal file
286
specs/features/003-bff-sessions.md
Normal file
@@ -0,0 +1,286 @@
|
||||
# Spec 003: BFF Session Management
|
||||
|
||||
## Status: Phase 2 Complete (34 tests passing)
|
||||
|
||||
## Problem
|
||||
|
||||
The current auth implementation stores forest-server's raw access_token and
|
||||
refresh_token directly in browser cookies. This has several problems:
|
||||
|
||||
1. **Security**: Forest-server credentials are exposed to the browser. If XSS
|
||||
ever bypasses HttpOnly (or we need to read auth state client-side), the raw
|
||||
tokens are right there.
|
||||
2. **No transparent refresh**: The extractor checks cookie existence but can't
|
||||
detect token expiry. When the access_token expires, `get_user()` fails and
|
||||
the user gets redirected to login - even though the refresh_token is still
|
||||
valid. Users get randomly logged out.
|
||||
3. **No user caching**: Every authenticated page makes 2-3 gRPC round-trips
|
||||
(token_info + get_user + page-specific call). For server-rendered pages
|
||||
this is noticeable latency.
|
||||
4. **No session concept**: There's no way to list active sessions, revoke
|
||||
sessions, or track "last seen". The server is stateless in a way that
|
||||
hurts the product.
|
||||
|
||||
## Solution: Backend-for-Frontend (BFF) Sessions
|
||||
|
||||
Forage server owns sessions. The browser gets an opaque session ID cookie.
|
||||
Forest-server tokens and cached user info live server-side only.
|
||||
|
||||
```
|
||||
Browser --[forage_session cookie]--> forage-server --[access_token]--> forest-server
|
||||
|
|
||||
[session store]
|
||||
sid -> { access_token, refresh_token,
|
||||
expires_at, user_cache }
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### Session Store Trait
|
||||
|
||||
A trait in `forage-core` so the store is swappable and testable:
|
||||
|
||||
```rust
|
||||
#[async_trait]
|
||||
pub trait SessionStore: Send + Sync {
|
||||
async fn create(&self, data: SessionData) -> Result<SessionId, SessionError>;
|
||||
async fn get(&self, id: &SessionId) -> Result<Option<SessionData>, SessionError>;
|
||||
async fn update(&self, id: &SessionId, data: SessionData) -> Result<(), SessionError>;
|
||||
async fn delete(&self, id: &SessionId) -> Result<(), SessionError>;
|
||||
}
|
||||
```
|
||||
|
||||
### SessionId
|
||||
|
||||
An opaque, cryptographically random token. Not a UUID - use 32 bytes of
|
||||
`rand::OsRng` encoded as base64url. This is the only thing the browser sees.
|
||||
|
||||
### SessionData
|
||||
|
||||
```rust
|
||||
pub struct SessionData {
|
||||
pub access_token: String,
|
||||
pub refresh_token: String,
|
||||
pub access_expires_at: chrono::DateTime<Utc>, // computed from expires_in_seconds
|
||||
pub user: Option<CachedUser>, // cached to avoid repeated get_user calls
|
||||
pub created_at: chrono::DateTime<Utc>,
|
||||
pub last_seen_at: chrono::DateTime<Utc>,
|
||||
}
|
||||
|
||||
pub struct CachedUser {
|
||||
pub user_id: String,
|
||||
pub username: String,
|
||||
pub emails: Vec<UserEmail>,
|
||||
}
|
||||
```
|
||||
|
||||
### In-Memory Store (Phase 1)
|
||||
|
||||
`HashMap<SessionId, SessionData>` behind a `RwLock`. Good enough for single-instance
|
||||
deployment. A background task reaps expired sessions periodically.
|
||||
|
||||
This is sufficient for now. When forage needs horizontal scaling, swap to a
|
||||
Redis or PostgreSQL-backed store behind the same trait.
|
||||
|
||||
### Cookie
|
||||
|
||||
Single cookie: `forage_session`
|
||||
- Value: the opaque SessionId (base64url, ~43 chars)
|
||||
- HttpOnly: yes
|
||||
- Secure: yes (always - even if we need to configure for local dev)
|
||||
- SameSite: Lax
|
||||
- Path: /
|
||||
- Max-Age: 30 days (the session lifetime, not the access token lifetime)
|
||||
|
||||
The previous `forage_access` and `forage_refresh` cookies are removed entirely.
|
||||
|
||||
## Behavioral Contract
|
||||
|
||||
### Login / Register Flow
|
||||
|
||||
1. User submits login/signup form
|
||||
2. Forage calls forest-server's Login/Register RPC, gets AuthTokens
|
||||
3. Forage computes `access_expires_at = now + expires_in_seconds`
|
||||
4. Forage calls `get_user` to populate the user cache
|
||||
5. Forage creates a session in the store with tokens + user cache
|
||||
6. Forage sets `forage_session` cookie with the session ID
|
||||
7. Redirect to /dashboard
|
||||
|
||||
### Authenticated Request Flow
|
||||
|
||||
1. Extract `forage_session` cookie
|
||||
2. Look up session in store
|
||||
3. If no session: redirect to /login
|
||||
4. If `access_expires_at` is in the future (with margin): use cached access_token
|
||||
5. If access_token is expired or near-expiry (< 60s remaining):
|
||||
a. Call forest-server's RefreshToken RPC with the stored refresh_token
|
||||
b. On success: update session with new tokens + new expiry
|
||||
c. On failure (refresh_token also expired): delete session, redirect to /login
|
||||
6. Return session to the route handler (which has access_token + cached user)
|
||||
|
||||
### Logout Flow
|
||||
|
||||
1. Extract session ID from cookie
|
||||
2. Get refresh_token from session store
|
||||
3. Call forest-server's Logout RPC (best-effort)
|
||||
4. Delete session from store
|
||||
5. Clear the `forage_session` cookie
|
||||
6. Redirect to /
|
||||
|
||||
### Session Expiry
|
||||
|
||||
- Sessions expire after 30 days of inactivity (configurable)
|
||||
- `last_seen_at` is updated on each request
|
||||
- A background reaper runs every 5 minutes, removes sessions where
|
||||
`last_seen_at + 30 days < now`
|
||||
- If the refresh_token is rejected by forest-server, the session is
|
||||
destroyed immediately regardless of age
|
||||
|
||||
## Changes to Existing Code
|
||||
|
||||
### What Gets Replaced
|
||||
|
||||
- `auth.rs`: `MaybeAuth` and `RequireAuth` extractors rewritten to use session store
|
||||
- `auth.rs`: `auth_cookies()` and `clear_cookies()` replaced with session cookie helpers
|
||||
- `routes/auth.rs`: Login/signup handlers create sessions instead of setting token cookies
|
||||
- `routes/auth.rs`: Logout handler destroys session
|
||||
- `routes/auth.rs`: Dashboard and token pages use `session.user` cache instead of calling `get_user()` every time
|
||||
|
||||
### What Stays the Same
|
||||
|
||||
- `ForestAuth` trait and `GrpcForestClient` - unchanged, still the interface to forest-server
|
||||
- Validation functions in `forage-core` - unchanged
|
||||
- Templates - unchanged (they receive the same data)
|
||||
- Route structure and URLs - unchanged
|
||||
- All existing tests continue to pass (mock gets wrapped in mock session store)
|
||||
|
||||
### New Dependencies
|
||||
|
||||
- `rand` (workspace): for cryptographic session ID generation
|
||||
- No new external session framework - the store is simple enough to own
|
||||
|
||||
### AppState Changes
|
||||
|
||||
```rust
|
||||
pub struct AppState {
|
||||
pub templates: TemplateEngine,
|
||||
pub forest_client: Arc<dyn ForestAuth>,
|
||||
pub sessions: Arc<dyn SessionStore>, // NEW
|
||||
}
|
||||
```
|
||||
|
||||
## Extractors (New Design)
|
||||
|
||||
### `Session` extractor (replaces `RequireAuth`)
|
||||
|
||||
Extracts the session, handles refresh transparently, provides both the
|
||||
access_token (for forest-server calls that aren't cached) and cached user info.
|
||||
|
||||
```rust
|
||||
pub struct Session {
|
||||
pub session_id: SessionId,
|
||||
pub access_token: String,
|
||||
pub user: CachedUser,
|
||||
}
|
||||
```
|
||||
|
||||
The extractor:
|
||||
1. Reads cookie
|
||||
2. Looks up session
|
||||
3. Refreshes token if needed (updating the store)
|
||||
4. Returns `Session` or redirects to /login
|
||||
|
||||
Because refresh updates the session store (not the cookie), no response
|
||||
headers need to be set during extraction. The cookie stays the same.
|
||||
|
||||
### `MaybeSession` extractor (replaces `MaybeAuth`)
|
||||
|
||||
Same as `Session` but returns `Option<Session>` instead of redirecting.
|
||||
Used for pages like /signup and /login that behave differently when
|
||||
already authenticated.
|
||||
|
||||
## Edge Cases
|
||||
|
||||
- **Concurrent requests during refresh**: Two requests arrive with the same
|
||||
expired access_token. Both try to refresh. The session store update is
|
||||
behind a RwLock, so the second one will see the already-refreshed token.
|
||||
Alternatively, use a per-session Mutex for refresh operations to avoid
|
||||
double-refresh. Start simple (accept occasional double-refresh), optimize
|
||||
if it becomes a problem.
|
||||
|
||||
- **Session ID collision**: 32 bytes of crypto-random = 256 bits of entropy.
|
||||
Collision probability is negligible.
|
||||
|
||||
- **Store grows unbounded**: The reaper task handles this. For in-memory store,
|
||||
also enforce a max session count (e.g., 100k) as a safety valve.
|
||||
|
||||
- **Server restart loses all sessions**: Yes. In-memory store is not durable.
|
||||
All users will need to re-login after a deploy. This is acceptable for now
|
||||
and is the primary motivation for eventually moving to Redis/Postgres.
|
||||
|
||||
- **Cookie without valid session**: Treat as unauthenticated. Clear the stale
|
||||
cookie.
|
||||
|
||||
- **Forest-server down during refresh**: Keep the existing session alive with
|
||||
the expired access_token. The next forest-server call will fail, and the
|
||||
route handler deals with it (same as today). Don't destroy the session just
|
||||
because refresh failed due to network - only destroy it if forest-server
|
||||
explicitly rejects the refresh token.
|
||||
|
||||
## Test Strategy
|
||||
|
||||
### Unit Tests (forage-core)
|
||||
|
||||
- `SessionId` generation: length, format, uniqueness (generate 1000, assert no dupes)
|
||||
- `SessionData` expiry logic: `is_access_expired()`, `needs_refresh()` (with margin)
|
||||
- `InMemorySessionStore`: create/get/update/delete round-trip
|
||||
- `InMemorySessionStore`: get non-existent returns None
|
||||
- `InMemorySessionStore`: delete then get returns None
|
||||
|
||||
### Integration Tests (forage-server)
|
||||
|
||||
All existing tests must continue passing. Additionally:
|
||||
|
||||
- Login creates a session and sets `forage_session` cookie (not `forage_access`)
|
||||
- Dashboard with valid session cookie returns 200 with user content
|
||||
- Dashboard with expired access_token (but valid refresh) still returns 200
|
||||
(transparent refresh)
|
||||
- Dashboard with expired session redirects to /login
|
||||
- Logout destroys session and clears cookie
|
||||
- Signup creates session same as login
|
||||
- Old `forage_access` / `forage_refresh` cookies are ignored (clean break)
|
||||
|
||||
### Mock Session Store
|
||||
|
||||
For tests, use `InMemorySessionStore` directly (it's already simple). The mock
|
||||
`ForestClient` stays as-is for controlling gRPC behavior.
|
||||
|
||||
## Implementation Order
|
||||
|
||||
1. Add `SessionId`, `SessionData`, `SessionStore` trait, `InMemorySessionStore` to `forage-core`
|
||||
2. Add unit tests for session types and in-memory store
|
||||
3. Add `rand` dependency, implement `SessionId::generate()`
|
||||
4. Rewrite `auth.rs` extractors to use session store
|
||||
5. Rewrite route handlers to use new extractors
|
||||
6. Update `AppState` to include session store
|
||||
7. Update `main.rs` to create the in-memory store
|
||||
8. Update integration tests
|
||||
9. Add session reaper background task
|
||||
10. Remove old cookie helpers and constants
|
||||
|
||||
## What This Does NOT Do
|
||||
|
||||
- No Redis/Postgres session store yet (in-memory only)
|
||||
- No "active sessions" UI for users
|
||||
- No CSRF protection (SameSite=Lax is sufficient for form POSTs from same origin)
|
||||
- No session fixation protection beyond generating new IDs on login
|
||||
- No rate limiting on session creation (defer to forest-server's rate limiting)
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. Should we invalidate all sessions for a user when they change their password?
|
||||
(Requires either forest-server notification or polling.)
|
||||
2. Session cookie name: `forage_session` or `__Host-forage_session`?
|
||||
(`__Host-` prefix forces Secure + no Domain + Path=/, which is stricter.)
|
||||
3. Should the user cache have a separate TTL (e.g., refresh user info every 5 min)?
|
||||
Or only refresh on explicit actions like "edit profile"?
|
||||
Reference in New Issue
Block a user