basecamp-sdk 0.7.3 → 0.8.0

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

data/lib/basecamp/oauth/fetcher.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Basecamp
+  module Oauth
+    # SSRF-hardened fetch of a small OAuth discovery JSON document, shared by both
+    # discovery hops (RFC 9728 resource metadata and RFC 8414 AS metadata).
+    #
+    # RFC 9728 §7.7 flags SSRF via attacker-influenced metadata: advertised AS
+    # URLs are untrusted input. Every fetch therefore:
+    #
+    # 1. requires HTTPS (localhost exempt) — enforced by the origin-root profile
+    #    ({Basecamp::Security.require_origin_root!}) before this is called;
+    # 2. bounds the timeout — both a per-read socket timeout AND a monotonic
+    #    wall-clock deadline over the whole streaming read (a per-read timeout
+    #    alone resets on every chunk, so a slow-drip peer could hang the fetch);
+    # 3. suppresses redirects — the default Faraday connection carries no redirect
+    #    middleware, so an attacker-controlled 3xx +Location+ is surfaced as a
+    #    non-2xx +api_error+ rather than chased;
+    # 4. reads the body under a genuine bounded/streaming cap that aborts the read
+    #    the moment the accumulated size exceeds the limit (via Faraday's +on_data+
+    #    streaming callback) — NOT a post-hoc size check on an already-buffered
+    #    body.
+    #
+    # Non-2xx on either hop maps to +api_error+ (not +network+).
+    module Fetcher
+      # Discovery documents are tiny; cap the read at 1 MiB by default.
+      DEFAULT_MAX_BODY_BYTES = 1 * 1024 * 1024
+
+      # Default request timeout in seconds when a caller supplies none or an
+      # invalid one.
+      DEFAULT_TIMEOUT = 10
+
+      # Coerce the public timeout to a finite, positive numeric. A nil, non-numeric,
+      # non-positive, or +Float::INFINITY+/+NaN+ value would otherwise disable BOTH
+      # the socket timeout and the wall-clock deadline in {fetch_json} (+now + inf+
+      # never trips), letting a slow-drip peer hold the fetch open indefinitely.
+      # Mirrors the +max_body_bytes+ normalization in the discovery initializers.
+      #
+      # @param timeout [Object] caller-supplied timeout
+      # @return [Numeric] a finite, positive timeout in seconds
+      def self.normalize_timeout(timeout)
+        # +real?+ gates out Complex before +finite?+/+positive?+ (which Complex does
+        # not define — calling them would raise NoMethodError). Integer, Float, and
+        # Rational are all real and answer both.
+        return timeout if timeout.is_a?(Numeric) && timeout.real? && timeout.finite? && timeout.positive?
+
+        DEFAULT_TIMEOUT
+      end
+
+      # Raised internally to abort a streaming read once the cap is exceeded.
+      # Never escapes this module — it is mapped to an OauthError.
+      class BodyTooLarge < StandardError; end
+
+      # Raised internally when a streaming read exceeds its wall-clock deadline.
+      # Never escapes this module — it is mapped to a retryable +network+ OauthError.
+      class ReadDeadlineExceeded < StandardError; end
+
+      # Builds a +[chunks, on_data]+ pair for a genuine bounded/streaming read.
+      # Assign +on_data+ to a request's +req.options.on_data+; after the request
+      # returns, +chunks.join+ is the accumulated body. The proc raises
+      # {BodyTooLarge} the moment the accumulated size exceeds +max_body_bytes+,
+      # so an oversized body is never fully buffered. Callers rescue
+      # {BodyTooLarge} and map it to their own error. Shared by both discovery
+      # hops and the device flow so every OAuth response reads under the same cap.
+      #
+      # +req.options.timeout+ only bounds each individual socket read, and every
+      # +on_data+ chunk resets it — so a peer dripping one byte before each read
+      # timeout can hold the connection open arbitrarily long without ever tripping
+      # the cap. When a monotonic +deadline+ is supplied, the proc raises
+      # {ReadDeadlineExceeded} the moment the WHOLE read outlives it, matching the
+      # wall-clock bound the other SDKs enforce (Python's monotonic deadline, Go's
+      # context, TS's abort timer, Kotlin's requestTimeoutMillis).
+      #
+      # @param max_body_bytes [Integer] bounded read cap in bytes
+      # @param deadline [Float, nil] monotonic clock deadline (CLOCK_MONOTONIC seconds)
+      # @return [Array(Array<String>, Proc)] the chunk buffer and the +on_data+ proc
+      def self.bounded_reader(max_body_bytes, deadline: nil)
+        chunks = []
+        total = 0
+        reader = proc do |chunk, _received|
+          if deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+            raise ReadDeadlineExceeded
+          end
+
+          total += chunk.bytesize
+          raise BodyTooLarge if total > max_body_bytes
+
+          chunks << chunk
+        end
+        [ chunks, reader ]
+      end
+
+      # Builds the default SSRF-hardened Faraday connection. No redirect
+      # middleware is registered, so redirects are not followed.
+      #
+      # @param timeout [Integer] request + connect timeout in seconds
+      # @return [Faraday::Connection]
+      def self.build_client(timeout)
+        Faraday.new do |conn|
+          conn.options.timeout = timeout
+          conn.options.open_timeout = timeout
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      # Rejects an INJECTED connection whose middleware stack we cannot verify to
+      # be redirect-free. Redirect suppression is a load-bearing SSRF control (RFC
+      # 9728 §7.7): a caller-supplied client that follows redirects would silently
+      # chase an attacker-controlled +Location+. A class-NAME heuristic (matching
+      # +/redirect/+) is bypassable by a follower whose class name does not contain
+      # "redirect", so we enforce a POLICY instead of guessing by name: an injected
+      # connection may carry ONLY adapter handlers. The default {build_client}
+      # connection (adapter only) and a test's mock adapter qualify; ANY request/
+      # response middleware — which could follow redirects under any name, or
+      # otherwise rewrite the request — is refused rather than trusted.
+      #
+      # @param client [Faraday::Connection]
+      # @raise [OauthError] +validation+ when non-adapter middleware is present
+      def self.ensure_redirects_suppressed!(client)
+        return unless client.respond_to?(:builder)
+
+        builder = client.builder
+        handlers = Array(builder.handlers)
+        # Faraday keeps the TERMINAL adapter handler OUTSIDE builder.handlers, so
+        # a redirect-follower smuggled into the adapter slot (+conn.adapter Follower+,
+        # not validated to be a Faraday::Adapter subclass) would evade a
+        # handlers-only scan and run as the terminal app. Fold the adapter into
+        # the same policy check: a genuine adapter (<= Faraday::Adapter) passes;
+        # any non-adapter class in that slot is refused.
+        handlers += [ builder.adapter ] if builder.respond_to?(:adapter)
+        offending = handlers.compact.find do |h|
+          h.respond_to?(:klass) && h.klass.is_a?(Class) && !(h.klass <= Faraday::Adapter)
+        end
+        return unless offending
+
+        raise OauthError.new(
+          "validation",
+          "Injected OAuth discovery client must carry only an adapter (no middleware); " \
+          "found #{offending.klass.name}. Redirects are suppressed for SSRF safety, so a " \
+          "connection whose middleware stack cannot be verified redirect-free is refused"
+        )
+      end
+
+      # Fetches +url+ and returns the parsed JSON object (a Hash).
+      #
+      # The request timeout is applied per-request (not only on the connection)
+      # so a bounded read is enforced even when the caller INJECTS its own
+      # connection: an injected client's adapter default would otherwise leave the
+      # requested +timeout+ unenforced. This mirrors the device flow's +post_form+.
+      #
+      # @param http_client [Faraday::Connection] the SSRF-hardened connection
+      # @param url [String] fully-qualified well-known URL to fetch
+      # @param timeout [Integer] per-request timeout in seconds
+      # @param max_body_bytes [Integer] bounded read cap in bytes
+      # @return [Hash] the parsed JSON document
+      # @raise [OauthError] +api_error+ on non-2xx, oversized body, non-object
+      #   JSON, or parse failure; +network+ on transport failure
+      def self.fetch_json(http_client, url, timeout:, max_body_bytes: DEFAULT_MAX_BODY_BYTES)
+        # Wall-clock deadline over the WHOLE read: req.options.timeout below bounds
+        # only each socket read and resets on every chunk, so a slow-drip peer could
+        # otherwise hang the fetch indefinitely while staying under max_body_bytes.
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        chunks, on_data = bounded_reader(max_body_bytes, deadline: deadline)
+
+        response = http_client.get(url) do |req|
+          req.headers["Accept"] = "application/json"
+          # Bounded streaming read: abort the moment the cap is exceeded so an
+          # oversized body is never fully buffered.
+          req.options.on_data = on_data
+          # Apply the request timeout on every request — even an injected client —
+          # so a stalled socket can't hang discovery under the adapter default.
+          req.options.timeout = timeout
+          req.options.open_timeout = timeout
+        end
+
+        body = chunks.join.force_encoding(Encoding::UTF_8)
+
+        unless (200..299).cover?(response.status)
+          raise OauthError.new(
+            "api_error",
+            "OAuth discovery failed with status #{response.status}: #{Basecamp::Security.truncate(body)}",
+            http_status: response.status
+          )
+        end
+
+        data = JSON.parse(body)
+        raise OauthError.new("api_error", "OAuth discovery response is not a JSON object") unless data.is_a?(Hash)
+
+        data
+      rescue BodyTooLarge
+        raise OauthError.new("api_error", "OAuth discovery response exceeds size cap")
+      rescue ReadDeadlineExceeded
+        raise OauthError.new("network", "OAuth discovery timed out", retryable: true)
+      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 OAuth discovery response: #{e.message}")
+      end
+    end
+  end
+end

data/lib/basecamp/oauth/protected_resource_metadata.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Oauth
+    # RFC 9728 protected-resource metadata (hop 1 of resource-first discovery).
+    #
+    # +authorization_servers+ preserves "key absent" and "present but empty
+    # <tt>[]</tt>" distinctly: BC5 omits the key while dark, per RFC 9728 §3.2.
+    # Both select Launchpad, but the distinction is meaningful to callers
+    # inspecting metadata directly (absent => +nil+, empty => +[]+).
+    #
+    # @attr resource [String] The resource identifier; equals the requested
+    #   resource origin by code-point.
+    # @attr authorization_servers [Array<String>, nil] Advertised authorization
+    #   servers; +nil+ when the key is absent, +[]+ when present but empty.
+    ProtectedResourceMetadata = Data.define(:resource, :authorization_servers) do
+      def initialize(resource:, authorization_servers: nil)
+        super
+      end
+    end
+  end
+end

data/lib/basecamp/oauth/resource.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Oauth
+    # Fetches RFC 9728 protected-resource metadata (hop 1 of resource-first
+    # discovery) and binds the returned +resource+ to the requested origin.
+    class Resource
+      # @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), reintroducing an SSRF/OOM risk.
+        @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 protected-resource metadata from
+      # <tt>{resource_origin}/.well-known/oauth-protected-resource</tt>.
+      # +resource+ is required and must equal the requested origin by code-point;
+      # +authorization_servers+ is preserved distinctly as absent (+nil+) vs
+      # present-empty (+[]+).
+      #
+      # @param resource_origin [String] the API/resource host origin
+      # @return [ProtectedResourceMetadata]
+      # @raise [Basecamp::UsageError] on a malformed caller origin
+      # @raise [OauthError] +api_error+ on invalid metadata / resource mismatch
+      def discover(resource_origin)
+        origin = Basecamp::Security.require_origin_root!(resource_origin, "resource origin")
+        url = "#{origin}/.well-known/oauth-protected-resource"
+        data = Fetcher.fetch_json(@http_client, url, timeout: @timeout, max_body_bytes: @max_body_bytes)
+
+        resource = data["resource"]
+        # Type-check, don't just probe truthiness: a wrong-typed resource (number,
+        # object, array) is malformed metadata, and calling +.empty?+ on it would
+        # raise a NoMethodError rather than a clean api_error.
+        if !resource.is_a?(String) || resource.empty?
+          raise OauthError.new("api_error", "Invalid resource metadata: missing required field: resource")
+        end
+
+        # Bind the resource identifier to the requested identifier (the raw caller
+        # origin), code-point exact, NO normalization (RFC 9728 §3.3, SPEC.md §16):
+        # the well-known URL is built from the normalized +origin+, but the metadata
+        # +resource+ must be identical to what the caller supplied.
+        unless resource == resource_origin
+          raise OauthError.new(
+            "api_error",
+            "Resource identifier mismatch: metadata resource #{resource.inspect} does not equal #{resource_origin.inspect}"
+          )
+        end
+
+        ProtectedResourceMetadata.new(
+          resource: resource,
+          authorization_servers: extract_authorization_servers(data)
+        )
+      end
+
+      private
+
+        # Preserve absent (+nil+) vs present-empty (+[]+). A present value that is
+        # not an array of strings — including a JSON +null+ — is malformed metadata
+        # and is rejected (→ soft resource_discovery_failed in the orchestrator),
+        # never iterated (a bare string would otherwise be treated as a sequence of
+        # single-character issuers during selection) and never normalized to +[]+.
+        def extract_authorization_servers(data)
+          return nil unless data.key?("authorization_servers")
+
+          servers = data["authorization_servers"]
+          # A present JSON null (or any non-array-of-strings) is MALFORMED metadata,
+          # not "present but empty": it must fail hop-1 (→ soft resource_discovery_failed
+          # in the orchestrator), never be normalized to [] and read as no_as_advertised.
+          # An empty array is a valid "present but empty" value and is preserved.
+          unless servers.is_a?(Array) && servers.all?(String)
+            raise OauthError.new(
+              "api_error",
+              "Invalid resource metadata: authorization_servers must be an array of strings"
+            )
+          end
+
+          servers
+        end
+    end
+  end
+end

data/lib/basecamp/oauth.rb

@@ -46,6 +46,18 @@ module Basecamp
   module Oauth
     LAUNCHPAD_BASE_URL = "https://launchpad.37signals.com"
 
+    # Soft fallback reasons — the ONLY two outcomes under which
+    # {discover_from_resource} yields a fallback (Launchpad) rather than a
+    # selected config. Every other failure raises {DiscoverySelectionError}.
+    FALLBACK_RESOURCE_DISCOVERY_FAILED = "resource_discovery_failed"
+    FALLBACK_NO_AS_ADVERTISED = "no_as_advertised"
+
+    # Discovers RFC 8414 Authorization Server Metadata and binds +issuer+ to
+    # +base_url+ by code-point.
+    #
+    # @param base_url [String] the OAuth server's issuer origin
+    # @param timeout [Integer] request timeout in seconds
+    # @return [Config]
     def self.discover(base_url, timeout: 10)
       Discovery.new(timeout: timeout).discover(base_url)
     end
@@ -54,6 +66,56 @@ module Basecamp
       discover(LAUNCHPAD_BASE_URL, timeout: timeout)
     end
 
+    # Discovers RFC 9728 protected-resource metadata for a resource origin.
+    #
+    # @param resource_origin [String] the API/resource host origin
+    # @param timeout [Integer] request timeout in seconds
+    # @return [ProtectedResourceMetadata]
+    def self.discover_protected_resource(resource_origin, timeout: 10)
+      Resource.new(timeout: timeout).discover(resource_origin)
+    end
+
+    # Resource-first discovery orchestrator (SPEC.md §16). Composes RFC 9728
+    # (resource metadata) and RFC 8414 (AS metadata) and applies the
+    # stage-sensitive fallback state machine.
+    #
+    # Returns a {DiscoveryResult} that is either +selected+ (a bound AS config)
+    # or a soft +fallback+ whose reason is +resource_discovery_failed+ or
+    # +no_as_advertised+ ONLY. Every hard failure raises
+    # {DiscoverySelectionError} — callers MUST NOT convert a raise into a
+    # Launchpad request.
+    #
+    # @param resource_origin [String] the API/resource host origin
+    # @param expected_issuer [String, nil] explicit, authoritative issuer
+    #   selection. When provided, the advertised member equal by code-point is
+    #   selected; if none matches, +expected_issuer_unavailable+ is raised (never
+    #   a fallback). Omit to use the Basecamp-profile exclusion heuristic.
+    # @param timeout [Integer] request timeout in seconds
+    # @return [DiscoveryResult]
+    # @raise [Basecamp::UsageError] on a malformed caller +resource_origin+
+    # @raise [DiscoverySelectionError] on any hard selection/validation failure
+    def self.discover_from_resource(resource_origin, expected_issuer: nil, timeout: 10)
+      # Origin-root validation of the *caller's* input is a usage error — let it
+      # propagate as-is (not a soft fallback).
+      # Hop 1: resource metadata. Any failure here is soft (before selection).
+      # Pass the RAW resource_origin so binding is code-point-exact against the
+      # caller's identifier (SPEC.md §16); discover_protected_resource normalizes
+      # only its fetch URL. A malformed caller origin raises UsageError → re-raised.
+      resource = begin
+        discover_protected_resource(resource_origin, timeout: timeout)
+      rescue Basecamp::UsageError
+        raise
+      rescue OauthError
+        nil
+      end
+
+      if resource.nil?
+        DiscoveryResult.fallback(FALLBACK_RESOURCE_DISCOVERY_FAILED)
+      else
+        select_and_bind(resource.authorization_servers || [], expected_issuer, timeout)
+      end
+    end
+
     def self.exchange_code(
       token_endpoint:, code:, redirect_uri:, client_id:,
       client_secret: nil, code_verifier: nil,
@@ -84,5 +146,116 @@ module Basecamp
     def self.token_expired?(token, buffer_seconds = 60)
       token.expired?(buffer_seconds)
     end
+
+    # Selects an issuer from the advertised set and — once a BC5 issuer is
+    # committed — binds its AS metadata. From this point on, every failure is
+    # fatal: no Launchpad request may be issued.
+    #
+    # @return [DiscoveryResult] +selected+, or +fallback(no_as_advertised)+ when
+    #   the advertised set carries no non-Launchpad issuer.
+    def self.select_and_bind(advertised, expected_issuer, timeout)
+      selected_issuer =
+        if expected_issuer
+          select_expected(advertised, expected_issuer)
+        else
+          select_by_exclusion(advertised)
+        end
+
+      if selected_issuer.nil?
+        # Valid resource metadata omits BC5 — soft fallback (before selection).
+        DiscoveryResult.fallback(FALLBACK_NO_AS_ADVERTISED)
+      else
+        bind_issuer(selected_issuer, timeout)
+      end
+    end
+
+    # Explicit, authoritative selection: the advertised member equal by
+    # code-point, else a hard +expected_issuer_unavailable+.
+    def self.select_expected(advertised, expected_issuer)
+      match = advertised.find { |server| server == expected_issuer }
+      if match.nil?
+        raise DiscoverySelectionError.new(
+          "expected_issuer_unavailable",
+          "Expected issuer #{expected_issuer.inspect} is not advertised by the resource"
+        )
+      end
+
+      match
+    end
+
+    # Basecamp-profile heuristic: identification by exclusion. Exactly one
+    # non-Launchpad issuer selects it; two or more is a hard +ambiguous_issuers+
+    # (never guess); zero returns +nil+ (caller yields the soft fallback).
+    def self.select_by_exclusion(advertised)
+      # Dedupe by code-point: the same non-Launchpad issuer advertised twice
+      # (e.g. [BC5, BC5, Launchpad]) is ONE candidate, not an ambiguity.
+      non_launchpad = advertised.reject { |server| launchpad_issuer?(server) }.uniq
+      if non_launchpad.length >= 2
+        raise DiscoverySelectionError.new(
+          "ambiguous_issuers",
+          "Multiple non-Launchpad issuers advertised; pass expected_issuer to disambiguate: #{non_launchpad.join(", ")}"
+        )
+      end
+
+      non_launchpad.first
+    end
+
+    # BC5 is committed: validate the advertised issuer origin then fetch + bind
+    # its AS metadata. Every failure here is a hard {DiscoverySelectionError}.
+    def self.bind_issuer(selected_issuer, timeout)
+      config = begin
+        # discover_advertised validates the advertised issuer as an origin root,
+        # then fetches from the normalized origin and binds the AS metadata issuer
+        # against the RAW advertised string by code-point — so an AS whose issuer
+        # equals what the resource advertised is not rejected merely because
+        # normalization dropped a trailing slash / default port before the bind.
+        # It exposes no unvalidated-fetch entry point (the SSRF origin policy holds).
+        Discovery.new(timeout: timeout).discover_advertised(selected_issuer)
+      rescue Basecamp::UsageError => e
+        raise DiscoverySelectionError.new(
+          "invalid_issuer_origin",
+          "Advertised issuer #{selected_issuer.inspect} is not a valid origin root: #{e.message}"
+        )
+      rescue OauthError => e
+        raise as_failure_error(selected_issuer, e)
+      end
+
+      DiscoveryResult.selected(config)
+    end
+
+    # Distinguishes an issuer-binding mismatch from a generic AS fetch failure by
+    # the error's CLASS — a structured marker ({Discovery::IssuerBindingError})
+    # raised by the binding check — not by matching its message text.
+    def self.as_failure_error(issuer_origin, error)
+      case error
+      when Discovery::IssuerBindingError
+        DiscoverySelectionError.new("issuer_mismatch", error.message)
+      else
+        DiscoverySelectionError.new(
+          "as_fetch_failed",
+          "AS metadata fetch failed for committed issuer #{issuer_origin.inspect}: #{error.message}"
+        )
+      end
+    end
+
+    # True when an advertised issuer string denotes the Launchpad origin. A
+    # non-origin-root advertised value is (correctly) treated as non-Launchpad;
+    # its later origin-root validation raises +invalid_issuer_origin+. Comparison
+    # is origin-aware (scheme + normalized host + port) via {Security.same_origin?}
+    # so a case-variant host (e.g. +Launchpad.37signals.COM+) still classifies as
+    # Launchpad rather than slipping through as a BC5 issuer.
+    def self.launchpad_issuer?(issuer)
+      origin = Basecamp::Security.require_origin_root!(issuer, "issuer")
+      Basecamp::Security.same_origin?(origin, launchpad_origin)
+    rescue Basecamp::UsageError
+      false
+    end
+
+    def self.launchpad_origin
+      @launchpad_origin ||= Basecamp::Security.require_origin_root!(LAUNCHPAD_BASE_URL, "Launchpad base URL")
+    end
+
+    private_class_method :select_and_bind, :select_expected, :select_by_exclusion,
+      :bind_issuer, :as_failure_error, :launchpad_issuer?, :launchpad_origin
   end
 end