better_auth 0.4.0 → 0.5.0

data/lib/better_auth/routes/session.rb

@@ -3,11 +3,34 @@
 module BetterAuth
   module Routes
     def self.get_session
-      Endpoint.new(path: "/get-session", method: "GET") do |ctx|
-        session = current_session(ctx, allow_nil: true)
+      Endpoint.new(
+        path: "/get-session",
+        method: ["GET", "POST"],
+        metadata: {
+          openapi: {
+            operationId: "getSession",
+            description: "Get the current session",
+            responses: {
+              "200" => OpenAPI.json_response("Current session or null", OpenAPI.session_response_schema_pair.merge(nullable: true))
+            }
+          }
+        }
+      ) do |ctx|
+        defer_refresh = ctx.context.session_config[:defer_session_refresh]
+        if ctx.method == "POST" && !defer_refresh
+          raise APIError.new(
+            "METHOD_NOT_ALLOWED",
+            code: "METHOD_NOT_ALLOWED_DEFER_SESSION_REQUIRED",
+            message: BASE_ERROR_CODES["METHOD_NOT_ALLOWED_DEFER_SESSION_REQUIRED"]
+          )
+        end
+
+        session = current_session(ctx, allow_nil: true, disable_refresh: defer_refresh && ctx.method == "GET")
         next ctx.json(nil) unless session
 
-        ctx.json(parsed_session_response(ctx, session))
+        response = parsed_session_response(ctx, session)
+        response[:needsRefresh] = session_needs_refresh?(ctx, session[:session]) if defer_refresh && ctx.method == "GET"
+        ctx.json(response)
       rescue APIError
         raise
       rescue => error
@@ -17,7 +40,22 @@ module BetterAuth
     end
 
     def self.list_sessions
-      Endpoint.new(path: "/list-sessions", method: "GET") do |ctx|
+      Endpoint.new(
+        path: "/list-sessions",
+        method: "GET",
+        metadata: {
+          openapi: {
+            operationId: "listSessions",
+            description: "List active sessions for the current user",
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Active sessions",
+                {type: "array", items: {type: "object", "$ref": "#/components/schemas/Session"}}
+              )
+            }
+          }
+        }
+      ) do |ctx|
         session = current_session(ctx)
         sessions = ctx.context.internal_adapter.list_sessions(session[:user]["id"])
         active = sessions
@@ -29,8 +67,22 @@ module BetterAuth
     end
 
     def self.update_session
-      Endpoint.new(path: "/update-session", method: "POST") do |ctx|
-        session = current_session(ctx, sensitive: true)
+      Endpoint.new(
+        path: "/update-session",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "updateSession",
+            description: "Update the current session",
+            responses: {
+              "200" => OpenAPI.json_response("Updated session", OpenAPI.session_response_schema_pair)
+            }
+          }
+        }
+      ) do |ctx|
+        session = current_session(ctx)
+        raise APIError.new("BAD_REQUEST", code: "BODY_MUST_BE_AN_OBJECT", message: BASE_ERROR_CODES["BODY_MUST_BE_AN_OBJECT"]) unless ctx.body.is_a?(Hash)
+
         body = Routes.parse_declared_input(ctx, "session", ctx.body, allowed_base: [])
         raise APIError.new("BAD_REQUEST", message: "No fields to update") if body.empty?
 
@@ -38,12 +90,32 @@ module BetterAuth
         updated = ctx.context.internal_adapter.update_session(session[:session]["token"], update)
         merged = session[:session].merge(updated || update)
         Cookies.set_session_cookie(ctx, {session: merged, user: session[:user]}, Cookies.dont_remember?(ctx))
-        ctx.json(parsed_session_response(ctx, {session: merged, user: session[:user]}))
+        ctx.json({session: Schema.parse_output(ctx.context.options, "session", merged)})
       end
     end
 
     def self.revoke_session
-      Endpoint.new(path: "/revoke-session", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/revoke-session",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "revokeSession",
+            description: "Revoke a session by token",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  token: {type: "string", description: "The session token to revoke"}
+                },
+                required: ["token"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response("Session revoked", OpenAPI.status_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         session = current_session(ctx, sensitive: true)
         body = normalize_hash(ctx.body)
         token = body["token"].to_s
@@ -58,7 +130,19 @@ module BetterAuth
     end
 
     def self.revoke_sessions
-      Endpoint.new(path: "/revoke-sessions", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/revoke-sessions",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "revokeSessions",
+            description: "Revoke all sessions for the current user",
+            responses: {
+              "200" => OpenAPI.json_response("Sessions revoked", OpenAPI.status_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         session = current_session(ctx, sensitive: true)
         ctx.context.internal_adapter.delete_sessions(session[:user]["id"])
         Cookies.delete_session_cookie(ctx)
@@ -67,7 +151,19 @@ module BetterAuth
     end
 
     def self.revoke_other_sessions
-      Endpoint.new(path: "/revoke-other-sessions", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/revoke-other-sessions",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "revokeOtherSessions",
+            description: "Revoke all sessions except the current one",
+            responses: {
+              "200" => OpenAPI.json_response("Other sessions revoked", OpenAPI.status_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         session = current_session(ctx, sensitive: true)
         current_token = session[:session]["token"]
         sessions = ctx.context.internal_adapter.list_sessions(session[:user]["id"])
@@ -81,11 +177,11 @@ module BetterAuth
       end
     end
 
-    def self.current_session(ctx, allow_nil: false, sensitive: false)
+    def self.current_session(ctx, allow_nil: false, sensitive: false, fresh: false, disable_refresh: false)
       data = Session.find_current(
         ctx,
         disable_cookie_cache: truthy_query?(ctx.query, "disableCookieCache"),
-        disable_refresh: truthy_query?(ctx.query, "disableRefresh"),
+        disable_refresh: disable_refresh || truthy_query?(ctx.query, "disableRefresh"),
         sensitive: sensitive
       )
       return nil if allow_nil && data.nil?
@@ -93,7 +189,7 @@ module BetterAuth
       raise APIError.new("UNAUTHORIZED") unless data
 
       session = stringify_keys(data[:session] || data["session"])
-      ensure_fresh_session!(ctx, session) if sensitive
+      ensure_fresh_session!(ctx, session) if fresh
 
       {
         session: session,
@@ -101,6 +197,15 @@ module BetterAuth
       }
     end
 
+    def self.request_only_session(ctx)
+      session = current_session(ctx, allow_nil: true)
+      if !session && (ctx.request || !ctx.headers.empty?)
+        raise APIError.new("UNAUTHORIZED", code: "UNAUTHORIZED", message: "Unauthorized")
+      end
+
+      session
+    end
+
     def self.ensure_fresh_session!(ctx, session)
       fresh_age = ctx.context.session_config[:fresh_age].to_i
       return if fresh_age.zero?
@@ -111,6 +216,16 @@ module BetterAuth
       raise APIError.new("FORBIDDEN", code: "SESSION_NOT_FRESH", message: BASE_ERROR_CODES.fetch("SESSION_NOT_FRESH"))
     end
 
+    def self.session_needs_refresh?(ctx, session)
+      return false if truthy_query?(ctx.query, "disableRefresh") || ctx.context.session_config[:disable_session_refresh]
+
+      update_age = ctx.context.session_config[:update_age].to_i
+      return true if update_age.zero?
+
+      updated_at = normalize_time(session["updatedAt"])
+      updated_at && updated_at + update_age <= Time.now
+    end
+
     def self.normalize_time(value)
       return value if value.is_a?(Time)
       return nil if value.nil? || value.to_s.empty?

data/lib/better_auth/routes/sign_in.rb

@@ -8,17 +8,39 @@ module BetterAuth
       Endpoint.new(
         path: "/sign-in/email",
         method: "POST",
+        body_schema: request_body_schema(required_strings: %w[email password]),
         metadata: {
           allowed_media_types: [
             "application/x-www-form-urlencoded",
             "application/json"
-          ]
+          ],
+          openapi: {
+            operationId: "signInEmail",
+            description: "Sign in with email and password",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  email: {type: "string", description: "Email of the user"},
+                  password: {type: "string", description: "Password of the user"},
+                  callbackURL: {type: ["string", "null"], description: "Callback URL to use as a redirect for email verification"},
+                  rememberMe: {type: ["boolean", "null"], default: true, description: "If this is false, the session will not be remembered. Default is `true`."}
+                },
+                required: ["email", "password"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Success - Returns either session details or redirect URL",
+                OpenAPI.session_response_schema(description: "Session response when idToken is provided", nullable_url: true)
+              )
+            }
+          }
         }
       ) do |ctx|
         options = ctx.context.options
         email_config = options.email_and_password
         if email_config[:enabled] != true
-          raise APIError.new("BAD_REQUEST", message: "Email and password is not enabled")
+          raise APIError.new("BAD_REQUEST", code: "EMAIL_PASSWORD_DISABLED", message: BASE_ERROR_CODES["EMAIL_PASSWORD_DISABLED"])
         end
 
         body = normalize_hash(ctx.body)

data/lib/better_auth/routes/sign_out.rb

@@ -3,7 +3,19 @@
 module BetterAuth
   module Routes
     def self.sign_out
-      Endpoint.new(path: "/sign-out", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/sign-out",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "signOut",
+            description: "Sign out the current session",
+            responses: {
+              "200" => OpenAPI.json_response("Successfully signed out", OpenAPI.success_response_schema)
+            }
+          }
+        }
+      ) do |ctx|
         token_cookie = ctx.context.auth_cookies[:session_token]
         token = ctx.get_signed_cookie(token_cookie.name, ctx.context.secret)
         ctx.context.internal_adapter.delete_session(token) if token

data/lib/better_auth/routes/sign_up.rb

@@ -11,17 +11,52 @@ module BetterAuth
       Endpoint.new(
         path: "/sign-up/email",
         method: "POST",
+        body_schema: request_body_schema(
+          required_strings: %w[name email],
+          required_nonempty_strings: %w[password]
+        ),
         metadata: {
           allowed_media_types: [
             "application/x-www-form-urlencoded",
             "application/json"
-          ]
+          ],
+          openapi: {
+            operationId: "signUpWithEmailAndPassword",
+            description: "Sign up a user using email and password",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  name: {type: "string", description: "The name of the user"},
+                  email: {type: "string", description: "The email of the user"},
+                  password: {type: "string", description: "The password of the user"},
+                  image: {type: "string", description: "The profile image URL of the user"},
+                  callbackURL: {type: "string", description: "The URL to use for email verification callback"},
+                  rememberMe: {type: "boolean", description: "If this is false, the session will not be remembered. Default is `true`."}
+                },
+                required: ["name", "email", "password"]
+              ),
+              required: false
+            ),
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Successfully created user",
+                OpenAPI.object_schema(
+                  {
+                    token: {type: "string", nullable: true, description: "Authentication token for the session"},
+                    user: {type: "object", "$ref": "#/components/schemas/User"}
+                  },
+                  required: ["user"]
+                )
+              ),
+              "422" => OpenAPI.error_response("Unprocessable Entity. User already exists or failed to create user.")
+            }
+          }
         }
       ) do |ctx|
         options = ctx.context.options
         email_config = options.email_and_password
         if email_config[:enabled] != true || email_config[:disable_sign_up]
-          raise APIError.new("BAD_REQUEST", message: "Email and password sign up is not enabled")
+          raise APIError.new("BAD_REQUEST", code: "EMAIL_PASSWORD_SIGN_UP_DISABLED", message: BASE_ERROR_CODES["EMAIL_PASSWORD_SIGN_UP_DISABLED"])
         end
 
         body = normalize_hash(ctx.body)
@@ -118,7 +153,8 @@ module BetterAuth
           "name" => name,
           "image" => image,
           "emailVerified" => false
-        )
+        ),
+        context: ctx
       )
     rescue APIError
       raise
@@ -151,18 +187,40 @@ module BetterAuth
         "updatedAt" => now
       }
       reserved = %w[email password name image callbackURL callbackUrl callback_url rememberMe remember_me]
-      additional = parse_declared_input(ctx, "user", body.except(*reserved), allowed_base: [])
+      additional = synthetic_additional_user_fields(ctx, body.except(*reserved))
       custom = ctx.context.options.email_and_password[:custom_synthetic_user]
       return core_fields.merge(additional) unless custom.respond_to?(:call)
 
       value = {
         core_fields: core_fields.except("id"),
+        coreFields: core_fields.except("id"),
         additional_fields: additional,
+        additionalFields: additional,
         id: core_fields["id"]
       }
       stringify_synthetic_user(custom.call(value))
     end
 
+    def self.synthetic_additional_user_fields(ctx, data)
+      additional = parse_declared_input(ctx, "user", data, allowed_base: [])
+      configured = ctx.context.options.user[:additional_fields] || {}
+      configured.each do |field, attributes|
+        storage_field = Schema.storage_key(field)
+        next if additional.key?(storage_field)
+
+        field_attributes = normalize_hash(attributes || {})
+        next unless field_attributes.key?("defaultValue") || field_attributes.key?("default_value")
+
+        default = field_attributes.key?("defaultValue") ? field_attributes["defaultValue"] : field_attributes["default_value"]
+        additional[storage_field] = resolve_default(default)
+      end
+      additional
+    end
+
+    def self.resolve_default(value)
+      value.respond_to?(:call) ? value.call : value
+    end
+
     def self.stringify_synthetic_user(value)
       return value.each_with_object({}) { |(key, object_value), result| result[Schema.storage_key(key)] = object_value } if value.is_a?(Hash)
 

data/lib/better_auth/routes/social.rb

@@ -7,7 +7,49 @@ require "securerandom"
 module BetterAuth
   module Routes
     def self.sign_in_social
-      Endpoint.new(path: "/sign-in/social", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/sign-in/social",
+        method: "POST",
+        metadata: {
+          openapi: {
+            description: "Sign in with a social provider",
+            operationId: "socialSignIn",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  provider: {type: "string"},
+                  callbackURL: {type: ["string", "null"], description: "Callback URL to redirect to after the user has signed in"},
+                  errorCallbackURL: {type: ["string", "null"], description: "Callback URL to redirect to if an error happens"},
+                  newUserCallbackURL: {type: ["string", "null"]},
+                  disableRedirect: {type: ["boolean", "null"], description: "Disable automatic redirection to the provider. Useful for handling the redirection yourself"},
+                  requestSignUp: {type: ["boolean", "null"], description: "Explicitly request sign-up. Useful when disableImplicitSignUp is true for this provider"},
+                  loginHint: {type: ["string", "null"], description: "The login hint to use for the authorization code request"},
+                  additionalData: {type: ["string", "null"]},
+                  scopes: {type: ["array", "null"], description: "Array of scopes to request from the provider. This will override the default scopes passed."},
+                  idToken: {
+                    type: ["object", "null"],
+                    properties: {
+                      token: {type: "string", description: "ID token from the provider"},
+                      accessToken: {type: ["string", "null"], description: "Access token from the provider"},
+                      refreshToken: {type: ["string", "null"], description: "Refresh token from the provider"},
+                      expiresAt: {type: ["number", "null"], description: "Expiry date of the token"},
+                      nonce: {type: ["string", "null"], description: "Nonce used to generate the token"}
+                    },
+                    required: ["token"]
+                  }
+                },
+                required: ["provider"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Success - Returns either session details or redirect URL",
+                OpenAPI.session_response_schema(description: "Session response when idToken is provided")
+              )
+            }
+          }
+        }
+      ) do |ctx|
         body = normalize_hash(ctx.body)
         provider_id = body["provider"].to_s
         provider = social_provider(ctx.context, provider_id)
@@ -66,21 +108,38 @@ module BetterAuth
 
     def self.callback_oauth
       Endpoint.new(
-        path: "/callback/:providerId",
+        path: "/callback/:id",
         method: ["GET", "POST"],
-        metadata: {allowed_media_types: ["application/x-www-form-urlencoded", "application/json"]}
+        metadata: {
+          allowed_media_types: ["application/x-www-form-urlencoded", "application/json"],
+          openapi: {
+            operationId: "callbackOAuth",
+            description: "Handle an OAuth provider callback",
+            parameters: [
+              {
+                name: "id",
+                in: "path",
+                required: true,
+                schema: {type: "string"}
+              }
+            ],
+            responses: {
+              "302" => {description: "Redirects to the configured callback URL"}
+            }
+          }
+        }
       ) do |ctx|
+        provider_id = (fetch_value(ctx.params, "id") || fetch_value(ctx.params, "providerId")).to_s
         if ctx.method == "POST"
           merged = normalize_hash(ctx.query).merge(normalize_hash(ctx.body))
           query = URI.encode_www_form(merged.reject { |_key, value| value.nil? || value.to_s.empty? })
-          target = "#{ctx.context.base_url}/callback/#{fetch_value(ctx.params, "providerId")}"
+          target = "#{ctx.context.base_url}/callback/#{provider_id}"
           target = "#{target}?#{query}" unless query.empty?
           raise ctx.redirect(target)
         end
 
         source = ctx.query
         data = normalize_hash(source)
-        provider_id = fetch_value(ctx.params, "providerId").to_s
         provider = social_provider(ctx.context, provider_id)
         state = data["state"].to_s
         state_data = state.empty? ? nil : Crypto.verify_jwt(state, ctx.context.secret)
@@ -132,7 +191,42 @@ module BetterAuth
     end
 
     def self.link_social
-      Endpoint.new(path: "/link-social", method: "POST") do |ctx|
+      Endpoint.new(
+        path: "/link-social",
+        method: "POST",
+        metadata: {
+          openapi: {
+            operationId: "linkSocialAccount",
+            description: "Link a social account to the current user",
+            requestBody: OpenAPI.json_request_body(
+              OpenAPI.object_schema(
+                {
+                  provider: {type: "string"},
+                  callbackURL: {type: ["string", "null"]},
+                  errorCallbackURL: {type: ["string", "null"]},
+                  disableRedirect: {type: ["boolean", "null"]},
+                  scopes: {type: ["array", "null"], items: {type: "string"}},
+                  idToken: {type: ["object", "null"]}
+                },
+                required: ["provider"]
+              )
+            ),
+            responses: {
+              "200" => OpenAPI.json_response(
+                "Social account link started or completed",
+                OpenAPI.object_schema(
+                  {
+                    url: {type: "string"},
+                    redirect: {type: "boolean"},
+                    status: {type: ["boolean", "null"]}
+                  },
+                  required: ["url", "redirect"]
+                )
+              )
+            }
+          }
+        }
+      ) do |ctx|
         session = current_session(ctx)
         body = normalize_hash(ctx.body)
         provider_id = body["provider"].to_s
@@ -254,7 +348,8 @@ module BetterAuth
             image: fetch_value(user_info, "image"),
             emailVerified: !!fetch_value(user_info, "emailVerified")
           },
-          account_info.merge("providerId" => provider_id, "accountId" => account_id)
+          account_info.merge("providerId" => provider_id, "accountId" => account_id),
+          context: ctx
         )
         user = created[:user]
         new_user = true