keyfork: add docs, clean help output

Cargo.lock

@@ -327,6 +327,7 @@ dependencies = [
  "anstyle",
  "clap_lex",
  "strsim",
+ "terminal_size",
 ]
 
 [[package]]
@@ -828,6 +829,17 @@ dependencies = [
  "yaml-rust",
 ]
 
+[[package]]
+name = "io-lifetimes"
+version = "1.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eae7b9aee968036d54dce06cebaefd919e4472e753296daccd6d344e3e2df0c2"
+dependencies = [
+ "hermit-abi",
+ "libc",
+ "windows-sys 0.48.0",
+]
+
 [[package]]
 name = "is-terminal"
 version = "0.4.9"
@@ -835,7 +847,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cb0889898416213fab133e1d33a0e5858a48177452750691bde3666d0fdbaf8b"
 dependencies = [
  "hermit-abi",
- "rustix",
+ "rustix 0.38.13",
  "windows-sys 0.48.0",
 ]
 
@@ -1080,6 +1092,12 @@ version = "0.5.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0717cef1bc8b636c6e1c1bbdefc09e6322da8a9321966e8928ef80d20f7f770f"
 
+[[package]]
+name = "linux-raw-sys"
+version = "0.3.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef53942eb7bf7ff43a617b3e2c1c4a5ecf5944a7c1bc12d7ee39bbb15e5c1519"
+
 [[package]]
 name = "linux-raw-sys"
 version = "0.4.7"
@@ -1604,6 +1622,20 @@ dependencies = [
  "semver",
 ]
 
+[[package]]
+name = "rustix"
+version = "0.37.25"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4eb579851244c2c03e7c24f501c3432bed80b8f720af1d6e5b0e0f01555a035"
+dependencies = [
+ "bitflags 1.3.2",
+ "errno",
+ "io-lifetimes",
+ "libc",
+ "linux-raw-sys 0.3.8",
+ "windows-sys 0.48.0",
+]
+
 [[package]]
 name = "rustix"
 version = "0.38.13"
@@ -1613,7 +1645,7 @@ dependencies = [
  "bitflags 2.4.0",
  "errno",
  "libc",
- "linux-raw-sys",
+ "linux-raw-sys 0.4.7",
  "windows-sys 0.48.0",
 ]
 
@@ -1896,7 +1928,7 @@ dependencies = [
  "cfg-if",
  "fastrand",
  "redox_syscall 0.3.5",
- "rustix",
+ "rustix 0.38.13",
  "windows-sys 0.48.0",
 ]
 
@@ -1911,6 +1943,16 @@ dependencies = [
  "winapi",
 ]
 
+[[package]]
+name = "terminal_size"
+version = "0.2.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e6bf6f19e9f8ed8d4048dc22981458ebcf406d67e94cd422e5ecd73d63b3237"
+dependencies = [
+ "rustix 0.37.25",
+ "windows-sys 0.48.0",
+]
+
 [[package]]
 name = "thiserror"
 version = "1.0.49"

keyfork/Cargo.toml

@@ -7,7 +7,7 @@ edition = "2021"
 
 [dependencies]
 keyfork-mnemonic-util = { version = "0.1.0", path = "../keyfork-mnemonic-util" }
-clap = { version = "4.4.2", features = ["derive", "env"] }
+clap = { version = "4.4.2", features = ["derive", "env", "wrap_help"] }
 thiserror = "1.0.48"
 smex = { version = "0.1.0", path = "../smex" }
 keyfork-plumbing = { version = "0.1.0", path = "../keyfork-plumbing" }

keyfork/src/cli/mnemonic.rs

@@ -118,6 +118,13 @@ impl MnemonicSeedSource {
 #[derive(Subcommand, Clone, Debug)]
 pub enum MnemonicSubcommands {
     /// Generate a mnemonic using a given entropy source.
+    ///
+    /// Mnemonics are a form of encoding a given form of entropy and are used to create a master
+    /// seed for BIP-0032 hierarchial derivation. The mnemonic is like the "password" for all of
+    /// Keyfork's derivations, and should be treated securely. This command provides a secure
+    /// method of generating a seed using system entropy, as well as various forms of loading
+    /// physicalized entropy into a mnemonic. The mnemonic should be stored in a safe location
+    /// (such as a Trezor "recovery seed card") and never persisted digitally.
     Generate {
         /// The source from where a seed is created.
         #[arg(long, value_enum, default_value_t = Default::default())]

keyfork/src/cli/mod.rs

@@ -17,10 +17,10 @@ pub enum KeyforkCommands {
     /// Mnemonic generation and persistence utilities.
     Mnemonic(mnemonic::Mnemonic),
 
-    /// Secret sharing utilities.
+    /// Splitting and combining secrets using Shamir's Secret Sharing.
     Shard(shard::Shard),
 
-    /// Keyforkd background daemon to manage seed creation.
+    /// Keyforkd background daemon to manage derivation.
     Daemon,
 }
 

keyfork/src/cli/shard.rs

@@ -105,7 +105,12 @@ struct P256;
 
 #[derive(Subcommand, Clone, Debug)]
 pub enum ShardSubcommands {
-    /// Split a secret into multiple shares, using Shamir's Secret Sharing.
+    /// Split a hex-encoded secret from input into multiple shares, using Shamir's Secret Sharing.
+    ///
+    /// The shares are encrypted once per key, with keys discovered either on-system or by
+    /// prompting for hardware interactions. Metadata about decrypting keys is then stored and
+    /// encrypted to all keys, to ensure any key that holds a share can then be used to begin the
+    /// process of combining keys.
     Split {
         /// The amount of shares required to recombine a secret.
         #[arg(long)]
@@ -119,7 +124,12 @@ pub enum ShardSubcommands {
         key_discovery: PathBuf,
     },
 
-    /// Combine multiple shares into a secret
+    /// Combine multiple encrypted shares into a hex-encoded secret, printed to stdout.
+    ///
+    /// This command only accepts input from `keyfork shard split`, and is dependent on the format
+    /// used when splitting. Metadata is encrypted to all keys that may hold a share, so when using
+    /// hardware metadata discovery, any hardware key used to split may be used to decrypt metadata
+    /// used to combine.
     Combine {
         /// The amount of sharesr equired to recombine a secret.
         #[arg(long)]