basecamp-sdk 0.7.3 → 0.8.0

data/lib/basecamp/generated/types.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Auto-generated from OpenAPI spec. Do not edit manually.
-# Generated: 2026-03-26T04:17:28Z
+# Generated: 2026-07-22T08:33:01Z
 
 require "json"
 require "time"
@@ -2093,7 +2093,7 @@ module Basecamp
     # Notification
     class Notification
       include TypeHelpers
-      attr_accessor :created_at, :id, :updated_at, :app_url, :bookmark_url, :bucket_name, :content_excerpt, :creator, :image_url, :memory_url, :named, :participants, :previewable_attachments, :read_at, :readable_identifier, :readable_sgid, :section, :subscribed, :subscription_url, :title, :type, :unread_at, :unread_count, :unread_url
+      attr_accessor :created_at, :id, :updated_at, :app_url, :bookmark_url, :bubble_up_at, :bubble_up_url, :bucket_name, :content_excerpt, :creator, :image_url, :memory_url, :named, :participants, :previewable_attachments, :read_at, :readable_identifier, :readable_sgid, :section, :subscribed, :subscription_url, :title, :type, :unread_at, :unread_count, :unread_url
 
       # @return [Array<Symbol>]
       def self.required_fields
@@ -2106,6 +2106,8 @@ module Basecamp
         @updated_at = parse_datetime(data["updated_at"])
         @app_url = data["app_url"]
         @bookmark_url = data["bookmark_url"]
+        @bubble_up_at = parse_datetime(data["bubble_up_at"])
+        @bubble_up_url = data["bubble_up_url"]
         @bucket_name = data["bucket_name"]
         @content_excerpt = data["content_excerpt"]
         @creator = parse_type(data["creator"], "Person")
@@ -2134,6 +2136,8 @@ module Basecamp
           "updated_at" => @updated_at,
           "app_url" => @app_url,
           "bookmark_url" => @bookmark_url,
+          "bubble_up_at" => @bubble_up_at,
+          "bubble_up_url" => @bubble_up_url,
           "bucket_name" => @bucket_name,
           "content_excerpt" => @content_excerpt,
           "creator" => @creator,
@@ -2164,9 +2168,10 @@ module Basecamp
     # OutOfOffice
     class OutOfOffice
       include TypeHelpers
-      attr_accessor :enabled, :end_date, :ongoing, :person, :start_date
+      attr_accessor :back_on_date, :enabled, :end_date, :ongoing, :person, :start_date
 
       def initialize(data = {})
+        @back_on_date = data["back_on_date"]
         @enabled = parse_boolean(data["enabled"])
         @end_date = data["end_date"]
         @ongoing = parse_boolean(data["ongoing"])
@@ -2176,6 +2181,7 @@ module Basecamp
 
       def to_h
         {
+          "back_on_date" => @back_on_date,
           "enabled" => @enabled,
           "end_date" => @end_date,
           "ongoing" => @ongoing,
@@ -2219,7 +2225,7 @@ module Basecamp
     # OutOfOfficePerson
     class OutOfOfficePerson
       include TypeHelpers
-      attr_accessor :id, :name
+      attr_accessor :id, :avatar_url, :name
 
       # @return [Array<Symbol>]
       def self.required_fields
@@ -2228,12 +2234,14 @@ module Basecamp
 
       def initialize(data = {})
         @id = parse_integer(data["id"])
+        @avatar_url = data["avatar_url"]
         @name = data["name"]
       end
 
       def to_h
         {
           "id" => @id,
+          "avatar_url" => @avatar_url,
           "name" => @name,
         }.compact
       end
@@ -2246,7 +2254,7 @@ module Basecamp
     # Person
     class Person
       include TypeHelpers
-      attr_accessor :id, :name, :admin, :attachable_sgid, :avatar_url, :bio, :can_access_hill_charts, :can_access_timesheet, :can_manage_people, :can_manage_projects, :can_ping, :client, :company, :created_at, :email_address, :employee, :location, :owner, :personable_type, :time_zone, :title, :updated_at, :system_label
+      attr_accessor :id, :name, :admin, :attachable_sgid, :avatar_url, :bio, :can_access_hill_charts, :can_access_timesheet, :can_manage_people, :can_manage_projects, :can_ping, :client, :company, :created_at, :email_address, :employee, :location, :owner, :personable_type, :tagline, :time_zone, :title, :updated_at, :system_label
 
       # @return [Array<Symbol>]
       def self.required_fields
@@ -2274,6 +2282,7 @@ module Basecamp
         @location = data["location"]
         @owner = parse_boolean(data["owner"])
         @personable_type = data["personable_type"]
+        @tagline = data["tagline"]
         @time_zone = data["time_zone"]
         @title = data["title"]
         @updated_at = parse_datetime(data["updated_at"])
@@ -2300,6 +2309,7 @@ module Basecamp
           "location" => @location,
           "owner" => @owner,
           "personable_type" => @personable_type,
+          "tagline" => @tagline,
           "time_zone" => @time_zone,
           "title" => @title,
           "updated_at" => @updated_at,
@@ -2427,7 +2437,7 @@ module Basecamp
     # Project
     class Project
       include TypeHelpers
-      attr_accessor :app_url, :created_at, :id, :name, :status, :updated_at, :url, :bookmark_url, :bookmarked, :client_company, :clients_enabled, :clientside, :description, :dock, :purpose
+      attr_accessor :app_url, :created_at, :id, :name, :status, :updated_at, :url, :bookmark_url, :bookmarked, :client_company, :clients_enabled, :clientside, :description, :dock, :end_date, :purpose, :start_date
 
       # @return [Array<Symbol>]
       def self.required_fields
@@ -2449,7 +2459,9 @@ module Basecamp
         @clientside = parse_type(data["clientside"], "ClientSide")
         @description = data["description"]
         @dock = parse_array(data["dock"], "DockItem")
+        @end_date = data["end_date"]
         @purpose = data["purpose"]
+        @start_date = data["start_date"]
       end
 
       def to_h
@@ -2468,7 +2480,9 @@ module Basecamp
           "clientside" => @clientside,
           "description" => @description,
           "dock" => @dock,
+          "end_date" => @end_date,
           "purpose" => @purpose,
+          "start_date" => @start_date,
         }.compact
       end
 
@@ -3375,7 +3389,7 @@ module Basecamp
     # Todo
     class Todo
       include TypeHelpers
-      attr_accessor :app_url, :bucket, :content, :created_at, :creator, :id, :inherits_status, :parent, :status, :title, :type, :updated_at, :url, :visible_to_clients, :assignees, :bookmark_url, :boosts_count, :boosts_url, :comments_count, :comments_url, :completed, :completion_subscribers, :completion_url, :description, :due_on, :position, :starts_on, :subscription_url
+      attr_accessor :app_url, :bucket, :content, :created_at, :creator, :id, :inherits_status, :parent, :status, :title, :type, :updated_at, :url, :visible_to_clients, :assignees, :bookmark_url, :boosts_count, :boosts_url, :comments_count, :comments_url, :completed, :completion_subscribers, :completion_url, :description, :due_on, :position, :starts_on, :steps, :subscription_url
 
       # @return [Array<Symbol>]
       def self.required_fields
@@ -3410,6 +3424,7 @@ module Basecamp
         @due_on = data["due_on"]
         @position = parse_integer(data["position"])
         @starts_on = data["starts_on"]
+        @steps = parse_array(data["steps"], "CardStep")
         @subscription_url = data["subscription_url"]
       end
 
@@ -3442,6 +3457,7 @@ module Basecamp
           "due_on" => @due_on,
           "position" => @position,
           "starts_on" => @starts_on,
+          "steps" => @steps,
           "subscription_url" => @subscription_url,
         }.compact
       end
@@ -3662,7 +3678,7 @@ module Basecamp
     # Todoset
     class Todoset
       include TypeHelpers
-      attr_accessor :app_url, :bucket, :created_at, :creator, :id, :inherits_status, :name, :status, :title, :type, :updated_at, :url, :visible_to_clients, :app_todolists_url, :bookmark_url, :completed, :completed_ratio, :position, :todolists_count, :todolists_url
+      attr_accessor :app_url, :bucket, :created_at, :creator, :id, :inherits_status, :name, :status, :title, :type, :updated_at, :url, :visible_to_clients, :app_todolists_url, :app_todos_url, :bookmark_url, :completed, :completed_loose_todos_count, :completed_ratio, :position, :todolists_count, :todolists_url, :todos_count, :todos_url
 
       # @return [Array<Symbol>]
       def self.required_fields
@@ -3684,12 +3700,16 @@ module Basecamp
         @url = data["url"]
         @visible_to_clients = parse_boolean(data["visible_to_clients"])
         @app_todolists_url = data["app_todolists_url"]
+        @app_todos_url = data["app_todos_url"]
         @bookmark_url = data["bookmark_url"]
         @completed = parse_boolean(data["completed"])
+        @completed_loose_todos_count = parse_integer(data["completed_loose_todos_count"])
         @completed_ratio = data["completed_ratio"]
         @position = parse_integer(data["position"])
         @todolists_count = parse_integer(data["todolists_count"])
         @todolists_url = data["todolists_url"]
+        @todos_count = parse_integer(data["todos_count"])
+        @todos_url = data["todos_url"]
       end
 
       def to_h
@@ -3708,12 +3728,16 @@ module Basecamp
           "url" => @url,
           "visible_to_clients" => @visible_to_clients,
           "app_todolists_url" => @app_todolists_url,
+          "app_todos_url" => @app_todos_url,
           "bookmark_url" => @bookmark_url,
           "completed" => @completed,
+          "completed_loose_todos_count" => @completed_loose_todos_count,
           "completed_ratio" => @completed_ratio,
           "position" => @position,
           "todolists_count" => @todolists_count,
           "todolists_url" => @todolists_url,
+          "todos_count" => @todos_count,
+          "todos_url" => @todos_url,
         }.compact
       end
 

data/lib/basecamp/http.rb

@@ -61,12 +61,56 @@ module Basecamp
     end
 
     # Performs a GET request to an absolute URL.
-    # Used for endpoints not on the base API (e.g., Launchpad).
+    # Used for endpoints not on the base API.
+    #
+    # This is the PUBLIC, general path and it credentials cross-origin for ONE
+    # destination only: the exact Launchpad authorization URL
+    # ({Basecamp::Security::LAUNCHPAD_AUTHORIZATION_URL}). Every other foreign
+    # origin — including an endpoint-shaped URL such as
+    # +https://evil.example/authorization.json+ — trips the same-origin guard, so
+    # the bearer token only ever reaches Launchpad, the configured base URL, or
+    # localhost. There is deliberately NO raw-string trusted-origin parameter: a
+    # syntactically valid origin does not prove discovery provenance, so the ONE
+    # legitimate cross-origin discovery destination goes through the narrow
+    # {#get_authorization_document}, which derives its issuer from internal
+    # discovery of the configured base URL rather than any caller argument.
+    #
     # @param url [String] absolute URL
     # @param params [Hash] query parameters
     # @return [Response]
     def get_absolute(url, params: {})
-      request(:get, url, params: params)
+      Security.require_https_unless_localhost!(url, "absolute URL")
+
+      allow_cross_origin = url == Security::LAUNCHPAD_AUTHORIZATION_URL
+      request(:get, url, params: params, allow_cross_origin: allow_cross_origin)
+    end
+
+    # Fetches the credentialed authorization document (the fixed +authorization.json+
+    # path). This is the ONE sanctioned cross-origin credential path besides
+    # Launchpad, and the origin that receives the bearer token is NOT
+    # caller-supplied.
+    #
+    # The issuer is derived HERE by running resource-first discovery (SPEC.md §16)
+    # against this client's OWN configured base URL, then binding to whatever
+    # issuer discovery selects and validates (RFC 8414 issuer binding). A soft
+    # fallback fetches Launchpad's fixed URL; a hard discovery failure raises. The
+    # request URL is CONSTRUCTED from the discovered issuer origin + the fixed path
+    # (string concatenation, never URL re-parsing). Because no caller-supplied
+    # config, origin, or path reaches this method, there is no public API through
+    # which a forged issuer could redirect the credential to a foreign host —
+    # discovery provenance is structural, not a claim about a passed-in object.
+    #
+    # @return [Response]
+    # @raise [Oauth::DiscoverySelectionError] on a hard discovery failure
+    # @raise [Basecamp::UsageError] when the discovered issuer is not an origin root
+    def get_authorization_document
+      result = Oauth.discover_from_resource(@config.base_url)
+      if result.selected?
+        issuer_origin = Security.require_origin_root!(result.issuer, "selected issuer origin")
+        request(:get, "#{issuer_origin}/authorization.json", allow_cross_origin: true)
+      else
+        get_absolute(Security::LAUNCHPAD_AUTHORIZATION_URL)
+      end
     end
 
     # Performs a POST request.
@@ -296,18 +340,18 @@ module Basecamp
       end
     end
 
-    def request(method, path, params: {}, body: nil)
-      url = build_url(path)
+    def request(method, path, params: {}, body: nil, allow_cross_origin: false)
+      url = build_url(path, allow_cross_origin: allow_cross_origin)
 
       # Mutations don't retry on 429/5xx to avoid duplicating data
       if method == :get
-        request_with_retry(method, url, params: params)
+        request_with_retry(method, url, params: params, allow_cross_origin: allow_cross_origin)
       else
-        single_request(method, url, params: params, body: body, attempt: 1)
+        single_request(method, url, params: params, body: body, attempt: 1, allow_cross_origin: allow_cross_origin)
       end
     end
 
-    def request_with_retry(method, url, params: {})
+    def request_with_retry(method, url, params: {}, allow_cross_origin: false)
       attempt = 0
       last_error = nil
 
@@ -316,7 +360,7 @@ module Basecamp
         break if attempt > @config.max_retries
 
         begin
-          return single_request(method, url, params: params, body: nil, attempt: attempt)
+          return single_request(method, url, params: params, body: nil, attempt: attempt, allow_cross_origin: allow_cross_origin)
         rescue Basecamp::RateLimitError, Basecamp::NetworkError, Basecamp::ApiError => e
           raise e unless e.retryable?
 
@@ -336,7 +380,8 @@ module Basecamp
       raise last_error || Basecamp::ApiError.new("Request failed after #{@config.max_retries} retries")
     end
 
-    def single_request(method, url, params:, body:, attempt:, retry_count: 0)
+    def single_request(method, url, params:, body:, attempt:, retry_count: 0, allow_cross_origin: false)
+      assert_credential_origin!(url, allow_cross_origin)
       info = RequestInfo.new(method: method.to_s.upcase, url: url, attempt: attempt)
       @hooks.on_request_start(info)
 
@@ -370,7 +415,7 @@ module Basecamp
         # After a successful token refresh on 401, retry the request once
         if error.is_a?(Basecamp::AuthError) && error.http_status == 401 && retry_count < 1 && @token_refreshed
           @token_refreshed = false
-          return single_request(method, url, params: params, body: body, attempt: attempt, retry_count: retry_count + 1)
+          return single_request(method, url, params: params, body: body, attempt: attempt, retry_count: retry_count + 1, allow_cross_origin: allow_cross_origin)
         end
 
         raise error
@@ -393,6 +438,7 @@ module Basecamp
     end
 
     def single_request_raw(method, url, body:, content_type:, attempt:)
+      assert_credential_origin!(url, false)
       info = RequestInfo.new(method: method.to_s.upcase, url: url, attempt: attempt)
       @hooks.on_request_start(info)
 
@@ -467,17 +513,42 @@ module Basecamp
       err
     end
 
-    def build_url(path)
-      if path.start_with?("https://")
-        return path
-      elsif path.start_with?("http://")
-        raise Basecamp::UsageError.new("URL must use HTTPS: #{path}")
+    def build_url(path, allow_cross_origin: false)
+      # Schemes are case-insensitive (RFC 3986): detect absolute URLs on a
+      # lowercased copy so HTTPS://... is not mis-joined onto the base URL.
+      lower_path = path.downcase
+      if lower_path.start_with?("https://")
+        return path if allow_cross_origin
+        return path if Security.localhost?(path) || Security.same_origin?(path, @config.base_url)
+
+        raise Basecamp::UsageError.new("URL origin does not match configured base URL: #{Security.truncate(path)}")
+      elsif lower_path.start_with?("http://")
+        # Localhost may use plain HTTP for local development; every other host
+        # must use HTTPS.
+        return path if Security.localhost?(path)
+
+        raise Basecamp::UsageError.new("URL must use HTTPS: #{Security.truncate(path)}")
       end
 
       path = "/#{path}" unless path.start_with?("/")
       "#{@config.base_url}#{path}"
     end
 
+    # Attach-point backstop: refuse to attach credentials to a foreign origin
+    # before the auth strategy adds the bearer token. Localhost is carved out
+    # for dev/test. allow_cross_origin is granted only by get_absolute (for the
+    # trusted Launchpad authorization endpoint) or get_authorization_document (for
+    # a URL constructed against an issuer that internal discovery selected and
+    # validated); every other absolute URL must be same-origin with the base URL.
+    def assert_credential_origin!(url, allow_cross_origin)
+      return if allow_cross_origin
+      return if Security.localhost?(url) || Security.same_origin?(url, @config.base_url)
+
+      raise Basecamp::UsageError.new(
+        "Refusing to send credentials to a different origin than base URL: #{Security.truncate(url)}"
+      )
+    end
+
     def calculate_delay(attempt, server_retry_after)
       return server_retry_after if server_retry_after&.positive?
 

data/lib/basecamp/oauth/config.rb

@@ -2,26 +2,41 @@
 
 module Basecamp
   module Oauth
-    # OAuth 2 server configuration from discovery endpoint.
+    # OAuth 2 server configuration from an Authorization Server Metadata document
+    # (RFC 8414).
+    #
+    # As of BC5 resource-first discovery, +authorization_endpoint+ is OPTIONAL:
+    # device-only authorization servers omit it, so authorization-code consumers
+    # MUST assert its presence before use. +token_endpoint+ stays required.
     #
     # @attr issuer [String] The authorization server's issuer identifier
-    # @attr authorization_endpoint [String] URL of the authorization endpoint
+    # @attr authorization_endpoint [String, nil] URL of the authorization endpoint (optional)
     # @attr token_endpoint [String] URL of the token endpoint
+    # @attr device_authorization_endpoint [String, nil] URL of the RFC 8628 device authorization endpoint
     # @attr registration_endpoint [String, nil] URL of the dynamic client registration endpoint
     # @attr scopes_supported [Array<String>, nil] List of OAuth 2 scopes supported
+    # @attr grant_types_supported [Array<String>, nil] OAuth 2 grant types the server supports
+    # NOTE: +device_authorization_endpoint+ is APPENDED after the pre-existing
+    # members. Data.define's member order is the positional/deconstruct order, so
+    # inserting a new field mid-list would shift positional callers (and pattern
+    # matches). Keep new fields last for positional compatibility.
     Config = Data.define(
       :issuer,
       :authorization_endpoint,
       :token_endpoint,
       :registration_endpoint,
-      :scopes_supported
+      :scopes_supported,
+      :grant_types_supported,
+      :device_authorization_endpoint
     ) do
       def initialize(
         issuer:,
-        authorization_endpoint:,
         token_endpoint:,
+        authorization_endpoint: nil,
         registration_endpoint: nil,
-        scopes_supported: nil
+        scopes_supported: nil,
+        grant_types_supported: nil,
+        device_authorization_endpoint: nil
       )
         super
       end

data/lib/basecamp/oauth/discovery.rb

@@ -1,91 +1,161 @@
 # frozen_string_literal: true
 
-require "faraday"
-require "json"
-
 module Basecamp
   module Oauth
-    # Fetches OAuth 2 server configuration from discovery endpoints.
+    # Fetches RFC 8414 OAuth 2 Authorization Server Metadata and binds the
+    # returned +issuer+ to the requested issuer origin (hop 2 of resource-first
+    # discovery).
     class Discovery
-      # @param http_client [Faraday::Connection, nil] HTTP client (uses default if nil)
-      # @param timeout [Integer] Request timeout in seconds (default: 10)
-      def initialize(http_client: nil, timeout: 10)
-        @http_client = http_client || build_default_client(timeout)
+      # Structured marker: AS metadata failed the RFC 8414 issuer code-point
+      # bind. Raised (never message-matched) so {Oauth.discover_from_resource}
+      # classifies an issuer mismatch by CLASS via {Oauth.as_failure_error} —
+      # brittle, locale-sensitive substring matching is gone. Kept in the
+      # discovery layer, deliberately NOT in the device error files that
+      # {DeviceFlowError} shares.
+      class IssuerBindingError < OauthError
+        def initialize(message, http_status: nil)
+          super("api_error", message, http_status: http_status)
+        end
       end
 
-      # Discovers OAuth configuration from the well-known endpoint.
-      #
-      # Fetches the OAuth 2 Authorization Server Metadata from:
-      # `{base_url}/.well-known/oauth-authorization-server`
+      # @param http_client [Faraday::Connection, nil] HTTP client (SSRF-hardened default if nil)
+      # @param timeout [Integer] request timeout in seconds (default: 10)
+      # @param max_body_bytes [Integer] bounded read cap in bytes
+      def initialize(http_client: nil, timeout: 10, max_body_bytes: Fetcher::DEFAULT_MAX_BODY_BYTES)
+        Fetcher.ensure_redirects_suppressed!(http_client) if http_client
+        # Normalize before building the client and before the fetch computes its
+        # wall-clock deadline: a non-finite/non-positive timeout must not disable
+        # either bound (see Fetcher.normalize_timeout).
+        @timeout = Fetcher.normalize_timeout(timeout)
+        @http_client = http_client || Fetcher.build_client(@timeout)
+        # Normalize the public cap to a finite non-negative Integer: a nil, float,
+        # or Float::INFINITY would otherwise disable the streaming memory bound
+        # (an infinite/undefined cap never trips +total > max_body_bytes+),
+        # reintroducing an SSRF/OOM risk. Mirrors Resource#initialize.
+        @max_body_bytes =
+          if max_body_bytes.is_a?(Integer) && max_body_bytes >= 0
+            max_body_bytes
+          else
+            Fetcher::DEFAULT_MAX_BODY_BYTES
+          end
+      end
+
+      # Discovers OAuth configuration from
+      # <tt>{base_url}/.well-known/oauth-authorization-server</tt>, binding the
+      # returned +issuer+ to +base_url+ by code-point (RFC 8414 §3.3/§4, no
+      # normalization beyond origin-root parsing). +token_endpoint+ is required;
+      # +authorization_endpoint+ is optional (device-only servers omit it).
       #
-      # @param base_url [String] The OAuth server's base URL (e.g., "https://launchpad.37signals.com")
-      # @return [Config] The OAuth server configuration
-      # @raise [OauthError] on network or parsing errors
+      # @param base_url [String] the OAuth server's issuer origin
+      # @return [Config] the OAuth server configuration
+      # @raise [Basecamp::UsageError] on a malformed origin
+      # @raise [OauthError] +api_error+ on invalid metadata / issuer mismatch
       #
       # @example
-      #   discovery = Basecamp::Oauth::Discovery.new
-      #   config = discovery.discover("https://launchpad.37signals.com")
-      #   puts config.token_endpoint
-      #   # => "https://launchpad.37signals.com/authorization/token"
+      #   config = Basecamp::Oauth::Discovery.new.discover("https://launchpad.37signals.com")
+      #   config.token_endpoint # => "https://launchpad.37signals.com/authorization/token"
       def discover(base_url)
-        Basecamp::Security.require_https_unless_localhost!(base_url, "discovery base URL")
+        issuer_origin = Basecamp::Security.require_origin_root!(base_url, "OAuth discovery base URL")
+        # Bind against the caller's raw +base_url+ (RFC 8414 §3.3, SPEC.md §16 "NO
+        # normalization"); the normalized origin is only for the fetch URL.
+        discover_and_bind(issuer_origin, base_url)
+      end
 
-        normalized_base = base_url.chomp("/")
-        discovery_url = "#{normalized_base}/.well-known/oauth-authorization-server"
+      # Resource-first entry: validate +advertised_issuer+ as an origin root, then
+      # fetch from the normalized origin and bind the AS metadata +issuer+ against
+      # the RAW advertised string by code-point. Routing and binding are distinct —
+      # an AS whose issuer matches what the resource advertised (e.g. a trailing
+      # slash or explicit default port) binds instead of being normalized away into
+      # a false +issuer_mismatch+. Validation happens HERE so there is NO public
+      # unvalidated-fetch entry point: the SSRF origin policy is always enforced.
+      #
+      # @param advertised_issuer [String] the raw issuer string a resource advertised
+      # @raise [Basecamp::UsageError] on a malformed advertised origin
+      def discover_advertised(advertised_issuer)
+        issuer_origin = Basecamp::Security.require_origin_root!(advertised_issuer, "advertised issuer")
+        discover_and_bind(issuer_origin, advertised_issuer)
+      end
 
-        response = @http_client.get(discovery_url) do |req|
-          req.headers["Accept"] = "application/json"
-        end
+      private
 
-        unless response.success?
-          raise OauthError.new(
-            "network",
-            "OAuth discovery failed with status #{response.status}: #{Basecamp::Security.truncate(response.body)}",
-            http_status: response.status
-          )
+        # Fetch AS metadata from +issuer_origin+ (an ALREADY-VALIDATED origin root)
+        # but bind the returned +issuer+ against +bind_issuer+ by code-point. Kept
+        # private: it does no origin validation of its own, so exposing it would be
+        # an unvalidated-fetch entry point that defeats the SSRF origin policy.
+        def discover_and_bind(issuer_origin, bind_issuer)
+          discovery_url = "#{issuer_origin}/.well-known/oauth-authorization-server"
+          data = Fetcher.fetch_json(@http_client, discovery_url, timeout: @timeout, max_body_bytes: @max_body_bytes)
+          parse_and_bind(data, bind_issuer)
         end
 
-        Basecamp::Security.check_body_size!(response.body, Basecamp::Security::MAX_ERROR_BODY_BYTES, "Discovery")
+        # Universal validation only: +issuer+ + +token_endpoint+ present and
+        # non-empty, issuer identical by code-point, and any present +*_endpoint+
+        # field non-empty. Per-grant endpoint checks are the consumer's job.
+        def parse_and_bind(data, expected_issuer_origin)
+          issuer = data["issuer"]
+          if !issuer.is_a?(String) || issuer.empty?
+            raise OauthError.new("api_error", "Invalid OAuth discovery response: missing required fields: issuer")
+          end
 
-        data = JSON.parse(response.body)
-        validate_discovery_response!(data)
+          # RFC 8414 §3.3/§4: issuer identical by code-point. No normalization.
+          unless issuer == expected_issuer_origin
+            raise IssuerBindingError.new(
+              "OAuth issuer mismatch: metadata issuer #{issuer.inspect} does not equal #{expected_issuer_origin.inspect}"
+            )
+          end
 
-        Config.new(
-          issuer: data["issuer"],
-          authorization_endpoint: data["authorization_endpoint"],
-          token_endpoint: data["token_endpoint"],
-          registration_endpoint: data["registration_endpoint"],
-          scopes_supported: data["scopes_supported"]
-        )
-      rescue Faraday::Error => e
-        raise OauthError.new("network", "OAuth discovery failed: #{e.message}", retryable: true)
-      rescue JSON::ParserError => e
-        raise OauthError.new("api_error", "Failed to parse discovery response: #{e.message}")
-      end
+          token_endpoint = data["token_endpoint"]
+          if !token_endpoint.is_a?(String) || token_endpoint.empty?
+            raise OauthError.new("api_error", "Invalid OAuth discovery response: missing required fields: token_endpoint")
+          end
 
-      private
+          reject_empty_endpoints!(data)
+          validate_string_array!(data, "grant_types_supported")
+          validate_string_array!(data, "scopes_supported")
 
-      def build_default_client(timeout)
-        Faraday.new do |conn|
-          conn.options.timeout = timeout
-          conn.options.open_timeout = timeout
-          conn.adapter Faraday.default_adapter
+          Config.new(
+            issuer: issuer,
+            authorization_endpoint: data["authorization_endpoint"],
+            token_endpoint: token_endpoint,
+            device_authorization_endpoint: data["device_authorization_endpoint"],
+            registration_endpoint: data["registration_endpoint"],
+            scopes_supported: data["scopes_supported"],
+            grant_types_supported: data["grant_types_supported"]
+          )
         end
-      end
 
-      def validate_discovery_response!(data)
-        missing = []
-        missing << "issuer" unless data["issuer"]
-        missing << "authorization_endpoint" unless data["authorization_endpoint"]
-        missing << "token_endpoint" unless data["token_endpoint"]
+        # Any endpoint field that IS present must be a non-empty String: "" is a
+        # truthy value in Ruby and must be rejected, and a non-string endpoint
+        # (array/number/object, or a present JSON null) is malformed metadata —
+        # a present null is NOT the same as an absent key.
+        def reject_empty_endpoints!(data)
+          data.each do |key, value|
+            next unless key.end_with?("_endpoint")
 
-        return if missing.empty?
+            unless value.is_a?(String) && !value.empty?
+              raise OauthError.new("api_error", "Invalid OAuth discovery response: invalid #{key}")
+            end
+          end
+        end
 
-        raise OauthError.new(
-          "api_error",
-          "Invalid OAuth discovery response: missing required fields: #{missing.join(", ")}"
-        )
-      end
+        # A metadata list field (e.g. +grant_types_supported+, +scopes_supported+),
+        # when present, must be an array of strings. A bare string must never be
+        # accepted: substring-matching +grant_types_supported+ could falsely enable
+        # a grant such as device_code, and a non-array is malformed metadata.
+        def validate_string_array!(data, key)
+          # Distinguish an ABSENT key from a present JSON null: a present null is
+          # malformed (the field must be an array of strings when present), while
+          # an absent key is legitimately unset.
+          return unless data.key?(key)
+
+          value = data[key]
+          unless value.is_a?(Array) && value.all?(String)
+            raise OauthError.new(
+              "api_error",
+              "Invalid OAuth discovery response: #{key} must be an array of strings"
+            )
+          end
+        end
     end
   end
 end