many usability improvements

quorum-vault-system/src/SUMMARY.md

@@ -31,8 +31,6 @@
                 * [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)
-<<<<<<< HEAD
                 * [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)
->>>>>>> feat/encrypt-wallet-to-namespace
+                * [Export Namespace Mnemonic](generated-documents/level-2/fixed-location/operator/export-namespace-mnemonic.md)

quorum-vault-system/src/component-documents/ceremony-repository.md

@@ -10,7 +10,9 @@ This repository holds data pertaining to ceremonies. The primary data consists o
 
 * Trusted PGP keyring
 
-* Shardfile
+* Shardfiles
+
+* Blockchain metadata
 
 * Policies (such as spending rules)
 
@@ -20,8 +22,6 @@ This repository holds data pertaining to ceremonies. The primary data consists o
 
 * MUST be a private repository
 
-* MUST be write protected, requiring approval from at least 1 individual other than one who opened the PR for merging
-
 * MUST require signed commits
 
 ## Repository Structure

quorum-vault-system/src/component-documents/finding-device-name.md

@@ -0,0 +1,6 @@
+/* ANCHOR: all */
+// ANCHOR: content
+Look for your SD card device name (`<device_name>`) in the output of the `lsblk` command. It will typically be listed as `/dev/sdX`, where X is a letter (e.g., `/dev/sdb`, `/dev/sdc`). You can identify it by its size or by checking if it has a partition (like `/dev/sdX1`)
+    * You may mount the device using: `sudo mount /dev/<your_device> media/` 
+// ANCHOR_END: content
+/* ANCHOR_END: all */

quorum-vault-system/src/component-documents/git-commit-signing.md

@@ -3,7 +3,7 @@
 // ANCHOR: steps
 1. Retrieve the value of your PGP key ID by using:
 
-    `gpg --list-keys`
+    * `gpg --list-keys`
 
 1. Set up local `.gitconfig` file with desired PGP key:
     ```

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

@@ -31,11 +31,9 @@ as such need to be set up in a manner that minimizes exposure risks.
 
 1. Insert an SD card to contain the public certificate and the encrypted mnemonic.
 
-	* `lsblk`
+	* {{ #include finding-device-name.md:content}} 
 
-	* `sudo mount /dev/<your_device> media/`
+	* `cp cert.asc encrypted-mnemonic.asc /media/<device_name>/`
-
-	* `cp cert.asc encrypted-mnemonic.asc /media`
 
 // ANCHOR_END: steps-keyfork
 

quorum-vault-system/src/component-documents/sd-formatting.md

@@ -4,27 +4,23 @@
 
     * microSD or standard SD card can be used
 
-2. Launch a terminal 
+1. Launch a terminal 
 
-3. List all block devices, including your SD card:
+1. {{ #include finding-device-name.md: content }}  
 
-    * `lsblk`
+1. Before formatting, you need to unmount the SD card. Replace `/dev/sdX1` with the actual partition name you identified in the previous step:
-
-4. Look for your SD card in the output of the `lsblk` command. It will typically be listed as `/dev/sdX`, where X is a letter (e.g., `/dev/sdb`, `/dev/sdc`). You can identify it by its size or by checking if it has a partition (like `/dev/sdX1`)
-
-5. Before formatting, you need to unmount the SD card. Replace `/dev/sdX1` with the actual partition name you identified in the previous step:
 
     * `sudo umount /dev/sdX1`
 
-6. Use the mkfs command to format the SD card. You can choose the file system type (e.g., vfat for FAT32, ext4, etc.). Replace /dev/sdX with the actual device name (without the partition number):
+1. Use the mkfs command to format the SD card. You can choose the file system type (e.g., vfat for FAT32, ext4, etc.). Replace /dev/sdX with the actual device name (without the partition number):
 
     * `sudo mkfs.vfat /dev/sdX`
 
-7. You can verify that the SD card has been formatted by running lsblk again or by checking the file system type:
+1. You can verify that the SD card has been formatted by running lsblk again or by checking the file system type:
 
     * `lsblk -f`
 
-8. Once formatting is complete, you can safely remove physically or eject the SD card:
+1. Once formatting is complete, you can safely remove physically or eject the SD card:
 
     * `sudo eject /dev/sdX`
 //ANCHOR_END:steps

quorum-vault-system/src/component-documents/storage-device-management.md

@@ -9,8 +9,7 @@ USB devices are assigned names when they are connected to a Linux operating
 system. The first storage device is assigned the name `sda` (storage device a),
 the second `sdb`, the third `sdc` and so on.
 
-One may use the `lsblk` to list the detected storage devices for a system, which
+One may use the `lsblk` to list the detected storage devices for a system, which will output something like this:
-will output something like this:
 ```
 NAME    MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
 xvda    202:0    1    50G  0 disk

quorum-vault-system/src/generated-documents/all-levels/pgp-key-provisioning.md

@@ -2,7 +2,10 @@
 
 ## Requirements
 
-* Computer that can load AirgapOS ([compatibility reference](https://git.distrust.co/public/airgap#tested-models))
+* Computer
+    * Preferred: [AirGapped Bundle](../level-2/fixed-location/provisioner/air-gapped-bundle.md)
+    
+    * Alternative: Computer that can load AirgapOS ([compatibility reference](https://git.distrust.co/public/airgap#tested-models))
 
 * [AirgapOS SD card](../level-2/fixed-location/provisioner/provision-airgapos.md)
 
@@ -12,6 +15,10 @@
 
 ##  Generate OpenPGP Key
 
+1. If using AirGapped Bundle unseal first, otherwise proceed to step where AirgapOS SD card is inserted into computer
+
+{{ #include ../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-unsealing }}
+
 1. Insert AirgapOS SD card into computer
 
 1. Boot to AirgapOS
@@ -54,6 +61,10 @@
 
 1. Place the file in `keys/all/<key_fingerprint>.asc`
 
+1. Stage the modified file:
+
+    * `git add keys/all/<key_fingerprint>.asc`
+
 1. Create signed git commit:
 
     * `git commit -S -m "add <name> pgp key"`
@@ -69,3 +80,8 @@
     * Fallback: via two logically distinct online communications methods (e.g. encrypted chat, and video call)
 
 1. Get confirmation they have used `gpg --import <your_key_id>.asc` to import your key from the git repo to the keyrings on workstations they will use to interact with the ceremony repo
+
+## Local Configurations for OpenPGP
+This configuration enables the use of smart cards for OpenPGP operations, and enforces git commit signing.
+
+{{ #include ../../component-documents/git-commit-signing.md:steps }}

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

@@ -46,15 +46,27 @@ The approver is responsible for verifying a transaction proposed by a [proposer]
 
 1. Plug in the Ceremony SD card
 
+1. {{ #include ../../../../component-documents/finding-device-names.md:content }}
+
+1. Plug in the Operator smart card
+
+1. Set a local variable `pgp_key_id` to the smart card OpenPGP key id:
+    
+    * `pgp_key_id="$(oct list -i | head -1)`
+
 1. Copy the git repo locally from the Ceremony SD card
 
-	* `cp -r /media/external/ceremonies /root/ceremonies; cd /root/ceremonies`
+	* `cp -r /media/<device_name>/ceremonies /root/ceremonies`
+
+1. Change directory to ceremonies 
+
+	* `cd /root/ceremonies`
 
 1. Verify the detached signature for the payload
 
-	* `gpg --verify <filename> <filename>.1.sig`
+	* `gpg --verify <payload>.<num>.json <payload>.<num>.<key_id>.sig`
 
-	* The filename will be of format: `keys/ceremonies/<date>/payloads/payload_<number>.json`
+	* The filename will be of format: `/<namespace>/ceremonies/<date>/payloads/payload_<number>.json`
 
 1. Verify the key is authenticated:
 
@@ -64,28 +76,42 @@ The approver is responsible for verifying a transaction proposed by a [proposer]
 
 1. Sign the transaction payload:
 
-    * `gpg --detach-sign <filename> > <filename>.2.sig`
+    * `gpg --detach-sign <namespace>/ceremonies/<date>/payloads/payload_<num>.json > <namespace>/ceremonies/<date>/payloads/payload_<num>_$pgp_key_id.sig`
+
+	* e.g `gpg --detach-sign solana-01/ceremonies/2025-01-01/payloads/payload_1.json > solana-01/ceremonies/2025-01-01/payloads/payload_1_F4BF5C81EC78A5DD341C91EEDC4B7D1F52E0BA4D.sig`
+
+1. Stage the modified file:
+
+    * `git add <namespace>/ceremonies/<date>/payloads/payload_<num>_$pgp_key_id.sig`
 
 1. Create a signed git commit:
 
-	* `git commit -S -m "add <name> pgp key"`
+	* `git commit -S -m "add payload signature for payload_<num>.json using $pgp_key_id"`
+
+1. {{ #include ../../../../component-documents/finding-device-names.md:content }}
 
 1. Copy the updated ceremonies repo to the SD card
 
-	* `cp -r . /media/external/ceremonies`
+	* `cp -r /root/ceremonies /media/<device_name>/ceremonies`
 
 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:
+
+	* `cp -r /media/<device_name>/ceremonies ~/`
+
+1. Change into locally copied directory
+
+	* `cd ~/ceremonies`
+
 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}}
-
-## Appendix
-
-### Git Commit Signing Configuration
-
-{{ #include ../../../../component-documents/git-commit-signing.md:steps }}

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

@@ -20,11 +20,11 @@
 
 1. Navigate to the ceremony repository for the ceremony being executed
 
-1. Find the SD cards device name using `lsblk`
+* {{ #include ../../../../component-documents/finding-device-name.md:content }}
 
 1. Write the ceremony repo data to the SD card:
 
-    `cp ceremonies/ /media/<device_name>`
+    `cp -r ceremonies/ /media/<device_name>/`
 
 1. Unplug the SD card 
 

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

@@ -30,7 +30,7 @@
 
 1. Copy the Ceremony SD Card contents to machine
 
-    * Find device name using `lsblk`
+    * {{ #include ../../../../component-documents/finding-device-name.md:content }}
 
     * Copy the contents of the card to machine:
 
@@ -38,7 +38,7 @@
 
 1. Start `keyfork` using the relevant Shardfile:
 
-	* `keyfork recover shard --daemon /media/<media_name>/path/to/shardfile.asc`
+	* `keyfork recover shard --daemon /media/<device_name>/path/to/shardfile.asc`
 
     * Follow on screen prompts
 

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

@@ -0,0 +1,59 @@
+# Export Namespace Mnemonic
+
+## Requirements
+
+{{ #include ../../operator-requirements.md:requirements }}
+
+* [SD Card Pack](../procurer/procure-sd-card-pack.md)
+
+* [Ceremony SD Card](../operator/ceremony-sd-card-provisioning.md) 
+
+* [High Visibility Storage](TODO): plastic container or bag that's used to keep items while not in use in a visible location like the middle of a desk.
+
+## Procedure
+
+1. Enter the designated location with the quorum of operators and all required equipment
+
+1. Lock access to the location - there should be no inflow or outflow of people during the ceremony
+
+1. Place Ceremony SD card in High Visibility Storage
+
+1. Retrieve sealed Air-Gapped bundle, polaroid of tamper evidence, and online laptop from locked storage
+
+{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-unsealing}}
+
+1. Place all contents except for the laptop into High Visibility Storage
+
+1. Retrieve AirgapOS SD card and plug it into the air-gapped machine
+
+1. Boot the computer  
+
+1. Unplug the AirgapOS SD card and place it in High Visibility Storage
+
+1. Retrieve Ceremony SD card from High Visibility Storage and plug it into the air-gapped machine 
+
+1. Recover the mnemonic from an existing shardfile
+
+    * {{ #include ../../../../component-documents/finding-device-name.md:content }}
+
+    * `keyfork shard combine /media/<device_name>/shard.asc | keyfork-mnemonic-from-seed`
+
+1. Follow on screen prompts
+
+1. Unplug the Ceremony SD card and place it in High Visibility Storage
+
+1. Unseal the SD Card Pack 
+
+{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-unsealing}}
+
+1. Put the mnemonic on an SD card for transport or use `cat` command to output it in the terminal for entry into a hardware wallet or otherwise
+
+1. Shut down the air gapped machine
+
+1. Gather all the original items that were in the air-gapped bundle:
+
+    * Air-gapped computer
+
+    * AirgapOS SD card
+
+{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing}}

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

@@ -44,17 +44,17 @@ This is a ceremony for generating and sharding entropy to a set of existing Quor
 
 1. Back up the newly generated artifacts to any desired number of SD cards, and label each "Shardfile [unique_name] [date]"
 
-    1. `lsblk` to find media name
+    1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
 
     1. Back up the output shardfile: 
-        * `cp shardfile.new.asc /media/<media_name>/`
+        * `cp shardfile.new.asc /media/<device_name>/`
 
     1. Back up the new keyring file:
 
-        * `cp keyring.new.asc /media/<media_name>/`
+        * `cp keyring.new.asc /media/<device_name>/`
 
     1. Back up the root PGP certificate:
-        * `cp root_pgp_cert.asc /media/<media_name>/`
+        * `cp root_pgp_cert.asc /media/<device_name>/`
 
     1. Each backup should be placed into High Visibility Storage after it's made
 

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

@@ -46,19 +46,19 @@ This is a ceremony for generating entropy which is used to derive Quorum PGP key
 
 1. Plug in SD cards one at a time and use following steps to back up ceremony artifacts
 
-    1. Find media name using `lsblk`
+    1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
 
     1. Back up the root OpenPGP certificate
 
-        * `cp encryption_cert.asc /media/<media_name>/`
+        * `cp encryption_cert.asc /media/<device_name>/`
 
     1. Back up the `shardfile.asc`     
 
-        * `cp shardfile.asc /media/<media_name>/` 
+        * `cp shardfile.asc /media/<device_name>/` 
 
     1. Back up the `keyring.asc`
 
-        * `cp keyring.asc /media/<media_name>/`
+        * `cp keyring.asc /media/<device_name>/`
 
     1. Unplug the SD card and place it in High Visibility Storage
 

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

@@ -20,7 +20,6 @@ The proposer must combine these values into a JSON file, such as:
 }
 ```
 
-
 ## Requirements
 
 * [Quorum PGP Key](../operator/quorum-entropy-ceremony.md)
@@ -35,22 +34,32 @@ The proposer must combine these values into a JSON file, such as:
 
 * Ensure that the computer is configured to sign commits with the desired key. Refer to the [Appendix: Git Commit Signing Configuration](#git-commit-signing-configuration)
 
-* Clone the [Ceremonies Repository](../provisioner/provision-ceremonies-repository.md) for your organization to the machine
+* Organization's Ceremonies repository git url
 
 ## Procedure
 
 1. Turn on online machine 
 
+1. Clone the repository if it's not available locally:
+
+	* `git clone <repository_git_url>`
+
 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}}
 
 1. Plug a fresh SD card into the online machine
 
+1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
+
 1. Save the ceremonies repo to the SD card, referred to as the Ceremony SD card
 
+	* `cp -r ~/ceremonies/ /media/<device_name>/`
+
 1. Unplug the Ceremony SD card
 
 1. Unseal the tamper proofed bundle
@@ -63,18 +72,38 @@ The proposer must combine these values into a JSON file, such as:
 
 1. Plug in the Ceremony SD card
 
+1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
+
+1. Plug in the Operator smart card
+
+1. Set a local variable `pgp_key_id` to the smart card OpenPGP key id:
+	
+	* `pgp_key_id="$(oct list -i | head -1)`
+
 1. Copy the git repo locally from the Ceremony SD card
 
-	* `cp -r /media/external/ceremonies /root/ceremonies; cd /root/ceremonies`
+	* `cp -r /media/<device_name>/ceremonies /root/ceremonies`
+	
+1. Change into the ceremonies directory:
 
-1. Create a new directory in the `ceremonies` repository for the date on which the ceremony for the transaction will take place if it doesn't already exist, for example `2024-01-01/`
+	* `cd /root/ceremonies`
 
-	* `mkdir -p keys/ceremonies/2024-01-01/payloads`
+1. Create a new payloads directory in the `ceremonies` repository for the date on which the ceremony for the transaction will take place if it doesn't already exist
 
-1. Determine a new filename `payload_<num>.json`, for example `payload_1.json`
+	* `mkdir -p <namespace>/ceremonies/<date>/payloads`
+
+	* e.g `mkdir -p solana-01/ceremonies/2025-01-01/payloads`
+
+1. Create a new file `payload_<num>.json`, for example `payload_1.json`
+
+	* `touch <namespace>/ceremonies/<date>/payloads/payload_<num>.json`
+
+	* e.g `touch solana-01/ceremonies/2025-01-01/payloads/payload_1.json`
 
 1. Collect data for the transaction being sent, and structure it according to the template below, replacing values with valid ones. The values have to come from a organization approved list of values, for each field, except for `datetime` which is just the current date and time.
 
+	* Write the data to the file: `vim <namespace>/ceremonies/<date>/payloads/payload_<num>.json`
+
 	```json
 	{
 		"workflow": ["<workflow_namespace>", "<workflow_name>"],
@@ -100,37 +129,50 @@ The proposer must combine these values into a JSON file, such as:
 		"proposal_datetime": "2025-01-28T18:18:00"
 	}
 	```
-
 1. Import the keys relevant to the ceremony:
 
-	* `gpg --import keys/all/*.asc`
+	* `gpg --import <namespace>/keyring.asc`
 
 1. Sign the data in the CLI using `gpg` or another OpenPGP implementation:
 
-	* `gpg --detach-sign <file> <file>.1.sig`
+	* `gpg --detach-sign <namespace>/ceremonies/<date>/payloads/<payload>_<num>.json > <namespace>/ceremonies/<date>/payloads/payload_<num>_$pgp_key_id.sig`
+
+	* e.g `gpg --detach-sign solana-01/ceremonies/2025-01-01/payloads/payload_1.json > solana-01/ceremonies/2025-01-01/payloads/payload_1_F4BF5C81EC78A5DD341C91EEDC4B7D1F52E0BA4D.sig`
+
+1. Stage the new file:
+
+	* `git add <namespace>/ceremonies/<date>/payloads/<payload>.<num>.$pgp_key_id.sig`
+
+1. Create a signed git commit:
+
+	* `git commit -S -m "add payload signature for payload_<num>.sig using $pgp_key_id"`
+
+1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
 
 1. Copy the updated ceremonies repo to the SD card
 
-	* `cp -r . /media/external/ceremonies`
+	* `cp -r /root/ceremonies /media/<device_name>/ceremonies`
 
 1. Unplug the SD card from the air-gapped machine
 
 1. Plug in the SD card into the online machine
 
-1. Create a signed git commit:
+1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
 
-	* `git commit -S -m "add <name> pgp key"`
+1. Copy the updated repository locally:
+
+	* `cp -r /media/<device_name>/ceremonies ~/`
+
+1. Change into locally copied directory
+
+	* `cd ~/ceremonies`
 
 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.
 
 1. Tamper proof the AirgapOS and Air-gapped laptop
 
 {{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing}}
-
-## Appendix
-
-### Git Commit Signing Configuration
-
-{{ #include ../../../../component-documents/git-commit-signing.md:steps }}

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

@@ -32,7 +32,7 @@
 
 1. Retrieve a labelled SD card from High Visibility Storage, and plug it into the computer where AirgapOS will be built
 
-1. Look for your SD card in the output of the `lsblk` command. It will typically be listed as `/dev/sdX`, where X is a letter (e.g., `/dev/sdb`, `/dev/sdc`). You can identify it by its size or by checking if it has a partition (like `/dev/sdX1`)
+1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
 
 1. Flash `airgap.iso` to an SD Card:
 
@@ -42,7 +42,7 @@
 
 1. Once booted, the card needs to be locked using `sdtool` which is available in `AirgapOS`:
 
-    * Find out the block device name using `lsblk`
+    * {{ #include ../../../../component-documents/finding-device-name.md:content }}
 
     * Note: the device will not mount as a proper block device on QubesOS so a different OS has to be used where the device appears as /dev/mmcblk<num>
 

quorum-vault-system/src/sdtool-instructions.md

@@ -19,7 +19,7 @@ This tool is also available via [stagex](https://registry.hub.docker.com/r/stage
           * To get container hash: `docker inspect --format='{{json .RepoDigests}}'  stagex/sdtool`
           * Check the [signatures dir](https://codeberg.org/stagex/stagex/src/branch/main/signatures/stagex) in stagex project for latest signed hashes
 
-1. Use `lsblk` to figure out the SD card device name
+1. {{ #include finding-device-name.md:content }}
 
     * Note: the device will not mount as a proper block device on QubesOS so a different OS has to be used where the device appears as /dev/mmcblk<num>