Security posture

What axess chooses for you, what it leaves to you, and what an auditor will ask about. Read it before launch, not after the questionnaire arrives.

Crypto backends

Axess uses RustCrypto for every primitive it implements itself, unconditionally: AES-256-GCM (the session envelope), HMAC-SHA256 (cookie signing, fingerprint binding), Argon2id (password hashing), TOTP and HOTP (RFC 6238 and RFC 4226), and SHA-256 (refresh token hashing). These are plain dependencies. There is no feature that swaps them for another implementation, and no cfg in the source that selects between backends.

The one backend an adopter chooses is for JWT signature verification, because jsonwebtoken takes its provider from a cargo feature and will not pick one for you. Anything enabling jwt names one of:

[dependencies]
# Pure Rust, builds anywhere. The default choice.
axess = { version = "0.7.0", features = ["jwt", "jwt-rust-crypto"] }

# aws-lc-rs: wraps the FIPS-validated aws-lc, needs a C toolchain
# (and NASM on Windows), and does not build on every target.
axess = { version = "0.7.0", features = ["jwt", "jwt-aws-lc"] }

Naming neither is a compile error. Naming both is allowed, because cargo can enable the second one when another crate in the build asks for it, and axess installs one provider rather than letting jsonwebtoken panic.

ring still appears in the dependency graph through TLS-adjacent crates (rustls and its consumers), not through axess's own code.

FIPS targeting

Axess does not today offer a FIPS-validated build. A deployment that needs one should read this section as a statement of the gap rather than a route through it.

The reason is the first of the three things a FIPS 140-3 deployment requires: every cryptographic operation must run through a validated module. Axess's own primitives are RustCrypto, which is not validated, and they are not switchable. The jwt-aws-lc feature routes JWT signature verification through aws-lc-rs, and that is the only operation it covers. The session envelope, password hashing, refresh-token hashing and HMAC fingerprint binding do not move with it.

The second requirement is that the compile and link chain introduces no non-validated crypto. Cargo's dependency graph is the source of truth: cargo tree and inspecting for non-aws-lc crypto crates (rustls, ring, the RustCrypto crates) shows what the deployment actually pulls in.

The third is that the validation certificate covers the platform the deployment runs on. NIST publishes FIPS validation certificates per platform-binary combination; a certificate for Linux x86-64 does not cover macOS ARM. The deployment's compliance evidence must include the certificate matching the production platform.

Closing the gap means making the remaining primitives selectable, which is a design change and not a feature flag. Raise it as an adopter requirement if you need it.

PII classification

The application records PII across several stores. The classification matters for GDPR (the data subject's rights), for SOC 2 (the control objectives), and for the retention sweep (Device identity's device_retention_days). The classification:

Pseudonymous is a claim about the data on its own. Each of those values becomes PII the moment it is joined to the primary set, and the join needs access to the identity store, so that store's access control is what keeps the classification true.

The GDPR right-to-erasure verb is IdentityAdmin::delete_user, and what it does is your implementation's decision rather than a cascade axess runs. The trait states the contract: delete or irreversibly anonymise the user row, every factor config under AuthnScope::User, the refresh tokens, the persisted sessions, the password history, and any application rows whose retention basis was the consent now withdrawn. After Ok(()), get_user, find_user and account_status must report the user gone, and any in-flight session must fail its next is_valid check.

Its default body panics rather than returning an error, so a backend that never overrode it fails loudly the first time an erasure request arrives instead of reporting success and deleting nothing. The audit-event entries that reference the user are not removed (the audit trail is load-bearing for compliance); the user's identifier in the events is hashed to a pseudonymous token, which makes the events non-PII without losing the ability to correlate them.

Compliance touch-points

The deployment will face one or more of these regulatory frames. Axess does not provide compliance on its own; it provides the controls each framework requires. The touch-points:

One gap in that first column is easy to miss under SOC 2: every authentication decision produces an AuthEvent, but authorisation decisions go to a tracing target instead. They are not in the catalogue, so an evidence pipeline that reads only AuthEvent rows will not have them. Wire the target separately.

For the mechanism behind a specific control: Session lifecycle and crypto envelope for encryption at rest, Audit pipeline for retention, Refresh tokens and session continuity for refresh-token hygiene, Multi-tenancy for the lockout policy.

Failing closed

Two stores sit behind the login path, and what happens when each one is down is a decision rather than an accident.

The lockout counter is the first. record_failed_attempt is a write, and the read-replica split this library encourages puts reads on a replica and writes on the primary, so a primary outage leaves logins working and the counter dead. LockoutPolicy::on_counter_unavailable decides what happens then. It defaults to CounterUnavailable::Lock, which treats the attempt as locked and keeps brute force bounded. CounterUnavailable::Allow keeps those users logging in and leaves lockout disabled until the counter returns. Alert on AuthnMetrics::factor_counter_store_outage either way: under Lock it explains the support calls, and under Allow it is the only signal that a control is off.

The audit store is the second, and it fails closed with no switch. If IdentityAuthnLog::record_event returns an error, the flow returns AuthnError::Store and the login does not succeed. An authentication that leaves no evidence has not, for evidence purposes, happened, and a catalogue offered as SOC 2 or PCI-DSS evidence cannot be allowed to develop holes quietly.

The cost is availability, and it is not small: logins fail while the audit store does. Put the sink behind something durable. Write locally and ship asynchronously, so record_event only fails when a local write fails, rather than calling a remote service on the request path. AuthnMetrics::audit_store_outage fires on this path and should page rather than feed a dashboard, because every login is failing while it does.

One consequence is worth stating, because the obvious implementation gets it wrong. Every path that rejects a login emits before it returns, including the ones where the tenant or the identifier does not exist. That is what stops an audit outage from becoming a user-enumeration oracle: if only known users triggered an audit write, an attacker who could degrade the audit store would see Err for real accounts and an ordinary rejection for everything else, and could read off which identifiers are registered. Both paths write, so both fail identically.

The same change closes a blind spot that had nothing to do with outages: a credential-stuffing run against a list of addresses, none of which are registered, previously left no audit rows at all. Those attempts now appear as LoginAttempt / Failure with an error of unknown_tenant or unknown_identifier, unattributed or attributed to the tenant only.

Disclosure protocol

The vulnerability disclosure protocol lives in the canonical SECURITY.md at the repo root. The summary:

Vulnerability reports go through the private channel described in SECURITY.md (typically a security email or GitHub Security Advisories). Do not file vulnerabilities on the public issue tracker.

The maintainers acknowledge reports within a few business days and triage to a severity level. Critical and high-severity issues get a private fix in a security branch, a coordinated disclosure window, and a CVE if the issue warrants one. Lower severity issues fix in the normal development cycle.

Adopters are expected to keep their axess dependency current. Vulnerability fixes ship in the next patch release; the changelog notes which fixes are security-relevant. Deployments behind on patches accept the risk of the unfixed vulnerabilities.

Canonical SECURITY.md

The rest of this chapter is the canonical SECURITY.md from the repo root, included so the production checklist is in one place.

Security Policy

Reporting a Vulnerability

If you discover a security issue in Axess, please report it through GitHub's private vulnerability reporting (the Report a vulnerability button under the repository's Security tab) or by emailing security@gnomes.ch. Do not open a public issue.

Response targets (best-effort while the project is pre-1.0):

• Acknowledgement: within 48 hours of report
• Triage and severity assessment: within 7 calendar days
• Critical / High fix: patch release within 7 calendar days of confirmation
• Medium fix: patch in the next scheduled release (typically within 30 days)
• Advisory: published via GitHub Security Advisory once a fix is available

Only the latest 0.x minor receives security patches. If you are on an older version, upgrade to receive fixes.

Using Axess Securely

Axess is a library for authentication and authorization. Its security depends on correct integration and configuration in your application.

Production integration checklist

Transport and cookies

• Terminate TLS before Axess sees requests. All session cookies default to Secure; HttpOnly; SameSite=Lax.
• Set an HSTS header (Strict-Transport-Security: max-age=63072000; includeSubDomains) at the reverse-proxy or application layer so browsers never downgrade to HTTP.
• Use a cryptographically random 32-byte signing key loaded from a secrets manager. Never hard-code or re-use the all-zero example key.

CSRF

• Mount CsrfLayer on state-changing routes. The shipped middleware implements signed double-submit cookie protection; CsrfConfig::new(signing_key) is the entry point.
• SameSite=Lax (the cookie default) mitigates the most common vectors, but is not sufficient on older browsers or cross-site GET-triggered mutations; keep CsrfLayer engaged.
• For API-only endpoints, validate Origin / Referer headers or use a custom request header as a CSRF defence in addition.

Session binding and hijacking

• Enable session binding (e.g. UserAgentBinding) to detect cookie theft from a different browser/client.
• Understand the trade-off: session binding raises the bar for opportunistic theft but does not protect against an attacker who copies the User-Agent string along with the cookie.
• Consider combining with IP-subnet or TLS channel binding for higher-security environments.

Session registry and forced logout

• If using a session registry for forced logout, guard all authenticated routes with registry validity checks; not just require_authn!; so suspended or force-logged-out users cannot continue using stale sessions.
• Call suspend_user (which automatically invalidates registry entries) rather than updating store status manually.

Rate limiting

• Apply per-IP rate limiting on login, factor verification, and OAuth callback endpoints using the built-in RateLimitLayer. Axess enforces per-user lockout, but distributed brute-force across many usernames requires IP-level throttling.

Recommended configuration for authentication endpoints:

use axess::{RateLimitLayer, RateLimitConfig, KeyExtractor};
use std::time::Duration;

// Tight limit for login / factor verification (5 attempts per 60 s per IP).
let auth_rate_limit = RateLimitLayer::new(
    RateLimitConfig::builder()
        .max_requests(5)
        .window(Duration::from_secs(60))
        .key(KeyExtractor::ClientIp)
        .build(),
);

// Separate, tighter limit for OTP verification (3 attempts per 60 s).
let otp_rate_limit = RateLimitLayer::new(
    RateLimitConfig::builder()
        .max_requests(3)
        .window(Duration::from_secs(60))
        .key(KeyExtractor::ClientIp)
        .build(),
);

let app = Router::new()
    .route("/login", post(login_handler))
    .route("/verify-totp", post(totp_handler))
    .layer(auth_rate_limit)
    // Or apply per-route:
    .route("/verify-email-otp", post(otp_handler))
    .route_layer(otp_rate_limit);

• Rate-limit OTP verification endpoints separately; 8-digit email OTPs have 10^8 possibilities but a tighter window reduces feasibility further.

Trusted proxy and IP extraction

• Wrap the router in axess::client_ip::layer with a TrustedProxies set naming your proxies, and read ClientIp wherever an address is needed. Nothing reads a forwarded header directly any more: there is no function that takes one and believes it.
• Still configure your reverse proxy to strip client-supplied X-Forwarded-For and X-Real-IP. The trusted-proxy walk is defence in depth, not a substitute.

Rate limiting is required in front of login routes

• Apply the rate-limit layer to every route that reaches begin_login. Axess does not enforce it inside the service, and since 0.6.0 every failed login, including for identifiers that do not exist, writes an audit row, while a failed audit write fails the login. Without a limit, an unauthenticated caller can drive unbounded writes at your audit store, and exhausting it turns every login into a failure for every user. Your sink can also shed under load by returning AuditOutcome::Shed, but shed on a global rate or watermark, never on anything derived from which identifier was tried, or the drop becomes a user-enumeration signal.
• Alert on AuthnMetrics::audit_store_outage. It fires on exactly that path.
• Put the audit sink behind something durable: write locally, ship asynchronously, rather than a remote service on the request path.

Identity store lookup latency

• If your IdentityStore caches find_user or account_status, cache negative results on the same terms as positive ones. Axess equalises login response time between known and unknown identifiers using a fresh random id, which can never hit a cache; caching only real users inverts the timing signal and restores a user-enumeration oracle.

Session store selection

• In-memory stores (MemorySessionStore, MemoryRefreshTokenStore) are for testing only. They use non-constant-time lookups and do not persist across restarts.
• SQL stores (SqliteSessionStore, PostgresSessionStore, MysqlSessionStore) support optional AES-256-GCM encryption at rest via SqliteSessionStore::new(pool, SessionCrypto::new(key)); opt out only via the explicit ::plaintext(pool) constructor (dev/test only).
• Valkey store supports AES-256-GCM encryption via ValkeySessionStore::new(client, key). Plaintext available via ::plaintext(client) for dev/test.
• All encryption-capable stores support key rotation via SessionCrypto::with_previous_key(old_key); sessions encrypted with the previous key are transparently re-encrypted on the next access.

Content Security Policy

• Set a Content-Security-Policy header on all HTML responses to mitigate XSS impact. At minimum: default-src 'self'; script-src 'self'; style-src 'self'.
• Avoid unsafe-inline and unsafe-eval in CSP directives.

OAuth / OIDC

• Register only HTTPS issuer URLs. Axess rejects http:// issuer URLs in discovery (localhost / 127.0.0.1 / [::1] exemption for dev).
• Request the minimum scopes needed; avoid offline_access unless refresh tokens are required.
• Validate that the OAuth redirect URI matches exactly; do not use wildcard patterns.

Social login (plain OAuth 2.0)

• Prefer OIDC whenever the provider supports it. Reach for SocialProvider only for IdPs that explicitly don't (GitHub user login, Twitter/X, Discord, Reddit, Spotify, …).
• Understand the weaker security model: identity comes from a userinfo HTTPS GET, not from a signed assertion. A compromised IdP can impersonate any of its users to your service; you accept that blast radius when you adopt the provider.
• Keep PKCE on (the default). A handful of providers reject the extra parameter; SocialProvider::without_pkce is the opt-out and should be used sparingly.
• Verify csrf_state echo on the callback before calling exchange_code; SocialProvider::mint_csrf_state produces a fresh value routed through the same injectable RNG as PKCE.

Workload identity

• Pin the trust domain at resolver construction. Every shipped resolver (JwtSvidResolver, MtlsResolver, WorkloadResolver) accepts an expected TrustDomain and rejects tokens / certs whose synthesised WorkloadId lives under a different one; defense in depth against a confused-deputy where the JWKS or CA happens to be shared across trust domains.
• For the generic WorkloadResolver, keep adopter-supplied claim mappers strict about which subject paths the application admits. The recipes in examples/workload-identity/ are templates, not policy.
• When fetching SVIDs from a local SPIRE agent, use the spire-workload crate today; see docs/workload-identity/jwt-svid.md for the fetch-side recipe.

Dependencies

• Regularly update Axess and its dependencies (cargo update).
• Run cargo audit in CI to catch known vulnerabilities in the dependency tree.

Trusted proxy configuration (detailed)

Axess can extract client IP addresses from the X-Real-IP and X-Forwarded-For headers for audit logging and rate limiting. These headers are only trustworthy if your reverse proxy strips or overwrites them before forwarding, and if you use the trusted-proxy form described below.

If you don't run behind a trusted reverse proxy, these headers are user-controlled and any IP-based security decision (rate limiting, geo-blocking, audit trails) can be spoofed.

Configure your reverse proxy to:

1. Strip incoming X-Forwarded-For and X-Real-IP from client requests.
2. Set X-Real-IP to the immediate client address (TCP peer).
3. Append X-Forwarded-For with the client address (for multi-hop chains).

Example for nginx:

proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

What axess does with these headers

Since 0.6.0 axess does walk the forwarded chain and does maintain a trusted-proxy allowlist. trusted.client_ip(headers, peer):

1. Returns the TCP peer immediately if the peer is not itself a trusted proxy: an unproxied client's headers are never read.
2. Otherwise joins every X-Forwarded-For field line in order (RFC 9110 §5.3 makes repeated lines one comma-joined list) and walks it right to left, skipping hops that are themselves trusted, returning the first address that is not.
3. Stops at a malformed entry and returns the peer, rather than trusting past it.
4. Reads X-Real-IP only when no X-Forwarded-For is present, and only when there is exactly one such line: more than one means something appended rather than overwrote, so the first is whatever the client sent.

Rightmost-untrusted is the only correct reading: X-Forwarded-For is append-only, so the leftmost entry is whatever the client chose to put there. Axess took the leftmost entry before 0.6.0, which was spoofable through a correctly configured proxy.

Build the allowlist with exact addresses or CIDR ranges:

use axess::client_ip::TrustedProxies;

let trusted = TrustedProxies::from_cidrs(["10.0.0.0/8", "2001:db8::/32"])?;
// or, for a same-pod sidecar:
let trusted = TrustedProxies::loopback_only();

A spec with bits set below the prefix is rejected rather than widened: 10.0.0.5/8 is an error, because it reads like one host and would mean sixteen million. Write 10.0.0.0/8 or 10.0.0.5/32.

Since 0.7.0 you do not usually call the walk yourself. client_ip::layer runs it once per request, outside every route, and hands each handler a ClientIp:

let app = axess::client_ip::layer(app, trusted);

ClientIp has a private field and the layer is the only thing that fills it, so no amount of header reading produces one. Everything that wants an address takes it from there: the audit context, the Cedar request context, the rate limiter's KeyExtractor::ClientIp, the device gate, and lockout.

There is no longer a function that reads a forwarded header and believes it. The untrusted forms were removed in 0.7.0: a name carrying its own warning was tried twice and lost both times, once to a consumer that moved seven call sites onto one because its documentation recommended it.

Feature inventory

The shipped security surface, grouped by area. Caveats live in the Notes column.

Authentication factors

Sessions

Device identity

Workload identity

OAuth / OIDC ceremonies

On-behalf-of (OBO)

Authorization

Middleware

Audit and observability

PII classification

Axess processes personal data as part of authentication. This section documents what the library logs, stores, and never touches; useful for GDPR Data Protection Impact Assessments and SOC2 evidence packages.

What axess logs (via tracing and AuthEvent)

What axess stores in session data

What axess NEVER logs or stores

• Plaintext passwords (only Argon2id hashes are stored; input is zeroized after hashing)
• TOTP/HOTP secrets in logs (stored encrypted in FactorConfig, zeroized on drop)
• Session cookie values
• OAuth tokens (access, refresh, ID tokens); these stay in memory only during the exchange
• PKCE verifiers, CSRF state tokens (cleared from session after use)

Recommendations

• Encrypt at rest: pass a SessionCrypto::new(key) to the SQL session-store constructors (SqliteSessionStore::new(pool, crypto), same for Postgres / MySQL) or use ValkeySessionStore::new(client, key) so session data (which contains user_id) is AES-256-GCM protected. The explicit ::plaintext(pool) constructor opts out and is dev/test only.
• Log retention: configure your log aggregator to retain auth events per your compliance requirements (MiFID II: 5 years; GDPR: minimize).
• Right to erasure: deleting a user's sessions (SessionRegistry::invalidate_user) and database records satisfies GDPR erasure for axess-managed data. The custom session field is the application's responsibility.

Compliance framework mapping

GDPR

SOC2

PCI-DSS

HIPAA

These mappings are informational. Compliance certification requires assessment of the complete application stack, not just the authentication library.

Supported Versions

We recommend using the latest release of Axess and actively maintained branches.

Disclaimer

Axess is provided as a library. While we strive for secure defaults, the overall security of your application depends on your usage and integration.

Further reading

Operations runbook covers the production-launch checklist (key rotation, multi-instance considerations, graceful shutdown). Audit events and Audit pipeline cover the audit mechanisms the compliance frames depend on. Migration guide covers cross-version upgrade paths, including security-relevant breaking changes.