Merge pull request #295 from nodevault/copilot/how-to-unseal-a-vault

Add unseal example and docs for already-initialized vaults

Author: aviadhahami

README.md

@@ -86,6 +86,44 @@ vault.init({ secret_shares: 1, secret_threshold: 1 })
   .catch(console.error);
 ```
 
+### Unseal a vault that is already initialized
+
+If the vault server has been restarted or sealed, you can unseal it using
+the unseal keys from the original initialization. If the vault was initialized
+with `secret_threshold > 1`, you must call `unseal` multiple times with
+different keys until the threshold is met.
+
+```javascript
+const vault = require('node-vault')({
+  apiVersion: 'v1',
+  endpoint: 'http://127.0.0.1:8200',
+});
+
+// unseal vault server with a single key
+vault.unseal({ key: 'my-unseal-key' })
+  .then(console.log)
+  .catch(console.error);
+```
+
+When the vault requires multiple unseal keys (threshold > 1):
+
+```javascript
+vault.unseal({ key: 'first-unseal-key' })
+  .then((result) => {
+    // result.sealed will be true until enough keys are provided
+    console.log('Sealed:', result.sealed);
+    console.log('Progress:', result.progress + '/' + result.t);
+    return vault.unseal({ key: 'second-unseal-key' });
+  })
+  .then((result) => {
+    // once the threshold is met, sealed will be false
+    console.log('Sealed:', result.sealed);
+  })
+  .catch(console.error);
+```
+
+See [example/unseal.js](example/unseal.js) for a working example.
+
 ### Write, read, update and delete secrets
 
 ```javascript

example/unseal.js

@@ -0,0 +1,16 @@
+// file: example/unseal.js
+
+process.env.DEBUG = 'node-vault'; // switch on debug mode
+
+const vault = require('./../src/index')();
+
+// Unseal a vault server that is already initialized.
+// Provide one of the unseal keys from the init response.
+// If the vault was initialized with secret_threshold > 1,
+// you must call unseal multiple times with different keys
+// until the threshold is met.
+const key = process.env.UNSEAL_KEY;
+
+vault.unseal({ key })
+    .then(console.log)
+    .catch((err) => console.error(err.message));