Sigra.Config (Sigra v1.20.0)

Configuration for Sigra authentication.

Sigra uses NimbleOptions for compile-time validated configuration with auto-generated documentation. Only :repo and :user_schema are required; all other options have secure, OWASP-grade defaults.

Usage

config = Sigra.Config.new!(
  repo: MyApp.Repo,
  user_schema: MyApp.Accounts.User
)

Options

:repo (atom/0) - Required. The Ecto Repo module for database operations.
:user_schema (atom/0) - Required. The Ecto schema module for users.
:otp_app (atom/0) - The OTP application name. Used for config.exs convenience layer.
:secret_key_base - The host app's secret key base. Required for JWT HS256 signing and token operations. The default value is nil.
:mailer (atom/0) - The mailer module implementing Sigra.Mailer behaviour.
:email_module - The generated email template module implementing Sigra.EmailTemplates behaviour. The default value is nil.
:password (keyword/0) - Password hashing and validation options. The default value is [].
- :min_length (pos_integer/0) - Minimum password length. NIST SP 800-63B recommends at least 8. The default value is 8.
- :max_length (pos_integer/0) - Maximum password length. Set to 72 to match bcrypt's limit for migration compatibility. The default value is 72.
- :hasher (atom/0) - Module implementing the Sigra.Hasher behaviour. The default value is Sigra.Hashers.Argon2.
- :notify_on_change (boolean/0) - Send notification email when password is changed. Default: true. The default value is true.
- :invalidate_sessions_on_change (boolean/0) - Invalidate all other sessions on password change. Default: true. The default value is true.
:password_policy (keyword/0) - Password validation policy options for Sigra.PasswordPolicy. The default value is [].
- :min_length (pos_integer/0) - Minimum password length. Default: 8 (NIST SP 800-63B). The default value is 8.
- :max_bytes (pos_integer/0) - Maximum password byte size. Default: 72 (bcrypt compatibility). The default value is 72.
- :require_uppercase (boolean/0) - Require at least one uppercase letter. Default: false. The default value is false.
- :require_digit (boolean/0) - Require at least one digit. Default: false. The default value is false.
- :require_special (boolean/0) - Require at least one special character. Default: false. The default value is false.
- :check_common (boolean/0) - Check against the embedded common passwords list. Default: true. The default value is true.
- :check_breached (boolean/0) - Check against the HIBP breached passwords API. Default: false. The default value is false.
- :password_max_age - Maximum password age in seconds before forced rotation. Default: nil (disabled). The default value is nil.
:magic_link (keyword/0) - Magic link authentication options. The default value is [].
- :ttl (pos_integer/0) - Magic link token TTL in seconds. Default: 600 (10 minutes). The default value is 600.
- :max_requests (pos_integer/0) - Maximum magic link requests within the rate limit window. Default: 3. The default value is 3.
- :window_seconds (pos_integer/0) - Rate limit window for magic link requests in seconds. Default: 900 (15 minutes). The default value is 900.
:require_confirmation (boolean/0) - Whether email confirmation is required before login. Default: false. The default value is false.
:session_ttl (pos_integer/0) - Session time-to-live in seconds. Default: 5,184,000 (60 days). The default value is 5184000.
:session (keyword/0) - Session management options. The default value is [].
- :remember_me_max_age (pos_integer/0) - Max age for remember-me cookies in seconds. Default: 60 days (5,184,000s). The default value is 5184000.
- :reissue_age (pos_integer/0) - Age after which session tokens are reissued. Default: 7 days. The default value is 604800.
- :store (atom/0) - Module implementing the Sigra.SessionStore behaviour. The default value is Sigra.SessionStores.Ecto.
- :idle_timeout (pos_integer/0) - Idle timeout in seconds. Default: 1800 (30 minutes). The default value is 1800.
- :absolute_timeout (pos_integer/0) - Absolute session timeout in seconds. Default: 86400 (24 hours). The default value is 86400.
- :activity_update_threshold (pos_integer/0) - Minimum seconds between last_active_at DB writes. Default: 300 (5 minutes). The default value is 300.
- :sudo_timeout (pos_integer/0) - Sudo mode window in seconds. Default: 300 (5 minutes). The default value is 300.
- :session_schema (atom/0) - The generated UserSession Ecto schema module.
:token_ttl (keyword/0) - Token time-to-live values in seconds. The default value is [].
- :confirm (pos_integer/0) - Email confirmation token TTL. Default: 48 hours. The default value is 172800.
- :reset_password (pos_integer/0) - Password reset token TTL. Default: 1 hour. The default value is 3600.
- :magic_link (pos_integer/0) - Magic link token TTL. Default: 15 minutes. The default value is 900.
- :email_change (pos_integer/0) - Email change token TTL in seconds. Default: 24 hours. The default value is 86400.
:rate_limiting (keyword/0) - Rate limiting options. The default value is [].
- :limiter - Module implementing the Sigra.RateLimiter behaviour. Nil disables rate limiting. The default value is nil.
- :ip_limit (pos_integer/0) - Maximum requests per IP within the window. Default: 10. The default value is 10.
- :ip_window_ms (pos_integer/0) - IP rate limiting window in milliseconds. Default: 60 seconds. The default value is 60000.
- :account_limit (pos_integer/0) - Maximum failed attempts per account before lockout. Default: 5. The default value is 5.
:confirmation (keyword/0) - Email confirmation options. The default value is [].
- :unconfirmed_access - Behavior for unconfirmed users. :allow_with_banner shows a reminder, :block prevents login. The default value is :allow_with_banner.
- :code_length (pos_integer/0) - Length of the numeric confirmation code. Default: 6. The default value is 6.
- :max_resends (pos_integer/0) - Maximum confirmation resend requests per window. Default: 3. The default value is 3.
- :resend_window_seconds (pos_integer/0) - Rate limit window for confirmation resend in seconds. Default: 900 (15 minutes). The default value is 900.
- :code_max_attempts (pos_integer/0) - Maximum code entry attempts per window. Default: 5. The default value is 5.
- :code_window_seconds (pos_integer/0) - Rate limit window for code entry in seconds. Default: 900 (15 minutes). The default value is 900.
:reset (keyword/0) - Password reset options. The default value is [].
- :max_requests (pos_integer/0) - Maximum reset requests per email per window. Default: 3. The default value is 3.
- :window_seconds (pos_integer/0) - Rate limit window for reset requests in seconds. Default: 900 (15 minutes). The default value is 900.
:email (keyword/0) - Email delivery options. The default value is [].
- :from_address (String.t/0) - From address for transactional emails. Default derived from endpoint config.
- :delivery_mode - Email delivery mode. :auto detects Oban presence. Default: :auto. The default value is :auto.
- :oban_queue (String.t/0) - Oban queue name for async email delivery. Default: "sigra_mailer". The default value is "sigra_mailer".
- :oban_concurrency (pos_integer/0) - Maximum concurrent email delivery workers. Default: 10. The default value is 10.
:lockout (keyword/0) - Account lockout options. The default value is [].
- :threshold (pos_integer/0) - Failed attempts before lockout. Default: 5. The default value is 5.
- :duration (pos_integer/0) - Lockout duration in seconds. Default: 900 (15 minutes). The default value is 900.
- :notify (boolean/0) - Send lockout notification email. Default: true. The default value is true.
:geo_ip (keyword/0) - GeoIP lookup options. The default value is [].
- :module - Module implementing Sigra.GeoIP behaviour. Default: nil (disabled). The default value is nil.
:suspicious_login (keyword/0) - Suspicious login detection options. The default value is [].
- :enabled (boolean/0) - Enable suspicious login detection. Default: true. The default value is true.
- :notify (boolean/0) - Send suspicious login notification email. Default: true. The default value is true.
:mfa (keyword/0) - Multi-factor authentication options. The default value is [].
- :enabled (boolean/0) - Enable MFA support. Default: true. The default value is true.
- :totp_issuer - TOTP issuer name for authenticator apps. Falls back to humanized otp_app. Default: nil. The default value is nil.
- :totp_drift_steps (non_neg_integer/0) - TOTP drift window in 30-second steps. Default: 1. The default value is 1.
- :backup_code_count (pos_integer/0) - Number of backup codes generated per enrollment. Default: 8. The default value is 8.
- :trust_enabled (boolean/0) - Enable trust-this-browser cookies. Default: true. The default value is true.
- :trust_ttl (pos_integer/0) - Trust cookie TTL in seconds (default 30 days). Default: 2,592,000. The default value is 2592000.
- :lockout_threshold (pos_integer/0) - Failed MFA attempts before lockout. Default: 5. The default value is 5.
- :lockout_duration (pos_integer/0) - MFA lockout duration in seconds (default 15 min). Default: 900. The default value is 900.
- :pending_timeout (pos_integer/0) - MFA pending session timeout in seconds (default 5 min). Default: 300. The default value is 300.
- :show_trust_option (boolean/0) - Show trust-this-browser checkbox on MFA challenge. Default: true. The default value is true.
:passkeys (keyword/0) - Passkey (WebAuthn) options. The default value is [].
- :enabled (boolean/0) - Enable passkey support. Default: true. The default value is true.
- :passkey_primary_enabled (boolean/0) - Enable passkey-primary login. Passkey MFA and enrollment are still controlled by :enabled. Default: false. The default value is false.
- :sign_count_policy - Sign-count regression policy. Default: :warn to accommodate synced passkeys. The default value is :warn.
- :max_per_user (pos_integer/0) - Maximum passkeys per user. Enforced atomically. Default: 10. The default value is 10.
- :rp_id - Relying party ID. Default: nil. The default value is nil.
- :rp_name (String.t/0) - Relying party display name. Default: "Sigra". The default value is "Sigra".
- :origin - Relying party origin (https://...). Default: nil. The default value is nil.
- :attestation - Attestation conveyance preference. Default: :none. The default value is :none.
- :user_verification - User verification requirement. Default: :preferred. The default value is :preferred.
- :timeout_ms (pos_integer/0) - Passkey ceremony timeout in milliseconds. Default: 60_000. The default value is 60000.
- :ceremony_rate_limit (keyword/0) - Per-user ceremony initiation rate limit. Default: 5 per 60_000ms. The default value is [].
  - :limit (pos_integer/0) - Maximum ceremony initiations per user within the window. Default: 5. The default value is 5.
  - :window_ms (pos_integer/0) - Ceremony initiation window in milliseconds. Default: 60_000. The default value is 60000.
- :user_passkey_schema - Generated host UserPasskey schema module. Default: nil. The default value is nil.
:oauth (keyword/0) - OAuth / social login options. The default value is [].
- :enabled (boolean/0) - Master switch for OAuth. When false, OAuth routes are disabled and buttons hidden (D-63). The default value is true.
- :providers (keyword/0) - Provider configurations. Each key is a provider atom, value is a keyword list with :client_id, :client_secret, :redirect_uri, and optional :strategy, :scopes. The default value is [].
- :session_type - Session type for OAuth logins. Default: :remember_me (D-43). The default value is :remember_me.
- :link_confirmation - Account linking behavior when OAuth email matches existing account. Default: :required (D-01). The default value is :required.
- :trust_provider_email (boolean/0) - Whether to auto-confirm email based on provider verification. Set false for Facebook (D-42). The default value is true.
:api_token (keyword/0) - API token options. The default value is [].
- :prefix - Token prefix. Nil derives from otpapp: {otp_app}_sk. Must match ^[a-z0-9_]+$ and not start with eyJ. The default value is nil.
- :custom_scopes (list of String.t/0) - Custom scope strings in resource:action format. The default value is [].
- :write_implies_read (boolean/0) - Whether write scope implies read. Default: false. The default value is false.
- :require_expiry (boolean/0) - Whether expiration is required. Default: false. The default value is false.
- :max_ttl - Maximum TTL in seconds. Nil = no limit. The default value is nil.
- :cleanup_retention (pos_integer/0) - Retention period for revoked/expired tokens in seconds. Default: 90 days. The default value is 7776000.
- :activity_update_threshold (pos_integer/0) - Minimum seconds between last_used_at writes. Default: 300. The default value is 300.
- :default_page_size (pos_integer/0) - Default page size for token listing. Default: 50. The default value is 50.
- :max_page_size (pos_integer/0) - Maximum page size. Default: 200. The default value is 200.
- :api_token_schema - The generated UserAPIToken schema module. The default value is nil.
:jwt (keyword/0) - JWT options (requires Joken ~> 2.6 as optional dependency). The default value is [].
- :enabled (boolean/0) - Enable JWT support. Default: false. The default value is false.
- :algorithm - Signing algorithm. Default: HS256. The default value is "HS256".
- :issuer - JWT issuer claim. Nil = otp_app name. The default value is nil.
- :access_ttl (pos_integer/0) - Access token TTL in seconds. Default: 900 (15 min). The default value is 900.
- :refresh_ttl (pos_integer/0) - Refresh token TTL in seconds. Default: 30 days. The default value is 2592000.
- :refresh (boolean/0) - Enable refresh tokens. Default: true. The default value is true.
- :claims_builder - Module implementing Sigra.JWT.ClaimsBuilder behaviour. The default value is nil.
- :verify_epoch (boolean/0) - Verify user token_epoch on every JWT request. Default: true. The default value is true.
- :private_key - PEM private key for RS256/ES256. The default value is nil.
:deletion (keyword/0) - Account deletion options. The default value is [].
- :strategy - Deletion strategy. :soft_delete preserves row with deleted_at, :hard_delete removes row, :anonymize strips PII. Default: :soft_delete. The default value is :soft_delete.
- :grace_period_days - Days before scheduled deletion executes. 0 or nil for immediate. Default: 14. The default value is 14.
- :cooldown_hours (pos_integer/0) - Hours after cancelling deletion before re-requesting is allowed. Default: 24. The default value is 24.
- :notify (boolean/0) - Send email notifications for deletion events. Default: true. The default value is true.
:hooks (keyword/0) - Lifecycle hook callbacks. Each is a {module, function} tuple or nil. The default value is [].
- :on_register - Called after user registration. Receives (multi, context_map). Default: nil. The default value is nil.
- :on_email_change - Called after email change confirmation. Receives (multi, context_map). Default: nil. The default value is nil.
- :on_password_change - Called after password change. Receives (multi, context_map). Default: nil. The default value is nil.
- :on_delete - Called when deletion is scheduled. Receives (multi, context_map). Default: nil. The default value is nil.
:audit (keyword/0) - Structured audit logging options (Phase 9). See Sigra.Audit. The default value is [].
- :audit_schema - The generated AuditEvent schema module. Default: nil. The default value is nil.
- :retention_days - Days to retain audit events. nil = keep forever (D-09). Default: nil. The default value is nil.
- :max_metadata_bytes (pos_integer/0) - Cap on JSON-encoded metadata byte size (D-20). Default: 8192. The default value is 8192.
- :reserved_prefixes (list of String.t/0) - Reserved action prefixes developers cannot use (D-17, D-18). The default value is ["auth.", "session.", "mfa.", "oauth.", "api.", "account.", "sigra.", "passkey."].

Summary

Types

t()

Functions

new!(opts)

Creates a new %Sigra.Config{} struct from the given options.

oauth_enabled?(config)

Returns whether OAuth is enabled AND has at least one configured provider.

oauth_providers(config)

Returns the list of configured OAuth providers from the given config.

Types

t()

@type t() :: %Sigra.Config{
  api_token: keyword(),
  audit: keyword(),
  confirmation: keyword(),
  cookie_domain: String.t() | nil,
  deletion: keyword(),
  email: keyword(),
  email_module: module() | nil,
  geo_ip: keyword(),
  hooks: keyword(),
  jwt: keyword(),
  lockout: keyword(),
  magic_link: keyword(),
  mailer: module() | nil,
  mfa: keyword(),
  oauth: keyword(),
  organizations_module: module() | nil,
  otp_app: atom() | nil,
  passkeys: keyword(),
  password: keyword(),
  password_policy: keyword(),
  rate_limiting: keyword(),
  repo: module(),
  require_confirmation: boolean(),
  reset: keyword(),
  scope_module: module() | nil,
  secret_key_base: String.t() | nil,
  session: keyword(),
  session_ttl: pos_integer(),
  suspicious_login: keyword(),
  token_ttl: keyword(),
  user_schema: module()
}

Functions

new!(opts)

(since 0.1.0)

@spec new!(keyword()) :: t()

Creates a new %Sigra.Config{} struct from the given options.

Validates all options via NimbleOptions and raises NimbleOptions.ValidationError for invalid or missing required options. Only :repo and :user_schema are required; all other options have secure defaults.

Examples

iex> config = Sigra.Config.new!(repo: Fake.Repo, user_schema: Fake.User)
iex> config.repo
Fake.Repo

iex> config = Sigra.Config.new!(repo: Fake.Repo, user_schema: Fake.User)
iex> config.cookie_domain
nil

iex> config = Sigra.Config.new!(repo: Fake.Repo, user_schema: Fake.User, cookie_domain: ".example.com")
iex> config.cookie_domain
".example.com"

iex> config = Sigra.Config.new!(repo: Fake.Repo, user_schema: Fake.User, cookie_domain: nil)
iex> config.cookie_domain
nil

iex> config = Sigra.Config.new!(repo: Fake.Repo, user_schema: Fake.User, require_confirmation: true)
iex> config.require_confirmation
true

iex> config = Sigra.Config.new!(repo: Fake.Repo, user_schema: Fake.User, session_ttl: 86_400)
iex> config.session_ttl
86_400

oauth_enabled?(config)

(since 0.1.0)

@spec oauth_enabled?(t()) :: boolean()

Returns whether OAuth is enabled AND has at least one configured provider.

Returns true only when oauth[:enabled] is not explicitly false AND oauth[:providers] contains at least one entry. This prevents callers from rendering an empty "Sign in with..." row on the default config (which has no providers configured).

Examples

iex> config = Sigra.Config.new!(
...>   repo: Fake.Repo,
...>   user_schema: Fake.User,
...>   oauth: [enabled: true, providers: [google: [client_id: "x"]]]
...> )
iex> Sigra.Config.oauth_enabled?(config)
true

iex> config = Sigra.Config.new!(repo: Fake.Repo, user_schema: Fake.User)
iex> Sigra.Config.oauth_enabled?(config)
false

iex> config = Sigra.Config.new!(
...>   repo: Fake.Repo,
...>   user_schema: Fake.User,
...>   oauth: [enabled: false, providers: [google: [client_id: "x"]]]
...> )
iex> Sigra.Config.oauth_enabled?(config)
false

oauth_providers(config)

(since 0.1.0)

@spec oauth_providers(t()) :: keyword()

Returns the list of configured OAuth providers from the given config.

Examples

iex> config = Sigra.Config.new!(repo: Fake.Repo, user_schema: Fake.User, oauth: [providers: [google: [client_id: "x"]]])
iex> Sigra.Config.oauth_providers(config)
[google: [client_id: "x"]]

iex> config = Sigra.Config.new!(repo: Fake.Repo, user_schema: Fake.User)
iex> Sigra.Config.oauth_providers(config)
[]