// Copyright 2026 Thomas Zuyev

// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at

//     http://www.apache.org/licenses/LICENSE-2.0

// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! # sealwd
//!
//! `sealwd` provides small, focused primitives for handling secrets safely in Rust.
//!
//! The crate is specifically designed for server-side authentication and secret management systems.
//! It enforces a strict, type-level separation between user-provided passwords and system-generated
//! tokens, ensuring that the correct cryptographic algorithms are applied to each.
//!
//! ## Core Primitives
//!
//! - **[`Password`]**: Represents a low-entropy user secret. Passwords are hashed using
//!   Argon2id, a slow and memory-hard algorithm designed to resist brute-force attacks.
//! - **[`Token`]**: Represents a high-entropy, fixed-length generated secret (e.g., session IDs,
//!   API keys, refresh tokens). Tokens are hashed using BLAKE3 combined with a server-side pepper,
//!   optimizing for speed while maintaining security.
//!
//! ## Security Model
//!
//! 1. **Zeroization**: Raw secret material ([`Password`], [`Token`]) automatically zeroes its memory
//!    when dropped, reducing the risk of sensitive data lingering in RAM.
//! 2. **Explicit Separation**: Using fast token hashing (BLAKE3) for low-entropy passwords is
//!    insecure and intentionally unsupported. The API enforces Argon2id for passwords.
//! 3. **Forward Compatibility**: Serialized hashes ([`PasswordHash`], [`TokenHash`]) are
//!    self-describing, embedding an algorithm identifier to allow seamless future upgrades.
//!
//! ## Example: Password Lifecycle
//!
//! ```rust
//! # use sealwd::{Password, PasswordPolicy};
//! let policy = PasswordPolicy::with_sane_defaults();
//!
//! // Generate a password that passes the policy
//! let password = Password::random(&policy).unwrap();
//!
//! // Hash for storage (Argon2id)
//! let hash = password.to_default_hash().unwrap();
//!
//! // Verify
//! assert!(hash.verify(&password).is_ok());
//! ```
//!
//! ## Example: Token Lifecycle
//!
//! ```rust
//! # use sealwd::Token;
//! // Generate a 32-byte token
//! let token = Token::<32>::random().unwrap();
//!
//! // Convert to Base64 to give to the user
//! let b64 = token.to_base64();
//!
//! // Hash with a server pepper for database storage (BLAKE3)
//! let pepper = b"server-side-secret-pepper";
//! let stored_hash = token.to_default_hash(pepper);
//! ```
//!
//! ## Feature Flags
//!
//! - `encryption`: Enables the [`crypto`] module, providing authenticated encryption (AEAD)
//!   primitives for secrets that must be stored reversibly.
//! - `serde`: Implements `Serialize` and `Deserialize` for the crate's types.
//! - `sqlx`: Implements database encoding/decoding, mapping hash and encrypted types
//!   transparently to database binary columns (e.g., `BYTEA` in PostgreSQL).
//!
//! ## Non-goals
//!
//! This crate does **not** attempt to be a general-purpose key derivation framework,
//! a secret storage engine, or a full authentication protocol implementation. It provides
//! the cryptographic building blocks intended to be composed by higher-level systems.

pub(crate) mod encoding;
pub(crate) mod random;

#[cfg(feature = "encryption")]
pub mod crypto;

pub mod password;
pub mod range;
pub mod token;

pub use password::{Password, PasswordHash, PasswordPolicy};
pub use token::{Token, TokenHash};
