Crate aster_forge_auth

Expand description

Product-neutral local session authentication mechanics.

aster_forge_auth owns JWT token contracts, validation policy, token-pair issuance, and the refresh-rotation coordinator. Product repositories own account state, database transactions, session tables, cookies, permissions, audit events, and error presentation. Persistence is accessed through RefreshSessionStore, so this crate does not depend on SeaORM or a product schema.

Select exactly one Cargo backend feature: aws-lc-rs (default) or rust-crypto. The product entrypoint must call initialize_jwt_crypto_provider before any JWT use, including direct jsonwebtoken calls. This installs a process-wide provider, not an instance-specific backend. Signing algorithms remain a runtime JwtPolicy choice.

use aster_forge_auth::{AuthTokenType, JwtKey, JwtPolicy, JwtSigner, JwtVerifier,
    Restriction, SessionId, SessionVersion, Subject};

aster_forge_auth::initialize_jwt_crypto_provider()?;
let key = JwtKey::hmac([42; 32])?; // Product loads a dedicated random signing key.
let policy = JwtPolicy::new("product", "local-web", 900, 604_800)?;
let signer = JwtSigner::with_system_clock(key.clone(), policy.clone());
let verifier = JwtVerifier::with_system_clock(key, policy);
let pair = signer.issue(Subject::new("42")?, SessionId::new("session-1")?,
    SessionVersion::new(1), Restriction::None)?;
let verified = verifier.verify(&pair.access_token, AuthTokenType::Access)?;
assert_eq!(verified.claims().sub.as_str(), "42");
// Product persists the session before publishing pair, and checks current authorization.

Structs§

AuthTokenPair: Candidate credentials; commit their refresh identity before releasing token strings.
ClientContext: Untrusted client metadata used only for stale-retry classification, never device authentication.
FixedClock: Fixed clock for deterministic tests and product integration tests.
JwtKey: HMAC key wrapper. Products own entropy, loading, rotation, and isolation from AEAD keys.
JwtPolicy: Issuance lifetimes and strict namespace. Namespace/session checks cannot be disabled. Old JWT formats require reauthentication rather than an implicit fallback parser.
JwtSigner: Product-configured signer with injectable clock and ID source.
JwtVerifier: Strict verifier: only signature-verified claims cross the validation boundary.
PasswordHashRuntime: Instance-owned blocking executor with a memory/CPU concurrency budget.
RandomIdSource: Production ID source using the upstream UUID v4 implementation.
RefreshCoordinator: Instance resource shared by all refresh requests. No global singleton or historical-JTI leak. The finite budget includes running requests and same-JTI waiters; saturation rejects promptly. It complements, never replaces, the product’s authoritative cross-instance database CAS.
RefreshJti: Single-use refresh identity. Debug output is always redacted.
RefreshRotationRequest: Candidate mutation submitted to the product’s writer transaction. It contains IDs and expiry, never token strings. Stores must recheck current account state, version, restriction and session ownership, then use classify_refresh before conditional rotation or atomic reuse revocation.
RefreshSession: Authoritative product session snapshot, read under the transaction used for the decision.
RefreshTokenService: Refresh workflow combining strict JWT checks, a shared instance coordinator, and product CAS. The coordinator can be reused while products rebuild signers for dynamic lifetime configuration.
SessionId: Server-side session identity, distinct from its single-use refresh JTI.
SessionVersion: Account-wide generation; revocation must fail on overflow rather than reuse a version.
Subject: Stable product subject; integer IDs and UUIDs use their string representation.
SystemClock: Production clock backed by SystemTime.
TokenClaims: Required local web-session claims. No product entities or permissions are embedded. Claims are signed, not encrypted, and must never carry secrets.
VerifiedToken: Signature/policy-verified claims. Private construction prevents labeling unchecked JSON as verified. Current account, session, and permissions still require product checks.

Enums§

AuthError: Errors produced by the product-neutral authentication mechanism.
AuthTokenType: Local session credential purpose; OAuth access and OIDC ID tokens use other contracts.
JwtAlgorithm: Supported HMAC algorithms; headers cannot select a different key family.
PasswordWorkError: Redacted async password-work errors. Products map these at their own boundary.
RefreshDecision: Pure state-machine decision; products apply its effects atomically in their own transaction.
RefreshError: Refresh failure separates mechanism failures from the product’s unmodified persistence error.
RefreshOutcome: Post-commit result. Only the successful branch contains usable replacement credentials.
RefreshPolicy: Explicit replay policy. Both variants reject old credentials; neither grants a second refresh.
RefreshRejection: Authentication rejection, distinct from persistence/commit failure and never containing tokens.
RefreshStoreOutcome: Transaction result. A store must not return success or reuse until all required writes commit.
Restriction: Authentication restriction. Products decide which operations a restricted session may perform.

Constants§

DEFAULT_PASSWORD_HASH_MAX_CONCURRENCY: Default number of concurrent memory-hard password jobs.

Traits§

Clock: Time source used by token issuance and validation.
IdSource: Supplies unpredictable refresh IDs in production and deterministic IDs in tests.
RefreshSessionStore: Product persistence boundary. Forge never opens a database transaction or maps product errors.

Functions§

classify_refresh: Classifies authoritative session state without accessing product entities or performing effects.
initialize_jwt_crypto_provider: Installs the backend selected by this crate’s Cargo features for the entire process.

Type Aliases§

Result: Result returned by authentication primitives.