Merge branch 'feat/use-mini-quorum'

notes-from-lance.txt

@@ -1,92 +0,0 @@
-# Distrust meet 2025-01-13
-
-1. choose location
-	a. random location
-	b. if shipped, neutral location, picked up by both
-
-* barrel jacks are more secure
-
-Level 0
-	* key import from unknown trust level
-	* key export to unknown trust level
-	* use any tools you want
-level 1
-	* icepick level 1
-	* sealing or vault
-	* self custody (by design)
-	* trust single person
-	* portable ceremonies are this level
-	* doesn't matter where they do it, a single individual is trusted
-	* they use tamper evidence because they don't trust others
-	* level 2 assumes witnesses
-
-- [ ] move paragraph above procedures in provisioner/index
-- [ ] add more steps to the docs to make it more explicit
-- [ ] gotta fix the mnemonic word
-
----
-
-break out the requirements for bootstrapping into separate prep doc
-o
-
-* assume every ceremony will be done by different people
-
-* you need to be able to do this ceremony to pass
-	* if u wanna be a multi party operator you need to have a personal computer
-
-
-* personal operator key provisioning
-* provisioning computer
-
-* provisioner should just buy a laptop and tamper proof it 
-	* operators should be gutting laptops
-
-* num of laptops
-	* redundant primary laptop
-	* redundant operator laptops
-	* spare bundles for ceremonies
-
-* all levels need hardware procurement
-
-* commit inventory to a repo, ceremonies repo is fine,
-it can be a text file
-
-## procurer
-
-* obtain numbers of needed items, quantity of each item
-* tamper proof all hardware, sd cards, laptops, etc.
-* tamper proof booster pack of 5 sd cards
-
-- [ ] specner you can go and do these cermonies right now
-
-operator 
-	* gets equipment from ceremony inventory
-
-* get both Spencer and Herve to use a laptop from inventory with airgapos to set up their pgp keys
-
-* provisioned hardware (that's what provisioners do) can write label on bundles
-
-	* operator kits
-	* ceremony kits
-
-* safes and vaults
-	* everything labelled 
-	* didn't use tamper evident bags because they had big vaults
-
-* CSA tamper evident safes
-
-* Spencer tries first, then gets Herve to do it once it's smooth
-
-* could write some data layer stuff in rust
-
-- [ ] track down bug for keyfork mnemonic
-
-* use docs as a way to decide what features to implement
-	* lighter use
-	*  
-- [ ] look ahead at other coins
-	* shell script to make tx
-
-- [ ] do level 0 doc
-
-- [ ] hide document components

quorum-vault-system/src/SUMMARY.md

@@ -9,12 +9,13 @@
     * [Glossary](glossary.md)
 * [Generated Documents]()
     * [All Levels]()
-        * [Create Ceremony Repository](generated-documents/all-levels/create-ceremonies-repository.md)
+        * [Create Vaults Repository](generated-documents/all-levels/create-vaults-repository.md)
         * [Personal PGP Key Provisioning](generated-documents/all-levels/pgp-key-provisioning.md)
     * [Level 2]()
         * [Fixed-Location]()
             * [Procurer](generated-documents/level-2/fixed-location/procurer/index.md)
                 * [Procure Facility](generated-documents/level-2/fixed-location/procurer/procure-facility.md)
+                * [Create Inventory Repository](generated-documents/level-2/fixed-location/procurer/create-inventory-repository.md)
                 * [Procure Tamper Proofing Equipment](generated-documents/level-2/fixed-location/procurer/procure-tamper-proofing-equipment.md)
                 * [Procure SD Card Pack](generated-documents/level-2/fixed-location/procurer/procure-sd-card-pack.md)
                 * [Procure Hardware](generated-documents/level-2/fixed-location/procurer/procure-hardware.md)
@@ -32,3 +33,5 @@
                 * [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)
                 * [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)

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` or `/dev/mmcblk<num>`, 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-basics.md

@@ -0,0 +1,27 @@
+/* ANCHOR: all */
+// ANCHOR: content
+1. Connect SD card to online machine
+
+1. {{ #include finding-device-name.md:content }}
+
+1. Copy files into designated location in a repository:
+
+    * e.g `cp /dev/<your_device> ~/<repository_name>/<path_to_location>`
+
+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-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/inventory-repository.md

@@ -1,4 +1,7 @@
+
+/* ANCHOR: all */
 # Inventory Repository
+// ANCHOR: content
 
 This repository is used to keep track of available inventory and tamper proofing evidence
 
@@ -15,5 +18,14 @@ bundles/
         description.txt
         tamper_evidence_front.jpeg
         tamper_evidence_back.jpeg
+sd_cards/
+    <num>
+        ...
 ```
 
+## Procedure: Setting up Repository
+
+{{ #include ./git-repository-initialization.md:procedure}}
+
+// ANCHOR_END: content
+/* ANCHOR_END: all */

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

@@ -10,11 +10,18 @@ as such need to be set up in a manner that minimizes exposure risks.
 
 1. Insert a smartcard into the system, and get its ID:
 
-	* `identifier="$(oct list -i | head -1)`
+	* `smart_card_id="$(oct list -i | head -1)"`
+
+1. Set the smart card to require touch for all operations:
+
+	* `oct admin --card $smart_card_id touch --key SIG --policy On`
+	* `oct admin --card $smart_card_id touch --key DEC --policy On`
+	* `oct admin --card $smart_card_id touch --key AUT --policy On`
+	* `oct admin --card $smart_card_id touch --key ATT --policy On`
 
 1. Generate a mnemonic, encrypting to a newly-generated key:
         
-	* `keyfork mnemonic generate --size 256 --encrypt-to-self cert.asc,output=encrypted-mnemonic.asc --provision openpgp-card,identifier="$identifier"`
+	* `keyfork mnemonic generate --size 256 --encrypt-to-self cert.asc,output=encrypted-mnemonic.asc --provision openpgp-card,identifier="$smart_card_id"`
 
 1. If additional keys are required, recover the Keyfork key from the encrypted
 	 mnemonic:
@@ -25,17 +32,15 @@ as such need to be set up in a manner that minimizes exposure risks.
 
 	* Remove your previous key, and plug in the new key.
 
-	* `identifier="$(oct list -i | head -1)"`
+	* `smart_card_id="$(oct list -i | head -1)"`
 
-	* `keyfork provision openpgp-card --identifier "$identifier" --account-id 0`
+	* `keyfork provision openpgp-card --identifier "$smart_card_id" --account-id 0`
 
 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`
+	* `cp cert.asc encrypted-mnemonic.asc /media/<device_name>/`
 
 // 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`
-
-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:
+1. 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
-will output something like this:
+One may use the `lsblk` to list the detected storage devices for a system, which will output something like this:
 ```
 NAME    MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
 xvda    202:0    1    50G  0 disk

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

@@ -124,7 +124,7 @@ Sealing bags of standard size objects which need to be protected can fit in. The
 
 1. Date and sign the polaroid photographs and store them in a local lock box
 
-1. Take the SD card to an online connected device, ensuring continued dual custody, and commit the photographs to a repository. If two individuals are present, have one create a PR with a signed commit, and the other do a signed merge commit.
+1. Take the SD card to an online connected device, ensuring continued dual custody, and commit the tamper evidence photographs to a repository. If two individuals are present, have one create a PR with a signed commit, and the other do a signed merge commit.
 
 // ANCHOR_END: vsbwf-procedure-sealing
 
@@ -137,7 +137,7 @@ Sealing bags of standard size objects which need to be protected can fit in. The
 
 1. Compare polaroid to printed photographs of digital record
 
-1. If there is no noticeable difference, proceed with unsealing the object, otherwise initiate an [incident response process (todo)](TODO).
+1. If there is no noticeable difference, proceed with unsealing the object, otherwise initiate an incident response process according to organization's policies.
 
 // ANCHOR_END: vsbwf-procedure-unsealing
 

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

@@ -1,16 +1,20 @@
 /* ANCHOR: all */
-# Ceremony Repository
+# Vaults Repository
 
 // ANCHOR: content
-This repository holds data pertaining to ceremonies. The primary data consists of:
+This repository holds data pertaining to vaults. The primary data consists of:
 
-* Transaction proposals
+* Operation proposals
 
-* Transaction approvals
+* Operation approvals
+
+* Payloads
 
 * Trusted PGP keyring
 
-* Shardfile
+* Shardfiles
+
+* Blockchain metadata
 
 * Policies (such as spending rules)
 
@@ -20,8 +24,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/generated-documents/all-levels/create-ceremonies-repository.md

@@ -1,3 +0,0 @@
-# Create Ceremony Repository
-
-{{ #include ../../component-documents/ceremony-repository.md:content }}

quorum-vault-system/src/generated-documents/all-levels/create-vaults-repository.md

@@ -0,0 +1,3 @@
+# Create Ceremony Repository
+
+{{ #include ../../component-documents/vaults-repository.md:content }}

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/basic-requirements.md

@@ -6,7 +6,7 @@
 
 * 2 individuals with appropriate role 
 
-    * Each needs a [Personal PGP key pair](/key-types.md#personal-pgp-keypair) 
+    * Each needs a [Personal PGP key pair](/generated-documents/all-levels/pgp-key-provisioning.html) 
 
 * [Tamper-proofing equipment](/generated-documents/level-2/fixed-location/procurer/procure-tamper-proofing-equipment.html)
 

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

@@ -14,17 +14,15 @@ The approver is responsible for verifying a transaction proposed by a [proposer]
 
 	* The approver should print photographic evidence from digital cameras which is stored in a PGP signed repository. The photographs should be of the top and underside of the vacuum sealed object.
 
-	* The approver should verify the commit signatures of the photographs they are printing against a list of permitted PGP keys found in the "ceremonies" repo
+	* The approver should verify the commit signatures of the photographs they are printing against a list of permitted PGP keys found in the `vaults` repo
 
-* 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
+* Clone the [Vaults Repository](../../../all-levels/create-vaults-repository.md) for your organization to the machine
 
 ## Procedure
 
 1. Turn on online machine 
 
-1. Pull the latest changes from the `ceremonies` repository
+1. Pull the latest changes from the `vaults` repository
 
 1. Unseal the SD Card Pack
 
@@ -32,7 +30,7 @@ The approver is responsible for verifying a transaction proposed by a [proposer]
 
 1. Plug a fresh SD card into the online machine
 
-1. Save the ceremonies repo to the SD card, referred to as the Ceremony SD card
+1. Save the `vaults` repository to the SD card, referred to as the Ceremony SD card
 
 1. Unplug the Ceremony SD card
 
@@ -46,46 +44,54 @@ 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-name.md:content }}
+
+1. Plug in the Operator smart card
+
 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>/vaults /root/vaults`
 
-1. Verify the detached signature for the payload
+1. Change directory to vaults 
 
-	* `gpg --verify <filename> <filename>.1.sig`
+	* `cd /root/vaults`
 
-	* The filename will be of format: `keys/ceremonies/<date>/payloads/payload_<number>.json`
+1. Verify the existing signatures and add your own signature:
 
-1. Verify the key is authenticated:
+	* `icepick workflow --add-signature-to-file <namespace>/ceremonies/<date>/payload_<num>.json --shardfile <shardfile>.asc`
 
-	* `sq-wot --gpg list "<their@email.co>"`
+1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
 
-	* Ensure the output of the command includes "fully authenticated"
+1. Copy the updated vaults repo to the SD card
 
-1. Sign the transaction payload:
-
-    * `gpg --detach-sign <filename> > <filename>.2.sig`
-
-1. Create a signed git commit:
-
-	* `git commit -S -m "add <name> pgp key"`
-
-1. Copy the updated ceremonies repo to the SD card
-
-	* `cp -r . /media/external/ceremonies`
+	* `cp -r /root/vaults /media/<device_name>/vaults`
 
 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>/vaults ~/`
+
+1. Change into locally copied directory
+
+	* `cd ~/vaults`
+
+1. Stage the modified file:
+
+    * `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}}
-
-## 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 vaults/ /media/<device_name>/`
 
 1. Unplug the SD card 
 

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

@@ -2,14 +2,14 @@
 
 ## Requirements
 
+{{ #include ../../../../operator-requirements.md:requirements }}
+
 * Online machine
 
 * [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.
 
 * [Quorum PGP key pairs](../../key-types.md#quorum-pgp-keypair) 
 
-{{ #include ../../../../operator-requirements.md:requirements }}
-
 * [Ceremony SD card](../../ceremony-sd-card-provisioning.md)
 
 ## Procedure
@@ -50,30 +50,6 @@
 
 1. Retrieve Ceremony SD card from High Visibility Storage and plug it into the air-gapped machine 
 
-1. Verify keyring data from the Ceremony SD card:
-
-	1. Import keys into the system
-
-		* `gpg --import keys/all/*.asc`
-
-	1. Plug in the operator's smartcard, and ensure it is loaded:
-
-		* `gpg --card-status`
-
-	1. Print the list of trusted keys:
-
-		* `sq-wot --gpg list`
-
-	1. Repeat for every operator, ensuring all keys are cross-trusted.
-
-	1. Terminate `gpg-agent`: `killall gpg-agent`
-
-1. Verify all signatures for the workflow data:
-
-	* `for file in <payload.json>.*.sig; do echo "Verifying: $file"; gpg --verify "${file}" "<payload.json>"; done`
-
-	* Ensure that the script doesn't output any "WARNING" messages to the console. If it does, abort the ceremony and initiate incident response.
-
 1. Start Keyfork using the relevant Shardfile:
 
 	* `keyfork recover shard --daemon /media/external/shard.asc`
@@ -84,7 +60,7 @@
 
 1. Run the `icepick` command with the transaction payload
 
-	* `icepick workflow sol transfer-token --input-file=<(jq .values <payload.json>)` 
+	* `icepick workflow --run-quorum <payload>.json --shardfile /media/external/shard.asc`
 
 	* Follow on screen prompts
 

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

@@ -10,35 +10,21 @@
 
 ## Procedure
 
-1. Enter the designated location with required personnel and equipment
-
-1. Lock access to the location - there should be no inflow or outflow of people during the ceremony
-
-1. Retrieve Air-Gapped Bundle and polaroid tamper evidence from locked storage
-
-{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-unsealing}}
-
-1. Place all materials except for the laptop into High Visibility Storage
-
-1. Retrieve AirgapOS SD card from High Visibility Storage and plug it into air-gapped laptop 
-
-1. Turn on the machine
-
-1. Once booted, remove the AirgapOS SD card and place it into High Visibility Storage
+{{ #include template-ceremony-setup.md:content }}
 
 1. Retrieve Ceremony SD Card from High Visibility Storage and plug it into the machine
 
 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:
 
-        * `cp -r /media/<device_name>/* ~`
+        * `cp -r /media/<device_name>/vaults /root/`
 
 1. Start `keyfork` using the relevant Shardfile:
 
-	* `keyfork recover shard --daemon /media/<media_name>/path/to/shardfile.asc`
+	* `keyfork recover shard --daemon /root/vaults/<namespace>/shardfile.asc`
 
     * Follow on screen prompts
 
@@ -51,3 +37,13 @@
     * `sq decrypt --recipient-file secret_key.asc < encrypted.asc --output decrypted`
 
 1. Proceed to transfer the secret (`decrypted`) to desired location such as hardware wallet, power washed chromebook (via SD card) etc. 
+
+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/encrypt-wallet-to-namespace-key.md

@@ -0,0 +1,24 @@
+# Encrypt Wallet to Namespace Key
+
+Procedure for importing an arbitrary secret (raw key, mnemonic, state secrets) into a Namespace.
+
+## Requirements
+
+* [Namespace OpenPGP Certificate]() 
+
+    * It can be on an SD card or accessed online
+
+## Procedure
+
+1. Access machine which has the secret that should be encrypted available
+
+    * If not on a computer, but a hardware wallet or otherwise, perform the steps on a air-gapped machine
+
+1. Encrypt the secret to certificate:
+
+    * `sq encrypt --for-file <certificate> <file_to_encrypt> --output encrypted.asc` TODO: sq needs to be added to airgapOS
+
+1. Once encrypted, name the file appropriately and add it to an `artifacts/` directory in the appropriate namespace subdirectory in the `vaults` repository
+
+{{ #include ../../../../component-documents/git-basics.md:content }}
+

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

@@ -0,0 +1,61 @@
+# 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 > mnemonic.txt`
+
+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
+
+    * WARNING: if displaying on screen, ensure nothing else can see the mnemonic. It is recommended to cover the operator and the machine with a blanket to obstruct the view of the screen.
+
+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

@@ -14,25 +14,15 @@ This is a ceremony for generating and sharding entropy to a set of existing Quor
 
 ## Procedure 
 
-1. Enter the designated location with the operators and all required equipment
-
-1. Lock access to the location - there should be no inflow or outflow of people during the ceremony
-
-1. Retrieve Air-Gapped Bundle and polaroid tamper evidence from locked storage
-
-{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-unsealing}}
-
-1. Plug the AirgapOS SD card into the laptop
-
-1. Turn on the machine
-
-1. Once booted, remove the AirgapOS SD card and place it into High Visibility Storage
+{{ #include template-ceremony-setup.md:content }}
 
 1. Plug the Ceremony SD card into the machine 
 
 1. Run the command to generate new entropy and shard it to quorum of public certificates of the input shardfile:
 
-	* `keyfork mnemonic generate --size 256 --shard-to <path_to_input_shard>,output=<output_shardfile>`
+    * Replace the values: <path_to_input_shard>, <pgp_cert_id>
+
+	* `keyfork wizard generate-shard-secret --shard-to shardfile.asc --output shardfile.new.asc --cert-output keyring.new.asc --derive-openpgp-cert encryption_cert.new.asc,userid=<user_id>` TODO: NOT IMPLEMENTED
 
 1. Unseal an SD card pack
 
@@ -40,23 +30,29 @@ This is a ceremony for generating and sharding entropy to a set of existing Quor
 
 1. Place all unsealed SD cards into High Visibility Storage
 
-1. Back up the `<output_shardfile>` to any desired number of SD cards, and label each "Shardfile [unique_name] [date]"
+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. `cp <shard_file_name> /media/<media_name>`
+    1. Back up the output shardfile: 
+        * `cp shardfile.new.asc /media/<device_name>/`
+
+    1. Back up the new keyring file:
+
+        * `cp keyring.new.asc /media/<device_name>/`
+
+    1. Back up the root PGP certificate:
+        * `cp root_pgp_cert.asc /media/<device_name>/`
 
     1. Each backup should be placed into High Visibility Storage after it's made
 
-<!--
-1. Optionally write an `autorun.sh` file to the Shardfile SD card containing the following command:
+    1. Unplug the SD card and place it in High Visibility Storage
 
-    * `keyfork recover shard --daemon /media/external/<shard_file_name>`
--->
+    1. Label the SD card "Shardfile [date] [namespace]"
 
-1. Unplug the SD card and place it in High Visibility Storage
+1. Upload the newly generated artifacts into the `vaults` repository
 
-1. Label the SD card "Shardfile \[date\] \[namespace\]"
+{{ #include ../../../../component-documents/git-basics.md:content }}
 
 1. Gather all the original items that were in the air-gapped bundle:
 
@@ -65,3 +61,4 @@ This is a ceremony for generating and sharding entropy to a set of existing Quor
     * AirgapOS SD card
 
 {{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-sealing}}
+

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

@@ -6,33 +6,22 @@ This is a ceremony for generating entropy which is used to derive Quorum PGP key
 
 {{ #include ../../operator-requirements.md:requirements }}
 
-* [SD Card Booster Pack](../provisioner/provision-sd-card.md)
+* [SD Card Pack](../procurer/procure-sd-card-pack.md)
 
 * `N` Smart Cards in the chosen `M of N` quorum
 
-* [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.
+* High Visibility Storage: 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 required personnel and equipment
-
-1. Lock access to the location - there should be no inflow or outflow of people during the ceremony
-
-1. Retrieve Air-Gapped Bundle and polaroid tamper evidence from locked storage
-
-{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-unsealing}}
-
-1. Place all materials except for the laptop into High Visibility Storage
-
-1. Retrieve AirgapOS SD card from High Visibility Storage and plug it into air-gapped laptop 
-
-1. Turn on the machine
-
-1. Once booted, remove the AirgapOS SD card and place it into High Visibility Storage
+{{ #include template-ceremony-setup.md:content }}
 
 1. Run the relevant keyfork wizard to perform the ceremony:
 
-	* `keyfork wizard generate-shard-secret --threshold <M> --max <N> --keys-per-shard=<number_of_smart_cards_per_operator> --output shardfile.asc --cert-output keyring.asc`
+    * Replace the following values: <M>, <N>, <number_of_smart_cards_per_operator>, <pgp_cert_id>
+
+
+    * `keyfork wizard generate-shard-secret --threshold <M> --max <N> --keys-per-shard=<number_of_smartcards_per_operator> --output shardfile.asc --cert-output keyring.asc --derive-openpgp-cert encryption_cert.asc,userid=<pgp_cert_id>` TODO: NOT IMPLEMENTED
 
 1. Unseal an SD card pack
 
@@ -42,25 +31,29 @@ 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/<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>`
-
-<!--
-    1. Optionally write an `autorun.sh` file to the Shardfile SD card containing the following command:
-
-        * `echo -e '#!/bin/bash\nkeyfork recover shard --daemon' > /media/<media_name>/autorun.sh`
--->
+        * `cp keyring.asc /media/<device_name>/`
 
     1. Unplug the SD card and place it in High Visibility Storage
 
-    1. Label the SD card "Shardfile [date]"
+    1. Label the SD card "Ceremony [date]"
+
+1. Power down the air-gapped machine
+
+1. Transfer the ceremony artifacts to an online machine using one of the SD cards and upload the newly generated artifacts into the `vaults` repository in the appropriate `<namespace>` sub directory using an online machine
+
+{{ #include ../../../../component-documents/git-basics.md:content }}
 
 1. Gather all the original items that were in the air-gapped bundle:
 

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

@@ -0,0 +1,19 @@
+/* ANCHOR: all */
+// ANCHOR: content
+1. Enter the designated location with required personnel and equipment
+
+1. Lock access to the location - there should be no inflow or outflow of people during the ceremony
+
+1. Retrieve Air-Gapped Bundle and polaroid tamper evidence from locked storage
+
+{{ #include ../../../../component-documents/tamper-evidence-methods.md:vsbwf-procedure-unsealing}}
+
+1. Place all materials except for the laptop into High Visibility Storage
+
+1. Retrieve AirgapOS SD card from High Visibility Storage and plug it into air-gapped laptop 
+
+1. Turn on the machine
+
+1. Once booted, remove the AirgapOS SD card and place it into High Visibility Storage
+// ANCHOR_END: content
+/* ANCHOR_END: all */

quorum-vault-system/src/generated-documents/level-2/fixed-location/procurer/create-inventory-repository.md

@@ -0,0 +1,3 @@
+# Create Inventory Repository
+
+{{ #include ../../../../component-documents/inventory-repository.md:content }}

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

@@ -8,9 +8,9 @@ The procurer is responsible for:
 
     * [Hardware](procure-hardware.md) (computers, sd cards, sd card adapters, smart cards, cameras etc.)
 
-* Ensuring equipment is properly tamper proofed
+* Creating and maintaining the [Inventory](create-inventory-repository.md)
 
-* Ensuring inventory is updated properly
+* Ensuring equipment is properly tamper proofed
 
 * Maintaining stock of supplies in the inventory 
 
@@ -22,6 +22,8 @@ The procurer is responsible for:
 
 1. Procuring a [facility](./procure-facility.md)
 
+1. Creating a [Inventory repository](create-inventory-repository.md)
+
 1. Procuring [tamper proofing equipment](./procure-tamper-proofing-equipment.md)
 
 1. Procuring [hardware](./procure-hardware.md)

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)
@@ -29,27 +28,35 @@ The proposer must combine these values into a JSON file, such as:
 
 	* The proposer  should print photographic evidence from digital cameras which is stored in a PGP signed repository. The photographs should be of the top and underside of the vacuum sealed object.
 
-	* The proposer should verify the commit signatures of the photographs they are printing against a list of permitted PGP keys found in the "ceremonies" repo
+	* The proposer should verify the commit signatures of the photographs they are printing against a list of permitted PGP keys found in the `vaults` repo
 
-* [Online Machine](TODO)
+* Online Machine
 
-* 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
+* Clone the [Vaults Repository](../../../all-levels/create-vaults-repository.md) for your organization to the machine
 
 ## 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. Save the ceremonies repo to the SD card, referred to as the Ceremony SD card
+1. {{ #include ../../../../component-documents/finding-device-name.md:content }}
+
+1. Save the `vaults` repo to the SD card, referred to as the Ceremony SD card
+
+	* `cp -r ~/vaults/ /media/<device_name>/`
 
 1. Unplug the Ceremony SD card
 
@@ -63,74 +70,66 @@ 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. 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>/vaults /root/vaults`
 	
-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/`
+1. Change into the vaults directory:
 
-	* `mkdir -p keys/ceremonies/2024-01-01/payloads`
+	* `cd /root/vaults`
 
-1. Determine a new filename `payload_<num>.json`, for example `payload_1.json`
+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
 
-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.
+	* `mkdir -p <namespace>/ceremonies/<date>/payloads`
 
-	```json
-	{
-		"workflow": ["<workflow_namespace>", "<workflow_name>"],
-		"values": {
-			"<workflow_field>": "<workflow_value>"
-		},
-		"proposal_datetime": "<datetime>"
-	}
-	```
+	* e.g `mkdir -p solana-01/ceremonies/2025-01-01/payloads`
 
-	Example data object:
+1. Use `icepick workflow --help` to list the available workflows and options
 
-	```json
-	{
-		"workflow": ["cosmos", "withdraw"],
-		"values": {
-			"delegate_address": "kyve1q9w3nar74up6mxnwd428wpr5nffcw3360tkxer",
-			"validator_address": "kyvevaloper1ghpmzfuggm7vcruyhfzrczl4aczy8gas8guslh",
-			"asset_name": "KYVE",
-			"asset_amount": "0.4",
-			"chain_name": "korellia"
-		},
-		"proposal_datetime": "2025-01-28T18:18:00"
-	}
-	```
+1. Use icepick to generate and sign the payload:
 
-1. Import the keys relevant to the ceremony:
+	* `icepick workflow <chain> <workflow> <--option value> <--option value> --export-for-quorum --sign > <output_file>`
 
-	* `gpg --import keys/all/*.asc`
+	* e.g `icepick workflow cosmos withdraw-rewards --delegate-address kyve1q9w3nar74up6mxnwd428wpr5nffcw3360tkxer --validator-address kyvevaloper1ghpmzfuggm7vcruyhfzrczl4aczy8gas8guslh --chain-name korellia --export-for-quorum --sign > <namespace>/ceremonies/<date>/payloads/payload_<num>.json`
 
-1. Sign the data in the CLI using `gpg` or another OpenPGP implementation:
-
-	* `gpg --detach-sign <file> <file>.1.sig`
+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/vaults /media/<device_name>/vaults`
 
 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>/vaults ~/`
+
+1. Change into locally copied directory
+
+	* `cd ~/vaults`
+
+1. Stage the modified file:
+
+    * `git add <namespace>/ceremonies/<date>/payloads/*`
+
 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"`
 
 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/index.md

@@ -4,14 +4,12 @@ The provisioner is responsible for:
 
 * Provisioning hardware
 
-* Provisioning SD Cards (AirapOS, Keychain, Shardfiles etc.)
+* Provisioning SD Cards (AirapOS, Ceremony etc.)
 
-* Provisioning ceremony bundles
+* Provisioning bundles (e.g Air-Gapped bundle)
 
 ## Procedures
 
-* [Provision SD Card](./provision-sd-card.md)
-* [Provision Ceremonies Repository](./provision-ceremonies-repository.md)
 * [Provision AirgapOS](./provision-airgapos.md)
 * [Provision Computer](./procure-computer.md)
     * Requires tamper proofing equipment to be available

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/generated-documents/level-2/fixed-location/provisioner/provision-ceremonies-repository.md

@@ -1,3 +1,3 @@
 # Provision Ceremony Repository
 
-{{ #include ../../../../component-documents/ceremony-repository.md:content }}
+{{ #include ../../../../component-documents/vaults-repository.md:content }}

quorum-vault-system/src/generated-documents/level-2/hardware.md

@@ -23,6 +23,8 @@
 
 * Computers which are compatible which can be verified via [this guide](https://git.distrust.co/public/airgap#hardware-compatibility)
 
+* Online Use: Chromebook or QubesOS laptop
+
 // ANCHOR_END: computer-models
 
 ## Digital Camera

quorum-vault-system/src/generated-documents/level-2/operator-requirements.md

@@ -4,6 +4,9 @@
 ## For Quorum Based Operations
 // ANCHOR: requirements
 
+* For ALL tamper proofed hardware used in the ceremony, both operators MUST print photographic evidence from digital cameras which is stored in a PGP signed repository. The photographs should be of the top and underside of the vacuum sealed object.
+
+    * The operators should verify the commit signatures of the photographs they are printing against a list of permitted PGP keys found in the "ceremonies" repo
 
 * [Air-gapped bundle](/generated-documents/level-2/fixed-location/provisioner/air-gapped-bundle.md)
 
@@ -13,9 +16,5 @@
 
 * Tamper-proofing equipment
 
-* Both operators should print photographic evidence from digital cameras which is stored in a PGP signed repository. The photographs should be of the top and underside of the vacuum sealed object.
-
-    * The operators should verify the commit signatures of the photographs they are printing against a list of permitted PGP keys found in the "ceremonies" repo
-
 // ANCHOR_END: requirements
 /* ANCHOR_END: all */

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>