attio-ruby 0.1.0

data/lib/attio/oauth/client.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require "uri"
+require "securerandom"
+require "base64"
+
+module Attio
+  # OAuth authentication module for Attio API
+  module OAuth
+    # OAuth client for handling the OAuth 2.0 authorization flow
+    class Client
+      # OAuth endpoints
+      OAUTH_BASE_URL = "https://app.attio.com/authorize"
+      # Token exchange endpoint
+      TOKEN_URL = "https://app.attio.com/oauth/token"
+      # Default OAuth scopes requested if none specified
+      DEFAULT_SCOPES = %w[
+        record:read
+        record:write
+        object:read
+        object:write
+        list:read
+        list:write
+        webhook:read
+        webhook:write
+        user:read
+      ].freeze
+
+      attr_reader :client_id, :client_secret, :redirect_uri
+
+      def initialize(client_id:, client_secret:, redirect_uri:)
+        @client_id = client_id
+        @client_secret = client_secret
+        @redirect_uri = redirect_uri
+        validate_config!
+      end
+
+      # Generate authorization URL for OAuth flow
+      def authorization_url(scopes: DEFAULT_SCOPES, state: nil, extras: {})
+        state ||= generate_state
+        scopes = validate_scopes(scopes)
+
+        params = {
+          client_id: client_id,
+          redirect_uri: redirect_uri,
+          response_type: "code",
+          scope: scopes.join(" "),
+          state: state
+        }.merge(extras)
+
+        uri = URI.parse(OAUTH_BASE_URL)
+        uri.query = URI.encode_www_form(params)
+
+        {
+          url: uri.to_s,
+          state: state
+        }
+      end
+
+      # Exchange authorization code for access token
+      def exchange_code_for_token(code:, state: nil)
+        raise ArgumentError, "Authorization code is required" if code.nil? || code.empty?
+
+        params = {
+          grant_type: "authorization_code",
+          code: code,
+          redirect_uri: redirect_uri,
+          client_id: client_id,
+          client_secret: client_secret
+        }
+
+        response = make_token_request(params)
+        Token.new(response.merge(client: self))
+      end
+
+      # Refresh an existing access token
+      def refresh_token(refresh_token)
+        raise ArgumentError, "Refresh token is required" if refresh_token.nil? || refresh_token.empty?
+
+        params = {
+          grant_type: "refresh_token",
+          refresh_token: refresh_token,
+          client_id: client_id,
+          client_secret: client_secret
+        }
+
+        response = make_token_request(params)
+        Token.new(response.merge(client: self))
+      end
+
+      # Revoke a token
+      def revoke_token(token)
+        token_value = token.is_a?(Token) ? token.access_token : token
+
+        params = {
+          token: token_value,
+          client_id: client_id,
+          client_secret: client_secret
+        }
+
+        # Use Faraday directly for OAuth endpoints
+        conn = create_oauth_connection
+        response = conn.post("/oauth/revoke") do |req|
+          req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+          req.body = URI.encode_www_form(params)
+        end
+
+        response.success?
+      rescue => e
+        # Log the error if debug mode is enabled
+        warn "OAuth token revocation failed: #{e.message}" if Attio.configuration.debug
+        false
+      end
+
+      # Validate token with introspection endpoint
+      def introspect_token(token)
+        token_value = token.is_a?(Token) ? token.access_token : token
+
+        params = {
+          token: token_value,
+          client_id: client_id,
+          client_secret: client_secret
+        }
+
+        # Use Faraday directly for OAuth endpoints
+        conn = create_oauth_connection
+        response = conn.post("/oauth/introspect") do |req|
+          req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+          req.body = URI.encode_www_form(params)
+        end
+
+        if response.success?
+          response.body
+        else
+          handle_oauth_error(response)
+        end
+      end
+
+      private
+
+      def validate_config!
+        raise ArgumentError, "client_id is required" if client_id.nil? || client_id.empty?
+        raise ArgumentError, "client_secret is required" if client_secret.nil? || client_secret.empty?
+        raise ArgumentError, "redirect_uri is required" if redirect_uri.nil? || redirect_uri.empty?
+
+        unless redirect_uri.start_with?("http://", "https://")
+          raise ArgumentError, "redirect_uri must be a valid HTTP(S) URL"
+        end
+      end
+
+      def validate_scopes(scopes)
+        scopes = Array(scopes).map(&:to_s)
+        return DEFAULT_SCOPES if scopes.empty?
+
+        invalid_scopes = scopes - ScopeValidator::VALID_SCOPES
+        unless invalid_scopes.empty?
+          raise ArgumentError, "Invalid scopes: #{invalid_scopes.join(", ")}"
+        end
+
+        scopes
+      end
+
+      def generate_state
+        SecureRandom.urlsafe_base64(32)
+      end
+
+      def make_token_request(params)
+        conn = Faraday.new do |faraday|
+          faraday.request :url_encoded
+          faraday.response :json, parser_options: {symbolize_names: true}
+          faraday.adapter Faraday.default_adapter
+        end
+
+        response = conn.post(TOKEN_URL, params) do |req|
+          req.headers["Accept"] = "application/json"
+        end
+
+        if response.success?
+          response.body
+        else
+          handle_oauth_error(response)
+        end
+      end
+
+      def create_oauth_connection
+        Faraday.new(url: "https://app.attio.com") do |faraday|
+          faraday.response :json, parser_options: {symbolize_names: true}
+          faraday.adapter Faraday.default_adapter
+        end
+      end
+
+      def handle_oauth_error(response)
+        error_body = begin
+          response.body
+        rescue
+          {}
+        end
+        error_message = if error_body.is_a?(Hash)
+          error_body[:error_description] || error_body[:error] || "OAuth error"
+        else
+          "OAuth error"
+        end
+
+        case response.status
+        when 400
+          raise BadRequestError, error_message
+        when 401
+          raise AuthenticationError, error_message
+        when 403
+          raise ForbiddenError, error_message
+        when 404
+          raise NotFoundError, error_message
+        else
+          raise Error, "OAuth error: #{error_message} (status: #{response.status})"
+        end
+      end
+    end
+  end
+end

data/lib/attio/oauth/scope_validator.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Attio
+  module OAuth
+    # Validates and manages OAuth scopes for Attio API
+    class ScopeValidator
+      # Define all valid scopes with their descriptions
+      SCOPE_DEFINITIONS = {
+        # Record scopes
+        "record:read" => "Read access to records",
+        "record:write" => "Write access to records (includes read)",
+
+        # Object scopes
+        "object:read" => "Read access to objects and their configuration",
+        "object:write" => "Write access to objects (includes read)",
+
+        # List scopes
+        "list:read" => "Read access to lists and list entries",
+        "list:write" => "Write access to lists (includes read)",
+
+        # Webhook scopes
+        "webhook:read" => "Read access to webhooks",
+        "webhook:write" => "Write access to webhooks (includes read)",
+
+        # User scopes
+        "user:read" => "Read access to workspace members",
+
+        # Note scopes
+        "note:read" => "Read access to notes",
+        "note:write" => "Write access to notes (includes read)",
+
+        # Attribute scopes
+        "attribute:read" => "Read access to attributes",
+        "attribute:write" => "Write access to attributes (includes read)",
+
+        # Comment scopes
+        "comment:read" => "Read access to comments",
+        "comment:write" => "Write access to comments (includes read)",
+
+        # Task scopes
+        "task:read" => "Read access to tasks",
+        "task:write" => "Write access to tasks (includes read)"
+      }.freeze
+
+      # Array of all valid scope strings
+      VALID_SCOPES = SCOPE_DEFINITIONS.keys.freeze
+
+      # Scope hierarchy - write scopes include read scopes
+      SCOPE_HIERARCHY = {
+        "record:write" => ["record:read"],
+        "object:write" => ["object:read"],
+        "list:write" => ["list:read"],
+        "webhook:write" => ["webhook:read"],
+        "note:write" => ["note:read"],
+        "attribute:write" => ["attribute:read"],
+        "comment:write" => ["comment:read"],
+        "task:write" => ["task:read"]
+      }.freeze
+
+      class << self
+        # Validate that all provided scopes are valid
+        # @param scopes [Array<String>, String] Scopes to validate
+        # @return [Array<String>] Validated scopes
+        # @raise [InvalidScopeError] If any scope is invalid
+        def validate(scopes)
+          scopes = Array(scopes).map(&:to_s)
+          invalid_scopes = scopes - VALID_SCOPES
+
+          unless invalid_scopes.empty?
+            raise InvalidScopeError, "Invalid scopes: #{invalid_scopes.join(", ")}"
+          end
+
+          scopes
+        end
+
+        # Validate scopes and return true if valid
+        # @param scopes [Array<String>, String] Scopes to validate
+        # @return [true]
+        # @raise [InvalidScopeError] If any scope is invalid
+        def validate!(scopes)
+          validate(scopes)
+          true
+        end
+
+        def valid?(scope)
+          VALID_SCOPES.include?(scope.to_s)
+        end
+
+        # Get the description for a scope
+        # @param scope [String] The scope to describe
+        # @return [String, nil] Description or nil if scope not found
+        def description(scope)
+          SCOPE_DEFINITIONS[scope.to_s]
+        end
+
+        # Check if a set of scopes includes a specific permission
+        def includes?(scopes, required_scope)
+          scopes = Array(scopes).map(&:to_s)
+          required = required_scope.to_s
+
+          return true if scopes.include?(required)
+
+          # Check if any scope in the set provides the required scope
+          scopes.any? do |scope|
+            implied_scopes = SCOPE_HIERARCHY[scope] || []
+            implied_scopes.include?(required)
+          end
+        end
+
+        # Expand scopes to include all implied scopes
+        def expand(scopes)
+          scopes = Array(scopes).map(&:to_s)
+          expanded = Set.new(scopes)
+
+          scopes.each do |scope|
+            implied = SCOPE_HIERARCHY[scope] || []
+            expanded.merge(implied)
+          end
+
+          expanded.to_a.sort
+        end
+
+        # Get minimal set of scopes (remove redundant read scopes)
+        def minimize(scopes)
+          scopes = Array(scopes).map(&:to_s)
+          minimized = scopes.dup
+
+          SCOPE_HIERARCHY.each do |write_scope, read_scopes|
+            if minimized.include?(write_scope)
+              minimized -= read_scopes
+            end
+          end
+
+          minimized.sort
+        end
+
+        # Group scopes by resource type
+        def group_by_resource(scopes)
+          scopes = Array(scopes).map(&:to_s)
+          grouped = {}
+
+          scopes.each do |scope|
+            resource = scope.split(":").first
+            grouped[resource] ||= []
+            grouped[resource] << scope
+          end
+
+          grouped
+        end
+
+        # Check if scopes are sufficient for an operation
+        def sufficient_for?(scopes, resource:, operation:)
+          required_scope = "#{resource}:#{operation}"
+          includes?(scopes, required_scope)
+        end
+      end
+
+      # Raised when invalid scopes are provided
+      class InvalidScopeError < StandardError; end
+    end
+  end
+end

data/lib/attio/oauth/token.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Attio
+  module OAuth
+    # Represents an OAuth access token with refresh capabilities
+    class Token
+      attr_reader :access_token, :refresh_token, :token_type, :expires_in,
+        :expires_at, :scope, :created_at, :client
+
+      def initialize(attributes = {})
+        # Since this doesn't inherit from Resources::Base, we need to normalize
+        normalized_attrs = normalize_attributes(attributes)
+        @access_token = normalized_attrs[:access_token]
+        @refresh_token = normalized_attrs[:refresh_token]
+        @token_type = normalized_attrs[:token_type] || "Bearer"
+        @expires_in = normalized_attrs[:expires_in]&.to_i
+        @scope = parse_scope(normalized_attrs[:scope])
+        @created_at = normalized_attrs[:created_at] || Time.now.utc
+        @client = normalized_attrs[:client]
+
+        calculate_expiration!
+        validate!
+      end
+
+      def expired?
+        return false if @expires_at.nil?
+        Time.now.utc >= @expires_at
+      end
+
+      def expires_soon?(threshold = 300)
+        return false if @expires_at.nil?
+        Time.now.utc >= (@expires_at - threshold)
+      end
+
+      def refresh!
+        raise InvalidTokenError, "No refresh token available" unless @refresh_token
+        raise InvalidTokenError, "No OAuth client configured" unless @client
+
+        new_token = @client.refresh_token(@refresh_token)
+        update_from(new_token)
+        self
+      end
+
+      def revoke!
+        raise InvalidTokenError, "No OAuth client configured" unless @client
+
+        @client.revoke_token(self)
+        @access_token = nil
+        @refresh_token = nil
+        true
+      end
+
+      # Convert token to hash representation
+      # @return [Hash] Token attributes as a hash
+      def to_h
+        {
+          access_token: @access_token,
+          refresh_token: @refresh_token,
+          token_type: @token_type,
+          expires_in: @expires_in,
+          expires_at: @expires_at&.iso8601,
+          scope: @scope,
+          created_at: @created_at.iso8601
+        }.compact
+      end
+
+      # Convert token to JSON string
+      # @param opts [Hash] Options to pass to JSON.generate
+      # @return [String] JSON representation of the token
+      def to_json(*opts)
+        JSON.generate(to_h, *opts)
+      end
+
+      # Human-readable representation with masked token
+      # @return [String] Inspection string with partially masked token
+      def inspect
+        scope_str = @scope.is_a?(Array) ? @scope.join(" ") : @scope.to_s
+        "#<#{self.class.name}:#{object_id} " \
+          "token=#{@access_token ? "***" + @access_token[-4..] : "nil"} " \
+          "expires_at=#{@expires_at&.iso8601} " \
+          "scope=#{scope_str}>"
+      end
+
+      # Authorization header value
+      def authorization_header
+        "#{@token_type} #{@access_token}"
+      end
+
+      # Check if token has specific scope
+      def has_scope?(scope)
+        @scope.include?(scope.to_s)
+      end
+
+      # Store token securely (subclasses can override)
+      def save
+        # Default implementation does nothing
+        # Subclasses can implement secure storage
+        self
+      end
+
+      # Load token from secure storage (class method)
+      def self.load(identifier = nil)
+        # Default implementation returns nil
+        # Subclasses can implement secure retrieval
+        nil
+      end
+
+      private
+
+      def calculate_expiration!
+        @expires_at = if @expires_in
+          @created_at + @expires_in
+        end
+      end
+
+      def parse_scope(scope)
+        case scope
+        when String
+          scope.split(" ")
+        when Array
+          scope.map(&:to_s)
+        when NilClass
+          # If scope is not provided in the token response, return nil
+          # This indicates the token has all scopes that were authorized
+          nil
+        else
+          []
+        end
+      end
+
+      def validate!
+        raise InvalidTokenError, "Access token is required" if @access_token.nil? || @access_token.empty?
+        raise InvalidTokenError, "Invalid token type" unless %w[Bearer bearer].include?(@token_type)
+      end
+
+      def update_from(other_token)
+        @access_token = other_token.access_token
+        @refresh_token = other_token.refresh_token if other_token.refresh_token
+        @token_type = other_token.token_type
+        @expires_in = other_token.expires_in
+        @expires_at = other_token.expires_at
+        @scope = other_token.scope
+        @created_at = other_token.created_at
+      end
+
+      def normalize_attributes(attributes)
+        return {} unless attributes
+
+        attributes.each_with_object({}) do |(key, value), hash|
+          hash[key.to_sym] = value
+        end
+      end
+
+      # Raised when token validation fails
+      class InvalidTokenError < StandardError; end
+    end
+  end
+end