Session token rotation
Session tokens become a liability the moment a user's authority changes. This spec makes rotation immediate and observable: a fresh token on every privilege change, the prior token dead within one request cycle, and a single serialised lock so concurrent logouts can't race.
§1 Goals & non-goals
- ✓Rotate on every privilege change
- ✓Invalidate the prior token in one cycle
- ✓Serialise concurrent rotations
- ×Refresh-token storage policy → AUTH-STORE
- ×Device-level revocation UI
§2 Requirements
Tokens rotate on privilege change
The system MUST issue a fresh session token whenever a user's role changes, and MUST invalidate the prior token within one request cycle.
Concurrent rotations serialise
Two privilege changes arriving within the same cycle SHOULD serialise behind a single rotation lock, so the later change always supersedes the earlier.
§3 Decision
Serialise with a per-subject advisory lock
- Context
- Logout and role-change can fire in the same cycle; an optimistic check left a window for double-rotation.
- Decision
- Take a per-subject advisory lock for the rotation critical section. Cheap, already available, no new infra.
- Consequences
- Adds <1ms under contention; lock held only across the write. Revisit if subjects shard across regions.
§4 Options considered
| Option | Effort | Race-safe | Infra |
|---|---|---|---|
| Optimistic version check | Low | No | None |
| Advisory lock ✓ | Low | Yes | None |
| Dedicated queue | High | Yes | New |
§5 Changelog
This is a deliberately small starter — two requirements, one decision, no budget gauge, no change proposals. The canonical example is the spec for Spectastic itself — written in Spectastic, exercising every component: budget, status meta, requirements, decisions, conformance index, triage log, and archived change proposals.
More worked examples — meta-spec, triage logs, archived change proposals — live in the examples directory.
One file. Renders anywhere. Degrades to readable static HTML.
← Back to spectastic