feat: improve docs and fix .gitignore (#72)

Author: mbystedt

.gitignore

@@ -9,9 +9,6 @@ node_modules
 npm-debug.log
 VAULT_ROOT_TOKEN
 VAULT_UNSEAL_KEY
-/setenv-local.sh
 .DS_Store
 /intention.json
-/config/envconsul/env.hcl
-/config/config.json
 /setenv/*

README-config.md

@@ -1,18 +1,28 @@
 # Vault Sync Tool - Configuration
 
+Back: [README.md](README.md)
+
 This document is aimed at Vault Administrators looking to alter the policies and access the Vault Sync Tool configures.
 
-For users, the Vault Sync Tool maps client roles coming from OIDC to internal groups with policies that manage what the group can do. For services, it maps App Roles to policies that manage what the service can do.
+For users, the Vault Sync Tool maps client roles coming from OIDC to internal groups with policies that manage what the group can do. For services, it maps [AppRoles](https://developer.hashicorp.com/vault/docs/auth/approle) to policies that manage what the service can do.
+
+## Configuring OIDC
+
+Configuring OIDC is out of scope for the Vault Sync Tool. The tool assumes there is another process (manual or automated) that maps end users to the roles included in their token.
+
+It is extremely important that roles are correctly mapped.
 
 ## Defined Groups
 
-The 'group' here refers to a grouping of policies and not a Vault group. This allows for the syncing of a specific group of policies (like apps or system) by themselves. A group is a collection of policies aimed at solving a class of access.
+A group is a collection of policies aimed at solving a class of access. This allows for the syncing of a specific group of policies (like apps or system) by themselves.
+
+The 'group' here is not a Vault group which is a separate thing.
 
 | Group | Definition | Examples | Typical Usage |
 | --- | --- | --- | --- |
-| system | Policies that provide broad access of Vault or a specific part. | system/admin-super | Admin users |
-| apps | Policies that an individual application needs for itself. | apps/fidq/prod-kv-read	| Applications or developers of an application |
-| groups | Policies for a group of end users (humans) | groups/appdelivery-user | A group of end users (application delivery, DBA, etc) |
+| system | Policies that provide broad access to Vault. | system/admin-super | Admin users; Generic access |
+| apps | Policies required by an individual application for its own use. | apps/fidq/prod-kv-read	| Applications or developers of an application |
+| groups | Policies for a group of end users (humans) | groups/appdelivery-user | A group of end users (developers, operations, security, auditors, management) |
 
 ### Policy Naming Pattern
 
@@ -24,6 +34,8 @@ The tool uses a naming pattern that Vault admins need to be aware of. The patter
 
 This repo includes a generic configuration in [./config](./config/). If you have specific needs, you can copy this folder to another repository and make your changes there.
 
+If required, copy (or mount) your configuration to the config folder before you run the tool.
+
 ## File: config.json
 
 This is a key value object. Each of the root keys will be described in a separate section.

README-dev.md

@@ -27,13 +27,13 @@ podman build . -t vsync
 
 ### With NR Broker
 
-NR Broker's local setup will start a Vault container and run a setup script. No further setup should be required.
+Setting up NR Broker locally involves starting a Vault container and executing a setup script. This process enables the Vault Sync Tool to operate seamlessly with the local installation, requiring no additional setup.
 
 This is currently the only practical way to run the Vault Sync Tool because NR Broker is the only implemented data source for applications.
 
 ### Without NR Broker
 
-The following will start up Vault in Podman. The Vault Sync Tool defaults to localhost:8200 for the address and myroot for the token.
+The following will start up Vault in Podman. The Vault Sync Tool defaults to 'localhost:8200' for the address and 'myroot' for the token.
 
 `podman run --rm -e 'VAULT_DEV_ROOT_TOKEN_ID=myroot' -e 'VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200' --name=dev-vault -p 8200:8200 vault`
 
@@ -47,6 +47,12 @@ vault secrets enable -path=apps -version=2 kv
 vault secrets enable -path=groups -version=2 kv
 ```
 
-## Running with Broker
+## Running Vault Sync Tool
+
+### With NR Broker
 
 See: [Running Vault Sync Tool](https://bcgov-nr.github.io/nr-broker/#/development?id=running-vault-sync-tool)
+
+### Without NR Broker
+
+This is unsupported currently.

README.md

@@ -1,6 +1,6 @@
 # Vault Sync Tool
 
-The Vault Sync Tool configures HashiCorp Vault using data sources to allow applications and users to access Vault securely. It can read a static configuration or read dynamic data from the business intelligence tool, [NR Broker](https://github.com/bcgov-nr/nr-broker). It can monitor for changes in its datasources or be run on-demand.
+The Vault Sync Tool configures HashiCorp Vault by utilizing data sources, enabling secure access for applications and users. It can either read a static configuration or dynamically retrieve data from the business intelligence tool, [NR Broker](https://github.com/bcgov-nr/nr-broker). Additionally, it can monitor data source changes or be run on-demand.
 
 <!-- toc -->
 * [Vault Sync Tool](#vault-sync-tool)
@@ -10,23 +10,21 @@ The Vault Sync Tool configures HashiCorp Vault using data sources to allow appli
 
 ## Running
 
-The tool can be run from the source using Node.js or a release container image by using Podman or Docker.
+The tool can be run from the source using Node.js or a container image by using Podman or Docker.
 
 ```
 ./bin/dev health
 ```
 
 ```
-podman run --rm ghcr.io/bcgov-nr/vault-sync-app:v1.0.4 health
+podman run --rm ghcr.io/bcgov-nr/vault-sync-app:v2.0.1 health
 ```
 
-The sample command runs the health command. All the commands will probably require some arguments set up to work with your Vault.
-
-The container expects to recieve a VAULT_ADDR and VAULT_TOKEN to load
+The sample command runs the health command. All the commands will probably require some arguments set up to work with your installation of Hashicorp Vault. With no arguments set, it will try to use a local Vault installation with a static token.
 
 ## Environment Variables
 
-The tool can use environment variables in place of most command arguments. It is recommended that all confidential paramaters (tokens, etc.) be set using environment variables.
+The tool can utilize environment variables instead of most command arguments. It is recommended to set all confidential parameters (such as tokens) using environment variables. Specifically, the argument 'vault-token' should always be configured with the environment variable 'VAULT_TOKEN'.
 
 These can be found by looking in the [src/flags.ts](src/flags.ts) file.
 

config/envconsul/env.hcl

@@ -0,0 +1,20 @@
+vault {
+  renew_token = false
+  retry {
+    enabled = false
+    attempts = 12
+    backoff = "250ms"
+    max_backoff = "1m"
+  }
+}
+secret {
+  no_prefix = true
+  path = "apps/prod/vault/vsync"
+}
+exec {
+  splay = "0s"
+  env {
+    pristine = false
+  }
+  kill_timeout = "5s"
+}

package-lock.json

@@ -37,9 +37,9 @@
     ]
   },
   "dependencies": {
-    "@oclif/core": "^4.0.12",
+    "@oclif/core": "^4.0.13",
     "@oclif/plugin-help": "^6.2.6",
-    "@oclif/plugin-plugins": "^5.3.7",
+    "@oclif/plugin-plugins": "^5.3.8",
     "axios": "^1.7.2",
     "ejs": "^3.1.10",
     "inversify": "^6.0.2",
@@ -62,7 +62,7 @@
     "eslint-plugin-jest": "^28.6.0",
     "eslint-plugin-prettier": "^5.2.1",
     "jest": "^29.7.0",
-    "oclif": "^4.14.6",
+    "oclif": "^4.14.8",
     "rimraf": "^3.0.2",
     "shx": "^0.3.4",
     "ts-jest": "^29.2.3",