supabase-rails 0.1.0 → 1.0.0

data/lib/supabase/rails/web/auth_client_factory.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "../env"
+require_relative "../errors"
+require_relative "request_scoped_storage"
+
+module Supabase
+  module Rails
+    module Web
+      # Constructs one `Supabase::Auth::Client` per request, cached in
+      # `request.env["supabase.rails.auth_client"]` so every helper that
+      # touches Supabase Auth within a single request shares the same
+      # instance (and therefore the same `RequestScopedStorage`).
+      #
+      # The client is wired with the invariants documented in FR-W6 / FR-W10:
+      #
+      #   * `storage:`             — per-request `RequestScopedStorage`
+      #   * `auto_refresh_token:`  — `false` (no Timer threads in workers;
+      #                               refresh is inline via US-006)
+      #   * `flow_type:`           — `"pkce"` (required for OAuth)
+      #   * `persist_session:`     — `true` (storage is request-scoped, so
+      #                               "persist" means "within this request")
+      module AuthClientFactory
+        ENV_KEY = "supabase.rails.auth_client"
+
+        module_function
+
+        def build(request, env: nil, supabase_options: nil)
+          cached = request.env[ENV_KEY]
+          return cached unless cached.nil?
+
+          request.env[ENV_KEY] = build_client(
+            request,
+            env: env,
+            supabase_options: supabase_options
+          )
+        end
+
+        def build_client(request, env:, supabase_options:)
+          resolved_env = env.is_a?(SupabaseEnv) ? env : Env.resolve(env || {})
+          publishable_key = resolve_publishable_key(resolved_env.publishable_keys)
+
+          # `auto_refresh_token: false` is a hard invariant for every
+          # `Supabase::Auth::Client` constructed by this gem (PRD §FR-W10,
+          # US-008). `supabase-rb` would otherwise spawn a background Timer
+          # thread per session that outlives the request and leaks across
+          # Puma worker fork cycles. Refresh is performed inline by
+          # `Web::CookieCredentialStrategy` (US-006).
+          # `spec/supabase/rails/auto_refresh_token_invariant_spec.rb`
+          # enforces this by grepping the gem source.
+          ::Supabase::Auth::Client.new(
+            url: auth_url(resolved_env.url),
+            headers: build_headers(publishable_key, supabase_options),
+            storage: RequestScopedStorage.new(request),
+            auto_refresh_token: false,
+            flow_type: "pkce",
+            persist_session: true
+          )
+        end
+
+        def auth_url(base_url)
+          "#{base_url.to_s.chomp('/')}/auth/v1"
+        end
+
+        def resolve_publishable_key(keys)
+          key = keys["default"]
+          return key unless key.nil? || key.to_s.empty?
+
+          raise EnvError.missing_default_publishable_key
+        end
+
+        def build_headers(publishable_key, supabase_options)
+          base = {
+            "apikey" => publishable_key,
+            "Authorization" => "Bearer #{publishable_key}"
+          }
+
+          global = option_value(supabase_options, :global) || {}
+          extra = option_value(global, :headers) || {}
+
+          base.merge(stringify_keys(extra))
+        end
+
+        def option_value(hash, key)
+          return nil unless hash.is_a?(Hash)
+
+          hash.key?(key) ? hash[key] : hash[key.to_s]
+        end
+
+        def stringify_keys(hash)
+          return {} unless hash.is_a?(Hash)
+
+          hash.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+        end
+
+        private_class_method :build_client, :auth_url, :resolve_publishable_key,
+                             :build_headers, :option_value, :stringify_keys
+      end
+    end
+  end
+end

data/lib/supabase/rails/web/auth_error_mapper.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module Supabase
+  module Rails
+    module Web
+      # Translates `Supabase::Auth::Errors::*` (raised by `supabase-rb`) into
+      # the gem-stable `Supabase::Rails::AuthError` surface (`#code` + `#status`)
+      # per FR-W9. Controllers and the middleware error-shaping pipeline can
+      # rely on these stable codes/statuses without inspecting upstream classes.
+      #
+      # Ordering note: the dispatch is a `case/when`, so the most specific
+      # classes must come before their ancestors. `AuthRetryableError`,
+      # `AuthSessionMissing`, `AuthInvalidCredentialsError`,
+      # `AuthInvalidJwtError`, and `AuthWeakPassword` all inherit from
+      # `CustomAuthError < AuthError`; `AuthApiError`, `AuthPKCEError`, and
+      # `AuthUnknownError` inherit directly from `AuthError`. None of them
+      # inherit from each other, so the within-leaf order is cosmetic.
+      module AuthErrorMapper
+        module_function
+
+        # @param err [Supabase::Auth::Errors::AuthError, StandardError]
+        # @return [Supabase::Rails::AuthError]
+        def translate(err)
+          message = err.respond_to?(:message) ? err.message.to_s : err.to_s
+
+          case err
+          when ::Supabase::Auth::Errors::AuthInvalidCredentialsError
+            AuthError.new(message, AuthError::INVALID_CREDENTIALS, 401)
+          when ::Supabase::Auth::Errors::AuthInvalidJwtError
+            AuthError.new(message, AuthError::INVALID_CREDENTIALS, 401)
+          when ::Supabase::Auth::Errors::AuthSessionMissing
+            AuthError.new(message, AuthError::SESSION_MISSING, 401)
+          when ::Supabase::Auth::Errors::AuthWeakPassword
+            AuthError.new(message, AuthError::WEAK_PASSWORD, 422)
+          when ::Supabase::Auth::Errors::AuthPKCEError
+            AuthError.new(message, AuthError::PKCE_ERROR, 400)
+          when ::Supabase::Auth::Errors::AuthRetryableError
+            AuthError.new(message, AuthError::AUTH_RETRYABLE, 503)
+          when ::Supabase::Auth::Errors::AuthApiError
+            map_api_error(message, err.status)
+          when ::Supabase::Auth::Errors::AuthUnknownError
+            AuthError.new(message, AuthError::AUTH_GENERIC_ERROR, 500)
+          else
+            AuthError.new(message, AuthError::AUTH_GENERIC_ERROR, 500)
+          end
+        end
+
+        class << self
+          private
+
+          def map_api_error(message, status)
+            if status.is_a?(Integer) && status >= 500
+              AuthError.new(message, AuthError::AUTH_UPSTREAM_ERROR, 503)
+            else
+              upstream = status.is_a?(Integer) ? status : 400
+              AuthError.new(message, AuthError::AUTH_API_ERROR, upstream)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/supabase/rails/web/cookie_credential_strategy.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require_relative "../context"
+require_relative "../logging"
+require_relative "../session_store"
+require_relative "auth_client_factory"
+require_relative "refresh_coordinator"
+
+module Supabase
+  module Rails
+    module Web
+      # Web-mode credential extraction from the encrypted session cookie.
+      #
+      # Reads the Supabase session via {SessionStore}, then:
+      #
+      #   * missing/unparseable cookie                  → anonymous context
+      #   * cookie missing access_token /               → anonymous context
+      #     expires_at, or non-numeric exp
+      #   * `expires_at > now + 10s`                    → JWT verify the
+      #                                                   access_token and build
+      #                                                   a `:user` context
+      #   * `expires_at <= now + 10s` + refresh_token   → inline refresh via
+      #                                                   `auth.refresh_session`
+      #     - success                                   → write new cookie + use
+      #                                                   the new access_token
+      #     - AuthApiError 400/401                      → clear cookie, anon
+      #     - upstream 5xx / network                    → Result.failure with
+      #                                                   AuthError(status: 503)
+      #   * refresh_token missing on a near-expired     → clear cookie, anon
+      #     cookie
+      #
+      # The `Authorization: Bearer` header is intentionally ignored — in
+      # `:web` mode the cookie is the sole credential source. Per-controller
+      # `verify_supabase_auth(mode: :api)` (US-024) re-runs the API path.
+      class CookieCredentialStrategy
+        REFRESH_LEEWAY_SECONDS = 10
+
+        RackRequest = Struct.new(:env)
+        private_constant :RackRequest
+
+        def initialize(env: nil, supabase_options: nil, session: nil, session_store: nil, user_model: nil)
+          @env_overrides = env
+          @supabase_options = supabase_options
+          @session_store = session_store || SessionStore.new(session)
+          @user_model = user_model
+        end
+
+        def call(rack_env)
+          session = read_session(rack_env)
+
+          return anonymous_context(rack_env) if session.nil?
+
+          access_token = session["access_token"]
+          expires_at   = session["expires_at"]
+
+          return anonymous_context(rack_env) unless valid_token?(access_token)
+          return anonymous_context(rack_env) unless valid_expiry?(expires_at)
+          return refresh_or_clear(rack_env, session) if needs_refresh?(expires_at)
+
+          user_context(rack_env, access_token)
+        end
+
+        private
+
+        def read_session(rack_env)
+          @session_store.read(request_for(rack_env))
+        rescue StandardError
+          nil
+        end
+
+        def request_for(rack_env)
+          require "action_dispatch/http/request"
+          ActionDispatch::Request.new(rack_env)
+        end
+
+        def valid_token?(token)
+          token.is_a?(String) && !token.empty?
+        end
+
+        def valid_expiry?(expires_at)
+          expires_at.is_a?(Numeric)
+        end
+
+        def needs_refresh?(expires_at)
+          expires_at <= Time.now.to_i + REFRESH_LEEWAY_SECONDS
+        end
+
+        def refresh_or_clear(rack_env, session)
+          Logging.log(:info, "[supabase.rails.web.refresh] refresh starting")
+          refresh_token = session["refresh_token"]
+
+          unless valid_token?(refresh_token)
+            Logging.log(:warn, "[supabase.rails.web.refresh] clearing session cookie (no refresh_token)")
+            clear_cookie(rack_env)
+            return anonymous_context(rack_env)
+          end
+
+          outcome = RefreshCoordinator.synchronize(refresh_token) do
+            current = read_session(rack_env)
+            if current && fresh_enough?(current)
+              current
+            else
+              perform_refresh(rack_env, refresh_token)
+            end
+          end
+
+          apply_outcome(rack_env, outcome)
+        end
+
+        def fresh_enough?(session)
+          valid_token?(session["access_token"]) &&
+            valid_expiry?(session["expires_at"]) &&
+            !needs_refresh?(session["expires_at"])
+        end
+
+        def perform_refresh(rack_env, refresh_token)
+          request = request_for(rack_env)
+          client = AuthClientFactory.build(
+            request,
+            env: @env_overrides,
+            supabase_options: @supabase_options
+          )
+          response = client.refresh_session(refresh_token)
+          session_to_hash(response.session)
+        rescue ::Supabase::Auth::Errors::AuthApiError => e
+          [400, 401].include?(e.status) ? :invalid : :transient
+        rescue ::Supabase::Auth::Errors::AuthSessionMissing
+          :invalid
+        rescue ::Supabase::Auth::Errors::AuthError
+          :transient
+        rescue StandardError
+          :transient
+        end
+
+        def session_to_hash(session)
+          return nil if session.nil?
+          return session.transform_keys(&:to_s) if session.is_a?(Hash)
+          return session.to_h.transform_keys(&:to_s) if session.respond_to?(:to_h)
+
+          nil
+        end
+
+        def apply_outcome(rack_env, outcome)
+          case outcome
+          when Hash
+            write_cookie(rack_env, outcome)
+            user_context(rack_env, outcome["access_token"])
+          when :invalid
+            Logging.log(:warn, "[supabase.rails.web.refresh] clearing session cookie (refresh invalid)")
+            clear_cookie(rack_env)
+            anonymous_context(rack_env)
+          when :transient
+            Logging.log(:error, "[supabase.rails.web.refresh] upstream refresh unavailable (5xx/network)")
+            Result.failure(AuthError.refresh_unavailable)
+          else
+            Logging.log(:warn, "[supabase.rails.web.refresh] clearing session cookie (refresh unknown outcome)")
+            clear_cookie(rack_env)
+            anonymous_context(rack_env)
+          end
+        end
+
+        def write_cookie(rack_env, session_hash)
+          @session_store.write(request_for(rack_env), session_hash)
+        rescue StandardError
+          nil
+        end
+
+        def clear_cookie(rack_env)
+          @session_store.clear(request_for(rack_env))
+        rescue StandardError
+          nil
+        end
+
+        def anonymous_context(rack_env)
+          Rails.create_context(
+            RackRequest.new(rack_env),
+            auth: :none,
+            env: @env_overrides,
+            supabase_options: @supabase_options,
+            user_model: @user_model
+          )
+        end
+
+        def user_context(rack_env, access_token)
+          # Overlay the cookie's access_token onto the env so the existing
+          # `create_context` pipeline (extract_headers → verify_credentials
+          # → build_context_result) handles JWT verify and client build.
+          shim_env = rack_env.merge("HTTP_AUTHORIZATION" => "Bearer #{access_token}")
+          Rails.create_context(
+            RackRequest.new(shim_env),
+            auth: :user,
+            env: @env_overrides,
+            supabase_options: @supabase_options,
+            user_model: @user_model
+          )
+        end
+      end
+    end
+  end
+end

data/lib/supabase/rails/web/redirect_validator.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "uri"
+
+require_relative "../errors"
+
+module Supabase
+  module Rails
+    module Web
+      # Validates a `redirect_to` target against an origin allowlist (FR-W11,
+      # US-015). Prevents open-redirect vulnerabilities introduced via
+      # attacker-controlled `?redirect_to=` query params on OAuth start and
+      # callback URLs.
+      #
+      # A target is accepted when it is either:
+      #   * a path (no scheme/host), e.g. `/dashboard` or `/foo?a=1`, OR
+      #   * an absolute URL whose origin (`scheme://host[:port]`) matches an
+      #     entry in `allowed_origins`.
+      #
+      # Anything else raises `Supabase::Rails::AuthError(code: "INVALID_REDIRECT")`.
+      # Origin matching is case-insensitive on scheme + host; the port must
+      # match exactly (or be the scheme default on both sides).
+      module RedirectValidator
+        module_function
+
+        # @param uri [String, URI::Generic, nil] the candidate redirect target.
+        # @param allowed_origins [Array<String>] list of allowed origins
+        #   (`"https://myapp.com"` style) — typically
+        #   `config.supabase.allowed_redirect_origins`, falling back to
+        #   `[request.host]` at the call site.
+        # @return [String] the input target, unchanged, when valid.
+        # @raise [Supabase::Rails::AuthError] when the target is off-allowlist
+        #   or malformed (`code: "INVALID_REDIRECT"`, `status: 400`).
+        def validate(uri, allowed_origins:)
+          raise AuthError.invalid_redirect(uri) if uri.nil?
+
+          raw = uri.to_s
+          raise AuthError.invalid_redirect(raw) if raw.empty?
+
+          parsed = parse(raw)
+          raise AuthError.invalid_redirect(raw) if parsed.nil?
+
+          return raw if path_only?(parsed)
+          return raw if origin_allowed?(parsed, allowed_origins)
+
+          raise AuthError.invalid_redirect(raw)
+        end
+
+        class << self
+          private
+
+          def parse(raw)
+            URI.parse(raw)
+          rescue URI::InvalidURIError
+            nil
+          end
+
+          # A "path-only" target has no scheme AND no host — `URI.parse("/foo")`
+          # yields `scheme=nil, host=nil, path="/foo"`. Protocol-relative URLs
+          # like `//evil.com/x` have `host="evil.com"` and are NOT path-only;
+          # they fall through to origin matching (and get rejected unless the
+          # host happens to be allowlisted). Scheme-only targets like
+          # `javascript:alert(1)` have `scheme="javascript", host=nil` and are
+          # also NOT path-only — rejected by origin matching.
+          def path_only?(uri)
+            uri.scheme.nil? && uri.host.nil? && !uri.path.to_s.empty?
+          end
+
+          def origin_allowed?(uri, allowed_origins)
+            return false if uri.scheme.nil? || uri.host.nil?
+            return false unless allowed_origins.is_a?(Array)
+
+            target_origin = origin_of(uri)
+            allowed_origins.any? do |entry|
+              allowed = parse(entry.to_s)
+              next false if allowed.nil? || allowed.scheme.nil? || allowed.host.nil?
+
+              origin_of(allowed) == target_origin
+            end
+          end
+
+          def origin_of(uri)
+            scheme = uri.scheme.to_s.downcase
+            host = uri.host.to_s.downcase
+            port = uri.port || URI.scheme_list[scheme.upcase]&.default_port
+            "#{scheme}://#{host}:#{port}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/supabase/rails/web/refresh_coordinator.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Supabase
+  module Rails
+    module Web
+      # In-process mutex pool keyed by `SHA256(refresh_token)`. Two threads
+      # holding the same refresh token cooperate on a single outbound
+      # `auth.refresh_session` call instead of racing.
+      #
+      # Documented limitation: across clustered Puma workers (separate
+      # processes) two simultaneous requests for the same user can each
+      # acquire their own worker-local mutex and both refresh. In practice
+      # browsers serialize cookie-bearing requests; acceptable for v0.2 and
+      # revisitable if telemetry shows refresh contention.
+      #
+      # Entries are reference-counted: the SHA256 -> Mutex entry is dropped
+      # when the last holder releases it, so the hash does not grow
+      # unboundedly in long-lived workers.
+      module RefreshCoordinator
+        @entries = {}
+        @entries_mutex = Mutex.new
+
+        module_function
+
+        # Yield the block while holding the per-token mutex. Returns the
+        # block's return value.
+        def synchronize(refresh_token)
+          key = digest(refresh_token)
+          mutex = checkout(key)
+          begin
+            mutex.synchronize { yield }
+          ensure
+            checkin(key)
+          end
+        end
+
+        def digest(refresh_token)
+          Digest::SHA256.hexdigest(refresh_token.to_s)
+        end
+
+        # Number of live (refcounted) entries — for tests / introspection.
+        def entry_count
+          @entries_mutex.synchronize { @entries.size }
+        end
+
+        # Test-only escape hatch. Forcibly drops every entry so a leaked
+        # mutex from a previous example can't bleed into the next.
+        def reset!
+          @entries_mutex.synchronize { @entries.clear }
+        end
+
+        class << self
+          private
+
+          def checkout(key)
+            @entries_mutex.synchronize do
+              entry = @entries[key] ||= { mutex: Mutex.new, refs: 0 }
+              entry[:refs] += 1
+              entry[:mutex]
+            end
+          end
+
+          def checkin(key)
+            @entries_mutex.synchronize do
+              entry = @entries[key]
+              return unless entry
+
+              entry[:refs] -= 1
+              @entries.delete(key) if entry[:refs] <= 0
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/supabase/rails/web/request_scoped_storage.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module Supabase
+  module Rails
+    module Web
+      # Per-request Supabase Auth storage.
+      #
+      # Implements the `Supabase::Auth::SupportedStorage` duck type
+      # (`get_item` / `set_item` / `remove_item`). The backing Hash lives in
+      # `request.env["supabase.rails.auth_storage"]` and is allocated lazily
+      # on first access — concurrent requests in the same worker each get
+      # their own slot, so PKCE verifiers and session state never leak across
+      # threads or users.
+      #
+      # PKCE verifiers must survive the OAuth round-trip (the verifier is
+      # written during `sign_in_with_oauth` on one request and consumed at
+      # `/callback` on another). When `#oauth_state` is set, writes to any
+      # key whose name ends with `code-verifier` are mirrored into a signed
+      # cookie `sb-oauth-state-<state>` with a 10-minute expiry; reads fall
+      # back to that cookie when the per-request hash misses. Keying the
+      # cookie by the OAuth `state` param binds the verifier to the specific
+      # round-trip and prevents mix-ups across concurrent OAuth attempts.
+      class RequestScopedStorage < ::Supabase::Auth::SupportedStorage
+        ENV_KEY            = "supabase.rails.auth_storage"
+        COOKIE_NAME_PREFIX = "sb-oauth-state-"
+        COOKIE_TTL_SECONDS = 600
+        PKCE_KEY_SUFFIX    = "code-verifier"
+
+        attr_accessor :oauth_state
+        attr_reader :request
+
+        def initialize(request, oauth_state: nil)
+          super()
+          @request = request
+          @oauth_state = oauth_state
+        end
+
+        def get_item(key)
+          value = backing_hash[key]
+          return value unless value.nil?
+
+          read_pkce_cookie(key)
+        end
+
+        def set_item(key, value)
+          backing_hash[key] = value
+          write_pkce_cookie(value) if pkce_key?(key) && oauth_state_present?
+          value
+        end
+
+        def remove_item(key)
+          existed = backing_hash.key?(key)
+          value = backing_hash.delete(key)
+          clear_pkce_cookie if pkce_key?(key) && oauth_state_present?
+          existed ? value : nil
+        end
+
+        # The backing per-request hash, lazily allocated in `request.env`.
+        # Subsequent `RequestScopedStorage.new(request)` calls for the same
+        # request observe the same hash (memoized by env key).
+        def backing_hash
+          env[ENV_KEY] ||= {}
+        end
+
+        private
+
+        def env
+          @request.env
+        end
+
+        def pkce_key?(key)
+          key.is_a?(String) && key.end_with?(PKCE_KEY_SUFFIX)
+        end
+
+        def oauth_state_present?
+          !oauth_state.nil? && !oauth_state.to_s.empty?
+        end
+
+        def read_pkce_cookie(key)
+          return nil unless pkce_key?(key) && oauth_state_present?
+
+          jar = signed_jar
+          jar && jar[cookie_name]
+        end
+
+        def write_pkce_cookie(value)
+          jar = signed_jar
+          return if jar.nil?
+
+          jar[cookie_name] = {
+            value: value,
+            expires: Time.now + COOKIE_TTL_SECONDS,
+            httponly: true,
+            same_site: :lax,
+            path: "/",
+            secure: default_secure
+          }
+        end
+
+        def clear_pkce_cookie
+          jar = base_jar
+          return if jar.nil?
+
+          jar.delete(cookie_name, path: "/")
+        end
+
+        def cookie_name
+          "#{COOKIE_NAME_PREFIX}#{oauth_state}"
+        end
+
+        def signed_jar
+          jar = base_jar
+          return nil if jar.nil?
+
+          jar.respond_to?(:signed) ? jar.signed : jar
+        end
+
+        def base_jar
+          return nil unless @request.respond_to?(:cookie_jar)
+
+          @request.cookie_jar
+        end
+
+        def default_secure
+          defined?(::Rails) && ::Rails.respond_to?(:env) && ::Rails.env.production?
+        end
+      end
+    end
+  end
+end

data/lib/supabase/rails.rb

@@ -6,8 +6,10 @@ require_relative "rails/logging"
 require_relative "rails/env"
 require_relative "rails/jwt"
 require_relative "rails/core"
+require_relative "rails/user"
 require_relative "rails/context"
 require_relative "rails/cors"
+require_relative "rails/session_store"
 
 module Supabase
   module Rails
@@ -15,6 +17,14 @@ module Supabase
   end
 end
 
+require_relative "rails/web/request_scoped_storage"
+require_relative "rails/web/auth_client_factory"
+require_relative "rails/web/refresh_coordinator"
+require_relative "rails/web/auth_error_mapper"
+require_relative "rails/web/redirect_validator"
 require_relative "rails/middleware"
 require_relative "rails/controller"
+require_relative "rails/authentication"
+require_relative "rails/routes"
+require_relative "rails/engine" if defined?(::Rails::Engine)
 require_relative "rails/railtie" if defined?(::Rails::Railtie)