Struct SessionLayer 

pub struct SessionLayer<S> { /* private fields */ }

Tower layer that provides signed session cookies and typed crate::session::SessionData.

Add this layer to your Axum router. Handlers receive an super::extractor::AuthSession extractor which wraps the SessionHandle stored in request extensions.

let app = Router::new()
    .route("/login", post(login_handler))
    .layer(SessionLayer::new(store, signing_key));

Configuration

Cookie attributes and TTL are set via the with_* builder methods:

let layer = SessionLayer::new(store, key)
    .with_ttl(Duration::from_secs(7200))
    .with_secure(false)
    .with_same_site(SameSite::Strict);

Implementations

impl<S: SessionStore> SessionLayer<S>

pub fn new(store: S, signing_key: [u8; 32]) -> Self

Create a session layer with the given store and 32-byte HMAC signing key.

Uses SessionConfig::default(): production-safe defaults (24-hour TTL, Secure, HttpOnly, SameSite=Lax).

The signing key derives sub-keys via HKDF for cookie HMAC, fingerprint HMAC, and CSRF; keep it in a secret store and rotate per your key-management policy (a fresh layer is required on rotation since the derived keys are cached).

Example

use axess_core::{MemorySessionStore, session::SessionLayer};
use std::time::Duration;

// Production: load the master key from a secret store (KMS, Vault, …).
// Below uses a fixed value purely for the construction example.
let signing_key: [u8; 32] = [0u8; 32];
let store = MemorySessionStore::default();

let layer = SessionLayer::new(store, signing_key)
    .with_ttl(Duration::from_secs(3600))
    .with_cookie_name("myapp.sid");

// Attach to your router:
//     let app = axum::Router::new().layer(layer);

pub fn derive_subkey(&self, info: &'static [u8]) -> Zeroizing<[u8; 32]>

Derive a 32-byte sub-key from this layer’s master signing key using a caller-supplied info label. Use this to feed CSRF token signing, push-notification HMAC, or any other HMAC site that would otherwise be tempted to reuse the raw master key. Pick a stable byte-string label per use site (e.g. b"my-app.v1.csrf"); changing the label invalidates every value previously derived under it.

The returned bytes are wrapped in zeroize::Zeroizing so they are wiped on drop: a compromise of any derived sub-key with a known label lets an attacker forge against that path, so the material is held under the same drop discipline as the master key. Deref through * or as_ref() to access the raw [u8; 32].

pub fn with_ttl(self, ttl: Duration) -> Self

Override the session TTL (default: 24 hours).

pub fn with_cookie_name(self, name: impl Into<Arc<str>>) -> Self

Override the cookie name (default: "axess.sid").

pub fn with_secure(self, secure: bool) -> Self

Set the Secure flag on the session cookie (default: true).

Set to false only for local HTTP development. In production, cookies without the Secure flag can be intercepted on the network.

pub fn with_same_site(self, same_site: SameSite) -> Self

Set the SameSite policy (default: Lax).

pub fn with_http_only(self, http_only: bool) -> Self

Set the HttpOnly flag on the session cookie (default: true).

pub fn with_max_custom_bytes(self, max: usize) -> Self

Override the maximum size (in bytes) of the JSON-encoded custom-data payload. Default: 64 KiB. Set to 0 to disable the clamp entirely (do this only if you have your own size guarding upstream of the session layer).

When the clamp fires, the offending custom payload is dropped to Value::Null and a tracing::warn! is emitted; the session itself is preserved.

pub fn with_path(self, path: impl Into<Arc<str>>) -> Self

Set the cookie Path attribute (default: "/").

pub fn with_binding(self, binding: impl SessionBinding) -> Self

Enable session-to-client binding for hijacking detection.

When enabled, the library hashes client-specific request properties (determined by the SessionBinding implementation) and stores the hash in the session upon authentication. On every subsequent request the hash is recomputed and compared; a mismatch resets the session to Guest (the cookie may have been stolen by a different client).

use axess::session::UserAgentBinding;

let layer = SessionLayer::new(store, key)
    .with_binding(UserAgentBinding);

pub fn with_metrics(self, metrics: impl AuthnMetrics) -> Self

Attach a metrics hook for session-level observability.

pub fn with_device_resolver<R>(self, resolver: R) -> Self

where R: DeviceResolver,

Available on crate feature device only.

Configure a DeviceResolver to stamp SessionData::device_id on every request before the inner handler runs.

Errors returned by the resolver are logged via tracing::warn! and treated as None; device resolution never fails the request. When unset (the default), device_id stays at whatever the loaded session carried, which for new sessions is None.

See docs/identity/device.md for the full design.

Trait Implementations

impl<S: Clone> Clone for SessionLayer<S>

fn clone(&self) -> SessionLayer<S>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<S, Inner> Layer<Inner> for SessionLayer<S>

where S: SessionStore + Clone,

type Service = SessionService<S, Inner>

The wrapped service

fn layer(&self, inner: Inner) -> Self::Service

Wrap the given service with the middleware, returning a new service that has been decorated with the middleware.