Crate codlet_core 

codlet-core

Runtime-neutral authentication primitives for codlet.

This crate holds pure types, policy objects, cryptographic lookup-key derivation, lifecycle state machines, and storage traits. It has no web framework, database, or async-executor dependencies.

codlet authenticates a subject; the host application authorizes that subject. This crate never decides membership, roles, permissions, or resource access.

Status: early pre-release (v0.1.0). The cryptographic primitives — code policy/generation/normalization/validation (RFC-003) and HMAC lookup-key derivation, key providers, domain separation, and key versioning (RFC-004) — are implemented and tested. Storage traits, session/form-token lifecycle, and adapters are still to come. Do not yet rely on this crate for a complete production authentication flow.

License

Apache-2.0

codlet-core

Runtime-neutral authentication primitives. This crate contains pure types, policy objects, cryptographic lookup-key derivation, lifecycle state machines, and storage traits. It deliberately contains no web framework, database, or async-executor dependencies (RFC-002).

Boundary

codlet authenticates a subject. The host application authorizes that subject (RFC-001). Nothing in this crate decides community membership, roles, permissions, or resource access.

Status

This release implements the first cryptographic primitives:

• code — code policy, generation, normalization, validation (RFC-003)
• hashing — HMAC lookup-key derivation, key providers, domain separation, key versioning (RFC-004)
• rng — fail-closed randomness abstraction (RFC-020)
• secret — redacted secret newtypes and opaque IDs (RFC-019 foundation)
• error — internal error layer (RFC-021)

Forthcoming modules (added with their RFCs):

• state — pure lifecycle classifiers (RFC-005/006/007)
• store — storage traits (RFC-005..008)

Example

Generate a code and derive the value that would be stored (never the plaintext). End-to-end redemption needs the storage traits, still to come.

use codlet_core::{CodePolicy, SecretDomain, SecretHasher, StaticKeyProvider};
use codlet_core::{generate_code, validate_code_input};
use codlet_core::rng::SystemRandom;
use std::time::Duration;

let policy = CodePolicy::default_human(Duration::from_secs(24 * 3600)).unwrap();

let mut rng = SystemRandom::new();
let code = generate_code(&policy, &mut rng).unwrap();

let hasher = SecretHasher::new(
    StaticKeyProvider::single("v1", b"real-key-from-secret-manager".to_vec()).unwrap(),
);
let normalized = validate_code_input(code.expose(), &policy).unwrap();
let (lookup_key, key_version) =
    hasher.lookup_key(SecretDomain::Code, &normalized).unwrap();
assert_eq!(key_version.as_str(), "v1");
assert_eq!(lookup_key.as_str().len(), 64);
// Persist `lookup_key` + `key_version`; never persist `code`.

Re-exports

pub use code::Alphabet;

pub use code::CodePolicy;

pub use code::generate_code;

pub use code::normalize;

pub use code::normalize;

pub use code::validate_code_input;

pub use error::CodeInputError;

pub use error::KeyError;

pub use error::PolicyError;

pub use error::RandomError;

pub use hashing::HmacKeyRef;

pub use hashing::KeyProvider;

pub use hashing::KeyVersion;

pub use hashing::LookupKey;

pub use hashing::SecretDomain;

pub use hashing::SecretHasher;

pub use hashing::StaticKeyProvider;

pub use rng::RandomSource;

pub use rng::SystemRandom;

pub use secret::CodeId;

pub use secret::FormTokenSecret;

pub use secret::PlainCode;

pub use secret::SecretString;

pub use secret::SessionId;

pub use secret::SessionSecret;

pub use secret::SubjectId;

Modules

code

One-time code policy, generation, normalization, and validation (RFC-003).

error

Error types for codlet-core.

hashing

Secret hashing, key providers, domain separation, and key versioning (RFC-004).

rng

Randomness abstraction (RFC-020).

secret

Secret-bearing and opaque-identifier newtypes.

Constants

FORMAT_VERSION

The codlet wire/format version embedded in domain-separated HMAC inputs.