Authentication Deep Dive

{
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "admin@example.com",
  "given_name": "John",
  "family_name": "Doe",
  "role": "SuperAdmin",
  "permissions": [
    "admins.view", "admins.create", "admins.update",
    "users.view", "users.create", "roles.manage"
  ],
  "tenant_id": "f8e7d6c5-b4a3-2190-fedc-ba0987654321",
  "is_admin": "true",
  "impersonator_id": null,
  "iat": 1708444800,
  "exp": 1708445700,
  "iss": "scripe-api",
  "aud": "scripe-client"
}

// Hash password with BCrypt (work factor = 12)
// ~250ms per hash — intentionally slow to resist brute force
var hashedPassword = BCrypt.Net.BCrypt.HashPassword(
    plainPassword,
    workFactor: 12  // 2^12 = 4,096 iterations
);

// Verify password during login
var isValid = BCrypt.Net.BCrypt.Verify(plainPassword, storedHash);
// Returns true/false — constant-time comparison prevents timing attacks

public class TfaService : ITfaService
{
    private const int SecretLength = 20;     // 160-bit secret
    private const int CodeLength = 6;        // 6-digit TOTP
    private const int TimeStep = 30;         // 30-second window
    private const int BackupCodeCount = 10;  // 10 backup codes

    public TfaSetupResult EnableTfa(string userId)
    {
        // 1. Generate random secret
        var secretBytes = RandomNumberGenerator.GetBytes(SecretLength);
        var secret = Base32Encoding.ToString(secretBytes);

        // 2. Generate QR code URI (otpauth:// format)
        var uri = $"otpauth://totp/SCRIPE:{userId}?secret={secret}&issuer=SCRIPE";

        // 3. Generate backup codes
        var backupCodes = Enumerable.Range(0, BackupCodeCount)
            .Select(_ => GenerateBackupCode())
            .ToList();

        return new TfaSetupResult(secret, uri, backupCodes);
    }

    public bool VerifyCode(string secret, string code)
    {
        // Validate TOTP with ±1 time step tolerance
        var totp = new Totp(Base32Encoding.ToBytes(secret),
            step: TimeStep, totpSize: CodeLength);

        return totp.VerifyTotp(code, out _, new VerificationWindow(1, 1));
    }

    private static string GenerateBackupCode()
        => $"{Random.Shared.Next(10000000, 99999999)}"; // 8-digit
}

public class ExternalAuthService : IExternalAuthService
{
    public async Task<ExternalUserInfo?> ValidateTokenAsync(
        string provider, string token)
    {
        return provider.ToLower() switch
        {
            "google" => await ValidateGoogleTokenAsync(token),
            "facebook" => await ValidateFacebookTokenAsync(token),
            "apple" => await ValidateAppleTokenAsync(token),
            "microsoft" => await ValidateMicrosoftTokenAsync(token),
            _ => throw new ArgumentException($"Unknown provider: {provider}")
        };
    }
}

// Returned user info for account linking/creation
public record ExternalUserInfo(
    string ProviderId,     // Provider's unique user ID
    string Email,
    string? FirstName,
    string? LastName,
    string? AvatarUrl,
    string Provider        // "google", "facebook", etc.
);

public class OtpService : IOtpService
{
    public async Task<string> GenerateAsync(
        string userId, OtpPurpose purpose, CancellationToken ct)
    {
        // 1. Invalidate any existing OTP for this user+purpose
        await _repository.InvalidateExistingAsync(userId, purpose, ct);

        // 2. Generate cryptographically random 6-digit code
        var code = RandomNumberGenerator.GetInt32(100000, 999999).ToString();

        // 3. Store hashed code (never store plaintext)
        var otpCode = new OtpCode
        {
            UserId = userId,
            Purpose = purpose,
            CodeHash = BCrypt.Net.BCrypt.HashPassword(code),
            ExpiresAt = DateTime.UtcNow.AddMinutes(15),
            RemainingAttempts = 3
        };

        await _repository.AddAsync(otpCode, ct);
        return code; // Return plaintext to send via email/SMS
    }

    public async Task<bool> VerifyAsync(
        string userId, string code, OtpPurpose purpose, CancellationToken ct)
    {
        var otp = await _repository.GetLatestAsync(userId, purpose, ct);
        if (otp is null || otp.ExpiresAt < DateTime.UtcNow) return false;
        if (otp.RemainingAttempts <= 0) return false;

        var isValid = BCrypt.Net.BCrypt.Verify(code, otp.CodeHash);
        if (!isValid)
        {
            otp.RemainingAttempts--;
            await _repository.SaveChangesAsync(ct);
            return false;
        }

        // Mark as used
        otp.UsedAt = DateTime.UtcNow;
        await _repository.SaveChangesAsync(ct);
        return true;
    }
}