supabase-rails 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecccb50074bb2287f87d4da6d42dd824d0857351c778c91ac6a13e4ad09d7258
-  data.tar.gz: 8e2e06f0425dcdedb6fdcedc19db9f44d731d09eb90709b136716dd819217e2e
+  metadata.gz: a290d81c0aa9acd877b7aeb8a1c94106a16641d7b54538c3b0c0f3551650967c
+  data.tar.gz: cc40eee184c781beebeab688ac3d78b788b327bb01397572d9ff36b332c88a3f
 SHA512:
-  metadata.gz: b08cac9795f94d01611d95f8b3115f6978b151054b0879ae865e5bf888de93bf21b8f15b3a811d0b985bea95e398a7d4788c0439bbce8f1b8d53b36e8f292ce2
-  data.tar.gz: 93b55c0c766f4f7a145769861b8818e182f93b5856f568f2c6f00f143ffc6b036de191fc7cb6a7e24827b7a83d76e86069f0c00131ab7cc9c438976cc9dd865f
+  metadata.gz: 48c4e01998a6a31e563e34623c187e4d9aaa2b219190c5c96bd541a503027c9b3da61f30b1598802a891de3f1cf23dbbeda4ca90788261e1e4684c44c1e6def8
+  data.tar.gz: b9663dad4a063e83d0b4111136197d805b2c37965d5b193ca98ea87246fa511accdfc6ad131c73039d7bed72527965d60ebf704ec78a7649682d4fdc69455059

data/app/controllers/supabase/rails/base_controller.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Rails
+    # Base class for all `Supabase::Rails::*Controller` shells (FR-W8 / US-017).
+    # Inherits from the host app's `::ApplicationController` so layouts, CSRF
+    # protection, helpers, and any global before_actions defined on the host's
+    # base class flow through to the gem's controllers. Includes the
+    # {Supabase::Rails::Authentication} concern so the FR-W5 surface
+    # (`require_authentication` before_action, `allow_unauthenticated_access`
+    # macro, `start_new_session_for`, `terminate_session`, low-level
+    # `supabase_*` helpers, override hooks) is available to subclasses.
+    class BaseController < ::ApplicationController
+      include Supabase::Rails::Authentication
+    end
+  end
+end

data/app/controllers/supabase/rails/oauth_controller.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Rails
+    # OAuth 2.0 + PKCE (FR-W7 / US-014):
+    #
+    #   * `authorize` — `GET /oauth/:provider`. Generates the PKCE state +
+    #     verifier (stashed in a signed cookie per `RequestScopedStorage`),
+    #     then redirects the user to the upstream provider's authorize URL
+    #     via Supabase Auth.
+    #   * `callback` — `GET /oauth/callback`. Exchanges the `code` + `state`
+    #     for a session via
+    #     {Supabase::Rails::Authentication#supabase_exchange_code_for_session}.
+    #     A missing PKCE verifier (cookie expired or state never issued)
+    #     fast-fails to a flash message + back to sign-in without bothering
+    #     the upstream.
+    #
+    # `redirect_to:` on `authorize` is validated against
+    # `config.supabase.allowed_redirect_origins` (FR-W11) before the upstream
+    # call, so an attacker can't smuggle in an off-allowlist destination.
+    class OauthController < BaseController
+      allow_unauthenticated_access only: %i[authorize callback]
+
+      def authorize
+        result = supabase_sign_in_with_oauth(
+          provider: params[:provider],
+          redirect_to: params[:redirect_to] || oauth_callback_url
+        )
+
+        if result.success?
+          redirect_to result.value, allow_other_host: true
+        else
+          redirect_to new_session_path,
+                      alert: I18n.t("supabase.rails.oauth.failed")
+        end
+      end
+
+      def callback
+        result = supabase_exchange_code_for_session(
+          code: params[:code],
+          state: params[:state]
+        )
+
+        if result.success?
+          redirect_to after_authentication_url,
+                      notice: I18n.t("supabase.rails.oauth.connected")
+        else
+          redirect_to new_session_path, alert: result.error.message
+        end
+      end
+    end
+  end
+end

data/app/controllers/supabase/rails/otp_controller.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Rails
+    # Passwordless sign-in via OTP / magic link (FR-W7 / US-013):
+    #
+    #   * `new` / `create` — user supplies an email or phone; gem calls
+    #     {Supabase::Rails::Authentication#supabase_sign_in_with_otp} which
+    #     triggers delivery (no session yet). Routes to `verify`.
+    #   * `verify` — accepts both GET (render the code-entry form) and POST
+    #     (submit the code via
+    #     {Supabase::Rails::Authentication#supabase_verify_otp}). On success
+    #     the helper writes the session cookie and we redirect to
+    #     `after_authentication_url`.
+    class OtpController < BaseController
+      allow_unauthenticated_access only: %i[new create verify]
+
+      def new; end
+
+      def create
+        result = supabase_sign_in_with_otp(
+          email: params[:email],
+          phone: params[:phone]
+        )
+
+        if result.success?
+          redirect_to verify_otp_index_path,
+                      notice: I18n.t("supabase.rails.otp.sent")
+        else
+          flash.now[:alert] = result.error.message
+          render :new, status: :unprocessable_entity
+        end
+      end
+
+      def verify
+        return unless request.post?
+
+        result = supabase_verify_otp(
+          token: params[:token],
+          type: params[:type] || "email",
+          email: params[:email],
+          phone: params[:phone]
+        )
+
+        if result.success?
+          redirect_to after_authentication_url,
+                      notice: I18n.t("supabase.rails.otp.verified")
+        else
+          flash.now[:alert] = result.error.message
+          render :verify, status: :unprocessable_entity
+        end
+      end
+    end
+  end
+end

data/app/controllers/supabase/rails/passwords_controller.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Rails
+    # Password reset (two-step flow):
+    #
+    #   * `new` / `create` — user requests a reset email. Supabase Auth
+    #     handles the email content + tokenized link.
+    #   * `edit` / `update` — user lands here after clicking the recovery
+    #     link. The recovery deep-link delivers them with an authenticated
+    #     session in the encrypted cookie, so {#update} can call
+    #     {Supabase::Rails::Authentication#supabase_update_user} to set the
+    #     new password (which goes through the session-seeded auth client
+    #     per FR-W6 / US-016).
+    class PasswordsController < BaseController
+      allow_unauthenticated_access only: %i[new create edit update]
+
+      def new; end
+
+      def create
+        result = supabase_reset_password(email: params[:email])
+
+        if result.success?
+          redirect_to new_session_path,
+                      notice: I18n.t("supabase.rails.passwords.reset_sent")
+        else
+          flash.now[:alert] = result.error.message
+          render :new, status: :unprocessable_entity
+        end
+      end
+
+      def edit; end
+
+      def update
+        result = supabase_update_user(password: params[:password])
+
+        if result.success?
+          redirect_to new_session_path,
+                      notice: I18n.t("supabase.rails.passwords.updated")
+        else
+          flash.now[:alert] = result.error.message
+          render :edit, status: :unprocessable_entity
+        end
+      end
+    end
+  end
+end

data/app/controllers/supabase/rails/registrations_controller.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Rails
+    # Email + password sign-up. Two-branch happy path:
+    #
+    #   * `result.value.session` is non-nil → auto-sign-in is enabled on the
+    #     Supabase project → user is signed in immediately.
+    #   * `result.value.session` is nil → email-confirmation is required →
+    #     render a "Check your inbox" notice and route back to the sign-in
+    #     page so the user lands there after clicking the confirmation link.
+    #
+    # On a 4xx upstream failure {Supabase::Rails::Authentication#supabase_sign_up}
+    # surfaces the mapped {AuthError} so the host can show specific UI for
+    # `WEAK_PASSWORD` (422) while masking other 4xx errors to a generic
+    # "Invalid credentials" (FR-W7 / US-012). 5xx flashes a generic message.
+    class RegistrationsController < BaseController
+      allow_unauthenticated_access only: %i[new create]
+
+      def new; end
+
+      def create
+        result = supabase_sign_up(email: params[:email], password: params[:password])
+
+        if result.success?
+          if registered_session_present?(result.value)
+            redirect_to after_authentication_url,
+                        notice: I18n.t("supabase.rails.registrations.created")
+          else
+            redirect_to new_session_path,
+                        notice: I18n.t("supabase.rails.registrations.pending_confirmation")
+          end
+        else
+          flash.now[:alert] = result.error.message
+          render :new, status: :unprocessable_entity
+        end
+      end
+
+      private
+
+      def registered_session_present?(value)
+        value.respond_to?(:session) && !value.session.nil?
+      end
+    end
+  end
+end

data/app/controllers/supabase/rails/sessions_controller.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Rails
+    # Email + password sign-in / sign-out. Subclassed in the host app by
+    # the install generator (FR-W12) so updates to flash copy, error
+    # handling, redirect destinations, etc. ship via `bundle update`.
+    # Hosts override any action by redefining it in the subclass.
+    class SessionsController < BaseController
+      allow_unauthenticated_access only: %i[new create]
+
+      def new; end
+
+      def create
+        if (supabase_session = authenticate_with_supabase(email: params[:email], password: params[:password]))
+          start_new_session_for(supabase_session)
+          redirect_to after_authentication_url,
+                      notice: I18n.t("supabase.rails.sessions.created")
+        else
+          flash.now[:alert] = I18n.t("supabase.rails.sessions.invalid")
+          render :new, status: :unauthorized
+        end
+      end
+
+      def destroy
+        terminate_session
+        redirect_to root_path,
+                    notice: I18n.t("supabase.rails.sessions.destroyed")
+      end
+    end
+  end
+end

data/app/views/supabase/rails/oauth/_buttons.html.erb

@@ -0,0 +1,8 @@
+<%# OAuth provider buttons. Renders one link per provider listed in
+   `config.supabase.oauth_providers` (defaults to none — host sets this in
+   the supabase initializer). Each link initiates the PKCE flow via
+   `OauthController#authorize`. %>
+<% providers = (Rails.application.config.supabase.oauth_providers if defined?(::Rails)) %>
+<% Array(providers).each do |provider| %>
+  <%= link_to "Sign in with #{provider.to_s.capitalize}", oauth_authorize_path(provider: provider), data: { turbo_method: :get } %><br>
+<% end %>

data/app/views/supabase/rails/otp/new.html.erb

@@ -0,0 +1,11 @@
+<h1>Sign in with a one-time code</h1>
+
+<%= render "supabase/rails/shared/flash" %>
+
+<%= form_with url: otp_index_path do |form| %>
+  <%= form.email_field :email, autofocus: true, autocomplete: "username", placeholder: "Enter your email address", value: params[:email] %><br>
+  <%= form.submit "Send me a code" %>
+<% end %>
+<br>
+
+<%= link_to "Back to sign in", new_session_path %>

data/app/views/supabase/rails/otp/verify.html.erb

@@ -0,0 +1,14 @@
+<h1>Enter your code</h1>
+
+<%= render "supabase/rails/shared/flash" %>
+
+<%= form_with url: verify_otp_index_path do |form| %>
+  <%= form.hidden_field :email, value: params[:email] %>
+  <%= form.hidden_field :phone, value: params[:phone] %>
+  <%= form.hidden_field :type, value: params[:type] || "email" %>
+  <%= form.text_field :token, required: true, autofocus: true, autocomplete: "one-time-code", inputmode: "numeric", placeholder: "Enter the code we just sent" %><br>
+  <%= form.submit "Verify" %>
+<% end %>
+<br>
+
+<%= link_to "Back to sign in", new_session_path %>

data/app/views/supabase/rails/passwords/edit.html.erb

@@ -0,0 +1,9 @@
+<h1>Update your password</h1>
+
+<%= render "supabase/rails/shared/flash" %>
+
+<%= form_with url: password_path(params[:token]), method: :put do |form| %>
+  <%= form.password_field :password, required: true, autocomplete: "new-password", placeholder: "Enter new password", maxlength: 72 %><br>
+  <%= form.password_field :password_confirmation, required: true, autocomplete: "new-password", placeholder: "Repeat new password", maxlength: 72 %><br>
+  <%= form.submit "Save" %>
+<% end %>

data/app/views/supabase/rails/passwords/new.html.erb

@@ -0,0 +1,11 @@
+<h1>Forgot your password?</h1>
+
+<%= render "supabase/rails/shared/flash" %>
+
+<%= form_with url: passwords_path do |form| %>
+  <%= form.email_field :email, required: true, autofocus: true, autocomplete: "username", placeholder: "Enter your email address", value: params[:email] %><br>
+  <%= form.submit "Email reset instructions" %>
+<% end %>
+<br>
+
+<%= link_to "Back to sign in", new_session_path %>

data/app/views/supabase/rails/registrations/new.html.erb

@@ -0,0 +1,12 @@
+<h1>Create an account</h1>
+
+<%= render "supabase/rails/shared/flash" %>
+
+<%= form_with url: registration_path do |form| %>
+  <%= form.email_field :email, required: true, autofocus: true, autocomplete: "username", placeholder: "Enter your email address", value: params[:email] %><br>
+  <%= form.password_field :password, required: true, autocomplete: "new-password", placeholder: "Choose a password", maxlength: 72 %><br>
+  <%= form.submit "Sign up" %>
+<% end %>
+<br>
+
+<%= link_to "Already have an account? Sign in", new_session_path %>

data/app/views/supabase/rails/sessions/new.html.erb

@@ -0,0 +1,15 @@
+<h1>Sign in</h1>
+
+<%= render "supabase/rails/shared/flash" %>
+
+<%= form_with url: session_path do |form| %>
+  <%= form.email_field :email, required: true, autofocus: true, autocomplete: "username", placeholder: "Enter your email address", value: params[:email] %><br>
+  <%= form.password_field :password, required: true, autocomplete: "current-password", placeholder: "Enter your password", maxlength: 72 %><br>
+  <%= form.submit "Sign in" %>
+<% end %>
+<br>
+
+<%= link_to "Forgot password?", new_password_path %><br>
+<%= link_to "Create an account", new_registration_path %>
+
+<%= render "supabase/rails/oauth/buttons" %>

data/app/views/supabase/rails/shared/_flash.html.erb

@@ -0,0 +1,5 @@
+<%# Flash partial — shared by every gem-shipped view. Uses the conventional
+   `notice` / `alert` keys (AC-4). Hosts can override this partial by shipping
+   their own at `app/views/supabase/rails/shared/_flash.html.erb`. %>
+<%= tag.div(flash[:alert], style: "color:red") if flash[:alert] %>
+<%= tag.div(flash[:notice], style: "color:green") if flash[:notice] %>

data/config/locales/en.yml

@@ -0,0 +1,19 @@
+en:
+  supabase:
+    rails:
+      sessions:
+        created: "Signed in successfully."
+        invalid: "Try another email address or password."
+        destroyed: "Signed out successfully."
+      registrations:
+        created: "Welcome — your account is ready."
+        pending_confirmation: "Check your inbox to confirm your email before signing in."
+      passwords:
+        reset_sent: "Check your inbox for a password-reset link."
+        updated: "Password updated. Sign in with your new password."
+      otp:
+        sent: "We sent you a code — enter it below."
+        verified: "Signed in successfully."
+      oauth:
+        failed: "We couldn't start that sign-in. Please try again."
+        connected: "Signed in successfully."

data/lib/generators/supabase/install/install_generator.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Supabase
+  module Generators
+    # `rails g supabase:install` (FR-W12 / US-018).
+    #
+    # Emits the host-app glue for `:web` mode: an `Authentication` concern
+    # that includes the gem's module, five near-empty controllers that
+    # subclass the gem's `Supabase::Rails::*Controller` base classes, a
+    # `Current` model, and a config initializer. Also patches
+    # `config/routes.rb` (adds `supabase_authentication_routes`) and
+    # `app/controllers/application_controller.rb` (adds `include Authentication`).
+    #
+    # Idempotent — Thor's `template` + `inject_into_file` skip writes when
+    # the target already matches the desired content, and prompt the user
+    # to overwrite when files diverge from the gem's defaults.
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc <<~DESC
+        Installs Supabase-backed authentication into the host app.
+
+        Emits an Authentication concern, controllers, a Current model, and
+        a config initializer, then patches config/routes.rb and
+        application_controller.rb to wire them up.
+      DESC
+
+      def create_authentication_concern
+        template "app/controllers/concerns/authentication.rb.tt",
+                 "app/controllers/concerns/authentication.rb"
+      end
+
+      def create_controllers
+        %w[sessions registrations passwords otp oauth].each do |name|
+          template "app/controllers/#{name}_controller.rb.tt",
+                   "app/controllers/#{name}_controller.rb"
+        end
+      end
+
+      def create_current_model
+        template "app/models/current.rb.tt", "app/models/current.rb"
+      end
+
+      def create_initializer
+        template "config/initializers/supabase.rb.tt",
+                 "config/initializers/supabase.rb"
+      end
+
+      def patch_routes
+        routes_path = "config/routes.rb"
+        return unless File.exist?(File.expand_path(routes_path, destination_root))
+        return if routes_already_patched?(routes_path)
+
+        inject_into_file routes_path,
+                         "  supabase_authentication_routes\n",
+                         after: "Rails.application.routes.draw do\n"
+      end
+
+      def patch_application_controller
+        app_controller_path = "app/controllers/application_controller.rb"
+        return unless File.exist?(File.expand_path(app_controller_path, destination_root))
+        return if application_controller_already_patched?(app_controller_path)
+
+        inject_into_class app_controller_path, "ApplicationController" do
+          "  include Authentication\n"
+        end
+      end
+
+      private
+
+      def routes_already_patched?(routes_path)
+        absolute = File.expand_path(routes_path, destination_root)
+        File.read(absolute).include?("supabase_authentication_routes")
+      end
+
+      def application_controller_already_patched?(app_controller_path)
+        absolute = File.expand_path(app_controller_path, destination_root)
+        File.read(absolute).include?("include Authentication")
+      end
+    end
+  end
+end

data/lib/generators/supabase/install/templates/app/controllers/concerns/authentication.rb.tt

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Authentication
+  extend ActiveSupport::Concern
+
+  included do
+    include Supabase::Rails::Authentication
+  end
+end

data/lib/generators/supabase/install/templates/app/controllers/oauth_controller.rb.tt

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class OauthController < Supabase::Rails::OauthController
+end

data/lib/generators/supabase/install/templates/app/controllers/otp_controller.rb.tt

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class OtpController < Supabase::Rails::OtpController
+end

data/lib/generators/supabase/install/templates/app/controllers/passwords_controller.rb.tt

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class PasswordsController < Supabase::Rails::PasswordsController
+end

data/lib/generators/supabase/install/templates/app/controllers/registrations_controller.rb.tt

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class RegistrationsController < Supabase::Rails::RegistrationsController
+end

data/lib/generators/supabase/install/templates/app/controllers/sessions_controller.rb.tt

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class SessionsController < Supabase::Rails::SessionsController
+end

data/lib/generators/supabase/install/templates/app/models/current.rb.tt

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Current < ActiveSupport::CurrentAttributes
+  attribute :user, :session
+end

data/lib/generators/supabase/install/templates/config/initializers/supabase.rb.tt

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+Rails.application.config.supabase.mode = :web
+
+# Origins the OAuth + password-reset helpers will accept as redirect targets.
+# Path-only redirects are always allowed; absolute URLs must match an entry
+# below. Defaults to [request.host] at runtime when this list is empty.
+# Rails.application.config.supabase.allowed_redirect_origins = ["https://example.com"]
+
+# Expose `current_user` as a view helper. nil = derive from mode
+# (true in :web, false in :api).
+# Rails.application.config.supabase.expose_current_user = nil
+
+# Encrypted session cookie defaults. `secure: nil` = auto-detect from Rails.env.
+# Rails.application.config.supabase.session = {
+#   cookie_name: "sb-session",
+#   same_site:   :lax,
+#   secure:      nil,
+#   domain:      nil,
+#   path:        "/"
+# }

data/lib/generators/supabase/user_model/templates/app/models/user.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class User < ApplicationRecord
+  self.primary_key = :id
+
+  def self.from_supabase(claims)
+    find_or_create_by!(id: claims["sub"]) do |u|
+      u.email = claims["email"]
+    end
+  end
+end

data/lib/generators/supabase/user_model/templates/db/migrate/create_supabase_users.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class CreateSupabaseUsers < ActiveRecord::Migration[7.1]
+  def change
+    create_table :users, id: :uuid do |t|
+      t.string :email
+
+      t.timestamps
+    end
+  end
+end

data/lib/generators/supabase/user_model/user_model_generator.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/migration"
+require "active_support/core_ext/string/strip"
+
+module Supabase
+  module Generators
+    # `rails g supabase:user_model` (FR-W14 / US-025).
+    #
+    # Opt-in shadow `User` ActiveRecord model. Emits a `users` migration
+    # with a UUID primary key matching Supabase's `user.id`, an AR model
+    # with a `from_supabase(claims)` upsert helper, and patches the
+    # `config/initializers/supabase.rb` to set
+    # `config.supabase.user_model = "User"` so the Authentication concern
+    # (US-016) substitutes the AR record for `Current.user`.
+    class UserModelGenerator < ::Rails::Generators::Base
+      include ::Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc <<~DESC
+        Installs an opt-in shadow `User` AR model backed by a UUID-keyed
+        `users` table that mirrors Supabase auth.users.
+
+        Emits a migration, an `app/models/user.rb` with a `from_supabase`
+        upsert, and patches `config/initializers/supabase.rb` to set
+        `config.supabase.user_model = "User"`.
+      DESC
+
+      # Rails' built-in timestamp for migration filenames. Mirrors what
+      # `ActiveRecord::Generators::Migration#next_migration_number` does
+      # so the generator works standalone (without ActiveRecord loaded).
+      def self.next_migration_number(_dirname)
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+
+      def create_migration_file
+        migration_template "db/migrate/create_supabase_users.rb.tt",
+                           "db/migrate/create_supabase_users.rb"
+      end
+
+      def create_user_model
+        template "app/models/user.rb.tt", "app/models/user.rb"
+      end
+
+      def patch_initializer
+        initializer_path = "config/initializers/supabase.rb"
+        return unless File.exist?(File.expand_path(initializer_path, destination_root))
+        return if initializer_already_patched?(initializer_path)
+
+        append_to_file initializer_path,
+                       %(\nRails.application.config.supabase.user_model = "User"\n)
+      end
+
+      private
+
+      def initializer_already_patched?(initializer_path)
+        absolute = File.expand_path(initializer_path, destination_root)
+        File.read(absolute).match?(/^\s*[^#\n]*config\.supabase\.user_model\s*=/)
+      end
+    end
+  end
+end