gitlab-customer-support-operations_gitlab 1.0.0

data/lib/support_ops_gitlab/gitlab/user_tokens.rb

@@ -0,0 +1,344 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module GitLab
+  module GitLab
+    ##
+    # Defines the class UserTokens within the module {SupportOps::GitLab}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [Boolean] active If the token is active or not
+    # @attr [String] created_at Timestamp when the token was created
+    # @attr [String] description Description of token
+    # @attr [String] expires_at Expiration date of the token in ISO format (YYYY-MM-DD)
+    # @attr [Integer] id ID of token
+    # @attr [Boolean] impersonation If the token is an impersonation token
+    # @attr [String] name Name of token
+    # @attr [Boolean] revoked If the token is revoked or not
+    # @attr [Array] scopes Array of approved scopes
+    # @attr [String] token The token itself
+    # @attr [Integer] user_id ID of user account
+    # @todo Get details on a personal access token => https://docs.gitlab.com/api/personal_access_tokens/#get-details-on-a-personal-access-token
+    # @todo List all token associations => https://docs.gitlab.com/api/personal_access_tokens/#list-all-token-associations
+    # @todo Get an impersonation token for a user => https://docs.gitlab.com/api/user_tokens/#get-an-impersonation-token-for-a-user
+    class UserTokens < SupportOps::GitLab::Base
+      # @!parse
+      #   # Creates a user token (personal access or impersonation)
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object] Instance of {SupportOps::GitLab::UserTokens}
+      #   # @note This is inherited from {SupportOps::GitLab::Base#save!}
+      #   # @see
+      #   #   https://docs.gitlab.com/api/user_tokens/#create-a-personal-access-token-for-a-user
+      #   #   GitLab API > User tokens > Create a personal access token for a user
+      #   # @see
+      #   #   https://docs.gitlab.com/api/user_tokens/#create-a-personal-access-token
+      #   #   GitLab API > User tokenss > Create a personal access token
+      #   # @see
+      #   #   https://docs.gitlab.com/api/user_tokens/#create-an-impersonation-token
+      #   #   GitLab API > User tokens > Create an impersonation token
+      #   # @example
+      #   #   require 'support_ops_gitlab'
+      #   #
+      #   #   SupportOps::GitLab::Configuration.configure do |config|
+      #   #     config.token = ENV.fetch('GL_TOKEN')
+      #   #     config.url = 'https://gitlab.com/api/v4'
+      #   #   end
+      #   #
+      #   #   user = SupportOps::GitLab::Users.get!(123456)
+      #   #   new_personal_access_token = SupportOps::GitLab::UserTokens.new
+      #   #   new_personal_access_token.name = 'Jason Test'
+      #   #   new_personal_access_token.expires_at = '2025-05-28'
+      #   #   new_personal_access_token.description = 'Jason Test Desc'
+      #   #   new_personal_access_token.scopes = ['api']
+      #   #   new_personal_access_token.user_id = user.id
+      #   #
+      #   #   new_personal_access_token.save!
+      #   #
+      #   #   pp new_personal_access_token.token
+      #   #   # => "glpat-abc123"
+      #   # @example
+      #   #   require 'support_ops_gitlab'
+      #   #
+      #   #   SupportOps::GitLab::Configuration.configure do |config|
+      #   #     config.token = ENV.fetch('GL_TOKEN')
+      #   #     config.url = 'https://gitlab.com/api/v4'
+      #   #   end
+      #   #
+      #   #   new_personal_access_token = SupportOps::GitLab::UserTokens.new
+      #   #   new_personal_access_token.name = 'Jason Test'
+      #   #   new_personal_access_token.expires_at = '2025-05-28'
+      #   #   new_personal_access_token.description = 'Jason Test Desc'
+      #   #   new_personal_access_token.scopes = ['k8s_proxy']
+      #   #
+      #   #   new_personal_access_token.save!
+      #   #
+      #   #   pp new_personal_access_token.token
+      #   #   # => "glpat-def456"
+      #   # @example
+      #   #   require 'support_ops_gitlab'
+      #   #
+      #   #   SupportOps::GitLab::Configuration.configure do |config|
+      #   #     config.token = ENV.fetch('GL_TOKEN')
+      #   #     config.url = 'https://gitlab.com/api/v4'
+      #   #   end
+      #   #
+      #   #   user = SupportOps::GitLab::Users.get!(123456)
+      #   #   new_impersonation_token = SupportOps::GitLab::UserTokens.new
+      #   #   new_impersonation_token.name = 'Jason Test'
+      #   #   new_impersonation_token.expires_at = '2025-05-28'
+      #   #   new_impersonation_token.description = 'Jason Test Desc'
+      #   #   new_impersonation_token.scopes = ['api']
+      #   #   new_impersonation_token.user_id = user.id
+      #   #   new_impersonation_token.impersonation = true
+      #   #
+      #   #   new_impersonation_token.save!
+      #   #
+      #   #   pp new_impersonation_token.token
+      #   #   # => "glpat-ghi789"
+      #   def save!; end
+      # @!parse
+      #   # Rotates a personal access token (does not work on impersonation tokens)
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object] Instance of {SupportOps::GitLab::UserTokens}
+      #   # @note This is inherited from {SupportOps::GitLab::Base#rotate!}
+      #   # @see
+      #   #   https://docs.gitlab.com/api/personal_access_tokens/#rotate-a-personal-access-token
+      #   #   GitLab API > Personal access tokens > Rotate a personal access token
+      #   # @example
+      #   #   require 'support_ops_gitlab'
+      #   #
+      #   #   SupportOps::GitLab::Configuration.configure do |config|
+      #   #     config.token = ENV.fetch('GL_TOKEN')
+      #   #     config.url = 'https://gitlab.com/api/v4'
+      #   #   end
+      #   #
+      #   #   user = SupportOps::GitLab::Users.get!(123456)
+      #   #   tokens = users.pats
+      #   #   new_token = tokens.last.rotate!
+      #   #   pp new_token.token
+      #   #   # => "glpat-def456"
+      #   def rotate!; end
+      # @!parse
+      #   # Revokes a token (personal access or impersonation)
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object] Instance of {SupportOps::GitLab::UserTokens}
+      #   # @note This is inherited from {SupportOps::GitLab::Base#revoke!}
+      #   # @see
+      #   #   https://docs.gitlab.com/api/personal_access_tokens/#revoke-a-personal-access-token
+      #   #   GitLab API > Personal access tokens > Revoke a personal access token
+      #   # @see
+      #   #   https://docs.gitlab.com/api/user_tokens/#revoke-an-impersonation-token
+      #   #   GitLab API > User tokens > Revoke an impersonation token
+      #   # @example
+      #   #   require 'support_ops_gitlab'
+      #   #
+      #   #   SupportOps::GitLab::Configuration.configure do |config|
+      #   #     config.token = ENV.fetch('GL_TOKEN')
+      #   #     config.url = 'https://gitlab.com/api/v4'
+      #   #   end
+      #   #
+      #   #   user = SupportOps::GitLab::Users.get!(123456)
+      #   #   tokens = users.pats
+      #   #   tokens.last.revoke!
+      #   def revoke!; end
+      define_attributes :active, :created_at, :description, :expires_at, :id,
+                        :impersonation, :name, :revoked, :scopes, :token,
+                        :user_id
+      readonly_attributes :active, :created_at, :id, :impersonation, :revoked,
+                          :token, :user_id
+
+      ##
+      # List all personal access tokens
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload list(key: value)
+      #   @param created_after [String optional] If defined, returns tokens
+      #     created after the specified time (ISO 8601)
+      #   @param created_before [String optional] If defined, returns tokens
+      #     created before the specified time (ISO 8601)
+      #   @param expires_after [String optional] If defined, returns tokens that
+      #     expire after the specified time (ISO 8601)
+      #   @param expires_before [String optional] If defined, returns tokens
+      #     that expire before the specified time (ISO 8601)
+      #   @param last_used_after [String optional] If defined, returns tokens
+      #     last used after the specified time (ISO 8601)
+      #   @param last_used_before [String optional] If defined, returns tokens
+      #     last used before the specified time (ISO 8601)
+      #   @param revoked [Boolean optional] If true, only returns revoked tokens
+      #   @param search [String optional] If defined, returns tokens that
+      #     include the specified value in the name
+      #   @param state [String optional] if defined, returns tokens with the
+      #     specified statel possible values: active and inactive
+      #   @param user_id [Integer optional] if defined, returns tokens owned by
+      #     the specified user
+      # @return [Array]
+      # @see
+      #   https://docs.gitlab.com/api/personal_access_tokens/#list-all-personal-access-tokens
+      #   GitLab API > Personal access tokens > List all personal access tokens
+      # @see SupportOps::GitLab::Configuration Setting up a client
+      # @example
+      #   require 'support_ops_gitlab'
+      #
+      #   SupportOps::GitLab::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.example.com/api/v4'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   pats = SupportOps::GitLab::UserTokens.list_paths(revoked: false)
+      #   pp pats.count
+      #   # => 2
+      #   pp pats.last.expires_at
+      #   # => "2025-08-15"
+      def self.list_pats(**args)
+        args[:created_after] = nil unless args[:created_after]
+        args[:created_before] = nil unless args[:created_before]
+        args[:expires_after] = nil unless args[:expires_after]
+        args[:expires_before] = nil unless args[:expires_before]
+        args[:last_used_after] = nil unless args[:last_used_after]
+        args[:last_used_before] = nil unless args[:last_used_before]
+        args[:revoked] = nil unless args[:revoked]
+        args[:search] = nil unless args[:search]
+        args[:state] = nil unless args[:state]
+        args[:user_id] = nil unless args[:user_id]
+        params = ''
+        params += "created_after=#{args[:created_after]}&" unless args[:created_after].nil?
+        params += "created_before=#{args[:created_before]}&" unless args[:created_before].nil?
+        params += "expires_after=#{args[:expires_after]}&" unless args[:expires_after].nil?
+        params += "expires_before=#{args[:expires_before]}&" unless args[:expires_before].nil?
+        params += "last_used_after=#{args[:last_used_after]}&" unless args[:last_used_after].nil?
+        params += "last_used_before=#{args[:last_used_before]}&" unless args[:last_used_before].nil?
+        params += "revoked=#{args[:revoked]}&" unless args[:revoked].nil?
+        params += "search=#{args[:search]}&" unless args[:search].nil?
+        params += "state=#{args[:state]}&" unless args[:state].nil?
+        params += "user_id=#{args[:user_id]}&" unless args[:user_id].nil?
+        tokens = []
+        page = 1
+        loop do
+          response = client.connection.get("personal_access_tokens?#{params}&page=#{page}&per_page=100")
+          body = Oj.load(response.body)
+          tokens += body.map { |p| UserTokens.new(p) }
+          break if body.count < 100
+
+          page += 1
+        end
+        tokens
+      end
+
+      ##
+      # List all impersonation tokens for a user
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload list(key: value)
+      #   @param state [String optional] if defined, returns tokens with the
+      #     specified statel possible values: active and inactive
+      #   @param user_id [Integer required] if defined, returns tokens owned by
+      #     the specified user
+      # @return [Array]
+      # @see
+      #   https://docs.gitlab.com/api/user_tokens/#list-all-impersonation-tokens-for-a-user
+      #   GitLab API > User tokens > List all impersonation tokens for a user
+      # @see SupportOps::GitLab::Configuration Setting up a client
+      # @example
+      #   require 'support_ops_gitlab'
+      #
+      #   SupportOps::GitLab::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.example.com/api/v4'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   user = Readiness::GitLab::Users.current
+      #   tokens = SupportOps::GitLab::UserTokens.list_impersonation(state: 'active', user_id: user.id)
+      #   pp tokens.count
+      #   # => 1
+      #   pp tokens.last.expires_at
+      #   # => "2025-08-15"
+      def self.list_impersonation(**args)
+        raise 'You must provide a user_id for this' unless args[:user_id]
+        args[:state] = nil unless args[:state]
+        params = ''
+        params += "state=#{args[:state]}&" unless args[:state].nil?
+        tokens = []
+        page = 1
+        loop do
+          response = client.connection.get("users/#{args[:user_id]}/impersonation_tokens?#{params}&page=#{page}&per_page=100")
+          body = Oj.load(response.body)
+          tokens += body.map { |p| UserTokens.new(p) }
+          break if body.count < 100
+
+          page += 1
+        end
+        tokens
+      end
+
+      private
+
+      ##
+      # @private
+      def create_record
+        url = if self.impersonation
+                "users/#{self.user_id}/impersonation_tokens"
+              elsif self.user_id.nil?
+                'user/personal_access_tokens'
+              else
+                "users/#{self.user_id}/personal_access_tokens"
+              end
+        response = self.client.connection.post(url, attributes_for_save.to_json)
+        body = Oj.load(response.body)
+        raise "Error creating token => #{body}" unless response.status == 201
+        body
+      end
+
+      ##
+      # @private
+      def update_record
+        raise 'You cannot update a token, you must create a new one'
+      end
+
+      ##
+      # @private
+      def delete_record
+        raise 'You cannot delete a token, you must revoke it'
+      end
+
+      ##
+      # @private
+      def rotate_record
+        raise 'You cannot rotate an impersonation token' if self.impersonation
+        data = { expires_at: self.expires_at }.to_json
+        response = self.client.connection.post("personal_access_tokens/#{self.id}/rotate", data)
+        body = Oj.load(response.body)
+        raise "Faield to rotate token #{self.id} => #{body}" unless response.status == 200
+        body.each do |key, value|
+          self.instance_variable_set("@#{key}", value) if self.respond_to?("#{key}=")
+        end
+        body
+      end
+
+      ##
+      # @private
+      def revoke_record
+        url = if self.impersonation
+                "users/#{self.user_id}/impersonation_tokens/#{self.id}"
+              else
+                "personal_access_tokens/#{self.id}"
+              end
+        response = self.client.connection.delete(url)
+        body = Oj.load(response.body)
+        raise "Error deleting token => #{self.body}" unless response.status == 204
+        self.instance_variable_set("@active", false)
+        self.instance_variable_set("@revoked", true)
+        true
+      end
+    end
+  end
+end