better_auth 0.1.1 → 0.3.0

data/lib/better_auth/plugins/magic_link.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module BetterAuth
+  module Plugins
+    module_function
+
+    def magic_link(options = {})
+      config = {store_token: "plain", allowed_attempts: 1}.merge(normalize_hash(options))
+
+      Plugin.new(
+        id: "magic-link",
+        endpoints: {
+          sign_in_magic_link: sign_in_magic_link_endpoint(config),
+          magic_link_verify: magic_link_verify_endpoint(config)
+        },
+        rate_limit: [
+          {
+            path_matcher: ->(path) { path.start_with?("/sign-in/magic-link", "/magic-link/verify") },
+            window: config.dig(:rate_limit, :window) || 60,
+            max: config.dig(:rate_limit, :max) || 5
+          }
+        ],
+        options: config
+      )
+    end
+
+    def sign_in_magic_link_endpoint(config)
+      Endpoint.new(path: "/sign-in/magic-link", method: "POST") do |ctx|
+        body = normalize_hash(ctx.body)
+        email = body[:email].to_s.downcase
+        raise APIError.new("BAD_REQUEST", message: BASE_ERROR_CODES["INVALID_EMAIL"]) unless Routes::EMAIL_PATTERN.match?(email)
+
+        token = magic_link_token(email, config)
+        stored_token = store_magic_link_token(token, config)
+        ctx.context.internal_adapter.create_verification_value(
+          identifier: stored_token,
+          value: JSON.generate({"email" => email, "name" => body[:name], "attempt" => 0}),
+          expiresAt: Time.now + (config[:expires_in] || 60 * 5).to_i
+        )
+
+        link = magic_link_url(ctx, token, body)
+        sender = config[:send_magic_link]
+        data = {email: email, url: link, token: token}
+        data[:metadata] = body[:metadata] if body.key?(:metadata)
+        sender.call(data, ctx) if sender.respond_to?(:call)
+        ctx.json({status: true})
+      end
+    end
+
+    def magic_link_verify_endpoint(config)
+      Endpoint.new(path: "/magic-link/verify", method: "GET") do |ctx|
+        query = normalize_hash(ctx.query)
+        token = query[:token].to_s
+        callback_url = query[:callback_url] || "/"
+        error_callback_url = query[:error_callback_url] || callback_url
+        new_user_callback_url = query[:new_user_callback_url] || callback_url
+
+        validate_magic_link_callback!(ctx, callback_url, "callbackURL")
+        validate_magic_link_callback!(ctx, error_callback_url, "errorCallbackURL")
+        validate_magic_link_callback!(ctx, new_user_callback_url, "newUserCallbackURL")
+
+        redirect_with_error = lambda do |error|
+          raise ctx.redirect(magic_link_error_url(error_callback_url, error))
+        end
+
+        stored_token = store_magic_link_token(token, config)
+        verification = ctx.context.internal_adapter.find_verification_value(stored_token)
+        redirect_with_error.call("INVALID_TOKEN") unless verification
+
+        if Routes.expired_time?(verification["expiresAt"])
+          ctx.context.internal_adapter.delete_verification_value(verification["id"])
+          redirect_with_error.call("EXPIRED_TOKEN")
+        end
+
+        payload = JSON.parse(verification["value"])
+        email = payload.fetch("email").to_s.downcase
+        name = payload["name"]
+        attempt = payload["attempt"].to_i
+        if magic_link_attempts_exceeded?(attempt, config)
+          ctx.context.internal_adapter.delete_verification_value(verification["id"])
+          redirect_with_error.call("ATTEMPTS_EXCEEDED")
+        end
+        ctx.context.internal_adapter.update_verification_value(
+          verification["id"],
+          value: JSON.generate(payload.merge("attempt" => attempt + 1))
+        )
+        found = ctx.context.internal_adapter.find_user_by_email(email)
+        user = found && found[:user]
+        new_user = false
+
+        unless user
+          redirect_with_error.call("new_user_signup_disabled") if config[:disable_sign_up]
+
+          user = ctx.context.internal_adapter.create_user(
+            email: email,
+            emailVerified: true,
+            name: name || ""
+          )
+          new_user = true
+          redirect_with_error.call("failed_to_create_user") unless user
+        end
+
+        unless user["emailVerified"]
+          user = ctx.context.internal_adapter.update_user(user["id"], emailVerified: true)
+        end
+
+        session = ctx.context.internal_adapter.create_session(user["id"])
+        redirect_with_error.call("failed_to_create_session") unless session
+
+        Cookies.set_session_cookie(ctx, {session: session, user: user})
+        unless query.key?(:callback_url)
+          next ctx.json({
+            token: session["token"],
+            user: Schema.parse_output(ctx.context.options, "user", user),
+            session: Schema.parse_output(ctx.context.options, "session", session)
+          })
+        end
+
+        raise ctx.redirect(new_user ? new_user_callback_url : callback_url)
+      rescue JSON::ParserError, KeyError
+        raise ctx.redirect(magic_link_error_url(error_callback_url || "/", "INVALID_TOKEN"))
+      end
+    end
+
+    def magic_link_token(email, config)
+      generator = config[:generate_token]
+      return generator.call(email) if generator.respond_to?(:call)
+
+      Array.new(32) { [*"a".."z", *"A".."Z"].sample }.join
+    end
+
+    def magic_link_attempts_exceeded?(attempt, config)
+      allowed = config[:allowed_attempts]
+      return false if allowed.respond_to?(:infinite?) && allowed.infinite?
+
+      attempt >= allowed.to_i
+    end
+
+    def store_magic_link_token(token, config)
+      storage = config[:store_token]
+      return Crypto.sha256(token, encoding: :base64url) if storage.to_s == "hashed"
+
+      if storage.is_a?(Hash) && %w[custom-hasher custom_hasher].include?(storage[:type].to_s)
+        hasher = storage[:hash]
+        return hasher.call(token) if hasher.respond_to?(:call)
+      end
+
+      token
+    end
+
+    def magic_link_url(ctx, token, body)
+      params = {
+        token: token,
+        callbackURL: body[:callback_url] || "/"
+      }
+      params[:newUserCallbackURL] = body[:new_user_callback_url] if body[:new_user_callback_url]
+      params[:errorCallbackURL] = body[:error_callback_url] if body[:error_callback_url]
+      "#{ctx.context.base_url}/magic-link/verify?#{URI.encode_www_form(params)}"
+    end
+
+    def validate_magic_link_callback!(ctx, value, label)
+      return if value.nil? || value.to_s.empty?
+      return if ctx.context.trusted_origin?(value.to_s, allow_relative_paths: true)
+
+      raise APIError.new("FORBIDDEN", message: "Invalid #{label}")
+    end
+
+    def magic_link_error_url(url, error)
+      uri = URI.parse(url.to_s.empty? ? "/" : url.to_s)
+      query = URI.decode_www_form(uri.query.to_s)
+      query << ["error", error]
+      uri.query = URI.encode_www_form(query)
+      uri.to_s
+    rescue URI::InvalidURIError
+      "/?error=#{URI.encode_www_form_component(error)}"
+    end
+  end
+end

data/lib/better_auth/plugins/mcp.rb

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+
+require "json"
+
+module BetterAuth
+  module Plugins
+    module MCP
+      module_function
+
+      def with_mcp_auth(app, resource_metadata_url:, auth: nil)
+        lambda do |env|
+          authorization = env["HTTP_AUTHORIZATION"].to_s
+          unless authorization.start_with?("Bearer ")
+            return unauthorized(resource_metadata_url)
+          end
+
+          session = auth&.api&.get_mcp_session(headers: {"authorization" => authorization})
+          return unauthorized(resource_metadata_url) unless session
+
+          env["better_auth.mcp_session"] = session
+
+          app.call(env)
+        rescue APIError
+          unauthorized(resource_metadata_url)
+        end
+      end
+
+      def unauthorized(resource_metadata_url)
+        [
+          401,
+          {
+            "www-authenticate" => %(Bearer resource_metadata="#{resource_metadata_url}"),
+            "access-control-expose-headers" => "WWW-Authenticate"
+          },
+          ["unauthorized"]
+        ]
+      end
+    end
+
+    module_function
+
+    def mcp(options = {})
+      config = {
+        login_page: "/login",
+        consent_page: "/oauth/consent",
+        resource: nil,
+        oidc_config: {},
+        code_expires_in: 600,
+        default_scope: "openid",
+        access_token_expires_in: 3600,
+        refresh_token_expires_in: 604_800,
+        allow_plain_code_challenge_method: true,
+        scopes: %w[openid profile email offline_access],
+        store: OAuthProtocol.stores
+      }.merge(normalize_hash(options))
+      config = mcp_normalize_config(config)
+
+      Plugin.new(
+        id: "mcp",
+        endpoints: mcp_endpoints(config),
+        hooks: {
+          after: [
+            {
+              matcher: ->(_ctx) { true },
+              handler: ->(ctx) { mcp_restore_login_prompt(ctx, config) }
+            }
+          ]
+        },
+        schema: oidc_provider_schema,
+        options: config
+      )
+    end
+
+    def mcp_endpoints(config)
+      {
+        get_mcp_o_auth_config: mcp_oauth_config_endpoint(config),
+        get_mcp_protected_resource: mcp_protected_resource_endpoint(config),
+        mcp_o_auth_authorize: mcp_authorize_endpoint(config),
+        mcp_o_auth_token: mcp_token_endpoint(config),
+        mcp_o_auth_user_info: mcp_userinfo_endpoint(config),
+        mcp_register: mcp_register_endpoint(config),
+        get_mcp_session: mcp_get_session_endpoint(config),
+        o_auth_consent: oidc_consent_endpoint(config),
+        mcp_jwks: mcp_jwks_endpoint(config)
+      }
+    end
+
+    def mcp_oauth_config_endpoint(config)
+      Endpoint.new(path: "/.well-known/oauth-authorization-server", method: "GET", metadata: {hide: true}) do |ctx|
+        base = OAuthProtocol.endpoint_base(ctx)
+        ctx.json({
+          issuer: OAuthProtocol.issuer(ctx),
+          authorization_endpoint: "#{base}/mcp/authorize",
+          token_endpoint: "#{base}/mcp/token",
+          userinfo_endpoint: "#{base}/mcp/userinfo",
+          jwks_uri: "#{base}/mcp/jwks",
+          registration_endpoint: "#{base}/mcp/register",
+          scopes_supported: config[:scopes],
+          response_types_supported: ["code"],
+          response_modes_supported: ["query"],
+          grant_types_supported: ["authorization_code", "refresh_token"],
+          acr_values_supported: ["urn:mace:incommon:iap:silver", "urn:mace:incommon:iap:bronze"],
+          subject_types_supported: ["public"],
+          id_token_signing_alg_values_supported: ["RS256", "none"],
+          token_endpoint_auth_methods_supported: ["client_secret_basic", "client_secret_post", "none"],
+          code_challenge_methods_supported: ["S256"],
+          claims_supported: %w[sub iss aud exp nbf iat jti email email_verified name]
+        }.merge(config[:oidc_config][:metadata] || {}))
+      end
+    end
+
+    def mcp_protected_resource_endpoint(config)
+      Endpoint.new(path: "/.well-known/oauth-protected-resource", method: "GET", metadata: {hide: true}) do |ctx|
+        origin = OAuthProtocol.origin_for(OAuthProtocol.endpoint_base(ctx))
+        ctx.json({
+          resource: config[:resource] || origin,
+          authorization_servers: [origin],
+          jwks_uri: config.dig(:oidc_config, :metadata, :jwks_uri) || "#{OAuthProtocol.endpoint_base(ctx)}/mcp/jwks",
+          scopes_supported: config.dig(:oidc_config, :metadata, :scopes_supported) || config[:scopes],
+          bearer_methods_supported: ["header"],
+          resource_signing_alg_values_supported: ["RS256", "none"]
+        })
+      end
+    end
+
+    def mcp_register_endpoint(config)
+      Endpoint.new(path: "/mcp/register", method: "POST") do |ctx|
+        mcp_set_cors_headers(ctx)
+        ctx.json(
+          OAuthProtocol.create_client(
+            ctx,
+            model: "oauthApplication",
+            body: ctx.body,
+            default_auth_method: "none",
+            store_client_secret: config[:store_client_secret] || "plain"
+          ),
+          status: 201,
+          headers: {"Cache-Control" => "no-store", "Pragma" => "no-cache"}
+        )
+      end
+    end
+
+    def mcp_authorize_endpoint(config)
+      Endpoint.new(path: "/mcp/authorize", method: "GET") do |ctx|
+        query = OAuthProtocol.stringify_keys(ctx.query)
+        session = Routes.current_session(ctx, allow_nil: true)
+        unless session
+          ctx.set_signed_cookie("oidc_login_prompt", JSON.generate(query), ctx.context.secret, max_age: 600, path: "/", same_site: "lax")
+          raise ctx.redirect(OAuthProtocol.redirect_uri_with_params(config[:login_page], query))
+        end
+
+        raise ctx.redirect(mcp_authorization_redirect(ctx, config, query, session))
+      end
+    end
+
+    def mcp_restore_login_prompt(ctx, config)
+      cookie = ctx.get_signed_cookie("oidc_login_prompt", ctx.context.secret)
+      return unless cookie
+
+      session = ctx.context.new_session
+      return unless session && session[:session] && ctx.response_headers["set-cookie"].to_s.include?(ctx.context.auth_cookies[:session_token].name)
+
+      query = mcp_parse_login_prompt(cookie)
+      return unless query
+
+      ctx.set_cookie("oidc_login_prompt", "", path: "/", max_age: 0)
+      ctx.context.set_current_session(session) if ctx.context.respond_to?(:set_current_session)
+      [302, ctx.response_headers.merge("location" => mcp_authorization_redirect(ctx, config, query, session)), [""]]
+    end
+
+    def mcp_authorization_redirect(ctx, config, query, session)
+      query = OAuthProtocol.stringify_keys(query)
+      query["prompt"] = mcp_prompt_without_login(query["prompt"]) if query.key?("prompt")
+      prompts = OIDCProvider.parse_prompt(query["prompt"])
+      unless query["client_id"]
+        raise ctx.redirect("#{ctx.context.base_url}/error?error=invalid_client")
+      end
+      unless query["response_type"]
+        raise ctx.redirect(OAuthProtocol.redirect_uri_with_params(ctx.context.base_url + "/error", error: "invalid_request", error_description: "response_type is required"))
+      end
+      client = OAuthProtocol.find_client(ctx, "oauthApplication", query["client_id"])
+      raise ctx.redirect("#{ctx.context.base_url}/error?error=invalid_client") unless client
+      OAuthProtocol.validate_redirect_uri!(client, query["redirect_uri"])
+      client_data = OAuthProtocol.stringify_keys(client)
+      raise ctx.redirect("#{ctx.context.base_url}/error?error=client_disabled") if client_data["disabled"]
+      unless query["response_type"] == "code"
+        raise ctx.redirect("#{ctx.context.base_url}/error?error=unsupported_response_type")
+      end
+
+      scopes = OAuthProtocol.parse_scopes(query["scope"] || config[:default_scope])
+      invalid_scopes = scopes.reject { |scope| config[:scopes].include?(scope) }
+      unless invalid_scopes.empty?
+        redirect = OAuthProtocol.redirect_uri_with_params(query["redirect_uri"], error: "invalid_scope", error_description: "The following scopes are invalid: #{invalid_scopes.join(", ")}", state: query["state"])
+        raise ctx.redirect(redirect)
+      end
+      if config[:require_pkce] && (query["code_challenge"].to_s.empty? || query["code_challenge_method"].to_s.empty?)
+        redirect = OAuthProtocol.redirect_uri_with_params(query["redirect_uri"], error: "invalid_request", error_description: "pkce is required", state: query["state"])
+        raise ctx.redirect(redirect)
+      end
+      challenge_method = query["code_challenge_method"].to_s
+      if challenge_method.empty?
+        query["code_challenge_method"] = "plain" if query["code_challenge"]
+      elsif !valid_code_challenge_method?(challenge_method, config)
+        redirect = OAuthProtocol.redirect_uri_with_params(query["redirect_uri"], error: "invalid_request", error_description: "invalid code_challenge method", state: query["state"])
+        raise ctx.redirect(redirect)
+      end
+
+      if prompts.include?("consent")
+        consent_code = Crypto.random_string(32)
+        config[:store][:consents][consent_code] = {
+          query: query,
+          session: session,
+          client: client,
+          scopes: scopes,
+          expires_at: Time.now + config[:code_expires_in].to_i
+        }
+        raise ctx.redirect(OAuthProtocol.redirect_uri_with_params(config[:consent_page], consent_code: consent_code, client_id: client_data["clientId"], scope: OAuthProtocol.scope_string(scopes)))
+      end
+
+      code = Crypto.random_string(32)
+      OAuthProtocol.store_code(
+        config[:store],
+        code: code,
+        client_id: query["client_id"],
+        redirect_uri: query["redirect_uri"],
+        session: session,
+        scopes: scopes,
+        code_challenge: query["code_challenge"],
+        code_challenge_method: query["code_challenge_method"]
+      )
+      OAuthProtocol.redirect_uri_with_params(query["redirect_uri"], code: code, state: query["state"])
+    end
+
+    def mcp_prompt_without_login(value)
+      prompts = value.to_s.split(/\s+/).reject(&:empty?)
+      prompts.delete("login")
+      prompts.join(" ")
+    end
+
+    def mcp_parse_login_prompt(value)
+      parsed = JSON.parse(value.to_s)
+      parsed.is_a?(Hash) ? parsed : nil
+    rescue JSON::ParserError
+      nil
+    end
+
+    def mcp_token_endpoint(config)
+      Endpoint.new(path: "/mcp/token", method: "POST", metadata: {allowed_media_types: ["application/x-www-form-urlencoded", "application/json"]}) do |ctx|
+        mcp_set_cors_headers(ctx)
+        body = OAuthProtocol.stringify_keys(ctx.body)
+        client = mcp_authenticate_token_client!(ctx, body, config)
+        raise APIError.new("UNAUTHORIZED", message: "invalid_client") unless client
+
+        response = case body["grant_type"]
+        when OAuthProtocol::AUTH_CODE_GRANT
+          client_data = OAuthProtocol.stringify_keys(client)
+          if client_data["type"] == "public" && body["code_verifier"].to_s.empty?
+            raise APIError.new("BAD_REQUEST", message: "invalid_request")
+          end
+          code = OAuthProtocol.consume_code!(
+            config[:store],
+            body["code"],
+            client_id: client_data["clientId"],
+            redirect_uri: body["redirect_uri"],
+            code_verifier: body["code_verifier"]
+          )
+          OAuthProtocol.issue_tokens(
+            ctx,
+            config[:store],
+            model: "oauthAccessToken",
+            client: client,
+            session: code[:session],
+            scopes: code[:scopes],
+            include_refresh: code[:scopes].include?("offline_access"),
+            issuer: OAuthProtocol.issuer(ctx),
+            access_token_expires_in: config[:access_token_expires_in]
+          )
+        when OAuthProtocol::REFRESH_GRANT
+          OAuthProtocol.refresh_tokens(ctx, config[:store], model: "oauthAccessToken", client: client, refresh_token: body["refresh_token"], scopes: body["scope"], issuer: OAuthProtocol.issuer(ctx), access_token_expires_in: config[:access_token_expires_in])
+        else
+          raise APIError.new("BAD_REQUEST", message: "unsupported_grant_type")
+        end
+        ctx.json(response, headers: {"Cache-Control" => "no-store", "Pragma" => "no-cache"})
+      end
+    end
+
+    def mcp_userinfo_endpoint(config)
+      Endpoint.new(path: "/mcp/userinfo", method: "GET") do |ctx|
+        ctx.json(OAuthProtocol.userinfo(config[:store], ctx.headers["authorization"]))
+      end
+    end
+
+    def mcp_get_session_endpoint(config)
+      Endpoint.new(path: "/mcp/get-session", method: "GET") do |ctx|
+        authorization = ctx.headers["authorization"].to_s
+        token = authorization.start_with?("Bearer ") ? authorization.delete_prefix("Bearer ").strip : ""
+        next ctx.json(nil) if token.empty?
+
+        ctx.json(OAuthProtocol.token_record(config[:store], token))
+      end
+    end
+
+    def mcp_jwks_endpoint(config)
+      Endpoint.new(path: "/mcp/jwks", method: "GET") do |ctx|
+        jwt_config = config[:jwt] || {}
+        create_jwk(ctx, jwt_config) if all_jwks(ctx, jwt_config).empty?
+        ctx.json({keys: public_jwks(ctx, jwt_config).map { |key| public_jwk(key, jwt_config) }})
+      end
+    end
+
+    def mcp_normalize_config(config)
+      oidc = normalize_hash(config[:oidc_config] || {})
+      merged = config.merge(oidc.except(:metadata))
+      merged[:scopes] = (Array(config[:scopes]) + Array(oidc[:scopes])).compact.map(&:to_s).uniq
+      merged
+    end
+
+    def mcp_set_cors_headers(ctx)
+      ctx.set_header("Access-Control-Allow-Origin", "*")
+      ctx.set_header("Access-Control-Allow-Methods", "POST, OPTIONS")
+      ctx.set_header("Access-Control-Allow-Headers", "Content-Type, Authorization")
+      ctx.set_header("Access-Control-Max-Age", "86400")
+    end
+
+    def mcp_authenticate_token_client!(ctx, body, config)
+      authorization = ctx.headers["authorization"].to_s
+      if authorization.start_with?("Basic ") && body["client_id"].to_s.empty?
+        return OAuthProtocol.authenticate_client!(ctx, "oauthApplication", store_client_secret: config[:store_client_secret] || "plain")
+      end
+
+      client = OAuthProtocol.find_client(ctx, "oauthApplication", body["client_id"])
+      raise APIError.new("UNAUTHORIZED", message: "invalid_client") unless client
+
+      data = OAuthProtocol.stringify_keys(client)
+      method = data["tokenEndpointAuthMethod"] || "client_secret_basic"
+      if method != "none" && !OAuthProtocol.verify_client_secret(ctx, data["clientSecret"], body["client_secret"], config[:store_client_secret] || "plain")
+        raise APIError.new("UNAUTHORIZED", message: "invalid_client")
+      end
+      client
+    end
+  end
+end

data/lib/better_auth/plugins/multi_session.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Plugins
+    module_function
+
+    MULTI_SESSION_ERROR_CODES = {
+      "INVALID_SESSION_TOKEN" => "Invalid session token"
+    }.freeze
+
+    def multi_session(options = {})
+      config = {maximum_sessions: 5}.merge(normalize_hash(options))
+
+      Plugin.new(
+        id: "multi-session",
+        endpoints: {
+          list_device_sessions: list_device_sessions_endpoint,
+          set_active_session: set_active_session_endpoint,
+          revoke_device_session: revoke_device_session_endpoint
+        },
+        hooks: {
+          after: [
+            {
+              matcher: ->(_ctx) { true },
+              handler: ->(ctx) { set_multi_session_cookie(ctx, config) }
+            },
+            {
+              matcher: ->(ctx) { ctx.path == "/sign-out" },
+              handler: ->(ctx) { clear_multi_session_cookies(ctx) }
+            }
+          ]
+        },
+        error_codes: MULTI_SESSION_ERROR_CODES,
+        options: config
+      )
+    end
+
+    def list_device_sessions_endpoint
+      Endpoint.new(path: "/multi-session/list-device-sessions", method: "GET") 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 }
+        unique = sessions.each_with_object({}) { |entry, by_user| by_user[entry[:user]["id"]] ||= entry }.values
+
+        ctx.json(unique.map { |entry| parsed_session(ctx, entry) })
+      end
+    end
+
+    def set_active_session_endpoint
+      Endpoint.new(path: "/multi-session/set-active", method: "POST") 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)
+          raise APIError.new("UNAUTHORIZED", message: MULTI_SESSION_ERROR_CODES["INVALID_SESSION_TOKEN"])
+        end
+
+        session = ctx.context.internal_adapter.find_session(token)
+        unless session && session[:session]["expiresAt"] > Time.now
+          expire_cookie(ctx, cookie_name)
+          raise APIError.new("UNAUTHORIZED", message: MULTI_SESSION_ERROR_CODES["INVALID_SESSION_TOKEN"])
+        end
+
+        Cookies.set_session_cookie(ctx, session)
+        ctx.json(parsed_session(ctx, session))
+      end
+    end
+
+    def revoke_device_session_endpoint
+      Endpoint.new(path: "/multi-session/revoke", method: "POST") do |ctx|
+        current = Routes.current_session(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)
+          raise APIError.new("UNAUTHORIZED", message: MULTI_SESSION_ERROR_CODES["INVALID_SESSION_TOKEN"])
+        end
+
+        ctx.context.internal_adapter.delete_session(token)
+        expire_cookie(ctx, cookie_name)
+
+        if current && current[:session]["token"] == token
+          next_session = ctx.context.internal_adapter
+            .find_sessions(verified_multi_session_tokens(ctx).reject { |entry| entry == token })
+            .find { |entry| !entry[:session]["expiresAt"] || entry[:session]["expiresAt"] > Time.now }
+          if next_session
+            Cookies.set_session_cookie(ctx, next_session)
+          else
+            Cookies.delete_session_cookie(ctx)
+          end
+        end
+
+        ctx.json({status: true})
+      end
+    end
+
+    def set_multi_session_cookie(ctx, config)
+      new_session = ctx.context.new_session
+      return unless new_session && new_session[:session]
+      set_cookie = ctx.response_headers["set-cookie"].to_s
+
+      token = new_session[:session]["token"]
+      cookie_config = ctx.context.auth_cookies[:session_token]
+      cookie_name = multi_session_cookie_name(ctx, token)
+      cookies = ctx.cookies
+      return unless set_cookie.include?(cookie_config.name)
+      return if cookies.key?(cookie_name)
+
+      deleted_count = 0
+      existing_multi_cookie_names = multi_cookie_names(ctx)
+      existing_multi_cookie_names.each do |name|
+        existing_token = ctx.get_signed_cookie(name, ctx.context.secret)
+        next unless existing_token
+
+        existing_session = ctx.context.internal_adapter.find_session(existing_token)
+        next unless existing_session && existing_session[:user]["id"] == new_session[:user]["id"]
+
+        ctx.context.internal_adapter.delete_session(existing_token)
+        expire_cookie(ctx, name)
+        deleted_count += 1
+      end
+
+      current_count = existing_multi_cookie_names.length - deleted_count + 1
+      return if current_count > config[:maximum_sessions].to_i
+
+      ctx.set_signed_cookie(cookie_name, token, ctx.context.secret, cookie_config.attributes)
+      nil
+    end
+
+    def clear_multi_session_cookies(ctx)
+      tokens = []
+      multi_cookie_names(ctx).each do |name|
+        token = ctx.get_signed_cookie(name, ctx.context.secret)
+        next unless token
+
+        tokens << token if token
+        expire_cookie(ctx, canonical_multi_session_cookie_name(name))
+      end
+      ctx.context.internal_adapter.delete_sessions(tokens) unless tokens.empty?
+      nil
+    end
+
+    def verified_multi_session_tokens(ctx)
+      multi_cookie_names(ctx).filter_map { |name| ctx.get_signed_cookie(name, ctx.context.secret) }
+    end
+
+    def multi_cookie_names(ctx)
+      ctx.cookies.keys.select { |name| multi_session_cookie?(name) }
+    end
+
+    def multi_session_cookie?(name)
+      name.to_s.include?("_multi-")
+    end
+
+    def multi_session_cookie_name(ctx, token)
+      "#{ctx.context.auth_cookies[:session_token].name}_multi-#{token.to_s.downcase}"
+    end
+
+    def parsed_session(ctx, entry)
+      {
+        session: Schema.parse_output(ctx.context.options, "session", entry[:session]),
+        user: Schema.parse_output(ctx.context.options, "user", entry[:user])
+      }
+    end
+
+    def expire_cookie(ctx, name)
+      ctx.set_cookie(name, "", ctx.context.auth_cookies[:session_token].attributes.merge(max_age: 0))
+    end
+
+    def canonical_multi_session_cookie_name(name)
+      prefix = "__Secure-"
+      name.to_s.sub(/\A#{Regexp.escape(prefix)}/i, prefix)
+    end
+  end
+end