291 lines
11 KiB
Markdown
291 lines
11 KiB
Markdown
# x
|
|
|
|
## Description
|
|
|
|
`sneak.berlin/go/x` is a WTFPL-licensed Go module and CLI tool by
|
|
[@sneak](https://sneak.berlin) that serves as an umbrella publishing space for
|
|
small reusable packages, plus `sutil`, a command-line utility that exposes them
|
|
from the shell.
|
|
|
|
Importable packages live in `pkg/`. The CLI is `cmd/sutil/`, and the code that
|
|
exists only to support it lives in `internal/`.
|
|
|
|
## Getting Started
|
|
|
|
### Install the CLI
|
|
|
|
```sh
|
|
go install sneak.berlin/go/x/cmd/sutil@latest
|
|
```
|
|
|
|
Or, from a checkout:
|
|
|
|
```sh
|
|
make build # builds ./sutil with the git version embedded
|
|
make install # installs sutil into $(go env GOBIN)
|
|
```
|
|
|
|
### Use the CLI
|
|
|
|
```sh
|
|
# An endless stream of fast pseudorandom bytes; stop it with Ctrl-C.
|
|
sutil generate random | pv > /dev/null
|
|
|
|
# The same, but deterministic: the same seed always produces the same bytes.
|
|
sutil generate random --count 1073741824 "my seed" > testdata.bin
|
|
|
|
# A memorable password: three dictionary words, each followed by a digit,
|
|
# joined by a randomly chosen delimiter. Requires a system word list.
|
|
sutil generate password
|
|
# marble7-sprout2-velvet9
|
|
|
|
# A new 24-word BIP39 mnemonic phrase (or --words 12).
|
|
sutil generate mnemonic
|
|
|
|
# A crypto_box keypair derived from a mnemonic. The mnemonic is read from
|
|
# stdin, never from the command line, so it stays out of shell history.
|
|
sutil generate mnemonic > mnemonic.txt
|
|
sutil cbk derive < mnemonic.txt
|
|
sutil cbk derive --public < mnemonic.txt
|
|
|
|
# Build metadata, including which config file (if any) was loaded.
|
|
sutil version
|
|
sutil info
|
|
|
|
# Every command first loads ~/.sneak.yaml (or .json, .toml, ...) if it
|
|
# exists, or the file named with --config.
|
|
sutil --config ./sneak.yaml info
|
|
```
|
|
|
|
### Use the packages
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"fmt"
|
|
|
|
"sneak.berlin/go/x/pkg/bip39wordlist"
|
|
"sneak.berlin/go/x/pkg/cbk"
|
|
)
|
|
|
|
func main() {
|
|
mnemonic, err := bip39wordlist.GenerateMnemonic(bip39wordlist.MaxWordCount)
|
|
if err != nil {
|
|
panic(err)
|
|
}
|
|
|
|
// The same mnemonic (and optional passphrase) always yields the same
|
|
// keypair, on any machine.
|
|
alice, err := cbk.New(cbk.Params{Mnemonic: mnemonic})
|
|
if err != nil {
|
|
panic(err)
|
|
}
|
|
|
|
bob, err := cbk.FromMnemonic("abandon abandon abandon abandon abandon " +
|
|
"abandon abandon abandon abandon abandon abandon about")
|
|
if err != nil {
|
|
panic(err)
|
|
}
|
|
|
|
sealed, err := alice.Seal([]byte("hello bob"), bob.PublicKey)
|
|
if err != nil {
|
|
panic(err)
|
|
}
|
|
|
|
plain, err := bob.Open(sealed, alice.PublicKey)
|
|
if err != nil {
|
|
panic(err)
|
|
}
|
|
|
|
fmt.Println(string(plain), alice.PublicKeyHex())
|
|
}
|
|
```
|
|
|
|
## Rationale
|
|
|
|
- **Reusable odds and ends need a home.** Several small packages are worth
|
|
sharing between projects but are too small to each deserve a repository, CI
|
|
pipeline, and release cadence of their own. This module collects them under
|
|
one import path.
|
|
- **`/dev/urandom` is slow.** Operating system random devices are tuned for
|
|
small requests of key material, not for filling a disk or producing gigabytes
|
|
of test data. `sutil generate random` streams pseudorandom bytes at close to
|
|
memory bandwidth, and can do so deterministically from a seed so test data is
|
|
reproducible.
|
|
- **Keys you can carry in your head.** A crypto_box keypair derived from a BIP39
|
|
mnemonic can be regenerated anywhere from a phrase a human can write down or
|
|
memorize, with no key file to lose. `pkg/cbk` makes that derivation explicit
|
|
and reproducible.
|
|
- **Passwords you can type.** Three dictionary words with digits and a delimiter
|
|
are far easier to transcribe than line noise, and with the macOS word list
|
|
they still carry about 62 bits of entropy.
|
|
|
|
## Design
|
|
|
|
### Layout
|
|
|
|
| Path | Purpose |
|
|
| ---------------------- | --------------------------------------------------- |
|
|
| `cmd/sutil/` | `package main`; the whole entrypoint is a few lines |
|
|
| `internal/cli/` | The cobra command tree, built by `cli.New` |
|
|
| `internal/randstream/` | Fast seeded pseudorandom byte stream |
|
|
| `internal/pwgen/` | Password generator over the system dictionary |
|
|
| `pkg/bip39wordlist/` | BIP39 English wordlist and mnemonic helpers |
|
|
| `pkg/cbk/` | crypto_box keypairs derived from BIP39 mnemonics |
|
|
|
|
The split between `pkg/` and `internal/` is deliberate and should be kept:
|
|
`pkg/` holds only packages designed to be imported by other programs, with a
|
|
stable, documented API. Anything that exists to support `sutil` goes under
|
|
`internal/`, even if it would be harmless to export, so that the public surface
|
|
of the module stays small and intentional.
|
|
|
|
The command tree holds no global state: `cli.New` builds every command from a
|
|
`Params` struct, so tests construct it repeatedly with captured input and
|
|
output, and nothing happens in `init` functions. Before any command runs, the
|
|
root command's persistent pre-run loads the optional configuration file (the one
|
|
named by `--config`, or else `.sneak.*` in the home directory found with
|
|
`go-homedir`) into a viper instance that also exposes environment variables. No
|
|
command consumes settings from it yet; `sutil info` reports which file was
|
|
loaded. Tests point `Params.ConfigDir` at a temporary directory so the real home
|
|
directory is never read.
|
|
|
|
### `pkg/cbk`
|
|
|
|
Derives NaCl crypto_box keypairs (Curve25519, XSalsa20, Poly1305)
|
|
deterministically from BIP39 mnemonics, and seals and opens messages with them.
|
|
The derivation is fixed and documented so keys are reproducible:
|
|
|
|
1. The mnemonic is validated and canonicalized with
|
|
`bip39wordlist.NormalizeWordlist`.
|
|
2. The standard 64-byte BIP39 seed is computed with PBKDF2-HMAC-SHA512 (2048
|
|
rounds, salt `"mnemonic" + passphrase`), exactly as a BIP39 wallet would, so
|
|
the optional passphrase works as the usual "25th word".
|
|
3. The 32-byte private key is
|
|
`HKDF-SHA256(seed, salt = nil, info = cbk.DerivationInfo)`.
|
|
4. The public key is the Curve25519 base-point multiple of the private key.
|
|
|
|
A sealed message is a 24-byte random nonce followed by the box ciphertext, so it
|
|
can be handled as a single opaque byte string. The API:
|
|
|
|
- `cbk.New(cbk.Params{Mnemonic, Passphrase})` and `cbk.FromMnemonic(m)` return a
|
|
`CryptoBoxKeypair`.
|
|
- `CryptoBoxKeypair.Seal(message, recipientPublicKey)` and
|
|
`CryptoBoxKeypair.Open(sealed, senderPublicKey)`.
|
|
- `CryptoBoxKey.Hex()`, `CryptoBoxKey.Bytes()`, `cbk.KeyFromHex(s)`, and the
|
|
`PublicKeyHex`, `PrivateKeyHex`, `PublicKeyBytes`, `PrivateKeyBytes` accessors
|
|
on the keypair.
|
|
|
|
The test suite pins the keypair derived from the standard all-zero-entropy BIP39
|
|
test vector. If that test ever fails, the derivation has changed and existing
|
|
keys are no longer reproducible.
|
|
|
|
### `pkg/bip39wordlist`
|
|
|
|
The BIP39 English wordlist, embedded from `english.txt` and checked against the
|
|
reference implementation in the tests, plus mnemonic helpers:
|
|
|
|
- `ValidateWordlist(mnemonic)` checks word count, every word, and the checksum,
|
|
ignoring letter case and whitespace. It reports what is wrong with sentinel
|
|
errors (`ErrInvalidWordCount`, `ErrUnknownWord` naming the word and its
|
|
position, `ErrInvalidChecksum`).
|
|
- `NormalizeWordlist(mnemonic)` returns the canonical lowercase,
|
|
single-space-separated form, and refuses anything invalid.
|
|
- `GenerateMnemonic(wordCount)` makes a new mnemonic of 12, 15, 18, 21, or 24
|
|
words from `crypto/rand`.
|
|
- `Contains(word)`, `ValidWordCount(n)`, and the `WordlistEnglish` and
|
|
`Wordlist` tables.
|
|
|
|
### `internal/randstream`
|
|
|
|
An `io.Reader` that expands a 32-byte key with the ChaCha8 generator from
|
|
`math/rand/v2`. With a seed string the key is its SHA-256 and the stream is
|
|
deterministic; without one the key comes from `crypto/rand`, which is the only
|
|
time the operating system's random source is touched. The output is for bulk
|
|
data, not for cryptographic keys.
|
|
|
|
### `internal/pwgen`
|
|
|
|
Produces passwords of the form
|
|
|
|
```
|
|
<word><digit><delim><word><digit><delim><word><digit>
|
|
```
|
|
|
|
where the delimiter is drawn once per password from `.-_|~+=:,!@#%^&*` and used
|
|
in both positions. Words come from the system word list
|
|
(`/usr/share/dict/words`) through `github.com/kavfixnel/words`, filtered to
|
|
lowercase ASCII words of four to eight letters, which drops proper nouns and
|
|
abbreviations. All choices use `crypto/rand`. On a system without a word list,
|
|
`sutil generate password` panics rather than falling back to something weaker;
|
|
the upstream library is only known to work on macOS.
|
|
|
|
### CLI
|
|
|
|
```
|
|
sutil
|
|
├── version print the build version
|
|
├── info print version, Go version, module, VCS metadata
|
|
├── generate (gen)
|
|
│ ├── random [seedstr] stream pseudorandom bytes (--count N to stop)
|
|
│ ├── password (pw) print a memorable password
|
|
│ └── mnemonic print a new BIP39 mnemonic (--words N)
|
|
└── cbk
|
|
└── derive keypair from a mnemonic on stdin (--public)
|
|
```
|
|
|
|
### Build, test, and CI
|
|
|
|
The `Makefile` is the single entry point: `make test` (30-second timeout, quiet
|
|
unless something fails), `make lint`, `make fmt` and `make fmt-check` (gofmt for
|
|
Go, prettier for markdown), `make check` for all three, `make build`,
|
|
`make install`, `make docker`, `make hooks`, `make tidy`, and `make setup` to
|
|
install the pinned prettier.
|
|
|
|
`make lint` runs golangci-lint inside the same hash-pinned Docker image the CI
|
|
build uses, so local results match CI exactly. The `Dockerfile` splits
|
|
`make check` across stages: a lint stage and a markdown-check stage fail fast in
|
|
seconds, and the build stage, which runs the tests and compiles `sutil`, depends
|
|
on both. The runtime image carries the binary and the source it was built from.
|
|
Every external reference, from base images to the GitHub Action in
|
|
`.gitea/workflows/check.yml`, is pinned by content hash with a version and date
|
|
comment. `.golangci.yml` is the standard configuration and is never edited by
|
|
hand here. cgo stays off: the Makefile exports `CGO_ENABLED=0` for every build
|
|
and test, so binaries are static and no C toolchain is needed anywhere.
|
|
|
|
Version tags are created by the author alone, when the author decides. Tooling,
|
|
contributors, and agents working in this repository do not propose, schedule, or
|
|
create tags.
|
|
|
|
## Development
|
|
|
|
```sh
|
|
make setup # once: install the pinned prettier with yarn
|
|
make check # test + lint + fmt-check, exactly what CI gates on
|
|
make fmt # gofmt and prettier, writes files
|
|
make hooks # install the pre-commit hook that runs make check
|
|
make docker # the full CI build
|
|
```
|
|
|
|
## TODO
|
|
|
|
- [ ] Bump the pinned `golangci/golangci-lint` image (in `Makefile` and
|
|
`Dockerfile`) past v2.12.2 once the canonical `.golangci.yml` disables
|
|
`exhaustruct_v5`, which v2.13.0 added alongside the already-disabled
|
|
`exhaustruct`, and replaces the deprecated `gomodguard` with
|
|
`gomodguard_v2`. With `default: all`, newer images enable `exhaustruct_v5`
|
|
and fail every partial struct literal.
|
|
- [ ] Add `sutil cbk seal` and `sutil cbk open` so messages can be sealed and
|
|
opened from the shell, not just from Go.
|
|
- [ ] Let `sutil cbk derive` take the BIP39 passphrase from an environment
|
|
variable; the library supports it, the CLI does not expose it yet.
|
|
|
|
## License
|
|
|
|
WTFPL. See `LICENSE`.
|
|
|
|
## Author
|
|
|
|
[@sneak](https://sneak.berlin)
|
|
<[sneak@sneak.berlin](mailto:sneak@sneak.berlin)>
|