goAuth

Low-latency authentication engine for Go: JWT access tokens + Redis-backed sessions + rotating refresh tokens + bitmask RBAC.

---

Features

• Three validation modes — JWT-only (0 Redis ops), Hybrid, Strict (instant revocation)
• Refresh token rotation — atomic Lua CAS with replay detection
• MFA — TOTP (RFC 6238) + backup codes with rate limiting
• Password management — Argon2id hashing, reset (Token/OTP/UUID strategies), change with reuse detection
• Email verification — enumeration-resistant with Lua CAS consumption
• Permission system — 64/128/256/512-bit frozen bitmasks, O(1) checks
• Rate limiting — 7-domain fixed-window limiters + auto-lockout
• Device binding — IP/UA fingerprint enforcement or anomaly detection
• Audit + Metrics — 44 counters, latency histogram, Prometheus + OpenTelemetry exporters
• Multi-tenancy — tenant-scoped sessions, counters, and rate limits

Showcase

goAuth is used in SuperAPI, a modular SaaS backend template designed for production use from day one.

SuperAPI
Modular SaaS backend template with policy pipelines, caching, rate limiting, and observability.

It provides:

• A module-oriented API architecture
• Policy-based middleware wiring
• Built-in auth, caching, rate limiting, and observability primitives
• A store-first data layer with strict boundaries

Quickstart

package main

import (
    "context"
    "fmt"
    "log"

    goAuth "github.com/MrEthical07/goAuth"
    "github.com/redis/go-redis/v9"
)

func main() {
    rdb := redis.NewClient(&redis.Options{Addr: "127.0.0.1:6379"})

    engine, err := goAuth.New().
        WithRedis(rdb).
        WithPermissions([]string{"user.read", "user.write"}).
        WithRoles(map[string][]string{
            "admin": {"user.read", "user.write"},
        }).
        WithUserProvider(myProvider{}).
        Build()
    if err != nil {
        log.Fatal(err)
    }
    defer engine.Close()

    // Login
    access, refresh, err := engine.Login(context.Background(), "alice@example.com", "password")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Access:", access[:20]+"...")

    // Validate
    result, err := engine.ValidateAccess(context.Background(), access)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("UserID:", result.UserID)

    // Refresh
    newAccess, newRefresh, err := engine.Refresh(context.Background(), refresh)
    _ = newAccess
    _ = newRefresh
}

See examples/http-minimal for a complete HTTP server with login, refresh, logout, and protected routes.

Installation

go get github.com/MrEthical07/goAuth

Requirements: Go 1.24+, Redis 6+

Validation Modes

Mode	Redis Ops	Use Case
ModeJWTOnly	0	Stateless microservices, dashboards
ModeHybrid	0–1	Most applications (default)
ModeStrict	1	Financial, healthcare, compliance

// Per-route mode with middleware
mux.Handle("/api/read", middleware.RequireJWTOnly(engine)(readHandler))
mux.Handle("/api/admin", middleware.RequireStrict(engine)(adminHandler))

Configuration

// Start from a preset
cfg := goAuth.HighSecurityConfig()
cfg.JWT.AccessTTL = 3 * time.Minute

// Lint for misconfigurations
if err := cfg.Lint().AsError(goAuth.LintHigh); err != nil {
    log.Fatal(err)
}

Three presets: DefaultConfig(), HighSecurityConfig(), HighThroughputConfig(). See docs/config.md.

Documentation

Document	Description
docs/index.md	Documentation hub
docs/flows.md	All auth flows with step lists
docs/api-reference.md	Full API reference
docs/architecture.md	System design
docs/security.md	Threat model and mitigations
docs/performance.md	Benchmarks and budgets
docs/ops.md	Deployment and monitoring
docs/config.md	Configuration reference
docs/roadmap.md	Future plans
CHANGELOG.md	Release history

Root-Level Documents

File	Purpose
CHANGELOG.md	Release history — follows Keep a Changelog format with Semantic Versioning
CONTRIBUTING.md	Contribution guidelines — conventions for docs, code, testing, and changelog entries
docsAuditReport.md	Documentation hardening audit — tracks doc coverage, accuracy, and consistency across all features
featureReport.md	Full feature verification report — all 21 features + 4 NFRs with test evidence and benchmarks

Testing

# All tests
go test ./...

# With race detector
go test -race ./...

# Integration tests (requires Redis)
docker compose -f docker-compose.test.yml up -d
go test -tags=integration ./test/...

# Benchmarks
go test -run '^$' -bench . -benchmem ./...

266 tests, 4 fuzz targets, 13 benchmarks. Race-detector clean.

License

Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.

---

Note: AI agents were used for documentation and report generation in this project. Content has been verified against actual test outputs and code, but please exercise caution — review carefully and report any issues in the Issues tab.