modify Makefile to add commit hash to book.toml before building, then clean up

afterwards

.editorconfig

@@ -10,8 +10,8 @@ indent_style = tab
 indent_size = 2
 
 [*.md]
-indent_style = tab
+indent_style = space
-indent_size = 4
+indent_size = 2
 
 [*]
 end_of_line = lf

Makefile

@@ -1,20 +1,27 @@
 PORT := 8080
+COMMIT_HASH := $(shell git log -1 --pretty=format:%H | cut -c1-10)
 .PHONY: default
 default: build-qvs
 
 out:
 	mkdir -p out
 
+.PHONY: clean
+clean: 
+	rm -rf out/
+
 .PHONY: build-qvs
-build-qvs: out/qvs/index.json
+build-qvs: clean out/qvs/index.json
 out/qvs/index.json: out Containerfile.qvs $(shell find quorum-vault-system -type f)
 	mkdir -p out/qvs
+	sed -i "/^title *=/c\title = \"Quorum Vault System (QVS) ${COMMIT_HASH}\"" quorum-vault-system/book.toml
 	docker \
 		build \
 		-f Containerfile.qvs \
 		--output type=oci,rewrite-timestamp=true,force-compression=true,name=git.distrust.co/public/docs-qvs,tar=true,dest=- \
 		. \
 	| tar -C out/qvs -mx
+	sed -i "/^title *=/c\title = \"Quorum Vault System (QVS)\"" quorum-vault-system/book.toml
 
 .PHONY: serve-qvs
 serve-qvs: build-qvs

quorum-vault-system/src/SUMMARY.md

@@ -29,12 +29,10 @@
                 * [Transaction Approval](generated-documents/level-2/fixed-location/approver/approve-transaction.md)
             * [Operator](generated-documents/level-2/fixed-location/operator/index.md)
                 * [Quorum Entropy Ceremony](generated-documents/level-2/fixed-location/operator/quorum-entropy-ceremony.md)
-                * [Ceremony SD Card Provisioning](generated-documents/level-2/fixed-location/operator/ceremony-sd-card-provisioning.md)
-                * [Namespace Operations]()
                 * [Namespace Entropy Ceremony](generated-documents/level-2/fixed-location/operator/namespace-entropy-ceremony.md)
+                * [Ceremony SD Card Provisioning](generated-documents/level-2/fixed-location/operator/ceremony-sd-card-provisioning.md)
+                * [SOL - Transfer Token](generated-documents/level-2/fixed-location/operator/coins/sol/transfer-token.md)
+                * [SOL - Generate Address](generated-documents/level-2/fixed-location/operator/coins/sol/generate-address.md)
                 * [Decrypt Namespace Secret](generated-documents/level-2/fixed-location/operator/decrypt-namespace-secret.md)
                 * [Encrypt Wallet To Namespace PGP Key](generated-documents/level-2/fixed-location/operator/encrypt-wallet-to-namespace-key.md)
                 * [Export Namespace Mnemonic](generated-documents/level-2/fixed-location/operator/export-namespace-mnemonic.md)
-                * [Coins - SOL]()
-                    * [SOL - Generate Address](generated-documents/level-2/fixed-location/operator/coins/sol/generate-address.md)
-                    * [SOL - Transfer Token](generated-documents/level-2/fixed-location/operator/coins/sol/transfer-token.md)

quorum-vault-system/src/component-documents/git-basics.md

@@ -4,15 +4,30 @@
 
 1. {{ #include finding-device-name.md:content }}
 
-1. If the `~/vaults/` repository already exists, ensure it doesn't have any changes that haven't been committed, then remove it using `sudo rm -rf ~/vaults` before re-running the previous step
+1. Copy files into designated location in a repository:
 
-1. Copy the repository with updated files to an online machine, sign, commit and push to the `vaults` repository:
+    * e.g `cp -r /media/vaults ~/vaults/`
-    ```
+
-    $ cp -r /media/vaults ~/vaults/
+    * If the `~/vaults/` repository already exists, ensure it doesn't have any changes that haven't been committed, then remove it using `sudo rm -rf ~/vaults` before re-running the previous step
-    $ cd ~/vaults
+
-    $ git add .
+1. Change directory to `vaults`
-    $ git commit -m -S "<message>"
+
-    $ git push origin HEAD
+    * `cd ~/vaults`
-    ```
+
+1. Add all files to git stage:
+
+    * `git add .`
+
+1. Review what files are staged:
+
+    * `git status`
+
+1. Create a signed commit:
+
+    * `git commit -m -S "<message>"`
+
+1. Push the changes to the branch you are on:
+
+    * `git push origin HEAD`
 // ANCHOR_END: content
 /* ANCHOR_END: all */

quorum-vault-system/src/component-documents/git-repository-initialization.md

@@ -11,6 +11,12 @@ Git is used because it permits cryptographic singing of commits using PGP, as we
 
 1. Set appropriate permissions to limit who can write to the repository.
 
+    * `main` branch should be write protected so that merges to that branch can only be done if at least 2 approvals are present
+
+        * The organization may choose to require more approvals based on risk tolerance and operational capacity
+
+    * The merges should be done via CLI signed commits
+
     * Require that all commits are signed using well known PGP keys 
 
 1. Optionally set up a chron job that periodically pulls the data from the repository as a backup.

quorum-vault-system/src/component-documents/openpgp-setup.md

@@ -5,7 +5,7 @@ Setting up a personal PGP key pair is necessary for a number of different
 aspects while bootstrapping QVS. The keys are a fundamental building block, and
 as such need to be set up in a manner that minimizes exposure risks.
 
-## Generating Keys using `keyfork`
+## Generating Keys using `keyfork` and `oct`
 // ANCHOR: steps-keyfork
 
 1. Insert an SD card into the system
@@ -15,7 +15,26 @@ as such need to be set up in a manner that minimizes exposure risks.
     $ cd /media/TRANSFER
     ```
 
-1. Insert all smartcards to be provisioned into the system.
+1. Insert a smartcard into the system, and get its ID:
+
+	a. Set variable with card ID
+    ```
+    $ card_id="$(oct list -i | head -1)"`
+    ```
+	b. Test the variable was set correctly
+    ```
+    $ echo $card_id 
+    ```
+
+1. Set the smart card to require touch for all operations
+
+    ```
+    $ oct admin --card $card_id touch --key SIG --policy On
+    $ oct admin --card $card_id touch --key DEC --policy On
+    $ oct admin --card $card_id touch --key AUT --policy On
+    $ oct admin --card $card_id touch --key ATT --policy On
+    ```
+    Note: default admin PIN is 12345678
 
 1. Set expiry time via environment variable - you can update 2y to desired value:
 
@@ -25,18 +44,30 @@ as such need to be set up in a manner that minimizes exposure risks.
 
 1. Generate a mnemonic, encrypting to a newly-generated key:
         
-	Ensure the User ID is your name and your email.
-
     ```
-    $ keyfork mnemonic generate --encrypt-to-self output=encrypted.asc --provision openpgp-card,userid="Your Name <your@email.co>"
+    $ keyfork mnemonic generate --encrypt-to-self public.asc,output=encrypted.asc --provision openpgp-card,identifier="$card_id"
     ```
 
-	The `count=` variable can be provided to `provision` to ensure the correct
-	amount of smartcards is provisioned - the program will error if the amount
-	of smartcards available is not equal to the count requested.
-
 	Note: The PIN can't use sequential numbers, characters or repeated patterns.
 
+1. Rename output to use key fingerprint:
+
+    ```
+    $ fingerprint="$(sq keyring cert.asc | awk '{ print $2 }')"
+    $ mv public.asc "${fingerprint}.pub.asc"
+    $ mv encrypted.asc "${fingerprint}.enc.asc"
+    ```
+
+1. Optional: Create duplicate smartcards.
+
+    You can insert new smartcards and perform the following steps as needed:
+    
+    ```
+    $ gpg --import *.pub.asc
+    $ gpg --decrypt $fingerprint.enc.asc | KEYFORK_PROMPT_TYPE=headless keyfork recover mnemonic --daemon
+    $ keyfork provision openpgp-card --identifier "$(oct list -i | head -1)" --account-id 0
+    ```
+
 // ANCHOR_END: steps-keyfork
 
 ## Generating Keys on Smartcard 

quorum-vault-system/src/component-documents/tamper-evidence-methods.md

@@ -116,7 +116,7 @@ Sealing bags of standard size objects which need to be protected can fit in. The
 
 1. Insert object(s) into plastic bag
 
-1. Fill bag with enough plastic beads that most of the object is surrounded
+1. Fill bag with enough plastic beads that all of the object is surrounded
 
 1. Use vacuum sealer to remove air from the bag until the beads are no longer able to move
 

quorum-vault-system/src/generated-documents/level-2/fixed-location/approver/approve-transaction.md

@@ -46,11 +46,14 @@ The approver is responsible for verifying a transaction proposed by a [proposer]
 
 1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
 
-1. Copy the git repo locally from the Ceremony SD card and change into it
+1. Copy the git repo locally from the Ceremony SD card
-	```
+
-	$ cp -r /media/vaults /root/vaults
+	* `cp -r /media/vaults /root/vaults`
-	$ cd /root/vaults
+
-	```
+1. Change directory to vaults 
+
+	* `cd /root/vaults`
+
 1. Plug in the Operator smart card
 
 1. Verify the existing signatures and add your own signature:
@@ -69,17 +72,26 @@ The approver is responsible for verifying a transaction proposed by a [proposer]
 
 1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
 
-1. Copy the updated repository locally and change into it:
+1. Copy the updated repository locally:
-	```
+
-	$ cp -r /media/vaults ~/
+	* `cp -r /media/vaults ~/`
-	$ cd ~/vaults
+
-	```
+1. Change into locally copied directory
-1. Stage, sign, commit and push changes to the ceremonies repository:
+
-	```
+	* `cd ~/vaults`
-    $ git add <namespace>/ceremonies/<date>/payloads/*
+
-	$ git commit -S -m "add payload signature for payload_<num>.json"
+1. Stage the modified file:
-	$ git push origin main
+
-	```
+    * `git add <namespace>/ceremonies/<date>/payloads/*`
+
+1. Create a signed git commit:
+
+	* `git commit -S -m "add payload signature for payload_<num>.json"`
+
+1. Push the latest commit to the repository
+	
+	* `git push origin main`
+
 1. Tamper proof the AirgapOS and Air-gapped laptop
 
 {{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing}}

quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/coins/sol/generate-address.md

@@ -36,11 +36,13 @@
 
 1. Retrieve Ceremony SD card from High Visibility Storage and plug it into the air-gapped machine 
 
-1. Copy the `vaults` repository to the machine and switch to it
+1. Copy the `vaults` repository to the machine
-    ```
+
-	$ cp -r /media/vaults /root/
+	* `cp -r /media/vaults /root/`
-	$ cd /root/vaults
+
-    ```
+1. Change directory to `vaults`:
+
+	* `cd /root/vaults`
 
 1. Start Keyfork using the relevant Shardfile:
 
@@ -156,12 +158,22 @@
 
     * Once the airdrop is done, nonce account will be created
 
-1. Stage, commit, sign and push the changes:
+1. Add all files to git stage:
-    ```
+
-    $ git add .
+    * `git add .`
-    $ git commit -m -S "<message>"
+
-    $ git push origin HEAD
+1. Review what files are staged:
-    ```
+
+    * `git status`
+
+1. Create a signed commit:
+
+    * `git commit -m -S "<message>"`
+
+1. Push the changes to the branch you are on:
+
+    * `git push origin HEAD`
+
 ### Sealing
 
 1. Gather all the original items that were in the air-gapped bundle:

quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/namespace-entropy-ceremony.md

@@ -32,12 +32,20 @@ This is a ceremony for generating and sharding entropy to a set of existing Quor
 
 1. Plug in the Ceremony SD card
 
-1. Back up the files     
+    1. Back up the `shardfile.asc`     
-    ```
+
-    $ cp shardfile.asc /media/vaults/<namespace>/
+        * `cp shardfile.asc /media/vaults/<namespace>/` 
-    TODO (NOT IMPLEMENTED): $ cp encryption_certificate.asc /media/vaults/<namespace>/
+
-    $ cp -r /media/vaults /root/
+    1. TODO - NOT IMPLEMENTED:
-    ```
+
+        * Back up the root OpenPGP certificate
+
+        * `cp encryption_certificate.asc /media/vaults/<namespace>/`
+
+    1. Copy the contents of Ceremony SD card to machine
+
+        * `cp -r /media/vaults /root/`
+
 1. To create additional backups of the updated `vaults` repository, plug in SD cards one at a time and use following steps to back up ceremony artifacts
 
     1. Plug in fresh SD card

quorum-vault-system/src/generated-documents/level-2/fixed-location/operator/quorum-entropy-ceremony.md

@@ -35,13 +35,23 @@ This is a ceremony for generating entropy which is used to derive Quorum PGP key
 
 1. Plug in the Ceremony SD card
 
-1. Back up the files   
+    1. Back up the `shardfile.asc`     
-    ```
+
-    $ cp shardfile.asc /media/vaults/<namespace>/ 
+        * `cp shardfile.asc /media/vaults/<namespace>/` 
-    $ cp keyring.asc /media/vaults/<namespace>/
+
-    TODO (NOT IMPLEMENTED): $ cp encryption_cert.asc /media/vaults/<namespace>/
+    1. Back up the `keyring.asc`
-    $ cp -r /media/vaults /root/
+
-    ```
+        * `cp keyring.asc /media/vaults/<namespace>/`
+
+    1. TODO - NOT IMPLEMENTED:
+
+        * Back up the root OpenPGP certificate
+
+        * `cp encryption_cert.asc /media/vaults/<namespace>/`
+
+    1. Copy the contents of Ceremony SD card to machine
+
+        * `cp -r /media/vaults /root/`
 
 1. To create additional backups of the updated `vaults` repository, plug in SD cards one at a time and use following steps to back up ceremony artifacts
 

quorum-vault-system/src/generated-documents/level-2/fixed-location/procurer/index.md

@@ -12,6 +12,8 @@ The procurer is responsible for:
 
 * Ensuring equipment is properly tamper proofed
 
+* Maintaining stock of supplies in the inventory 
+
 * Minimizing hardware supply chain security risks
 
 ## Order of Operations 
@@ -26,10 +28,4 @@ The procurer is responsible for:
 
 1. Procuring [hardware](./procure-hardware.md)
 
-    * Laptops
+1. Procuring [SD cards](./procure-sd-card-pack.md)
-
-    * SD cards
-
-    * SD card USB adapters
-
-    * Smart cards

quorum-vault-system/src/generated-documents/level-2/fixed-location/procurer/procure-facility.md

@@ -7,3 +7,13 @@
 1. Procure an enclosure for locking equipment. A simple lockbox or a safe can be used. It should be at least large enough to fit several laptops, with some extra room.
 
 1. Designate the location as the facility for conducting ceremonies and update documentation and policies to reflect this
+
+## Maintenance
+
+* The facility should always be well stocked with SD cards
+
+* Usage of these SD cards:
+
+    * Transferring transaction data from online to air-gapped machine
+
+    * Storing tamper proofing evidence produced at the end of the ceremony

quorum-vault-system/src/generated-documents/level-2/fixed-location/procurer/procure-hardware.md

@@ -14,10 +14,6 @@
 
 ## Procedure: Online Procurement
 
-1. Select a well known and reputable supplier. Establishing a relationship with a hardware supplier that has a reputation for privacy, supply chain security is preferred.
-
-2. Order the supplies to a registered mailbox, to prevent exposing your organization's location
-
 ## Tamper Proofing
 
 All hardware: 

quorum-vault-system/src/generated-documents/level-2/fixed-location/proposer/create-transaction-payload.md

@@ -38,11 +38,14 @@ The proposer must combine these values into a JSON file, such as:
 
 1. Turn on online machine 
 
-1. Clone the `vaults` repository if it's not available locally and get the latest changes:
+1. Clone the repository if it's not available locally:
-	```
+
-	$ git clone <repository_git_url>
+	* `git clone <repository_git_url>`
-	$ git pull origin main
+
-	```
+1. Pull the latest changes from the `ceremonies` repository
+
+	* `git pull origin main`
+
 1. Unseal the SD Card Pack
 
 {{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-unsealing}}
@@ -63,15 +66,19 @@ The proposer must combine these values into a JSON file, such as:
 
 1. Insert the AirgapOS SD card into the airgapped machine and turn it on
 
-1. Once booted, unplug the AirgapOS SD card and place it in High Visibility Storage 
+1. Once booted, unplug the AirgapOS SD card 
 
 1. Plug in the Ceremony SD card
 
-1. Copy the git repo locally from the Ceremony SD card and change to it
+
-	```
+1. Copy the git repo locally from the Ceremony SD card
-	$ cp -r /media/vaults /root
+
-	$ cd /root/vaults
+	* `cp -r /media/vaults /root`
-	```
+	
+1. Change into the vaults directory:
+
+	* `cd /root/vaults`
+
 1. Create a new payloads directory in the `vaults` repository for the date on which the ceremony for the transaction will take place if it doesn't already exist
 
 	* `mkdir -p <namespace>/ceremonies/<date>/payloads`
@@ -94,21 +101,31 @@ The proposer must combine these values into a JSON file, such as:
 
 	* `cp -r /root/vaults /media`
 
-1. Transfer the SD card from the air-gapped machine to the online machine
+1. Unplug the SD card from the air-gapped machine
+
+1. Plug in the SD card into the online machine
 
 1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
 
-1. Copy the updated repository locally and switch to it:
+1. Copy the updated repository locally:
-	```
+
-	$ cp -r /media/vaults ~/
+	* `cp -r /media/vaults ~/`
-	$ cd ~/vaults
+
-	```
+1. Change into locally copied directory
-1. Stage, sign, commit and push the changes to the ceremonies repository:
+
-	```
+	* `cd ~/vaults`
-    $ git add <namespace>/ceremonies/<date>/payloads/*
+
-	$ git commit -S -m "add payload signature for payload_<num>.json"
+1. Stage the modified file:
-	$ git push origin main
+
-	```
+    * `git add <namespace>/ceremonies/<date>/payloads/*`
+
+1. Create a signed git commit:
+
+	* `git commit -S -m "add payload signature for payload_<num>.json"`
+
+1. Push the latest commit to the repository
+	
+	* `git push origin main`
 
 1. Notify relevant individuals that there are new transactions queued up, and that a ceremony should be scheduled. This can be automated in the future so that when a commit is made or PR opened, others are notified, for example using a incident management tool.
 

quorum-vault-system/src/generated-documents/level-2/fixed-location/provisioner/provision-computer.md

@@ -10,16 +10,14 @@
 
 ## Procedure
 
-1. Unseal a tamper proofed laptop
-
 {{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-unsealing }}
 
-1. Remove all radio cards, storage drive, speakers, and microphone using standard industry laptop repair tactics
+1. Follow a given model manual to remove all radio cards, storage drive, speakers, and microphone using standard industry laptop repair tactics
 
 {{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing }}
 
-1. Apply a new label which indicates the laptop has been provisioned (include date, and any other desired metadata such as a unique ID (e.g Laptop #4))
+1. Apply a new label which indicates the laptop has been provisioned
 
-1. Place the provisioned laptop in inventory
+1. Return the provisioned laptop to inventory
 
-1. Update inventory to reflect that this hardware has been provisioned, and including the metadata in the `description.txt` for that item according to the [inventory repository structure](../procurer/create-inventory-repository.md)
+1. Update inventory to reflect that this hardware has ben provisioned