From bec08e95496561f244144638ef2c76ec6a664243 Mon Sep 17 00:00:00 2001
From: Matt Stofko <matt@mjslabs.com>
Date: Wed, 16 Sep 2020 21:29:37 -0700
Subject: [PATCH] Improving documentation

---
 README.md   | 26 +++++++++++++++++++++++---
 examples/bw | 16 ++++++++++++----
 2 files changed, 35 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index afea7fc..ca6a545 100644
--- a/README.md
+++ b/README.md
@@ -35,7 +35,7 @@ cumbersome.
 Each bitagent process is capable of storing only one secret. This keeps the code
 simple, which helps keep it performant and reduces the chance of errors.
 
-Installation & usage
+Installation
 ---
 
 To install bitagent, use the standard `go install` process.
@@ -46,10 +46,18 @@ git clone https://github.com/mjslabs/bitagent.git && cd bitagent
 go install
 ```
 
+Usage
+---
+
 The easiest way to work with bitagent is by making a wrapper script for your
 use case. See [examples](examples), which includes such a script for use with
 the Bitwarden CLI. Below are the instructions for working with bitagent
-manually, or when creating your own wrapper script.
+manually, or when creating your own wrapper script. If you're only interested in
+the Bitwarden use case, see the comments at the top of the
+[bw](examples/bw) example file.
+
+If you're interested in running bitagent manually, or creating your own wrapper,
+read on.
 
 First, launch bitagent using your system's preferred method of backgrounding a
 process, e.g.
@@ -74,6 +82,18 @@ To retrieve the secret, use `G`.
 echo "G" | nc -U ~/.bitagent.sock -N
 ```
 
+Full example showing the storage of the string `mysecret`, then retrieving it.
+
+```shell
+$ echo Pmysecret | nc -U ~/.bitagent.sock -N
+$ echo G | nc -U ~/.bitagent.sock -N
+mysecret
+```
+
+Your wrapper script should understand the output of the command you're proxying,
+parsing the output for whatever token you're looking to store, then use `nc` or
+something similar to store and retrieve the secret as needed.
+
 Caveats
 ---
 
@@ -83,7 +103,7 @@ out or included in core dumps. This has not been fully vetted by the authors of
 bitagent.  
 
 bitagent defaults to storing up to a 256 byte secret. This is tunable at the
-top of [main.go](main.go). This should be made to be dynamic.
+top of [bitagent.go](cmd/bitagent.go). This should be made dynamic.
 
 The only thing stopping someone from accessing your secret in bitagent is the
 permissions on the socket file. These default to a sane value, but there are
diff --git a/examples/bw b/examples/bw
index ef219f6..e6c89b2 100755
--- a/examples/bw
+++ b/examples/bw
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 
-# Proxy commands for the bitwarden CLI, intercepting them to get or set a
-# session token for seamless use between shells and other programs.
+# This script will proxy commands for the bitwarden CLI, intercepting them to
+# get or set a # session token for seamless use between shells and other programs.
 # Make sure this script is in your $PATH, so you can simply run 'bw' like you
 # normally would.
 
@@ -9,22 +9,28 @@
 # able to use this as an install method:
 # curl https://raw.githubusercontent.com/mjslabs/bitagent/master/examples/bw > $HOME/bin/bw && chmod 0755 $HOME/bin/bw
 
-# Installation of the bitwarden CLI
+# You will want to make sure that $bwcmd below is the full path to the real
+# bitwarden cli. The default is 'bwcli' stored in ~/bin
+
+# Installation of the real bitwarden CLI
 bwcmd="${HOME}/bin/bwcli"
 # Default socket location
 basock="${HOME}/.bitagent.sock"
-# This assumes you've run a `go install`
+# This assumes you've run a `go install` to install bitagent
 bitagent="${GOBIN:-${HOME}/go/bin}/bitagent $basock"
 
+# If our socket doesn't exist then run bitagent
 if [[ ! -e $basock ]]; then
   $bitagent 1>/dev/null & disown
 fi
 
+# If runninig 'bw unlock' or 'bw login', expect the session key to be output on success
 if [[ $1 == "unlock" || $1 == "login" ]]; then
   unlockOut=$($bwcmd $1)
   <<< $unlockOut grep -q BW_SESSION
   if [[ $? == "0" ]]; then
     echo "$1 successful"
+    # Store the key in bitagent
     echo "P"$(<<< $unlockOut tr -d '\n' | sed -e 's/^.*BW_SESSION="\(.*\)".*$/\1/') | nc -U $basock -N
   else
     echo "$1 failed"
@@ -32,6 +38,8 @@ if [[ $1 == "unlock" || $1 == "login" ]]; then
   fi
   exit
 else
+  # We're running some bitwarden command that isn't login or unlock,
+  # so set BW_SESSION using the secret in bitagent, then run the bw cli
   export BW_SESSION="$(echo G | nc -U $basock -N)"
   if [[ $BW_SESSION == "" ]]; then
     # Avoids "Session key is invalid." being sent to the terminal