supabase-rails 0.1.0 → 1.0.0

data/lib/supabase/rails/authentication.rb

@@ -0,0 +1,744 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "jwt"
+require "securerandom"
+require "uri"
+
+require_relative "context"
+require_relative "errors"
+require_relative "logging"
+require_relative "session_store"
+require_relative "user"
+require_relative "web/auth_client_factory"
+require_relative "web/auth_error_mapper"
+require_relative "web/redirect_validator"
+
+module Supabase
+  module Rails
+    # Rails-8-shape Authentication concern (FR-W5, US-010).
+    #
+    # `include Supabase::Rails::Authentication` gives a controller the same
+    # surface as Rails 8's built-in `bin/rails g authentication` output:
+    #
+    #   * `before_action :require_authentication` installed on inclusion
+    #   * `helper_method :authenticated?` registered on inclusion
+    #   * `allow_unauthenticated_access(only: ..., except: ...)` class macro
+    #     that delegates to `skip_before_action :require_authentication`
+    #   * Instance methods `authenticated?`, `require_authentication`,
+    #     `start_new_session_for(session)`, `terminate_session(scope:)`,
+    #     `authenticate_with_supabase(email:, password:)`, plus the
+    #     override hooks `request_authentication`, `after_authentication_url`,
+    #     `store_location_for_redirect`, `stored_location_for_redirect`.
+    #
+    # Backing implementation talks to Supabase Auth via the per-request
+    # `Supabase::Auth::Client` ({Web::AuthClientFactory}) and the encrypted
+    # session cookie ({SessionStore}). `Current.user` and `Current.session`
+    # are populated on resume / `start_new_session_for` and cleared on
+    # `terminate_session`. The host app is expected to provide `Current`
+    # (`app/models/current.rb` from the Rails 8 generator).
+    #
+    # `:api` mode: the concern still mounts so a single controller class can
+    # serve both surfaces, but `start_new_session_for` raises (cookies don't
+    # apply), `require_authentication` 401s instead of redirecting, and
+    # `terminate_session` is a local no-op.
+    module Authentication
+      extend ActiveSupport::Concern
+
+      included do
+        before_action :require_authentication
+        before_action :populate_current_attributes
+        helper_method :authenticated?
+
+        helper_method :current_user if Supabase::Rails::Authentication.expose_current_user?
+      end
+
+      class_methods do
+        # Rails-8 class macro:
+        #
+        #   class SessionsController < ApplicationController
+        #     allow_unauthenticated_access only: %i[new create]
+        #   end
+        def allow_unauthenticated_access(**options)
+          skip_before_action :require_authentication, **options
+        end
+      end
+
+      # Whether `current_user` should be exposed as a `helper_method` on the
+      # including controller. Resolved at include time from the Railtie config:
+      #
+      #   config.supabase.expose_current_user = true | false | nil
+      #
+      # When `nil` (the default), derives from `config.supabase.mode`:
+      # `:web` → true (Devise muscle memory in views), `:api` → false (avoid
+      # clashing with apps that already define `current_user` for API
+      # consumers). Returns `false` when Rails is not loaded so the gem can
+      # still be included in non-Rails specs.
+      def self.expose_current_user?
+        cfg = railtie_config
+        return false if cfg.nil?
+
+        explicit = cfg.respond_to?(:expose_current_user) ? cfg.expose_current_user : nil
+        return !!explicit unless explicit.nil?
+
+        mode = cfg.respond_to?(:mode) ? cfg.mode : :api
+        mode == :web
+      end
+
+      def self.railtie_config
+        return nil unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+
+        ::Rails.application.config.supabase
+      rescue StandardError
+        nil
+      end
+
+      # Masks the local part of an email address for safe logging.
+      # `alice@example.com` → `a***@example.com`.
+      # Returns a placeholder when the input is nil/empty/malformed so the
+      # raw value never leaks to the log line.
+      def self.redact_email(email)
+        return "<missing>" if email.nil?
+
+        str = email.to_s
+        return "<blank>" if str.empty?
+
+        local, _, domain = str.rpartition("@")
+        return "<malformed>" if local.empty? || domain.empty?
+
+        "#{local[0]}***@#{domain}"
+      end
+
+      # --- Rails-8 parity surface ---
+
+      def authenticated?
+        ::Current.user.present?
+      end
+
+      # Devise muscle-memory alias for `Current.user`. Always defined as an
+      # instance method; only exposed to views via `helper_method` when
+      # `config.supabase.expose_current_user` resolves to true (default in
+      # `:web` mode). When the host app defines its own `current_user` on a
+      # parent controller, Ruby's method lookup picks the host's first.
+      def current_user
+        ::Current.user
+      end
+
+      def require_authentication
+        resume_session || request_authentication
+      end
+
+      # Persists a Supabase session in the encrypted cookie and populates
+      # `Current.user` / `Current.session`. In `:api` mode this raises a
+      # {ConfigError} because cookies don't apply — clients send JWTs via
+      # the `Authorization: Bearer` header.
+      def start_new_session_for(supabase_session)
+        if supabase_mode == :api
+          raise Supabase::Rails::ConfigError.api_mode_cookie_unsupported
+        end
+
+        Supabase::Rails::SessionStore.new(supabase_session_config)
+                                     .write(request, supabase_session)
+
+        ::Current.user = build_current_user(supabase_session)
+        ::Current.session = supabase_session
+        supabase_session
+      end
+
+      # Best-effort upstream sign-out, then clears the encrypted cookie and
+      # `Current`. `auth.sign_out` is rescued because the local clear is the
+      # source of truth — a failed upstream call still produces a signed-out
+      # user locally. In `:api` mode this is a local no-op (no cookie to
+      # clear; clients drop the JWT on their side).
+      def terminate_session(scope: :local)
+        return if supabase_mode == :api
+
+        attempt_upstream_sign_out(scope) if ::Current.session
+      ensure
+        unless supabase_mode == :api
+          Supabase::Rails::SessionStore.new(supabase_session_config).clear(request)
+          ::Current.user = nil
+          ::Current.session = nil
+        end
+      end
+
+      # Mirrors Rails 8's `User.authenticate_by(email:, password:)`:
+      # returns a Supabase session on success, `nil` on a 4xx authentication
+      # failure (invalid credentials, weak password, etc), and raises only
+      # on upstream 5xx so the controller can surface a "try again" message.
+      def authenticate_with_supabase(email:, password:)
+        client = Supabase::Rails::Web::AuthClientFactory.build(request)
+        client.sign_in_with_password(email: email, password: password).session
+      rescue ::Supabase::Auth::Errors::AuthError => e
+        mapped = Supabase::Rails::Web::AuthErrorMapper.translate(e)
+        raise mapped if mapped.status.to_i >= 500
+
+        Supabase::Rails::Logging.log(
+          :warn,
+          "[supabase.rails.sign_in_failure] code=#{mapped.code} email=#{Supabase::Rails::Authentication.redact_email(email)}"
+        )
+        nil
+      end
+
+      # --- FR-W7 low-level helpers (US-012) ---
+      #
+      # `supabase_*` helpers return a {Result} wrapping either the upstream
+      # value (session struct, auth response, etc.) or a {AuthError}. Lets
+      # controllers compose custom flows without subclassing the gem's base
+      # controllers. Each helper:
+      #
+      #   * builds a per-request {Web::AuthClientFactory} client
+      #   * dispatches the upstream call
+      #   * on success calls `start_new_session_for` when a session is returned
+      #   * routes any `Supabase::Auth::Errors::AuthError` through
+      #     {Web::AuthErrorMapper} so the failure carries a stable
+      #     `code` + `status`
+
+      # Sign-in with email/password. Returns `Result.success(session)` on
+      # success (and calls `start_new_session_for(session)` internally so
+      # `Current.user` / `Current.session` are populated and the encrypted
+      # cookie is written). On a 4xx upstream failure returns
+      # `Result.failure(AuthError.invalid_credentials)` — a generic
+      # "Invalid credentials" message regardless of whether email or
+      # password was the bad field (prevents user enumeration). On a 5xx
+      # upstream failure returns `Result.failure` with the upstream-mapped
+      # error (status 503, code `AUTH_UPSTREAM_ERROR`).
+      def supabase_sign_in_with_password(email:, password:)
+        client = supabase_auth_client
+        response = client.sign_in_with_password(email: email, password: password)
+        session = response.session
+        start_new_session_for(session) if session
+        Supabase::Rails::Result.success(session)
+      rescue ::Supabase::Auth::Errors::AuthError => e
+        failure = translate_sign_in_error(e)
+        Supabase::Rails::Logging.log(
+          :warn,
+          "[supabase.rails.sign_in_failure] code=#{failure.code} email=#{Supabase::Rails::Authentication.redact_email(email)}"
+        )
+        Supabase::Rails::Result.failure(failure)
+      end
+
+      # Sign-up with email/password. Returns `Result.success(response)` on
+      # success — value is the upstream `Supabase::Auth::Types::AuthResponse`
+      # (`.user` always present, `.session` present when auto-sign-in is
+      # enabled, `nil` when email confirmation is pending). When a session
+      # is present `start_new_session_for(session)` is called internally so
+      # the cookie + `Current` are written. `data:` populates user metadata
+      # (`raw_user_meta_data`) and `redirect_to:` sets the post-confirmation
+      # redirect URL. Errors flow through {Web::AuthErrorMapper} so callers
+      # can branch on stable codes — notably `WEAK_PASSWORD` (422) is
+      # preserved so the host can render a specific UI; other 4xx errors
+      # are masked to `INVALID_CREDENTIALS` (401), and 5xx surfaces as
+      # `AUTH_UPSTREAM_ERROR` (503).
+      def supabase_sign_up(email:, password:, data: nil, redirect_to: nil)
+        client = supabase_auth_client
+        options = {}
+        options[:data] = data if data
+        options[:redirect_to] = redirect_to if redirect_to
+
+        credentials = { email: email, password: password }
+        credentials[:options] = options unless options.empty?
+
+        response = client.sign_up(credentials)
+        session = response.respond_to?(:session) ? response.session : nil
+        start_new_session_for(session) if session
+        Supabase::Rails::Result.success(response)
+      rescue ::Supabase::Auth::Errors::AuthError => e
+        Supabase::Rails::Result.failure(translate_sign_up_error(e))
+      end
+
+      # --- US-013 OTP / magic-link helpers (FR-W7) ---
+      #
+      # Three helpers cover the passwordless / second-factor flows:
+      #
+      #   * `supabase_sign_in_with_otp` — kicks off the delivery (magic link
+      #     for email, SMS code for phone). No session is created yet; returns
+      #     `Result.success(AuthOtpResponse)` so the caller can render a
+      #     "Check your inbox / Enter the code" page.
+      #   * `supabase_verify_otp` — exchanges the code/token for a session,
+      #     calls `start_new_session_for` on success.
+      #   * `supabase_resend` — re-triggers the delivery for a given
+      #     identifier + type. Returns `Result.success(nil)` (the upstream
+      #     `AuthOtpResponse` carries no data the host needs).
+
+      # Send an OTP / magic link. Provide either `email:` or `phone:`.
+      # `**opts` is forwarded as the upstream `:options` hash and accepts the
+      # full supabase-rb surface: `email_redirect_to:`, `should_create_user:`,
+      # `data:`, `channel:` ("sms" | "whatsapp"), `captcha_token:`.
+      # Returns `Result.success(AuthOtpResponse)` (delivery is pending —
+      # no session is established yet).
+      def supabase_sign_in_with_otp(email: nil, phone: nil, **opts)
+        client = supabase_auth_client
+        credentials = {}
+        credentials[:email] = email if email
+        credentials[:phone] = phone if phone
+        credentials[:options] = opts unless opts.empty?
+
+        response = client.sign_in_with_otp(credentials)
+        Supabase::Rails::Result.success(response)
+      rescue ::Supabase::Auth::Errors::AuthError => e
+        Supabase::Rails::Result.failure(Supabase::Rails::Web::AuthErrorMapper.translate(e))
+      end
+
+      # Verify an OTP token (`token:`) of a given `type:` (e.g. `"email"`,
+      # `"sms"`, `"magiclink"`, `"recovery"`, `"invite"`, `"signup"`).
+      # Returns `Result.success(session)` and calls `start_new_session_for`
+      # internally on success so `Current.user` / `Current.session` are
+      # populated and the encrypted cookie is written.
+      def supabase_verify_otp(token:, type:, email: nil, phone: nil)
+        client = supabase_auth_client
+        params = { token: token, type: type }
+        params[:email] = email if email
+        params[:phone] = phone if phone
+
+        response = client.verify_otp(params)
+        session = response.respond_to?(:session) ? response.session : nil
+        start_new_session_for(session) if session
+        Supabase::Rails::Result.success(session)
+      rescue ::Supabase::Auth::Errors::AuthError => e
+        Supabase::Rails::Result.failure(Supabase::Rails::Web::AuthErrorMapper.translate(e))
+      end
+
+      # Resend an OTP / magic link for the given identifier + `type:`.
+      # Returns `Result.success(nil)` — the upstream `AuthOtpResponse`
+      # carries no actionable data; the host typically just re-renders the
+      # "Check your inbox" page.
+      def supabase_resend(type:, email: nil, phone: nil)
+        client = supabase_auth_client
+        credentials = { type: type }
+        credentials[:email] = email if email
+        credentials[:phone] = phone if phone
+
+        client.resend(credentials)
+        Supabase::Rails::Result.success(nil)
+      rescue ::Supabase::Auth::Errors::AuthError => e
+        Supabase::Rails::Result.failure(Supabase::Rails::Web::AuthErrorMapper.translate(e))
+      end
+
+      # --- US-014 OAuth helpers with PKCE (FR-W7) ---
+      #
+      # OAuth in PKCE mode is a two-leg flow split across two HTTP requests:
+      #
+      #   1. The host's "start" controller calls `supabase_sign_in_with_oauth`
+      #      and redirects the browser to the returned URL. Internally the
+      #      helper generates a random `state`, binds the per-request
+      #      `RequestScopedStorage` to it, and lets supabase-rb write the
+      #      PKCE verifier — which our storage mirrors into a signed cookie
+      #      `sb-oauth-state-<state>` with a 10-minute TTL.
+      #   2. The OAuth provider redirects back to the app's callback URL
+      #      with `code=<auth_code>` and `state=<state>` query params. The
+      #      callback controller calls `supabase_exchange_code_for_session`
+      #      with both. The helper rebinds storage to the callback `state`
+      #      so the verifier lookup falls back to the signed cookie, then
+      #      exchanges the code for a session and calls
+      #      `start_new_session_for` on success.
+      #
+      # Binding the verifier cookie to the `state` value gives us two
+      # properties for free: concurrent OAuth flows in the same browser
+      # (different tabs) don't clobber each other (each state = unique
+      # cookie); and a callback that returns a `state` we never issued
+      # silently misses the cookie lookup → `PKCE_ERROR` (instead of a
+      # confusing upstream 400 from supabase-rb).
+
+      # Begin an OAuth sign-in. Returns `Result.success(<authorize_url>)`
+      # on success — the controller is expected to `redirect_to result.value`.
+      # The PKCE verifier is stashed in a signed cookie keyed by a freshly
+      # generated `state`; that same `state` is appended as a query param
+      # to the `redirect_to:` URL so the OAuth provider echoes it back on
+      # the callback, where {#supabase_exchange_code_for_session} can pick
+      # it up. `scopes:` is forwarded verbatim to the OAuth provider via
+      # supabase-rb (space-separated string per the OAuth 2.0 spec).
+      def supabase_sign_in_with_oauth(provider:, redirect_to:, scopes: nil)
+        Supabase::Rails::Web::RedirectValidator.validate(
+          redirect_to,
+          allowed_origins: supabase_allowed_redirect_origins
+        )
+
+        state = SecureRandom.urlsafe_base64(32)
+        client = supabase_auth_client
+        bind_oauth_state(client, state)
+
+        options = { redirect_to: append_state_to_redirect(redirect_to, state) }
+        options[:scopes] = scopes if scopes
+
+        response = client.sign_in_with_oauth({ provider: provider, options: options })
+        Supabase::Rails::Result.success(response.url)
+      rescue Supabase::Rails::AuthError => e
+        Supabase::Rails::Result.failure(e)
+      rescue ::Supabase::Auth::Errors::AuthError => e
+        Supabase::Rails::Result.failure(Supabase::Rails::Web::AuthErrorMapper.translate(e))
+      end
+
+      # Complete an OAuth sign-in by exchanging the auth code for a session.
+      # `code:` is the OAuth code from the callback URL; `state:` is the
+      # value the provider echoed back from the start leg — used to find
+      # the matching `sb-oauth-state-<state>` signed cookie that holds the
+      # PKCE verifier. When the cookie is missing or `state` doesn't match
+      # any issued state, returns `Result.failure(AuthError.pkce_missing_verifier)`
+      # (`code: PKCE_ERROR`, `status: 400`) without bothering the upstream.
+      # On success, calls `start_new_session_for(session)` internally so
+      # `Current.user` / `Current.session` are populated and the encrypted
+      # cookie is written.
+      def supabase_exchange_code_for_session(code:, state: nil, redirect_to: nil)
+        if redirect_to
+          Supabase::Rails::Web::RedirectValidator.validate(
+            redirect_to,
+            allowed_origins: supabase_allowed_redirect_origins
+          )
+        end
+
+        client = supabase_auth_client
+        bind_oauth_state(client, state) if state
+
+        unless pkce_verifier_present?(client)
+          return Supabase::Rails::Result.failure(
+            Supabase::Rails::AuthError.pkce_missing_verifier
+          )
+        end
+
+        response = client.exchange_code_for_session({ auth_code: code })
+        session = response.respond_to?(:session) ? response.session : nil
+        start_new_session_for(session) if session
+        Supabase::Rails::Result.success(session)
+      rescue Supabase::Rails::AuthError => e
+        Supabase::Rails::Result.failure(e)
+      rescue ::Supabase::Auth::Errors::AuthError => e
+        Supabase::Rails::Result.failure(Supabase::Rails::Web::AuthErrorMapper.translate(e))
+      end
+
+      # --- US-016 password reset + user update helpers (FR-W7) ---
+
+      # Trigger a password-reset email. Returns `Result.success(nil)` —
+      # the upstream call's response carries no actionable data; the host
+      # typically just renders a "Check your inbox" page. When `redirect_to:`
+      # is supplied (the deep-link the recovery email points the user back
+      # to), it's validated against `config.supabase.allowed_redirect_origins`
+      # via {Web::RedirectValidator} BEFORE the upstream call so an
+      # attacker-controlled URL short-circuits to
+      # `Result.failure(AuthError(INVALID_REDIRECT))` without bothering
+      # Supabase Auth. Upstream errors flow through {Web::AuthErrorMapper}.
+      def supabase_reset_password(email:, redirect_to: nil)
+        if redirect_to
+          Supabase::Rails::Web::RedirectValidator.validate(
+            redirect_to,
+            allowed_origins: supabase_allowed_redirect_origins
+          )
+        end
+
+        options = {}
+        options[:redirect_to] = redirect_to if redirect_to
+
+        client = supabase_auth_client
+        client.reset_password_for_email(email, options)
+        Supabase::Rails::Result.success(nil)
+      rescue Supabase::Rails::AuthError => e
+        Supabase::Rails::Result.failure(e)
+      rescue ::Supabase::Auth::Errors::AuthError => e
+        Supabase::Rails::Result.failure(Supabase::Rails::Web::AuthErrorMapper.translate(e))
+      end
+
+      # Update the currently-authenticated user's attributes (e.g. `email:`,
+      # `password:`, `data:` for `raw_user_meta_data`). Returns
+      # `Result.success(user)` on success where `user` is the upstream
+      # `Supabase::Auth::Types::User`. Requires an authenticated session —
+      # when the encrypted session cookie is missing or carries no access
+      # token, fast-fails with
+      # `Result.failure(AuthError.session_missing)` (`code: SESSION_MISSING`,
+      # `status: 401`) without calling the upstream. The current session is
+      # seeded into the per-request auth client's storage so supabase-rb's
+      # internal `get_session` resolves (its `@storage` is empty per-request
+      # in `:web` mode by design — FR-W6). Other upstream errors flow
+      # through {Web::AuthErrorMapper}.
+      def supabase_update_user(attributes)
+        session_hash = Supabase::Rails::SessionStore.new(supabase_session_config).read(request)
+        if session_hash.nil? || access_token_of(session_hash).to_s.empty?
+          return Supabase::Rails::Result.failure(Supabase::Rails::AuthError.session_missing)
+        end
+
+        client = supabase_auth_client
+        seed_storage_with_session(client, session_hash)
+
+        response = client.update_user(attributes)
+        user = response.respond_to?(:user) ? response.user : response
+        Supabase::Rails::Result.success(user)
+      rescue ::Supabase::Auth::Errors::AuthError => e
+        Supabase::Rails::Result.failure(Supabase::Rails::Web::AuthErrorMapper.translate(e))
+      end
+
+      # --- Override hooks (host apps customize by redefining) ---
+
+      def request_authentication
+        if supabase_mode == :api
+          head :unauthorized
+        else
+          store_location_for_redirect
+          redirect_to new_session_path
+        end
+      end
+
+      def after_authentication_url
+        stored_location_for_redirect || root_url
+      end
+
+      def store_location_for_redirect
+        return unless request.get?
+
+        session[:return_to_after_authenticating] = request.url
+      end
+
+      def stored_location_for_redirect
+        session.delete(:return_to_after_authenticating)
+      end
+
+      private
+
+      # Runs after `:require_authentication` (FR-W15). Populates
+      # `Current.user` and `Current.session` from `supabase_context` so that
+      # views can read `Current.user.email` directly — including on actions
+      # that opted out via `allow_unauthenticated_access` (where
+      # `:require_authentication` was skipped). Uses `||=` so an explicit
+      # assignment by `start_new_session_for` earlier in the request stays.
+      def populate_current_attributes
+        ctx = supabase_context
+        return unless ctx
+
+        ::Current.user = current_user_from_context(ctx) if ::Current.user.nil?
+
+        if ::Current.session.nil? && ctx.respond_to?(:jwt_claims)
+          ::Current.session = ctx.jwt_claims
+        end
+      end
+
+      def current_user_from_context(ctx)
+        name = supabase_user_model
+
+        if name && !name.to_s.empty?
+          claims = ctx.respond_to?(:jwt_claims) ? ctx.jwt_claims : nil
+          return nil if claims.nil? || (claims.respond_to?(:empty?) && claims.empty?)
+
+          model = name.is_a?(Class) ? name : Object.const_get(name.to_s)
+          model.from_supabase(claims)
+        else
+          ctx.respond_to?(:current_user) ? ctx.current_user : nil
+        end
+      end
+
+      def supabase_auth_client
+        Supabase::Rails::Web::AuthClientFactory.build(request)
+      end
+
+      # Seeds the per-request auth client's storage with the current
+      # session hash from the encrypted cookie so supabase-rb's internal
+      # `get_session` (called from `update_user` and other session-bound
+      # endpoints) returns the session. The auth client's `@storage` is a
+      # fresh `Web::RequestScopedStorage` per request (FR-W6) — empty by
+      # design — so without this seeding the upstream raises
+      # `AuthSessionMissing` even when the cookie is present and valid.
+      # supabase-rb's `_get_valid_session` accepts the Hash directly (no
+      # JSON encoding needed); see supabase-rb's `auth/client.rb`.
+      def seed_storage_with_session(client, session_hash)
+        storage = client.instance_variable_get(:@storage)
+        storage_key = client.instance_variable_get(:@storage_key)
+        return unless storage && storage_key
+
+        storage.set_item(storage_key, session_hash)
+      end
+
+      # Reaches into the auth client's `@storage` to set `oauth_state`.
+      # supabase-rb doesn't expose `storage` via `attr_reader` (US-005),
+      # but the `RequestScopedStorage` we injected at construction has a
+      # public `oauth_state=` accessor that the PKCE cookie-mirroring path
+      # reads on every `set_item`/`get_item`. Binding before the upstream
+      # call is what activates the per-state cookie isolation.
+      def bind_oauth_state(client, state)
+        storage = client.instance_variable_get(:@storage)
+        storage.oauth_state = state if storage.respond_to?(:oauth_state=)
+      end
+
+      # True if the per-request storage (or its signed-cookie fallback)
+      # holds a PKCE verifier under the auth client's storage_key. The
+      # `RequestScopedStorage#get_item` call returns the in-memory value
+      # when present, and otherwise falls back to the signed cookie when
+      # `oauth_state` is set. Used by {#supabase_exchange_code_for_session}
+      # to fast-fail with `PKCE_ERROR` instead of forwarding a nil
+      # `code_verifier` to the upstream.
+      def pkce_verifier_present?(client)
+        storage = client.instance_variable_get(:@storage)
+        return false if storage.nil?
+
+        storage_key = client.instance_variable_get(:@storage_key)
+        verifier = storage.get_item("#{storage_key}-code-verifier")
+        !verifier.nil? && !verifier.to_s.empty?
+      end
+
+      # Appends (or replaces) a `state=<state>` query param on the
+      # caller-supplied `redirect_to` URL so the OAuth provider echoes it
+      # back to the callback. Falls back to the original string on a
+      # malformed URI so we never raise out of `supabase_sign_in_with_oauth`
+      # — host apps that pass a bad `redirect_to` get a useful upstream
+      # error rather than a `URI::InvalidURIError`.
+      def append_state_to_redirect(redirect_to, state)
+        return redirect_to if redirect_to.nil?
+
+        uri = URI.parse(redirect_to.to_s)
+        query = URI.decode_www_form(uri.query.to_s).reject { |k, _| k == "state" }
+        query << ["state", state]
+        uri.query = URI.encode_www_form(query)
+        uri.to_s
+      rescue URI::InvalidURIError
+        redirect_to
+      end
+
+      # Sign-in error policy (US-012 AC-4): all 4xx upstream errors are
+      # masked to the generic `AuthError.invalid_credentials` ("Invalid
+      # credentials", 401) so the response leaks no information about
+      # which field was wrong. 5xx surface verbatim through the mapper so
+      # the host can show a "try again" message.
+      def translate_sign_in_error(err)
+        mapped = Supabase::Rails::Web::AuthErrorMapper.translate(err)
+        return mapped if mapped.status.to_i >= 500
+
+        Supabase::Rails::AuthError.invalid_credentials
+      end
+
+      # Sign-up error policy (US-012 AC-3): preserves the mapper's
+      # specific code/status for failures the user can act on
+      # (`WEAK_PASSWORD`, `PKCE_ERROR`, `SESSION_MISSING`, weak-password
+      # 422, 5xx infra). Generic 4xx credential failures (bad email,
+      # already-registered conflicts surfacing as 400/401) are masked to
+      # `INVALID_CREDENTIALS` for parity with the sign-in helper.
+      def translate_sign_up_error(err)
+        mapped = Supabase::Rails::Web::AuthErrorMapper.translate(err)
+        return mapped if mapped.status.to_i >= 500
+
+        case mapped.code
+        when Supabase::Rails::AuthError::WEAK_PASSWORD,
+             Supabase::Rails::AuthError::PKCE_ERROR,
+             Supabase::Rails::AuthError::SESSION_MISSING
+          mapped
+        else
+          Supabase::Rails::AuthError.invalid_credentials
+        end
+      end
+
+      # Resume the request's session by populating `Current.user` from the
+      # middleware-installed context. When `config.supabase.user_model` is
+      # set (FR-W14 shadow user), the context's `current_user` is nil by
+      # design — {Context.build_context_result} skips the value-object build
+      # so the host's AR record is the single source of truth. In that mode
+      # we re-derive the user per-request via `<Model>.from_supabase(claims)`
+      # — a cheap by-PK lookup that returns the same AR row a `belongs_to
+      # :user` query would resolve. When `user_model` is unset, we fall back
+      # to `ctx.current_user` (the `Supabase::Rails::User` value object).
+      def resume_session
+        ctx = supabase_context
+        return false if ctx.nil?
+
+        user = current_user_from_context(ctx)
+        return false if user.nil?
+
+        ::Current.user = user
+        true
+      end
+
+      def attempt_upstream_sign_out(scope)
+        return unless supabase_context
+        return unless supabase_context.respond_to?(:supabase)
+
+        client = supabase_context.supabase
+        return if client.nil?
+
+        client.auth.sign_out(scope: scope)
+      rescue ::Supabase::Auth::Errors::AuthError
+        # Best-effort — cookie clear is the source of truth.
+      end
+
+      def supabase_context
+        request.env[Supabase::Rails::CONTEXT_KEY]
+      end
+
+      def supabase_mode
+        cfg = supabase_railtie_config
+        cfg && cfg.respond_to?(:mode) ? (cfg.mode || :api) : :api
+      end
+
+      def supabase_session_config
+        cfg = supabase_railtie_config
+        cfg && cfg.respond_to?(:session) ? cfg.session : nil
+      end
+
+      def supabase_user_model
+        cfg = supabase_railtie_config
+        cfg && cfg.respond_to?(:user_model) ? cfg.user_model : nil
+      end
+
+      # Resolves the OAuth redirect allowlist (FR-W11). Reads
+      # `config.supabase.allowed_redirect_origins` and falls back to
+      # `[request.host]` (same-origin only) when the config is empty so a
+      # host that hasn't configured the list still gets a safe default.
+      # The fallback derives the scheme from the request so `:web` apps on
+      # plain HTTP in development work too.
+      def supabase_allowed_redirect_origins
+        cfg = supabase_railtie_config
+        configured = cfg.respond_to?(:allowed_redirect_origins) ? cfg.allowed_redirect_origins : nil
+        return configured if configured.is_a?(Array) && !configured.empty?
+
+        host = request.respond_to?(:host) ? request.host : nil
+        return [] if host.nil? || host.to_s.empty?
+
+        scheme = request.respond_to?(:scheme) ? request.scheme : "https"
+        port = request.respond_to?(:port) ? request.port : nil
+        origin = "#{scheme}://#{host}"
+        origin = "#{origin}:#{port}" if port && !default_port_for?(scheme, port)
+        [origin]
+      end
+
+      def default_port_for?(scheme, port)
+        case scheme.to_s.downcase
+        when "https" then port.to_i == 443
+        when "http"  then port.to_i == 80
+        else false
+        end
+      end
+
+      def supabase_railtie_config
+        return nil unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+
+        ::Rails.application.config.supabase
+      rescue StandardError
+        nil
+      end
+
+      def build_current_user(supabase_session)
+        claims = jwt_claims_from(supabase_session)
+        name = supabase_user_model
+
+        if name && !name.to_s.empty?
+          model = name.is_a?(Class) ? name : Object.const_get(name.to_s)
+          model.from_supabase(claims)
+        else
+          Supabase::Rails::User.from_claims(claims)
+        end
+      end
+
+      def jwt_claims_from(supabase_session)
+        token = access_token_of(supabase_session)
+        return {} if token.nil? || token.to_s.empty?
+
+        payload, _header = ::JWT.decode(token, nil, false)
+        payload.is_a?(Hash) ? payload : {}
+      rescue StandardError
+        {}
+      end
+
+      def access_token_of(supabase_session)
+        if supabase_session.is_a?(Hash)
+          return supabase_session["access_token"] || supabase_session[:access_token]
+        end
+        return supabase_session.access_token if supabase_session.respond_to?(:access_token)
+
+        nil
+      end
+    end
+  end
+end