better_auth 0.4.0 → 0.5.0

data/lib/better_auth/plugins/dub.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Plugins
+    module_function
+
+    def dub(options = {})
+      config = normalize_hash(options)
+      oauth_plugin = dub_oauth_plugin(config[:oauth])
+      endpoints = {dub_link: dub_link_endpoint(oauth_plugin)}
+      endpoints[:dub_o_auth2_callback] = oauth_plugin.endpoints.fetch(:o_auth2_callback) if oauth_plugin
+
+      Plugin.new(
+        id: "dub",
+        endpoints: endpoints,
+        init: ->(_context) {
+          {
+            options: {
+              database_hooks: {
+                user: {
+                  create: {
+                    after: ->(user, ctx) { dub_track_lead(config, user, ctx) }
+                  }
+                }
+              }
+            }
+          }
+        },
+        options: config
+      )
+    end
+
+    def dub_link_endpoint(oauth_plugin)
+      Endpoint.new(
+        path: "/dub/link",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "dubLink",
+            description: "Link a Dub OAuth account",
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Authorization URL generated successfully for linking a Dub account",
+                OpenAPI.object_schema(
+                  {
+                    url: {type: "string"},
+                    redirect: {type: "boolean"}
+                  },
+                  required: ["url", "redirect"]
+                )
+              )
+            }
+          }
+        }
+      ) do |ctx|
+        unless oauth_plugin
+          raise APIError.new("NOT_FOUND", message: "Dub OAuth is not configured")
+        end
+
+        body = normalize_hash(ctx.body)
+        callback_url = body[:callback_url] || body[:callbackURL]
+        if callback_url.to_s.empty?
+          raise APIError.new("BAD_REQUEST", message: BASE_ERROR_CODES["VALIDATION_ERROR"])
+        end
+        Routes.validate_auth_callback_url!(ctx.context, callback_url, "callbackURL")
+
+        ctx.body = body.merge(provider_id: "dub", callback_url: callback_url)
+        oauth_plugin.endpoints.fetch(:o_auth2_link_account).call(ctx)
+      end
+    end
+
+    def dub_oauth_plugin(oauth_options)
+      oauth = normalize_hash(oauth_options || {})
+      return nil if oauth.empty?
+
+      generic_oauth(
+        config: [
+          {
+            provider_id: "dub",
+            authorization_url: "https://app.dub.co/oauth/authorize",
+            token_url: "https://api.dub.co/oauth/token",
+            client_id: oauth[:client_id],
+            client_secret: oauth[:client_secret],
+            pkce: oauth.key?(:pkce) ? oauth[:pkce] : true
+          }
+        ]
+      )
+    end
+
+    def dub_track_lead(config, user, ctx)
+      return unless ctx
+
+      dub_id = ctx.get_cookie("dub_id")
+      return if dub_id.to_s.empty?
+      return if config[:disable_lead_tracking]
+
+      custom = config[:custom_lead_track]
+      if custom.respond_to?(:call)
+        custom.call(user, ctx)
+      else
+        dub_default_lead_track(config, user, dub_id, ctx)
+      end
+
+      ctx.set_cookie("dub_id", "", expires: Time.at(0), max_age: 0)
+    end
+
+    def dub_default_lead_track(config, user, dub_id, ctx)
+      track = config[:dub_client]&.track
+      return unless track&.respond_to?(:lead)
+
+      dub_invoke_lead(
+        track,
+        click_id: dub_id,
+        event_name: config[:lead_event_name] || "Sign Up",
+        customer_external_id: fetch_value(user, "id"),
+        customer_name: fetch_value(user, "name"),
+        customer_email: fetch_value(user, "email"),
+        customer_avatar: fetch_value(user, "image")
+      )
+    rescue => error
+      dub_log_error(ctx, error)
+    end
+
+    def dub_log_error(ctx, error)
+      logger = ctx.context.logger
+      if logger.respond_to?(:error)
+        logger.error(error)
+      elsif logger.respond_to?(:call)
+        logger.call(:error, error)
+      end
+    end
+
+    def dub_invoke_lead(track, payload)
+      if track.method(:lead).parameters.any? { |type, name| [:key, :keyreq].include?(type) && name == :request }
+        track.lead(request: dub_lead_request_body(payload))
+      else
+        track.lead(payload)
+      end
+    end
+
+    def dub_lead_request_body(payload)
+      klass = defined?(::OpenApiSDK::Models::Operations::TrackLeadRequestBody) && ::OpenApiSDK::Models::Operations::TrackLeadRequestBody
+      return payload unless klass
+
+      klass.new(**payload)
+    end
+  end
+end

data/lib/better_auth/plugins/email_otp.rb

@@ -77,7 +77,28 @@ module BetterAuth
     end
 
     def send_verification_otp_endpoint(config)
-      Endpoint.new(path: "/email-otp/send-verification-otp", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/email-otp/send-verification-otp",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "sendVerificationOTP",
+            description: "Send an email verification OTP",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  email: {type: "string"},
+                  type: {type: "string", enum: ["email-verification", "sign-in", "forget-password"]}
+                },
+                required: ["email", "type"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response("OTP sent", OpenAPI.success_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         body = normalize_hash(ctx.body)
         email = body[:email].to_s.downcase
         type = body[:type].to_s
@@ -111,7 +132,30 @@ module BetterAuth
     end
 
     def get_verification_otp_endpoint(config)
-      Endpoint.new(path: "/email-otp/get-verification-otp", method: "GET") do |ctx|
+      Endpoint.new(
+        path: "/email-otp/get-verification-otp",
+        method: "GET",
+        metadata: {
+          openapi: {
+            operationId: "getVerificationOTP",
+            description: "Get a stored verification OTP when storage allows plaintext access",
+            parameters: [
+              {name: "email", in: "query", required: true, schema: {type: "string"}},
+              {name: "type", in: "query", required: true, schema: {type: "string"}}
+            ],
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Stored OTP",
+                OpenAPI.object_schema(
+                  {
+                    otp: {type: ["string", "null"]}
+                  }
+                )
+              )
+            }
+          }
+        }
+      ) do |ctx|
         query = normalize_hash(ctx.query)
         email = query[:email].to_s.downcase
         type = query[:type].to_s
@@ -124,7 +168,7 @@ module BetterAuth
         when "hashed"
           raise APIError.new("BAD_REQUEST", message: "OTP is hashed, cannot return the plain text OTP")
         when "encrypted"
-          next ctx.json({otp: Crypto.symmetric_decrypt(key: ctx.context.secret, data: stored_otp)})
+          next ctx.json({otp: Crypto.symmetric_decrypt(key: ctx.context.secret_config, data: stored_otp)})
         end
 
         storage = config[:store_otp]
@@ -139,7 +183,29 @@ module BetterAuth
     end
 
     def check_verification_otp_endpoint(config)
-      Endpoint.new(path: "/email-otp/check-verification-otp", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/email-otp/check-verification-otp",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "checkVerificationOTP",
+            description: "Check an email verification OTP without consuming it",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  email: {type: "string"},
+                  type: {type: "string"},
+                  otp: {type: "string"}
+                },
+                required: ["email", "type", "otp"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response("OTP is valid", OpenAPI.success_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         body = normalize_hash(ctx.body)
         email = body[:email].to_s.downcase
         type = body[:type].to_s
@@ -154,7 +220,38 @@ module BetterAuth
     end
 
     def verify_email_otp_endpoint(config)
-      Endpoint.new(path: "/email-otp/verify-email", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/email-otp/verify-email",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "verifyEmailOTP",
+            description: "Verify an email address with an OTP",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  email: {type: "string"},
+                  otp: {type: "string"}
+                },
+                required: ["email", "otp"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Email verified",
+                OpenAPI.object_schema(
+                  {
+                    status: {type: "boolean"},
+                    token: {type: ["string", "null"]},
+                    user: {type: "object", "$ref": "#/components/schemas/User"}
+                  },
+                  required: ["status", "user"]
+                )
+              )
+            }
+          }
+        }
+      ) do |ctx|
         body = normalize_hash(ctx.body)
         email = body[:email].to_s.downcase
         otp = body[:otp].to_s
@@ -183,7 +280,37 @@ module BetterAuth
     end
 
     def sign_in_email_otp_endpoint(config)
-      Endpoint.new(path: "/sign-in/email-otp", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/sign-in/email-otp",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "signInEmailOTP",
+            description: "Sign in with an email OTP",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  email: {type: "string"},
+                  otp: {type: "string"}
+                },
+                required: ["email", "otp"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Signed in",
+                OpenAPI.object_schema(
+                  {
+                    token: {type: "string"},
+                    user: {type: "object", "$ref": "#/components/schemas/User"}
+                  },
+                  required: ["token", "user"]
+                )
+              )
+            }
+          }
+        }
+      ) do |ctx|
         body = normalize_hash(ctx.body)
         email = body[:email].to_s.downcase
         otp = body[:otp].to_s
@@ -195,7 +322,7 @@ module BetterAuth
         else
           raise APIError.new("BAD_REQUEST", message: EMAIL_OTP_ERROR_CODES["INVALID_OTP"]) if config[:disable_sign_up]
 
-          ctx.context.internal_adapter.create_user(email_otp_sign_up_user_data(ctx, body, email))
+          ctx.context.internal_adapter.create_user(email_otp_sign_up_user_data(ctx, body, email), context: ctx)
         end
 
         unless user["emailVerified"]
@@ -209,7 +336,28 @@ module BetterAuth
     end
 
     def request_email_change_email_otp_endpoint(config)
-      Endpoint.new(path: "/email-otp/request-email-change", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/email-otp/request-email-change",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "requestEmailChangeOTP",
+            description: "Request an OTP to change the current user's email",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  newEmail: {type: "string"},
+                  otp: {type: ["string", "null"]}
+                },
+                required: ["newEmail"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response("Change email OTP sent", OpenAPI.success_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         email_otp_change_email_enabled!(config)
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
@@ -235,7 +383,28 @@ module BetterAuth
     end
 
     def change_email_email_otp_endpoint(config)
-      Endpoint.new(path: "/email-otp/change-email", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/email-otp/change-email",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "changeEmailWithEmailOTP",
+            description: "Change the current user's email with an OTP",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  newEmail: {type: "string"},
+                  otp: {type: "string"}
+                },
+                required: ["newEmail", "otp"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response("Email changed", OpenAPI.success_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         email_otp_change_email_enabled!(config)
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
@@ -259,19 +428,81 @@ module BetterAuth
     end
 
     def request_password_reset_email_otp_endpoint(config)
-      Endpoint.new(path: "/email-otp/request-password-reset", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/email-otp/request-password-reset",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "requestPasswordResetEmailOTP",
+            description: "Request a password reset OTP by email",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  email: {type: "string"}
+                },
+                required: ["email"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response("Password reset OTP requested", OpenAPI.status_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         email_otp_password_reset_request(ctx, config)
       end
     end
 
     def forget_password_email_otp_endpoint(config)
-      Endpoint.new(path: "/forget-password/email-otp", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/forget-password/email-otp",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "forgetPasswordEmailOTP",
+            description: "Request a password reset OTP by email",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  email: {type: "string"}
+                },
+                required: ["email"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response("Password reset OTP requested", OpenAPI.status_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         email_otp_password_reset_request(ctx, config)
       end
     end
 
     def reset_password_email_otp_endpoint(config)
-      Endpoint.new(path: "/email-otp/reset-password", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/email-otp/reset-password",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "resetPasswordEmailOTP",
+            description: "Reset a password with an email OTP",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  email: {type: "string"},
+                  otp: {type: "string"},
+                  password: {type: "string"}
+                },
+                required: ["email", "otp", "password"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response("Password reset", OpenAPI.status_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         body = normalize_hash(ctx.body)
         email = body[:email].to_s.downcase
         otp = body[:otp].to_s
@@ -445,7 +676,7 @@ module BetterAuth
     def email_otp_stored_value(ctx, config, otp)
       storage = config[:store_otp]
       return Crypto.sha256(otp, encoding: :base64url) if storage.to_s == "hashed"
-      return Crypto.symmetric_encrypt(key: ctx.context.secret, data: otp) if storage.to_s == "encrypted"
+      return Crypto.symmetric_encrypt(key: ctx.context.secret_config, data: otp) if storage.to_s == "encrypted"
 
       if storage.is_a?(Hash)
         return storage[:hash].call(otp) if storage[:hash].respond_to?(:call)
@@ -460,7 +691,7 @@ module BetterAuth
       actual, expected = if storage.to_s == "hashed"
         [Crypto.sha256(otp, encoding: :base64url), stored_otp]
       elsif storage.to_s == "encrypted"
-        [Crypto.symmetric_decrypt(key: ctx.context.secret, data: stored_otp), otp]
+        [Crypto.symmetric_decrypt(key: ctx.context.secret_config, data: stored_otp), otp]
       elsif storage.is_a?(Hash) && storage[:hash].respond_to?(:call)
         [storage[:hash].call(otp), stored_otp]
       elsif storage.is_a?(Hash) && storage[:decrypt].respond_to?(:call)
@@ -477,7 +708,7 @@ module BetterAuth
     def email_otp_plain_value(ctx, config, stored_otp)
       storage = config[:store_otp]
       return stored_otp if storage.to_s == "plain" || storage.nil?
-      return Crypto.symmetric_decrypt(key: ctx.context.secret, data: stored_otp) if storage.to_s == "encrypted"
+      return Crypto.symmetric_decrypt(key: ctx.context.secret_config, data: stored_otp) if storage.to_s == "encrypted"
       return storage[:decrypt].call(stored_otp) if storage.is_a?(Hash) && storage[:decrypt].respond_to?(:call)
 
       nil

data/lib/better_auth/plugins/expo.rb

@@ -29,7 +29,23 @@ module BetterAuth
     end
 
     def expo_authorization_proxy_endpoint
-      Endpoint.new(path: "/expo-authorization-proxy", method: "GET") do |ctx|
+      Endpoint.new(
+        path: "/expo-authorization-proxy",
+        method: "GET",
+        metadata: {
+          openapi: {
+            operationId: "expoAuthorizationProxy",
+            description: "Proxy an Expo authorization redirect",
+            parameters: [
+              {in: "query", name: "authorizationURL", required: true, schema: {type: "string", format: "uri"}},
+              {in: "query", name: "oauthState", required: false, schema: {type: "string"}}
+            ],
+            responses: {
+              "302" => {description: "Redirects to the authorization URL"}
+            }
+          }
+        }
+      ) do |ctx|
         authorization_url = ctx.query[:authorizationURL] || ctx.query["authorizationURL"] || ctx.query[:authorization_url] || ctx.query["authorization_url"]
         oauth_state = ctx.query[:oauthState] || ctx.query["oauthState"] || ctx.query[:oauth_state] || ctx.query["oauth_state"]
         raise APIError.new("BAD_REQUEST", message: "Unexpected error") if authorization_url.to_s.empty?

data/lib/better_auth/plugins/generic_oauth.rb

@@ -213,7 +213,19 @@ module BetterAuth
     end
 
     def sign_in_with_oauth2_endpoint(config)
-      Endpoint.new(path: "/sign-in/oauth2", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/sign-in/oauth2",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "signInOAuth2",
+            description: "Sign in with OAuth2",
+            responses: {
+              "200" => OpenAPI.json_response("Sign in with OAuth2", generic_oauth_url_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         body = normalize_hash(ctx.body)
         provider_id = body[:provider_id].to_s
         provider = generic_oauth_provider!(config, provider_id)
@@ -223,7 +235,19 @@ module BetterAuth
     end
 
     def o_auth2_link_account_endpoint(config)
-      Endpoint.new(path: "/oauth2/link", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/oauth2/link",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "linkOAuth2",
+            description: "Link an OAuth2 account to the current user session",
+            responses: {
+              "200" => OpenAPI.json_response("Authorization URL generated successfully for linking an OAuth2 account", generic_oauth_url_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         session = Routes.current_session(ctx)
         body = normalize_hash(ctx.body)
         provider_id = body[:provider_id].to_s
@@ -243,8 +267,20 @@ module BetterAuth
     def o_auth2_callback_endpoint(config)
       Endpoint.new(
         path: "/oauth2/callback/:providerId",
-        method: ["GET", "POST"],
-        metadata: {allowed_media_types: ["application/x-www-form-urlencoded", "application/json"]}
+        method: "GET",
+        metadata: {
+          allowed_media_types: ["application/x-www-form-urlencoded", "application/json"],
+          openapi: {
+            operationId: "oauth2Callback",
+            description: "OAuth2 callback",
+            responses: {
+              "200" => OpenAPI.json_response(
+                "OAuth2 callback",
+                OpenAPI.object_schema({url: {type: "string"}}, required: ["url"])
+              )
+            }
+          }
+        }
       ) do |ctx|
         query = normalize_hash(ctx.query)
         provider_id = (fetch_value(ctx.params, "providerId") || query[:provider_id]).to_s
@@ -306,6 +342,16 @@ module BetterAuth
       end
     end
 
+    def generic_oauth_url_response_schema
+      OpenAPI.object_schema(
+        {
+          url: {type: "string"},
+          redirect: {type: "boolean"}
+        },
+        required: ["url", "redirect"]
+      )
+    end
+
     def generic_oauth_authorization_url(ctx, provider, body, link:)
       authorization_url = provider[:authorization_url] || generic_oauth_discovery(provider)["authorization_endpoint"]
       token_url = provider[:token_url] || generic_oauth_discovery(provider)["token_endpoint"]
@@ -368,7 +414,7 @@ module BetterAuth
       state = Crypto.random_string(32)
       if strategy.to_s == "cookie"
         cookie = ctx.context.create_auth_cookie("oauth_state", max_age: 600)
-        encrypted = Crypto.symmetric_encrypt(key: ctx.context.secret, data: JSON.generate(state_data.merge("state" => state)))
+        encrypted = Crypto.symmetric_encrypt(key: ctx.context.secret_config, data: JSON.generate(state_data.merge("state" => state)))
         ctx.set_cookie(cookie.name, encrypted, cookie.attributes)
         return state
       end
@@ -416,7 +462,7 @@ module BetterAuth
         end
 
         begin
-          decrypted = Crypto.symmetric_decrypt(key: ctx.context.secret, data: encrypted)
+          decrypted = Crypto.symmetric_decrypt(key: ctx.context.secret_config, data: encrypted)
           unless decrypted
             Cookies.expire_cookie(ctx, cookie)
             raise ctx.redirect(generic_oauth_error_url(generic_oauth_state_error_url(ctx), "please_restart_the_process"))
@@ -525,7 +571,7 @@ module BetterAuth
       return token if token.to_s.empty?
       return token unless ctx.context.options.account[:encrypt_oauth_tokens]
 
-      Crypto.symmetric_encrypt(key: ctx.context.secret, data: token)
+      Crypto.symmetric_encrypt(key: ctx.context.secret_config, data: token)
     end
 
     def generic_oauth_set_account_cookie(ctx, provider_id, account_id, user_id)