1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
/*!
# webgates-sessions
Framework-agnostic session lifecycle building blocks for `webgates` applications.
This crate defines the core types and contracts needed to issue, renew, rotate,
and revoke session-backed authentication without depending on HTTP adapters,
cookies, or any specific web framework.
## When to use this crate
Use `webgates-sessions` when you want:
- framework-agnostic session issuance and renewal
- refresh-token rotation and replay handling
- repository contracts for persisted session state
- lease coordination for concurrent renewal attempts
- transport-independent session services
## Key modules
The crate is split by responsibility so you can learn it in layers:
- [`session`] and [`tokens`] define the core domain and token types
- [`config`] and [`context`] define issuance and renewal inputs
- [`renewal`], [`lease`], and [`logout`] define lifecycle transitions and coordination rules
- [`repository`] defines the persistence contract
- [`services`] wires the pieces together into issue, renew, and revoke workflows
- [`errors`] defines the session-layer failure model
These modules keep transport concerns in adapter crates such as
`webgates-axum`.
## Distributed deployment model
The same session lifecycle works for both single-node and distributed
applications.
Canonical responsibilities are:
- **Auth authority**: verifies credentials, issues auth and refresh tokens,
persists session state, rotates refresh tokens, revokes sessions or session
families, and owns signing keys.
- **Resource service**: validates short-lived access tokens locally,
enforces authorization policy, never rotates refresh tokens, and never owns
session persistence.
- **Single-node deployment**: runs both roles in one process while keeping the
same token and revocation semantics.
This separation keeps refresh-token and session mutation logic in one place
while preserving fast local authorization on resource requests.
## Trust boundaries and token model
In the canonical distributed setup:
- private signing keys stay on the auth authority only
- resource services receive public verification keys only
- refresh tokens are handled only by authority-owned login, renewal, and logout flows
- access tokens are validated on every protected resource request
Helper-minted session-backed access tokens use a short-lived JWT plus a
long-lived refresh-token session. The `jti` claim supports audit correlation
and token lineage, while the `sid` claim binds a session-backed access token to
one server-side session identifier.
Revocation consistency across resource nodes is intentionally bounded by the
short access-token TTL. That trade-off avoids per-request introspection network
calls while keeping refresh-token rotation and replay-aware revocation in the
session layer.
## Getting started
A good first path is to read [`session`], [`tokens`], and [`services`] together.
That gives you the main domain model, token model, and workflow layer in order.
*/
/// Typed session configuration.
/// Request and session context inputs.
/// Session-layer error types.
/// Renewal lease coordination types.
/// Logout and revocation intent types.
/// Renewal flow inputs and outcomes.
/// Persistence contracts for session storage.
/// Session issuance, renewal, and revocation workflows.
/// Session and session-family domain types.
/// Auth and refresh token primitives.