Crate confirm_email

confirm_email

confirm_email is a lightweight Rust crate for generating and validating URL-safe, encrypted email confirmation tokens with configurable expiry.

Purpose

The confirm_email crate addresses a common requirement in user registration systems: verifying that users have access to the email addresses they provide. When users register for an account, the system needs to confirm their email address before fully activating their account or granting access to certain features.

This library generates secure, encrypted tokens that can be embedded in confirmation emails sent to users. When users click the confirmation link, the application validates the token to verify the email address and complete the registration process. The tokens contain the user’s email address and an expiration timestamp, ensuring that confirmation links remain valid only for a specified period.

The crate is designed for applications that need reliable email verification without the complexity of managing token storage in databases or external services. All token information is self-contained and cryptographically protected, making the system both secure and stateless.

Features

• Generate a token containing an email address and expiration timestamp, encrypted and encoded as a compact string.
• Configure token validity duration (default: 1 day).
• Validate and decrypt a token, returning the original email or a descriptive error if the token is invalid or expired.

Quickstart

Add this to your Cargo.toml:

[dependencies]
confirm_email = "0.1"

Usage

use confirm_email::{generate_token, generate_token_with_expiration, validate_token};
use confirm_email::error::Error;

// 1. Generate a token with default expiry (1 day):
let token = generate_token(
    "user@example.com".to_string(),
    "super_secret_key".to_string(),
).expect("Error generating token with default validity");

// 2. Generate a token with custom expiry (e.g., 3600 seconds = 1 hour):
let hour_token = generate_token_with_expiration(
    "user@example.com".to_string(),
    "super_secret_key".to_string(),
    3600,
).expect("Error generating token with custom validity");

// 3. Validate and decrypt the token:
match validate_token(token.clone(), "super_secret_key".to_string()) {
    Ok(email) => println!("Confirmed email: {}", email),
    Err(Error::Expired(ts)) => eprintln!("Token expired at {}", ts),
    Err(e) => eprintln!("Invalid token: {}", e),
}

API

• [generate_token(email, key)] Generate a token for email using key, valid for the default duration (1 day).

• [generate_token_with_expiration(email, key, exp_seconds)] Generate a token for email using key, valid for exp_seconds seconds.

• [validate(token, key)] Decrypt and verify token with key. Returns the original email on success or an [Other] on failure (Expired, Invalid, etc.).

License

MIT

Modules

error

Contains definitions for the possible errors

Functions

generate_token

Generates a token with the default expiration time.

generate_token_with_expiration

Generates a token with a specified expiration time in seconds.

validate_token

Parse the token and if valid returns the corresponding email.