kavrix 0.1.4 → 0.2.0
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.
- package/README.md +111 -52
- package/dist/bin.js +17521 -5949
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/kavrix.cdx.json +26 -8
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,13 +1,24 @@
|
|
|
1
1
|
# kavrix
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
Kavrix is a zero-knowledge credential vault for the terminal. It encrypts
|
|
4
|
+
credential names and values on your machine and stores authenticated ciphertext
|
|
5
|
+
in a protected local database file or in your own MongoDB deployment. One
|
|
6
|
+
database holds multiple independently encrypted vaults, and no Kavrix server,
|
|
7
|
+
account, or telemetry exists anywhere in the path.
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
Tools consume credentials through tightly scoped execution: `kavrix run`
|
|
10
|
+
injects only the requested values into a child process environment, permission
|
|
11
|
+
policies and temporary grants bound what each executable may do, and
|
|
12
|
+
`kavrix agent run` brokers every request from AI coding agents against those
|
|
13
|
+
policies.
|
|
8
14
|
|
|
9
|
-
|
|
10
|
-
|
|
15
|
+
## Requirements
|
|
16
|
+
|
|
17
|
+
- Node.js `>=24.12.0 <25` or `>=25.1.0`
|
|
18
|
+
- MongoDB only if you select that datastore; database writes require a
|
|
19
|
+
transaction-capable replica set or sharded topology
|
|
20
|
+
|
|
21
|
+
## Installation
|
|
11
22
|
|
|
12
23
|
```sh
|
|
13
24
|
npm install --global kavrix
|
|
@@ -18,68 +29,116 @@ kavrix --help
|
|
|
18
29
|
## Quick start
|
|
19
30
|
|
|
20
31
|
```sh
|
|
32
|
+
# 1. Register and select a non-secret route to your datastore.
|
|
21
33
|
kavrix db profile add work --datastore file \
|
|
22
34
|
--data-file ./work.kavrix --key-file ./work.kavrix.key
|
|
23
35
|
kavrix db profile use work
|
|
36
|
+
|
|
37
|
+
# 2. Initialize the database and create a vault.
|
|
24
38
|
kavrix db init --profile work
|
|
25
39
|
kavrix db vault create --profile work
|
|
40
|
+
|
|
41
|
+
# 3. Copy the returned opaque vault ID into the flat commands.
|
|
26
42
|
kavrix put github/token --profile work --vault <vault-id>
|
|
27
|
-
kavrix get github/token --profile work --vault <vault-id>
|
|
43
|
+
kavrix get github/token --reveal --profile work --vault <vault-id>
|
|
28
44
|
```
|
|
29
45
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
##
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
46
|
+
Sensitive input is prompted for or read from stdin; it is never accepted as a
|
|
47
|
+
normal argument. Use `kavrix <command> --help` for the exact protected-input
|
|
48
|
+
options in your installed version.
|
|
49
|
+
|
|
50
|
+
## Command overview
|
|
51
|
+
|
|
52
|
+
| Group | Purpose |
|
|
53
|
+
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
|
54
|
+
| `db profile ...` | Manage non-secret datastore routes. |
|
|
55
|
+
| `db init`, `db status` | Initialize or authenticate a multi-vault database. |
|
|
56
|
+
| `db vault ...` | Create, list, inspect, or rename encrypted vaults. |
|
|
57
|
+
| `db key create` | Create an exact-snapshot key for full local-file sharing. |
|
|
58
|
+
| `db recovery ...` | Manage database-root recovery kits. |
|
|
59
|
+
| `migrate database` | Copy one legacy version 2 vault into a database. |
|
|
60
|
+
| `put`, `get`, `list`, `view`, `search`, `stats`, `has`, `rename`, `remove` | Store, read, and organize credentials. |
|
|
61
|
+
| `key status/verify/copy/replicate/assign/rewrap` | Manage protected key files. |
|
|
62
|
+
| `recovery create/verify/status/revoke/use` | Manage recovery kits. |
|
|
63
|
+
| `doctor`, `doctor health` | Validate a vault; repair bounded transient state safely. |
|
|
64
|
+
| `init`, `vault`, `legacy v2 commands` | Version 2 compatibility surface. |
|
|
65
|
+
| `run` | Execute one command with selected credentials injected as environment variables only. |
|
|
66
|
+
| `policy create/list/show/remove` | Stored rules: allowlists, SHA-256 pins, TTLs, deny, confirmations. |
|
|
67
|
+
| `grant create/list/revoke` | Temporary consumable authorizations with expiry and use caps. |
|
|
68
|
+
| `audit` | Plaintext-free security audit trail. |
|
|
69
|
+
| `agent run`, `agent exec` | Credential firewall that brokers AI coding agents. |
|
|
70
|
+
|
|
71
|
+
Plaintext output is always opt-in through `--reveal`; listing and dashboard
|
|
51
72
|
commands never display credential values.
|
|
52
73
|
|
|
53
|
-
##
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
74
|
+
## Running tools without pasting secrets
|
|
75
|
+
|
|
76
|
+
```sh
|
|
77
|
+
kavrix run --secret AWS_KEY=aws/deploy-key -- terraform plan
|
|
78
|
+
|
|
79
|
+
kavrix policy create deploy --secret aws/deploy-key \
|
|
80
|
+
--command terraform --hash terraform=<sha256> --ttl 30m
|
|
81
|
+
|
|
82
|
+
kavrix grant create aws/deploy-key --ttl 15m --max-uses 3
|
|
83
|
+
|
|
84
|
+
kavrix agent run
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Policies are evaluated fail-closed before any child process spawns, grants are
|
|
88
|
+
consumed atomically and can be revoked immediately, and `kavrix audit` records
|
|
89
|
+
policy, grant, authorization, and completion events without secret material.
|
|
90
|
+
|
|
91
|
+
## Options worth knowing
|
|
92
|
+
|
|
93
|
+
| Flag | What it does |
|
|
94
|
+
| ----------------------------------- | -------------------------------------------------------------------------- |
|
|
95
|
+
| `--profile`, `--profile-config-dir` | Select a datastore profile without storing secrets. |
|
|
96
|
+
| `--vault <id>` | Select one opaque vault explicitly. |
|
|
97
|
+
| `--passphrase-stdin` | Read the key passphrase from stdin. |
|
|
98
|
+
| `--database-url-stdin` | Read the MongoDB URI from stdin. |
|
|
99
|
+
| `--value-stdin` | Read a credential value from stdin. |
|
|
100
|
+
| `--secrets-stdin` | Read every unlock secret from exact stdin frames. |
|
|
101
|
+
| `--reveal` | The explicit guard that prints plaintext. |
|
|
102
|
+
| `--json` | Masked machine-readable output. |
|
|
103
|
+
| `--overwrite` | Opt in to replacing something that already exists. |
|
|
104
|
+
| `--allow-insecure-transport` | Explicit opt-in to unencrypted MongoDB transport (isolated networks only). |
|
|
105
|
+
|
|
106
|
+
## Security model
|
|
107
|
+
|
|
108
|
+
Vault payloads, the private database catalog, and wrapped keys use
|
|
109
|
+
XChaCha20-Poly1305 authenticated encryption. Protected key and recovery files
|
|
110
|
+
derive keys with Argon2id; HKDF-SHA-256 separates key purposes. Ciphertext is
|
|
111
|
+
bound to exact database/vault identity, purpose, versions, revision, and a
|
|
112
|
+
metadata digest, and a root-key-authenticated local revision anchor rejects
|
|
113
|
+
rollback, forks, and inconsistent heads before plaintext is returned.
|
|
114
|
+
|
|
115
|
+
MongoDB stores ciphertext plus opaque routing metadata in two collections; it
|
|
116
|
+
never receives passphrases, root keys, labels, or decrypted values. Remote URIs
|
|
117
|
+
must explicitly enable validated TLS.
|
|
118
|
+
|
|
119
|
+
## Limitations
|
|
120
|
+
|
|
121
|
+
- Kavrix cannot protect an unlocked machine from administrators, same-user
|
|
122
|
+
malware, keyloggers, terminal capture, or process-memory inspection, and an
|
|
123
|
+
authorized program can always read its own environment.
|
|
124
|
+
- Losing all valid owner keys and all database recovery kits makes the database
|
|
125
|
+
permanently unrecoverable by design; there is no reset or escrow.
|
|
126
|
+
- User identities, public enrollment, per-vault grants and roles, revocation
|
|
127
|
+
with rotation, ownership transfer, groups, structured items, and typed fields
|
|
128
|
+
are not yet implemented.
|
|
129
|
+
- Windows command scripts (`.bat`, `.cmd`, `.com`) are refused for execution;
|
|
130
|
+
invoke real executables.
|
|
131
|
+
|
|
132
|
+
For local sharing, create a fresh share key with `kavrix db key create` and
|
|
133
|
+
transfer it with its exact matching encrypted database file; deliver the
|
|
134
|
+
passphrase separately. The pair grants access to all vaults once unlocked.
|
|
77
135
|
|
|
78
136
|
## Documentation and support
|
|
79
137
|
|
|
80
138
|
- [Full README](https://github.com/d4rkNinja/kavrix#readme)
|
|
81
139
|
- [Command guide](https://github.com/d4rkNinja/kavrix/blob/main/docs/cli-reference.md)
|
|
82
140
|
- [Threat model](https://github.com/d4rkNinja/kavrix/blob/main/docs/threat-model.md)
|
|
141
|
+
- [Implementation status](https://github.com/d4rkNinja/kavrix/blob/main/docs/implementation-status.md)
|
|
83
142
|
- [Security reports](https://github.com/d4rkNinja/kavrix/blob/main/SECURITY.md)
|
|
84
143
|
- [Issue tracker](https://github.com/d4rkNinja/kavrix/issues)
|
|
85
144
|
|