standard_id 0.52.0 → 0.53.0

data/lib/generators/standard_id/install/templates/standard_id_reference.rb

@@ -0,0 +1,581 @@
+# StandardId configuration
+# Generated by: rails g standard_id:install --with-reference
+#
+# The annotated reference: every commonly changed setting with its default.
+# All configuration fields are defined in lib/standard_id/config/schema.rb.
+# Commented-out lines show defaults; uncomment and edit to override. Once you
+# know what you need, delete the commented lines: an initializer that holds
+# only your overrides is easier to review than one that holds every default.
+
+StandardId.configure do |c|
+  # An Inertia app whose users sign in passwordlessly or socially can start
+  # from a preset instead of setting each option below. :inertia_web sets
+  # use_inertia, alias_current_user, web.signup/password_login/password_reset
+  # = false and oauth.discovery_endpoint_base = :request. Anything you assign
+  # yourself wins, before or after this line.
+  # c.preset :inertia_web
+
+  # ---------------------------------------------------------------------------
+  # Required
+  # ---------------------------------------------------------------------------
+
+  # The ActiveRecord class that represents a user/account in your app. Must
+  # include StandardId::AccountAssociations (see post-install checklist).
+  # Default: "User"
+  c.account_class_name = "User"
+  # The enum key StandardId::AccountStatus uses for a deactivated account
+  # (default :inactive). Set it to the value your status column already
+  # carries, e.g. :suspended, to adopt the concern without renaming it.
+  # c.inactive_account_status = :inactive
+
+  # JWT "iss" claim — typically your application's canonical base URL. When
+  # set, tokens embed it and verification enforces it. Strongly recommended
+  # for production; otherwise the engine logs a warning on boot.
+  # Default: nil
+  # c.issuer = "https://auth.example.com"
+
+  # ---------------------------------------------------------------------------
+  # Discovery documents (/.well-known/openid-configuration and
+  # /.well-known/oauth-authorization-server)
+  # ---------------------------------------------------------------------------
+  # READ THIS IF YOU MOUNT ApiEngine UNDER A PREFIX (/api, /api/v1, ...).
+  #
+  # The issuer and the endpoint base are different things. `issuer` is a stable
+  # security identifier (RFC 8414 §2) that clients compare byte-for-byte with the
+  # URL they used for discovery and with the `iss` claim of issued tokens. It is
+  # never derived from the request and cannot be overridden.
+  #
+  # `discovery_endpoint_base` is where /authorize, /oauth/token etc. ACTUALLY
+  # are. It defaults to the issuer, which is right only if your issuer carries
+  # the mount path (e.g. "https://host/auth/api"). If it does not, the document
+  # advertises endpoints at the bare origin and every one of them 404s.
+  #
+  #   nil (default) — the issuer
+  #   :request      — request.base_url + the detected mount path  <- prefixed mounts
+  #   "https://..." — verbatim
+  #   callable      — receives (request:); for a proxy that rewrites base_url, or
+  #                   an app mounting ApiEngine more than once
+  #
+  # Default: nil
+  # c.oauth.discovery_endpoint_base = :request
+
+  # Members that cannot be derived. Values static or callable; a callable gets
+  # { origin:, endpoint_base:, issuer:, request: } (origin has no path). A nil
+  # value REMOVES the member rather than emitting null. Setting `issuer` raises.
+  # Default: {}
+  # c.oauth.discovery_metadata_overrides = {
+  #   # a host-owned shim that injects the audience before handing off to the
+  #   # engine's /authorize
+  #   authorization_endpoint: ->(ctx) { "#{ctx[:origin]}/oauth/authorize" },
+  #   # narrower than everything the server can mint
+  #   scopes_supported: %w[mcp mcp:read],
+  #   # MUST mirror your dynamic-registration policy, or spec-following clients
+  #   # register in a way that policy then rejects
+  #   token_endpoint_auth_methods_supported: %w[none],
+  #   # omit a member entirely
+  #   userinfo_endpoint: nil
+  # }
+  #
+  # RFC 8615 clients probe the ORIGIN ROOT, which is outside every engine mount,
+  # so those routes must be drawn in config/routes.rb — the gem cannot:
+  #
+  #   standard_id_well_known_routes at: "/api"   # your ApiEngine mount path
+  #
+  # That draws the root form AND the RFC 8414 §3.1 path-inserted form
+  # (/.well-known/oauth-authorization-server/api). The second looks redundant
+  # and is not: it is the URL Claude Code actually requests against a
+  # path-carrying issuer. Accepts only:/except: (:oauth_authorization_server,
+  # :openid_configuration, :jwks) — e.g. `only: :jwks` if you keep your own
+  # metadata controller. See docs/MIGRATION_GUIDE.md.
+
+  # Login URL used for redirects when authentication is required but missing.
+  # Default: "/login"
+  # c.login_url = "/login"
+
+  # ---------------------------------------------------------------------------
+  # Infrastructure
+  # ---------------------------------------------------------------------------
+
+  # Cache backend for rate limits, JWKS, etc. Falls back to Rails.cache.
+  # Default: Rails.cache
+  # c.cache_store = Rails.cache
+
+  # Logger used by StandardId. Falls back to Rails.logger.
+  # Default: Rails.logger
+  # c.logger = Rails.logger
+
+  # Layout used by built-in ERB web views. Ignored when use_inertia is true.
+  # Default: nil (StandardId's packaged layout)
+  # c.web_layout = "application"
+
+  # Expose current_account as current_user (useful for ActionPolicy / Pundit).
+  # Default: false
+  # c.alias_current_user = true
+
+  # Opt StandardId's OWN associations out of an app-wide
+  # `strict_loading_by_default = true`.
+  #
+  # Affects Account#identifiers/credentials/sessions/refresh_tokens/
+  # client_applications, StandardId::Session#refresh_tokens and
+  # StandardId::Identifier#credentials. Set it to false if strict loading is on
+  # app-wide and you don't want to eager-load the gem's internals at every call
+  # site (the gem lazy-loads some of them itself).
+  #
+  # Tri-state, and nil is NOT the same as false:
+  #   nil   — declare no `strict_loading:` option at all; the associations
+  #           inherit your model's setting, exactly as before this option
+  #           existed. This is the default and preserves existing behaviour.
+  #   false — opt out: these associations may lazy-load even with strict
+  #           loading on app-wide.
+  #   true  — opt in: force strict loading on them even if it is off app-wide.
+  #
+  # Must be set HERE, in an initializer — not in an `after_initialize` block.
+  # The associations read it when your Account class body runs, so a later
+  # assignment has no effect. StandardId raises a ConfigurationError at boot if
+  # it detects that, rather than letting it fail silently.
+  #
+  # Default: nil
+  # c.association_strict_loading = false
+
+  # Default scope applied when loading the current account — eager-load the
+  # associations your views/controllers touch to avoid N+1s.
+  # Default: nil
+  # c.account_scope = ->(scope) { scope.includes(:profiles, :identifiers) }
+
+  # Inertia.js support (requires the inertia_rails gem). When enabled, web
+  # controllers render Inertia components instead of ERB views. Provide the
+  # matching frontend components (e.g. pages/auth/login/show.tsx).
+  # Defaults: use_inertia = false, inertia_component_namespace = "standard_id"
+  # c.use_inertia = true
+  # c.inertia_component_namespace = "auth"
+
+  # ---------------------------------------------------------------------------
+  # Web engine feature toggles
+  # ---------------------------------------------------------------------------
+  # Each toggle enables or disables a built-in WebEngine route group. Turn
+  # off features your app handles itself or does not expose.
+
+  # Default: true — enables /login, /logout and related password routes.
+  # c.web.password_login = true
+
+  # Default: true — enables /signup.
+  # c.web.signup = true
+
+  # Default: false — enables OTP (email/SMS) login at /passwordless.
+  # c.web.passwordless_login = false
+
+  # Default: false — allows new account registration via passwordless OTP.
+  # c.web.passwordless_registration = false
+
+  # Default: true — enables /auth/:provider social login routes.
+  # c.web.social_login = true
+
+  # Default: true — enables /password/reset flow.
+  # c.web.password_reset = true
+
+  # Default: true — enables email verification endpoints.
+  # c.web.email_verification = true
+
+  # Default: true — enables phone verification endpoints.
+  # c.web.phone_verification = true
+
+  # Default: true — enables /sessions management UI.
+  # c.web.sessions_management = true
+
+  # ---------------------------------------------------------------------------
+  # Session lifetimes (seconds)
+  # ---------------------------------------------------------------------------
+
+  # Default: 86_400 — 24 hours for browser (cookie) sessions.
+  # c.session.browser_session_lifetime = 86_400
+
+  # Default: 2_592_000 — 30 days for "remember me" cookies.
+  # c.session.browser_session_remember_me_lifetime = 2_592_000
+
+  # Default: 2_592_000 — 30 days for API / mobile device sessions.
+  # c.session.device_session_lifetime = 2_592_000
+
+  # Default: 7_776_000 — 90 days for service-to-service sessions.
+  # c.session.service_session_lifetime = 7_776_000
+
+  # ---------------------------------------------------------------------------
+  # Password policy
+  # ---------------------------------------------------------------------------
+
+  # Default: 8
+  # c.password.minimum_length = 8
+
+  # Default: true
+  # c.password.require_special_chars = true
+
+  # Default: true
+  # c.password.require_uppercase = true
+
+  # Default: true
+  # c.password.require_numbers = true
+
+  # ---------------------------------------------------------------------------
+  # Passwordless (OTP)
+  # ---------------------------------------------------------------------------
+
+  # OTP email delivery mode:
+  #   :custom   — host app handles delivery via event subscriber (default)
+  #   :built_in — engine sends via PasswordlessMailer
+  # Default: :custom
+  # c.passwordless.delivery = :built_in
+  # c.passwordless.mailer_from = "noreply@example.com"
+  # c.passwordless.mailer_subject = "Your sign-in code"
+
+  # Default: 600 (10 minutes) — TTL of OTP codes.
+  # c.passwordless.code_ttl = 600
+
+  # Default: 6 — length of generated OTP codes (digits). Clamped to 4..10.
+  # Codes may be zero-padded (e.g. "000123") so host apps that display or
+  # parse codes must treat them as strings, not integers. 8+ is recommended
+  # for security-sensitive deployments.
+  # c.passwordless.code_length = 6
+
+  # Per-challenge global attempt ceiling (across all IPs). When reached the
+  # challenge is burned so further submissions fail fast. Distinct from the
+  # per-IP rate limit (c.rate_limits.otp_verify_per_ip) — this defends
+  # against distributed brute-force against a single challenge.
+  # Default: nil — falls back to :max_attempts (default 3) for backwards
+  # compatibility, so the effective default ceiling is 3.
+  # c.passwordless.max_attempts_per_challenge = 3
+
+  # Default: 3 — deprecated alias for :max_attempts_per_challenge. Retained
+  # for backwards compatibility; new installs should set the newer key.
+  # c.passwordless.max_attempts = 3
+
+  # Default: 30 — OTP-resend cooldown: minimum seconds before the same target
+  # can request another code. Enforced in the passwordless start path; a resend
+  # inside the window is rejected (the already-sent code stays valid). Set to 0
+  # to disable the cooldown.
+  # c.passwordless.retry_delay = 30
+
+  # Custom username validator; return nil/false to accept, or an error message
+  # string to reject. Useful for domain allow-lists or truemail integration.
+  # Default: nil
+  # c.passwordless.username_validator = ->(username, connection_type) {
+  #   "Invalid email" unless TruemailValidator.valid?(username)
+  # }
+
+  # Custom account factory invoked during passwordless registration.
+  # Receives (identifier:, params:, request:) and must return an Account.
+  # Default: nil (uses built-in find_or_create logic)
+  # c.passwordless.account_factory = ->(identifier:, params:, request:) {
+  #   Account.create!(email: identifier.value)
+  # }
+
+  # With c.passwordless.delivery = :custom, deliver codes from an event
+  # subscriber (c.passwordless_email_sender / _sms_sender were removed in
+  # 0.43). It runs synchronously in the request, so I18n.locale etc. are still
+  # available. The same subscriber delivers Otp.issue(delivery: :custom) codes.
+  #
+  # StandardId::Events.subscribe(StandardId::Events::PASSWORDLESS_CODE_GENERATED) do |event|
+  #   next if event[:skip_sender] # Otp.issue(delivery: :manual)
+  #   case event[:channel]
+  #   when "email" then PasswordlessMailer.with(code: event[:code_challenge].code, to: event[:identifier]).deliver_later
+  #   when "sms"   then SmsProvider.send_code(phone: event[:identifier], code: event[:code_challenge].code)
+  #   end
+  # end
+
+  # ---------------------------------------------------------------------------
+  # API engine — OAuth / JWT
+  # ---------------------------------------------------------------------------
+
+  # Default: 3600 — access token lifetime in seconds (1 hour).
+  # c.oauth.default_token_lifetime = 3600
+
+  # Default: 2_592_000 — refresh token lifetime in seconds (30 days).
+  # c.oauth.refresh_token_lifetime = 2_592_000
+
+  # Per-grant overrides. Keys map to OAuth grant types.
+  # Default: {}
+  # c.oauth.token_lifetimes = {
+  #   password: 8.hours,
+  #   client_credentials: 24.hours,
+  #   social: 24.hours
+  # }
+
+  # Audiences accepted in JWT "aud" claim. An empty array disables audience
+  # validation entirely — set this in production.
+  # Default: []
+  # c.oauth.allowed_audiences = %w[web mobile admin]
+
+  # Scope-to-claims mapping — when a scope is granted, every listed claim is
+  # resolved via claim_resolvers below and embedded in the access token.
+  # Default: {}
+  # c.oauth.scope_claims = {
+  #   profile: %i[email display_name]
+  # }
+
+  # Claim resolvers: one per claim listed in scope_claims. Each is a callable
+  # receiving keyword args — pick only the ones you need.
+  # Available kwargs: account:, client:, request:, audience:, session:
+  # Default: {}
+  # c.oauth.claim_resolvers = {
+  #   email: ->(account:) { account.email },
+  #   display_name: ->(account:, client:) { "#{account.name} for #{client.client_id}" },
+  #   channel_id: ->(client:) { client.owner_type == "Channel" ? client.owner_id : nil }
+  # }
+  # c.oauth.allowed_audiences = %w[web mobile admin] # Empty = no validation
+  #
+  # Audience → profile-type binding. When set, StandardId::AudienceVerification
+  # will additionally verify that the authenticated account holds a profile of
+  # the configured type for the matched audience. Values may be a single
+  # profile-type string or an Array<String> for multi-type audiences.
+  # c.oauth.audience_profile_types = {
+  #   "admin_kit"     => "PlatformProfile",
+  #   "companion_kit" => "DeviceUserProfile",
+  #   "harness"       => ["PlatformProfile", "DeviceUserProfile"]
+  # }
+  #
+  # Optional resolver for picking the profile used for a given audience. Called
+  # with (account:, audience:, profile_types:). When nil (default), the gem
+  # looks up `account.profiles` and picks one whose `profileable_type` is in
+  # the configured profile_types (preferring an `active?` record).
+  # c.oauth.audience_profile_resolver = ->(account:, audience:, profile_types:) {
+  #   account.profiles.active.find_by(profileable_type: profile_types)
+  # }
+  #
+  # Custom claims added to every access token (independent of scopes).
+  # Receives keyword arguments: account:, client:, request:, audience:
+  # Must return a Hash. Reserved JWT keys (sub, exp, iat, etc.) are excluded.
+  # c.oauth.custom_claims = ->(account:, **) { { channel_id: account.channel_id } }
+
+  # RFC 7662 token introspection (POST /oauth/introspect).
+  #
+  # Off by default: the endpoint returns 404 and `introspection_endpoint` is not
+  # advertised in the discovery documents. An endpoint that answers questions
+  # about other people's tokens is not something to expose by accident.
+  #
+  # Confidential clients only — the caller presents client_id + client_secret
+  # (HTTP Basic or form body). Every failure renders `{"active": false}` with no
+  # other members, per RFC 7662 §2.2, including a tripped rate limit (a 429
+  # would distinguish "throttled" from "token invalid" and make the limiter a
+  # token-validity oracle).
+  #
+  # KNOW THE LIMIT BEFORE BUILDING AN AUTHORIZATION GATE ON THIS. Access tokens
+  # are stateless — never persisted, and carrying no `sid` — so a revoked
+  # session's access token introspects as `active: true` until its `exp`.
+  # Introspection answers "did we mint this, and is it unexpired?", NOT "is it
+  # still honoured?". The mitigation is a short access-token lifetime. Refresh
+  # tokens ARE persisted and are checked against the row, so a revoked refresh
+  # token introspects as inactive immediately.
+  #
+  # Default: false
+  # c.oauth.introspection_enabled = true
+
+  # JWT signing configuration.
+  #
+  # Default: :hs256 symmetric signing with Rails.application.secret_key_base.
+  # For asymmetric signing, set signing_key and expose the public key via the
+  # JWKS endpoint at /.well-known/jwks.json.
+  #
+  # Algorithms: :hs256/:hs384/:hs512 (HMAC), :rs256/:rs384/:rs512 (RSA),
+  #             :es256/:es384/:es512 (ECDSA — recommended for new projects).
+  #
+  # Generate keys:
+  #   ES256: openssl ecparam -name prime256v1 -genkey -noout -out signing_key.pem
+  #   RS256: openssl genrsa -out signing_key.pem 2048
+  #
+  # c.oauth.signing_algorithm = :es256
+  # c.oauth.signing_key = Rails.application.credentials.dig(:standard_id, :signing_key)
+  #
+  # Key rotation — move the previous signing_key here so tokens issued under
+  # it still verify during the grace period. Remove once the longest token
+  # lifetime has elapsed.
+  # c.oauth.previous_signing_keys = [
+  #   Rails.application.credentials.dig(:standard_id, :previous_signing_key)
+  # ]
+  # # Cross-algorithm rotation:
+  # c.oauth.previous_signing_keys = [
+  #   { key: Rails.application.credentials.dig(:standard_id, :old_rsa_key), algorithm: :rs256 }
+  # ]
+
+  # ---------------------------------------------------------------------------
+  # Lifecycle hooks (WebEngine, synchronous)
+  # ---------------------------------------------------------------------------
+
+  # Called after credential verification, BEFORE session creation.
+  # Receives: (account, request, context)
+  #   context = { mechanism:, provider:, first_sign_in: }
+  # Return nil/truthy to proceed, or { error: "message" } to reject.
+  # Default: nil
+  # c.before_sign_in = ->(account, request, context) {
+  #   { error: "Access restricted" } unless account.allowed?
+  # }
+
+  # Called after successful sign-in, before redirect.
+  # Receives: (account, request, context)
+  #   context = { first_sign_in:, mechanism:, provider:, session: }
+  # Return nil (use default redirect) or a path string to override.
+  # Raise StandardId::AuthenticationDenied to reject after sign-in.
+  # Default: nil
+  # c.after_sign_in = ->(account, request, context) {
+  #   context[:first_sign_in] ? "/onboarding" : nil
+  # }
+
+  # Decides which authentication methods may sign an account in. Consulted in
+  # EVERY web and API flow that establishes a new authentication, after the
+  # credential is proven and before any session or token is created.
+  # Receives any subset of: account:, auth_method: (:password, :passwordless,
+  # :social, :remember_me, :unspecified), provider:, request:, flow:
+  # Return truthy to allow, false/nil to refuse, or raise
+  # StandardId::LoginMethodDenied.new("message") to refuse with a message.
+  # Default: nil (every method allowed)
+  # c.login_method_policy = ->(account:, auth_method:, provider:) {
+  #   next true unless account.staff?
+  #   auth_method == :social && provider == "void_which_binds"
+  # }
+
+  # Called after a new account is created via any mechanism.
+  # Receives: (account, request, context)
+  #   context = { mechanism:, provider: }
+  # Use for profile provisioning, welcome emails, analytics, etc.
+  # Default: nil
+  # c.after_account_created = ->(account, request, context) {
+  #   UserProfileProvisioning.call(account, source: context[:mechanism])
+  # }
+
+  # ---------------------------------------------------------------------------
+  # Events
+  # ---------------------------------------------------------------------------
+
+  # Emit internal lifecycle events through Rails.logger.
+  # Default: false
+  # c.events.enable_logging = false
+
+  # For audit logging, use the standard_audit gem — see the README.
+
+  # ---------------------------------------------------------------------------
+  # Social login
+  # ---------------------------------------------------------------------------
+  # These fields are declared by the PROVIDER PLUGIN GEMS, not by standard_id
+  # itself, so each line below requires the matching gem in your Gemfile:
+  # `standard_id-google` for the google_* fields, `standard_id-apple` for the
+  # apple_* fields. Uncommenting a line without its gem raises
+  # StandardId::ConfigurationError ("Unknown field ... for scope 'social'") —
+  # the field genuinely does not exist, because nothing declared it.
+  #
+  # With the gem present, writing them here — in a plain initializer, in the
+  # `social` scope, exactly as shown — is correct and supported. standard_id
+  # >= 0.33.0 declares every loaded provider's fields before initializers run.
+  # On 0.32.0 and earlier these same lines raised, because the fields were only
+  # declared later from the plugin's Railtie, and apps worked around it by
+  # wrapping the writes in `Rails.application.config.after_initialize`. That
+  # wrapper is no longer needed, and it still works if you have one.
+  #
+  # ENV defaults (standard_id >= 0.42): every provider field you do not assign
+  # falls back to the ENV variable named after it, upper-cased — so with the
+  # canonical variables below set, you need none of these lines. Assign a
+  # field only to read it from somewhere else (a differently named variable,
+  # Rails credentials); an explicit assignment, even of nil, always wins.
+  #
+  #   GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
+  #   APPLE_CLIENT_ID, APPLE_MOBILE_CLIENT_ID,
+  #   APPLE_PRIVATE_KEY, APPLE_KEY_ID, APPLE_TEAM_ID
+  #
+  # A provider is enabled when its client ID is present
+  # (StandardId.social_provider_enabled?(:google)). An enabled provider missing
+  # fields its plugin marks required is reported at boot — see
+  # c.social.provider_misconfiguration below.
+
+  # c.social.google_client_id       = Rails.application.credentials.dig(:google, :client_id)
+  # c.social.google_client_secret   = Rails.application.credentials.dig(:google, :client_secret)
+  # c.social.apple_client_id        = ENV["APPLE_CLIENT_ID"]         # web (Services ID) flow
+  # c.social.apple_mobile_client_id = ENV["APPLE_MOBILE_CLIENT_ID"]  # native id_token flow
+  # c.social.apple_private_key      = ENV["APPLE_PRIVATE_KEY"]       # .p8 PEM, newlines intact
+  # c.social.apple_key_id           = ENV["APPLE_KEY_ID"]
+  # c.social.apple_team_id          = ENV["APPLE_TEAM_ID"]
+
+  # What to do at boot when an enabled provider is missing required fields
+  # (e.g. APPLE_CLIENT_ID set without APPLE_PRIVATE_KEY — the sign-in flow
+  # would start, then fail at the callback). :warn logs a warning; :raise
+  # raises StandardId::ConfigurationError in production and warns elsewhere.
+  # Default: :warn
+  # c.social.provider_misconfiguration = :raise
+
+  # Mobile redirect URI allow-list — custom schemes used by native apps.
+  # Default: []
+  # c.social.allowed_redirect_url_prefixes = ["example-app://"]
+
+  # OAuth scopes the host app supports for social providers.
+  # Default: []
+  # c.social.available_scopes = %w[profile email offline_access]
+
+  # Account linking strategy, for a social login whose (provider, sub) is not
+  # linked yet but whose email belongs to an existing account:
+  #   :strict          — link only if that email identifier came from the same
+  #                      provider, predates provider tracking, or the account
+  #                      already has an identifier from this provider (default)
+  #   :trust_provider  — link to the account that holds the email
+  # Under both, the provider must report the email as verified, and an email
+  # already linked to a different sub from the same provider is refused.
+  # Default: :strict
+  # c.social.link_strategy = :trust_provider
+
+  # Attributes written to the Account on social signup.
+  # Default: nil
+  # c.social.social_account_attributes = ->(social_info:, provider:) {
+  #   { email: social_info[:email], name: social_info[:name] || social_info[:given_name] }
+  # }
+
+  # ---------------------------------------------------------------------------
+  # OIDC logout allow-list
+  # ---------------------------------------------------------------------------
+
+  # Valid post_logout_redirect_uri values accepted by the OIDC RP-initiated
+  # logout endpoint.
+  # Default: []
+  # c.allowed_post_logout_redirect_uris = [
+  #   "https://app.example.com/logged_out",
+  #   "https://admin.example.com/signout"
+  # ]
+
+  # ---------------------------------------------------------------------------
+  # Rate limits (Rails 8 rate_limit DSL)
+  # ---------------------------------------------------------------------------
+  # Defaults are conservative; tune per environment.
+
+  # Login limits. The login action branches password OR passwordless, so on a
+  # passwordless app these govern the OTP-SEND limit. Prefer the
+  # mechanism-agnostic names (password_login_per_ip/_per_email were removed in 0.43).
+  # c.rate_limits.login_per_ip                   = 20  # per 15 minutes
+  # c.rate_limits.login_per_email                = 5   # per 15 minutes
+  # c.rate_limits.otp_verify_per_ip              = 20  # per 15 minutes
+  # c.rate_limits.verification_start_per_target  = 3   # per 15 minutes
+  # c.rate_limits.verification_start_per_ip      = 10  # per hour
+  # c.rate_limits.api_passwordless_start_per_ip  = 10  # per hour
+  # c.rate_limits.api_passwordless_start_per_target = 5  # per 15 minutes
+  # c.rate_limits.api_token_per_ip               = 30  # per 15 minutes
+
+  # Token introspection (only relevant with c.oauth.introspection_enabled).
+  # Throttles by IP so the endpoint can't be used to bulk-classify stolen
+  # tokens. Note the limit renders the ordinary {"active": false} / 200 rather
+  # than 429 — see the introspection_enabled comment above for why.
+  # c.rate_limits.introspection_per_ip           = 30  # per 15 minutes
+
+  # Optional per-audience tightening on top of api_token_per_ip. Only token
+  # requests targeting a configured audience count toward its cap (per IP,
+  # per 15 minutes); unlisted audiences are governed by the global ceiling.
+  # c.rate_limits.api_token_per_audience_per_ip  = { "mobile_app" => 10 }
+
+  # ---------------------------------------------------------------------------
+  # Observability
+  # ---------------------------------------------------------------------------
+
+  # Extra fields merged into Sentry user context for authenticated requests.
+  # Receives (account, session). Return a Hash; non-callable values ignored.
+  # Default: nil
+  # c.sentry_context = ->(account, _session) {
+  #   { segment: account.primary_profile&.type }
+  # }
+end
+
+# Notes:
+# - All scopes/fields are defined via the schema DSL in
+#   lib/standard_id/config/schema.rb
+# - Values are cast to the declared type (string, integer, boolean, ...).
+# - Invalid scopes or fields raise ArgumentError with a helpful message.

data/lib/standard_id/app_environment.rb

@@ -0,0 +1,26 @@
+module StandardId
+  # Whether this deploy is production, for every check the gem makes.
+  #
+  # The estate convention (shared by standard_audit, standard_health and
+  # standard_singpass) is the APP_ENVIRONMENT variable, falling back to
+  # Rails.env: a physically-staging box runs RAILS_ENV=production with
+  # APP_ENVIRONMENT=staging, so Rails.env alone would call staging production.
+  #
+  # It fails closed. Only the known non-production names count as
+  # non-production; any other value (a typo such as "prod", or "production")
+  # is production, so a misconfigured variable can never switch off a
+  # production-only guard.
+  module AppEnvironment
+    NON_PRODUCTION = %w[staging preview development test].freeze
+
+    module_function
+
+    # @return [Boolean]
+    def production?
+      app_env = ENV["APP_ENVIRONMENT"].to_s.strip
+      return !NON_PRODUCTION.include?(app_env) unless app_env.empty?
+
+      defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
+    end
+  end
+end

data/lib/standard_id/config/schema.rb

@@ -213,19 +213,19 @@ StandardId::ConfigSchema.define do
     # for *any* realm. Use a long, non-guessable value and unset it
     # outside test environments.
     #
-    # "Production" is decided by production_env_detector below (default
-    # Rails.env.production?), so host apps that distinguish a physical deploy
-    # environment from RAILS_ENV can still gate this correctly.
+    # "Production" is decided by production_env_detector below, defaulting to
+    # StandardId::AppEnvironment: APP_ENVIRONMENT when set (only staging,
+    # preview, development and test are non-production; anything else is
+    # production), else Rails.env.production?.
     field :bypass_code, type: :string, default: nil
 
     # Optional callable deciding whether the current deploy is "production"
     # for the purpose of the bypass-code guard. Takes no args, returns a
-    # boolean. When nil (default), falls back to Rails.env.production? — so
-    # existing consumers are unchanged. Host apps that distinguish a physical
-    # deploy environment from RAILS_ENV (e.g. APP_ENVIRONMENT, which stays
-    # RAILS_ENV=production on a physically-staging box) can supply
-    # `-> { AppEnv.production? }` to allow a bypass code on staging while it
-    # stays refused on real production.
+    # boolean. When nil (default), StandardId::AppEnvironment decides, which
+    # already reads APP_ENVIRONMENT (a physically-staging box with
+    # RAILS_ENV=production and APP_ENVIRONMENT=staging is not production), so
+    # `-> { AppEnv.production? }` is no longer needed. Set it only for a
+    # different discriminator.
     field :production_env_detector, type: :any, default: nil
 
     # Custom username validator for passwordless flows.

data/lib/standard_id/engine.rb

@@ -166,7 +166,7 @@ module StandardId
     # inclusion. Extracted to a module method so specs can exercise it
     # directly without booting a second Rails app.
     def self.warn_if_allowed_audiences_empty_in_production!
-      return unless Rails.env.production?
+      return unless StandardId::AppEnvironment.production?
       return if StandardId.config.oauth.allowed_audiences.present?
 
       Rails.logger.warn(

data/lib/standard_id/passwordless/verification_service.rb

@@ -247,14 +247,14 @@ module StandardId
       end
 
       # Whether the bypass code is forbidden because this is a production
-      # deploy. Defers to config.passwordless.production_env_detector when set
-      # (host apps that distinguish a physical deploy env from RAILS_ENV), else
-      # falls back to Rails.env.production?.
+      # deploy. Defers to config.passwordless.production_env_detector when set,
+      # else StandardId::AppEnvironment (APP_ENVIRONMENT, then Rails.env; fails
+      # closed).
       def bypass_production_deploy?
         detector = StandardId.config.passwordless.production_env_detector
         return !!detector.call if detector
 
-        defined?(Rails) && Rails.env.production?
+        StandardId::AppEnvironment.production?
       end
 
       def resolve_target_and_channel!(email, phone)

data/lib/standard_id/provider_registry.rb

@@ -201,7 +201,7 @@ module StandardId
       end
 
       def production?
-        defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
+        StandardId::AppEnvironment.production?
       end
 
       def validate_provider!(provider_class)