GaleForce.Services.Auth 1.0.0

GaleForce.Services.Auth

.NET authentication services library providing password hashing and email functionality.

Features

• PBKDF2 Password Hashing - Secure password hashing with SHA256 (100,000 iterations)
• SMTP Email Sender - Production email sending via SMTP (PurelyMail, SendGrid, etc.)
• Development Email Logger - Console logging for local development
• Easy DI Setup - Simple dependency injection registration

Installation

# Local reference (not yet published to NuGet)
dotnet add reference path/to/GaleForce.Services/dotnet/GaleForce.Services.Auth/GaleForce.Services.Auth.csproj

Quick Start

1. Register Services

// Program.cs
using GaleForce.Services.Auth.Extensions;

builder.Services.AddGaleForceAuth(builder.Configuration);

2. Configure Email (appsettings.json)

{
  "Email": {
    "SmtpHost": "smtp.purelymail.com",
    "SmtpPort": 587,
    "UseSsl": true,
    "SmtpUsername": "noreply@example.com",
    "SmtpPassword": "your-password",
    "DefaultFromEmail": "noreply@example.com",
    "DefaultFromName": "Example App"
  }
}

3. Use in Controllers/Services

using GaleForce.Services.Auth.Services;

public class AuthController : ControllerBase
{
    private readonly IPasswordHasher _passwordHasher;
    private readonly IEmailSender _emailSender;

    public AuthController(
        IPasswordHasher passwordHasher,
        IEmailSender emailSender)
    {
        _passwordHasher = passwordHasher;
        _emailSender = emailSender;
    }

    [HttpPost("register")]
    public async Task<IActionResult> Register(RegisterRequest request)
    {
        // Hash password
        var passwordHash = _passwordHasher.HashPassword(request.Password);

        // Save user with hashed password...
        var user = new User
        {
            Email = request.Email,
            PasswordHash = passwordHash
        };

        // Send welcome email
        await _emailSender.SendEmailAsync(
            toEmail: user.Email,
            subject: "Welcome!",
            htmlBody: "<p>Thanks for registering!</p>"
        );

        return Ok();
    }

    [HttpPost("login")]
    public IActionResult Login(LoginRequest request)
    {
        var user = GetUserByEmail(request.Email);

        // Verify password
        if (!_passwordHasher.VerifyPassword(request.Password, user.PasswordHash))
        {
            return Unauthorized();
        }

        return Ok(new { token = GenerateToken(user) });
    }
}

API Reference

IPasswordHasher

string HashPassword(string password);
bool VerifyPassword(string password, string storedHash);
bool NeedsUpgrade(string storedHash);

IEmailSender

Task SendEmailAsync(
    string toEmail,
    string subject,
    string htmlBody,
    string? textBody = null,
    string? fromEmail = null,
    string? fromName = null,
    CancellationToken ct = default);

Configuration Options

// appsettings.json
{
  "Email": {
    "SmtpHost": "smtp.purelymail.com",    // SMTP server
    "SmtpPort": 587,                      // SMTP port (587 for TLS)
    "UseSsl": true,                       // Use SSL/TLS
    "SmtpUsername": "user@example.com",   // SMTP username
    "SmtpPassword": "password",           // SMTP password
    "DefaultFromEmail": "noreply@example.com",
    "DefaultFromName": "App Name",
    "TimeoutMs": 30000                    // Timeout (default 30s)
  }
}

Development Mode

If SmtpPassword is not configured, the library automatically uses DevEmailSender which logs emails to console instead of sending them.

// Or explicitly use dev email sender
builder.Services.AddGaleForceAuthWithDevEmail();

Security Best Practices

Password Hashing

• Uses PBKDF2-SHA256 with 100,000 iterations (OWASP recommended)
• Generates cryptographically secure random salt (256 bits)
• Constant-time comparison to prevent timing attacks
• Stores salt + hash as Base64 string

Password Reset Tokens

• Generate cryptographically secure random tokens
• Set expiration time (recommend 1 hour)
• Invalidate token after use
• Store tokens in database (see PasswordResetToken model)

Email Providers

PurelyMail

{
  "Email": {
    "SmtpHost": "smtp.purelymail.com",
    "SmtpPort": 587,
    "UseSsl": true
  }
}

SendGrid

{
  "Email": {
    "SmtpHost": "smtp.sendgrid.net",
    "SmtpPort": 587,
    "UseSsl": true,
    "SmtpUsername": "apikey",
    "SmtpPassword": "SG.xxxxx..."
  }
}

Gmail

{
  "Email": {
    "SmtpHost": "smtp.gmail.com",
    "SmtpPort": 587,
    "UseSsl": true,
    "SmtpUsername": "your-email@gmail.com",
    "SmtpPassword": "app-specific-password"
  }
}

License

MIT License - See LICENSE file