nvault v0.1

Why nvault

The repo already had two half-stories: ndev secrets (macOS Keychain credentials) and ndev config (file-backed parameters). Neither had versioning, an SDK, or any way to share a value across machines or teammates without copy-paste or a committed .env.

nvault unifies both behind one Go core and gives it three faces, a typed SDK in two languages, and an end-to-end-encrypted cloud tier. The local experience gets easier; the capability becomes a product.

Pricing

The local CLI is free and open — secrets in your OS Keychain, typed params on disk, offline forever. The paid tier is the zero-knowledge team cloud: end-to-end-encrypted sync, RBAC, audit log, and SDKs. Priced to the value of replacing a secrets manager and a config service with one engine your server can't read.

Three faces, one engine

Every surface dispatches through the same internal/nvaultcli engine over internal/vault, so behavior can never diverge.

Quickstart

Local secrets & params

# store a secret (never via argv history — pipe it)
printf '%s' "$OPENAI_API_KEY" | nvault set OPENAI_API_KEY --stdin

# a typed parameter
nvault set PORT --value 3000 --param --type int

# list (secret values are NEVER printed)
nvault ls --scope dev

# inject the merged secret+param env into a process
nvault run --scope dev -- pnpm dev

# or materialize a dotenv
nvault env --format dotenv > .env.local

Team sync (end-to-end encrypted)

# 1. create this machine's identity (private key → Keychain)
nvault key init --label laptop

# 2. register teammates so secrets get sealed to them too
nvault key add-recipient bob nvpub_…

# 3. authenticate to the cloud tier (token → Keychain)
printf '%s' "$NVAULT_TOKEN" | nvault login --url https://…convex.site --org org_… --env env_… --stdin

# 4. push (encrypt locally, upload ciphertext) / pull (download, decrypt locally)
nvault push --scope prod
nvault pull --scope prod

Data model

In the cloud tier the hierarchy is org → project → environment → item, with immutable itemVersions history, hashed apiKeys, and an append-only auditEvents log.

Zero-knowledge crypto

The trust model is hybrid: the local tier uses the OS Keychain unchanged; the remote tier is end-to-end encrypted with an age-style scheme. The server stores only opaque envelopes (nvault.enc.v1) and has no key material.

• Each item gets a fresh 256-bit data key; the body is AEAD-encrypted with a 24-byte nonce. The logical slot (org/env/scope/key) is bound in as additional authenticated data, so an envelope can't be silently relocated.
• The data key is wrapped to every member's public key via a NaCl sealed box. Any member decrypts; nobody else can — not even the server operator.
• Rotation = rewrap. Membership changes re-seal the data key to the new recipient set without touching the ciphertext body. Removed members lose access to future pulls.
• Recovery is just an extra recipient whose private key is printed once and escrowed offline; nvault never persists it.

Cloud tier (Convex)

The multi-tenant backend lives in apps/nvault-cloud. Every query and mutation funnels through one RBAC chokepoint (reader < member < admin < owner) and one audit chokepoint. The CLI talks to two token-authenticated HTTP endpoints:

GET  /sync/pull?org=<id>&env=<id>     → { items: [{ key, kind, ciphertext, version }] }
POST /sync/push  { org, env, items }  → { results: [{ key, version }] }

Both authenticate with Authorization: Bearer nvk_… service tokens (only the SHA-256 hash is stored). Payloads are ciphertext end-to-end.

SDKs

Go

import "nicos.tools/nicos-dev/sdk/nvault"

c, _ := nvault.Open(nvault.Config{})
_ = c.SetSecret("dev", "OPENAI_API_KEY", key)
env, _ := c.Env("dev")        // merged secrets+params
_, _ = c.Push("dev")            // encrypt + upload (after Login)

TypeScript

import { NvaultClient, generateIdentity, sealEnvelope } from "@nvault/client";

const me = await generateIdentity();
const client = new NvaultClient({ baseUrl, org, env, token });
await client.push([{ key: "DB_URL", kind: "secret", ciphertext: JSON.stringify(env) }]);

The TS types are generated from the Go source by nvault-schemagen with a --check drift gate, so the two languages can never silently diverge.

Command reference

Add --json for machine-readable output on any verb. Under ndev the same surface is ndev [--json] vault <verb>.