Feature/puppet ca v1

lib/pe_client/resources/puppet.v3.rb

@@ -86,7 +86,7 @@ def facts(node_name:, facts:, environment: nil)
       #
       # @see https://help.puppet.com/core/current/Content/PuppetCore/server/http_api/http_file_content.htm
       def file_content(mount_point:, name:)
-        @client.get File.join("#{BASE_PATH}/file_content", mount_point, name), params: {"Content-Type": "application/octet-stream", Accept: "application/octet-stream"}.freeze
+        @client.get File.join("#{BASE_PATH}/file_content", mount_point, name), params: {"Content-Type": "application/octet-stream", Accept: "application/octet-stream"}
       end
 
       # This endpoint allows clients to send reports to the master.

lib/pe_client/resources/puppet.v3/file_bucket.rb

@@ -31,7 +31,7 @@ class FileBucket < Base
         BASE_PATH = "#{PuppetV3::BASE_PATH}/file_bucket_file".freeze
 
         # Common headers for file bucket requests
-        HEADERS = {"Content-Type": "application/octet-stream", Accept: "application/octet-stream"}.freeze
+        HEADERS = {"Content-Type": "application/octet-stream", Accept: "application/octet-stream"}
 
         # Retrieve the contents of a file.
         #

lib/pe_client/resources/puppet_ca.v1.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# Copyright 2025 Perforce Software Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative "base_with_port"
+
+module PEClient
+  module Resource
+    # Manages interactions with Puppet CA API endpoints.
+    # Most of the certificate authority (CA) API requires admin access.
+    #
+    # @note The Puppet CA V1 API requires certificate-based authentication.
+    #   The certificate used must have the `pp_cli_auth` extension.
+    #
+    # @see https://help.puppet.com/core/current/Content/PuppetCore/server/http_api/ca_v1_api.htm
+    class PuppetCAV1 < BaseWithPort
+      # The base path for Puppet CA API v1 endpoints.
+      BASE_PATH = "/puppet-ca/v1"
+
+      # Default Puppet CA API Port
+      PORT = 8140
+
+      # Common Puppet CA API V1 Headers
+      HEADERS = {Accept: "text/plain"}.freeze
+
+      # Returns the certificate for the specified name, which might be either a standard certname or ca.
+      #
+      # @param node_name [String]
+      #
+      # @return [String] PEM-encoded certificate
+      #
+      # @see https://help.puppet.com/core/current/Content/PuppetCore/server/http_api/http_certificate.htm
+      # @see https://help.puppet.com/core/current/Content/PuppetCore/puppet_registered_ids.htm#puppet_registered_ids
+      def certificate(node_name)
+        @client.get "#{BASE_PATH}/certificate/#{node_name}", headers: HEADERS
+      end
+
+      # Returns the "not-after" date for all certificates in the CA bundle, and the "next-update" date of all CRLs in the chain.
+      #
+      # @return [String]
+      #
+      # @see https://help.puppet.com/core/current/Content/PuppetCore/server/http_api/http_expirations.htm
+      def expirations
+        @client.get "#{BASE_PATH}/expirations", headers: HEADERS
+      end
+
+      # Allows you to revoke and delete a list of certificates with a single request.
+      #
+      # @param certnames [Array<String>]
+      #
+      # @return [String]
+      #
+      # @see https://help.puppet.com/core/current/Content/PuppetCore/server/http_api/http_certificate_clean.htm
+      def clean(certnames)
+        @client.put "#{BASE_PATH}/clean", body: {certnames:}, headers: HEADERS
+      end
+
+      # @return [PEClient::Resource::PuppetCAV1::CertificateRequest]
+      def certificate_request
+        require_relative "puppet_ca.v1/certificate_request"
+        @certificate_request ||= PuppetCAV1::CertificateRequest.new(@client)
+      end
+
+      # @return [PEClient::Resource::PuppetCAV1::CertificateStatus]
+      def certificate_status
+        require_relative "puppet_ca.v1/certificate_status"
+        @certificate_status ||= PuppetCAV1::CertificateStatus.new(@client)
+      end
+
+      # @return [PEClient::Resource::PuppetCAV1::CertificateRevocationList]
+      def certificate_revocation_list
+        require_relative "puppet_ca.v1/certificate_revocation_list"
+        @certificate_revocation_list ||= PuppetCAV1::CertificateRevocationList.new(@client)
+      end
+
+      # @return [PEClient::Resource::PuppetCAV1::BulkCertificateSign]
+      def bulk_certificate_sign
+        require_relative "puppet_ca.v1/bulk_certificate_sign"
+        @bulk_certificate_sign ||= PuppetCAV1::BulkCertificateSign.new(@client)
+      end
+    end
+  end
+end

lib/pe_client/resources/puppet_ca.v1/bulk_certificate_sign.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Copyright 2025 Perforce Software Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative "../base"
+
+module PEClient
+  module Resource
+    class PuppetCAV1
+      # Allows you to update a selection or all pending certificate requests to the signed state with a single request.
+      #
+      # @see https://help.puppet.com/core/current/Content/PuppetCore/server/http_api/http_certificate_sign.htm
+      class BulkCertificateSign < Base
+        # The base path for Puppet CA API v1 Bulk Certificate Sign endpoints.
+        BASE_PATH = "#{PuppetCAV1::BASE_PATH}/sign".freeze
+
+        # Allows you to request the signing of CSRs that match the certnames included in the payload.
+        #
+        # @param certnames [Array<String>]
+        #
+        # @return [Hash]
+        def sign(certnames)
+          @client.post BASE_PATH, body: {certnames:}
+        end
+
+        # Allows you to request the signing of all outstanding CSRs.
+        #
+        # @return [Hash]
+        def sign_all
+          @client.post "#{BASE_PATH}/all"
+        end
+      end
+    end
+  end
+end

lib/pe_client/resources/puppet_ca.v1/certificate_request.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Copyright 2025 Perforce Software Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative "../base"
+
+module PEClient
+  module Resource
+    class PuppetCAV1
+      # The `certificate_request` endpoint submits a Certificate Signing Request (CSR) to the primary server.
+      # CSRs that have been submitted can then also be retrieved.
+      # The returned CSR is always in the `.pem` format.
+      #
+      # @see https://help.puppet.com/core/current/Content/PuppetCore/server/http_api/http_certificate_request.htm
+      class CertificateRequest < Base
+        # The base path for Puppet CA API v1 Certificate Request endpoints.
+        BASE_PATH = "#{PuppetCAV1::BASE_PATH}/certificate_request".freeze
+
+        # Common headers for Puppet CA API v1 Certificate Request endpoints.
+        HEADERS = {"Content-Type": "text/plain", Accept: "text/plain"}.freeze
+
+        # Get a submitted CSR
+        #
+        # @param node_name [String]
+        #
+        # @return [String]
+        def get(node_name)
+          @client.get "#{BASE_PATH}/#{node_name}", headers: HEADERS
+        end
+
+        # Submit a CSR
+        #
+        # @param node_name [String]
+        # @param csr [String] PEM-encoded CSR
+        #
+        # @return [String]
+        def submit(node_name, csr)
+          @client.put "#{BASE_PATH}/#{node_name}", body: csr, headers: HEADERS
+        end
+
+        # Delete a submitted CSR
+        #
+        # @param node_name [String]
+        #
+        # @return [String]
+        def delete(node_name)
+          @client.delete "#{BASE_PATH}/#{node_name}", headers: HEADERS
+        end
+      end
+    end
+  end
+end

lib/pe_client/resources/puppet_ca.v1/certificate_revocation_list.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Copyright 2025 Perforce Software Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative "../base"
+
+module PEClient
+  module Resource
+    class PuppetCAV1
+      # The `certificate_revocation_list` endpoint retrieves a Certificate Revocation List (CRL) from the primary server.
+      # The returned CRL is always in the `.pem` format.
+      #
+      # @see https://help.puppet.com/core/current/Content/PuppetCore/server/http_api/http_certificate_revocation_list.htm
+      class CertificateRevocationList < Base
+        # The base path for Puppet CA API v1 Certificate Revocation List endpoints.
+        BASE_PATH = "#{PuppetCAV1::BASE_PATH}/certificate_revocation_list".freeze
+
+        # Common headers for Puppet CA API v1 Certificate Revocation List endpoints.
+        HEADERS = {"Content-Type": "text/plain", Accept: "text/plain"}.freeze
+
+        # Get the submitted CRL
+        #
+        # @return [String]
+        def get
+          @client.get "#{BASE_PATH}/ca", headers: HEADERS
+        end
+
+        # Update upstream CRLs
+        #
+        # @param crls [String] PEM-encoded CRLs
+        #
+        # @return [String]
+        def update(crls)
+          @client.put "#{BASE_PATH}/ca", body: crls, headers: HEADERS
+        end
+      end
+    end
+  end
+end

lib/pe_client/resources/puppet_ca.v1/certificate_status.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# Copyright 2025 Perforce Software Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative "../base"
+
+module PEClient
+  module Resource
+    class PuppetCAV1
+      # The `certificate_status` endpoint allows a client to read or alter the status of a certificate or pending certificate request.
+      #
+      # @see https://help.puppet.com/core/current/Content/PuppetCore/server/http_api/http_certificate_request.htm
+      class CertificateStatus < Base
+        # The base path for Puppet CA API v1 Certificate Status endpoints.
+        BASE_PATH = "#{PuppetCAV1::BASE_PATH}/certificate_status".freeze
+
+        # Retrieve information about the specified certificate.
+        #
+        # @param certname [String]
+        #
+        # @return [Hash]
+        def get(certname)
+          @client.get "#{BASE_PATH}/#{certname}"
+        end
+
+        # Retrieve information about all known certificates.
+        #
+        # @param state [String] The certificate state by which to filter search results.
+        #   Valid states are "requested", "signed", and "revoked".
+        #
+        # @return [Array<Hash>]
+        def list(state: nil)
+          @client.get "#{BASE_PATH}es/any_key", params: {state:}.compact
+        end
+
+        # Change the status of the specified certificate. The desired state is sent in the body of the PUT request as a one-item PSON hash; the two allowed complete hashes are:
+        #
+        # @param certname [String]
+        # @param desired_state [String] The desired state for the certificate.
+        #   Valid states are "signed" and "revoked".
+        # @param cert_ttl [Integer, String] To set the validity period of the signed certificate.
+        #   Can only be used when the `desired_state` is "signed".
+        #   By default, this key specifies the number of seconds, but you can specify another time unit.
+        #   See configuration for a list of Puppet's accepted time unit markers.
+        #
+        # @return [Hash]
+        #
+        # @note Revoking a certificate does not clean up other info about the host; see {#delete} for more information.
+        def update(certname, desired_state, cert_ttl: nil)
+          @client.put "#{BASE_PATH}/#{certname}", body: {desired_state:, cert_ttl:}.compact
+        end
+
+        # Cause the certificate authority to discard all SSL information regarding a host (including any certificates, certificate requests, and keys).
+        # This does not revoke the certificate if one is present; if you wish to emulate the behavior of puppet cert --clean, you must {#update} a `desired_state` of "revoked" before deleting the host’s SSL information.
+        #
+        # @param hostname [String]
+        #
+        # @return [String]
+        #
+        # @note {PuppetCAV1#clean} can be used to accomplish both revoking and cleaning in one request.
+        def delete(hostname)
+          @client.delete "#{BASE_PATH}/#{hostname}"
+        end
+      end
+    end
+  end
+end

sig/pe_client/resource/puppet_ca.v1.rbs

@@ -0,0 +1,21 @@
+module PEClient
+  module Resource
+    class PuppetCAV1
+      BASE_PATH: String
+      PORT: Integer
+      HEADERS: Hash[Symbol, String]
+
+      def certificate: (String) -> String
+      def expirations: () -> String
+      def clean: (Array[String]) -> String
+      @certificate_request: PuppetCAV1::CertificateRequest
+      def certificate_request: () -> PuppetCAV1::CertificateRequest
+      @certificate_status: PuppetCAV1::CertificateStatus
+      def certificate_status: () -> PuppetCAV1::CertificateStatus
+      @certificate_revocation_list: PuppetCAV1::CertificateRevocationList
+      def certificate_revocation_list: () -> PuppetCAV1::CertificateRevocationList
+      @bulk_certificate_sign: PuppetCAV1::BulkCertificateSign
+      def bulk_certificate_sign: () -> PuppetCAV1::BulkCertificateSign
+    end
+  end
+end

sig/pe_client/resource/puppet_ca.v1/bulk_certificate_sign.rbs

@@ -0,0 +1,12 @@
+module PEClient
+  module Resource
+    class PuppetCAV1
+      class BulkCertificateSign < Base
+        BASE_PATH: String
+
+        def sign: (Array[String]) -> Hash[String, untyped]
+        def sign_all: () -> Hash[String, untyped]
+      end
+    end
+  end
+end