basecamp-sdk 0.7.3 → 0.9.0

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

data/lib/basecamp/oauth/discovery_result.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Oauth
+    # Result of {Oauth.discover_from_resource}: either a *selected* AS config, or
+    # a *soft* fallback to Launchpad. Hard failures are raised as
+    # {DiscoverySelectionError}, never represented here — so no consumer can
+    # convert a hard failure into a Launchpad request.
+    #
+    # @attr kind [Symbol] +:selected+ or +:fallback+
+    # @attr config [Config, nil] the selected AS config (when +:selected+)
+    # @attr issuer [String, nil] the selected issuer (when +:selected+)
+    # @attr reason [String, nil] the soft fallback reason (when +:fallback+):
+    #   +"resource_discovery_failed"+ or +"no_as_advertised"+
+    DiscoveryResult = Data.define(:kind, :config, :issuer, :reason) do
+      def self.selected(config)
+        new(kind: :selected, config: config, issuer: config.issuer, reason: nil)
+      end
+
+      def self.fallback(reason)
+        new(kind: :fallback, config: nil, issuer: nil, reason: reason)
+      end
+
+      def selected?
+        kind == :selected
+      end
+
+      def fallback?
+        kind == :fallback
+      end
+    end
+  end
+end

data/lib/basecamp/oauth/discovery_selection_error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Oauth
+    # A hard resource-first selection/validation failure. Raised — never returned
+    # as a fallback — so no consumer can convert it into a Launchpad request.
+    #
+    # The +reason+ is one of:
+    # +ambiguous_issuers+, +expected_issuer_unavailable+, +invalid_issuer_origin+,
+    # +as_fetch_failed+, +issuer_mismatch+, +capability_unavailable+.
+    #
+    # @attr reason [String] the hard-failure classification
+    class DiscoverySelectionError < OauthError
+      attr_reader :reason
+
+      # @param reason [String] the hard-failure classification
+      # @param message [String] human-readable description
+      # @param http_status [Integer, nil] HTTP status code, if applicable
+      def initialize(reason, message, http_status: nil)
+        # Only capability_unavailable is consumer/usage-shaped (validation). Every
+        # other reason — including expected_issuer_unavailable — is an AS metadata
+        # fault surfaced as api_error, matching the other four SDKs (an issuer the
+        # resource does not advertise is a metadata fault, not a caller-usage one).
+        type = reason == "capability_unavailable" ? "validation" : "api_error"
+        super(type, message, http_status: http_status)
+        @reason = reason
+      end
+    end
+  end
+end