better_auth 0.4.0 → 0.6.0

data/lib/better_auth/plugins/multi_session.rb

@@ -36,7 +36,25 @@ module BetterAuth
     end
 
     def list_device_sessions_endpoint
-      Endpoint.new(path: "/multi-session/list-device-sessions", method: "GET") do |ctx|
+      Endpoint.new(
+        path: "/multi-session/list-device-sessions",
+        method: "GET",
+        metadata: {
+          openapi: {
+            operationId: "listDeviceSessions",
+            description: "List device sessions",
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Device sessions",
+                {
+                  type: "array",
+                  items: OpenAPI.session_response_schema_pair
+                }
+              )
+            }
+          }
+        }
+      ) do |ctx|
         tokens = verified_multi_session_tokens(ctx)
         sessions = ctx.context.internal_adapter.find_sessions(tokens)
           .reject { |entry| entry[:session]["expiresAt"] && entry[:session]["expiresAt"] <= Time.now }
@@ -47,7 +65,27 @@ module BetterAuth
     end
 
     def set_active_session_endpoint
-      Endpoint.new(path: "/multi-session/set-active", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/multi-session/set-active",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "setActiveSession",
+            description: "Set the active session",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  sessionToken: {type: "string", description: "The session token"}
+                },
+                required: ["sessionToken"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response("Active session", OpenAPI.session_response_schema_pair)
+            }
+          }
+        }
+      ) do |ctx|
         token = fetch_value(ctx.body, "sessionToken").to_s
         cookie_name = multi_session_cookie_name(ctx, token)
         unless !token.empty? && ctx.get_signed_cookie(cookie_name, ctx.context.secret)
@@ -66,7 +104,27 @@ module BetterAuth
     end
 
     def revoke_device_session_endpoint
-      Endpoint.new(path: "/multi-session/revoke", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/multi-session/revoke",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "revokeDeviceSession",
+            description: "Revoke a device session",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  sessionToken: {type: "string", description: "The session token"}
+                },
+                required: ["sessionToken"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response("Device session revoked", OpenAPI.status_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         current = Routes.current_session(ctx)
         token = fetch_value(ctx.body, "sessionToken").to_s
         cookie_name = multi_session_cookie_name(ctx, token)

data/lib/better_auth/plugins/oauth_protocol.rb

@@ -788,7 +788,7 @@ module BetterAuth
       def store_client_secret_value(ctx, secret, mode)
         mode = normalize_secret_storage_mode(mode)
         return Crypto.sha256(secret, encoding: :base64url) if mode == "hashed"
-        return Crypto.symmetric_encrypt(key: ctx.context.secret, data: secret) if mode == "encrypted"
+        return Crypto.symmetric_encrypt(key: ctx.context.secret_config, data: secret) if mode == "encrypted"
 
         if mode.is_a?(Hash)
           return mode[:hash].call(secret) if mode[:hash].respond_to?(:call)
@@ -801,7 +801,7 @@ module BetterAuth
       def verify_client_secret(ctx, stored_secret, provided_secret, mode)
         mode = normalize_secret_storage_mode(mode)
         return Crypto.constant_time_compare(Crypto.sha256(provided_secret, encoding: :base64url), stored_secret.to_s) if mode == "hashed"
-        return Crypto.symmetric_decrypt(key: ctx.context.secret, data: stored_secret) == provided_secret.to_s if mode == "encrypted"
+        return Crypto.symmetric_decrypt(key: ctx.context.secret_config, data: stored_secret) == provided_secret.to_s if mode == "encrypted"
 
         if mode.is_a?(Hash)
           return mode[:hash].call(provided_secret).to_s == stored_secret.to_s if mode[:hash].respond_to?(:call)

data/lib/better_auth/plugins/oauth_proxy.rb

@@ -43,12 +43,28 @@ module BetterAuth
     end
 
     def oauth_proxy_endpoint(config)
-      Endpoint.new(path: "/oauth-proxy-callback", method: "GET") do |ctx|
+      Endpoint.new(
+        path: "/oauth-proxy-callback",
+        method: "GET",
+        metadata: {
+          openapi: {
+            operationId: "oauthProxyCallback",
+            description: "OAuth Proxy Callback",
+            parameters: [
+              {in: "query", name: "callbackURL", required: true, schema: {type: "string", format: "uri"}},
+              {in: "query", name: "cookies", required: true, schema: {type: "string"}}
+            ],
+            responses: {
+              "302" => {description: "Redirects to the callback URL"}
+            }
+          }
+        }
+      ) do |ctx|
         query = normalize_hash(ctx.query)
         callback_url = query[:callback_url] || "/"
         oauth_proxy_validate_callback!(ctx, callback_url)
 
-        decrypted = Crypto.symmetric_decrypt(key: ctx.context.secret, data: query[:cookies].to_s)
+        decrypted = Crypto.symmetric_decrypt(key: oauth_proxy_secret(ctx, config), data: query[:cookies].to_s)
         raise ctx.redirect(oauth_proxy_error_url(ctx, "OAuthProxy - Invalid cookies or secret")) unless decrypted
 
         payload = JSON.parse(decrypted)
@@ -83,11 +99,11 @@ module BetterAuth
       nil
     end
 
-    def oauth_proxy_restore_state_package(ctx, _config)
+    def oauth_proxy_restore_state_package(ctx, config)
       state = fetch_value(ctx.query, "state") || fetch_value(ctx.body, "state")
       return if state.to_s.empty?
 
-      decrypted = Crypto.symmetric_decrypt(key: ctx.context.secret, data: state.to_s)
+      decrypted = Crypto.symmetric_decrypt(key: oauth_proxy_secret(ctx, config), data: state.to_s)
       return unless decrypted
 
       package = JSON.parse(decrypted)
@@ -121,7 +137,7 @@ module BetterAuth
       return if state_cookie.to_s.empty?
 
       encrypted_package = Crypto.symmetric_encrypt(
-        key: ctx.context.secret,
+        key: oauth_proxy_secret(ctx, config),
         data: JSON.generate({
           state: original_state,
           stateCookie: state_cookie,
@@ -160,7 +176,7 @@ module BetterAuth
       return if set_cookie.to_s.empty?
 
       encrypted = Crypto.symmetric_encrypt(
-        key: ctx.context.secret,
+        key: oauth_proxy_secret(ctx, config),
         data: JSON.generate({
           cookies: set_cookie,
           timestamp: (Time.now.to_f * 1000).to_i
@@ -180,6 +196,10 @@ module BetterAuth
       exact && exact[:value]
     end
 
+    def oauth_proxy_secret(ctx, config)
+      config[:secret] || ctx.context.secret_config
+    end
+
     def oauth_proxy_sign_in_path?(path)
       path.to_s.start_with?("/sign-in/social", "/sign-in/oauth2")
     end

data/lib/better_auth/plugins/oidc_provider.rb

@@ -6,9 +6,21 @@ module BetterAuth
   module Plugins
     module OIDCProvider
       VALID_PROMPTS = %w[none login consent create select_account].freeze
+      DEPRECATION_MESSAGE = 'The "oidc-provider" plugin is deprecated and will be removed in the next major version. Migrate to better_auth-oauth-provider. See: https://www.better-auth.com/docs/plugins/oauth-provider'
 
       module_function
 
+      def warn_deprecation!(logger = nil)
+        return if @deprecation_warned
+
+        Deprecate.warn_once("[Deprecation] #{DEPRECATION_MESSAGE}", logger)
+        @deprecation_warned = true
+      end
+
+      def reset_deprecation_warning!
+        @deprecation_warned = false
+      end
+
       def normalize_issuer(value)
         uri = URI.parse(value.to_s)
         uri.query = nil
@@ -34,6 +46,9 @@ module BetterAuth
     module_function
 
     def oidc_provider(options = {})
+      raw_options = normalize_hash(options)
+      OIDCProvider.warn_deprecation!(raw_options[:logger]) unless raw_options[:__skip_deprecation_warning]
+
       config = {
         code_expires_in: 600,
         consent_page: "/oauth2/authorize",
@@ -45,7 +60,7 @@ module BetterAuth
         store_client_secret: "plain",
         scopes: %w[openid profile email offline_access],
         store: OAuthProtocol.stores
-      }.merge(normalize_hash(options))
+      }.merge(raw_options.except(:logger, :__skip_deprecation_warning))
 
       Plugin.new(
         id: "oidc-provider",
@@ -113,7 +128,7 @@ module BetterAuth
     end
 
     def oidc_register_endpoint(config)
-      Endpoint.new(path: "/oauth2/register", method: "POST") do |ctx|
+      Endpoint.new(path: "/oauth2/register", method: "POST", metadata: oidc_openapi("registerOAuthApplication", "Register an OAuth2 application", "OAuth2 application registered successfully", oidc_client_schema)) do |ctx|
         session = Routes.current_session(ctx, allow_nil: true)
         unless session || config[:allow_dynamic_client_registration]
           raise APIError.new("UNAUTHORIZED", message: "invalid_token")
@@ -146,7 +161,7 @@ module BetterAuth
     end
 
     def oidc_get_client_endpoint
-      Endpoint.new(path: "/oauth2/client/:id", method: "GET") do |ctx|
+      Endpoint.new(path: "/oauth2/client/:id", method: "GET", metadata: oidc_openapi("getOAuthClient", "Get OAuth2 client details", "OAuth2 client retrieved successfully", oidc_client_schema)) do |ctx|
         client = OAuthProtocol.find_client(ctx, "oauthApplication", ctx.params["id"] || ctx.params[:id])
         raise APIError.new("NOT_FOUND", message: "client not found") unless client
 
@@ -155,7 +170,7 @@ module BetterAuth
     end
 
     def oidc_list_clients_endpoint
-      Endpoint.new(path: "/oauth2/clients", method: "GET") do |ctx|
+      Endpoint.new(path: "/oauth2/clients", method: "GET", metadata: oidc_openapi("listOAuthApplications", "List OAuth2 applications", "OAuth2 applications retrieved successfully", {type: "array", items: oidc_client_schema})) do |ctx|
         session = Routes.current_session(ctx)
         clients = ctx.context.adapter.find_many(model: "oauthApplication", where: [{field: "userId", value: session[:user]["id"]}])
         ctx.json(clients.map { |client| OAuthProtocol.client_response(client, include_secret: false) })
@@ -163,7 +178,7 @@ module BetterAuth
     end
 
     def oidc_update_client_endpoint
-      Endpoint.new(path: "/oauth2/client/:id", method: "PATCH") do |ctx|
+      Endpoint.new(path: "/oauth2/client/:id", method: "PATCH", metadata: oidc_openapi("updateOAuthApplication", "Update an OAuth2 application", "OAuth2 application updated successfully", oidc_client_schema)) do |ctx|
         session = Routes.current_session(ctx)
         client = oidc_find_owned_client!(ctx, session)
         body = OAuthProtocol.stringify_keys(ctx.body)
@@ -191,7 +206,7 @@ module BetterAuth
     end
 
     def oidc_rotate_client_secret_endpoint(config)
-      Endpoint.new(path: "/oauth2/client/:id/rotate-secret", method: "POST") do |ctx|
+      Endpoint.new(path: "/oauth2/client/:id/rotate-secret", method: "POST", metadata: oidc_openapi("rotateOAuthApplicationSecret", "Rotate an OAuth2 application secret", "OAuth2 application secret rotated successfully", oidc_client_schema)) do |ctx|
         session = Routes.current_session(ctx)
         client = oidc_find_owned_client!(ctx, session)
         if OAuthProtocol.stringify_keys(client)["tokenEndpointAuthMethod"] == "none"
@@ -209,7 +224,7 @@ module BetterAuth
     end
 
     def oidc_delete_client_endpoint
-      Endpoint.new(path: "/oauth2/client/:id", method: "DELETE") do |ctx|
+      Endpoint.new(path: "/oauth2/client/:id", method: "DELETE", metadata: oidc_openapi("deleteOAuthApplication", "Delete an OAuth2 application", "OAuth2 application deleted successfully", OpenAPI.success_response_schema)) do |ctx|
         session = Routes.current_session(ctx)
         client = oidc_find_owned_client!(ctx, session)
         ctx.context.adapter.delete(model: "oauthApplication", where: [{field: "id", value: client.fetch("id")}])
@@ -218,7 +233,7 @@ module BetterAuth
     end
 
     def oidc_authorize_endpoint(config)
-      Endpoint.new(path: "/oauth2/authorize", method: "GET") do |ctx|
+      Endpoint.new(path: "/oauth2/authorize", method: "GET", metadata: oidc_openapi("oauth2Authorize", "Authorize an OAuth2 request", "Authorization response generated successfully", {type: "object", additionalProperties: true})) do |ctx|
         query = OAuthProtocol.stringify_keys(ctx.query)
         prompts = OIDCProvider.parse_prompt(query["prompt"])
         session = Routes.current_session(ctx, allow_nil: true)
@@ -308,7 +323,7 @@ module BetterAuth
     end
 
     def oidc_consent_endpoint(config)
-      Endpoint.new(path: "/oauth2/consent", method: "POST") do |ctx|
+      Endpoint.new(path: "/oauth2/consent", method: "POST", metadata: oidc_openapi("oauth2Consent", "Handle OAuth2 consent", "OAuth2 consent handled successfully", oidc_redirect_response_schema)) do |ctx|
         Routes.current_session(ctx)
         body = OAuthProtocol.stringify_keys(ctx.body)
         consent = config[:store][:consents].delete(body["consent_code"].to_s)
@@ -338,7 +353,11 @@ module BetterAuth
     end
 
     def oidc_token_endpoint(config)
-      Endpoint.new(path: "/oauth2/token", method: "POST", metadata: {allowed_media_types: ["application/x-www-form-urlencoded", "application/json"]}) do |ctx|
+      Endpoint.new(
+        path: "/oauth2/token",
+        method: "POST",
+        metadata: oidc_openapi("oauth2Token", "Exchange OAuth2 code for tokens", "OAuth2 tokens issued successfully", oidc_token_response_schema).merge(allowed_media_types: ["application/x-www-form-urlencoded", "application/json"])
+      ) do |ctx|
         body = OAuthProtocol.stringify_keys(ctx.body)
         client = OAuthProtocol.authenticate_client!(ctx, "oauthApplication", store_client_secret: config[:store_client_secret])
         raise APIError.new("UNAUTHORIZED", message: "invalid_client") unless client
@@ -374,13 +393,17 @@ module BetterAuth
     end
 
     def oidc_userinfo_endpoint(config)
-      Endpoint.new(path: "/oauth2/userinfo", method: "GET") do |ctx|
+      Endpoint.new(path: "/oauth2/userinfo", method: "GET", metadata: oidc_openapi("oauth2Userinfo", "Get OAuth2 user information", "User information retrieved successfully", oidc_userinfo_schema)) do |ctx|
         ctx.json(OAuthProtocol.userinfo(config[:store], ctx.headers["authorization"], additional_claim: config[:get_additional_user_info_claim]))
       end
     end
 
     def oidc_introspect_endpoint(config)
-      Endpoint.new(path: "/oauth2/introspect", method: "POST", metadata: {allowed_media_types: ["application/x-www-form-urlencoded", "application/json"]}) do |ctx|
+      Endpoint.new(
+        path: "/oauth2/introspect",
+        method: "POST",
+        metadata: oidc_openapi("oauth2Introspect", "Introspect an OAuth2 token", "OAuth2 token introspection result", oidc_introspection_schema).merge(allowed_media_types: ["application/x-www-form-urlencoded", "application/json"])
+      ) do |ctx|
         OAuthProtocol.authenticate_client!(ctx, "oauthApplication", store_client_secret: config[:store_client_secret])
         body = OAuthProtocol.stringify_keys(ctx.body)
         token = config[:store][:tokens][body["token"].to_s] || config[:store][:refresh_tokens][body["token"].to_s]
@@ -396,7 +419,11 @@ module BetterAuth
     end
 
     def oidc_revoke_endpoint(config)
-      Endpoint.new(path: "/oauth2/revoke", method: "POST", metadata: {allowed_media_types: ["application/x-www-form-urlencoded", "application/json"]}) do |ctx|
+      Endpoint.new(
+        path: "/oauth2/revoke",
+        method: "POST",
+        metadata: oidc_openapi("oauth2Revoke", "Revoke an OAuth2 token", "OAuth2 token revoked successfully", OpenAPI.object_schema({revoked: {type: "boolean"}}, required: ["revoked"])).merge(allowed_media_types: ["application/x-www-form-urlencoded", "application/json"])
+      ) do |ctx|
         OAuthProtocol.authenticate_client!(ctx, "oauthApplication", store_client_secret: config[:store_client_secret])
         body = OAuthProtocol.stringify_keys(ctx.body)
         if (token = config[:store][:tokens][body["token"].to_s] || config[:store][:refresh_tokens][body["token"].to_s])
@@ -407,7 +434,11 @@ module BetterAuth
     end
 
     def oidc_end_session_endpoint
-      Endpoint.new(path: "/oauth2/endsession", method: ["GET", "POST"], metadata: {allowed_media_types: ["application/x-www-form-urlencoded", "application/json"]}) do |ctx|
+      Endpoint.new(
+        path: "/oauth2/endsession",
+        method: ["GET", "POST"],
+        metadata: oidc_openapi("oauth2EndSession", "RP-Initiated Logout endpoint", "Logout request handled").merge(allowed_media_types: ["application/x-www-form-urlencoded", "application/json"])
+      ) do |ctx|
         input_source = (ctx.method == "GET") ? ctx.query : ctx.body
         input = OAuthProtocol.stringify_keys(input_source)
         if input["post_logout_redirect_uri"]
@@ -425,6 +456,79 @@ module BetterAuth
       end
     end
 
+    def oidc_openapi(operation_id, description, response_description = "Success", response_schema = {type: "object"})
+      {
+        openapi: {
+          operationId: operation_id,
+          description: description,
+          responses: {
+            "200" => OpenAPI.json_response(response_description, response_schema)
+          }
+        }
+      }
+    end
+
+    def oidc_client_schema
+      OpenAPI.object_schema(
+        {
+          clientId: {type: "string"},
+          clientSecret: {type: ["string", "null"]},
+          name: {type: "string"},
+          redirectUris: {type: "array", items: {type: "string"}},
+          grantTypes: {type: "array", items: {type: "string"}},
+          responseTypes: {type: "array", items: {type: "string"}}
+        },
+        required: ["clientId", "name"]
+      )
+    end
+
+    def oidc_redirect_response_schema
+      OpenAPI.object_schema(
+        {redirectURI: {type: "string", format: "uri"}},
+        required: ["redirectURI"]
+      )
+    end
+
+    def oidc_token_response_schema
+      OpenAPI.object_schema(
+        {
+          access_token: {type: "string"},
+          token_type: {type: "string"},
+          expires_in: {type: "number"},
+          refresh_token: {type: ["string", "null"]},
+          id_token: {type: ["string", "null"]},
+          scope: {type: ["string", "null"]}
+        },
+        required: ["access_token", "token_type", "expires_in"]
+      )
+    end
+
+    def oidc_userinfo_schema
+      OpenAPI.object_schema(
+        {
+          sub: {type: "string"},
+          email: {type: ["string", "null"]},
+          email_verified: {type: ["boolean", "null"]},
+          name: {type: ["string", "null"]},
+          picture: {type: ["string", "null"]}
+        },
+        required: ["sub"]
+      )
+    end
+
+    def oidc_introspection_schema
+      OpenAPI.object_schema(
+        {
+          active: {type: "boolean"},
+          client_id: {type: ["string", "null"]},
+          scope: {type: ["string", "null"]},
+          sub: {type: ["string", "null"]},
+          exp: {type: ["number", "null"]}
+        },
+        required: ["active"]
+      )
+    end
+
     def oidc_provider_schema
       {
         oauthApplication: {

data/lib/better_auth/plugins/one_tap.rb

@@ -29,8 +29,12 @@ module BetterAuth
         },
         metadata: {
           openapi: {
+            operationId: "oneTapCallback",
             summary: "One tap callback",
-            description: "Use this endpoint to authenticate with Google One Tap"
+            description: "Use this endpoint to authenticate with Google One Tap",
+            responses: {
+              "200" => OpenAPI.json_response("Success", OpenAPI.session_response_schema_pair)
+            }
           }
         }
       ) do |ctx|
@@ -61,7 +65,8 @@ module BetterAuth
               providerId: "google",
               accountId: fetch_value(payload, "sub").to_s,
               idToken: id_token
-            }
+            },
+            context: ctx
           )
           raise APIError.new("INTERNAL_SERVER_ERROR", message: "Could not create user") unless created
 

data/lib/better_auth/plugins/one_time_token.rb

@@ -29,7 +29,27 @@ module BetterAuth
     end
 
     def generate_one_time_token_endpoint(config)
-      Endpoint.new(path: "/one-time-token/generate", method: "GET") do |ctx|
+      Endpoint.new(
+        path: "/one-time-token/generate",
+        method: "GET",
+        metadata: {
+          openapi: {
+            operationId: "generateOneTimeToken",
+            description: "Generate a one-time token for the current session",
+            responses: {
+              "200" => OpenAPI.json_response(
+                "One-time token",
+                OpenAPI.object_schema(
+                  {
+                    token: {type: "string"}
+                  },
+                  required: ["token"]
+                )
+              )
+            }
+          }
+        }
+      ) do |ctx|
         if config[:disable_client_request] && ctx.request
           raise APIError.new("BAD_REQUEST", message: "Client requests are disabled")
         end
@@ -41,7 +61,27 @@ module BetterAuth
     end
 
     def verify_one_time_token_endpoint(config)
-      Endpoint.new(path: "/one-time-token/verify", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/one-time-token/verify",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "verifyOneTimeToken",
+            description: "Verify a one-time token and restore its session",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  token: {type: "string"}
+                },
+                required: ["token"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response("Session restored", OpenAPI.session_response_schema_pair)
+            }
+          }
+        }
+      ) do |ctx|
         body = normalize_hash(ctx.body)
         token = body[:token].to_s
         stored_token = one_time_token_stored_value(config, token)