txt: ## dist_zef-PowellDean-WebService-HashiCorp-Vault.md
  [![Actions Status](https://github.com/PowellDean/WebService-HashiCorp-Vault/actions/workflows/test.yml/badge.svg)](https://github.com/PowellDean/WebService-HashiCorp-Vault/actions)
  
  # NAME
  
  WebService::HashiCorp::Vault - An API for managing secrets with Vault
  
  # SYNOPSIS
  
  ```
  use WebService::HashiCorp::Vault;
  
  ```
  
  # DESCRIPTION
  
  WebService::HashiCorp::Vault is a module written in pure Raku for managing secrets with Vault by [HashiCorp](https://hashicorp.com). For more information on what Vault is and how to use it, visit the official [Vault](https://vaultproject.io) website.
  
  **Note**: This is a work in progress, and the supported endpoints are subject to change.
  
  # PRE-REQUISITES
  
  * HashiCorp's executable for Vault, available from their website
  * JSON::Tiny
  * Cro HTTP Client tools
  * The latest Raku compiler (this project was created with v6.d)
  
  # INSTALLATION
  
  Installation is by the standard Raku package manager, [Zef](https://raku.land/github:ugexe/zef)
  
  `zef install WebService::HashiCorp::Vault`
  
  To successfully run the test suite, you will need to have your Vault instance running and unsealed. Please set the environment variable $VAULT\_TOKEN with the value of your token prior to running the tests.
  
  Also ensure you set $VAULT\_ADDR with the address/port of your running Vault instance.
  
  # USAGE
  
  ## Connecting to a Running Vault Instance
  
  ### Using an authentication token
  
  ```
  use WebService::HashiCorp::Vault;
  my $connection = Client.new(baseURL => 'http://127.0.0.1:8200',
      token => '<token generated by your Vault server>');
  
  ```
  
  You don't have to pass in $baseURL if you've set the environment variable $VAULT\_ADDR:
  
  ```
  use WebService::HashiCorp::Vault;
  my $connection = Client.new(token => '<token generated by your Vault server>');
  
  ```
  
  You don't have to pass in $token if you've set the environment variable $VAULT\_TOKEN:
  
  ```
  export VAULT_TOKEN=<token generated by your vault server>
  
  use WebService::HashiCorp::Vault;
  my $connection = Client.new();
  
  ```
  
  Note that if you do not pass the Vault URL explicitly, and the environment variable $VAULT\_ADDR is not set, the Client will use the default value <http://127.0.0.1:8200>
  
  ## Working With Secrets
  
  ### Saving Secrets
  
  ```
      # Save SecretV1 'foo' into vault 'cubbyhole'
      my $status = $connection.putSecretV1(vault => 'cubbyhole', key => 'foo',
          keyValues => %('bar', 'baz'));
  
      say $status.status;  # Will return standard HTTP return code 204 on success
  
      # Save SecretV2 'foo' into vault 'secret'
      my $status = $connection.putSecretV2(vault => 'secret', key => 'foo',
          keyValues => %('bar', 'baz'));
  
      say $status.status;  # Will return standard HTTP return code 204 on success
  
  ```
  
  ```
  
  
  ```
  
  ### Listing Secrets
  
  To list all the secret keys in the vault 'cubbyhole'
  
  ```
      say $connection.listV1Secrets(vault => 'cubbyhole');
  
  ```
  
  If successful, the output will be a list of secret keys: ['foo', 'foo1', 'snafu'].
  
  To list all the key/pair values found in a specific vault and key:
  
  ```
      # get a SecretV1 from vault 'cubbyhole'
      say $connection.getSecretV1(vault => 'cubbyhole', key => 'foo').data;
  
      # get a SecretV2 from vault 'secret'
      say $connection.getSecretV2(vault => 'secret', key => 'foo').data;
  
  ```
  
  ### Deleting Secrets
  
  ```
      # Delete SecretV1 'foo' from vault 'cubbyhole'
      say $connection.deleteV1Secret(vault => 'cubbyhole', key => 'foo');
      # Will return 204 upon successful completion (standard HTTP return code)
  
      # Delete SecretV2 from vault 'secret'
      say $connection.deleteV2Secret(vault => 'secret', key => 'foo');
      # Will return 204 upon successful completion (standard HTTP return code)
  
  ```
  
  # AUTHOR
  
  Dean Powell [PowellDean@gmail.com](mailto:PowellDean@gmail.com)
  
  # COPYRIGHT AND LICENSE
  
  Copyright 2023 Dean Powell
  
  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.
  
  ## class WebService::HashiCorp::Vault::Client
  
  A client for communicating with the Vault API
  
  ### multi method baseURL
  
  ```
  multi method baseURL() returns Mu
  
  ```
  
  Return the baseURL
  
  ### multi method baseURL
  
  ```
  multi method baseURL(
      $url
  ) returns Mu
  
  ```
  
  Set the baseURL
  
  ### multi method token
  
  ```
  multi method token() returns Mu
  
  ```
  
  Return the current session token
  
  ### multi method token
  
  ```
  multi method token(
      $aToken
  ) returns Mu
  
  ```
  
  Set the current session token
  
  ### method deleteV1Secret
  
  ```
  method deleteV1Secret(
      Str :$vault!,
      Str :$key!
  ) returns Mu
  
  ```
  
  Delete the secret with the key $key from vault $vault Will catch any generic error
  
  ### method generateRandomBytes
  
  ```
  method generateRandomBytes(
      Str :$format!,
      Int :$length!
  ) returns Mu
  
  ```
  
  Return high-quality random bytes of the given length, in the requested format. Supported formats are: =item base64 =item hex
  
  ### method getEncryptionKeyStatus
  
  ```
  method getEncryptionKeyStatus() returns Mu
  
  ```
  
  Query for encryption key status $status is a KeyStatus object with the following attributes: Int encryptions Str installTime Int leaseDuration Bool renewable Str requestId
  
  ### method getSecretV1
  
  ```
  method getSecretV1(
      Str :$vault!,
      Str :$key!
  ) returns Mu
  
  ```
  
  Return the V1 secret found in the given vault, at the given key The returned value is a SecretV1 object with the following attributes: ResponseHeader header (Hash of key/value pairs) data
  