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, storage traits, and audit events. It deliberately contains no web
9//! framework, 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 completes the M3 primitive layer:
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`,
30//!                 `RateLimitStore` traits (RFC-005/006/007/008)
31//! - [`cookie`]  — secure cookie policy and builder (RFC-006)
32//! - [`audit`]   — `CodeAuthEvent` vocabulary and `AuditSink` trait (RFC-012)
33//! - [`error`]   — two-layer error model: internal causes + public-safe
34//!                 failures (RFC-012/021)
35//! - `mem`       — in-memory stores (`test-utils` feature only, RFC-011/008)
36
37/// The codlet wire/format version embedded in domain-separated HMAC inputs.
38///
39/// Bumping this is a breaking change to every stored lookup key and MUST be
40/// accompanied by a key-version migration (RFC-004).
41pub const FORMAT_VERSION: &str = "codlet/v1";
42
43pub mod audit;
44pub mod clock;
45pub mod code;
46pub mod cookie;
47pub mod error;
48pub mod hashing;
49pub mod rng;
50pub mod secret;
51pub mod state;
52pub mod store;
53
54/// In-memory store implementations for tests and local development.
55///
56/// **Not for production.** Gated behind the `test-utils` feature.
57#[cfg(any(test, feature = "test-utils"))]
58pub mod mem;
59
60// Convenience re-exports for the most common types.
61pub use audit::{AuditSink, CodeAuthEvent, NoopAuditSink};
62pub use clock::{Clock, SystemClock};
63pub use code::{Alphabet, CodePolicy, generate_code, normalize, validate_code_input};
64pub use cookie::{CookiePolicy, CookieProfile, SameSitePolicy};
65pub use error::{
66    CodeInputError, KeyError, PolicyError, PublicFormError, PublicRedemptionError,
67    PublicSessionError, RandomError, RedemptionFailReason,
68};
69pub use hashing::{
70    HmacKeyRef, KeyProvider, KeyVersion, LookupKey, SecretDomain, SecretHasher, StaticKeyProvider,
71};
72pub use rng::{RandomSource, SystemRandom};
73pub use secret::{
74    CodeId, FormTokenSecret, PlainCode, SecretString, SessionId, SessionSecret, SubjectId,
75};
76pub use state::{
77    ClaimOutcome, SessionValidationOutcome, TokenConsumeOutcome, classify_claim, classify_session,
78    classify_token_consume,
79};
80pub use store::{
81    error::{PublicAuthError, StoreError},
82    ratelimit::{
83        RateLimitKey, RateLimitOutcome, RateLimitPolicy, RateLimitStore, RateLimitUnavailable,
84    },
85    token::TokenSubject,
86};
87
88#[cfg(test)]
89mod tests {
90    use super::*;
91
92    #[test]
93    fn format_version_is_stable() {
94        // Guard against an accidental format bump. Changing this string is a
95        // breaking change requiring a key-version migration (RFC-004).
96        assert_eq!(FORMAT_VERSION, "codlet/v1");
97    }
98}
codlet_core/lib.rs

codlet_core/
lib.rs
