codlet_core/
lib.rs

1#![forbid(unsafe_code)]
2#![doc = include_str!("../README.md")]
3
4//! # codlet-core
5//!
6//! Runtime-neutral authentication primitives. This crate contains pure types,
7//! policy objects, cryptographic lookup-key derivation, lifecycle state
8//! machines, and storage *traits*. It deliberately contains no web framework,
9//! database, or async-executor dependencies (RFC-002).
10//!
11//! ## Boundary
12//!
13//! codlet authenticates a subject. The host application authorizes that
14//! subject (RFC-001). Nothing in this crate decides community membership,
15//! roles, permissions, or resource access.
16//!
17//! ## Status
18//!
19//! This release adds lifecycle state machines and storage traits:
20//!
21//! - [`code`]    — code policy, generation, normalization, validation (RFC-003)
22//! - [`hashing`] — HMAC lookup-key derivation, key providers, domain
23//!                 separation, key versioning (RFC-004)
24//! - [`rng`]     — fail-closed randomness abstraction (RFC-020)
25//! - [`secret`]  — redacted secret newtypes and opaque IDs (RFC-019 foundation)
26//! - [`clock`]   — `Clock` trait for testable time (RFC-020)
27//! - [`state`]   — pure lifecycle classifiers: claim, session, form-token
28//!                 consume (RFC-005/006/007)
29//! - [`store`]   — `CodeStore`, `SessionStore`, `FormTokenStore` traits
30//!                 (RFC-005/006/007)
31//! - [`cookie`]  — secure cookie policy and builder (RFC-006)
32//! - [`error`]   — internal error layer (RFC-021)
33//! - `mem`      — in-memory stores (`test-utils` feature only, RFC-011)
34
35/// The codlet wire/format version embedded in domain-separated HMAC inputs.
36///
37/// Bumping this is a breaking change to every stored lookup key and MUST be
38/// accompanied by a key-version migration (RFC-004).
39pub const FORMAT_VERSION: &str = "codlet/v1";
40
41pub mod clock;
42pub mod code;
43pub mod cookie;
44pub mod error;
45pub mod hashing;
46pub mod rng;
47pub mod secret;
48pub mod state;
49pub mod store;
50
51/// In-memory store implementations for tests and local development.
52///
53/// **Not for production.** Gated behind the `test-utils` feature.
54#[cfg(any(test, feature = "test-utils"))]
55pub mod mem;
56
57// Convenience re-exports for the most common types.
58pub use clock::{Clock, SystemClock};
59pub use code::{Alphabet, CodePolicy, generate_code, normalize, validate_code_input};
60pub use cookie::{CookiePolicy, CookieProfile, SameSitePolicy};
61pub use error::{CodeInputError, KeyError, PolicyError, RandomError};
62pub use hashing::{
63    HmacKeyRef, KeyProvider, KeyVersion, LookupKey, SecretDomain, SecretHasher, StaticKeyProvider,
64};
65pub use rng::{RandomSource, SystemRandom};
66pub use secret::{
67    CodeId, FormTokenSecret, PlainCode, SecretString, SessionId, SessionSecret, SubjectId,
68};
69pub use state::{
70    ClaimOutcome, SessionValidationOutcome, TokenConsumeOutcome, classify_claim, classify_session,
71    classify_token_consume,
72};
73pub use store::{
74    error::{PublicAuthError, StoreError},
75    token::TokenSubject,
76};
77
78#[cfg(test)]
79mod tests {
80    use super::*;
81
82    #[test]
83    fn format_version_is_stable() {
84        // Guard against an accidental format bump. Changing this string is a
85        // breaking change requiring a key-version migration (RFC-004).
86        assert_eq!(FORMAT_VERSION, "codlet/v1");
87    }
88}
codlet_core/lib.rs

codlet_core/
lib.rs
