86 lines
3.7 KiB
Markdown
86 lines
3.7 KiB
Markdown
# clavis-cli
|
|
|
|
Pure C CLI for credential access by AI agents. Talks to a Clavitor vault over HTTPS, decrypts L2 fields locally.
|
|
|
|
## Build
|
|
|
|
```
|
|
make # build for host
|
|
make strip # strip binary
|
|
make clean # remove artifacts
|
|
```
|
|
|
|
Target: `clavitor-cli` binary, <1MB stripped. Requires: C11 compiler, POSIX (Linux/macOS/FreeBSD/Windows).
|
|
|
|
## Architecture
|
|
|
|
- **src/main.c** — CLI entry point, argument parsing, commands (get, list, totp, test-crypto, test-roundtrip, eval, test-totp)
|
|
- **src/http.c** — HTTPS client using BearSSL. Loads system CA certs for TLS validation. Supports plain HTTP fallback.
|
|
- **src/keystore.c** — Config storage at `~/.config/clavitor/config`. AES-128-GCM encrypted + HMAC-SHA256 signed. Inconvenience barrier only — real security is vault-side.
|
|
- **src/jsbridge.c** — QuickJS bridge exposing BearSSL crypto primitives to JS. Loads `crypto/crypto.js` and `crypto/totp.js` from `../clavis-crypto/`.
|
|
- **src/util.c** — Base64 (standard + url-safe), URL encoding.
|
|
|
|
## Vendored dependencies
|
|
|
|
All in `vendor/`, no system package dependencies:
|
|
- **BearSSL** — TLS, AES-GCM, HKDF, HMAC, PRNG
|
|
- **QuickJS** — JS runtime for shared crypto logic
|
|
- **cJSON** — JSON parsing
|
|
|
|
## Crypto design
|
|
|
|
Three-tier encryption model:
|
|
- **L1** — first 8 bytes of L2 key, used as Bearer auth token
|
|
- **L2** — 16-byte AES-128-GCM key, client-side field encryption/decryption
|
|
- **L3** — requires hardware key (not handled by CLI)
|
|
|
|
JS crypto in `../clavis-crypto/` is the single source of truth for encrypt/decrypt logic. The C code bridges BearSSL primitives into QuickJS so the same JS runs in CLI and browser.
|
|
|
|
## Token format
|
|
|
|
`--token` value is a base64url-encoded, AES-GCM encrypted blob containing: `vault_host \0 agent_name \0 l2_key_16_bytes`. Decrypted using HKDF-derived key from seed `clavitor-l2-`.
|
|
|
|
## Vault communication
|
|
|
|
All API calls go to `https://<host>:1984` with `Authorization: Bearer <L1>` and `X-Agent: <agent_name>` headers.
|
|
|
|
Endpoints used: `/api/entries`, `/api/search?q=`, `/api/entries/<id>`, `/api/ext/totp/<id>`.
|
|
|
|
## ⚒️ Foundation First — No Mediocrity. Ever.
|
|
|
|
The rule is simple: do it right, or say something.
|
|
|
|
Johan is an architect. Architects do not patch cracks in a bad foundation — they rebuild. Every agent on this team operates the same way.
|
|
|
|
### What this means in practice
|
|
|
|
If you need three fixes for one problem, stop. Something fundamental is wrong. Name it, surface it — we fix that, not the symptom.
|
|
|
|
If the code is spaghetti, say so. Do not add another workaround. The workaround is the problem now.
|
|
|
|
Quick fixes are not fixes. A "temporary" hack that ships is permanent. If it is not the right solution, it is the wrong solution.
|
|
|
|
Foundation > speed. A solid base makes everything downstream easy. A shaky base makes everything downstream a nightmare. We build bases.
|
|
|
|
### The restart rule
|
|
|
|
When the foundation is wrong: start over. Not "refactor slightly." Not "add an abstraction layer on top." Start over. This applies to code, infrastructure, design, encryption schemes, and written work alike.
|
|
|
|
### Q&D is research, not output
|
|
|
|
Exploratory/throwaway work has its place — but it stays in research. Nothing Q&D ships. Nothing Q&D becomes the production path. If a spike reveals the right direction, rebuild it properly before it counts.
|
|
|
|
### When you hit a bad foundation
|
|
|
|
Call it out. Do not work around it. Bad foundations are not your fault — but silently building on them is. Surface the problem, we work on it together.
|
|
|
|
The bar is high. The support is real.
|
|
|
|
## Testing
|
|
|
|
```
|
|
./clavitor-cli test-crypto # BearSSL + JS crypto self-tests
|
|
./clavitor-cli test-totp <seed> # TOTP generation from base32 seed
|
|
./clavitor-cli test-roundtrip # runs crypto/test_crypto.js
|
|
```
|