argon2_creds/lib.rs
1// SPDX-FileCopyrightText: 2023 Aravinth Manivannan <realaravinth@batsense.net>
2//
3// SPDX-License-Identifier: AGPL-3.0-or-later
4
5//! Argon2-Creds provides abstractions over credential management and cuts down on boilerplate code
6//! required to implement authenticatin
7//!
8//! ## Example
9//!
10//! 1. The easiest way to use this crate is with the default configuration. See `Default`
11//! implementation for the default configuration.
12//!
13//! ```rust
14//! use argon2_creds::Config;
15//! let config = Config::default();
16//!
17//! let password = "ironmansucks";
18//! let hash = config.password(password).unwrap();
19//!
20//! // email validation
21//! config.email("batman@we.net").unwrap();
22//!
23//! // process username
24//! let username = config.username("Realaravinth").unwrap(); // process username
25//!
26//! // generate hash
27//! let hash = config.password(password).unwrap();
28//!
29//! assert_eq!(username, "realaravinth");
30//! assert!(Config::verify(&hash, password).unwrap(), "verify hashing");
31//! ```
32//!
33//! 2. To gain fine-grained control over how credentials are managed, consider using
34//! [ConfigBuilder]:
35//!
36//!```rust
37//! use argon2_creds::{ConfigBuilder, PasswordPolicy, Config};
38//!
39//! let config = ConfigBuilder::default()
40//! .username_case_mapped(false)
41//! .profanity(true)
42//! .blacklist(false)
43//! .password_policy(PasswordPolicy::default())
44//! .build()
45//! .unwrap();
46//!
47//! let password = "ironmansucks";
48//! let hash = config.password(password).unwrap();
49//!
50//! // email validation
51//! config.email("batman@we.net").unwrap();
52//!
53//! // process username
54//! let username = config.username("Realaravinth").unwrap(); // process username
55//!
56//! // generate hash
57//! let hash = config.password(password).unwrap();
58//!
59//! assert_eq!(username, "realaravinth");
60//! assert!(Config::verify(&hash, password).unwrap(), "verify hashing");
61//!```
62//!
63//! ## Documentation & Community Resources
64//!
65//! In addition to this API documentation, other resources are available:
66//! * [Examples](https://github.com/realaravinth/argon2-creds/)
67//!
68//! To get started navigating the API docs, you may consider looking at the following pages first:
69//!
70//! * [Config]: This struct is the entry point to `argon2_creds`
71//!
72//! * [CredsError]: This module provides essential types for errors that can occur during
73//! credential processing
74//!
75//! ## Features
76//!
77//! * [rust-argon2](https://crates.io/rust-argon2)-based password hashing
78//! * PRECIS Framework [UsernameCaseMapped](https://tools.ietf.org/html/rfc8265#page-7)
79//! * Keep-alive and slow requests handling
80//! * Profanity filter based off of
81//! [List-of-Dirty-Naughty-Obscene-and-Otherwise-Bad-Words](https://github.com/LDNOOBW/List-of-Dirty-Naughty-Obscene-and-Otherwise-Bad-Words)
82//! * Problematic usernames filter based off of
83//! [The-Big-Username-Blacklist](https://github.com/marteinn/The-Big-Username-Blacklist)
84//! * Email validation using [validator](https://crates.io/validator)
85
86pub mod config;
87pub mod errors;
88mod filters;
89
90pub use crate::config::{Config, ConfigBuilder, PasswordPolicy, PasswordPolicyBuilder};
91pub use crate::errors::{CredsError, CredsResult};