infisical-sdk 2.3.8 → 3.0.0

data/lib/infisical/errors.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Infisical
+  # Base class for all errors raised by this SDK. Rescue this to catch
+  # anything Infisical-related.
+  class Error < StandardError; end
+
+  # Raised when the Infisical API responds with a non-2xx status. Well-known
+  # statuses raise a subclass ({AuthenticationError}, {PermissionError},
+  # {NotFoundError}, {RateLimitError}, {ServerError}); rescuing this class
+  # catches them all.
+  class APIError < Error
+    # @return [Integer] HTTP status code of the failed response
+    attr_reader :status
+
+    # @return [String] full URL the failed request was sent to
+    attr_reader :url
+
+    # @return [String] uppercase HTTP method of the failed request, e.g. "GET"
+    attr_reader :http_method
+
+    # @return [String, nil] server-assigned request id, when the response carried one
+    attr_reader :request_id
+
+    # Returns the error class that best matches an HTTP status, falling back
+    # to {APIError} itself. Constants are resolved at call time, so the
+    # subclasses defined below are visible here.
+    #
+    # @param status [Integer] HTTP status code
+    # @return [Class<APIError>]
+    def self.for_status(status)
+      case status
+      when 401 then AuthenticationError
+      when 403 then PermissionError
+      when 404 then NotFoundError
+      when 429 then RateLimitError
+      when 500..599 then ServerError
+      else self
+      end
+    end
+
+    # @param message [String] human-readable error detail from the API
+    # @param status [Integer] HTTP status code
+    # @param url [String] full URL the request was sent to
+    # @param http_method [String] HTTP method of the request
+    # @param request_id [String, nil] server-assigned request id, if any
+    def initialize(message, status:, url:, http_method:, request_id: nil)
+      @status = status
+      @url = url
+      @http_method = http_method
+      @request_id = request_id
+
+      context = "[Method=#{http_method}] [URL=#{url}] [StatusCode=#{status}]"
+      context += " [RequestId=#{request_id}]" if request_id
+
+      super("#{context} #{message}")
+    end
+  end
+
+  # Raised on HTTP 401: missing, expired, or invalid credentials.
+  class AuthenticationError < APIError; end
+
+  # Raised on HTTP 403: the authenticated identity lacks permission for the
+  # requested resource or action.
+  class PermissionError < APIError; end
+
+  # Raised on HTTP 404: the secret, project, environment, or path does not
+  # exist (or is not visible to the authenticated identity).
+  class NotFoundError < APIError; end
+
+  # Raised on HTTP 429, after the client has exhausted its automatic retries.
+  class RateLimitError < APIError; end
+
+  # Raised on HTTP 5xx: the Infisical server failed to process the request.
+  class ServerError < APIError; end
+
+  # Raised when the request itself fails (network/timeout) before a
+  # response is received. Always raised from inside a `rescue` for the
+  # underlying network exception, so Ruby's built-in `Exception#cause`
+  # already carries it through; no need to track it ourselves.
+  class RequestError < Error; end
+end

data/lib/infisical/http_client.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "time"
+
+require_relative "errors"
+require_relative "version"
+
+module Infisical
+  # Thin wrapper around Net::HTTP that knows how to talk to the Infisical
+  # API: bearer token auth, JSON (de)serialization, and retrying transient
+  # failures with exponential backoff + jitter.
+  #
+  # @api private Internal plumbing; use {Client} instead.
+  class HTTPClient
+    USER_AGENT = "infisical-ruby-sdk/v#{VERSION}".freeze
+
+    DEFAULT_TIMEOUT = 10 # seconds
+    DEFAULT_MAX_RETRIES = 4
+    DEFAULT_INITIAL_DELAY = 1.0 # seconds
+    DEFAULT_BACKOFF_FACTOR = 2
+    JITTER_RATIO = 0.2 # +/- 20%
+
+    RETRYABLE_EXCEPTIONS = [
+      Errno::ECONNRESET,
+      Errno::ECONNREFUSED,
+      Errno::ETIMEDOUT,
+      Net::OpenTimeout,
+      Net::ReadTimeout,
+      SocketError,
+      IOError
+    ].freeze
+
+    def initialize(base_url:, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES,
+                   initial_delay: DEFAULT_INITIAL_DELAY, backoff_factor: DEFAULT_BACKOFF_FACTOR,
+                   sleeper: ->(seconds) { sleep(seconds) })
+      @base_url = base_url.end_with?("/") ? base_url : "#{base_url}/"
+      @timeout = timeout
+      @max_retries = max_retries
+      @initial_delay = initial_delay
+      @backoff_factor = backoff_factor
+      @sleeper = sleeper
+      @access_token = nil
+    end
+
+    attr_writer :access_token
+
+    def get(path, params: {})
+      request(:get, path, params: params)
+    end
+
+    # auth: false sends the request without the stored access token, for
+    # endpoints like login where a stale bearer token must not be attached.
+    def post(path, body: nil, params: {}, auth: true)
+      request(:post, path, body: body, params: params, auth: auth)
+    end
+
+    def patch(path, body: nil, params: {})
+      request(:patch, path, body: body, params: params)
+    end
+
+    def delete(path, body: nil, params: {})
+      request(:delete, path, body: body, params: params)
+    end
+
+    # Computes the (pre-jitter) backoff delay for a given retry attempt
+    # (0-indexed). Exposed for testing.
+    def self.backoff_delay(attempt, initial_delay: DEFAULT_INITIAL_DELAY, backoff_factor: DEFAULT_BACKOFF_FACTOR)
+      initial_delay * (backoff_factor**attempt)
+    end
+
+    private
+
+    def request(method, path, body: nil, params: {}, auth: true)
+      uri = build_uri(path, params)
+
+      attempt = 0
+      begin
+        response = perform(method, uri, body, auth)
+        handle_response(response, method: method, uri: uri)
+      rescue *RETRYABLE_EXCEPTIONS => e
+        raise RequestError, "request to #{uri} failed: #{e.message}" if attempt >= @max_retries
+
+        attempt += 1
+        wait_before_retry(attempt)
+        retry
+      rescue RetryableAPIError => e
+        raise e.api_error if attempt >= @max_retries
+
+        attempt += 1
+        wait_before_retry(attempt, override: e.retry_after)
+        retry
+      end
+    end
+
+    def build_uri(path, params)
+      uri = URI.join(@base_url, path)
+      filtered = params.compact
+      uri.query = URI.encode_www_form(filtered) unless filtered.empty?
+      uri
+    end
+
+    def perform(method, uri, body, auth)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      request = build_request(method, uri, body, auth)
+      http.request(request)
+    end
+
+    def build_request(method, uri, body, auth)
+      request_class = {
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+        patch: Net::HTTP::Patch,
+        delete: Net::HTTP::Delete
+      }.fetch(method)
+
+      request = request_class.new(uri)
+      request["Accept"] = "application/json"
+      request["User-Agent"] = USER_AGENT
+      request["Authorization"] = "Bearer #{@access_token}" if auth && @access_token
+
+      unless body.nil?
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(body)
+      end
+
+      request
+    end
+
+    def handle_response(response, method:, uri:)
+      status = response.code.to_i
+      if status == 429
+        raise RetryableAPIError.new(build_api_error(response, status, method, uri),
+                                    retry_after: parse_retry_after(response["Retry-After"]))
+      end
+      raise build_api_error(response, status, method, uri) unless (200..299).cover?(status)
+
+      parse_body(response.body)
+    end
+
+    # Retry-After is usually an integer/float number of seconds, but per
+    # RFC 9110 it may also be an HTTP-date.
+    def parse_retry_after(value)
+      return nil if value.nil? || value.empty?
+
+      begin
+        Float(value)
+      rescue ArgumentError, TypeError
+        begin
+          seconds = Time.httpdate(value) - Time.now
+          seconds.positive? ? seconds : nil
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+
+    def build_api_error(response, status, method, uri)
+      data = parse_body(response.body)
+      data = {} unless data.is_a?(Hash)
+      message = data["message"] || data["error"] || response.body
+
+      APIError.for_status(status).new(
+        message.to_s,
+        status: status,
+        url: uri.to_s,
+        http_method: method.to_s.upcase,
+        request_id: data["reqId"]
+      )
+    end
+
+    def parse_body(raw)
+      return nil if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      raw
+    end
+
+    def wait_before_retry(attempt, override: nil)
+      if override
+        @sleeper.call(override)
+        return
+      end
+
+      base = self.class.backoff_delay(attempt - 1, initial_delay: @initial_delay, backoff_factor: @backoff_factor)
+      jitter = base * JITTER_RATIO * ((rand * 2) - 1)
+      @sleeper.call(base + jitter)
+    end
+
+    # Internal-only signal so 429s share the same retry path as network
+    # errors without retrying every other 4xx/5xx status. Carries the
+    # server's Retry-After hint (if any) so the wait honors it instead of
+    # our own computed backoff.
+    class RetryableAPIError < StandardError
+      attr_reader :api_error, :retry_after
+
+      def initialize(api_error, retry_after: nil)
+        @api_error = api_error
+        @retry_after = retry_after
+        super(api_error.message)
+      end
+    end
+    private_constant :RetryableAPIError
+  end
+end

data/lib/infisical/models/machine_identity_credential.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Infisical
+  module Models
+    # Credential material issued by a machine identity login. Exposes the
+    # token's lifetime so callers can build their own refresh logic.
+    #
+    # @!attribute access_token
+    #   @return [String] bearer token used to authenticate API requests
+    # @!attribute expires_in
+    #   @return [Integer] seconds until the token expires, from issue time
+    # @!attribute access_token_max_ttl
+    #   @return [Integer] hard ceiling in seconds on the token's total
+    #     lifetime across renewals
+    # @!attribute token_type
+    #   @return [String] token scheme, e.g. "Bearer"
+    MachineIdentityCredential = Struct.new(
+      :access_token, :expires_in, :access_token_max_ttl, :token_type,
+      keyword_init: true
+    ) do
+      # Builds a credential from an API response hash (camelCase keys).
+      #
+      # @api private
+      def self.from_api(data)
+        new(
+          access_token: data["accessToken"],
+          expires_in: data["expiresIn"],
+          access_token_max_ttl: data["accessTokenMaxTTL"],
+          token_type: data["tokenType"]
+        )
+      end
+    end
+  end
+end

data/lib/infisical/models/secret.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Infisical
+  # Value objects returned by the resource clients.
+  module Models
+    # A key/value metadata entry attached to a secret.
+    #
+    # @!attribute key
+    #   @return [String] metadata key
+    # @!attribute value
+    #   @return [String] metadata value
+    SecretMetadata = Struct.new(:key, :value, keyword_init: true) do
+      # @api private
+      def self.from_api(data)
+        new(key: data["key"], value: data["value"])
+      end
+    end
+
+    # A tag attached to a secret.
+    #
+    # @!attribute id
+    #   @return [String] unique id of the tag
+    # @!attribute slug
+    #   @return [String] URL-safe identifier of the tag
+    # @!attribute name
+    #   @return [String] display name of the tag
+    # @!attribute color
+    #   @return [String, nil] display color of the tag
+    SecretTag = Struct.new(:id, :slug, :name, :color, keyword_init: true) do
+      # @api private
+      def self.from_api(data)
+        new(id: data["id"], slug: data["slug"], name: data["name"], color: data["color"])
+      end
+    end
+
+    # Value object representing a single Infisical secret.
+    #
+    # @!attribute id
+    #   @return [String] unique id of the secret
+    # @!attribute workspace
+    #   @return [String] id of the project the secret belongs to
+    # @!attribute environment
+    #   @return [String] environment slug the secret belongs to
+    # @!attribute version
+    #   @return [Integer] version number, incremented on every update
+    # @!attribute type
+    #   @return [String] "shared" or "personal"
+    # @!attribute secret_key
+    #   @return [String] the secret's name
+    # @!attribute secret_value
+    #   @return [String] the secret's value
+    # @!attribute secret_comment
+    #   @return [String, nil] comment stored with the secret
+    # @!attribute secret_path
+    #   @return [String, nil] folder path the secret lives at
+    # @!attribute metadata
+    #   @return [Array<SecretMetadata>] key/value metadata entries
+    # @!attribute tags
+    #   @return [Array<SecretTag>] tags attached to the secret
+    # @!attribute created_at
+    #   @return [String, nil] ISO 8601 creation timestamp
+    # @!attribute updated_at
+    #   @return [String, nil] ISO 8601 last-update timestamp
+    Secret = Struct.new(
+      :id, :workspace, :environment, :version, :type,
+      :secret_key, :secret_value, :secret_comment, :secret_path,
+      :metadata, :tags,
+      :created_at, :updated_at,
+      keyword_init: true
+    ) do
+      # Builds a Secret from an API response hash (camelCase keys).
+      #
+      # @api private
+      def self.from_api(data)
+        new(
+          id: data["id"],
+          workspace: data["workspace"],
+          environment: data["environment"],
+          version: data["version"],
+          type: data["type"],
+          secret_key: data["secretKey"],
+          secret_value: data["secretValue"],
+          secret_comment: data["secretComment"],
+          secret_path: data["secretPath"],
+          metadata: Array(data["secretMetadata"]).map { |entry| SecretMetadata.from_api(entry) },
+          tags: Array(data["tags"]).map { |tag| SecretTag.from_api(tag) },
+          created_at: data["createdAt"],
+          updated_at: data["updatedAt"]
+        )
+      end
+    end
+  end
+end

data/lib/infisical/secrets.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "uri"
+
+require_relative "models/secret"
+
+module Infisical
+  # CRUD operations against Infisical's v4 secrets API.
+  class Secrets
+    # @api private
+    BASE_PATH = "api/v4/secrets"
+
+    # @api private Obtain instances via {Client#secrets} instead.
+    def initialize(http_client)
+      @http_client = http_client
+    end
+
+    # Lists the secrets in a project environment, sorted by key.
+    #
+    # @param project_id [String] id of the project to read from
+    # @param environment [String] environment slug, e.g. "dev"
+    # @param secret_path [String] folder path to list from
+    # @param include_imports [Boolean] fold in secrets from imported folders;
+    #   direct secrets win over imports on key conflicts, and earlier import
+    #   blocks win over later ones
+    # @param recursive [Boolean] also list secrets from sub-folders
+    # @param skip_unique_validation [Boolean] in recursive mode, duplicate keys
+    #   across folders are collapsed to one secret per key (last occurrence
+    #   wins) unless this is true, in which case all of them are kept
+    # @param attach_to_process_env [Boolean] export each fetched secret into
+    #   the process environment (ENV), without overriding variables that are
+    #   already set
+    # @return [Array<Models::Secret>]
+    # @raise [APIError] if the API rejects the request
+    def list(project_id:, environment:, secret_path: "/", include_imports: true, recursive: false,
+             skip_unique_validation: false, attach_to_process_env: false)
+      response = @http_client.get(
+        BASE_PATH,
+        params: {
+          projectId: project_id,
+          environment: environment,
+          secretPath: secret_path,
+          includeImports: include_imports,
+          recursive: recursive
+        }
+      )
+
+      secrets = Array(response["secrets"]).map { |secret| Models::Secret.from_api(secret) }
+      secrets = ensure_unique_secrets_by_key(secrets, skip_unique_validation) if recursive
+      secrets = merge_imported_secrets(secrets, response["imports"]) if include_imports
+      secrets = secrets.sort_by(&:secret_key)
+      attach_to_env(secrets) if attach_to_process_env
+      secrets
+    end
+
+    # Fetches a single secret by name.
+    #
+    # @param secret_name [String] key of the secret to fetch
+    # @param project_id [String] id of the project to read from
+    # @param environment [String] environment slug, e.g. "dev"
+    # @param secret_path [String] folder path the secret lives at
+    # @param include_imports [Boolean] also look through imported folders when
+    #   the secret is not found at the path itself
+    # @return [Models::Secret]
+    # @raise [NotFoundError] if no such secret exists
+    def get(secret_name, project_id:, environment:, secret_path: "/", include_imports: true)
+      response = @http_client.get(
+        secret_path_for(secret_name),
+        params: {
+          projectId: project_id,
+          environment: environment,
+          secretPath: secret_path,
+          includeImports: include_imports
+        }
+      )
+
+      Models::Secret.from_api(response["secret"])
+    end
+
+    # Creates a new secret.
+    #
+    # @param secret_name [String] key of the secret to create
+    # @param secret_value [String] value of the secret
+    # @param project_id [String] id of the project to write to
+    # @param environment [String] environment slug, e.g. "dev"
+    # @param secret_path [String] folder path to create the secret at
+    # @param secret_comment [String, nil] optional comment stored with the secret
+    # @param skip_multiline_encoding [Boolean, nil] disable the API's encoding
+    #   of multi-line values; omitted from the request when nil
+    # @return [Models::Secret] the created secret
+    # @raise [APIError] if the API rejects the request, e.g. the name is taken
+    def create(secret_name, secret_value, project_id:, environment:, secret_path: "/", secret_comment: nil,
+               skip_multiline_encoding: nil)
+      response = @http_client.post(
+        secret_path_for(secret_name),
+        body: {
+          projectId: project_id,
+          environment: environment,
+          secretPath: secret_path,
+          secretValue: secret_value,
+          secretComment: secret_comment,
+          skipMultilineEncoding: skip_multiline_encoding
+        }.compact
+      )
+
+      Models::Secret.from_api(response["secret"])
+    end
+
+    # Updates a secret's value, name, or both.
+    #
+    # @param secret_name [String] key of the secret to update
+    # @param project_id [String] id of the project to write to
+    # @param environment [String] environment slug, e.g. "dev"
+    # @param secret_value [String, nil] new value, if changing it
+    # @param new_secret_name [String, nil] new key, if renaming
+    # @param secret_path [String] folder path the secret lives at
+    # @param skip_multiline_encoding [Boolean, nil] disable the API's encoding
+    #   of multi-line values; omitted from the request when nil
+    # @return [Models::Secret] the updated secret
+    # @raise [ArgumentError] if neither secret_value nor new_secret_name is given
+    # @raise [NotFoundError] if no such secret exists
+    def update(secret_name, project_id:, environment:, secret_value: nil, new_secret_name: nil, secret_path: "/",
+               skip_multiline_encoding: nil)
+      if secret_value.nil? && new_secret_name.nil?
+        raise ArgumentError, "update requires at least one of secret_value: or new_secret_name:"
+      end
+
+      response = @http_client.patch(
+        secret_path_for(secret_name),
+        body: {
+          projectId: project_id,
+          environment: environment,
+          secretPath: secret_path,
+          secretValue: secret_value,
+          newSecretName: new_secret_name,
+          skipMultilineEncoding: skip_multiline_encoding
+        }.compact
+      )
+
+      Models::Secret.from_api(response["secret"])
+    end
+
+    # Deletes a secret.
+    #
+    # @param secret_name [String] key of the secret to delete
+    # @param project_id [String] id of the project to write to
+    # @param environment [String] environment slug, e.g. "dev"
+    # @param secret_path [String] folder path the secret lives at
+    # @return [Models::Secret] the deleted secret
+    # @raise [NotFoundError] if no such secret exists
+    def delete(secret_name, project_id:, environment:, secret_path: "/")
+      response = @http_client.delete(
+        secret_path_for(secret_name),
+        body: {
+          projectId: project_id,
+          environment: environment,
+          secretPath: secret_path
+        }
+      )
+
+      Models::Secret.from_api(response["secret"])
+    end
+
+    private
+
+    # In recursive mode the same key can exist at several paths; collapse to
+    # one secret per key (the last occurrence wins). With
+    # skip_unique_validation, secrets are instead kept unique per
+    # path+key, so same-named secrets at different paths all survive.
+    def ensure_unique_secrets_by_key(secrets, skip_unique_validation)
+      secrets.each_with_object({}) do |secret, by_key|
+        key = skip_unique_validation ? "#{secret.secret_path}:#{secret.secret_key}" : secret.secret_key
+        by_key[key] = secret
+      end.values
+    end
+
+    # Folds secrets from import blocks into the main list. Secrets already
+    # present win over imports, and earlier import blocks win over later
+    # ones.
+    def merge_imported_secrets(secrets, import_blocks)
+      merged = secrets.dup
+      seen = merged.to_h { |secret| [secret.secret_key, true] }
+
+      Array(import_blocks).each do |block|
+        Array(block["secrets"]).each do |data|
+          secret = Models::Secret.from_api(data)
+          next if seen[secret.secret_key]
+
+          seen[secret.secret_key] = true
+          merged << secret
+        end
+      end
+
+      merged
+    end
+
+    # Exports secrets into the process environment. A variable that already
+    # has a non-empty value is left untouched; an empty value counts as
+    # unset, matching the Go SDK.
+    def attach_to_env(secrets)
+      secrets.each do |secret|
+        ENV[secret.secret_key] = secret.secret_value if ENV[secret.secret_key].to_s.empty?
+      end
+    end
+
+    # Escapes a secret name for safe use as a single URI path segment, so
+    # names containing "/", "?", "#", or "%" can't be misread as path
+    # separators or query-string tokens.
+    def secret_path_for(secret_name)
+      "#{BASE_PATH}/#{URI::DEFAULT_PARSER.escape(secret_name.to_s, /[^A-Za-z0-9\-._~]/)}"
+    end
+  end
+end

data/lib/infisical/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Infisical
+  # Version of the infisical-sdk gem.
+  VERSION = "3.0.0"
+end

data/lib/infisical-sdk.rb

@@ -1,45 +1,5 @@
 # frozen_string_literal: true
 
-require 'json'
-require 'dry-types'
-
-require_relative 'schemas'
-require_relative 'extended_schemas/schemas'
-require_relative 'infisical_lib'
-require_relative 'infisical_error'
-require_relative 'command_runner'
-require_relative 'clients/secrets'
-require_relative 'clients/auth'
-require_relative 'clients/cryptography'
-
-module InfisicalSDK
-  class InfisicalClient
-    attr_reader :infisical, :command_runner, :secrets, :auth, :cryptography
-
-    def initialize(site_url = nil, cache_ttl = 300)
-      settings = ClientSettings.new(
-        # We preset these values or we'll get type validation errors (thanks Quicktype!)
-        access_token: nil,
-        client_secret: nil,
-        client_id: nil,
-        auth: nil,
-        ssl_certificate_path: nil,
-        user_agent: 'infisical-ruby-sdk',
-        cache_ttl: cache_ttl,
-        site_url: site_url
-      )
-
-
-      @infisical = InfisicalLib
-      @handle = @infisical.init(settings.to_dynamic.compact.to_json)
-      @command_runner = CommandRunner.new(@infisical, @handle)
-      @secrets = SecretsClient.new(@command_runner)
-      @auth = AuthClient.new(@command_runner)
-      @cryptography = CryptographyClient.new(@command_runner)
-    end
-
-    def free_mem
-      @infisical.free_mem(@handle)
-    end
-  end
-end
+# Entry point matching the gem name, so `Bundler.require` (e.g. in Rails)
+# can `require "infisical-sdk"` without an explicit `require:` override.
+require_relative "infisical"