From 0b3dcf08f2c8b28b0bdfab3eca20905ebdd3a93e Mon Sep 17 00:00:00 2001 From: Andy Dixon Date: Tue, 29 Sep 2026 15:04:28 +0100 Subject: [PATCH] Add man pages for vault and every command Co-Authored-By: Claude Sonnet 5.5 --- docs/vault-add.1 | 46 +++++++++++++++++++ docs/vault-genkey.1 | 32 +++++++++++++ docs/vault-get.1 | 32 +++++++++++++ docs/vault-init.1 | 27 +++++++++++ docs/vault-list.1 | 34 ++++++++++++++ docs/vault-migrate.1 | 41 +++++++++++++++++ docs/vault-mv.1 | 33 ++++++++++++++ docs/vault-rm.1 | 32 +++++++++++++ docs/vault.1 | 106 +++++++++++++++++++++++++++++++++++++++++++ 9 files changed, 383 insertions(+) create mode 100644 docs/vault-add.1 create mode 100644 docs/vault-genkey.1 create mode 100644 docs/vault-get.1 create mode 100644 docs/vault-init.1 create mode 100644 docs/vault-list.1 create mode 100644 docs/vault-migrate.1 create mode 100644 docs/vault-mv.1 create mode 100644 docs/vault-rm.1 create mode 100644 docs/vault.1 diff --git a/docs/vault-add.1 b/docs/vault-add.1 new file mode 100644 index 0000000..f89845a --- /dev/null +++ b/docs/vault-add.1 @@ -0,0 +1,46 @@ +.TH VAULT-ADD 1 "September 2026" "vault" "User Commands" +.SH NAME +vault-add \- encrypt files, directories or URLs into the vault +.SH SYNOPSIS +.B vault add +.RB [ \-\-key +.IR PATH ] +.RB [ \-\-vault +.IR DIR ] +.IR FILE | DIR | URL +.RI [ FOLDER ] +.SH DESCRIPTION +Encrypts a file into the vault, named after its base name. A directory is +added recursively, keeping its structure beneath its own name; a directory +named "." or ".." adds its contents directly. Non-regular files, the vault +and the key are skipped. A stored name that already exists is replaced. +.PP +An \fBhttp://\fR or \fBhttps://\fR \fIURL\fR is downloaded with a Chrome user +agent and stored under the last element of its final (post-redirect) path, or +the host name if there is none. Only a 200 response is accepted. +.PP +\fIFOLDER\fR places the result inside a folder in the vault. File contents +are cut into 4 MiB chunks, the last bucket-padded. +.SH OPTIONS +.TP +.BI \-\-key " PATH" +Key file. Default: $VAULT_KEY, else ~/.vault/key. +.TP +.BI \-\-vault " DIR" +Vault directory. Default: $VAULT_DIR, else ~/.vault/store. +.SH ENVIRONMENT +.TP +.B VAULT_PASSPHRASE +Passphrase, instead of prompting on the terminal. +.SH EXAMPLES +.nf +vault add report.pdf work/2026 +vault add ./photos +vault add https://example.com/paper.pdf papers +.fi +.SH SEE ALSO +.BR vault (1), +.BR vault\-migrate (1), +.BR vault\-mirror (1) +.SH AUTHOR +Andy Dixon , https://www.dixon.cx diff --git a/docs/vault-genkey.1 b/docs/vault-genkey.1 new file mode 100644 index 0000000..a06fcc7 --- /dev/null +++ b/docs/vault-genkey.1 @@ -0,0 +1,32 @@ +.TH VAULT-GENKEY 1 "September 2026" "vault" "User Commands" +.SH NAME +vault-genkey \- create a new vault key +.SH SYNOPSIS +.B vault genkey +.RB [ \-\-key +.IR PATH ] +.SH DESCRIPTION +Creates the key file, prompting twice for a passphrase, then for an optional +decoy passphrase (empty for none). Both passphrase slots are sealed with +Argon2id and XChaCha20-Poly1305, are the same size, and are stored in random +order; the second holds either a decoy identity or random bytes. It refuses to +overwrite an existing file. No seed or private key is ever written unencrypted. +.PP +When \fBVAULT_PASSPHRASE\fR is set, no prompts are made and the decoy comes +from \fBVAULT_DECOY_PASSPHRASE\fR, or is omitted. +.SH OPTIONS +.TP +.BI \-\-key " PATH" +Where to write the key. Default: $VAULT_KEY, else ~/.vault/key. +.SH ENVIRONMENT +.TP +.B VAULT_PASSPHRASE +Passphrase, instead of prompting on the terminal. +.TP +.B VAULT_DECOY_PASSPHRASE +Decoy passphrase; must differ from the passphrase. +.SH SEE ALSO +.BR vault (1), +.BR vault\-init (1) +.SH AUTHOR +Andy Dixon , https://www.dixon.cx diff --git a/docs/vault-get.1 b/docs/vault-get.1 new file mode 100644 index 0000000..cd27c1a --- /dev/null +++ b/docs/vault-get.1 @@ -0,0 +1,32 @@ +.TH VAULT-GET 1 "September 2026" "vault" "User Commands" +.SH NAME +vault-get \- decrypt a stored file +.SH SYNOPSIS +.B vault get +.RB [ \-o +.IR OUTPUT ] +.RB [ \-\-key +.IR PATH ] +.RB [ \-\-vault +.IR DIR ] +.I NAME +.SH DESCRIPTION +Decrypts \fINAME\fR. Nothing appears at the output path until every object has +authenticated. The stored mode and modification time are restored. It refuses +to overwrite an existing file. Takes a shared lock. +.SH OPTIONS +.TP +.BI \-o " OUTPUT" +Output path. Default: the base name of \fINAME\fR in the current directory. +.PP +See also \fB\-\-key\fR and \fB\-\-vault\fR in +.BR vault (1). +.SH ENVIRONMENT +.TP +.B VAULT_PASSPHRASE +Passphrase, instead of prompting on the terminal. +.SH SEE ALSO +.BR vault (1), +.BR vault\-list (1) +.SH AUTHOR +Andy Dixon , https://www.dixon.cx diff --git a/docs/vault-init.1 b/docs/vault-init.1 new file mode 100644 index 0000000..8ec2588 --- /dev/null +++ b/docs/vault-init.1 @@ -0,0 +1,27 @@ +.TH VAULT-INIT 1 "September 2026" "vault" "User Commands" +.SH NAME +vault-init \- create an empty vault +.SH SYNOPSIS +.B vault init +.RB [ \-\-vault +.IR DIR ] +.RB [ \-\-filler +.IR SIZE ] +.SH DESCRIPTION +Creates the vault directory, with \fBrecords/\fR and \fBobjects/\fR each +sharded into 256 subdirectories. It writes at least \fISIZE\fR bytes of +unreadable filler so that real files cannot be told apart from it by anyone +lacking the right passphrase. Filler is always written, even when \fISIZE\fR is 0. +.SH OPTIONS +.TP +.BI \-\-vault " DIR" +Vault directory. Default: $VAULT_DIR, else ~/.vault/store. +.TP +.BI \-\-filler " SIZE" +Minimum filler, in bytes, with an optional K, M, G or T suffix (powers of +1024), e.g. 500M or 2G. Default: 0. +.SH SEE ALSO +.BR vault (1), +.BR vault\-genkey (1) +.SH AUTHOR +Andy Dixon , https://www.dixon.cx diff --git a/docs/vault-list.1 b/docs/vault-list.1 new file mode 100644 index 0000000..3e757c2 --- /dev/null +++ b/docs/vault-list.1 @@ -0,0 +1,34 @@ +.TH VAULT-LIST 1 "September 2026" "vault" "User Commands" +.SH NAME +vault-list \- list files in the vault +.SH SYNOPSIS +.B vault list +.RB [ \-\-key +.IR PATH ] +.RB [ \-\-vault +.IR DIR ] +.RI [ PREFIX ] +.br +.B vault ls +\&... +.SH DESCRIPTION +Prints one line per stored file, sorted by name: human-readable size, +modification time (local, minute resolution) and name. With \fIPREFIX\fR only +that file, or files under that folder, are shown. Records the passphrase +cannot open are skipped silently. Takes a shared lock. +.SH OPTIONS +.TP +.BI \-\-key " PATH" +Key file. Default: $VAULT_KEY, else ~/.vault/key. +.TP +.BI \-\-vault " DIR" +Vault directory. Default: $VAULT_DIR, else ~/.vault/store. +.SH ENVIRONMENT +.TP +.B VAULT_PASSPHRASE +Passphrase, instead of prompting on the terminal. +.SH SEE ALSO +.BR vault (1), +.BR vault\-get (1) +.SH AUTHOR +Andy Dixon , https://www.dixon.cx diff --git a/docs/vault-migrate.1 b/docs/vault-migrate.1 new file mode 100644 index 0000000..9b9cc04 --- /dev/null +++ b/docs/vault-migrate.1 @@ -0,0 +1,41 @@ +.TH VAULT-MIGRATE 1 "September 2026" "vault" "User Commands" +.SH NAME +vault-migrate \- move files into the vault, deleting the originals +.SH SYNOPSIS +.B vault migrate +.RB [ \-\-yes ] +.RB [ \-\-key +.IR PATH ] +.RB [ \-\-vault +.IR DIR ] +.IR FILE | DIR +.RI [ FOLDER ] +.SH DESCRIPTION +Works like +.BR vault\-add (1) +but deletes each original once it is stored, then any directories left empty. +Directories still holding skipped files stay. A URL cannot be migrated. +.PP +Before storing anything it lists the vault names that would be overwritten and +asks for confirmation on the terminal. With no terminal the answer is no, and +nothing changes. +.SH OPTIONS +.TP +.B \-\-yes +Overwrite without asking. +.SH OPTIONS +.TP +.BI \-\-key " PATH" +Key file. Default: $VAULT_KEY, else ~/.vault/key. +.TP +.BI \-\-vault " DIR" +Vault directory. Default: $VAULT_DIR, else ~/.vault/store. +.SH ENVIRONMENT +.TP +.B VAULT_PASSPHRASE +Passphrase, instead of prompting on the terminal. +.SH SEE ALSO +.BR vault (1), +.BR vault\-add (1) +.SH AUTHOR +Andy Dixon , https://www.dixon.cx diff --git a/docs/vault-mv.1 b/docs/vault-mv.1 new file mode 100644 index 0000000..ed43c22 --- /dev/null +++ b/docs/vault-mv.1 @@ -0,0 +1,33 @@ +.TH VAULT-MV 1 "September 2026" "vault" "User Commands" +.SH NAME +vault-mv \- rename a stored file +.SH SYNOPSIS +.B vault mv +.RB [ \-\-key +.IR PATH ] +.RB [ \-\-vault +.IR DIR ] +.I OLD NEW +.br +.B vault rename +\&... +.SH DESCRIPTION +Renames \fIOLD\fR to \fINEW\fR, which may be in another folder. Fails if +\fINEW\fR exists or is not a valid vault path. File contents are not +re-encrypted. +.SH OPTIONS +.TP +.BI \-\-key " PATH" +Key file. Default: $VAULT_KEY, else ~/.vault/key. +.TP +.BI \-\-vault " DIR" +Vault directory. Default: $VAULT_DIR, else ~/.vault/store. +.SH ENVIRONMENT +.TP +.B VAULT_PASSPHRASE +Passphrase, instead of prompting on the terminal. +.SH SEE ALSO +.BR vault (1), +.BR vault\-rm (1) +.SH AUTHOR +Andy Dixon , https://www.dixon.cx diff --git a/docs/vault-rm.1 b/docs/vault-rm.1 new file mode 100644 index 0000000..50779d7 --- /dev/null +++ b/docs/vault-rm.1 @@ -0,0 +1,32 @@ +.TH VAULT-RM 1 "September 2026" "vault" "User Commands" +.SH NAME +vault-rm \- delete a stored file +.SH SYNOPSIS +.B vault rm +.RB [ \-\-key +.IR PATH ] +.RB [ \-\-vault +.IR DIR ] +.I NAME +.br +.B vault delete +\&... +.SH DESCRIPTION +Deletes the stored file \fINAME\fR from the vault. It does not ask for +confirmation. +.SH OPTIONS +.TP +.BI \-\-key " PATH" +Key file. Default: $VAULT_KEY, else ~/.vault/key. +.TP +.BI \-\-vault " DIR" +Vault directory. Default: $VAULT_DIR, else ~/.vault/store. +.SH ENVIRONMENT +.TP +.B VAULT_PASSPHRASE +Passphrase, instead of prompting on the terminal. +.SH SEE ALSO +.BR vault (1), +.BR vault\-list (1) +.SH AUTHOR +Andy Dixon , https://www.dixon.cx diff --git a/docs/vault.1 b/docs/vault.1 new file mode 100644 index 0000000..439903f --- /dev/null +++ b/docs/vault.1 @@ -0,0 +1,106 @@ +.TH VAULT 1 "September 2026" "vault" "User Commands" +.SH NAME +vault \- post-quantum encrypted file vault +.SH SYNOPSIS +.B vault +.I command +.RI [ options ] +.RI [ arguments ] +.SH DESCRIPTION +.B vault +stores files in a directory of encrypted, fixed-size records and chunks. +Encryption is a hybrid of FrodoKEM-640 and ML-KEM-768 with ChaCha20-Poly1305. +The key file is protected by an Argon2id-derived passphrase key. +File names, sizes and contents are only visible to a holder of the key and +passphrase. Ciphertext sizes and timestamps are normalised to hide +metadata from the storage host. +.PP +Options may appear before, between or after the arguments. +.SH COMMANDS +.TP +.BR vault\-genkey (1) +Create a new passphrase-protected key file. +.TP +.BR vault\-init (1) +Create a new, empty vault. +.TP +.BR vault\-add (1) +Encrypt a file, directory or downloaded URL into the vault. +.TP +.BR vault\-migrate (1) +Like add, then delete each original. +.TP +.BR vault\-mirror (1) +Crawl a website into the vault. +.TP +.BR vault\-list (1) +List stored files (alias: +.BR ls ). +.TP +.BR vault\-get (1) +Decrypt a stored file. +.TP +.BR vault\-mv (1) +Rename a stored file (alias: +.BR rename ). +.TP +.BR vault\-rm (1) +Delete a stored file (alias: +.BR delete ). +.TP +.B help +Print usage. +.SH OPTIONS +These apply to every command. +.TP +.BI \-\-key " PATH" +Key file. Default: $VAULT_KEY, else ~/.vault/key. +.TP +.BI \-\-vault " DIR" +Vault directory. Default: $VAULT_DIR, else ~/.vault/store. +.SH ENVIRONMENT +.TP +.B VAULT_KEY +Default key file. +.TP +.B VAULT_DIR +Default vault directory. +.TP +.B VAULT_PASSPHRASE +Passphrase, instead of prompting on the terminal. +.TP +.B VAULT_DECOY_PASSPHRASE +Decoy passphrase used by +.BR "vault genkey" . +.SH LOCKING +Commands that change the vault hold an exclusive lock on +.IR DIR/.lock ; +readers hold a shared lock. The lock is taken after the passphrase prompt. +.SH DECOY PASSPHRASE +.B genkey +can add a second passphrase. It unlocks a separate identity, so every +command run with it sees and changes only the decoy files, and the real +files stay invisible. The key file does not reveal whether a decoy exists, +and +.B init +fills each vault with unreadable filler, so hidden files look like filler to +anyone holding only the decoy passphrase. +.SH EXIT STATUS +0 on success; 1 on error (diagnostics on standard error); 2 when run with no command. +.SH EXAMPLES +.nf +vault genkey +vault init \-\-filler 500M +vault add report.pdf work/2026 +vault list work +vault get work/2026/report.pdf \-o /tmp/report.pdf +.fi +.SH FILES +.TP +.I ~/.vault/key +Default key file. +.TP +.I ~/.vault/store +Default vault directory. +.SH AUTHOR +Andy Dixon , https://www.dixon.cx