basecamp-sdk 0.9.0 → 0.11.0

data/lib/basecamp/oauth/device_flow_error.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Oauth
+    # A terminal RFC 8628 device-flow outcome. Carries a +reason+; the parent
+    # {OauthError} +type+ is DERIVED from that reason (SPEC.md §16) so callers can
+    # branch on either the precise +reason+ or the coarse +type+.
+    #
+    # | reason           | parent type          |
+    # |------------------|----------------------|
+    # | +:access_denied+ | +auth+               |
+    # | +:expired+       | +auth+               |
+    # | +:transport+     | +network+ (retryable)|
+    # | +:unavailable+   | +validation+         |
+    # | +:cancelled+     | +usage+              |
+    #
+    # @attr reason [Symbol] the device-flow termination reason
+    class DeviceFlowError < OauthError
+      # Maps a device-flow reason to its parent {OauthError} type.
+      REASON_TYPES = {
+        access_denied: "auth",
+        expired: "auth",
+        transport: "network",
+        unavailable: "validation",
+        cancelled: "usage"
+      }.freeze
+
+      attr_reader :reason
+
+      # @param reason [Symbol] the device-flow termination reason
+      # @param message [String] human-readable description
+      # @param http_status [Integer, nil] HTTP status code, if applicable
+      # @param hint [String, nil] helpful hint for resolving the error
+      def initialize(reason, message, http_status: nil, hint: nil)
+        super(
+          REASON_TYPES.fetch(reason, "api_error"),
+          message,
+          http_status: http_status,
+          hint: hint,
+          retryable: reason == :transport
+        )
+        @reason = reason
+      end
+    end
+  end
+end

data/lib/basecamp/oauth/discovery.rb

@@ -18,26 +18,28 @@ module Basecamp
         end
       end
 
-      # @param http_client [Faraday::Connection, nil] HTTP client (SSRF-hardened default if nil)
-      # @param timeout [Integer] request timeout in seconds (default: 10)
+      # @param http_client [Faraday::Connection, nil] injected Faraday client
+      #   (kept, verified redirect-free); nil selects the default headers-first
+      #   Net::HTTP transport ({Fetcher.stream_http})
+      # @param timeout [Numeric] request timeout in seconds (default: 10); an
+      #   invalid value falls back via {Fetcher.normalize_timeout}
       # @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
+        # Normalize before storing (nil selects the headers-first Net::HTTP
+        # transport; an injected client is kept) 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)
+        # nil selects the headers-first {Fetcher.stream_http} transport (total
+        # wall-clock bound incl. the header phase); an injected connection keeps
+        # the Faraday path, verified redirect-free above.
+        @http_client = http_client
         # 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
+        # reintroducing an SSRF/OOM risk. Shared with Resource and the device flow.
+        @max_body_bytes = Fetcher.normalize_body_cap(max_body_bytes)
       end
 
       # Discovers OAuth configuration from

data/lib/basecamp/oauth/exchange.rb

@@ -134,6 +134,10 @@ module Basecamp
         params["refresh_token"] = request.refresh_token
         params["client_id"] = request.client_id if request.client_id
         params["client_secret"] = request.client_secret if request.client_secret
+        # An empty string is truthy in Ruby but an empty resource is not a
+        # binding — treat it as unset (omit) per the send-only-when-set
+        # contract, matching Go/TS/Kotlin.
+        params["resource"] = request.resource unless request.resource.to_s.empty?
 
         params
       end
@@ -161,21 +165,56 @@ module Basecamp
 
         handle_error_response(response.status, data) unless response.success?
 
-        raise OauthError.new("api_error", "Token response missing access_token") unless data["access_token"]
+        unless data["access_token"].is_a?(String) && !data["access_token"].empty?
+          raise OauthError.new(
+            "api_error", "Token response missing or non-string access_token",
+            http_status: response.status
+          )
+        end
+
+        # resource: absent and JSON null are unset; when present it must be a
+        # non-empty string (SPEC §16) — an empty binding is not a binding.
+        resource = data["resource"]
+        unless resource.nil? || (resource.is_a?(String) && !resource.empty?)
+          raise OauthError.new(
+            "api_error",
+            "Token response resource must be a non-empty string when present",
+            http_status: response.status
+          )
+        end
+
+        # token_type: absent/JSON-null defaults to Bearer; present must be a
+        # non-empty String ("" is truthy in Ruby, so || alone would admit it) —
+        # matching the device-flow parser and SPEC §16.
+        token_type = data["token_type"]
+        unless token_type.nil? || (token_type.is_a?(String) && !token_type.empty?)
+          raise OauthError.new(
+            "api_error",
+            "Token response token_type must be a non-empty string when present",
+            http_status: response.status
+          )
+        end
 
         Token.new(
           access_token: data["access_token"],
           refresh_token: data["refresh_token"],
-          token_type: data["token_type"] || "Bearer",
+          token_type: token_type || "Bearer",
           expires_in: data["expires_in"],
-          scope: data["scope"]
+          scope: data["scope"],
+          resource: resource
         )
       rescue JSON::ParserError
+        # A token response that fails to parse may still contain credential
+        # material (a syntactically-broken body carrying an access_token) —
+        # never echo ANY of it into an error message, where it would reach
+        # logs and exception telemetry. The status is diagnosis enough.
+        # cause: nil — the parser error's message embeds the offending input,
+        # so the implicit cause chain would leak it via full_message.
         raise OauthError.new(
           "api_error",
-          "Failed to parse token response: #{Basecamp::Security.truncate(response.body)}",
+          "Failed to parse token response",
           http_status: response.status
-        )
+        ), cause: nil
       end
 
       def handle_error_response(status, data)