kavrix 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +79 -121
  2. package/dist/bin.js +11561 -3496
  3. package/dist/index.d.ts +1 -1
  4. package/dist/index.js +1 -1
  5. package/dist/kavrix.cdx.json +8 -8
  6. package/package.json +2 -2
package/README.md CHANGED
@@ -1,136 +1,94 @@
1
- # Kavrix CLI
1
+ # kavrix
2
2
 
3
- Kavrix is a local encrypted credential vault for MongoDB. It encrypts values
4
- before they leave your computer and connects directly to MongoDB. You do not
5
- run a Kavrix server, HTTP API, sync daemon, or self-hosting process.
3
+ A local, zero-knowledge credential vault that stores multiple independently
4
+ encrypted vaults in a protected local database file or MongoDB. Kavrix encrypts
5
+ private labels and values before storage; it does not require a Kavrix server.
6
6
 
7
7
  ## Install
8
8
 
9
- ```sh
10
- npm install --global kavrix
11
- ```
12
-
13
- Supported Node.js versions:
14
-
15
- ```
16
- >=24.12.0 <25 || >=25.1.0
17
- ```
18
-
19
- ## First vault
20
-
21
- Run these commands in order:
9
+ Requires Node.js `>=24.12.0 <25` or `>=25.1.0`. MongoDB is optional; database
10
+ writes require a transaction-capable replica set or sharded topology.
22
11
 
23
12
  ```sh
24
- kavrix db ping --database kavrix_local
25
- kavrix init --database kavrix_local --key-file ./kavrix.key
26
- kavrix put production/api-token --database kavrix_local --key-file ./kavrix.key
27
- kavrix list --database kavrix_local --key-file ./kavrix.key
28
- kavrix get production/api-token --database kavrix_local --key-file ./kavrix.key
13
+ npm install --global kavrix
14
+ kavrix --version
15
+ kavrix --help
29
16
  ```
30
17
 
31
- Kavrix asks for the MongoDB URI, key-file passphrase, and credential value
32
- through protected input. It never accepts those secrets as ordinary command
33
- arguments. `get` stays masked unless you explicitly add
34
- `--reveal`.
35
-
36
- Create and verify a recovery kit immediately after initialization:
18
+ ## Quick start
37
19
 
38
20
  ```sh
39
- kavrix recovery create \
40
- --vault default \
41
- --key-file ./kavrix.key \
42
- --recovery-file ./kavrix.recovery.kit
43
-
44
- kavrix recovery verify \
45
- --vault default \
46
- --key-file ./kavrix.key \
47
- --recovery-file ./kavrix.recovery.kit
21
+ kavrix db profile add work --datastore file \
22
+ --data-file ./work.kavrix --key-file ./work.kavrix.key
23
+ kavrix db profile use work
24
+ kavrix db init --profile work
25
+ kavrix db vault create --profile work
26
+ kavrix put github/token --profile work --vault <vault-id>
27
+ kavrix get github/token --profile work --vault <vault-id>
48
28
  ```
49
29
 
50
- Store the key file and recovery kit separately. They are protected files, not
51
- plain text codes. Losing every authorized unlock method is unrecoverable by
52
- design.
53
-
54
- ## Commands people use most
55
-
56
- | Task | Command |
57
- | ------------------------------------- | ------------------------------------------- |
58
- | Readable dashboard | `kavrix view` |
59
- | One credential card | `kavrix view <name>` |
60
- | Search names only | `kavrix search <pattern>` |
61
- | Counts and safe statistics | `kavrix stats` |
62
- | Add or replace a value | `kavrix put <name> [--overwrite]` |
63
- | Read a value | `kavrix get <name> [--reveal]` |
64
- | Rename a record | `kavrix rename <from> <to>` |
65
- | Delete a record | `kavrix remove <name>` |
66
- | Validate encrypted data | `kavrix doctor` |
67
- | Check and repair safe transient state | `kavrix doctor health` |
68
- | Inspect vaults | `kavrix vault list` / `kavrix vault status` |
69
-
70
- ## Key and recovery lifecycle
71
-
72
- | Task | Command |
73
- | ------------------------------------- | -------------------------------------------- |
74
- | Inspect a key file | `kavrix key status` |
75
- | Verify a key file | `kavrix key verify` |
76
- | Create another key-file copy | `kavrix key copy` |
77
- | Same copy operation, explicit aliases | `kavrix key replicate` / `kavrix key assign` |
78
- | Change a key-file passphrase | `kavrix key rewrap` |
79
- | Create a recovery kit | `kavrix recovery create` |
80
- | Verify a recovery kit | `kavrix recovery verify` |
81
- | List recovery-slot state | `kavrix recovery status` |
82
- | Revoke a recovery slot | `kavrix recovery revoke <slotId>` |
83
- | Replace a lost key with recovery | `kavrix recovery use` |
84
-
85
- Key-file copies share the same vault binding and are not independently
86
- revocable. Recovery use requires the trusted local revision anchor and creates
87
- a new protected destination; it does not silently overwrite an existing file.
30
+ Commands prompt for sensitive input. Do not place secrets or MongoDB credentials
31
+ in normal command arguments or shell history. Use `kavrix <command> --help` for
32
+ the exact protected-input options available in this version.
33
+
34
+ ## Main command groups
35
+
36
+ - `db profile`: manage protected non-secret datastore routes.
37
+ - `db init`, `db status`: initialize or authenticate a multi-vault database.
38
+ - `db vault`: create, list, inspect, or rename independently encrypted vaults.
39
+ - `db recovery`: manage database-root recovery kits.
40
+ - `migrate database`: explicitly copy a legacy version 2 vault into a database.
41
+ - `db ping`: test direct MongoDB connectivity.
42
+ - `init`, `vault`, `key`, `recovery`, `doctor`: version 2 compatibility commands.
43
+ - `put`, `get`, `list`, `view`, `search`, `stats`: manage encrypted values.
44
+ - `has`, `rename`, `remove`: inspect or change records without accidental reveal.
45
+ - `vault list`, `vault status`: select and inspect vaults.
46
+ - `key status|verify|copy|replicate|assign|rewrap`: manage protected key files.
47
+ - `recovery create|verify|revoke|status|use`: manage protected recovery kits.
48
+ - `doctor`, `doctor health`: authenticate, diagnose, and perform bounded safe repair.
49
+
50
+ Plaintext output is opt-in. `get` requires `--reveal`; listing and dashboard
51
+ commands never display credential values.
88
52
 
89
53
  ## Security boundary
90
54
 
91
- MongoDB receives encrypted envelopes, wrapped key-slot metadata, and unavoidable
92
- operational metadata. It does not receive plaintext credential values,
93
- passphrases, portable keys, recovery keys, or decrypted records.
94
-
95
- Kavrix uses versioned authenticated encryption, independent key slots, strict
96
- input schemas, protected key-file permissions, and fail-closed validation.
97
- Tampering, wrong bindings, malformed data, missing keys, and unsafe rollback
98
- states do not produce plaintext.
99
-
100
- The local process and host remain part of the trust boundary. A process running
101
- as the already-unlocked user can read plaintext in memory, and terminal
102
- software, clipboard managers, swap, backups, or crash dumps may retain data.
103
- Kavrix protects the database boundary; it cannot protect a compromised computer.
104
-
105
- ## Safe input and output
106
-
107
- - Use masked prompts, protected files, or explicit stdin for secrets.
108
- - Use `--database-url-stdin`, `--passphrase-stdin`, and `--value-stdin` for controlled automation.
109
- - Never put secrets in command arguments, URLs, environment files, or logs.
110
- - Plaintext is masked unless `--reveal` is explicitly requested.
111
- - Keep key files and recovery kits outside the database backup path when possible.
112
- - Use TLS with certificate and hostname verification for remote MongoDB.
113
-
114
- Run the full command help whenever you need option details:
115
-
116
- ```sh
117
- kavrix --help
118
- kavrix <command> --help
119
- ```
120
-
121
- For the complete practical guide, see
122
- [../../docs/cli-reference.md](../../docs/cli-reference.md) in the source
123
- repository. For the public product guide, see the repository
124
- [README](../../README.md).
125
-
126
- ## License and attribution
127
-
128
- Kavrix is released under the MIT license. The package includes attribution for
129
- the [EFF Short Wordlist for Passphrases #1](https://www.eff.org/files/2016/09/08/eff_short_wordlist_1.txt)
130
- under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/).
131
-
132
- ## Zero-knowledge boundary
133
-
134
- Kavrix uses a zero-knowledge storage boundary: MongoDB receives encrypted
135
- credential envelopes and wrapped key metadata, but not plaintext values,
136
- passphrases, portable keys, or recovery keys.
55
+ Vault payloads and the private database catalog use XChaCha20-Poly1305
56
+ authenticated encryption. Protected key and recovery files use Argon2id-derived
57
+ keys and XChaCha20-Poly1305; HKDF-SHA-256 separates database, catalog, anchor,
58
+ and vault wrapping purposes. Ciphertext is bound to exact database/vault identity,
59
+ purpose, versions, revision, and metadata digest. Kavrix does not claim
60
+ permanently unbreakable encryption.
61
+
62
+ A DRK-authenticated local revision anchor detects database rollback,
63
+ same-revision forks, and inconsistent catalog/vault heads. Normal database
64
+ unlock fails closed if that anchor is missing or inconsistent.
65
+
66
+ MongoDB stores two collections of ciphertext plus visible opaque routing
67
+ metadata; it never receives passphrases, DRKs, VRKs, labels, or decrypted values.
68
+ Remote URIs must explicitly enable validated TLS. Kavrix cannot protect an unlocked machine from local
69
+ administrators, same-user malware, keyloggers, terminal capture, or process-memory
70
+ inspection. For local sharing, create a fresh share key with `kavrix db key create`
71
+ and transfer it with its exact matching encrypted database snapshot. Deliver the
72
+ passphrase separately; the pair grants access to all vaults. User identities,
73
+ grants, roles, revocation, ownership
74
+ transfer, environments, groups, structured items, and typed fields are not yet
75
+ implemented. Losing all valid owner keys and database recovery kits makes the
76
+ database unrecoverable by design.
77
+
78
+ ## Documentation and support
79
+
80
+ - [Full README](https://github.com/d4rkNinja/kavrix#readme)
81
+ - [Command guide](https://github.com/d4rkNinja/kavrix/blob/main/docs/cli-reference.md)
82
+ - [Threat model](https://github.com/d4rkNinja/kavrix/blob/main/docs/threat-model.md)
83
+ - [Security reports](https://github.com/d4rkNinja/kavrix/blob/main/SECURITY.md)
84
+ - [Issue tracker](https://github.com/d4rkNinja/kavrix/issues)
85
+
86
+ ## Word-list attribution
87
+
88
+ Generated passphrases use **EFF Short Wordlist for Passphrases #1**, from
89
+ https://www.eff.org/files/2016/09/08/eff_short_wordlist_1.txt, licensed under
90
+ CC BY 4.0: https://creativecommons.org/licenses/by/4.0/.
91
+
92
+ ## License
93
+
94
+ MIT