1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
// 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`](password::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`](token::Token)**: Represents a high-entropy, fixed-length stack-allocated generated secret
//! (e.g., session IDs, API keys).
//! - **[`GenericToken`](token::GenericToken)**: A dynamically-sized, heap-allocated alternative to `Token`
//! when lengths cannot be determined at compile time.
//! - **[`EncryptedToken`](token::EncryptedToken)**: A type-safe wrapper for token material that has been
//! reversibly encrypted for storage using authenticated encryption (AEAD).
//!
//! ## Security Model
//!
//! 1. **Zeroization**: Raw secret materials ([`Password`](password::Password), [`Token`], and [`GenericToken`](token::GenericToken))
//! automatically zero their 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`](password::PasswordHash), [`TokenHash`](token::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, TokenMaterial};
//! // 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, alongside [`EncryptedToken`](token::EncryptedToken).
//! - `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
pub
pub
pub use ;
pub use ;