vault-kv 0.12.0

data/lib/vault/api/help.rb

@@ -0,0 +1,33 @@
+require_relative "../client"
+require_relative "../response"
+
+module Vault
+  # Help is the response from a help query.
+  class Help < Response
+    # @!attribute [r] help
+    #   The help information.
+    #   @return [String]
+    field :help
+
+    # @!attribute [r] see_also
+    #   Additional help documentation to see.
+    #   @return [String]
+    field :see_also
+  end
+
+  class Client
+    # Gets help for the given path.
+    #
+    # @example
+    #   Vault.help("secret") #=> #<Vault::Help help="..." see_also="...">
+    #
+    # @param [String] path
+    #   the path to get help for
+    #
+    # @return [Help]
+    def help(path)
+      json = self.get("/v1/#{EncodePath.encode_path(path)}", help: 1)
+      return Help.decode(json)
+    end
+  end
+end

data/lib/vault/api/kv.rb

@@ -0,0 +1,207 @@
+require_relative "secret"
+require_relative "../client"
+require_relative "../request"
+require_relative "../response"
+
+module Vault
+  class Client
+    # A proxy to the {KV} methods.
+    # @return [KV]
+    def kv(mount)
+      KV.new(self, mount)
+    end
+  end
+
+  class KV < Request
+    attr_reader :mount
+
+    def initialize(client, mount)
+      super client
+
+      @mount = mount
+    end
+
+    # List the names of secrets at the given path, if the path supports
+    # listing. If the the path does not exist, an empty array will be returned.
+    #
+    # @example
+    #   Vault.kv("secret").list("foo") #=> ["bar", "baz"]
+    #
+    # @param [String] path
+    #   the path to list
+    #
+    # @return [Array<String>]
+    def list(path = "", options = {})
+      headers = extract_headers!(options)
+      json = client.list("/v1/#{mount}/metadata/#{encode_path(path)}", {}, headers)
+      json[:data][:keys] || []
+    rescue HTTPError => e
+      return [] if e.code == 404
+      raise
+    end
+
+    # Read the secret at the given path. If the secret does not exist, +nil+
+    # will be returned. The latest version is returned by default, but you
+    # can request a specific version.
+    #
+    # @example
+    #   Vault.kv("secret").read("password") #=> #<Vault::Secret lease_id="">
+    #
+    # @param [String] path
+    #   the path to read
+    # @param [Integer] version
+    #   the version of the secret
+    #
+    # @return [Secret, nil]
+    def read(path, version = nil, options = {})
+      headers = extract_headers!(options)
+      params  = {}
+      params[:version] = version unless version.nil?
+
+      json = client.get("/v1/#{mount}/data/#{encode_path(path)}", params, headers)
+      return Secret.decode(json[:data])
+    rescue HTTPError => e
+      return nil if e.code == 404
+      raise
+    end
+
+    # Read the metadata of a secret at the given path. If the secret does not
+    # exist, nil will be returned.
+    #
+    # @example
+    #    Vault.kv("secret").read_metadata("password") => {...}
+    #
+    # @param [String] path
+    #   the path to read
+    #
+    # @return [Hash, nil]
+    def read_metadata(path)
+      client.get("/v1/#{mount}/metadata/#{encode_path(path)}")[:data]
+    rescue HTTPError => e
+      return nil if e.code == 404
+      raise
+    end
+
+    # Write the secret at the given path with the given data. Note that the
+    # data must be a {Hash}!
+    #
+    # @example
+    #   Vault.logical.write("secret/password", value: "secret") #=> #<Vault::Secret lease_id="">
+    #
+    # @param [String] path
+    #   the path to write
+    # @param [Hash] data
+    #   the data to write
+    #
+    # @return [Secret]
+    def write(path, data = {}, options = {})
+      headers = extract_headers!(options)
+      json = client.post("/v1/#{mount}/data/#{encode_path(path)}", JSON.fast_generate(:data => data), headers)
+      if json.nil?
+        return true
+      else
+        return Secret.decode(json)
+      end
+    end
+
+    # Write the metadata of a secret at the given path. Note that teh data must
+    # be a {Hash}.
+    #
+    # @example
+    #    Vault.kv("secret").write_metadata("password", max_versions => 3)
+    #
+    # @param [String] path
+    #   the path to write
+    # @param [Hash] metadata
+    #    the metadata to write
+    #
+    # @return [true]
+    def write_metadata(path, metadata = {})
+      client.post("/v1/#{mount}/metadata/#{encode_path(path)}", JSON.fast_generate(metadata))
+
+      true
+    end
+
+    # Delete the secret at the given path. If the secret does not exist, vault
+    # will still return true.
+    #
+    # @example
+    #   Vault.logical.delete("secret/password") #=> true
+    #
+    # @param [String] path
+    #   the path to delete
+    #
+    # @return [true]
+    def delete(path)
+      client.delete("/v1/#{mount}/data/#{encode_path(path)}")
+
+      true
+    end
+
+    # Mark specific versions of a secret as deleted.
+    #
+    # @example
+    #   Vault.kv("secret").delete_versions("password", [1, 2])
+    #
+    # @param [String] path
+    #   the path to remove versions from
+    # @param [Array<Integer>] versions
+    #   an array of versions to remove
+    #
+    # @return [true]
+    def delete_versions(path, versions)
+      client.post("/v1/#{mount}/delete/#{encode_path(path)}", JSON.fast_generate(versions: versions))
+
+      true
+    end
+
+    # Mark specific versions of a secret as active.
+    #
+    # @example
+    #   Vault.kv("secret").undelete_versions("password", [1, 2])
+    #
+    # @param [String] path
+    #   the path to enable versions for
+    # @param [Array<Integer>] versions
+    #   an array of versions to mark as undeleted
+    #
+    # @return [true]
+    def undelete_versions(path, versions)
+      client.post("/v1/#{mount}/undelete/#{encode_path(path)}", JSON.fast_generate(versions: versions))
+
+      true
+    end
+
+    # Completely remove a secret and its metadata.
+    #
+    # @example
+    #   Vault.kv("secret").destroy("password")
+    #
+    # @param [String] path
+    #   the path to remove
+    #
+    # @return [true]
+    def destroy(path)
+      client.delete("/v1/#{mount}/metadata/#{encode_path(path)}")
+
+      true
+    end
+
+    # Completely remove specific versions of a secret.
+    #
+    # @example
+    #   Vault.kv("secret").destroy_versions("password", [1, 2])
+    #
+    # @param [String] path
+    #   the path to remove versions from
+    # @param [Array<Integer>] versions
+    #   an array of versions to destroy
+    #
+    # @return [true]
+    def destroy_versions(path, versions)
+      client.post("/v1/#{mount}/destroy/#{encode_path(path)}", JSON.fast_generate(versions: versions))
+
+      true
+    end
+  end
+end

data/lib/vault/api/logical.rb

@@ -0,0 +1,150 @@
+require_relative "secret"
+require_relative "../client"
+require_relative "../request"
+require_relative "../response"
+
+module Vault
+  class Client
+    # A proxy to the {Logical} methods.
+    # @return [Logical]
+    def logical
+      @logical ||= Logical.new(self)
+    end
+  end
+
+  class Logical < Request
+    # List the secrets at the given path, if the path supports listing. If the
+    # the path does not exist, an exception will be raised.
+    #
+    # @example
+    #   Vault.logical.list("secret") #=> [#<Vault::Secret>, #<Vault::Secret>, ...]
+    #
+    # @param [String] path
+    #   the path to list
+    #
+    # @return [Array<String>]
+    def list(path, options = {})
+      headers = extract_headers!(options)
+      json = client.list("/v1/#{encode_path(path)}", {}, headers)
+      json[:data][:keys] || []
+    rescue HTTPError => e
+      return [] if e.code == 404
+      raise
+    end
+
+    # Read the secret at the given path. If the secret does not exist, +nil+
+    # will be returned.
+    #
+    # @example
+    #   Vault.logical.read("secret/password") #=> #<Vault::Secret lease_id="">
+    #
+    # @param [String] path
+    #   the path to read
+    #
+    # @return [Secret, nil]
+    def read(path, options = {})
+      headers = extract_headers!(options)
+      json = client.get("/v1/#{encode_path(path)}", {}, headers)
+      return Secret.decode(json)
+    rescue HTTPError => e
+      return nil if e.code == 404
+      raise
+    end
+
+    # Write the secret at the given path with the given data. Note that the
+    # data must be a {Hash}!
+    #
+    # @example
+    #   Vault.logical.write("secret/password", value: "secret") #=> #<Vault::Secret lease_id="">
+    #
+    # @param [String] path
+    #   the path to write
+    # @param [Hash] data
+    #   the data to write
+    #
+    # @return [Secret]
+    def write(path, data = {}, options = {})
+      headers = extract_headers!(options)
+      json = client.put("/v1/#{encode_path(path)}", JSON.fast_generate(data), headers)
+      if json.nil?
+        return true
+      else
+        return Secret.decode(json)
+      end
+    end
+
+    # Delete the secret at the given path. If the secret does not exist, vault
+    # will still return true.
+    #
+    # @example
+    #   Vault.logical.delete("secret/password") #=> true
+    #
+    # @param [String] path
+    #   the path to delete
+    #
+    # @return [true]
+    def delete(path)
+      client.delete("/v1/#{encode_path(path)}")
+      return true
+    end
+
+    # Unwrap the data stored against the given token. If the secret does not
+    # exist, `nil` will be returned.
+    #
+    # @example
+    #   Vault.logical.unwrap("f363dba8-25a7-08c5-430c-00b2367124e6") #=> #<Vault::Secret lease_id="">
+    #
+    # @param [String] wrapper
+    #   the token to use when unwrapping the value
+    #
+    # @return [Secret, nil]
+    def unwrap(wrapper)
+      client.with_token(wrapper) do |client|
+        json = client.get("/v1/cubbyhole/response")
+        secret = Secret.decode(json)
+
+        # If there is nothing in the cubbyhole, return early.
+        if secret.nil? || secret.data.nil? || secret.data[:response].nil?
+          return nil
+        end
+
+        # Extract the response and parse it into a new secret.
+        json = JSON.parse(secret.data[:response], symbolize_names: true)
+        secret = Secret.decode(json)
+        return secret
+      end
+    rescue HTTPError => e
+      return nil if e.code == 404
+      raise
+    end
+
+    # Unwrap a token in a wrapped response given the temporary token.
+    #
+    # @example
+    #   Vault.logical.unwrap("f363dba8-25a7-08c5-430c-00b2367124e6") #=> "0f0f40fd-06ce-4af1-61cb-cdc12796f42b"
+    #
+    # @param [String, Secret] wrapper
+    #   the token to unwrap
+    #
+    # @return [String, nil]
+    def unwrap_token(wrapper)
+      # If provided a secret, grab the token. This is really just to make the
+      # API a bit nicer.
+      if wrapper.is_a?(Secret)
+        wrapper = wrapper.wrap_info.token
+      end
+
+      # Unwrap
+      response = unwrap(wrapper)
+
+      # If nothing was there, return nil
+      if response.nil? || response.auth.nil?
+        return nil
+      end
+
+      return response.auth.client_token
+    rescue HTTPError => e
+      raise
+    end
+  end
+end

data/lib/vault/api/secret.rb

@@ -0,0 +1,168 @@
+require "time"
+
+require_relative "../response"
+
+module Vault
+  # Secret is a representation of a secret from Vault. Almost all data returned
+  # from Vault is represented as a secret.
+  class Secret < Response
+    # @!attribute [r] auth
+    #   Authentication information for this secret, if any. Most secrets will
+    #   contain this field, but it may also be `nil`. When authenticating to
+    #   Vault, the resulting Vault token will be included in this embedded
+    #   field.
+    #
+    #   @example Authenticating to Vault
+    #     secret = Vault.auth.userpass("username", "password")
+    #     secret.auth.client_token #=> "fdb29070-6379-70c9-ca3a-46152fb66de1"
+    #
+    #   @return [SecretAuth, nil]
+    field :auth, load: ->(v) { SecretAuth.decode(v) }
+
+    # @!attribute [r] data
+    #   Arbitrary data returned by the secret. The keys returned are dependent
+    #   upon the request made. For more information on the names of the keys
+    #   that may be returned, please see the Vault documentation.
+    #
+    #   @example Reading data
+    #     secret = Vault.auth.token("abcd1234")
+    #     secret.data[:id] #=> "abcd1234"
+    #     secret.data[:ttl] #=> 0
+    #
+    #   @return [Hash<Symbol, Object>]
+    field :data, freeze: true
+
+    # @!attribute [r] metadata
+    #   Read-only metadata information related to the secret.
+    #
+    #   @example Reading metadata
+    #     secret = Vault.logical(:versioned).read("secret", "foo")
+    #     secret.metadata[:created_time] #=> "2018-12-08T04:22:54.168065Z"
+    #     secret.metadata[:version]      #=> 1
+    #     secret.metadata[:destroyed]    #=> false
+    #
+    #   @return [Hash<Symbol, Object>]
+    field :metadata, freeze: true
+
+    # @!attribute [r] lease_duration
+    #   The number of seconds this lease is valid. If this number is 0 or nil,
+    #   the secret does not expire.
+    #
+    #   @example Getting lease duration
+    #     secret = Vault.logical.read("secret/foo")
+    #     secret.lease_duration #=> 2592000 # 30 days
+    #
+    #   @return [Fixnum]
+    field :lease_duration
+
+    # @!attribute [r] lease_id
+    #   Unique ID for the lease associated with this secret. The `lease_id` is a
+    #   path and UUID that uniquely represents the secret. This may be used for
+    #   renewing and revoking the secret, if permitted.
+    #
+    #   @example Getting lease ID
+    #     secret = Vault.logical.read("postgresql/creds/readonly")
+    #     secret.lease_id #=> "postgresql/readonly/fdb29070-6379-70c9-ca3a-46152fb66de1"
+    #
+    #   @return [String]
+    field :lease_id
+
+    # @!method [r] renewable?
+    #   Returns whether this lease is renewable.
+    #
+    #   @example Checking if a lease is renewable
+    #     secret = Vault.logical.read("secret/foo")
+    #     secret.renewable? #=> false
+    #
+    #   @return [Boolean]
+    field :renewable, as: :renewable?
+
+    # @!attribute [r] warnings
+    #   List of warnings returned by the Vault server. These are returned by the
+    #   Vault server and may include deprecation information, new APIs, or
+    #   request using the API differently in the future.
+    #
+    #   @example Display warnings
+    #     result = Vault.logical.read("secret/foo")
+    #     result.warnings #=> ["This path has been deprecated"]
+    #
+    #   @return [Array<String>, nil]
+    field :warnings, freeze: true
+
+    # @!attribute [r] wrap_info
+    #   Wrapped information sent with the request (only present in Vault 0.6+).
+    #   @return [WrapInfo, nil]
+    field :wrap_info, load: ->(v) { WrapInfo.decode(v) }
+  end
+
+  # SecretAuth is a struct that contains the information about auth data, if
+  # present. This is never returned alone and is usually embededded in a
+  # {Secret}.
+  class SecretAuth < Response
+    # @!attribute [r] accessor
+    #   Accessor for the token. This is like a `lease_id`, but for a token.
+    #   @return [String]
+    field :accessor
+
+    # @!attribute [r] client_token
+    #   The client token for this authentication.
+    #   @return [String]
+    field :client_token
+
+    # @!attribute [r] lease_duration
+    #   Number of seconds the token is valid.
+    #   @return [Fixnum]
+    field :lease_duration
+
+    # @!attribute [r] metadata
+    #   Arbitrary metadata from the authentication.
+    #
+    #   @example Listing metadata attached to an authentication
+    #     auth.metadata #=> { :username => "sethvargo" }
+    #
+    #   @return [Hash<Symbol, Object>, nil]
+    field :metadata, freeze: true
+
+    # @!attribute [r] policies
+    #   List of policies attached to this authentication.
+    #
+    #   @example Listing policies attached to an authentication
+    #     auth.policies #=> ["default"]
+    #
+    #   @return [Array<String>, nil]
+    field :policies, freeze: true
+
+    # @!attribute [r] renewable
+    #   Returns whether this authentication is renewable.
+    #
+    #   @example Checking if an authentication is renewable
+    #     auth.renewable? #=> false
+    #
+    #   @return [Boolean]
+    field :renewable, as: :renewable?
+  end
+
+  # WrapInfo is the information returned by a wrapped response. This is almost
+  # always embedded as part of a {Secret}.
+  class WrapInfo < Response
+    # @!attribute [r] token
+    #   Wrapped response token. This token may be used to unwrap the response.
+    #   @return [String]
+    field :token
+
+    # @!attribute [r] wrapped_accessor
+    #   Accessor for the wrapped token. This is like a `lease_id`, but for a token.
+    #   @return [String]
+    field :wrapped_accessor
+
+    # @!attribute [r] creation_time
+    #   Date & time when the wrapped token was created
+    #   @return [Time]
+    field :creation_time, load: ->(v) { Time.parse(v) }
+
+    # @!attribute [r] ttl
+    #   The TTL on the token returned in seconds.
+    #   @return [Fixnum]
+    field :ttl
+  end
+end