egauth

README

egauth

A complete, composable, non-opinionated authentication toolkit for Go.

About this project — please read. egauth was built mostly through "vibe coding" (AI-assisted development). egauth's security review to date is an AI-driven audit only; it has not had an independent third-party human security audit, and that risk is accepted for v1.0 — pin a reviewed commit, commission your own audit, or wait if that trade-off is unacceptable. I wrote it because I wanted a library like this for my own projects. The code is engineered carefully and secure-by-default — an adversarial pass found no high/critical issue — but "AI-audited" is not a synonym for "audited", so weigh the status accordingly before using it for anything sensitive. The full audit status, scope, and escape hatch live in AUDIT.md.

Comments, reviews, issues, and security audits are genuinely welcome. If you spot something — a bug, a design smell, a crypto/protocol concern — please open an issue or PR; for anything security-sensitive see SECURITY.md. Independent scrutiny is exactly what this project wants.

egauth is a set of independent modules in the style of the standard library's database/sql: you import the ones you need and wire them together with dependency injection. There is no framework to adopt — egauth never owns your HTTP router, your database access, or your conventions. Every module exposes a Service interface plus a Store contract, with in-memory and PostgreSQL (pgx) backends behind a shared cross-backend conformance suite.

Status: The API is still settling; see Stability.

Modules

Module	What it does
identity	Accounts & credentials: register, login, password reset, email verification, magic link, change-password/email, account deletion, OAuth identity linking; forced-password-change for temporary credentials (AdminCreateUser, SetTemporaryPassword)
tokens	Stateless JWT access tokens (pluggable symmetric HS256 or asymmetric RS256/ES256/EdDSA signing, publishable JWKS) + single-use refresh tokens with rotation & theft detection; API keys. Reference impl in tokens/jwt
sessions	Server-side, revocable sessions with idle-timeout (Touch) and fixation defense (Rotate)
passwords	Hashing/policy/breach seams + references: argon2, policy, breach/hibp, breach/offline
mfa	TOTP (RFC 6238) with recovery codes
otp	One-time codes (email/SMS), enumeration-safe HTTP handlers
passkey	WebAuthn / passkeys, including discoverable (usernameless) login
oauth	OAuth2 / OIDC, PKCE-S256, id_token/nonce/JWKS; 12 built-in providers (Apple, Auth0, Cognito, Discord, Facebook, GitHub, GitLab, Google, Keycloak, LinkedIn, Microsoft, Okta) in oauth/providers
identity.Mailer / identity.SMSSender	Bring-your-own-delivery seams: wire your own SMTP, SendGrid, Twilio, etc. — egauth never sends mail or SMS itself
ratelimit, event, health	Pluggable rate-limiting, audit-event, and readiness seams

Install

go get github.com/JLugagne/egauth

The PostgreSQL storage backend lives in a separate module (adapters/pgx) so core consumers never pull the pgx driver or the testcontainers/Docker chain into their dependency graph. Install it only if you use the Postgres stores:

go get github.com/JLugagne/egauth/adapters/pgx

Requires Go 1.26+.

Quickstart: login + refresh

The recommended stateless stack is identity (verify credentials) + tokens/jwt (issue and rotate tokens). This wires it with the in-memory backends; swap in the pgx stores for production.

Most applications carry no custom data in their tokens. For that common case use the tokens/basic convenience layer, which specializes the token API to "no custom claims" so you never spell the [struct{}] type argument. (Need custom claims? Use the generic API directly with your own type — see below.) This is the runnable package example (go test ./tokens/basic -run Example).

ctx := context.Background()
const tenant = "" // empty string is the single-tenant default partition

// identity: credential verification + account lifecycle
idStore := identitymem.NewStore() // identity/memory; or adapters/pgx/identity.NewStore(pool)
svc := identity.NewService(idStore, argon2.NewHasher(), policy.NewDefaultPolicy())

// tokens: stateless access tokens + refresh rotation (no custom claims).
// claimsProvider re-derives a user's claims on every refresh, so a disabled or
// role-changed user is re-evaluated rather than frozen at login.
claimsProvider := basic.ClaimsProviderFunc(
    func(_ context.Context, userID uuid.UUID, tenantID string) (basic.Claims, error) {
        return basic.Claims{Subject: userID, TenantID: tenantID}, nil
    },
)
tokenStore := basic.NewMemoryStore() // tokens/memory; or adapters/pgx/tokens.NewStore(pool)
issuer := basic.NewIssuer(basic.Config{
    Store:          tokenStore,
    Issuer:         "example-app",
    SecretKey:      hs256SecretFromYourSecretStore, // >= 32 bytes
    AccessTTL:      15 * time.Minute,
    RefreshTTL:     720 * time.Hour,
    ClaimsProvider: claimsProvider, // required for Rotate (refresh)
})

// register, authenticate, issue a token pair
user, err := svc.Register(ctx, tenant, "alice@example.com", password)
// ... handle err
pair, err := issuer.IssueTokenPair(ctx, basic.Claims{Subject: user.ID, TenantID: tenant})

// later: refresh — rotation single-use-consumes the old refresh token
// (replaying it trips theft detection and revokes the family)
next, err := issuer.Rotate(ctx, tenant, pair.RefreshToken)

Over HTTP

The handlers are à-la-carte http.HandlerFunc factories you mount on your own mux — egauth imposes no router:

claimsOf := func(u *identity.User) basic.Claims {
    return basic.Claims{Subject: u.ID, TenantID: u.TenantID}
}
mux := http.NewServeMux()
mux.Handle("POST /login",   identity.LoginHandler(svc, issuer, claimsOf))
mux.Handle("POST /refresh", basic.RefreshHandler(issuer))    // issuer is the Rotator
mux.Handle("POST /logout",  basic.LogoutHandler(tokenStore)) // revokes the refresh family

// protect a route with the access-token middleware:
mux.Handle("GET /me", basic.RequireAuth(issuer,
    func(w http.ResponseWriter, r *http.Request, actor egauth.Actor, _ struct{}) {
        // actor.UserID / actor.TenantID are authenticated
    }))

With custom claims

To carry application data in your tokens, use the generic tokens / tokens/jwt API directly with your own claims type C. The shape is identical — basic is only a thin facade over it — but every token type takes the type argument: tokens.Claims[C], jwt.New[C], tokens.RequireAuth[C], and so on. Use tokens.Claims[struct{}] if you ever need the generic form with no custom claims. See go doc github.com/JLugagne/egauth/tokens.

For asymmetric signing (so verifiers hold only a public key), set jwt.Config.Signers with jwt.NewRSASigner / jwt.NewECDSASigner / jwt.NewEdDSASigner instead of SecretKey, and serve the public keys from Service.PublicJWKS(). The default tokens/basic facade stays HS256-only; asymmetric signing uses the generic tokens/jwt API.

Multi-tenancy

Every tenant-scoped operation takes an explicit tenantID string argument. An empty string ("") is the valid single-tenant default partition — passing it explicitly keeps the tenant boundary visible at every call site (the defense against cross-tenant access / IDOR).

For a genuinely single-tenant application, wrap a Service once and drop the argument:

app := identity.NewSingleTenant(svc) // every call uses the empty tenant ("")
user, err := app.Register(ctx, "bob@example.com", password)

SingleTenant facades exist on identity, sessions, mfa, otp, passkey, and tokens/jwt.

Storage backends

Each module ships two interchangeable Store implementations behind one contract:

• <module>/memory — zero-dependency, for tests and single-process apps; lives in the core module.
• adapters/pgx/<module> — PostgreSQL via jackc/pgx, in the separate adapters/pgx module (go get github.com/JLugagne/egauth/adapters/pgx). Call Migrate(ctx, pool) once at startup (forward-only, versioned via a schema_migrations table; re-running is a no-op).

import identitypgx "github.com/JLugagne/egauth/adapters/pgx/identity"

pool, _ := pgxpool.New(ctx, dsn)
_ = identitypgx.Migrate(ctx, pool)
store := identitypgx.NewStore(pool)

Security

egauth is enumeration-safe by default (uniform responses + decoy hashing), enforces brute-force lockout, pins each JWT to its key's algorithm (rejecting none/alg-confusion) for symmetric (HS256) or asymmetric (RS256/ES256/EdDSA) signing, rotates refresh tokens with family-based theft detection, stores only SHA-256 hashes of refresh/API/session/OTP secrets, and caps pre-auth body size against hashing-DoS. Credential-bearing types redact their secrets on fmt/slog. Read SECURITY.md for the full model — including the explicit trade-offs (e.g. TOTP secrets stored recoverably, accepted account-existence disclosures) and the boundaries egauth leaves to the application (CSRF tokens, rate-limit policy, mail/SMS transport, observability, idempotency).

Forced-password-change for temporary credentials. Provision a one-time credential via identity.AdminCreateUser (admin-created account) or identity.SetTemporaryPassword (admin-issued temporary password); both flag the credential so the user must choose a new password at next login. A flagged login issues a full, renewable pair carrying tokens.Claims.MustChangePassword=true; the flag is recorded on the refresh-token family and carried onto every silent refresh, so mounting tokens.WithPasswordChangeGate on your protected routes keeps soft-redirecting to the reset page until the password is changed — a user cannot escape by waiting for the access token to expire. The credential stays valid throughout — never a lockout. egauth does NOT do periodic, age-based rotation (NIST SP 800-63B discourages fixed-interval expiry). See SECURITY.md for the full semantics.

Observability — wire your metrics/audit pipeline to event.Sink. Use event.NewSlogSink for the common structured-logging case, or github.com/JLugagne/egauth/adapters/otel for OpenTelemetry spans (NewSpanSink creates one child span per security event with egauth.* attributes). Combine them with event.MultiSink. Request-level idempotency is the application layer's responsibility. See SECURITY.md § Observability and idempotency.

Reference application

examples/fullstack is a self-contained runnable application that wires the full egauth stack — identity + tokens with custom claims + MFA (TOTP) + passkey + admin operations + audit events — over HTTP using only in-memory backends and the standard library mux. It builds from the module proxy with no local go.work workspace:

go run github.com/JLugagne/egauth/examples/fullstack@latest

A smoke test (go test ./examples/fullstack) exercises all six concerns end-to-end.

Documentation

Full API reference: pkg.go.dev/github.com/JLugagne/egauth

Each module has a package overview (go doc github.com/JLugagne/egauth/identity) and the login-critical packages carry runnable examples.

Production: evict in-memory stores

The sessions/memory, otp/memory, and ratelimit.TokenBucket backends grow without bound unless their eviction methods (DeleteExpired / Cleanup) are called periodically. In any non-trivial production deployment you must schedule this — a flood of unique keys, sessions, or OTP codes otherwise exhausts available memory. Use the optional janitor helper:

import "github.com/JLugagne/egauth/janitor"

j := janitor.Start(ctx, 5*time.Minute, func() {
    sessStore.DeleteExpired(context.Background(), tenantID)
})
defer j.Stop()

janitor.Start accepts any func(), so the same pattern covers otpStore.DeleteExpired and tokenBucket.Cleanup. For production deployments beyond a single binary, swap the in-memory stores for their pgx counterparts (which rely on the database for eviction instead).

Stability

Pre-1.0: the API may change between minor versions until it settles, at which point releases will follow SemVer with a CHANGELOG. Pin a commit or tag in go.mod for reproducible builds.

Go version support policy.

• For v1.x and later: The go.mod go directive is pinned for the life of the major version. v1.0 through v1.x will all require go 1.26 (the minimum toolchain at v1.0 release). Bumping to a newer major Go release is deferred to v2. This provides maximum build stability within a major version.

• Pre-v1 releases: egauth targets the newest major Go release as its minimum toolchain. The go.mod directive is bumped deliberately — each time a new major Go version ships, the floor moves up to it. This is an intentional choice (not an accident): the library is expected to be adopted in greenfield projects that run the current toolchain. If you need support for an older Go version, pin an earlier egauth release.

Documentation

Overview

Package egauth is a composable authentication toolkit for Go: a set of independent modules you import à la carte and wire together yourself, in the style of the standard library's database/sql — rather than a framework that owns your HTTP router, your database access, or your conventions. The root package itself is deliberately tiny: it exports only Actor, the explicit authenticated-principal value passed to handlers (never smuggled through context.Context). All behavior lives in the sub-packages below.

Modules

identity   Accounts & credentials: register, login (Authenticate), password reset, email
           verification, magic-link login, change-password / change-email, phone verification,
           an independent recovery channel, account deletion, and OAuth identity linking.
tokens     Stateless JWT access tokens + single-use refresh tokens with rotation and theft
           detection, plus API keys. Reference implementation in tokens/jwt.
sessions   Server-side, revocable sessions with idle-timeout (Touch) and fixation defense
           (Rotate).
passwords  Hashing / policy / breach-check seams plus references: passwords/argon2,
           passwords/policy, passwords/breach/hibp, passwords/breach/offline.
mfa        TOTP (RFC 6238) with recovery codes. (SMS is intentionally excluded as a factor.)
otp        One-time codes (email/SMS), with enumeration-safe HTTP handlers.
passkey    WebAuthn / passkeys, including discoverable (usernameless) login.
oauth      OAuth2 / OIDC with PKCE-S256 and id_token/nonce/JWKS; ready-made providers
           (Google, GitHub, Microsoft, Apple, Okta, Auth0, ...) live in oauth/providers.
ratelimit  Pluggable rate-limiting Limiter + token-bucket reference + middleware.
event      Dependency-free security-event Sink seam (audit logging, slog adapter).
health     Optional Store Ping/readiness seam.

Composable by design

There is no top-level constructor that bundles everything, and that is intentional: each module has its own Service interface, its own Store contract (with in-memory and pgx backends behind a shared cross-backend conformance suite), and functional-option dependency injection. You compose exactly the stack you need. A typical password-login deployment wires identity (verifies credentials and manages the account lifecycle) with tokens (issues the access/refresh pair) — identity never issues tokens or sessions itself, so you pick the token backend that fits.

idStore := identitymem.NewStore()                          // or adapters/pgx/identity.NewStore(pool)
idSvc := identity.NewService(idStore, argon2.NewHasher(), policy.NewDefaultPolicy())

tkStore := basic.NewMemoryStore()                          // tokens/basic: the no-custom-claims path
issuer := basic.NewIssuer(basic.Config{                    // thin tokens/jwt facade, zero [struct{}]
	Store: tkStore, Issuer: "example-app", SecretKey: secret,
	AccessTTL: 15 * time.Minute, RefreshTTL: 720 * time.Hour,
})

user, _ := idSvc.Register(ctx, tenantID, email, password)
pair, _ := issuer.IssueTokenPair(ctx, basic.Claims{Subject: user.ID, TenantID: tenantID})

The complete, runnable login + refresh wiring (including the HTTP handlers) lives in the identity package's example tests — see Example, ExampleNewSingleTenant and ExampleLoginHandler.

Multi-tenancy

Multi-tenancy is explicit and pervasive: every Store and Service operation takes a tenantID string. The empty string is the valid single-tenant default partition, so a single-tenant application simply passes "" — or wraps a Service in that module's SingleTenant facade (e.g. identity.NewSingleTenant) to drop the argument from every call.

Security and stability

egauth is security-literate by default (Argon2id, enumeration-resistant auth paths, refresh rotation with theft detection, alg-pinned JWTs, secure-by-default cookies, pre-auth body caps). The full threat model is in SECURITY.md; the module overview and a copy-pasteable quickstart are in README.md. The API is pre-1.0 and still settling; pin a commit or tag in go.mod for reproducible builds (see the Stability section of README.md).

Audit status: egauth's security review to date is an AI-driven audit only; it has not had an independent third-party human security audit, and that risk is accepted for v1.0 — pin a reviewed commit, commission your own audit, or wait if that trade-off is unacceptable. "AI-audited" is not a synonym for "audited". See AUDIT.md for the full review scope and the cautious-user escape hatch.

Index

• type Actor

Types

type Actor

type Actor struct {
	UserID   uuid.UUID
	TenantID string
}

Actor represents the authenticated entity making a request. It is explicitly passed as an argument to handlers, never transported via context.Context.