sessions 0.1.0

data/lib/sessions/adapters/omniauth.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Sessions
+  module Adapters
+    # OmniAuth integration.
+    #
+    # Successes need NO hook here: the OAuth callback always lands in an
+    # app-side controller that creates the session through whichever adapter
+    # is active, and the classifier sniffs `env["omniauth.auth"]` at that
+    # moment (→ docs/research/05-oauth.md §1.2).
+    #
+    # Failures are the part nobody records: every strategy failure funnels
+    # through the swappable `OmniAuth.config.on_failure` rack endpoint. We
+    # COMPOSE-wrap it (record, then call the original — Devise's dispatcher
+    # or OmniAuth's FailureEndpoint both keep working) from
+    # `config.after_initialize`, so it wraps whatever the app's own
+    # initializers installed. Captured: the error type symbol
+    # (:invalid_credentials, :access_denied = the user hit Cancel,
+    # :authenticity_error = CSRF), the provider, the originating page, and
+    # IP/UA. Not capturable (documented): which local user, and
+    # abandonments at the provider.
+    module Omniauth
+      module_function
+
+      def install!
+        return if @installed
+        return unless defined?(::OmniAuth) && ::OmniAuth.respond_to?(:config)
+
+        @installed = true
+        original = ::OmniAuth.config.on_failure
+        ::OmniAuth.config.on_failure = lambda do |env|
+          Sessions::Adapters::Omniauth.record_failure(env)
+          original.call(env)
+        end
+      end
+
+      def installed?
+        !!@installed
+      end
+
+      def reset_installation!
+        @installed = false
+      end
+
+      def record_failure(env)
+        Sessions.safely("omniauth.failure") do
+          next unless Sessions.config.track_failed_logins
+
+          request = ActionDispatch::Request.new(env)
+          strategy = env["omniauth.error.strategy"]
+          provider = strategy.respond_to?(:name) ? strategy.name.to_s : nil
+
+          Sessions.record_failed_attempt(
+            request,
+            reason: env["omniauth.error.type"],
+            method: :oauth,
+            provider: Sessions::Classifier.normalize_provider(provider),
+            detail: { origin: env["omniauth.origin"] }.compact
+          )
+        end
+      end
+    end
+  end
+end

data/lib/sessions/adapters/warden.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+module Sessions
+  module Adapters
+    # The Devise/Warden adapter — four class-level Warden hooks, registered
+    # from the engine ONLY when `::Warden::Manager` is already loaded
+    # (Bundler.require precedes initializers, so the check is decisive; the
+    # gem never `require`s warden itself and stays inert in non-Warden apps).
+    #
+    # The revocation mechanism generalizes devise-security's proven
+    # `session_limitable` (a complete 55-line template whose only structural
+    # flaw is one-token-per-user): the token moves from a users-table column
+    # to a sessions-table ROW, turning "exactly one session" into "N devices,
+    # each individually revocable" (→ docs/research/04-devise-warden.md §5).
+    #
+    #   login  — mint a random token, store [row_id, raw_token] in the
+    #            per-scope warden session (it survives Warden's :renew SID
+    #            rotation and is deleted by Warden itself on logout; we
+    #            never key on the Rack SID), persist only the SHA-256
+    #            digest on the row.
+    #   fetch  — per-request liveness check: row exists + digest matches
+    #            (constant-time) → throttled touch; row gone (revoked!) →
+    #            the proven session_limitable kick: clear, logout, throw.
+    #   failure — record the failed attempt with the typed identity.
+    #   logout — destroy the row, labeled as a logout.
+    module Warden
+      # Key inside `warden.session(scope)` holding [row_id, raw_token].
+      SESSION_KEY = "sessions"
+
+      # Sticky per-scope flag: a login recorded with `sessions_skip: true`
+      # must not be kicked by the fetch validation later (session_limitable's
+      # third skip layer).
+      SKIP_SESSION_KEY = "sessions.skip"
+
+      # Request-wide skip: `request.env["sessions.skip"] = true`.
+      SKIP_ENV_KEY = "sessions.skip" # = Sessions::SKIP_ENV_KEY (set by Sessions.skip!)
+
+      # The `throw :warden` message on revoked sessions — Devise's failure
+      # app surfaces it like :timeout/:session_limited (add a
+      # `devise.failure.session_revoked` translation for custom copy).
+      THROW_MESSAGE = :session_revoked
+
+      module_function
+
+      def install!
+        return if @installed
+
+        @installed = true
+
+        ::Warden::Manager.after_set_user(except: :fetch) do |record, warden, opts|
+          Sessions::Adapters::Warden.record_login(record, warden, opts)
+        end
+
+        ::Warden::Manager.after_set_user(only: :fetch) do |record, warden, opts|
+          Sessions::Adapters::Warden.validate_session(record, warden, opts)
+        end
+
+        ::Warden::Manager.before_failure do |env, opts|
+          Sessions::Adapters::Warden.record_failure(env, opts)
+        end
+
+        ::Warden::Manager.before_logout do |record, warden, opts|
+          Sessions::Adapters::Warden.record_logout(record, warden, opts)
+        end
+      end
+
+      # Test seam.
+      def installed?
+        !!@installed
+      end
+
+      def reset_installation!
+        @installed = false
+      end
+
+      # --- Hook 1: any fresh login (form, remember-me, OmniAuth, sign-up
+      # auto-login, post-password-reset) ----------------------------------------
+
+      def record_login(record, warden, opts)
+        Sessions.safely("warden.login") do
+          scope = opts[:scope]
+          # Guard set lifted from Devise's own hooks. The `store: false`
+          # check is CRITICAL: token/HTTP-Basic strategies fire this hook on
+          # EVERY request with store: false — without it we'd mint a session
+          # row per API call.
+          next unless warden.authenticated?(scope)
+          next if opts[:store] == false
+          next if warden.request.env[SKIP_ENV_KEY]
+          next if record.respond_to?(:sessions_skip?) && record.sessions_skip?
+          # Reauthentication (sudo-style confirms) re-runs sign_in
+          # MID-SESSION — devise-passkeys' `reauthenticate` calls
+          # `sign_in(..., event: :passkey_reauthentication)` (see its
+          # controllers/reauthentication_controller_concern.rb), which fires
+          # after_set_user like any login. That's the same person proving
+          # presence on an already-tracked session, not a new device:
+          # minting a row here would orphan the live one mid-request.
+          next if opts[:event].to_s.match?(/reauth/i)
+
+          if opts[:sessions_skip]
+            warden.session(scope)[SKIP_SESSION_KEY] = true
+            next
+          end
+
+          next unless row_accepts?(record)
+
+          create_row_for(record, warden, scope)
+        end
+      end
+
+      def create_row_for(record, warden, scope, suppress_login_event: false)
+        token = Sessions.generate_token
+        request = warden.request
+
+        row = Sessions.session_model.new(
+          user: record,
+          scope: scope.to_s,
+          ip_address: Sessions::IpAddress.resolve(request),
+          user_agent: request.user_agent,
+          token_digest: Sessions.token_digest(token)
+        )
+        row.sessions_suppress_login_event = suppress_login_event
+        Sessions.with_request(request) { row.save! }
+
+        warden.session(scope)[SESSION_KEY] = [row.id, token]
+        row
+      end
+
+      # --- Hook 2: per-request resume — validate, expire, touch ---------------
+
+      def validate_session(record, warden, opts)
+        scope = opts[:scope]
+        return if opts[:store] == false
+        return if warden.request.env[SKIP_ENV_KEY]
+        return if record.respond_to?(:sessions_skip?) && record.sessions_skip?
+
+        data = Sessions.safely("warden.fetch") do
+          session_data = warden.session(scope)
+          next :skip if session_data[SKIP_SESSION_KEY]
+
+          session_data[SESSION_KEY]
+        end
+        return if data == :skip
+
+        if data.nil?
+          adopt_preexisting_session(record, warden, scope)
+          return
+        end
+
+        # The lookup is NOT wrapped in `safely`: an ERRORED lookup and a
+        # MISSING row must be distinguishable. A row that's genuinely gone
+        # (or a token that doesn't match) means revocation → kick. A raised
+        # lookup — the sessions table unreachable, a timeout, a migration
+        # mid-deploy — means the TRACKING layer is down, and tracking must
+        # never break authentication: fail OPEN, let the request through
+        # untracked, try again next request.
+        begin
+          id, token = data
+          found = Sessions.session_model.find_by(id: id)
+          row = found if found&.sessions_token_matches?(token)
+        rescue StandardError => e
+          Sessions.warn("warden.fetch failed open: #{e.class}: #{e.message}")
+          return
+        end
+
+        if row.nil?
+          # Revoked (the row is gone) or tampered (digest mismatch): the
+          # proven session_limitable sequence — log the scope out and hand
+          # control to the failure app. NOT wrapped in `safely`: the throw
+          # is control flow, not an error.
+          kick!(warden, scope)
+        elsif Sessions.safely("warden.expired?") { row.sessions_expired? }
+          Sessions.safely("warden.expire") { row.revoke!(reason: :expired) }
+          kick!(warden, scope)
+        else
+          Sessions.safely("warden.touch") { row.touch_last_seen!(warden.request) }
+        end
+      end
+
+      # A session that predates the gem (no token in the warden session):
+      # adopt it so existing logged-in users appear on their devices page
+      # right after deploy — a row is minted with `auth_method: "unknown"`
+      # and NO login event (adoption isn't a login; the trail stays honest).
+      # Never kicks anyone: adoption failures degrade to "untracked".
+      def adopt_preexisting_session(record, warden, scope)
+        Sessions.safely("warden.adopt") do
+          next unless row_accepts?(record)
+
+          row = create_row_for(record, warden, scope, suppress_login_event: true)
+          row&.update_columns(auth_detail: { "adopted" => true })
+        end
+      end
+
+      # SCOPE-PRECISE teardown: only this scope's warden entries go (the
+      # serialized user key and our token stash) — an admin scope riding
+      # the same rack session, and unrelated host session data (carts,
+      # locale, return-to paths), survive a user-scope kick. Deleting the
+      # keys BEFORE logout matters: our before_logout hook then finds no
+      # token and records nothing (a kick is not a logout — the revocation
+      # event was already written by whoever destroyed the row).
+      def kick!(warden, scope)
+        warden.raw_session.delete("warden.user.#{scope}.key")
+        warden.raw_session.delete("warden.user.#{scope}.session")
+        warden.logout(scope)
+        throw :warden, scope: scope, message: THROW_MESSAGE
+      end
+
+      # --- Hook 3: failed logins ------------------------------------------------
+
+      def record_failure(env, opts)
+        Sessions.safely("warden.failure") do
+          next unless Sessions.config.track_failed_logins
+          next if env[SKIP_ENV_KEY]
+
+          request = ActionDispatch::Request.new(env)
+          # `before_failure` fires for EVERY warden failure, including plain
+          # unauthenticated page-hits and timeouts. A real credential
+          # failure is a POST carrying the scope's credentials hash
+          # (→ research/04 §3). The password key is never read.
+          next unless request.post?
+
+          # Devise passes scope: explicitly in auth_options; a bare
+          # `warden.authenticate!` throws opts WITHOUT it — fall back to the
+          # stack's default scope, like Warden itself does.
+          scope = opts[:scope] || warden_default_scope(env)
+          credentials = request.params[scope.to_s]
+          next unless credentials.is_a?(Hash)
+
+          identity = credentials.values_at("email", "login", "username", "phone").compact.first
+
+          Sessions::Event.record_failure(
+            request,
+            scope: scope,
+            identity: identity,
+            # Devise's message symbol, verbatim — under paranoid mode this
+            # stays :invalid; we never infer (or leak) account existence.
+            reason: opts[:message],
+            metadata: { attempted_path: opts[:attempted_path] }.compact
+          )
+        end
+      end
+
+      # --- Hook 4: logout ---------------------------------------------------------
+
+      # Fires once per scope (including forced logouts: timeout, lockout,
+      # our own revocation kick). If the row is already gone — revoked from
+      # another device — there's nothing to do; the `revoked` event was
+      # written by whoever destroyed it.
+      #
+      # CRITICAL: read the RAW session here, never `warden.session(scope)`.
+      # Warden's logout deletes `@users[scope]` BEFORE running before_logout
+      # callbacks (proxy.rb#logout), so Proxy#session's authenticated? check
+      # would re-deserialize the user → re-fire after_set_user → and when the
+      # logout came from a hook that logs out and throws (Devise's
+      # activatable on unconfirmed/locked accounts, timeoutable) that loops:
+      # activatable → logout → us → re-auth → activatable → … SystemStackError.
+      def record_logout(_record, warden, opts)
+        Sessions.safely("warden.logout") do
+          scope = opts[:scope]
+          data = warden.raw_session["warden.user.#{scope}.session"]&.dig(SESSION_KEY)
+          next unless data
+
+          id, token = data
+          row = Sessions.session_model.find_by(id: id)
+          next unless row&.sessions_token_matches?(token)
+
+          row.revocation_reason ||= :logout
+          row.destroy
+        end
+      end
+
+      def warden_default_scope(env)
+        warden = env["warden"]
+        warden.respond_to?(:config) ? warden.config.default_scope : nil
+      rescue StandardError
+        nil
+      end
+
+      # Multi-scope safety: with a plain (non-polymorphic) `user`
+      # association, rows can only hold the matching class — a second Devise
+      # scope on another model stays silently untracked (re-run the install
+      # generator with --polymorphic to track every scope).
+      def row_accepts?(record)
+        reflection = Sessions.session_model.reflect_on_association(:user)
+        return false unless reflection
+        return true if reflection.polymorphic?
+
+        record.is_a?(reflection.klass)
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/sessions/classifier.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Sessions
+  # Classifies HOW a session was started — password, OAuth (which provider),
+  # passkey, magic link… — from whatever signals the request carries at
+  # session-creation time. First match wins (→ docs/research/05-oauth.md):
+  #
+  #   1. An explicit `Sessions.tag(request, …)` (the universal escape hatch —
+  #      One Tap, passkeys, custom SSO flows can't self-identify).
+  #   2. `env["omniauth.auth"]` — any OmniAuth callback, on either auth stack.
+  #   3. The winning Warden strategy class (Devise password and remember-me
+  #      logins, devise-passwordless magic links, custom strategies via
+  #      `config.strategy_methods`).
+  #   4. `flash[:google_sign_in]` — Basecamp's google_sign_in gem hands the
+  #      id_token to the app through the flash.
+  #   5. A credentials POST (the omakase SessionsController#create shape and
+  #      any custom password form: a password param was just exchanged for a
+  #      session).
+  #   6. :unknown — never guess.
+  #
+  # Output: { method:, provider:, detail: } matching the auth_method /
+  # auth_provider / auth_detail columns. Methods are reserved for
+  # transport-distinct flows (Sign in with Apple is `oauth` + provider
+  # "apple", NOT its own method) so the taxonomy stays stable.
+  module Classifier
+    METHODS = %w[password oauth google_one_tap passkey magic_link otp sso token unknown].freeze
+
+    # The rack env key `Sessions.tag` writes.
+    TAG_ENV_KEY = "sessions.auth"
+
+    # Built-in Warden strategy → method mapping. Keys are matched as
+    # substrings of the strategy class name, so Devise's
+    # `Devise::Strategies::DatabaseAuthenticatable` and a host's custom
+    # subclass both classify. `config.strategy_methods` entries are
+    # consulted first and may override these.
+    #
+    # devise-two-factor is SINGLE-PHASE (password + OTP validated together
+    # in one strategy — its TwoFactorAuthenticatable SUBCLASSES Devise's
+    # DatabaseAuthenticatable and consumes params[scope]["otp_attempt"]
+    # before deferring to password validation, see devise-two-factor
+    # lib/devise_two_factor/strategies/two_factor_authenticatable.rb — so
+    # warden signs in once, at full auth). Its method is therefore
+    # :password — the second factor rides auth_detail (see from_warden).
+    #
+    # Passkey first-factor strategies classify as :passkey out of the box:
+    # devise-passkeys registers Devise::Strategies::PasskeyAuthenticatable
+    # (lib/devise/passkeys/strategy.rb) and its PasskeyReauthentication
+    # subclass; bare warden-webauthn registers Warden::WebAuthn::Strategy
+    # (lib/warden/webauthn/strategy.rb) — both names match by substring.
+    STRATEGY_METHODS = {
+      "DatabaseAuthenticatable" => :password,
+      "Rememberable" => :password,
+      "MagicLinkAuthenticatable" => :magic_link,
+      "TwoFactorAuthenticatable" => :password,
+      "TwoFactorBackupable" => :password,
+      "Passkey" => :passkey,
+      "WebAuthn" => :passkey
+    }.freeze
+
+    # OmniAuth strategy names normalized to recognizable providers
+    # ("google_oauth2" → "google"). Unlisted strategies pass through as-is.
+    PROVIDER_ALIASES = {
+      "google_oauth2" => "google",
+      "google_oauth2_hd" => "google",
+      "azure_activedirectory_v2" => "microsoft",
+      "microsoft_graph" => "microsoft"
+    }.freeze
+
+    module_function
+
+    # Never raises — classification is best-effort decoration on the login
+    # hot path; an exotic env degrades to :unknown.
+    def classify(request)
+      return blank if request.nil?
+
+      from_tag(request) ||
+        from_omniauth(request) ||
+        from_warden(request) ||
+        from_google_sign_in(request) ||
+        from_password_post(request) ||
+        blank
+    rescue StandardError => e
+      Sessions.warn("auth classification failed: #{e.class}: #{e.message}")
+      blank
+    end
+
+    def blank
+      { method: "unknown", provider: nil, detail: {} }
+    end
+
+    def from_tag(request)
+      tag = request.env[TAG_ENV_KEY]
+      return unless tag.is_a?(Hash)
+
+      {
+        method: normalize_method(tag[:method]),
+        provider: tag[:provider]&.to_s,
+        detail: (tag[:detail] || {}).to_h
+      }
+    end
+
+    def from_omniauth(request)
+      auth = request.env["omniauth.auth"]
+      return unless auth
+
+      detail = {}
+      detail["origin"] = request.env["omniauth.origin"] if request.env["omniauth.origin"]
+      # AuthHash is a Hashie::Mash; plain hashes from tests work too.
+      credentials = auth["credentials"] if auth.respond_to?(:[])
+      detail["scopes"] = credentials["scope"] if credentials.respond_to?(:[]) && credentials["scope"]
+      info = auth["info"] if auth.respond_to?(:[])
+      detail["email_verified"] = info["email_verified"] if info.respond_to?(:[]) && !info["email_verified"].nil?
+      extra = auth["extra"] if auth.respond_to?(:[])
+      id_info = extra["id_info"] if extra.respond_to?(:[])
+      detail["hd"] = id_info["hd"] if id_info.respond_to?(:[]) && id_info["hd"]
+
+      { method: "oauth", provider: normalize_provider(auth["provider"]), detail: detail }
+    end
+
+    def from_warden(request)
+      warden = request.env["warden"]
+      return unless warden.respond_to?(:winning_strategy)
+
+      strategy = warden.winning_strategy
+      return unless strategy
+
+      strategy_name = strategy.class.name.to_s
+      method = method_for_strategy(strategy_name)
+      return unless method
+
+      detail = {}
+      detail["remembered"] = true if strategy_name.include?("Rememberable")
+
+      # devise-two-factor: a backup-code win IS a second factor; the main
+      # strategy also serves users without 2FA, so the OTP only counts when
+      # an otp_attempt actually rode the request.
+      if strategy_name.include?("TwoFactorBackupable")
+        detail["second_factor"] = "backup_code"
+      elsif strategy_name.include?("TwoFactorAuthenticatable") && otp_attempted?(request)
+        detail["second_factor"] = "totp"
+      end
+
+      { method: method.to_s, provider: nil, detail: detail }
+    end
+
+    def otp_attempted?(request)
+      params = request.params
+      return true if params["otp_attempt"].present?
+
+      params.each_value.any? { |value| value.is_a?(Hash) && value["otp_attempt"].present? }
+    rescue StandardError
+      false
+    end
+
+    def method_for_strategy(strategy_name)
+      Sessions.config.strategy_methods.merge(STRATEGY_METHODS).each do |substring, method|
+        return method if strategy_name.include?(substring)
+      end
+      nil
+    end
+
+    def from_google_sign_in(request)
+      flash = request.respond_to?(:flash) ? request.flash : nil
+      return unless flash && flash["google_sign_in"].present?
+
+      { method: "oauth", provider: "google", detail: {} }
+    rescue StandardError
+      # Requests outside the Flash middleware (rack tests, API stacks) raise
+      # when the flash hash is unavailable — there's just no signal here.
+      nil
+    end
+
+    # A POST that exchanged a password for a session IS a password login —
+    # covers the omakase SessionsController and hand-rolled password forms.
+    def from_password_post(request)
+      return unless request.respond_to?(:post?) && request.post?
+
+      params = request.params
+      return unless params.is_a?(Hash) || params.respond_to?(:[])
+      return unless password_param?(params)
+
+      { method: "password", provider: nil, detail: {} }
+    rescue StandardError
+      nil
+    end
+
+    def password_param?(params)
+      return true if params["password"].present?
+
+      # Devise nests credentials under the scope: user[password]
+      params.each_value.any? { |value| value.is_a?(Hash) && value["password"].present? }
+    rescue StandardError
+      false
+    end
+
+    def normalize_method(method)
+      name = method.to_s
+      METHODS.include?(name) ? name : name.presence || "unknown"
+    end
+
+    def normalize_provider(provider)
+      return nil if provider.nil?
+
+      name = provider.to_s
+      PROVIDER_ALIASES.fetch(name, name)
+    end
+  end
+end