webgates_sessions/
lib.rs

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

webgates_sessions/
lib.rs
