keyfork-user-guide: add dev guide

This commit is contained in:
Ryan Heywood 2023-10-18 13:24:07 -05:00
parent 9599734bd6
commit 8809db6f7f
Signed by: ryan
GPG Key ID: 8E401478A3FBEF72
2 changed files with 38 additions and 0 deletions

View File

@ -11,3 +11,4 @@
- [keyfork-mnemonic-from-seed](./bin/keyfork-plumbing/mnemonic-from-seed.md)
- [keyfork-derive-key](./bin/keyfork-derive-key.md)
- [keyfork-derive-openpgp](./bin/keyfork-derive-openpgp.md)
- [Development Guide](./dev-guide/index.md)

View File

@ -0,0 +1,37 @@
# Development Guide
### Binaries - Porcelain and Plumbing
Binaries are split into two categories, porcelain (such as `keyfork`) and
plumbing (just about everything else). Porcelain binaries include what can be
called "the kitchen sink". They offer support for everything - an intuitive
interface, automatic `keyforkd` management, interconnectivity between
derivation utilities and provisioning utilities, and the ability to read from
and write to a configuration file. Plumbing binaries, on the other hand, are
often very rough around the edges and pull in as few dependencies as possible.
Usually, only cryptographic functionality (such as `sequoia-openpgp` or
`dalek-ed25519`) or hardware integration libraries (such as `openpgp-card`) are
included.
### Auditing Dependencies
Dependencies must be reviewed before being added to the repository, and must
not be added for pure convenience. There are few exceptions, such as `clap` and
`thiserror`, which provide derivation macros that are used heavily throughout
`keyfork` and the codebase as a whole. Any dependency added must be reviewed at
least on a surface level to ensure no malicious actions are performed with the
data the library will be responsible for handling. For example, any use of
`std::process` in a crate providing cryptographic functions should be heavily
scrutinized, and any crate that loads arbitrary code or performs networking
requests should have an incredibly important reason for doing so.
Dependencies should be restricted such that the least amount of dead code is
enabled. For instance, a crate such as `keyfork_derive_openpgp` can only make
use of the `ed25519` algorithm, so it exports its own `derive_util` that only
includes the crates required for that library. This can then be used by
programs such as `keyfork-shard`'s OpenPGP mode or `keyfork provision openpgp`
to ensure only the required dependencies are enabled. This reduces the burden
of auditors, but it does mean we can't use projects such as [`hakari`] to
optimize full-project builds.
[`hakari`]: https://docs.rs/cargo-hakari/latest/cargo_hakari/index.html