basecamp-sdk 0.2.1

data/lib/basecamp/oauth/errors.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Oauth
+    # OAuth-specific error class.
+    #
+    # @attr type [String] Error type ("validation", "auth", "network", "api_error")
+    # @attr http_status [Integer, nil] HTTP status code if applicable
+    # @attr hint [String, nil] Helpful hint for resolving the error
+    # @attr retryable [Boolean] Whether the request can be retried
+    class OAuthError < StandardError
+      attr_reader :type, :http_status, :hint, :retryable
+
+      # @param type [String] Error type
+      # @param message [String] Error message
+      # @param http_status [Integer, nil] HTTP status code
+      # @param hint [String, nil] Helpful hint
+      # @param retryable [Boolean] Whether retryable
+      def initialize(type, message, http_status: nil, hint: nil, retryable: false)
+        super(message)
+        @type = type
+        @http_status = http_status
+        @hint = hint
+        @retryable = retryable
+      end
+
+      def to_s
+        parts = [ "[#{type}] #{super}" ]
+        parts << "(HTTP #{http_status})" if http_status
+        parts << "Hint: #{hint}" if hint
+        parts.join(" ")
+      end
+    end
+  end
+end

data/lib/basecamp/oauth/exchange.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "uri"
+
+module Basecamp
+  # OAuth 2 helpers for Basecamp authentication.
+  module Oauth
+    # Exchanger handles OAuth 2 token exchange and refresh operations.
+    class Exchanger
+      # @param http_client [Faraday::Connection, nil] HTTP client (uses default if nil)
+      # @param timeout [Integer] Request timeout in seconds (default: 30)
+      def initialize(http_client: nil, timeout: 30)
+        @http_client = http_client || build_default_client(timeout)
+      end
+
+      # Exchanges an authorization code for access and refresh tokens.
+      #
+      # Supports both standard OAuth 2 and Basecamp's Launchpad legacy format.
+      # Use `use_legacy_format: true` for Launchpad compatibility.
+      #
+      # @param request [ExchangeRequest] Exchange request parameters
+      # @return [Token] The token response
+      # @raise [OAuthError] on validation, network, or authentication errors
+      #
+      # @example Standard OAuth 2
+      #   token = exchanger.exchange(ExchangeRequest.new(
+      #     token_endpoint: config.token_endpoint,
+      #     code: "auth_code_from_callback",
+      #     redirect_uri: "https://myapp.com/callback",
+      #     client_id: "my_client_id",
+      #     client_secret: "my_client_secret"
+      #   ))
+      #
+      # @example Launchpad legacy format
+      #   token = exchanger.exchange(ExchangeRequest.new(
+      #     token_endpoint: config.token_endpoint,
+      #     code: "auth_code",
+      #     redirect_uri: "https://myapp.com/callback",
+      #     client_id: "my_client_id",
+      #     client_secret: "my_client_secret",
+      #     use_legacy_format: true
+      #   ))
+      def exchange(request)
+        validate_exchange_request!(request)
+
+        params = build_exchange_params(request)
+        do_token_request(request.token_endpoint, params)
+      end
+
+      # Refreshes an access token using a refresh token.
+      #
+      # Supports both standard OAuth 2 and Basecamp's Launchpad legacy format.
+      # Use `use_legacy_format: true` for Launchpad compatibility.
+      #
+      # @param request [RefreshRequest] Refresh request parameters
+      # @return [Token] The new token response
+      # @raise [OAuthError] on validation, network, or authentication errors
+      #
+      # @example Standard OAuth 2
+      #   new_token = exchanger.refresh(RefreshRequest.new(
+      #     token_endpoint: config.token_endpoint,
+      #     refresh_token: old_token.refresh_token,
+      #     client_id: "my_client_id",
+      #     client_secret: "my_client_secret"
+      #   ))
+      #
+      # @example Launchpad legacy format
+      #   new_token = exchanger.refresh(RefreshRequest.new(
+      #     token_endpoint: config.token_endpoint,
+      #     refresh_token: old_token.refresh_token,
+      #     use_legacy_format: true
+      #   ))
+      def refresh(request)
+        validate_refresh_request!(request)
+
+        params = build_refresh_params(request)
+        do_token_request(request.token_endpoint, params)
+      end
+
+      private
+
+      def build_default_client(timeout)
+        Faraday.new do |conn|
+          conn.options.timeout = timeout
+          conn.options.open_timeout = timeout
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      def validate_exchange_request!(request)
+        raise OAuthError.new("validation", "Token endpoint is required") if request.token_endpoint.to_s.empty?
+        raise OAuthError.new("validation", "Authorization code is required") if request.code.to_s.empty?
+        raise OAuthError.new("validation", "Redirect URI is required") if request.redirect_uri.to_s.empty?
+        raise OAuthError.new("validation", "Client ID is required") if request.client_id.to_s.empty?
+      end
+
+      def validate_refresh_request!(request)
+        raise OAuthError.new("validation", "Token endpoint is required") if request.token_endpoint.to_s.empty?
+        raise OAuthError.new("validation", "Refresh token is required") if request.refresh_token.to_s.empty?
+      end
+
+      def build_exchange_params(request)
+        params = {}
+
+        if request.use_legacy_format
+          # Launchpad uses non-standard "type" parameter
+          params["type"] = "web_server"
+        else
+          # Standard OAuth 2
+          params["grant_type"] = "authorization_code"
+        end
+
+        params["code"] = request.code
+        params["redirect_uri"] = request.redirect_uri
+        params["client_id"] = request.client_id
+        params["client_secret"] = request.client_secret if request.client_secret
+        params["code_verifier"] = request.code_verifier if request.code_verifier
+
+        params
+      end
+
+      def build_refresh_params(request)
+        params = {}
+
+        if request.use_legacy_format
+          # Launchpad uses non-standard "type" parameter
+          params["type"] = "refresh"
+        else
+          # Standard OAuth 2
+          params["grant_type"] = "refresh_token"
+        end
+
+        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
+
+        params
+      end
+
+      def do_token_request(token_endpoint, params)
+        Basecamp::Security.require_https_unless_localhost!(token_endpoint, "token endpoint")
+
+        response = @http_client.post(token_endpoint) do |req|
+          req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+          req.headers["Accept"] = "application/json"
+          req.body = URI.encode_www_form(params)
+        end
+
+        parse_token_response(response)
+      rescue Faraday::TimeoutError
+        raise OAuthError.new("network", "Token request timed out", retryable: true)
+      rescue Faraday::Error => e
+        raise OAuthError.new("network", "Token request failed: #{e.message}", retryable: true)
+      end
+
+      def parse_token_response(response)
+        Basecamp::Security.check_body_size!(response.body, Basecamp::Security::MAX_ERROR_BODY_BYTES, "Token")
+
+        data = JSON.parse(response.body)
+
+        handle_error_response(response.status, data) unless response.success?
+
+        raise OAuthError.new("api_error", "Token response missing access_token") unless data["access_token"]
+
+        Token.new(
+          access_token: data["access_token"],
+          refresh_token: data["refresh_token"],
+          token_type: data["token_type"] || "Bearer",
+          expires_in: data["expires_in"],
+          scope: data["scope"]
+        )
+      rescue JSON::ParserError
+        raise OAuthError.new(
+          "api_error",
+          "Failed to parse token response: #{Basecamp::Security.truncate(response.body)}",
+          http_status: response.status
+        )
+      end
+
+      def handle_error_response(status, data)
+        error_msg = Basecamp::Security.truncate(data["error_description"] || data["error"] || "Token request failed")
+
+        if status == 401 || data["error"] == "invalid_grant"
+          raise OAuthError.new(
+            "auth",
+            error_msg,
+            http_status: status,
+            hint: "The authorization code or refresh token may be invalid or expired"
+          )
+        end
+
+        raise OAuthError.new("api_error", error_msg, http_status: status)
+      end
+    end
+
+    module_function
+
+    # Exchanges an authorization code for access and refresh tokens.
+    #
+    # @param token_endpoint [String] URL of the token endpoint
+    # @param code [String] The authorization code
+    # @param redirect_uri [String] The redirect URI used in the authorization request
+    # @param client_id [String] The client identifier
+    # @param client_secret [String, nil] The client secret
+    # @param code_verifier [String, nil] PKCE code verifier
+    # @param use_legacy_format [Boolean] Use Launchpad's non-standard format
+    # @param timeout [Integer] Request timeout in seconds (default: 30)
+    # @return [Token] The token response
+    #
+    # @example
+    #   token = Basecamp::Oauth.exchange_code(
+    #     token_endpoint: config.token_endpoint,
+    #     code: "auth_code",
+    #     redirect_uri: "https://myapp.com/callback",
+    #     client_id: ENV["BASECAMP_CLIENT_ID"],
+    #     client_secret: ENV["BASECAMP_CLIENT_SECRET"],
+    #     use_legacy_format: true
+    #   )
+    def exchange_code(
+      token_endpoint:,
+      code:,
+      redirect_uri:,
+      client_id:,
+      client_secret: nil,
+      code_verifier: nil,
+      use_legacy_format: false,
+      timeout: 30
+    )
+      request = ExchangeRequest.new(
+        token_endpoint: token_endpoint,
+        code: code,
+        redirect_uri: redirect_uri,
+        client_id: client_id,
+        client_secret: client_secret,
+        code_verifier: code_verifier,
+        use_legacy_format: use_legacy_format
+      )
+      Exchanger.new(timeout: timeout).exchange(request)
+    end
+
+    # Refreshes an access token using a refresh token.
+    #
+    # @param token_endpoint [String] URL of the token endpoint
+    # @param refresh_token [String] The refresh token
+    # @param client_id [String, nil] The client identifier
+    # @param client_secret [String, nil] The client secret
+    # @param use_legacy_format [Boolean] Use Launchpad's non-standard format
+    # @param timeout [Integer] Request timeout in seconds (default: 30)
+    # @return [Token] The new token response
+    #
+    # @example
+    #   new_token = Basecamp::Oauth.refresh_token(
+    #     token_endpoint: config.token_endpoint,
+    #     refresh_token: old_token.refresh_token,
+    #     use_legacy_format: true
+    #   )
+    def refresh_token(
+      token_endpoint:,
+      refresh_token:,
+      client_id: nil,
+      client_secret: nil,
+      use_legacy_format: false,
+      timeout: 30
+    )
+      request = RefreshRequest.new(
+        token_endpoint: token_endpoint,
+        refresh_token: refresh_token,
+        client_id: client_id,
+        client_secret: client_secret,
+        use_legacy_format: use_legacy_format
+      )
+      Exchanger.new(timeout: timeout).refresh(request)
+    end
+
+    # Checks if a token is expired or about to expire.
+    #
+    # @param token [Token] The token to check
+    # @param buffer_seconds [Integer] Buffer time before actual expiration (default: 60)
+    # @return [Boolean] true if expired or will expire within buffer time
+    #
+    # @example
+    #   if Basecamp::Oauth.token_expired?(token)
+    #     token = Basecamp::Oauth.refresh_token(...)
+    #   end
+    def token_expired?(token, buffer_seconds = 60)
+      token.expired?(buffer_seconds)
+    end
+  end
+end

data/lib/basecamp/oauth/pkce.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "digest"
+require "base64"
+
+module Basecamp
+  module Oauth
+    # PKCE (Proof Key for Code Exchange) utilities for OAuth 2.0.
+    #
+    # Provides cryptographically secure code verifier and challenge generation
+    # to protect against authorization code interception attacks.
+    module Pkce
+      # Generates a cryptographically secure PKCE code verifier and challenge.
+      #
+      # The verifier is 43 characters (32 random bytes, base64url-encoded).
+      # The challenge is the base64url-encoded SHA256 hash of the verifier.
+      #
+      # Use code_challenge_method=S256 with the challenge in the authorization request.
+      #
+      # @return [Hash] containing :verifier and :challenge keys
+      #
+      # @example
+      #   pkce = Basecamp::Oauth::Pkce.generate
+      #
+      #   # In authorization request:
+      #   auth_url = "#{auth_endpoint}?code_challenge=#{pkce[:challenge]}&code_challenge_method=S256"
+      #
+      #   # Later, in token exchange:
+      #   token = exchange_code(code: code, code_verifier: pkce[:verifier])
+      #
+      def self.generate
+        # Generate 32 random bytes, base64url-encoded without padding
+        # Note: Use Base64.urlsafe_encode64 directly for consistent behavior across Ruby versions
+        verifier = Base64.urlsafe_encode64(SecureRandom.random_bytes(32), padding: false)
+
+        # Compute SHA256 hash and base64url-encode without padding
+        hash = Digest::SHA256.digest(verifier)
+        challenge = Base64.urlsafe_encode64(hash, padding: false)
+
+        { verifier: verifier, challenge: challenge }
+      end
+
+      # Generates a cryptographically secure OAuth state parameter.
+      #
+      # The state is 22 characters (16 random bytes, base64url-encoded).
+      # Use this to prevent CSRF attacks on the OAuth flow.
+      #
+      # @return [String] the state parameter
+      #
+      # @example
+      #   state = Basecamp::Oauth::Pkce.generate_state
+      #
+      #   # Store state in session before redirect:
+      #   session[:oauth_state] = state
+      #
+      #   # In callback handler:
+      #   if params[:state] != session[:oauth_state]
+      #     raise "State mismatch - possible CSRF attack"
+      #   end
+      #
+      def self.generate_state
+        # Note: Use Base64.urlsafe_encode64 directly for consistent behavior across Ruby versions
+        Base64.urlsafe_encode64(SecureRandom.random_bytes(16), padding: false)
+      end
+    end
+  end
+end

data/lib/basecamp/oauth/types.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Oauth
+    # OAuth 2 server configuration from discovery endpoint.
+    #
+    # @attr issuer [String] The authorization server's issuer identifier
+    # @attr authorization_endpoint [String] URL of the authorization endpoint
+    # @attr token_endpoint [String] URL of the token 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
+    Config = Data.define(
+      :issuer,
+      :authorization_endpoint,
+      :token_endpoint,
+      :registration_endpoint,
+      :scopes_supported
+    ) do
+      def initialize(
+        issuer:,
+        authorization_endpoint:,
+        token_endpoint:,
+        registration_endpoint: nil,
+        scopes_supported: nil
+      )
+        super
+      end
+    end
+
+    # OAuth 2 access token response.
+    #
+    # @attr access_token [String] The access token string
+    # @attr token_type [String] Token type (usually "Bearer")
+    # @attr refresh_token [String, nil] The refresh token string
+    # @attr expires_in [Integer, nil] Lifetime of the access token in seconds
+    # @attr expires_at [Time, nil] Calculated expiration time
+    # @attr scope [String, nil] OAuth scope granted
+    Token = Data.define(
+      :access_token,
+      :token_type,
+      :refresh_token,
+      :expires_in,
+      :expires_at,
+      :scope
+    ) do
+      def initialize(
+        access_token:,
+        token_type: "Bearer",
+        refresh_token: nil,
+        expires_in: nil,
+        expires_at: nil,
+        scope: nil
+      )
+        # Calculate expires_at from expires_in if not provided
+        calculated_expires_at = expires_at || (expires_in ? Time.now + expires_in : nil)
+        super(
+          access_token: access_token,
+          token_type: token_type,
+          refresh_token: refresh_token,
+          expires_in: expires_in,
+          expires_at: calculated_expires_at,
+          scope: scope
+        )
+      end
+
+      # Checks if the token is expired or about to expire.
+      #
+      # @param buffer_seconds [Integer] Buffer time before actual expiration (default: 60)
+      # @return [Boolean] true if expired or will expire within buffer time
+      def expired?(buffer_seconds = 60)
+        return false unless expires_at
+
+        Time.now + buffer_seconds >= expires_at
+      end
+    end
+
+    # Parameters for exchanging an authorization code for tokens.
+    #
+    # @attr token_endpoint [String] URL of the token endpoint
+    # @attr code [String] The authorization code received from the authorization server
+    # @attr redirect_uri [String] The redirect URI used in the authorization request
+    # @attr client_id [String] The client identifier
+    # @attr client_secret [String, nil] The client secret (optional for public clients)
+    # @attr code_verifier [String, nil] PKCE code verifier (optional)
+    # @attr use_legacy_format [Boolean] Use Launchpad's non-standard token format
+    ExchangeRequest = Data.define(
+      :token_endpoint,
+      :code,
+      :redirect_uri,
+      :client_id,
+      :client_secret,
+      :code_verifier,
+      :use_legacy_format
+    ) do
+      def initialize(
+        token_endpoint:,
+        code:,
+        redirect_uri:,
+        client_id:,
+        client_secret: nil,
+        code_verifier: nil,
+        use_legacy_format: false
+      )
+        super
+      end
+    end
+
+    # Parameters for refreshing an access token.
+    #
+    # @attr token_endpoint [String] URL of the token endpoint
+    # @attr refresh_token [String] The refresh token
+    # @attr client_id [String, nil] The client identifier (optional)
+    # @attr client_secret [String, nil] The client secret (optional)
+    # @attr use_legacy_format [Boolean] Use Launchpad's non-standard token format
+    RefreshRequest = Data.define(
+      :token_endpoint,
+      :refresh_token,
+      :client_id,
+      :client_secret,
+      :use_legacy_format
+    ) do
+      def initialize(
+        token_endpoint:,
+        refresh_token:,
+        client_id: nil,
+        client_secret: nil,
+        use_legacy_format: false
+      )
+        super
+      end
+    end
+  end
+end

data/lib/basecamp/oauth.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "oauth/errors"
+require_relative "oauth/types"
+require_relative "oauth/discovery"
+require_relative "oauth/exchange"
+
+module Basecamp
+  # OAuth 2 module for Basecamp SDK.
+  #
+  # Provides OAuth discovery, token exchange, and token refresh functionality.
+  # Supports both standard OAuth 2 and Basecamp's Launchpad legacy format.
+  #
+  # @example Complete OAuth flow
+  #   # 1. Discover OAuth configuration
+  #   config = Basecamp::Oauth.discover_launchpad
+  #
+  #   # 2. Build authorization URL (redirect user here)
+  #   auth_url = "#{config.authorization_endpoint}?" + URI.encode_www_form(
+  #     type: "web_server",
+  #     client_id: ENV["BASECAMP_CLIENT_ID"],
+  #     redirect_uri: "https://myapp.com/callback"
+  #   )
+  #
+  #   # 3. Exchange authorization code for tokens (in callback handler)
+  #   token = Basecamp::Oauth.exchange_code(
+  #     token_endpoint: config.token_endpoint,
+  #     code: params[:code],
+  #     redirect_uri: "https://myapp.com/callback",
+  #     client_id: ENV["BASECAMP_CLIENT_ID"],
+  #     client_secret: ENV["BASECAMP_CLIENT_SECRET"],
+  #     use_legacy_format: true  # Required for Launchpad
+  #   )
+  #
+  #   # 4. Use the token
+  #   client = Basecamp.client(
+  #     access_token: token.access_token,
+  #     account_id: "12345"
+  #   )
+  #
+  #   # 5. Refresh when needed
+  #   if token.expired?
+  #     token = Basecamp::Oauth.refresh_token(
+  #       token_endpoint: config.token_endpoint,
+  #       refresh_token: token.refresh_token,
+  #       use_legacy_format: true
+  #     )
+  #   end
+  #
+  # @see https://github.com/basecamp/api/blob/master/sections/authentication.md
+  module Oauth
+    # Re-export constants
+    # @return [String] Default Launchpad base URL
+    # LAUNCHPAD_BASE_URL is defined in discovery.rb
+  end
+end

data/lib/basecamp/oauth_token_provider.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # A token provider that supports OAuth token refresh.
+  #
+  # @example
+  #   provider = Basecamp::OauthTokenProvider.new(
+  #     access_token: "current-token",
+  #     refresh_token: "refresh-token",
+  #     client_id: "your-client-id",
+  #     client_secret: "your-client-secret"
+  #   )
+  class OauthTokenProvider
+    include TokenProvider
+
+    # Token endpoint for Basecamp OAuth
+    TOKEN_URL = "https://launchpad.37signals.com/authorization/token"
+
+    # @return [String, nil] the current refresh token
+    attr_reader :refresh_token
+
+    # @return [Time, nil] when the access token expires
+    attr_reader :expires_at
+
+    # Callback invoked when tokens are refreshed.
+    # @return [Proc, nil]
+    attr_accessor :on_refresh
+
+    # @param access_token [String] current access token
+    # @param refresh_token [String, nil] refresh token for renewal
+    # @param client_id [String] OAuth client ID
+    # @param client_secret [String] OAuth client secret
+    # @param expires_at [Time, nil] token expiration time
+    # @param on_refresh [Proc, nil] callback when tokens refresh
+    def initialize(access_token:, client_id:, client_secret:, refresh_token: nil, expires_at: nil, on_refresh: nil)
+      @access_token = access_token
+      @refresh_token = refresh_token
+      @client_id = client_id
+      @client_secret = client_secret
+      @expires_at = expires_at
+      @on_refresh = on_refresh
+      @mutex = Mutex.new
+    end
+
+    # Returns the current access token, refreshing if expired.
+    # @return [String]
+    def access_token
+      @mutex.synchronize do
+        refresh_if_needed
+        @access_token
+      end
+    end
+
+    # Refreshes the access token using the refresh token.
+    # @return [Boolean] true if refresh succeeded
+    def refresh
+      @mutex.synchronize do
+        return false unless refreshable?
+
+        perform_refresh
+      end
+    end
+
+    # @return [Boolean] true if refresh token is available
+    def refreshable?
+      @refresh_token && !@refresh_token.empty?
+    end
+
+    # @return [Boolean] true if the access token is expired
+    def expired?
+      @expires_at && Time.now >= @expires_at
+    end
+
+    private
+
+      def refresh_if_needed
+        perform_refresh if expired? && refreshable?
+      end
+
+      def perform_refresh
+        require "faraday"
+        require "json"
+        require "uri"
+
+        response = Faraday.post(TOKEN_URL) do |req|
+          req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+          req.body = URI.encode_www_form(
+            type: "refresh",
+            refresh_token: @refresh_token,
+            client_id: @client_id,
+            client_secret: @client_secret
+          )
+        end
+
+        raise AuthError.new("Token refresh failed: #{response.status}") unless response.success?
+
+        data = JSON.parse(response.body)
+        @access_token = data["access_token"]
+        @expires_at = Time.now + data["expires_in"].to_i if data["expires_in"]
+
+        @on_refresh&.call(@access_token, @refresh_token, @expires_at)
+
+        true
+      rescue Faraday::Error => e
+        raise NetworkError.new("Token refresh network error", cause: e)
+      end
+  end
+end