kavrix 0.1.0 → 0.1.2

package/README.md

@@ -1,136 +1,80 @@
-# Kavrix CLI
+# kavrix
 
-Kavrix is a local encrypted credential vault for MongoDB. It encrypts values
-before they leave your computer and connects directly to MongoDB. You do not
-run a Kavrix server, HTTP API, sync daemon, or self-hosting process.
+A local, zero-knowledge credential vault backed directly by MongoDB. Kavrix
+encrypts values before storage; it does not require or start a Kavrix server.
 
 ## Install
 
+Requires Node.js `>=24.12.0 <25` or `>=25.1.0` and a reachable MongoDB deployment.
+
 ```sh
 npm install --global kavrix
+kavrix --version
+kavrix --help
 ```
 
-Supported Node.js versions:
-
-```
->=24.12.0 <25 || >=25.1.0
-```
-
-## First vault
-
-Run these commands in order:
+## Quick start
 
 ```sh
-kavrix db ping --database kavrix_local
-kavrix init --database kavrix_local --key-file ./kavrix.key
-kavrix put production/api-token --database kavrix_local --key-file ./kavrix.key
-kavrix list --database kavrix_local --key-file ./kavrix.key
-kavrix get production/api-token --database kavrix_local --key-file ./kavrix.key
+kavrix db ping
+kavrix init
+kavrix put github/token
+kavrix list
+kavrix view
+kavrix get github/token --reveal
 ```
 
-Kavrix asks for the MongoDB URI, key-file passphrase, and credential value
-through protected input. It never accepts those secrets as ordinary command
-arguments. `get` stays masked unless you explicitly add
-`--reveal`.
+Commands prompt for sensitive input. Do not place secrets or MongoDB credentials
+in normal command arguments or shell history. Use `kavrix <command> --help` for
+the exact protected-input options available in this version.
 
-Create and verify a recovery kit immediately after initialization:
+## Main command groups
 
-```sh
-kavrix recovery create \
-  --vault default \
-  --key-file ./kavrix.key \
-  --recovery-file ./kavrix.recovery.kit
-
-kavrix recovery verify \
-  --vault default \
-  --key-file ./kavrix.key \
-  --recovery-file ./kavrix.recovery.kit
-```
+- `db ping`: test direct MongoDB connectivity.
+- `init`: create a vault and passphrase-protected portable key file.
+- `put`, `get`, `list`, `view`, `search`, `stats`: manage encrypted values.
+- `has`, `rename`, `remove`: inspect or change records without accidental reveal.
+- `vault list`, `vault status`: select and inspect vaults.
+- `key status|verify|copy|replicate|assign|rewrap`: manage protected key files.
+- `recovery create|verify|revoke|status|use`: manage protected recovery kits.
+- `doctor`, `doctor health`: authenticate, diagnose, and perform bounded safe repair.
 
-Store the key file and recovery kit separately. They are protected files, not
-plain text codes. Losing every authorized unlock method is unrecoverable by
-design.
-
-## Commands people use most
-
-| Task                                  | Command                                     |
-| ------------------------------------- | ------------------------------------------- |
-| Readable dashboard                    | `kavrix view`                               |
-| One credential card                   | `kavrix view <name>`                        |
-| Search names only                     | `kavrix search <pattern>`                   |
-| Counts and safe statistics            | `kavrix stats`                              |
-| Add or replace a value                | `kavrix put <name> [--overwrite]`           |
-| Read a value                          | `kavrix get <name> [--reveal]`              |
-| Rename a record                       | `kavrix rename <from> <to>`                 |
-| Delete a record                       | `kavrix remove <name>`                      |
-| Validate encrypted data               | `kavrix doctor`                             |
-| Check and repair safe transient state | `kavrix doctor health`                      |
-| Inspect vaults                        | `kavrix vault list` / `kavrix vault status` |
-
-## Key and recovery lifecycle
-
-| Task                                  | Command                                      |
-| ------------------------------------- | -------------------------------------------- |
-| Inspect a key file                    | `kavrix key status`                          |
-| Verify a key file                     | `kavrix key verify`                          |
-| Create another key-file copy          | `kavrix key copy`                            |
-| Same copy operation, explicit aliases | `kavrix key replicate` / `kavrix key assign` |
-| Change a key-file passphrase          | `kavrix key rewrap`                          |
-| Create a recovery kit                 | `kavrix recovery create`                     |
-| Verify a recovery kit                 | `kavrix recovery verify`                     |
-| List recovery-slot state              | `kavrix recovery status`                     |
-| Revoke a recovery slot                | `kavrix recovery revoke <slotId>`            |
-| Replace a lost key with recovery      | `kavrix recovery use`                        |
-
-Key-file copies share the same vault binding and are not independently
-revocable. Recovery use requires the trusted local revision anchor and creates
-a new protected destination; it does not silently overwrite an existing file.
+Plaintext output is opt-in. `get` requires `--reveal`; listing and dashboard
+commands never display credential values.
 
 ## Security boundary
 
-MongoDB receives encrypted envelopes, wrapped key-slot metadata, and unavoidable
-operational metadata. It does not receive plaintext credential values,
-passphrases, portable keys, recovery keys, or decrypted records.
-
-Kavrix uses versioned authenticated encryption, independent key slots, strict
-input schemas, protected key-file permissions, and fail-closed validation.
-Tampering, wrong bindings, malformed data, missing keys, and unsafe rollback
-states do not produce plaintext.
-
-The local process and host remain part of the trust boundary. A process running
-as the already-unlocked user can read plaintext in memory, and terminal
-software, clipboard managers, swap, backups, or crash dumps may retain data.
-Kavrix protects the database boundary; it cannot protect a compromised computer.
-
-## Safe input and output
+Vault payloads use XChaCha20-Poly1305 authenticated encryption. Protected key and
+recovery files use Argon2id-derived keys and XChaCha20-Poly1305. Ciphertext is
+bound to vault identity, schema/key version, revision, and security metadata.
+MongoDB stores ciphertext plus visible operational metadata; it never receives
+the portable key, recovery key, passphrase, root key, or decrypted value.
 
-- Use masked prompts, protected files, or explicit stdin for secrets.
-- Use `--database-url-stdin`, `--passphrase-stdin`, and `--value-stdin` for controlled automation.
-- Never put secrets in command arguments, URLs, environment files, or logs.
-- Plaintext is masked unless `--reveal` is explicitly requested.
-- Keep key files and recovery kits outside the database backup path when possible.
-- Use TLS with certificate and hostname verification for remote MongoDB.
+A protected local revision anchor detects older database snapshots and
+same-revision metadata forks. Normal unlock fails closed if the anchor is
+missing or inconsistent. `doctor health --accept-current` is an explicit trust
+decision, not an automatic recovery shortcut.
 
-Run the full command help whenever you need option details:
+Remote MongoDB URIs must explicitly enable validated TLS. Kavrix rejects insecure
+TLS options. It cannot protect an already-unlocked machine from local
+administrators, same-user malware, keyloggers, terminal capture, or process-memory
+inspection. Losing all valid key files and recovery kits makes the vault
+unrecoverable by design.
 
-```sh
-kavrix --help
-kavrix <command> --help
-```
+## Documentation and support
 
-For the complete practical guide, see
-[../../docs/cli-reference.md](../../docs/cli-reference.md) in the source
-repository. For the public product guide, see the repository
-[README](../../README.md).
+- [Full README](https://github.com/d4rkNinja/kavrix#readme)
+- [Command guide](https://github.com/d4rkNinja/kavrix/blob/main/docs/cli-reference.md)
+- [Threat model](https://github.com/d4rkNinja/kavrix/blob/main/docs/threat-model.md)
+- [Security reports](https://github.com/d4rkNinja/kavrix/blob/main/SECURITY.md)
+- [Issue tracker](https://github.com/d4rkNinja/kavrix/issues)
 
-## License and attribution
+## Word-list attribution
 
-Kavrix is released under the MIT license. The package includes attribution for
-the [EFF Short Wordlist for Passphrases #1](https://www.eff.org/files/2016/09/08/eff_short_wordlist_1.txt)
-under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/).
+Generated passphrases use **EFF Short Wordlist for Passphrases #1**, from
+https://www.eff.org/files/2016/09/08/eff_short_wordlist_1.txt, licensed under
+CC BY 4.0: https://creativecommons.org/licenses/by/4.0/.
 
-## Zero-knowledge boundary
+## License
 
-Kavrix uses a zero-knowledge storage boundary: MongoDB receives encrypted
-credential envelopes and wrapped key metadata, but not plaintext values,
-passphrases, portable keys, or recovery keys.
+MIT

package/dist/index.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION: "0.1.0";
+export declare const CLI_VERSION: "0.1.2";

package/dist/index.js

@@ -1 +1 @@
-export const CLI_VERSION = "0.1.0";
+export const CLI_VERSION = "0.1.2";

package/dist/kavrix.cdx.json

@@ -2,14 +2,14 @@
   "$schema": "https://cyclonedx.org/schema/bom-1.6.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.6",
-  "serialNumber": "urn:uuid:a4b75e7c-54aa-5d05-96d9-6fb74fec7a15",
+  "serialNumber": "urn:uuid:94180fb5-4ac3-50b4-80f2-79b105dcd363",
   "version": 1,
   "metadata": {
     "component": {
       "type": "application",
-      "bom-ref": "pkg:npm/kavrix@0.1.0",
+      "bom-ref": "pkg:npm/kavrix@0.1.2",
       "name": "kavrix",
-      "version": "0.1.0",
+      "version": "0.1.2",
       "licenses": [
         {
           "license": {
@@ -17,11 +17,11 @@
           }
         }
       ],
-      "purl": "pkg:npm/kavrix@0.1.0",
+      "purl": "pkg:npm/kavrix@0.1.2",
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "dd5f9d96102cbfb5f3728ee8607785343cf4747552ffb7b2c2ca388ea9c08b6d"
+          "content": "3d3da15ec6e0ac5da3d9c57ee4e022d893419a7643735111663c75a902e7f5ac"
         }
       ],
       "properties": [
@@ -31,7 +31,7 @@
         },
         {
           "name": "kavrix:artifact-sha256:dist/index.js",
-          "value": "eae7d988ab6907e7bebd6d849d08e4c8eba026addd7d7d79c3151dfb9ef9854a"
+          "value": "1c3d7ecb3a9e13c00a0f7225a8f13e2628c2bf17dca01c507b6b36023365c6aa"
         }
       ]
     }
@@ -289,7 +289,7 @@
   ],
   "dependencies": [
     {
-      "ref": "pkg:npm/kavrix@0.1.0",
+      "ref": "pkg:npm/kavrix@0.1.2",
       "dependsOn": [
         "pkg:npm/mongodb@7.5.0",
         "urn:kavrix:data:eff-short-wordlist-for-passphrases-1"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kavrix",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Zero-knowledge credential vault command-line interface",
   "license": "MIT",
   "repository": {
@@ -46,16 +46,15 @@
   "engines": {
     "node": ">=24.12.0 <25 || >=25.1.0"
   },
+  "dependencies": {
+    "mongodb": "7.5.0"
+  },
   "scripts": {
     "build": "tsc -b tsconfig.build.json --pretty false && node scripts/build-package.js",
     "typecheck": "tsc -b tsconfig.build.json --pretty false && tsc -p tsconfig.json --pretty false",
     "test": "pnpm run build && vitest run --root ../.. apps/cli/test/local-vault-cli-view.test.ts apps/cli/test/package.test.ts",
     "test:coverage": "pnpm run build && vitest run --root ../.. apps/cli/test/local-vault-cli-view.test.ts apps/cli/test/package.test.ts --coverage --coverage.include=apps/cli/src/**",
-    "prepack": "pnpm run build",
     "pack:check": "pnpm pack --dry-run --json",
     "package:smoke": "pnpm run build && node scripts/smoke-packed-package.js"
-  },
-  "dependencies": {
-    "mongodb": "7.5.0"
   }
-}
+}