supabase-auth 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4f59194c543746f17fee64c695a67376d979b29d84cef81927f2e0ee28b2c3c0
+  data.tar.gz: 0645f3fa4daca0abd64124e61735f2b95e04fca4b2a9395e519882fd15b50150
+SHA512:
+  metadata.gz: 95dec921b37d44b44a94f36dcc9ab5e6466a2f9fc774657f2b526c003cba2acf867ed2103093ff5b2bd4b01064f8db271b5298f07b6dab5621cc83e511679d67
+  data.tar.gz: 10a3996b51836f65cbabc33514ae57c1a11f997b35885144bd818a208f8625e65138231fe335b9b5cf65c89cf7872702927600b4abd779c571ed9bb30dd392a5

data/README.md

@@ -0,0 +1,233 @@
+# supabase-auth
+
+[![Gem Version](https://img.shields.io/gem/v/supabase-auth)](https://rubygems.org/gems/supabase-auth)
+[![CI](https://github.com/supabase/supabase-rb/actions/workflows/ci.yml/badge.svg)](https://github.com/supabase/supabase-rb/actions/workflows/ci.yml)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0-red)](https://www.ruby-lang.org)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Ruby client for [Supabase Auth](https://supabase.com/docs/guides/auth) (GoTrue API).
+
+## Features
+
+- Email/password, phone, and anonymous sign-in
+- OAuth and SSO provider support
+- Magic link and OTP verification
+- PKCE authentication flow
+- MFA (TOTP and phone)
+- JWT verification with JWKS support
+- Session management with auto-refresh
+- Admin API for user management
+- Auth state change subscriptions
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "supabase-auth"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+```ruby
+require "supabase/auth"
+
+client = Supabase::Auth::Client.new(
+  url: "https://your-project.supabase.co/auth/v1",
+  headers: { "apiKey" => "your-anon-key" }
+)
+
+# Sign up
+response = client.sign_up(email: "user@example.com", password: "secure-password")
+
+# Sign in
+response = client.sign_in_with_password(email: "user@example.com", password: "secure-password")
+
+# Get session and user
+session = client.get_session
+user = client.get_user
+```
+
+## Usage
+
+### Authentication
+
+```ruby
+# Email/password
+client.sign_in_with_password(email: "user@example.com", password: "password")
+
+# Magic link (OTP)
+client.sign_in_with_otp(email: "user@example.com")
+
+# Phone OTP
+client.sign_in_with_otp(phone: "+1234567890")
+
+# OAuth
+response = client.sign_in_with_oauth(provider: "google")
+
+# SSO
+response = client.sign_in_with_sso(domain: "company.com")
+
+# ID token (e.g. from Google Sign-In)
+response = client.sign_in_with_id_token(provider: "google", token: "id-token")
+
+# Anonymous
+response = client.sign_in_anonymously
+
+# Sign out
+client.sign_out
+```
+
+### Session Management
+
+```ruby
+# Set session from existing tokens
+client.set_session("access_token", "refresh_token")
+
+# Refresh session
+client.refresh_session
+
+# Exchange code for session (PKCE)
+client.exchange_code_for_session(auth_code: "code")
+
+# Listen for auth state changes
+subscription = client.on_auth_state_change do |event, session|
+  puts "Auth event: #{event}"
+end
+
+# Unsubscribe
+subscription.unsubscribe.call
+```
+
+Auth events: `SIGNED_IN`, `SIGNED_OUT`, `TOKEN_REFRESHED`, `USER_UPDATED`, `MFA_CHALLENGE_VERIFIED`, `PASSWORD_RECOVERY`
+
+### User Management
+
+```ruby
+# Get current user
+user = client.get_user
+
+# Update user
+client.update_user(data: { name: "Jane Doe" })
+
+# Reset password
+client.reset_password_for_email("user@example.com")
+
+# Verify OTP
+client.verify_otp(type: "email", email: "user@example.com", token: "123456")
+
+# Identity linking
+client.link_identity(provider: "github")
+client.unlink_identity(identity)
+```
+
+### MFA (Multi-Factor Authentication)
+
+```ruby
+# Enroll a TOTP factor
+enrolled = client.mfa.enroll(factor_type: "totp")
+
+# Challenge
+challenge = client.mfa.challenge(factor_id: enrolled["id"])
+
+# Verify
+client.mfa.verify(factor_id: enrolled["id"], challenge_id: challenge.id, code: "123456")
+
+# List factors
+factors = client.mfa.list_factors
+
+# Get assurance level
+aal = client.mfa.get_authenticator_assurance_level
+
+# Unenroll
+client.mfa.unenroll(factor_id: enrolled["id"])
+```
+
+### JWT Verification
+
+```ruby
+# Verify and extract JWT claims (supports HS256, RS256, ES256, PS256+)
+claims = client.get_claims(jwt: "eyJhbG...")
+claims.claims  # decoded payload
+claims.headers # JWT headers
+```
+
+### Admin API
+
+Requires a service role key.
+
+```ruby
+admin = Supabase::Auth::AdminApi.new(
+  url: "https://your-project.supabase.co/auth/v1",
+  headers: { "Authorization" => "Bearer #{service_role_key}", "apiKey" => service_role_key }
+)
+
+# CRUD operations
+user = admin.create_user(email: "new@example.com", password: "password")
+users = admin.list_users(page: 1, per_page: 50)
+user = admin.get_user_by_id("uuid")
+admin.update_user_by_id("uuid", email: "updated@example.com")
+admin.delete_user("uuid")
+
+# Invite user
+admin.invite_user_by_email("user@example.com")
+
+# Generate links
+admin.generate_link(type: "signup", email: "user@example.com", password: "password")
+
+# Sign out a user
+admin.sign_out("access_token")
+```
+
+### Configuration Options
+
+```ruby
+client = Supabase::Auth::Client.new(
+  url: "https://your-project.supabase.co/auth/v1",
+  headers: { "apiKey" => "your-anon-key" },
+  auto_refresh_token: true,    # Auto-refresh expiring tokens (default: true)
+  persist_session: true,        # Persist session to storage (default: true)
+  detect_session_in_url: true,  # Detect OAuth callback in URL (default: true)
+  flow_type: "implicit",        # "implicit" or "pkce" (default: "implicit")
+  storage: custom_storage        # Custom storage backend (default: in-memory)
+)
+```
+
+## Development
+
+### Prerequisites
+
+- Ruby >= 3.0
+- Docker & Docker Compose (for integration tests)
+
+### Setup
+
+```bash
+bundle install
+```
+
+### Running Tests
+
+Start the GoTrue infrastructure:
+
+```bash
+docker compose -f infra/docker-compose.yml up -d
+```
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+Coverage reports are generated automatically via SimpleCov. After running tests, open `coverage/index.html`.
+
+## License
+
+MIT

data/lib/supabase/auth/admin_api.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Supabase
+  module Auth
+    # Admin API for managing users with a service role key.
+    # Provides CRUD operations on users, link generation, and MFA management.
+    class AdminApi < Api
+      # @param url [String] The GoTrue API base URL
+      # @param headers [Hash] Headers including Authorization bearer token
+      # @param http_client [Faraday::Connection, nil] Optional custom Faraday client
+      def initialize(url:, headers: {}, http_client: nil)
+        super(url: url, headers: headers, http_client: http_client)
+      end
+
+      # Creates a new user via the admin API.
+      # @param attributes [Hash] user attributes (email, password, user_metadata, app_metadata, etc.)
+      # @return [Types::UserResponse]
+      def create_user(attributes)
+        data = post("admin/users", body: attributes)
+        Helpers.parse_user_response(data)
+      end
+
+      # Lists all users.
+      # @param page [Integer, nil] page number
+      # @param per_page [Integer, nil] users per page
+      # @return [Array<Types::User>]
+      def list_users(page: nil, per_page: nil)
+        params = {}
+        params[:page] = page if page
+        params[:per_page] = per_page if per_page
+        data = get("admin/users", params: params)
+        users = data["users"] || []
+        users.map { |u| Types::User.from_hash(u) }
+      end
+
+      # Gets a user by their ID.
+      # @param uid [String] user UUID
+      # @return [Types::UserResponse]
+      # @raise [ArgumentError] if uid is not a valid UUID
+      def get_user_by_id(uid)
+        _validate_uuid(uid)
+        data = get("admin/users/#{uid}")
+        Helpers.parse_user_response(data)
+      end
+
+      # Updates a user by their ID.
+      # @param uid [String] user UUID
+      # @param attributes [Hash] attributes to update
+      # @return [Types::UserResponse]
+      # @raise [ArgumentError] if uid is not a valid UUID
+      def update_user_by_id(uid, attributes)
+        _validate_uuid(uid)
+        data = put("admin/users/#{uid}", body: attributes)
+        Helpers.parse_user_response(data)
+      end
+
+      # Deletes a user by their ID.
+      # @param uid [String] user UUID
+      # @param should_soft_delete [Boolean] soft delete instead of hard delete
+      # @raise [ArgumentError] if uid is not a valid UUID
+      def delete_user(uid, should_soft_delete: false)
+        _validate_uuid(uid)
+        _request("DELETE", "admin/users/#{uid}", body: { should_soft_delete: should_soft_delete })
+      end
+
+      # Generates email links and OTPs.
+      def generate_link(params)
+        options = params[:options] || params["options"] || {}
+        body = {
+          type: params[:type] || params["type"],
+          email: params[:email] || params["email"],
+          password: params[:password] || params["password"],
+          new_email: params[:new_email] || params["new_email"],
+          data: options[:data] || options["data"]
+        }
+        redirect_to = options[:redirect_to] || options["redirect_to"]
+        query = {}
+        query["redirect_to"] = redirect_to if redirect_to
+        data = post("admin/generate_link", body: body, params: query)
+        Helpers.parse_link_response(data)
+      end
+
+      # Invites a user by email.
+      def invite_user_by_email(email, options = {})
+        body = { email: email, data: options[:data] || options["data"] }
+        redirect_to = options[:redirect_to] || options["redirect_to"]
+        query = {}
+        query["redirect_to"] = redirect_to if redirect_to
+        data = post("invite", body: body, params: query)
+        Helpers.parse_user_response(data)
+      end
+
+      # Signs out a user by revoking their session via the admin API.
+      def sign_out(access_token, scope = "global")
+        _request("POST", "logout", jwt: access_token, params: { "scope" => scope }, no_resolve_json: true)
+      end
+
+      # Lists MFA factors for a user (admin).
+      # @param params [Hash] :user_id (required)
+      # @return [Types::AuthMFAAdminListFactorsResponse]
+      def _list_factors(params)
+        user_id = params[:user_id] || params["user_id"]
+        _validate_uuid(user_id)
+        data = get("admin/users/#{user_id}/factors")
+        Types::AuthMFAAdminListFactorsResponse.from_hash(data)
+      end
+
+      # Deletes an MFA factor for a user (admin).
+      # @param params [Hash] :user_id and :id (both required)
+      # @return [Types::AuthMFAAdminDeleteFactorResponse]
+      def _delete_factor(params)
+        user_id = params[:user_id] || params["user_id"]
+        factor_id = params[:id] || params["id"]
+        _validate_uuid(user_id)
+        _validate_uuid(factor_id)
+        data = delete("admin/users/#{user_id}/factors/#{factor_id}")
+        Types::AuthMFAAdminDeleteFactorResponse.from_hash(data)
+      end
+    end
+  end
+end

data/lib/supabase/auth/api.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Supabase
+  module Auth
+    class Api
+      CONTENT_TYPE = "application/json;charset=UTF-8"
+      UUID_REGEX = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+
+      attr_reader :url, :headers
+
+      # @param url [String] The GoTrue API base URL
+      # @param headers [Hash] Default headers to include on every request (e.g., apikey)
+      # @param http_client [Faraday::Connection, nil] Optional custom Faraday client
+      def initialize(url:, headers: {}, http_client: nil)
+        @url = url
+        @headers = headers
+        @http_client = http_client
+      end
+
+      # Central HTTP dispatch method. Builds URL, merges headers (including API version
+      # and Authorization), handles redirect_to as query param, parses JSON, applies
+      # optional transform, and maps errors via Helpers.handle_exception.
+      #
+      # @param method [String, Symbol] HTTP method (GET, POST, PUT, DELETE)
+      # @param path [String] Request path (relative to base URL)
+      # @param jwt [String, nil] Bearer token for Authorization header
+      # @param body [Hash, nil] Request body (serialized to JSON)
+      # @param params [Hash] Query parameters
+      # @param headers [Hash] Additional headers for this request
+      # @param redirect_to [String, nil] If present, added as redirect_to query param
+      # @param xform [Proc, nil] Optional transform function applied to parsed response
+      # @param no_resolve_json [Boolean] If true, return raw Faraday::Response
+      # @return [Hash, Object] Parsed JSON response, transformed result, or raw response
+      def _request(method, path, jwt: nil, body: nil, params: {}, headers: {}, redirect_to: nil, xform: nil, no_resolve_json: false)
+        merged_headers = @headers.merge(headers)
+        merged_headers["Content-Type"] ||= CONTENT_TYPE
+        merged_headers[Constants::API_VERSION_HEADER_NAME] ||= Constants::API_VERSIONS.keys.last
+        merged_headers["Authorization"] = "Bearer #{jwt}" if jwt
+
+        query = params.dup
+        query["redirect_to"] = redirect_to if redirect_to
+
+        full_path = build_path(path)
+        json_body = body ? JSON.generate(body) : nil
+
+        response = connection.run_request(method.to_s.downcase.to_sym, full_path, json_body, merged_headers) do |req|
+          req.params.update(query) unless query.empty?
+        end
+
+        result = no_resolve_json ? response : parse_response(response)
+
+        xform ? xform.call(result) : result
+      rescue Faraday::Error => e
+        raise Helpers.handle_exception(e)
+      rescue StandardError => e
+        raise Helpers.handle_exception(e)
+      end
+
+      # @param id [String] UUID to validate
+      # @raise [ArgumentError] if not a valid UUID format
+      def _validate_uuid(id)
+        unless id.is_a?(String) && id.match?(UUID_REGEX)
+          raise ArgumentError, "Invalid id, '#{id}' is not a valid uuid"
+        end
+      end
+
+      # Convenience methods that delegate to _request
+
+      def get(path, headers: {}, params: {})
+        _request(:get, path, headers: headers, params: params)
+      end
+
+      def post(path, body: {}, headers: {}, params: {})
+        _request(:post, path, body: body, headers: headers, params: params)
+      end
+
+      def put(path, body: {}, headers: {}, params: {})
+        _request(:put, path, body: body, headers: headers, params: params)
+      end
+
+      def delete(path, headers: {}, params: {})
+        _request(:delete, path, headers: headers, params: params)
+      end
+
+      private
+
+      def connection
+        @connection ||= @http_client || build_connection
+      end
+
+      def build_connection
+        Faraday.new(url: @url) do |f|
+          f.response :raise_error
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      def build_path(path)
+        base_path = URI.parse(@url).path.chomp("/")
+        "#{base_path}/#{path.sub(%r{^/}, '')}"
+      end
+
+      def parse_response(response)
+        return {} if response.body.nil? || response.body.empty?
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end