supabase-rails 0.1.0 → 1.0.0

data/lib/supabase/rails/context.rb

@@ -10,7 +10,8 @@ module Supabase
     SupabaseContext = Data.define(
       :supabase, :supabase_admin,
       :user_claims, :jwt_claims,
-      :auth_mode, :auth_key_name
+      :auth_mode, :auth_key_name,
+      :current_user
     )
 
     class Result
@@ -38,7 +39,7 @@ module Supabase
       end
     end
 
-    def self.create_context(request, auth: :user, env: nil, supabase_options: nil)
+    def self.create_context(request, auth: :user, env: nil, supabase_options: nil, user_model: nil)
       headers = extract_headers(request)
       credentials = Core.extract_credentials(headers)
 
@@ -50,10 +51,15 @@ module Supabase
           return Result.failure(e)
         end
 
-      build_context_result(auth_result, env: env, supabase_options: supabase_options)
+      build_context_result(
+        auth_result,
+        env: env,
+        supabase_options: supabase_options,
+        user_model: user_model
+      )
     end
 
-    def self.build_context_result(auth_result, env:, supabase_options:)
+    def self.build_context_result(auth_result, env:, supabase_options:, user_model: nil)
       publishable_key_name = auth_result.auth_mode == :publishable ? auth_result.key_name : nil
       supabase = Core.create_context_client(
         auth: { token: auth_result.token, key_name: publishable_key_name },
@@ -68,6 +74,16 @@ module Supabase
         supabase_options: supabase_options
       )
 
+      # `current_user` is the default `Current.user` value (FR-W15).
+      # Built only when `user_model` is unset (the host hasn't opted into a
+      # shadow AR model via FR-W14). When `user_model` is set, the
+      # Authentication concern populates `Current.user` with the AR record
+      # in `start_new_session_for` and this stays nil.
+      current_user =
+        if user_model.nil? && auth_result.jwt_claims.is_a?(Hash)
+          User.from_claims(auth_result.jwt_claims)
+        end
+
       Result.success(
         SupabaseContext.new(
           supabase: supabase,
@@ -75,7 +91,8 @@ module Supabase
           user_claims: auth_result.user_claims,
           jwt_claims: auth_result.jwt_claims,
           auth_mode: auth_result.auth_mode,
-          auth_key_name: auth_result.key_name
+          auth_key_name: auth_result.key_name,
+          current_user: current_user
         )
       )
     rescue EnvError => e

data/lib/supabase/rails/controller.rb

@@ -15,8 +15,30 @@ module Supabase
         request.env[Rails::CONTEXT_KEY]
       end
 
-      def verify_supabase_auth(auth: nil, env: nil, supabase_options: nil)
-        if auth.nil? && env.nil? && supabase_options.nil?
+      # `mode: :api` forces header-only credential extraction (FR-W1) even
+      # when the global mode is `:web`. Use this in `/api/v1/*` controllers
+      # inside a `:web` monolith so a single gem handles both surfaces — the
+      # cookie context (anonymous or user) set by the middleware is
+      # discarded and `Rails.create_context` re-runs against the request's
+      # `Authorization: Bearer` header. Without `mode: :api`, a request that
+      # carries only a session cookie would authenticate via the cookie
+      # (web-mode behavior); with it, the request must present a JWT in the
+      # header or `AuthError.invalid_credentials` is raised.
+      def verify_supabase_auth(mode: nil, auth: nil, env: nil, supabase_options: nil)
+        unless mode.nil? || Middleware::VALID_MODES.include?(mode)
+          raise ConfigError.invalid_mode(mode)
+        end
+
+        if mode.nil? && auth.nil? && env.nil? && supabase_options.nil?
+          raise AuthError.invalid_credentials if supabase_context.nil?
+
+          return supabase_context
+        end
+
+        # `mode: :web` is the no-op case — the middleware already extracted
+        # via cookie. Return the existing context (or raise) so a controller
+        # can declare web-mode intent without re-running extraction.
+        if mode == :web && auth.nil? && env.nil? && supabase_options.nil?
           raise AuthError.invalid_credentials if supabase_context.nil?
 
           return supabase_context

data/lib/supabase/rails/core.rb

@@ -128,6 +128,15 @@ module Supabase
         safe_headers = safe_headers.merge("Authorization" => "Bearer #{token}") if token && !token.to_s.empty?
 
         auth_opts = option_value(supabase_options, :auth) || {}
+        # `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 the
+        # web-mode credential strategy (`Web::CookieCredentialStrategy`).
+        # `spec/supabase/rails/auto_refresh_token_invariant_spec.rb`
+        # enforces this by grepping the gem source — do not relax it
+        # without removing that spec.
         auth_opts = auth_opts.merge(
           persist_session: false,
           auto_refresh_token: false,

data/lib/supabase/rails/engine.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "action_dispatch"
+require "rails/engine"
+require_relative "routes"
+
+module Supabase
+  module Rails
+    # Internal `::Rails::Engine` (FR-W8 / US-017). Its only job is to add the
+    # gem's top-level `app/controllers`, `app/views`, and `config/locales`
+    # directories to the host app's autoload + I18n load paths. It is NOT
+    # mounted by users — there's no `mount Supabase::Rails::Engine`. Routes
+    # for the auth surface come from the `supabase_authentication_routes`
+    # helper (FR-W12 / US-022) that the install generator emits into the
+    # host's `config/routes.rb`.
+    #
+    # We deliberately do NOT call `isolate_namespace` so that the gem's
+    # controllers inherit from the host's `::ApplicationController` (picking
+    # up CSRF, layouts, helpers, and any global before_actions) and so the
+    # views resolve under the host's view-path lookup rules.
+    #
+    # `Engine.root` is left at the framework default — Rails walks up from
+    # this file until it finds the gem root (the directory containing
+    # `lib/supabase/rails.rb`), which is exactly what we want.
+    class Engine < ::Rails::Engine
+      # Install `supabase_authentication_routes` onto the routing DSL.
+      # Runs before `:set_routes_reloader` (the Rails-internal initializer
+      # that loads `config/routes.rb`), so the helper is available the first
+      # time the host's routes are drawn at boot.
+      initializer "supabase.rails.routes_helper", before: :set_routes_reloader do
+        ActionDispatch::Routing::Mapper.include(Supabase::Rails::Routes)
+      end
+    end
+  end
+end

data/lib/supabase/rails/errors.rb

@@ -51,10 +51,46 @@ module Supabase
       end
     end
 
+    class ConfigError < StandardError
+      CONFIG_GENERIC_ERROR = "CONFIG_ERROR"
+      INVALID_MODE = "INVALID_MODE"
+      API_MODE_COOKIE_UNSUPPORTED = "API_MODE_COOKIE_UNSUPPORTED"
+
+      attr_reader :code
+
+      def initialize(message, code = CONFIG_GENERIC_ERROR)
+        super(message)
+        @code = code
+      end
+
+      def self.invalid_mode(value)
+        new(
+          %(Invalid `config.supabase.mode = #{value.inspect}`. Must be :api or :web.),
+          INVALID_MODE
+        )
+      end
+
+      def self.api_mode_cookie_unsupported
+        new(
+          "`start_new_session_for` is not supported in :api mode. Cookies don't apply " \
+          "to JWT-bearer flows — clients send the `Authorization: Bearer` header instead.",
+          API_MODE_COOKIE_UNSUPPORTED
+        )
+      end
+    end
+
     class AuthError < StandardError
       AUTH_GENERIC_ERROR = "AUTH_ERROR"
       INVALID_CREDENTIALS = "INVALID_CREDENTIALS"
       CREATE_SUPABASE_CLIENT_ERROR = "CREATE_SUPABASE_CLIENT_ERROR"
+      REFRESH_UNAVAILABLE = "REFRESH_UNAVAILABLE"
+      PKCE_ERROR = "PKCE_ERROR"
+      WEAK_PASSWORD = "WEAK_PASSWORD"
+      SESSION_MISSING = "SESSION_MISSING"
+      INVALID_REDIRECT = "INVALID_REDIRECT"
+      AUTH_API_ERROR = "AUTH_API_ERROR"
+      AUTH_UPSTREAM_ERROR = "AUTH_UPSTREAM_ERROR"
+      AUTH_RETRYABLE = "AUTH_RETRYABLE"
 
       attr_reader :code, :status
 
@@ -71,6 +107,38 @@ module Supabase
       def self.create_supabase_client_error
         new("Failed to create Supabase client", CREATE_SUPABASE_CLIENT_ERROR, 500)
       end
+
+      def self.refresh_unavailable
+        new(
+          "Supabase Auth is temporarily unavailable. Please try again.",
+          REFRESH_UNAVAILABLE,
+          503
+        )
+      end
+
+      def self.pkce_missing_verifier
+        new(
+          "PKCE verifier missing or expired. Restart the OAuth flow.",
+          PKCE_ERROR,
+          400
+        )
+      end
+
+      def self.invalid_redirect(uri)
+        new(
+          %(redirect target #{uri.inspect} is not in `config.supabase.allowed_redirect_origins`),
+          INVALID_REDIRECT,
+          400
+        )
+      end
+
+      def self.session_missing
+        new(
+          "Authentication required. No active Supabase session.",
+          SESSION_MISSING,
+          401
+        )
+      end
     end
   end
 end

data/lib/supabase/rails/middleware.rb

@@ -2,16 +2,24 @@
 
 require "json"
 require_relative "../rails"
+require_relative "web/cookie_credential_strategy"
 
 module Supabase
   module Rails
     class Middleware
-      def initialize(app, auth: :user, env: nil, supabase_options: nil, cors: nil)
+      VALID_MODES = %i[api web].freeze
+
+      def initialize(app, mode: :api, auth: :user, env: nil, supabase_options: nil, cors: nil, session: nil, user_model: nil)
+        raise ConfigError.invalid_mode(mode) unless VALID_MODES.include?(mode)
+
         @app = app
+        @mode = mode
         @auth = auth
         @env_overrides = env
         @supabase_options = supabase_options
         @cors = cors
+        @session = session
+        @user_model = user_model
       end
 
       def call(env)
@@ -21,12 +29,7 @@ module Supabase
 
         return @app.call(env) if env[Rails::CONTEXT_KEY]
 
-        result = Rails.create_context(
-          RackRequest.new(env),
-          auth: @auth,
-          env: @env_overrides,
-          supabase_options: @supabase_options
-        )
+        result = build_context(env)
 
         return error_response(result.error) if result.failure?
 
@@ -38,6 +41,26 @@ module Supabase
 
       private
 
+      def build_context(env)
+        case @mode
+        when :api
+          Rails.create_context(
+            RackRequest.new(env),
+            auth: @auth,
+            env: @env_overrides,
+            supabase_options: @supabase_options,
+            user_model: @user_model
+          )
+        when :web
+          Web::CookieCredentialStrategy.new(
+            env: @env_overrides,
+            supabase_options: @supabase_options,
+            session: @session,
+            user_model: @user_model
+          ).call(env)
+        end
+      end
+
       def cors_enabled?
         @cors != false
       end

data/lib/supabase/rails/railtie.rb

@@ -6,21 +6,47 @@ module Supabase
   module Rails
     class Railtie < ::Rails::Railtie
       config.supabase = ActiveSupport::OrderedOptions.new
+      config.supabase.mode = :api
       config.supabase.auth = :user
       config.supabase.cors = nil
       config.supabase.env = nil
       config.supabase.supabase_options = nil
       config.supabase.insert_middleware = true
+      config.supabase.user_model = nil
+      # nil = derive from mode (true in :web, false in :api). See
+      # `Supabase::Rails::Authentication.expose_current_user?`.
+      config.supabase.expose_current_user = nil
+      # Empty default; the OAuth helpers (US-015) fall back to
+      # `[request.host]` (same-origin) at runtime when this is empty.
+      config.supabase.allowed_redirect_origins = []
+      # Empty default; the `supabase/rails/oauth/_buttons.html.erb` partial
+      # iterates this list to render one "Sign in with <provider>" link
+      # per entry. Set in the host's initializer (e.g. `%i[google github]`).
+      config.supabase.oauth_providers = []
+      config.supabase.session = {
+        cookie_name: Supabase::Rails::SessionStore::DEFAULT_COOKIE_NAME,
+        same_site:   Supabase::Rails::SessionStore::DEFAULT_SAME_SITE,
+        secure:      nil,
+        domain:      nil,
+        path:        Supabase::Rails::SessionStore::DEFAULT_PATH
+      }
 
-      initializer "supabase.middleware" do |app|
+      # Insert after config/initializers/*.rb so host overrides of
+      # `config.supabase.*` (mode, auth, session, etc.) take effect — the
+      # default ordering would read the unchanged Railtie defaults before
+      # the host initializer ran.
+      initializer "supabase.middleware", after: :load_config_initializers do |app|
         cfg = app.config.supabase
         next unless cfg.insert_middleware
 
         app.middleware.use Supabase::Rails::Middleware,
+                           mode: cfg.mode,
                            auth: cfg.auth,
                            env: cfg.env,
                            supabase_options: cfg.supabase_options,
-                           cors: cfg.cors
+                           cors: cfg.cors,
+                           session: cfg.session,
+                           user_model: cfg.user_model
       end
     end
   end

data/lib/supabase/rails/routes.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Rails
+    # `supabase_authentication_routes` routing-DSL helper (FR-W12 / US-022).
+    #
+    # Installed onto `ActionDispatch::Routing::Mapper` by
+    # {Supabase::Rails::Engine} so hosts can write a single line inside
+    # `Rails.application.routes.draw do ... end` to mount the entire auth
+    # surface that the gem's controllers (US-017) and views (US-020) expect.
+    #
+    # Expansion (default — no filter):
+    #
+    #   * `resource :session, only: %i[new create destroy]`
+    #   * `resource :registration, only: %i[new create]`
+    #   * `resources :passwords, only: %i[new create edit update], param: :token`
+    #   * `resources :otp, only: %i[new create]` with a `verify` collection
+    #     route responding to both GET (render the code-entry form) and POST
+    #     (submit the code). Named `verify_otp_index_path`.
+    #   * `GET /oauth/:provider/authorize` → `oauth_authorize_path(provider)`
+    #   * `GET /oauth/callback`            → `oauth_callback_path`
+    #
+    # `only:` / `except:` filter by group symbol — one of `:session`,
+    # `:registration`, `:passwords`, `:otp`, `:oauth` (per OQ-W4 lean-yes).
+    # A host that only wants password resets can write:
+    #
+    #     supabase_authentication_routes only: %i[passwords]
+    #
+    # The helper does NOT name controllers — by default `resource :session`
+    # routes to `::SessionsController`, which is exactly the top-level
+    # wrapper the install generator (US-018) creates. Hosts that nest auth
+    # under a scope can wrap the call:
+    #
+    #     scope module: "auth" do
+    #       supabase_authentication_routes
+    #     end
+    module Routes
+      GROUPS = %i[session registration passwords otp oauth].freeze
+
+      def supabase_authentication_routes(only: nil, except: nil)
+        groups = Routes.filter(only: only, except: except)
+
+        if groups.include?(:session)
+          resource :session, only: %i[new create destroy]
+        end
+
+        if groups.include?(:registration)
+          resource :registration, only: %i[new create]
+        end
+
+        if groups.include?(:passwords)
+          resources :passwords, only: %i[new create edit update], param: :token
+        end
+
+        if groups.include?(:otp)
+          resources :otp, only: %i[new create] do
+            collection do
+              match :verify, via: %i[get post], as: :verify
+            end
+          end
+        end
+
+        if groups.include?(:oauth)
+          get "/oauth/:provider/authorize", to: "oauth#authorize", as: :oauth_authorize
+          get "/oauth/callback",            to: "oauth#callback",  as: :oauth_callback
+        end
+      end
+
+      def self.filter(only: nil, except: nil)
+        validate_filter!(:only,   only)   if only
+        validate_filter!(:except, except) if except
+
+        groups = GROUPS.dup
+        groups &= Array(only).map(&:to_sym)   if only
+        groups -= Array(except).map(&:to_sym) if except
+        groups
+      end
+
+      def self.validate_filter!(name, value)
+        unknown = Array(value).map(&:to_sym) - GROUPS
+        return if unknown.empty?
+
+        raise ArgumentError,
+              "supabase_authentication_routes: unknown #{name}: #{unknown.inspect}. " \
+              "Valid groups: #{GROUPS.inspect}"
+      end
+    end
+  end
+end

data/lib/supabase/rails/session_store.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Supabase
+  module Rails
+    # Single source of truth for the encrypted session cookie used in `:web`
+    # mode. Wraps Rails' `ActionDispatch::Cookies::EncryptedCookieJar` (keyed
+    # by the host app's `secret_key_base`, so no new secret is introduced) so
+    # the middleware (read + refresh-rewrite) and the `Authentication`
+    # concern (`start_new_session_for` / `terminate_session`) read and write
+    # the same cookie consistently.
+    #
+    # Decrypted payload contains only the credential fields needed to verify
+    # / refresh the session — access_token, refresh_token, expires_at,
+    # expires_in, token_type. The upstream `Supabase::Auth::Types::Session`
+    # struct also exposes a `user` field (and `provider_token` /
+    # `provider_refresh_token`), but those are intentionally NOT persisted:
+    # the user object is reconstructed from the access_token's JWT claims at
+    # request time, and a full Session would overflow Rails' 4 KB cookie
+    # limit on real Supabase responses (which embed identities, metadata,
+    # etc.).
+    class SessionStore
+      DEFAULT_COOKIE_NAME = "sb-session"
+      DEFAULT_SAME_SITE = :lax
+      DEFAULT_PATH = "/"
+      PERSISTED_KEYS = %w[access_token refresh_token expires_at expires_in token_type].freeze
+
+      attr_reader :cookie_name, :same_site, :secure, :domain, :path
+
+      def initialize(config = nil)
+        cfg = normalize_config(config)
+
+        @cookie_name = cfg[:cookie_name] || DEFAULT_COOKIE_NAME
+        @same_site   = cfg[:same_site]   || DEFAULT_SAME_SITE
+        @path        = cfg[:path]        || DEFAULT_PATH
+        @domain      = cfg[:domain]
+        @secure      = cfg.key?(:secure) && !cfg[:secure].nil? ? cfg[:secure] : default_secure
+      end
+
+      # Decrypts the session cookie. Returns a Hash mirroring
+      # `Supabase::Auth::Types::Session`, or `nil` if the cookie is missing,
+      # tampered, or otherwise unreadable. A tampered ciphertext is treated
+      # as a missing cookie (no exception bubbles up).
+      def read(request)
+        raw = encrypted_jar(request)[cookie_name]
+        return nil if raw.nil?
+        return nil unless raw.is_a?(Hash)
+
+        raw
+      rescue StandardError
+        nil
+      end
+
+      # Encrypts and persists a Supabase session as a cookie. Accepts either a
+      # `Supabase::Auth::Types::Session` (or any struct with `#to_h`) or a Hash.
+      def write(response, session)
+        encrypted_jar(response)[cookie_name] = cookie_options.merge(value: serialize_session(session))
+      end
+
+      # Past-dates the cookie so the browser drops it. Deletion happens on the
+      # base jar — the encrypted layer wraps read/write encoding only.
+      def clear(response)
+        base_jar(response).delete(cookie_name, delete_options)
+      end
+
+      private
+
+      def normalize_config(config)
+        case config
+        when nil then {}
+        when Hash then config.transform_keys(&:to_sym)
+        else
+          if config.respond_to?(:to_h)
+            config.to_h.transform_keys(&:to_sym)
+          else
+            raise ArgumentError, "SessionStore config must be a Hash (got #{config.class})"
+          end
+        end
+      end
+
+      def default_secure
+        defined?(::Rails) && ::Rails.respond_to?(:env) && ::Rails.env.production?
+      end
+
+      def encrypted_jar(req_or_resp)
+        jar = base_jar(req_or_resp)
+        jar.respond_to?(:encrypted) ? jar.encrypted : jar
+      end
+
+      def base_jar(req_or_resp)
+        req_or_resp.cookie_jar
+      end
+
+      def serialize_session(session)
+        hash =
+          if session.is_a?(Hash)
+            session
+          elsif session.respond_to?(:to_h)
+            session.to_h
+          else
+            raise ArgumentError,
+                  "session must be a Hash or respond to #to_h (got #{session.class})"
+          end
+
+        hash.transform_keys(&:to_s).slice(*PERSISTED_KEYS)
+      end
+
+      def cookie_options
+        opts = {
+          httponly: true,
+          same_site: same_site,
+          secure: secure,
+          path: path
+        }
+        opts[:domain] = domain unless domain.nil?
+        opts
+      end
+
+      def delete_options
+        opts = { path: path }
+        opts[:domain] = domain unless domain.nil?
+        opts
+      end
+    end
+  end
+end

data/lib/supabase/rails/user.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Rails
+    # Immutable value object representing the authenticated Supabase user.
+    #
+    # Built from verified JWT claims by the middleware and exposed via
+    # `supabase_context.current_user`. When `config.supabase.user_model`
+    # is unset (default), this is also what populates `Current.user` for
+    # the Authentication concern (FR-W15). When the host app opts into a
+    # shadow AR `User` model (FR-W14), the concern substitutes the AR
+    # record for `Current.user` but `supabase_context.current_user`
+    # remains this value object.
+    #
+    # All fields are read straight from the verified JWT payload — no
+    # extra `auth.get_user` round-trip. Use `supabase_context.supabase
+    # .auth.get_user` when the full `Supabase::Auth::Types::User` is
+    # required.
+    class User < Data.define(:id, :email, :role, :app_metadata, :user_metadata, :raw)
+      def self.from_claims(claims)
+        claims = {} unless claims.is_a?(Hash)
+        new(
+          id:            claims["sub"],
+          email:         claims["email"],
+          role:          claims["role"],
+          app_metadata:  claims["app_metadata"],
+          user_metadata: claims["user_metadata"],
+          raw:           claims
+        )
+      end
+
+      def initialize(**)
+        super
+        freeze
+      end
+    end
+  end
+end

data/lib/supabase/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Supabase
   module Rails
-    VERSION = "0.1.0"
+    VERSION = "1.0.0"
   end
 end