Configuration

All configuration options for the Authsome engine, sessions, passwords, rate limiting, and lockout.

The root authsome package defines the Config struct, DefaultConfig() defaults, and the Option functions for constructing an engine. All configuration is passed at construction time via authsome.New(opts...).

authsome.Config

Config is the top-level configuration struct for the Authsome engine.

import "github.com/xraph/authsome"

type Config struct {
    AppID          string          `json:"app_id"`
    BasePath       string          `json:"base_path"`
    Session        SessionConfig   `json:"session"`
    Password       PasswordConfig  `json:"password"`
    RateLimit      RateLimitConfig `json:"rate_limit"`
    Lockout        LockoutConfig   `json:"lockout"`
    DriverName     string          `json:"driver_name"`
    Debug          bool            `json:"debug"`
    DisableRoutes  bool            `json:"disable_routes"`
    DisableMigrate bool            `json:"disable_migrate"`
}

Field	Type	Default	Description
`AppID`	`string`	`""`	Application identifier used for scoping. Required if not set via `WithAppID`.
`BasePath`	`string`	`"/v1/auth"`	URL prefix for all auto-registered auth routes.
`Session`	`SessionConfig`	See below	Session token and refresh token behavior.
`Password`	`PasswordConfig`	See below	Password policy and hashing algorithm.
`RateLimit`	`RateLimitConfig`	See below	Per-endpoint rate limiting.
`Lockout`	`LockoutConfig`	See below	Account lockout after repeated failures.
`DriverName`	`string`	`""`	Grove driver name (`"pg"`, `"sqlite"`, `"mongo"`, `"memory"`). Set automatically by the extension.
`Debug`	`bool`	`false`	Enables verbose logging of all engine operations.
`DisableRoutes`	`bool`	`false`	When `true`, prevents automatic route registration on `Start`.
`DisableMigrate`	`bool`	`false`	When `true`, prevents automatic schema migration on `Start`.

SessionConfig

type SessionConfig struct {
    TokenTTL           time.Duration `json:"token_ttl"`
    RefreshTokenTTL    time.Duration `json:"refresh_token_ttl"`
    MaxActiveSessions  int           `json:"max_active_sessions"`
    RotateRefreshToken *bool         `json:"rotate_refresh_token"`
    BindToIP           bool          `json:"bind_to_ip"`
    BindToDevice       bool          `json:"bind_to_device"`
}

Field	Type	Default	Description
`TokenTTL`	`time.Duration`	`1h`	Lifetime of access tokens. After expiry, the client must use the refresh token.
`RefreshTokenTTL`	`time.Duration`	`720h` (30 days)	Lifetime of refresh tokens. After expiry, the user must sign in again.
`MaxActiveSessions`	`int`	`0` (unlimited)	Maximum concurrent sessions per user. When exceeded, the oldest session is revoked.
`RotateRefreshToken`	`*bool`	`true`	When `true`, every `Refresh` call issues a new refresh token and invalidates the old one. Set to `false` to reuse the same refresh token.
`BindToIP`	`bool`	`false`	When `true`, sessions are rejected if the client IP differs from the IP recorded at creation. Useful for high-security environments but breaks users on mobile networks.
`BindToDevice`	`bool`	`false`	When `true`, sessions are rejected if the User-Agent differs from the one recorded at creation.

ShouldRotateRefreshToken

The SessionConfig helper method ShouldRotateRefreshToken() returns true when RotateRefreshToken is nil (unset) or explicitly true:

cfg := authsome.SessionConfig{}
cfg.ShouldRotateRefreshToken() // returns true (default)

t := true
cfg.RotateRefreshToken = &t
cfg.ShouldRotateRefreshToken() // returns true

f := false
cfg.RotateRefreshToken = &f
cfg.ShouldRotateRefreshToken() // returns false

PasswordConfig

type PasswordConfig struct {
    MinLength        int          `json:"min_length"`
    RequireUppercase bool         `json:"require_uppercase"`
    RequireLowercase bool         `json:"require_lowercase"`
    RequireDigit     bool         `json:"require_digit"`
    RequireSpecial   bool         `json:"require_special"`
    BcryptCost       int          `json:"bcrypt_cost"`
    Algorithm        string       `json:"algorithm"`
    Argon2           Argon2Config `json:"argon2"`
    CheckBreached    bool         `json:"check_breached"`
    HistoryCount     int          `json:"history_count"`
    MaxAgeDays       int          `json:"max_age_days"`
}

Field	Type	Default	Description
`MinLength`	`int`	`8`	Minimum password length in characters.
`RequireUppercase`	`bool`	`true`	Requires at least one uppercase letter (`A-Z`).
`RequireLowercase`	`bool`	`true`	Requires at least one lowercase letter (`a-z`).
`RequireDigit`	`bool`	`true`	Requires at least one digit (`0-9`).
`RequireSpecial`	`bool`	`false`	Requires at least one special character (`!@#$%^&*`).
`BcryptCost`	`int`	`12`	bcrypt work factor. Higher values are slower but more secure. Production minimum: 12.
`Algorithm`	`string`	`"bcrypt"`	Hashing algorithm: `"bcrypt"` or `"argon2id"`. Existing hashes are transparently re-hashed on next login when the algorithm changes.
`Argon2`	`Argon2Config`	See below	Argon2id parameters (used when `Algorithm = "argon2id"`).
`CheckBreached`	`bool`	`false`	When `true`, checks passwords against the HaveIBeenPwned k-anonymity API on signup and password change. Fail-open on network errors.
`HistoryCount`	`int`	`0` (disabled)	Number of previous password hashes to retain. Users cannot reuse any of their last N passwords.
`MaxAgeDays`	`int`	`0` (disabled)	Forces password rotation after this many days. Returns `ErrPasswordExpired` on sign-in with an expired password.

Argon2Config

type Argon2Config struct {
    Memory      uint32 `json:"memory"`      // KiB (default: 65536 = 64 MiB)
    Iterations  uint32 `json:"iterations"`  // time cost (default: 3)
    Parallelism uint8  `json:"parallelism"` // threads (default: 2)
    SaltLength  uint32 `json:"salt_length"` // bytes (default: 16)
    KeyLength   uint32 `json:"key_length"`  // bytes (default: 32)
}

The Argon2 defaults (64 MiB, 3 iterations, 2 threads) meet the OWASP recommendation for server-side password hashing.

RateLimitConfig

type RateLimitConfig struct {
    SignInLimit          int  `json:"signin_limit"`
    SignUpLimit          int  `json:"signup_limit"`
    ForgotPasswordLimit  int  `json:"forgot_password_limit"`
    MFAChallengeLimit    int  `json:"mfa_challenge_limit"`
    WindowSeconds        int  `json:"window_seconds"`
    Enabled              bool `json:"enabled"`
}

Field	Type	Default	Description
`Enabled`	`bool`	`false`	Rate limiting is disabled by default. Set to `true` to enable.
`SignInLimit`	`int`	`5`	Max sign-in attempts per IP per window.
`SignUpLimit`	`int`	`3`	Max sign-up attempts per IP per window.
`ForgotPasswordLimit`	`int`	`3`	Max forgot-password requests per IP per window.
`MFAChallengeLimit`	`int`	`5`	Max MFA challenge attempts per session per window.
`WindowSeconds`	`int`	`60`	Sliding window duration in seconds.

Rate limiting requires a ratelimit.Limiter backend to be configured with WithRateLimiter. Without a limiter, rate limit config is ignored.

LockoutConfig

type LockoutConfig struct {
    MaxAttempts            int  `json:"max_attempts"`
    LockoutDurationSeconds int  `json:"lockout_duration_seconds"`
    ResetAfterSeconds      int  `json:"reset_after_seconds"`
    Enabled                bool `json:"enabled"`
}

Field	Type	Default	Description
`Enabled`	`bool`	`false`	Account lockout is disabled by default. Set to `true` to enable.
`MaxAttempts`	`int`	`5`	Number of consecutive failed sign-in attempts before the account is locked.
`LockoutDurationSeconds`	`int`	`900` (15 min)	Duration of the lockout in seconds.
`ResetAfterSeconds`	`int`	`3600` (1 hour)	Resets the failure counter after this many seconds of no failures.

Account lockout requires a lockout.Tracker backend configured with WithLockoutTracker.

DefaultConfig

DefaultConfig() returns sensible defaults for all fields:

cfg := authsome.DefaultConfig()
// cfg.BasePath              = "/v1/auth"
// cfg.Session.TokenTTL      = 1 * time.Hour
// cfg.Session.RefreshTokenTTL = 30 * 24 * time.Hour
// cfg.Password.MinLength    = 8
// cfg.Password.RequireUppercase = true
// cfg.Password.RequireLowercase = true
// cfg.Password.RequireDigit = true
// cfg.Password.BcryptCost   = 12
// cfg.RateLimit.SignInLimit  = 5
// cfg.RateLimit.SignUpLimit  = 3
// cfg.RateLimit.WindowSeconds = 60
// cfg.Lockout.MaxAttempts   = 5
// cfg.Lockout.LockoutDurationSeconds = 900
// cfg.Lockout.ResetAfterSeconds = 3600

Option functions

All engine options are func(*Engine) type values passed to authsome.New.

Option	Description
`WithConfig(cfg Config)`	Set the full config, overriding defaults.
`WithStore(s store.Store)`	Set the persistence backend. Required.
`WithLogger(l *slog.Logger)`	Set the structured logger.
`WithDebug(bool)`	Enable verbose debug logging.
`WithAppID(string)`	Set the default application ID.
`WithPlugin(p plugin.Plugin)`	Register a plugin. Call multiple times for multiple plugins.
`WithStrategy(s, priority int)`	Register a custom auth strategy.
`WithChronicle(bridge.Chronicle)`	Set the audit trail bridge.
`WithMailer(bridge.Mailer)`	Set the transactional email bridge.
`WithSMSSender(bridge.SMSSender)`	Set the SMS sending bridge.
`WithHerald(bridge.Herald)`	Set the unified notification bridge.
`WithWarden(*warden.Engine)`	Set the Warden authorization engine.
`WithKeysmith(*keysmith.Engine)`	Set the Keysmith API key engine.
`WithEventRelay(bridge.EventRelay)`	Set the webhook event relay.
`WithVault(bridge.Vault)`	Set the secrets/config bridge.
`WithDispatcher(bridge.Dispatcher)`	Set the background job bridge.
`WithLedger(bridge.Ledger)`	Set the billing bridge.
`WithMetrics(bridge.MetricsCollector)`	Set the metrics bridge.
`WithBasePath(string)`	Override the URL prefix.
`WithDisableRoutes()`	Prevent automatic route registration.
`WithDisableMigrate()`	Prevent automatic migration on Start.
`WithRateLimiter(ratelimit.Limiter)`	Set the rate limiter backend.
`WithLockoutTracker(lockout.Tracker)`	Set the account lockout tracker.
`WithCeremonyStore(ceremony.Store)`	Set the ceremony state store.
`WithPasswordHistory(account.PasswordHistoryStore)`	Set the password history store.
`WithDefaultTokenFormat(tokenformat.Format)`	Set the default access token format.
`WithJWTFormat(appID string, jwt *tokenformat.JWT)`	Set JWT token format for a specific app.
`WithAppSessionConfig(*appsessionconfig.Config)`	Seed a per-app session config override.

Per-app session config overrides

You can override session configuration for a specific app using appsessionconfig.Config. This is useful when different apps within the same engine instance need different token TTLs.

import "github.com/xraph/authsome/appsessionconfig"

eng, err := authsome.New(
    authsome.WithStore(store),
    authsome.WithPlugin(password.New()),
    authsome.WithAppSessionConfig(&appsessionconfig.Config{
        AppID:           "premium-app",
        TokenTTL:        ptr(8 * time.Hour),    // longer TTL for premium app
        RefreshTokenTTL: ptr(90 * 24 * time.Hour), // 90 days
        MaxActiveSessions: ptr(20),
    }),
)

Per-app session config is seeded into the store during Start and takes precedence over the global SessionConfig. Per-environment settings take precedence over both.

Resolution order (highest priority wins):

Per-environment settings (EnvironmentSettings.SessionOverrides)
Per-app session config (appsessionconfig.Config)
Global engine SessionConfig

Configuration

On this page