Setup

cfg := jwt.DefaultConfig()
cfg.Issuer   = "https://auth.example.com"
cfg.Audience = []string{"https://api.example.com"}

// Optional: tolerate up to 30 s of clock drift between servers.
cfg.ClockSkewLeeway = 30 * time.Second

jwtMod, err := jwt.New[UserClaims](auth, cfg)

jwt.DefaultConfig() values:

[!NOTE] validateConfig rejects TTLs above the ceilings listed above. This prevents issuing effectively permanent bearer tokens by accident (e.g. typing 10 * time.Hour where 10 * time.Minute was intended).

Login — creating a token pair

// subject must be a UUID v7 (RFC 9562 §5.7).
pair, err := jwtMod.CreateTokens(userID, UserClaims{Name: "Ana", Role: "admin"})
if err != nil {
    // jwt.ErrInvalidSubject — subject is not a valid UUID v7
}

pair.AccessToken            // short-lived JWT for API requests
pair.AccessTokenExpiresAt   // time.Time — tell the client when to refresh
pair.RefreshToken           // long-lived JWT for token rotation
pair.RefreshTokenExpiresAt  // time.Time — when the user must log in again
pair.RefreshTokenHash       // HMAC-SHA256 hex digest — store this in your DB
pair.SessionID              // UUID v7 jti shared by both tokens — use as session PK

Never store the raw refresh token. Store only RefreshTokenHash.

Authenticating requests

claims, err := jwtMod.VerifyAccessToken(tokenFromHeader)
switch {
case errors.Is(err, jwt.ErrTokenExpired):
    // 401 — client should refresh
case errors.Is(err, jwt.ErrTokenInvalid):
    // 401 — tampered, wrong key, or issuer/audience mismatch
case errors.Is(err, jwt.ErrTokenMalformed):
    // 400 — not a JWT at all
case err != nil:
    // 401 — catch-all
}

fmt.Println(claims.Subject)    // UUID v7 user ID
fmt.Println(claims.Extra.Role) // "admin" — your custom claims
fmt.Println(claims.ExpiresAt)  // time.Time

[!NOTE] Verification enforces both iss (issuer) and aud (audience) match the values in jwt.Config. A token signed by a trusted key but minted for a different service is rejected with ErrTokenInvalid — this is the defense against accidental key reuse across services.

Rotating tokens

The recommended pattern — verify the hash before calling RotateTokens to prevent token-reuse attacks even if your database is compromised:

// 1. Compute the hash of the token the client presented.
incoming := jwtMod.HashRefreshToken(clientToken)

// 2. Look it up in your database.
session, err := db.FindSessionByHash(incoming)
if err != nil {
    return http.StatusUnauthorized
}

// 3. Use timing-safe comparison to verify the hash matches.
//    This prevents timing attacks on the lookup result.
if !jwtMod.VerifyRefreshTokenHash(clientToken, session.RefreshTokenHash) {
    return http.StatusUnauthorized
}

// 4. Rotate — authcore verifies the token's signature and expiry.
freshClaims := UserClaims{Name: session.UserName, Role: session.UserRole}
newPair, err := jwtMod.RotateTokens(clientToken, freshClaims)
if err != nil {
    return http.StatusUnauthorized
}

// 5. Atomically replace the old hash in your database.
db.ReplaceRefreshHash(session.ID, newPair.RefreshTokenHash)

// 6. Send the new tokens to the client.

Clock skew tolerance

In distributed systems, server clocks may drift by a few seconds. Set ClockSkewLeeway to accept tokens that expired within that window:

cfg.ClockSkewLeeway = 30 * time.Second

The leeway applies to both access and refresh token verification. Keep it small — large values reduce the security margin of short-lived tokens.

No boilerplate. No algorithm choices. Just secure password hashing that works.

Setup

auth, err := authcore.New(authcore.DefaultConfig())

// Zero-config — OWASP-recommended Argon2id defaults applied automatically.
pwdMod, err := password.New(auth)

That's it. No config required.

Why Argon2id? It's memory-hard: an attacker must allocate ~64 MiB of RAM per attempt, making GPU and ASIC brute-force attacks prohibitively expensive. bcrypt does not have this property.

Hashing a password

hash, err := pwdMod.Hash(userPassword)
switch {
case errors.Is(err, password.ErrWeakPassword):
    // 400 — tell the user exactly what's missing (message is descriptive)
case err != nil:
    // 500 — unexpected error
}
// Store hash in your database. Never store the plaintext.
db.StorePasswordHash(userID, hash)

Hash validates the password before spending CPU on hashing:

Each call also generates a fresh random salt, so two hashes of the same password are always different strings — but both verify correctly.

The stored string is fully self-describing (PHC format):

$argon2id$v=19$m=65536,t=3,p=2$<base64-salt>$<base64-hash>

Verifying a password

ok, err := pwdMod.Verify(submittedPassword, storedHash)
switch {
case errors.Is(err, password.ErrInvalidHash):
    // 500 — hash in the database is malformed
case !ok:
    // 401 — wrong password
}

Comparison is constant-time (crypto/subtle) — timing attacks are not possible. Parameters are always read from the stored hash, never from the current module config, and bounded to the same safe range (Memory 8 MiB – 4 GiB, Iterations ≤ 20, Parallelism ≥ 1) so a corrupted or malicious stored hash cannot force argon2.IDKey into an unbounded memory allocation.

[!NOTE] Both Hash and Verify normalise plaintext to Unicode NFC before processing. A password like café hashes the same whether the user typed it on macOS (precomposed é) or Linux (decomposed e + combining acute), so cross-platform account access works out of the box.

Tuning work parameters (optional)

The defaults are sized for 2 vCPUs / 4 GiB RAM. On more powerful hardware, crank them up — a hash should take roughly 200–500 ms:

pwdMod, err := password.New(auth, password.Config{
    Memory:      128 * 1024, // 128 MiB
    Iterations:  4,
    Parallelism: 4,          // match your guaranteed CPU core count
})

Old hashes stay valid. All parameters live inside the hash string itself. Changing the config only affects new hashes — existing users keep working.

Setup

emailMod, err := email.New(auth)
if err != nil {
    log.Fatal(err)
}
defer emailMod.Close() // stops the background cache eviction goroutine

Validating and normalizing

Always call ValidateAndNormalize instead of validating and normalizing separately. It lowercases, trims whitespace, and validates in a single call — ensuring the value you store is always in canonical form:

normalized, err := emailMod.ValidateAndNormalize(req.Email)
switch {
case errors.Is(err, email.ErrInvalidEmail):
    // 400 — tell the user exactly what failed (message is descriptive)
    c.JSON(400, map[string]string{"error": errors.Unwrap(err).Error()})
    return
case err != nil:
    // 500 — unexpected error
}
// Store normalized — always lowercase, trimmed.
db.StoreUser(normalized, ...)

Validation rules (RFC 5321 / RFC 5322):

Always normalize before storing and before querying. This ensures consistent lookup — User@EXAMPLE.COM and user@example.com are the same address.

[!NOTE] Internationalised domains (IDN) are supported. Unicode domains are converted to ASCII punycode during normalisation:

user@münchen.de  →  user@xn--mnchen-3ya.de
user@例え.jp     →  user@xn--r8jz45g.jp

Store the ASCII form so DNS lookups and database comparisons are deterministic.

Verifying a domain can receive email

VerifyDomain performs an optional DNS MX lookup to confirm the domain is configured to receive email. Call it after ValidateAndNormalize when you want to reject obviously fake domains before sending a verification email.

Results are cached per domain (default 5 minutes) and DNS lookups for the same domain are deduplicated via singleflight — safe for high-concurrency workloads.

ctx, cancel := context.WithTimeout(r.Context(), 3*time.Second)
defer cancel()

err = emailMod.VerifyDomain(ctx, normalized)
switch {
case errors.Is(err, email.ErrDomainNoMX):
    // 400 — domain exists but cannot receive email
    c.JSON(400, map[string]string{"error": "email domain cannot receive messages"})
    return
case errors.Is(err, email.ErrDomainUnresolvable):
    // DNS lookup failed — do NOT block the user; log and continue
    log.Warn("DNS check unavailable: %v", err)
}

ErrDomainUnresolvable is a soft failure. DNS can be temporarily unavailable due to network issues unrelated to the user's input. Never block a registration on this error — log it and proceed.

Setup

userMod, err := username.New(auth)
if err != nil {
    log.Fatal(err)
}

Validating and normalizing

Always call ValidateAndNormalize — it lowercases, trims whitespace, and validates in a single call, ensuring the value you store is always in canonical form:

normalized, err := userMod.ValidateAndNormalize(req.Username)
if err != nil {
    // errors.Unwrap(err).Error() contains the specific rule that failed.
    c.JSON(400, map[string]string{"error": errors.Unwrap(err).Error()})
    return
}
db.StoreUser(normalized, ...) // always lowercase, trimmed, validated

Validation rules:

Always normalize before storing and before querying. Alice123 and alice123 are the same username — store only the canonical (normalized) form.

On first run authcore creates KeysDir (default .authcore) and generates:

On subsequent starts the files are loaded and the key pair is validated for consistency. If only one PEM file is present, New() returns ErrKeyManager — delete both to regenerate.

In containers or CI, point KeysDir at a mounted secrets volume:

cfg := authcore.DefaultConfig()
cfg.KeysDir = os.Getenv("AUTHCORE_KEYS_DIR") // e.g. /run/secrets/authcore
auth, err := authcore.New(cfg)

The KeyID() accessor returns a 16-character hex digest derived from the public key. It is embedded in every token's kid JOSE header, enabling zero-downtime key rotation. Verification rejects tokens whose kid does not match the module's current key id, so a future multi-key deployment only ever accepts tokens minted under an authorised key.

[!NOTE] Key-file loaders enforce a 4 KiB size cap. A healthy Ed25519 PEM is ~200 bytes; anything larger is refused before it reaches pem.Decode, protecting startup from a corrupted or attacker-replaced key file that would otherwise be loaded whole into memory.

type Config struct {
    EnableLogs bool             // emit log output; default true via DefaultConfig()
    Timezone   *time.Location   // time zone for all operations; default time.UTC
    Logger     authcore.Logger  // custom logger (slog, zap, zerolog, …); overrides EnableLogs
    KeysDir    string           // key storage directory; default ".authcore"
}

Always start from DefaultConfig() and override only what you need:

cfg := authcore.DefaultConfig()
cfg.EnableLogs = false                    // silence output in tests
cfg.Logger     = slog.Default()           // use your application logger
cfg.KeysDir    = "/run/secrets/authcore"  // absolute path in containers

Note on EnableLogs: Go cannot distinguish EnableLogs = false from a zero-value Config{}. Start from DefaultConfig() to get EnableLogs = true, then set it to false to explicitly opt out.

Implement the Logger interface to route authcore output through your existing log pipeline:

type Logger interface {
    Debug(msg string, args ...any)
    Info(msg string, args ...any)
    Warn(msg string, args ...any)
    Error(msg string, args ...any)
}

*slog.Logger satisfies this interface directly:

cfg := authcore.DefaultConfig()
cfg.Logger = slog.Default() // or slog.New(yourHandler)

When Config.Logger is non-nil it takes precedence over EnableLogs.

Every AuthCore module accepts a Provider interface — not a concrete *AuthCore — which means you never need to generate real keys or touch the disk in tests. Pass in a stub.

package mypkg_test

import (
    "crypto/ed25519"
    "testing"

    "github.com/Jaro-c/authcore"
    "github.com/Jaro-c/authcore/auth/jwt"
)

// stubProvider implements authcore.Provider with fixed, in-memory dependencies.
type stubProvider struct {
    cfg    authcore.Config
    logger authcore.Logger
    keys   authcore.Keys
}

func (s *stubProvider) Config() authcore.Config { return s.cfg }
func (s *stubProvider) Logger() authcore.Logger { return s.logger }
func (s *stubProvider) Keys() authcore.Keys     { return s.keys }

// stubKeys satisfies authcore.Keys with values you control in the test.
type stubKeys struct {
    priv   ed25519.PrivateKey
    pub    ed25519.PublicKey
    secret []byte
    kid    string
}

func (k *stubKeys) PrivateKey() ed25519.PrivateKey { return k.priv }
func (k *stubKeys) PublicKey() ed25519.PublicKey   { return k.pub }
func (k *stubKeys) RefreshSecret() []byte          { return k.secret }
func (k *stubKeys) KeyID() string                  { return k.kid }

func TestMyHandler(t *testing.T) {
    pub, priv, _ := ed25519.GenerateKey(nil)
    p := &stubProvider{
        cfg:    authcore.DefaultConfig(),
        logger: &noopLogger{},
        keys:   &stubKeys{priv: priv, pub: pub, secret: []byte("test-secret-32-bytes-long-xxxxxx"), kid: "test"},
    }

    jwtMod, err := jwt.New[struct{}](p, jwt.DefaultConfig())
    if err != nil {
        t.Fatal(err)
    }
    // ... exercise your handler against jwtMod, with no file I/O.
}

[!TIP] For deterministic time in tests (e.g. to assert ExpiresAt), override Config.Timezone and use time.Now() equivalents through the same clock your production code reads from.

AuthCore can take over password verification from another library without forcing every user to reset their password. Use the "re-hash on next login" pattern:

func Login(email, submitted string) error {
    user := db.FindUser(email)

    // 1. Try authcore first. New users and already-migrated users land here.
    if ok, _ := pwdMod.Verify(submitted, user.PasswordHash); ok {
        return issueSession(user)
    }

    // 2. Fall back to the legacy hasher (e.g. bcrypt).
    if !legacyBcrypt.Compare(submitted, user.PasswordHash) {
        return ErrWrongPassword
    }

    // 3. Password is correct — upgrade the hash transparently.
    newHash, err := pwdMod.Hash(submitted)
    if err != nil {
        return err
    }
    db.UpdatePasswordHash(user.ID, newHash)
    return issueSession(user)
}

After a few weeks, most active users are migrated and you can delete the legacy path. Dormant accounts can be forced into password reset the next time they log in.

[!NOTE] If your existing hashes are already in PHC Argon2id format ($argon2id$v=19$…), no migration is needed — pwdMod.Verify reads all parameters from the stored hash, regardless of which library produced it.

authcore/
├── authcore.go          # New() · AuthCore struct · compile-time interface assertions
├── config.go            # Config · DefaultConfig()
├── logger.go            # Logger interface · stdlib and noop implementations
├── module.go            # Keys · Provider · Module interfaces
├── errors.go            # Sentinel errors
│
├── internal/
│   ├── clock/           # Timezone-aware Clock — injected for deterministic tests
│   └── keymanager/      # Ed25519 + HMAC key generation, persistence, validation
│
├── auth/
│   ├── jwt/             # JSON Web Token authentication (EdDSA / Ed25519)
│   ├── password/        # Argon2id password hashing
│   ├── email/           # Email validation, normalization, DNS MX verification
│   └── username/        # Username validation, normalization, reserved name blocklist
│
└── examples/
    ├── basic/           # authcore initialisation strategies
    ├── jwt/             # JWT: create, verify, rotate
    ├── password/        # Password: policy, hash, verify
    ├── email/           # Email: validate, normalize, DNS MX verification
    ├── username/        # Username: validate, normalize, reserved names
    ├── fiber/           # Full auth API with Fiber v3 (separate module)
    └── gin/             # Full auth API with Gin (separate module)

Modules depend on authcore.Provider — not the concrete *AuthCore — so they remain independently testable without touching the filesystem or generating real keys.

// Provider is the narrow interface that *AuthCore satisfies.
type Provider interface {
    Config() Config  // shared configuration
    Logger() Logger  // shared logger sink
    Keys()   Keys    // Ed25519 keys + HMAC secret
}

// Module is the marker interface every sub-module must implement.
type Module interface {
    Name() string // stable, lowercase identifier e.g. "jwt"
}

Minimal module skeleton:

package mypkg

import "github.com/Jaro-c/authcore"

type MyModule struct {
    log authcore.Logger
    // ...
}

func New(p authcore.Provider, cfg Config) (*MyModule, error) {
    return &MyModule{log: p.Logger()}, nil
}

func (m *MyModule) Name() string { return "mypkg" }

In tests, inject a stub Provider that returns fixed keys — no disk I/O required.

authcore package

auth/jwt package

auth/password package

auth/email package

auth/username package

Always use errors.Is for error inspection — errors may be wrapped:

claims, err := jwtMod.VerifyAccessToken(token)
if errors.Is(err, jwt.ErrTokenExpired) {
    // prompt the client to refresh
}

No — AuthCore never touches your database. It hashes passwords, signs tokens, and validates input. You store hashes, usernames, and refresh-token hashes wherever your app already keeps data (Postgres, Redis, SQLite, even an in-memory map for a toy project).

UUID v7 is a 128-bit identifier whose first 48 bits are a millisecond Unix timestamp (RFC 9562 §5.7). That means UUID v7 values sort naturally by creation time — ideal as a database primary key and as a stable session identifier. AuthCore requires v7 for the sub claim so your sessions always sort chronologically.

Libraries that generate UUID v7 in Go: github.com/google/uuid (≥ v1.6), github.com/gofrs/uuid.

Short answer: yes, if your refresh token lives longer than a few minutes. Rotation limits the blast radius of a stolen refresh token — once the legitimate client rotates, the stolen copy is rejected. Combined with storing only the hash of refresh tokens on the server, an attacker who dumps your database still cannot forge new sessions.

Yes. Different servers may have clocks that drift a few seconds apart, causing ErrTokenExpired on a brand-new token. Set ClockSkewLeeway in your JWT config:

cfg := jwt.DefaultConfig()
cfg.ClockSkewLeeway = 5 * time.Second

Keep it small (5–30 s). Larger values erode the security margin of short-lived tokens.

AuthCore could not read or create its key files. Check that:

1. KeysDir (default .authcore) is writable by the process.
2. The directory is not a read-only filesystem (common in some container setups).
3. Existing key files are not corrupted — delete .authcore and let AuthCore regenerate them. Warning: regenerating keys invalidates every token currently in circulation.

Yes. AuthCore embeds the kid (key ID) in every token header. When you add a new key pair, keep the old public key in the key store under its original kid. The verifier will select the right key automatically. See the Key Management section for the rotation workflow.

Yes. See Migrating from bcrypt / other libraries for the re-hash-on-next-login pattern. If your hashes are already in PHC Argon2id format ($argon2id$v=19$…), no migration is needed at all — pwdMod.Verify reads parameters from the stored hash.

Yes. Point KeysDir at a mounted secrets volume so keys survive container restarts and are shared across replicas:

cfg := authcore.DefaultConfig()
cfg.KeysDir = os.Getenv("AUTHCORE_KEYS_DIR") // e.g. /run/secrets/authcore

Pre-generate the key files once (a one-shot job that runs AuthCore against the volume), then mount them read-only into your app.

Yes — Argon2id deliberately takes ~100–300 ms and allocates 64 MiB of RAM per call. In tests, use a low-cost config to avoid slow suites:

pwd, _ := password.New(auth, password.Config{
    Memory:      8 * 1024, // minimum allowed (8 MiB)
    Iterations:  1,
    Parallelism: 1,
})

No — AuthCore gives you the primitives (hash, sign, verify, rotate) and stays framework-agnostic. See examples/fiber and examples/gin for wiring into a real HTTP stack, including protected-route middleware.

Each ring is a directory; each slice is a file. Greener wedges are better covered. Click through for the full per-line report on Codecov.

authcore follows Semantic Versioning.

• v1.x (current) — the public API is frozen under semver guarantees. Breaking changes only ship in a new major version (v2.0.0). Minor releases add features; patch releases fix bugs or harden existing code paths without changing public shapes.
• v1.2.0 shipped defence-in-depth hardenings: JWT TTL caps, kid header matching, Unicode NFC password normalisation, IDN email support, and a PEM file size cap. See CHANGELOG.md for the full release history.

Internal packages (internal/…) carry no compatibility guarantees at any version and must not be imported from outside the module.