docs: enhance Sharing Vaults With Secrets tutorial

Expand the Sharing Vaults With Secrets documentation to include detailed steps for sharing, scanning, cloning, and synchronizing vaults. Add troubleshooting guidelines and link back to prerequisites from the Discovering Users' Nodes and Managing Access Permissions section for a streamlined user experience. Include code examples for each critical operation and emphasize debugging techniques for common sharing issues.

Author: CryptoTotalWar

docs/tutorials/polykey-cli/sharing-vaults.md

@@ -1,181 +1,109 @@
-# Sharing Vaults
+# Sharing Vaults With Secrets
 
-This tutorial assumes that you are working in the `Polykey` project's directory, and you have successfully built it using `npm run build`.
+In Polykey, sharing vaults containing secrets is essential for collaborative environments. This guide will walk you through the process of securely sharing your vaults and enabling other users to access and synchronize secrets between trusted nodes.
 
-### Setting Up Nodes
-For two agents to communicate with each other we need two agents to be running. For this example we're going to run two `Polykey` nodes on the same machine and have them communicate over the loop-back device.
+## Prerequisites for Sharing Vaults
 
-First we want to start the first node. Since we are going to run two nodes on the same machine, we need to keep them separate. For this we need to override the `node-path` to a directory we want the `Polykey` node to be created in. for this example we're going to use a temp directory `tmp`.  We're also going to set a static port value for the proxy.
+Before sharing a vault, ensure that both nodes have established trust and appropriate permissions are set. For details on setting trust and access permissions, refer to the "Discovering Users' Nodes and Managing Access Permissions" section.
 
-Run the following command
+### Common Debugging Techniques for Sharing Secrets
 
-```
-node dist/bin/polykey agent start --node-path tmp/nodeA --proxy-port 55551
-```
-
-If this is the first time creating the node you should be prompted for the password twice. After that some information about the node should be printed.
+To share secrets between two nodes on different machines, both must be actively connected to the Polykey network. Here are some techniques to ensure connectivity and troubleshoot common issues:
 
-```
-✔ Enter new password … ********
-✔ Confirm new password … ********
-pid     476567
-nodeId  "vfjqk9v06k6p1tnuc4444irt0krasjmi1btmmf7ptaqg477em9390"
-clientHost      "127.0.0.1"
-clientPort      50617
-agentHost       "127.0.0.1"
-agentPort       35629
-proxyHost       "0.0.0.0"
-proxyPort       55551
-forwardHost     "127.0.0.1"
-forwardPort     38331
-recoveryCode    "drill video walnut message stone exhibit render snack comic maze deposit decline bless unit crater correct stool remain legend problem egg lecture approve normal"
-```
+- **Node Ping:** Use `polykey nodes ping <nodeID>` to check if the intended recipient's node is active and reachable.
 
-Note the `NodeId` here as `vvrijg034ie10dnn05mv0b2lfo1g7nhv6kb63c03lh7qcc4eqo79g`. This will differ for your node.
+- **Restarting Polykey Agent:** If connectivity issues persist, try restarting the Polykey agent. Persistent errors might indicate restrictive network settings blocking communication.
 
-Now create a 2nd node using the same method, this time with the `node-path` of `tmp/nodeB` and port `55552`. You should see the same password prompt and status read-out. For our example the 2nd node has a `NodeId` of `vd2nmd13qqj718ivke8n8si6cgdsd6ufgche84moofr2fhh9vj2jg`.
+- **Network Alternatives:** Connectivity issues may also be due to restrictive networks, try connecting from a different network environment.
 
-### Connecting and Trusting Nodes
+- **Multiple Nodes:** To test sharing functionality without another user, set up multiple nodes on your system. Refer to the managing multiple nodes section for guidance.
 
-Normally when a `Polykey` node is started, the first thing it does is automatically contact a seed node to join the network. In the absence of seed nodes to act as an entry point for a network. We can tell a node how to find other nodes directly.
+## Sharing the Vault
 
-First we need to tell `NodeA` how to contact `NodeB`. For this we need to know the `NodeId`, `host` and `port` of `NodeB`. If we read the status output of `NodeB` when we started it up, we can see the following information.
+Share a vault with another node using the `polykey vaults share` command:
 
-```
-nodeId  "vvrijg034ie10dnn05mv0b2lfo1g7nhv6kb63c03lh7qcc4eqo79g"
-...
-proxyHost       "0.0.0.0"
-proxyPort       55551
+```bash
+polykey vaults share <vaultName> <nodeId>
 ```
 
-Using this we give `NodeA` `NodeB`'s information using the following command.
+- `<vaultName>`: The name of the vault you wish to share.
+- `<nodeId>`: The Node ID of the node you are sharing the vault with.
 
-```
-node dist/bin/polykey nodes add --node-path tmp/nodeA vd2nmd13qqj718ivke8n8si6cgdsd6ufgche84moofr2fhh9vj2jg 127.0.0.1 55552
-```
-
-This will add the `NodeB`'s connection information into `NodeA`'s node graph. Now whenever we refer to `NodeB` via it's `NodeId` of `vd2nmd13qqj718ivke8n8si6cgdsd6ufgche84moofr2fhh9vj2jg`, `NodeA` will know where to connect to. Note that this step is only needed because both nodes do not share a network. If they did share a network then they could query nodes within the network to find each other.
+:::tip
 
-To verify if this information is correct and a connection can be made, we can ping `NodeB` using the following command.
+Remember, you can run the following commands to reference the argument names to pass into your command:
 
-```
-node dist/bin/polykey nodes ping --node-path tmp/nodeA vd2nmd13qqj718ivke8n8si6cgdsd6ufgche84moofr2fhh9vj2jg
-```
+- `polykey vaults list`
+- `polykey identities list`
 
-If a connection can be made then you should get `Node is Active.` as the response. Otherwise, you will get `No response received`.
+:::
 
-When a connection is made between two nodes then they learn about each other. So when `NodeA` pinged `NodeB`, `NodeB` learned how to connect to `NodeA`. You can verify this by pinging `NodeA` from `NodeB`.
+### Example
 
+```bash
+polykey vaults share my-software-project v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500
 ```
-node dist/bin/polykey nodes ping --node-path tmp/nodeB vfjqk9v06k6p1tnuc4444irt0krasjmi1btmmf7ptaqg477em9390
 
-Node is Active.
-```
+This command shares the "my-software-project" vault with the specified node.
 
-Now if `NodeA` wants to do anything more complex than pinging `NodeB`, we need to make `NodeB` trust `NodeA`. We can do this with the trust command. This will allow `NodeB` to receive notifications from `NodeA`, otherwise `NodeB` will just ignore them.
+## Receiving a Shared Vault
 
-```
-node dist/bin/polykey identities trust --node-path tmp/nodeB vfjqk9v06k6p1tnuc4444irt0krasjmi1btmmf7ptaqg477em9390
-```
+### Scanning for Available Vaults
 
-We should also have `NodeA` trust `NodeB`.
+Once a vault is shared, the recipient should scan for available vaults:
 
-```
-node dist/bin/polykey identities trust --node-path tmp/nodeB vd2nmd13qqj718ivke8n8si6cgdsd6ufgche84moofr2fhh9vj2jg
+```bash
+polykey vaults scan <nodeId>
 ```
 
-### Sharing Vaults
+- `<nodeId>`: The Node ID of the node that shared the vault with you.
 
-#### Creating a Vault
-A core feature of `Polykey` is sharing secrets between nodes. This is done by sharing the vaults that contain the secrets. In order to do this we need a vault to share. Start by creating a vault on `NodeB`. We can do this with the `vaults create` command, doing so will return a unique `VaultId` to identify that vault.
+#### Example
 
+```bash
+polykey vaults scan v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500
 ```
-node dist/bin/polykey vaults create --node-path tmp/nodeB someVault
 
-Vault zRMeFutQmJErPNR5rAE1LmN created successfully
-```
+This command lists the vaults shared by the specified node.
 
-Vaults and generally be referenced by its name, here it's `someVault`. Or it's `VaultId`, here as `zRMeFutQmJErPNR5rAE1LmN`. An empty vault Is not very useful so let's add some data to it.
+## Cloning the Shared Vault
 
+After identifying the shared vaults, the recipient can clone the desired vault to their own local node:
 
+```bash
+polykey vaults clone <vaultName> <nodeId>
 ```
-echo "this is a secret" > tmp/someSecret
 
-node dist/bin/polykey secrets create --node-path tmp/nodeB tmp/someSecret someVault:someSecret
-```
+- `<vaultName>`: The name of the vault to be cloned.
+- `<nodeId>`: The Node ID from which to clone the vault.
 
-We should be able to see the secret in the vault now.
+### Example
 
+```bash
+polykey vaults clone myvault v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500
 ```
-node dist/bin/polykey secrets list --node-path tmp/nodeB someVault
 
-someSecret
-```
+This command clones "myvault" from the specified node to the local system.
 
-#### Sharing a Vault
+## Synchronizing Changes
 
-The next step is allowing `NodeA` to clone a vault from `NodeB`. This is done with the `vaults share` command. This will give `NodeA` permission to clone and pull this vault and send a notification to `NodeA`.
+If updates are made to the original vault, such as key rotations or new secrets added, the receiving node can synchronize these changes by pulling the latest version of the vault:
 
+```bash
+polykey vaults pull <vaultName> <targetNodeId>
 ```
-node dist/bin/polykey vaults share --node-path tmp/nodeB someVault vfjqk9v06k6p1tnuc4444irt0krasjmi1btmmf7ptaqg477em9390
-```
-
-`NodeA` should be able to clone the vault now. This is done with the `vaults clone` command.
 
-```
-node dist/bin/polykey vaults clone --node-path tmp/nodeA someVault vd2nmd13qqj718ivke8n8si6cgdsd6ufgche84moofr2fhh9vj2jg
-```
+- `<vaultNameOrId>`: The name or ID of the vault to update.
+- `<targetNodeId>`: (Optional) The node ID from which to pull updates.
 
-If this completed with no errors, we should be able to see the vault in `NodeA` now.
+### Example
 
+```bash
+polykey vaults pull myvault v4c11qv5fpq2fm3ropmma2sglfc9349jspqb1iutl3f7en1ckv500
 ```
-node dist/bin/polykey vaults list --node-path tmp/nodeA
 
-someVault:              zEsnWCGvgBqSuuu8r2SscSQ
-```
+This command updates "myvault" with the latest changes from the specified node.
 
-We can access the secret as well.
+## Conclussion
 
-```
-node dist/bin/polykey secrets list --node-path tmp/nodeA someVault
-
-someSecret
-
-node dist/bin/polykey secrets get --node-path tmp/nodeA someVault:someSecret
-
-this is a secret
-```
-
-#### Pulling Vault Changes
-
-Vaults can be updated. If we wanted these changes then we can pull the vault. If a vault was cloned from another node then it keeps track of where it came from. So pulling a vault is pretty simple.
-
-First we need to add a new secret to `NodeB`'s vault.
-
-```
-node dist/bin/polykey secrets create --node-path tmp/nodeB tmp/newSecret someVault:newSecret
-
-node dist/bin/polykey secrets list --node-path tmp/nodeB someVault
-
-newSecret
-someSecret
-```
-
-Now we can tell `NodeA` to pull the changes from `NodeB` with `Vaults pull`.
-
-```
-node dist/bin/polykey vaults pull --node-path tmp/nodeA someVault
-```
-
-And see the changes
-
-```
-node dist/bin/polykey secrets list --node-path tmp/nodeA someVault
-
-newSecret
-someSecret
-
-node dist/bin/polykey secrets get --node-path tmp/nodeA someVault:newSecret
-
-This is a new secret
-```
+Sharing and synchronizing vaults in Polykey enhances collaboration and security across the network. By following these guidelines, users can effectively manage sensitive data, ensuring all parties involved have secure and up-to-date access to shared resources.