better_auth 0.10.0 → 0.11.0

data/lib/better_auth/plugins/oauth_popup.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module BetterAuth
+  module Plugins
+    OAUTH_POPUP_MESSAGE_TYPE = "better-auth:oauth-popup"
+    OAUTH_POPUP_DATA_ELEMENT_ID = "better-auth-oauth-popup"
+    OAUTH_POPUP_MARKER_COOKIE = "oauth_popup"
+    OAUTH_POPUP_ERROR_CODES = {
+      "POPUP_SIGN_IN_FAILED" => "Popup sign-in failed",
+      "POPUP_BLOCKED" => "Sign-in popup was blocked by the browser",
+      "POPUP_CLOSED" => "Sign-in popup was closed before completing",
+      "POPUP_TIMEOUT" => "Sign-in popup timed out"
+    }.freeze
+    OAUTH_POPUP_INTERNAL_STATE_KEYS = OAuthState::INTERNAL_KEYS
+    OAUTH_POPUP_COMPLETE_SCRIPT = [
+      "(function () {",
+      "\tvar el = document.getElementById(\"better-auth-oauth-popup\");",
+      "\tif (!el) return;",
+      "\tvar payload;",
+      "\ttry {",
+      "\t\tpayload = JSON.parse(el.textContent || \"\");",
+      "\t} catch (e) {",
+      "\t\treturn;",
+      "\t}",
+      "\tvar target = window.opener || window.parent;",
+      "\tif (target && target !== window) {",
+      "\t\ttry {",
+      "\t\t\ttarget.postMessage(",
+      "\t\t\t\t{",
+      "\t\t\t\t\ttype: payload.type,",
+      "\t\t\t\t\tnonce: payload.nonce,",
+      "\t\t\t\t\ttoken: payload.token,",
+      "\t\t\t\t\tredirectTo: payload.redirectTo,",
+      "\t\t\t\t\terror: payload.error,",
+      "\t\t\t\t},",
+      "\t\t\t\tpayload.targetOrigin,",
+      "\t\t\t);",
+      "\t\t} catch (e) {}",
+      "\t}",
+      "\twindow.close();",
+      "})();",
+      ""
+    ].join("\n")
+    OAUTH_POPUP_SCRIPT_CSP_HASH = "sha256-tIo2K8VBC9SnhvdZ+9GsGkQoZm+jm/JcxL+d+i8b8KQ="
+
+    module_function
+
+    def oauth_popup
+      Plugin.new(
+        id: "oauth-popup",
+        endpoints: {
+          oauth_popup_start: oauth_popup_start_endpoint
+        },
+        hooks: {
+          after: [
+            {
+              matcher: ->(ctx) { oauth_popup_callback_path?(ctx.path) },
+              handler: ->(ctx) { oauth_popup_after_callback(ctx) }
+            }
+          ]
+        },
+        error_codes: OAUTH_POPUP_ERROR_CODES
+      )
+    end
+
+    def oauth_popup_start_endpoint
+      Endpoint.new(
+        path: "/oauth-popup/start",
+        method: "GET",
+        query_schema: Routes.request_query_schema(
+          required_strings: %w[provider popupOrigin],
+          optional_strings: %w[popupNonce callbackURL errorCallbackURL newUserCallbackURL scopes requestSignUp additionalData]
+        ),
+        metadata: {
+          hide: true,
+          openapi: {
+            parameters: [
+              {name: "provider", in: "query", required: true, schema: {type: "string"}},
+              {name: "popupOrigin", in: "query", required: true, schema: {type: "string"}},
+              {name: "popupNonce", in: "query", required: false, schema: {type: "string"}},
+              {name: "callbackURL", in: "query", required: false, schema: {type: "string"}},
+              {name: "errorCallbackURL", in: "query", required: false, schema: {type: "string"}},
+              {name: "newUserCallbackURL", in: "query", required: false, schema: {type: "string"}},
+              {name: "scopes", in: "query", required: false, schema: {type: "string"}},
+              {name: "requestSignUp", in: "query", required: false, schema: {type: "string"}},
+              {name: "additionalData", in: "query", required: false, schema: {type: "string"}}
+            ]
+          }
+        }
+      ) do |ctx|
+        query = normalize_hash(ctx.query)
+        popup_origin = oauth_popup_validate_origin!(ctx, query[:popup_origin].to_s)
+
+        nonce = query[:popup_nonce].to_s
+        invalid_redirect = oauth_popup_invalid_redirect(ctx, query, popup_origin, nonce)
+        next invalid_redirect if invalid_redirect
+
+        provider_id = query[:provider].to_s
+        provider = Routes.social_provider(ctx.context, provider_id)
+        unless provider
+          next oauth_popup_completion(ctx, popup_origin, nonce: nonce, error: {
+            code: "provider_not_found",
+            description: "Unknown provider: #{provider_id}"
+          })
+        end
+
+        code_verifier = Crypto.random_string(128)
+        scopes = query[:scopes]&.to_s&.split(",")
+        additional_data = oauth_popup_additional_data(query[:additional_data])
+        callback_url = query[:callback_url].to_s
+        callback_url = ctx.context.base_url if callback_url.empty?
+        request_sign_up = (query[:request_sign_up].to_s == "true") ? true : nil
+
+        begin
+          authorization_url = if (start = fetch_value(provider, "oauthPopupAuthorizationUrl")).respond_to?(:call)
+            start.call(
+              ctx,
+              callbackURL: callback_url,
+              errorCallbackURL: query[:error_callback_url],
+              newUserCallbackURL: query[:new_user_callback_url],
+              requestSignUp: request_sign_up,
+              scopes: scopes,
+              additionalData: additional_data,
+              codeVerifier: code_verifier
+            )
+          else
+            state_data = additional_data.merge(
+              "callbackURL" => callback_url,
+              "errorURL" => query[:error_callback_url],
+              "newUserURL" => query[:new_user_callback_url],
+              "requestSignUp" => request_sign_up,
+              "codeVerifier" => code_verifier,
+              "expiresAt" => Time.now.to_i + 600
+            ).compact
+            state = OAuthState.generate(ctx, state_data)
+            Routes.call_provider(provider, :create_authorization_url, {
+              state: state,
+              codeVerifier: code_verifier,
+              code_verifier: code_verifier,
+              redirectURI: "#{ctx.context.canonical_base_url}/callback/#{provider_id}",
+              redirect_uri: "#{ctx.context.canonical_base_url}/callback/#{provider_id}",
+              scopes: scopes
+            })
+          end
+
+          oauth_popup_set_marker(ctx, popup_origin, nonce)
+        rescue => error
+          oauth_popup_log(ctx.context, :error, "OAuth popup failed to start", error)
+          next oauth_popup_completion(ctx, popup_origin, nonce: nonce, error: {
+            code: "popup_sign_in_failed",
+            description: "Failed to start the OAuth flow."
+          })
+        end
+
+        raise ctx.redirect(authorization_url.to_s)
+      end
+    end
+
+    def oauth_popup_validate_origin!(ctx, popup_origin)
+      uri = URI.parse(popup_origin)
+      valid_scheme = %w[http https].include?(uri.scheme)
+      valid_path = uri.path.to_s.empty? || uri.path == "/"
+      absolute = valid_scheme && !uri.host.to_s.empty?
+      canonical = Configuration.origin_for(uri) if absolute
+      valid = absolute &&
+        uri.userinfo.nil? &&
+        valid_path &&
+        uri.query.nil? &&
+        uri.fragment.nil? &&
+        !popup_origin.match?(/[?*]/) &&
+        ctx.context.trusted_origin?(canonical, allow_relative_paths: false)
+      return canonical if valid
+
+      oauth_popup_log(ctx.context, :error, "OAuth popup origin is not trusted")
+      raise APIError.new("FORBIDDEN", code: "INVALID_ORIGIN", message: BASE_ERROR_CODES["INVALID_ORIGIN"])
+    rescue URI::InvalidURIError
+      raise APIError.new("FORBIDDEN", code: "INVALID_ORIGIN", message: BASE_ERROR_CODES["INVALID_ORIGIN"])
+    end
+
+    def oauth_popup_invalid_redirect(ctx, query, popup_origin, nonce)
+      {
+        callback_url: "invalid_callback_url",
+        error_callback_url: "invalid_error_callback_url",
+        new_user_callback_url: "invalid_new_user_callback_url"
+      }.each do |key, code|
+        value = query[key]
+        next if value.to_s.empty?
+        next if ctx.context.trusted_origin?(value.to_s, allow_relative_paths: true)
+
+        oauth_popup_log(ctx.context, :error, "OAuth popup redirect URL is not trusted")
+        return oauth_popup_completion(ctx, popup_origin, nonce: nonce, error: {
+          code: code,
+          description: "Untrusted redirect URL"
+        })
+      end
+      nil
+    end
+
+    def oauth_popup_additional_data(value)
+      parsed = value.is_a?(Hash) ? value : JSON.parse(value.to_s)
+      return {} unless parsed.is_a?(Hash)
+
+      parsed.reject { |key, _entry| OAUTH_POPUP_INTERNAL_STATE_KEYS.include?(key.to_s) }
+    rescue JSON::ParserError
+      {}
+    end
+
+    def oauth_popup_set_marker(ctx, popup_origin, nonce)
+      cookie = ctx.context.create_auth_cookie(OAUTH_POPUP_MARKER_COOKIE, max_age: 600)
+      ctx.set_signed_cookie(
+        cookie.name,
+        JSON.generate({popupOrigin: popup_origin, popupNonce: nonce}),
+        ctx.context.secret,
+        cookie.attributes
+      )
+    end
+
+    def oauth_popup_callback_path?(path)
+      path.to_s.start_with?("/callback/", "/oauth2/callback/")
+    end
+
+    def oauth_popup_after_callback(ctx)
+      location = ctx.response_headers["location"].to_s
+      return if location.empty?
+
+      marker_cookie = ctx.context.create_auth_cookie(OAUTH_POPUP_MARKER_COOKIE)
+      marker = ctx.get_signed_cookie(marker_cookie.name, ctx.context.secret)
+      return unless marker
+
+      Cookies.expire_cookie(ctx, marker_cookie)
+      data = JSON.parse(marker)
+      popup_origin = data.fetch("popupOrigin").to_s
+      nonce = data["popupNonce"].to_s
+      return if popup_origin.empty?
+
+      token = oauth_popup_session_token(ctx)
+      message = if token
+        {nonce: nonce, token: token, redirectTo: location}
+      else
+        error = oauth_popup_redirect_error(location)
+        return unless error
+
+        {nonce: nonce, error: error}
+      end
+
+      oauth_popup_completion(ctx, popup_origin, message)
+    rescue JSON::ParserError, KeyError
+      nil
+    end
+
+    def oauth_popup_session_token(ctx)
+      name = ctx.context.auth_cookies[:session_token].name
+      Cookies.split_set_cookie_header(ctx.response_headers["set-cookie"]).each do |line|
+        cookie = Cookies.parse_set_cookie(line)
+        next unless cookie && cookie[:name] == name
+        max_age = cookie.dig(:attributes, "max-age")
+        next if cookie[:value].empty? || (max_age.to_s.strip.match?(/\A[+-]?\d+\z/) && max_age.to_i == 0)
+
+        return URI.decode_uri_component(cookie[:value])
+      rescue ArgumentError
+        return cookie[:value]
+      end
+      nil
+    end
+
+    def oauth_popup_redirect_error(location)
+      uri = URI.parse(location)
+      params = URI.decode_www_form(uri.query.to_s).to_h
+      return if params["error"].to_s.empty?
+
+      {code: params["error"], description: params["error_description"]}.compact
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def oauth_popup_completion(ctx, popup_origin, message)
+      oauth_popup_warn_missing_bearer(ctx) if message[:token]
+      payload = {
+        type: OAUTH_POPUP_MESSAGE_TYPE,
+        targetOrigin: popup_origin
+      }.merge(message)
+      serialized = JSON.generate(payload)
+        .gsub("<", "\\u003c")
+        .gsub("\u2028", "\\u2028")
+        .gsub("\u2029", "\\u2029")
+      html = <<~HTML
+        <!doctype html>
+        <html>
+        <head><meta charset="utf-8"><title>Completing sign-in</title></head>
+        <body>
+        <script type="application/json" id="#{OAUTH_POPUP_DATA_ELEMENT_ID}">#{serialized}</script>
+        <script>#{OAUTH_POPUP_COMPLETE_SCRIPT}</script>
+        </body>
+        </html>
+      HTML
+      headers = ctx.response_headers.merge(
+        "content-type" => "text/html; charset=utf-8",
+        "content-security-policy" => "default-src 'none'; script-src '#{OAUTH_POPUP_SCRIPT_CSP_HASH}'; base-uri 'none'",
+        "cache-control" => "no-store",
+        "pragma" => "no-cache"
+      )
+      headers.delete("location")
+      Endpoint::Result.new(response: html, status: 200, headers: headers)
+    end
+
+    def oauth_popup_warn_missing_bearer(ctx)
+      return if ctx.context.options.plugins.any? { |plugin| plugin.id == "bearer" }
+      return if @oauth_popup_warned_missing_bearer
+
+      @oauth_popup_warned_missing_bearer = true
+      oauth_popup_log(
+        ctx.context,
+        :warn,
+        "OAuth popup hands the session token back via postMessage, but the `bearer` plugin is not registered. Add bearer() for embedded cross-site authentication."
+      )
+    end
+
+    def oauth_popup_log(context, level, message, *details)
+      logger = context.logger
+      if logger.respond_to?(:call)
+        logger.call(level, message, *details)
+      elsif logger.respond_to?(level)
+        logger.public_send(level, message, *details)
+      end
+    end
+  end
+end

data/lib/better_auth/plugins/oauth_protocol.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "base64"
+require "json"
 require "jwt"
 require "openssl"
 require "time"
@@ -36,11 +37,11 @@ module BetterAuth
       end
 
       def issuer(ctx)
-        ctx.context.options.base_url.to_s.empty? ? origin_for(ctx.context.base_url) : ctx.context.options.base_url
+        origin_for(ctx.context.canonical_base_url)
       end
 
       def endpoint_base(ctx)
-        ctx.context.base_url
+        ctx.context.canonical_base_url
       end
 
       def origin_for(url)
@@ -59,6 +60,7 @@ module BetterAuth
       end
 
       def validate_redirect_uri!(client, redirect_uri)
+        validate_safe_url!(redirect_uri, field: "redirect_uri")
         redirects = client_redirect_uris(client)
         return if redirects.include?(redirect_uri.to_s)
         return if loopback_redirect_match?(redirects, redirect_uri)
@@ -105,15 +107,19 @@ module BetterAuth
         value.to_s.split(",").map(&:strip).reject(&:empty?)
       end
 
-      def create_client(ctx, model:, body:, owner_session: nil, default_auth_method: "client_secret_basic", store_client_secret: "plain", unauthenticated: false, default_scopes: nil, allowed_scopes: nil, prefix: {}, dynamic_registration: false, admin: false, pairwise_secret: nil, strip_client_metadata: false, reference_id: nil)
+      def create_client(ctx, model:, body:, owner_session: nil, default_auth_method: "client_secret_basic", store_client_secret: "plain", unauthenticated: false, default_scopes: nil, allowed_scopes: nil, prefix: {}, dynamic_registration: false, admin: false, pairwise_secret: nil, strip_client_metadata: false, reference_id: nil, generate_client_id: nil, generate_client_secret: nil, client_registration_client_secret_expiration: nil)
         body = request_body!(body || {})
         requested_auth_method = body["token_endpoint_auth_method"] || default_auth_method
         validate_client_metadata_enums!(requested_auth_method, body)
         validate_admin_only_fields!(body, admin: admin)
         auth_method = unauthenticated ? "none" : requested_auth_method
         public_client = auth_method == "none"
-        client_id = Crypto.random_string(32)
-        client_secret = public_client ? nil : Crypto.random_string(32)
+        client_id = generate_client_id.respond_to?(:call) ? generate_client_id.call : Crypto.random_string(32)
+        client_secret = if public_client
+          nil
+        else
+          generate_client_secret.respond_to?(:call) ? generate_client_secret.call : Crypto.random_string(32)
+        end
         redirects = Array(body["redirect_uris"]).map(&:to_s)
         raise APIError.new("BAD_REQUEST", message: "redirect_uris is required") if redirects.empty?
         redirects.each { |uri| validate_safe_url!(uri, field: "redirect_uris") }
@@ -146,6 +152,12 @@ module BetterAuth
         else
           body["type"] || (public_client ? nil : "web")
         end
+        issued_at = Time.now.to_i
+        secret_expires_at = if client_secret && dynamic_registration && !client_registration_client_secret_expiration.nil?
+          resolve_client_secret_expires_at(client_registration_client_secret_expiration, issued_at)
+        elsif admin
+          body["client_secret_expires_at"] || 0
+        end
         data = {
           "clientId" => client_id,
           "clientSecret" => client_secret ? store_client_secret_value(ctx, client_secret, store_client_secret) : nil,
@@ -163,7 +175,7 @@ module BetterAuth
           "redirectUris" => redirects,
           "redirectUrls" => redirects.join(","),
           "postLogoutRedirectUris" => Array(body["post_logout_redirect_uris"]).map(&:to_s),
-          "clientSecretExpiresAt" => admin ? (body["client_secret_expires_at"] || 0) : nil,
+          "clientSecretExpiresAt" => secret_expires_at,
           "tokenEndpointAuthMethod" => auth_method,
           "grantTypes" => grant_types,
           "responseTypes" => response_types,
@@ -183,7 +195,10 @@ module BetterAuth
           client_id_issued_at: Time.now.to_i
         ).compact
         response[:require_pkce] = require_pkce unless require_pkce.nil?
-        response[:client_secret_expires_at] = 0 if client_secret
+        if client_secret
+          expires = stringify_keys(created || {})["clientSecretExpiresAt"] || secret_expires_at
+          response[:client_secret_expires_at] = timestamp_seconds(expires) || 0
+        end
         response
       end
 
@@ -265,7 +280,12 @@ module BetterAuth
         raise APIError.new("BAD_REQUEST", message: "pairwise subject_type requires pairwise_secret") if pairwise_secret.to_s.empty?
 
         hosts = redirects.map { |uri| URI.parse(uri).host }.uniq
-        raise APIError.new("BAD_REQUEST", message: "pairwise redirect_uris must share the same host") if hosts.length > 1
+        if hosts.length > 1
+          raise APIError.new(
+            "BAD_REQUEST",
+            message: "pairwise clients with redirect_uris on different hosts require a sector_identifier_uri, which is not yet supported. All redirect_uris must share the same host."
+          )
+        end
       rescue URI::InvalidURIError
         raise APIError.new("BAD_REQUEST", message: "invalid redirect_uris")
       end
@@ -334,8 +354,17 @@ module BetterAuth
         end
       end
 
-      def find_client(ctx, model, client_id)
-        ctx.context.adapter.find_one(model: model, where: [{field: "clientId", value: client_id.to_s}])
+      def find_client(ctx, model, client_id, cached_trusted_clients: nil)
+        client_id = client_id.to_s
+        if (cached = trusted_client_cache[client_id])
+          return cached
+        end
+
+        client = ctx.context.adapter.find_one(model: model, where: [{field: "clientId", value: client_id}])
+        if client && cached_trusted_clients&.include?(client_id)
+          trusted_client_cache[client_id] = client
+        end
+        client
       end
 
       def authenticate_client!(ctx, model, store_client_secret: "plain", prefix: {}, require_confidential: false)
@@ -390,9 +419,10 @@ module BetterAuth
         seconds && seconds <= Time.now.to_i
       end
 
-      def store_code(store, code:, client_id:, redirect_uri:, session:, scopes:, code_challenge: nil, code_challenge_method: nil, nonce: nil, reference_id: nil, auth_time: nil, expires_in: 600, store_tokens: "hashed")
+      def store_code(internal_adapter, code:, client_id:, redirect_uri:, session:, scopes:, code_challenge: nil, code_challenge_method: nil, nonce: nil, reference_id: nil, auth_time: nil, expires_in: 600, store_tokens: "hashed")
         stored_code = get_stored_token(store_tokens, code, "authorization_code")
-        store[:codes][stored_code] = {
+        expires_at = Time.now + expires_in.to_i
+        data = {
           client_id: client_id,
           redirect_uri: redirect_uri,
           session: session,
@@ -402,15 +432,19 @@ module BetterAuth
           nonce: nonce,
           reference_id: reference_id,
           auth_time: auth_time || session_auth_time(session),
-          expires_at: Time.now + expires_in.to_i
+          expires_at: expires_at.iso8601(6)
         }
+        internal_adapter.create_verification_value(identifier: stored_code, value: JSON.generate(data), expiresAt: expires_at)
       end
 
-      def consume_code!(store, code, client_id:, redirect_uri:, code_verifier: nil, store_tokens: "hashed")
+      def consume_code!(internal_adapter, code, client_id:, redirect_uri:, code_verifier: nil, store_tokens: "hashed")
         stored_code = get_stored_token(store_tokens, code.to_s, "authorization_code")
-        data = store[:codes].delete(stored_code) || store[:codes].delete(code.to_s)
-        raise APIError.new("BAD_REQUEST", message: "invalid_grant") unless data
-        raise APIError.new("BAD_REQUEST", message: "invalid_grant") if data[:expires_at] <= Time.now
+        verification = internal_adapter.consume_verification_value(stored_code)
+        verification ||= internal_adapter.consume_verification_value(code.to_s) if stored_code != code.to_s
+        data = verification && JSON.parse(verification.fetch("value"), symbolize_names: true)
+        unless data.is_a?(Hash) && !data[:client_id].to_s.empty? && !data[:redirect_uri].to_s.empty? && data[:session].is_a?(Hash) && data[:scopes].is_a?(Array)
+          raise APIError.new("BAD_REQUEST", message: "invalid_grant")
+        end
         raise APIError.new("BAD_REQUEST", message: "invalid_grant") unless data[:client_id] == client_id.to_s
         raise APIError.new("BAD_REQUEST", message: "invalid_grant") unless data[:redirect_uri] == redirect_uri.to_s
         if data[:code_challenge]
@@ -420,6 +454,8 @@ module BetterAuth
         end
 
         data
+      rescue JSON::ParserError, KeyError, TypeError
+        raise APIError.new("BAD_REQUEST", message: "invalid_grant")
       end
 
       def verify_pkce!(code_data, verifier)
@@ -452,7 +488,7 @@ module BetterAuth
         true
       end
 
-      def issue_tokens(ctx, store, model:, client:, session:, scopes:, include_refresh: false, issuer: nil, jwt_audience: nil, access_token_expires_in: 3600, refresh_token_expires_in: 2_592_000, id_token_expires_in: 3600, id_token_signer: nil, prefix: {}, audience: nil, grant_type: nil, custom_token_response_fields: nil, custom_access_token_claims: nil, custom_id_token_claims: nil, jwt_access_token: false, use_jwt_plugin: false, pairwise_secret: nil, nonce: nil, auth_time: nil, reference_id: nil, filter_id_token_claims_by_scope: false, store_tokens: "hashed")
+      def issue_tokens(ctx, store, model:, client:, session:, scopes:, include_refresh: false, issuer: nil, jwt_audience: nil, access_token_expires_in: 3600, refresh_token_expires_in: 2_592_000, id_token_expires_in: 3600, id_token_signer: nil, prefix: {}, audience: nil, grant_type: nil, custom_token_response_fields: nil, custom_access_token_claims: nil, custom_id_token_claims: nil, jwt_access_token: false, use_jwt_plugin: false, pairwise_secret: nil, nonce: nil, auth_time: nil, reference_id: nil, filter_id_token_claims_by_scope: false, store_tokens: "hashed", generate_opaque_access_token: nil, generate_refresh_token: nil, format_refresh_token: nil)
         data = stringify_keys(session || {})
         user = stringify_keys(data["user"] || data[:user] || {})
         session_data = stringify_keys(data["session"] || data[:session] || {})
@@ -460,9 +496,11 @@ module BetterAuth
         subject = subject_identifier(user["id"], client_data, pairwise_secret)
         token_auth_time = auth_time || session_auth_time({"session" => session_data})
         token_reference_id = reference_id || client_data["referenceId"]
-        access_token_value = Crypto.random_string(32)
-        refresh_token_value = include_refresh ? Crypto.random_string(32) : nil
-        refresh_token = refresh_token_value ? apply_prefix(refresh_token_value, prefix, :refresh_token) : nil
+        access_token_value = generate_opaque_access_token.respond_to?(:call) ? generate_opaque_access_token.call : Crypto.random_string(32)
+        refresh_token_value = if include_refresh
+          generate_refresh_token.respond_to?(:call) ? generate_refresh_token.call : Crypto.random_string(32)
+        end
+        refresh_token = refresh_token_value ? encode_refresh_token(refresh_token_value, prefix: prefix, format_refresh_token: format_refresh_token, session_id: session_data["id"]) : nil
         scope = scope_string(scopes)
         expires_at = Time.now + access_token_expires_in.to_i
         access_token = if jwt_access_token && audience
@@ -536,9 +574,10 @@ module BetterAuth
         response
       end
 
-      def refresh_tokens(ctx, store, model:, client:, refresh_token:, scopes: nil, issuer: nil, access_token_expires_in: 3600, refresh_token_expires_in: 2_592_000, id_token_expires_in: 3600, id_token_signer: nil, prefix: {}, audience: nil, custom_token_response_fields: nil, custom_access_token_claims: nil, custom_id_token_claims: nil, jwt_access_token: false, use_jwt_plugin: false, pairwise_secret: nil, filter_id_token_claims_by_scope: false, store_tokens: "hashed")
-        refresh_token_value = strip_prefix(refresh_token, prefix, :refresh_token)
-        data = refresh_token_value ? store[:refresh_tokens][refresh_token_value] : nil
+      def refresh_tokens(ctx, store, model:, client:, refresh_token:, scopes: nil, issuer: nil, access_token_expires_in: 3600, refresh_token_expires_in: 2_592_000, id_token_expires_in: 3600, id_token_signer: nil, prefix: {}, audience: nil, custom_token_response_fields: nil, custom_access_token_claims: nil, custom_id_token_claims: nil, jwt_access_token: false, use_jwt_plugin: false, pairwise_secret: nil, filter_id_token_claims_by_scope: false, store_tokens: "hashed", generate_opaque_access_token: nil, generate_refresh_token: nil, format_refresh_token: nil)
+        refresh_token_value = decode_refresh_token(refresh_token, prefix: prefix, format_refresh_token: format_refresh_token)
+        raise APIError.new("BAD_REQUEST", message: "invalid_grant") if refresh_token_value.to_s.empty?
+        data = store[:refresh_tokens][refresh_token_value]
         raise APIError.new("BAD_REQUEST", message: "invalid_grant") unless data
         if data["revoked"]
           revoke_refresh_family!(ctx, store, data)
@@ -583,7 +622,10 @@ module BetterAuth
           auth_time: data["authTime"],
           reference_id: data["referenceId"],
           filter_id_token_claims_by_scope: filter_id_token_claims_by_scope,
-          store_tokens: store_tokens
+          store_tokens: store_tokens,
+          generate_opaque_access_token: generate_opaque_access_token,
+          generate_refresh_token: generate_refresh_token,
+          format_refresh_token: format_refresh_token
         )
       end
 
@@ -616,8 +658,7 @@ module BetterAuth
           "exp" => expires_at.to_i
         ).compact
         if use_jwt_plugin
-          signed = sign_oauth_jwt(ctx, payload, issuer: issuer_value, audience: audience)
-          return signed if signed
+          return sign_oauth_jwt!(ctx, payload, issuer: issuer_value, audience: audience)
         end
 
         ::JWT.encode(payload, ctx.context.secret, "HS256")
@@ -694,9 +735,12 @@ module BetterAuth
         )
       end
 
-      def find_token_by_hint(store, token, hint, prefix: {})
+      def find_token_by_hint(store, token, hint, prefix: {}, format_refresh_token: nil)
         access = -> { (value = strip_prefix(token, prefix, :access_token)) && store[:tokens][value] }
-        refresh = -> { (value = strip_prefix(token, prefix, :refresh_token)) && store[:refresh_tokens][value] }
+        refresh = lambda {
+          value = decode_refresh_token(token, prefix: prefix, format_refresh_token: format_refresh_token)
+          value && store[:refresh_tokens][value]
+        }
 
         case hint.to_s
         when "access_token"
@@ -746,6 +790,65 @@ module BetterAuth
         "#{token_prefix(prefix, kind)}#{value}"
       end
 
+      def encode_refresh_token(token_value, prefix:, format_refresh_token: nil, session_id: nil)
+        formatted = if format_refresh_token.is_a?(Hash) && format_refresh_token[:encrypt].respond_to?(:call)
+          format_refresh_token[:encrypt].call(token_value, session_id)
+        else
+          token_value
+        end
+        apply_prefix(formatted, prefix, :refresh_token)
+      end
+
+      def decode_refresh_token(token, prefix:, format_refresh_token: nil)
+        value = strip_prefix(token, prefix, :refresh_token)
+        return nil if value.nil?
+
+        if format_refresh_token.is_a?(Hash) && format_refresh_token[:decrypt].respond_to?(:call)
+          decrypted = format_refresh_token[:decrypt].call(value)
+          if decrypted.is_a?(Hash)
+            decrypted[:token] || decrypted["token"]
+          else
+            decrypted.to_s
+          end
+        else
+          value
+        end
+      end
+
+      def trusted_client_cache
+        @trusted_client_cache ||= {}
+      end
+
+      def resolve_client_secret_expires_at(value, issued_at)
+        return value.to_i if value.is_a?(Numeric)
+        return value.to_i if value.is_a?(Time)
+
+        seconds = timestamp_seconds(value)
+        return seconds if seconds && !value.is_a?(String)
+
+        issued_at.to_i + parse_duration(value.to_s)
+      rescue TypeError
+        0
+      end
+
+      def parse_duration(value)
+        match = value.strip.match(/\A(-?\d+)\s*(s|sec|secs|second|seconds|m|min|mins|minute|minutes|h|hr|hrs|hour|hours|d|day|days|w|week|weeks|y|yr|yrs|year|years)(?:\s+from now|\s+ago)?\z/i)
+        raise TypeError, "Invalid time string" unless match
+
+        amount = match[1].to_i
+        amount = -amount if value.include?("ago")
+        unit = match[2].downcase
+        multiplier = case unit
+        when "s", "sec", "secs", "second", "seconds" then 1
+        when "m", "min", "mins", "minute", "minutes" then 60
+        when "h", "hr", "hrs", "hour", "hours" then 3600
+        when "d", "day", "days" then 86_400
+        when "w", "week", "weeks" then 604_800
+        else 31_557_600
+        end
+        amount * multiplier
+      end
+
       def strip_prefix(value, prefix, kind)
         token = value.to_s
         expected = token_prefix(prefix, kind)
@@ -796,8 +899,7 @@ module BetterAuth
         return signer.call(ctx, payload) if signer.respond_to?(:call)
 
         if use_jwt_plugin && ctx
-          signed = sign_oauth_jwt(ctx, payload, issuer: issuer_value, audience: audience)
-          return signed if signed
+          return sign_oauth_jwt!(ctx, payload, issuer: issuer_value, audience: audience)
         end
 
         Crypto.sign_jwt(
@@ -838,6 +940,15 @@ module BetterAuth
         BetterAuth::Plugins.sign_jwt_payload(ctx, stringify_keys(payload), config)
       end
 
+      def sign_oauth_jwt!(ctx, payload, issuer:, audience:)
+        raise BetterAuth::Error, "jwt_config" unless jwt_plugin_options(ctx)
+
+        signed = sign_oauth_jwt(ctx, payload, issuer: issuer, audience: audience)
+        raise BetterAuth::Error, "jwt_config" unless signed
+
+        signed
+      end
+
       def verify_oauth_jwt(ctx, token, issuer:, hs256_secret:)
         payload = ::JWT.decode(token.to_s, nil, false).first
         audience = payload["aud"]
@@ -955,7 +1066,6 @@ module BetterAuth
 
       def stores
         {
-          codes: {},
           tokens: {},
           refresh_tokens: {},
           consents: {}