kern v0.2 — encrypted secrets in git, scoped by folder, managed by agents

TypeScript SDK + CLI + MCP server + local form for secure credential capture.
Built on age encryption. One dependency. MIT.

Author: mirkokiefer

.github/workflows/test.yml

@@ -0,0 +1,18 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - run: bun test ./test/smoke.ts ./test/proxy.test.ts

.gitignore

@@ -1 +1,2 @@
 node_modules/
+.smoke-tmp/

README.md

@@ -1,123 +1,258 @@
 # kern
 
-Secrets for agents. TypeScript SDK + CLI built on [age](https://age-encryption.org/) encryption.
+[![tests](https://github.com/daslabhq/kern/actions/workflows/test.yml/badge.svg)](https://github.com/daslabhq/kern/actions/workflows/test.yml)
 
-## Why
+Encrypted secrets in git. Scoped by folder. Managed by agents.
 
-Every agent stack reinvents secret management (badly): env vars on the
-server, plaintext in databases, "share the .env in Slack" for dev. Kern is
-the small, composable, standards-aligned alternative — built on
-[age](https://age-encryption.org/) and BIP-39, no new crypto.
+```bash
+npm install @daslab/kern
+```
 
-What you get:
+## The problem
 
-- **One environment variable** in production (the server's age key) instead
-  of dozens
-- **Encrypted vault committed to your repo** — auditable in git, useless
-  to non-recipients
-- **Multi-recipient** by default: same secret encrypted to multiple
-  identities (team, prod server, your devices) at once
-- **No vendor lock-in** — vault files are standard age, readable by the
-  `age` CLI / `rage` / any age library
+91 API keys in a `.env` file. Shared over Slack. Copied between machines. Half of them are test keys that shouldn't be in production. New teammate joins — "ask the lead dev for the keys." Rotate one key — update it in 7 places, miss 2.
 
-## Install
+## How kern solves it
+
+Secrets are age-encrypted files organized in folders. Each folder has a `.recipients` file that controls who can decrypt. Commit the whole thing to git — it's useless without a private key.
 
-```bash
-bun add @daslab/kern
+```
+secrets/
+├── .recipients                  # everyone (Alice + Production + CI)
+├── .nodes                       # who's who
+│
+├── infra/                       # prod runtime
+│   ├── database_url.age
+│   ├── redis_url.age
+│   ├── jwt_secret.age
+│   └── r2.age                   # { access_key_id, secret, account_id }
+│
+├── oauth/                       # prod OAuth app credentials
+│   ├── github.age               # { client_id, client_secret, app_id }
+│   ├── google.age
+│   └── slack.age
+│
+├── testing/                     # local dev + CI only
+│   ├── .recipients              # Alice + CI (NOT production server)
+│   ├── llm.age                  # { anthropic, openai, gemini }
+│   ├── elevenlabs.age
+│   ├── stripe_test.age
+│   └── ci_demo.age
+│
+└── deploy/                      # CI/CD only
+    ├── .recipients              # Alice + CI
+    ├── apple_signing.age
+    └── tauri_signing.age
 ```
 
-The package is ESM-only; works on Bun, Node 20+, and Deno. age-encryption
-0.3+ is the only runtime dependency.
+Your production server only decrypts `infra/` and `oauth/` — it never sees test keys or deploy secrets. CI decrypts `testing/` and `deploy/` but never touches production database credentials. Each node sees only what it should.
 
-## Programmatic API
+## Quick start
+
+```bash
+# create your identity
+kern identity init
 
-```ts
+# create the vault
+mkdir -p secrets
+kern identity pubkey >> secrets/.recipients
+
+# add your first secret
+kern secret add github_token
+
+# group related credentials
+mkdir -p secrets/testing
+cp secrets/.recipients secrets/testing/.recipients
+kern secret add testing/llm    # { "anthropic": "sk-...", "openai": "sk-..." }
+```
+
+## Use from code
+
+```typescript
 import { loadIdentityFromHost, openVault } from "@daslab/kern";
 
-// load from KORN_AGE_KEY env var, falling back to ~/.kern/key
-const id    = await loadIdentityFromHost();
-const vault = openVault({ identity: id });  // reads ./secrets by default
+const vault = openVault({ identity: await loadIdentityFromHost() });
+
+// simple value
+const dbUrl = await vault.get("infra/database_url");
+
+// grouped credentials
+const llm = JSON.parse(await vault.get("testing/llm"));
+const anthropicKey = llm.anthropic;
+```
+
+## Use from Claude Code
+
+Add kern as an MCP server:
+
+```json
+{
+  "mcpServers": {
+    "kern": {
+      "command": "npx",
+      "args": ["@daslab/kern", "mcp"]
+    }
+  }
+}
+```
+
+```
+You: "Set up secrets for this project — I need GitHub OAuth,
+      an OpenAI key for testing, and Stripe test credentials"
+
+Claude → kern_add("oauth/github")
+  → browser opens kern's local form
+  → you paste client_id + client_secret
+  → encrypted into secrets/oauth/github.age
+
+Claude → kern_add("testing/openai")
+  → same flow
+  → encrypted into secrets/testing/openai.age
+
+Claude → kern_add("testing/stripe")
+  → same flow
+
+"3 secrets added. testing/ is scoped to Alice + CI.
+ oauth/ is available to all nodes."
+```
+
+Credentials go: browser form → kern → encrypted vault. The LLM never sees them.
+
+## Nodes
 
-// shorthand: returns plaintext string
-const openaiKey = await vault.get("openai_api_key");
+A node is any machine with an age keypair — your laptop, CI, a server. Add a `.nodes` file to track them:
 
-// scoped form — preferred. Plaintext only lives inside the callback.
-const result = await vault.with("anthropic_api_key", async (key) => {
-    return await anthropic.messages.create({ ... });
-});
+```
+# secrets/.nodes
+age1abc...  Alice          owner
+age1def...  Production         server
+age1ghi...  GitHub CI      ci
+```
+
+### Add a teammate
+
+```bash
+# Bob generates his keypair
+kern identity init && kern identity pubkey
+# → age1xyz...
+
+# You add him to the folders he needs
+echo "age1xyz..." >> secrets/.recipients
+echo "age1xyz..." >> secrets/testing/.recipients
+kern secret rewrap
+git commit -am "add Bob"
 
-// listing, writing, deleting
-vault.list();                                      // ["openai_api_key", ...]
-await vault.put("slack_webhook", "https://...");   // re-encrypts to current recipients
-vault.delete("old_key");
-const r = await vault.rewrap();                    // after editing .recipients
-console.log(`rewrapped ${r.rewrapped}`);
+# Bob clones, everything works
 ```
 
-## CLI
+### Add CI
 
 ```bash
-# one-time setup per machine
-kern identity init                # writes ~/.kern/key (age private key)
-kern identity pubkey              # → "age1..."
+# generate a keypair for CI
+kern identity init --save /tmp/ci-key
+# add to the folders CI needs
+echo "$(kern identity pubkey)" >> secrets/.recipients
+echo "$(kern identity pubkey)" >> secrets/testing/.recipients
+echo "$(kern identity pubkey)" >> secrets/deploy/.recipients
+kern secret rewrap
+# set the one CI secret
+gh secret set KERN_AGE_KEY < /tmp/ci-key
+rm /tmp/ci-key
+```
 
-# vault management (in your project)
-mkdir secrets/
-echo "age1yourpubkey..." > secrets/.recipients
-kern secret add openai_api_key    # prompts on stdin
-kern secret list
-kern secret get openai_api_key    # decrypts to stdout
+One secret in CI. Everything else decrypts from git.
 
-# add a teammate
-echo "age1theirpubkey..." >> secrets/.recipients
-kern secret rewrap                # re-encrypts every secret to current recipients
+### Revoke access
 
-# rotate a value
-kern secret rotate openai_api_key
+```bash
+# remove Bob's key from all .recipients files
+kern recipients remove age1xyz...
+kern secret rewrap
+# rotate any secrets Bob had access to
+kern secret rotate testing/openai
+```
+
+## Scoping rules
+
+- Each folder can have its own `.recipients`
+- A secret is encrypted to the `.recipients` in its folder
+- If no `.recipients` in a folder, it inherits from the parent
+- Root `.recipients` is the default for everything
+
+This means:
+- Secrets in `infra/` → encrypted to root recipients (everyone)
+- Secrets in `testing/` → encrypted to testing's recipients (dev + CI, not prod)
+- Secrets in `deploy/` → encrypted to deploy's recipients (dev + CI)
+
+No duplication. No complex config. Just folders and recipient files.
+
+## Local form server
+
+```bash
+kern serve
+# → http://localhost:9271
+```
+
+Dashboard shows all secrets (names only), all nodes, folder structure. Add, edit, rotate secrets through the browser. Same server that MCP elicitation uses.
+
+## CLI reference
+
+```bash
+kern identity init [--save PATH]   # create age keypair
+kern identity pubkey               # print public key
+
+kern secret add [FOLDER/]NAME      # encrypt and store
+kern secret get [FOLDER/]NAME      # decrypt to stdout
+kern secret list                   # show all names
+kern secret rotate [FOLDER/]NAME   # replace a value
+kern secret delete [FOLDER/]NAME   # remove
+kern secret rewrap                 # re-encrypt for current recipients
+
+kern recipients list               # show all nodes
+kern recipients remove KEY         # remove a node from all folders
+
+kern mcp                           # start MCP server
+kern serve                         # start local form + dashboard
 ```
 
 ## Environment
 
 | Variable | Purpose | Default |
 |---|---|---|
-| `KORN_AGE_KEY` | private age key, used for decryption | (none) |
-| `KORN_VAULT_DIR` | vault root directory | `./secrets` |
+| `KERN_AGE_KEY` | age private key | `~/.kern/key` |
+| `KERN_VAULT_DIR` | vault directory | `./secrets` |
 
-Production deploys typically set `KORN_AGE_KEY` to the server's own age
-private key. Local dev uses the file at `~/.kern/key`. Both work via the
-same code path.
+## How it compares
 
-## Vault layout
+| | .env | SOPS | Vault | 1Password | kern |
+|---|---|---|---|---|---|
+| Encrypted in git | no | yes | no | no | yes |
+| Folder scoping | no | no | yes | yes | yes |
+| No server needed | yes | yes | no | no | yes |
+| TypeScript SDK | no | no | no | no | yes |
+| Agent integration (MCP) | no | no | no | no | yes |
+| Grouped credentials | no | yes | yes | yes | yes |
 
-```
-secrets/
-├── .recipients                 plaintext, one age pubkey per line
-├── openai_api_key.age
-├── anthropic_api_key.age
-└── prod/
-    ├── .recipients             narrower recipient set
-    └── stripe_live.age
-```
+## Building on kern
 
-Nearest enclosing `.recipients` applies. The format is canonical age
-v1, fully interoperable with the upstream `age` binary.
+kern is the encryption + scoping primitive. Build governance on top:
 
-## Roadmap
+```typescript
+import { loadIdentityFromHost, openVault } from "@daslab/kern";
 
-- **BIP-39 seed derivation** — derive age keys from mnemonic phrases
-- **OS Keychain integration** — store the private key in macOS Keychain / Windows Credential Manager
-- **Agent grants** — scoped, auditable secret access for sub-agents
+// your platform wraps kern with policy
+const vault = openVault({ identity: await loadIdentityFromHost() });
 
-## Testing
+// kern handles: encrypted storage, folder scoping, recipients
+const creds = await vault.get("oauth/github");
 
-```bash
-bun test ./test/smoke.ts
+// you add: RBAC, approval flows, audit trails, asset-level permissions
+await checkPolicy(user, "oauth/github", "read");
+await auditLog(user, "oauth/github", "read");
 ```
 
-10 tests covering identity generation, round-trip, multi-recipient,
-nested recipients, rewrap, scoped `with()`, list, delete, missing-key,
-path-traversal rejection.
+The folder structure maps naturally to governance scopes — `testing/` is one access tier, `deploy/` is another, `infra/` is another. The primitive is simple; the policy layer is yours.
 
 ## License
 
-MIT.
+MIT