README: fixup start of document explaining bip39 and bip32

Cargo.lock

@@ -1763,6 +1763,9 @@ dependencies = [
 [[package]]
 name = "keyfork-entropy"
 version = "0.1.0"
+dependencies = [
+ "smex",
+]
 
 [[package]]
 name = "keyfork-frame"
@@ -1786,15 +1789,6 @@ dependencies = [
  "sha2",
 ]
 
-[[package]]
-name = "keyfork-plumbing"
-version = "0.1.0"
-dependencies = [
- "keyfork-entropy",
- "keyfork-mnemonic-util",
- "smex",
-]
-
 [[package]]
 name = "keyfork-prompt"
 version = "0.1.0"

Cargo.toml

@@ -19,7 +19,6 @@ members = [
     "crates/util/keyfork-frame",
     "crates/util/keyfork-mnemonic-util",
     "crates/util/keyfork-prompt",
-    "crates/util/keyfork-plumbing",
     "crates/util/keyfork-slip10-test-data",
     "crates/util/smex",
 ]

README.md

@@ -1,16 +1,25 @@
 # keyfork #
 
 An opinionated and modular toolchain for generating and managing a wide range
-of cryptographic keys offline and on smartcards from a shared bip39 mnemonic
+of cryptographic keys offline and on smartcards from a shared [BIP-0039]
-phrase.
+mnemonic phrase. BIP-0039 phrases are used to calculate a [BIP-0032] seed,
+which is used for hierarchical deterministic key derivation.
+
+**Note:** The difference between the data encoded in a BIP-0039 mnemonic, and
+the BIP-0032 seed, is that a BIP-0039 mnemonic of any length can be used to
+generate a BIP-0032 seed of a static length (512 bits). Keyfork makes use of a
+BIP-0039 mnemonic and does not accept just a BIP-0032 seed - it will be treated
+as the entropy provided for a mnemonic, or rejected outright for being of an
+invalid size.
 
 Keyfork can be used by organizations and solo users, for the purposes of
 disaster recovery, cold storage, and reproducibility of private keys and secret
-data. Keyfork achieves this by using a bip32 seed loaded into an agent to
+data. Keyfork achieves this by loading a BIP-0032 seed into an agent to
 generate deterministic and unique keypairs. This ensures only the agent has
-control over the mnemonic itself, and other components can request
+control over the root seed itself, and other components can request
-deterministic data. The seed can be split using the Keyfork Shard mechanism,
+deterministic data. The BIP-0039 data can also be split using the Keyfork Shard
-which utilizes Shamir's Secret Sharing to allow "M-of-N" recovery of the seed.
+mechanism, which utilizes Shamir's Secret Sharing to allow "M-of-N" recovery of
+the data.
 
 All crate licenses are notated using the "license" field in their respective
 Cargo.toml. As a general rule, As a general rule, crates with binaries are
@@ -57,8 +66,8 @@ Note: The following features are proposed, and may not yet be implemented.
     * Config file and 24 word mnemonic phrase to recover *every* key
     * Shard mechanism allows for "M-of-N" recovery of seed if lost
   * Unpredictable
-    * Generate a BIP39 phrase from OS or physicalized entropy
+    * Generate a BIP-0039 phrase from OS or physicalized entropy
-    * Provide and use BIP39 passphrase from user supplied entropy
+    * Provide and use BIP-0039 passphrase from user supplied entropy
     * Read up on [milksad](https://milksad.info) to understand why this matters!
   * Deterministic
     * Given the same seed, repeated derivation requests will be reproducible
@@ -217,6 +226,8 @@ which can be opened in-browser by running
 `mdbook serve --open docs`.
 
 [`docs`]: /public/keyfork/src/branch/main/docs/src/SUMMARY.md
+[BIP-0039]: https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki
+[BIP-0032]: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki
 
 <!--
 ```
@@ -230,7 +241,7 @@ keyfork version
 keyfork help
     Show this text.
 keyfork [command]
-    Commands receive bip32 root as stdin
+    Commands receive BIP-0032 root as stdin
     Commands return output and config data as json over stdout back to keyfork
 keyfork [command] help
     Show help for a particular sub-command

crates/keyfork/src/cli/recover.rs

@@ -27,8 +27,8 @@ pub enum RecoverSubcommands {
 }
 
 impl RecoverSubcommands {
-    /// Return the 128-bit or 256-bit entropy for a bip39 mnemonic. This is _not_ the same as the
+    /// Return the 128-bit or 256-bit entropy for a BIP-0039 mnemonic. This is _not_ the same as
-    /// 512-bit seed used by bip32.
+    /// the 512-bit seed used by BIP-0032.
     fn handle(&self) -> Result<Vec<u8>> {
         match self {
             RecoverSubcommands::Shard {

crates/util/keyfork-entropy/Cargo.toml

@@ -6,4 +6,9 @@ license = "MIT"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
+[features]
+default = []
+bin = ["smex"]
+
 [dependencies]
+smex = { version = "0.1.0", path = "../smex", optional = true }

crates/util/keyfork-plumbing/Cargo.toml

@@ -1,12 +0,0 @@
-[package]
-name = "keyfork-plumbing"
-version = "0.1.0"
-edition = "2021"
-license = "AGPL-3.0-only"
-
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
-[dependencies]
-keyfork-entropy = { version = "0.1.0", path = "../keyfork-entropy" }
-keyfork-mnemonic-util = { version = "0.1.0", path = "../keyfork-mnemonic-util" }
-smex = { version = "0.1.0", path = "../smex" }

crates/util/keyfork-prompt/src/validators.rs

@@ -142,7 +142,7 @@ pub mod mnemonic {
         }
     }
 
-    /// A mnemonic of a given choice of lengths. For example, a 128-bit or 256-bit bip32 seed.
+    /// A mnemonic of a given choice of lengths. For example, a 128-bit or 256-bit BIP-0032 seed.
     #[derive(thiserror::Error, Debug)]
     pub enum MnemonicChoiceValidationError {
         /// The provided mnemonic did not match any of the valid ranges.

docs/src/INSTALL.md

@@ -10,15 +10,16 @@ cargo install --index https://git.distrust.co/public/_cargo-index keyfork@0.1.0
 
 The index is managed by Distrust, but is not signed by developers when commits
 are created, so a safer alternative may be to build from source. It is
-recommended to perform these operations on a machine dedicated for the purpose
+recommended to perform these operations in an environment dedicated for the
-of building Rust binaries, to avoid the risk of building a compromised binary.
+purpose of building Rust binaries, to avoid the risk of building a compromised
+binary.
 
 ```sh
 git clone https://git.distrust.co/public/keyfork
 cd keyfork
 # git checkout keyfork-0.1.0
 git verify-commit HEAD
-cargo install --locked --path keyfork
+cargo install --locked --path crates/keyfork
 ```
 
 This will build Keyfork from source, using a local `Cargo.lock` file to ensure
@@ -30,15 +31,12 @@ Keyfork offers "plumbing" binaries (as opposed to the "porcelain" `keyfork`)
 that offer a smaller [SBOM], allowing users with a smaller feature requirement
 to lessen the requirements for code review. Plumbing binaries can be installed
 the same way Keyfork is installed, either through the registry or by building
-locally. Plumbing binaries are grouped by crates of shared dependencies. For
+locally. Plumbing binaries may be grouped by crates of shared dependencies if
-instance, `keyfork-plumbing` includes all binaries using only shared
+all dependencies are shared between the binaries. Plumbing binaries may also
-dependencies. Eventually, `keyfork-plumbing-openpgp` may contain all
+exist in crates that exist only to serve as a command-line interface to that
-dependencies relevant to OpenPGP (such as the `keyfork-shard` variants,
+crate, but may require additional dependencies to build a binary. These will be
-`keyfork-derive-openpgp`, and `keyfork-provision-openpgp-card`). There may also
+specified by `--features bin` as a flag that should be passed to `cargo
-be plumbing binaries that exist by themselves, without a plumbing package.
+install`.
-Unfortunately, Cargo offers no convenient way to install a binary from any
-package on a workspace, so the information about which package contains which
-binary must be known beforehand.
 
 <!-- TODO:
   Should plumbing binaries be their own packages?
@@ -46,8 +44,11 @@ binary must be known beforehand.
   -->
 
 ```sh
-cargo install --index https://git.distrust.co/public/_cargo-index keyfork-plumbing@0.1.0
+# Currently (2024-01-17) unreleased, may not exist yet
-cargo install --locked --path keyfork-plumbing --bin keyfork-entropy
+cargo install --index https://git.distrust.co/public/_cargo-index keyfork-entropy@0.1.0 --features bin
+
+# Confirmed to work as of 2024-01-17.
+cargo install --locked --path crates/util/keyfork-entropy --bin keyfork-entropy --features bin
 ```
 
 [SBOM]: https://en.wikipedia.org/wiki/SBOM

docs/src/dev-guide/provisioners.md

@@ -9,7 +9,7 @@ particular mechanism) to an external source, such as a smart card. Provisioners
 should hardcode at least one path index (such as `7366512`, for "PGP") specific
 to the usage of the key to be provisioned (and such index should be recorded in
 the keyfork-path-data crate), and accept at least one index to use as what
-bip32 calls an "account". While some users may never practically make use of
+BIP-0032 calls an "account". While some users may never practically make use of
 multiple accounts, having the option to specify multiple accounts is important.
 
 ## Plumbing