67000b66ee
Server: Express + better-sqlite3 (WAL), multi-recipient key-wrapping per IMPLEMENTATION.md's design — vaults/recipients/vault_grants/ access_log. Two auth paths: ADMIN_PASSWORD header for recipient management and revoke (pure metadata operations), signed-request auth (Ed25519 signature over method+path+timestamp+body-hash) for push/pull/grant, mirroring the spirit of this project family's other signed-handshake patterns without naming them. CLI: identity init/show/set-id, push/pull/grant/log, admin recipient add/list/remove and revoke. Grant is a client-side crypto operation (the granter unwraps the vault's current key locally and reseals it for the new recipient) rather than a server-side operation, since the server never holds an unwrapped key to grant with. Verified end-to-end with two independent local identities against a live server and separately against the built Docker image: register, push, pull (granted and ungranted), grant without re-pushing, admin revoke, a subsequent rotation confirming the revoked recipient stays excluded, and rejection of missing/malformed signed-request auth. Two real bugs caught during verification, not just written up: - libsodium-wrappers' published ESM build does a relative import only resolvable under bundler-style resolution — broken under plain Node ESM. Fixed via createRequire to force the CJS build. - Express's req.path inside a sub-router is relative to the mount point, which would have silently mismatched a client signing the full request path. Fixed by verifying against req.originalUrl. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
164 lines
6.4 KiB
Markdown
164 lines
6.4 KiB
Markdown
# keep
|
|
|
|
A self-hosted, end-to-end encrypted secrets store for deploy scripts.
|
|
`keep pull myapp/production` gets you a `.env`-shaped bundle of secrets,
|
|
decrypted locally — the server never sees plaintext values, and never
|
|
sees the key that would let it.
|
|
|
|
## Why
|
|
|
|
Across a small family of self-hosted projects, every repo tends to have
|
|
its own `.env`/`.env.example` pair, and every one of those `.env` files
|
|
exists today by being hand-copied onto whatever machine needs it. That's
|
|
a real, already-felt annoyance, not a hypothetical one:
|
|
|
|
- Rotating a credential means finding and updating every machine that has
|
|
a copy, by hand.
|
|
- There's no record of which machine has which secret, or when it was
|
|
last updated.
|
|
- Onboarding a new deploy target means manually reconstructing a `.env`
|
|
from memory, a password manager note, or asking "hey, what's the value
|
|
for X."
|
|
|
|
`keep` is a small always-on service that holds encrypted secret bundles
|
|
and lets authorized machines/people pull them, decrypted locally, without
|
|
ever exposing plaintext to the server in between.
|
|
|
|
## What it isn't
|
|
|
|
- **Not Vault or Doppler.** Those are the established, heavier answers —
|
|
full policy engines, dynamic secrets, enterprise everything. `keep` is
|
|
the "already-solved problem, but self-hosted and scoped to what this
|
|
actually needs" answer, closer in spirit to `age`/`sops` (multi-recipient
|
|
encrypted files) than to a full secrets-management platform.
|
|
- **Not a static encrypted file committed to git**, which is what
|
|
`age`/`sops` typically produce. `keep` exists specifically for the two
|
|
things a committed encrypted file can't give you without re-running a
|
|
tool and re-committing: **live rotation** (push once, everyone with
|
|
access can pull the update) and **an access log** (who/what actually
|
|
fetched a secret bundle, and when — a git history shows content
|
|
changes, not access).
|
|
- **Not an ephemeral file-drop tool.** Something built for single-retrieval,
|
|
self-destructing file sharing is the opposite of what a secret needs to
|
|
be — a deploy script needs to fetch the same bundle on every deploy, not
|
|
once and then have it vanish.
|
|
|
|
## Core model
|
|
|
|
Adapts the pattern `age`/`sops`/PGP already use for multi-recipient
|
|
encrypted files — a symmetric key encrypts the actual payload, and that
|
|
symmetric key is separately "wrapped" (encrypted) once per authorized
|
|
recipient's public key — into a live service instead of a static file:
|
|
|
|
1. Each client (a developer's machine, a deploy script running on a VPS)
|
|
has its own Ed25519/X25519 keypair.
|
|
2. A vault (`myapp/production`, `myapp/staging`, whatever key) holds one
|
|
encrypted blob — the actual secret bundle, encrypted under a random
|
|
symmetric key.
|
|
3. That symmetric key is wrapped separately for every recipient granted
|
|
access to that vault. The server stores N small wrapped-key blobs, one
|
|
per recipient, alongside the one encrypted payload.
|
|
4. `keep pull <vault>` fetches the payload plus this identity's wrapped
|
|
key, unwraps locally with the private key, decrypts, and prints (or
|
|
writes) the `.env`-shaped result.
|
|
5. Revoking a recipient's access is deleting their one wrapped-key row —
|
|
the payload and every other recipient's access are untouched.
|
|
6. Rotating a secret is `keep push <vault>` again — a new random
|
|
symmetric key, re-wrapped for every currently-granted recipient. Cheap,
|
|
since the recipient list rarely changes.
|
|
|
|
Full design — data model, the atomic-grant/revoke details, and what this
|
|
explicitly does and doesn't protect against — is in
|
|
[IMPLEMENTATION.md](./IMPLEMENTATION.md). Ideas for wiring this into
|
|
existing deploy scripts are in [INTEGRATION.md](./INTEGRATION.md).
|
|
|
|
## Quickstart
|
|
|
|
```bash
|
|
# 1. Run the server (see "Docker" below for a real deploy)
|
|
cp .env.example .env
|
|
npm install
|
|
npm run dev:server
|
|
|
|
# 2. Each machine/person that needs access generates its own identity
|
|
npm run cli -- identity init
|
|
# → prints a public key
|
|
|
|
# 3. An admin registers that public key as a recipient
|
|
KEEP_ADMIN_PASSWORD=... npm run cli -- recipient add --label "my-laptop" --pubkey <hex>
|
|
# → prints a recipient id
|
|
|
|
# 4. The machine that generated the identity records its assigned id
|
|
npm run cli -- identity set-id <recipient-id>
|
|
|
|
# 5. Push a vault — the pusher is automatically its first recipient
|
|
npm run cli -- push myapp/production --file .env.production
|
|
|
|
# 6. Anyone else with a grant can pull it, decrypted, ready to use
|
|
npm run cli -- pull myapp/production > .env
|
|
```
|
|
|
|
## Granting, revoking, rotating
|
|
|
|
```bash
|
|
# An existing recipient of a vault can grant a NEW recipient access,
|
|
# without needing admin rights or re-encrypting the payload:
|
|
keep grant myapp/production <new-recipient-id>
|
|
|
|
# Revoking is an admin operation — pure metadata deletion, immediate:
|
|
KEEP_ADMIN_PASSWORD=... keep revoke myapp/production <recipient-id>
|
|
|
|
# Revoke only stops FUTURE pulls. If this was a compromise response,
|
|
# also rotate the actual values:
|
|
keep push myapp/production --file .env.production
|
|
|
|
# See who's touched a vault and when:
|
|
keep log myapp/production
|
|
```
|
|
|
|
## Docker
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
Uses the image from `IMAGE` in `.env`. For a local build:
|
|
|
|
```bash
|
|
docker build -t keep:local .
|
|
IMAGE=keep:local docker compose up -d
|
|
```
|
|
|
|
## CI/CD
|
|
|
|
Gitea Actions workflow at `.gitea/workflows/docker.yml`. Builds and
|
|
pushes to the Gitea container registry on every push to `main`. Requires
|
|
a `TKNTKN` secret (PAT with `packages:write`) in the repo settings.
|
|
|
|
## Environment variables
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `PORT` | `3050` | Port to listen on |
|
|
| `DATA_DIR` | `./data` | Where the SQLite DB (vaults, recipients, grants) lives |
|
|
| `ADMIN_PASSWORD` | — | Gates recipient add/remove and revoke. Unset disables `/api/admin/*` (503) — push/pull/grant for already-registered recipients keep working |
|
|
| `REQUEST_MAX_SKEW_SECONDS` | `300` | Replay-protection window for signed CLI requests |
|
|
|
|
CLI-side: `KEEP_SERVER_URL` (default `http://localhost:3050`),
|
|
`KEEP_ADMIN_PASSWORD` (for admin commands: `recipient add/list/remove`,
|
|
`revoke`).
|
|
|
|
## Status
|
|
|
|
Implemented: identity, push/pull/grant/revoke/log, admin recipient
|
|
management, Docker deploy. Verified end-to-end (two independent
|
|
identities, grant, pull, revoke persisting through a subsequent
|
|
rotation, malformed-auth rejection) against both a local server and the
|
|
built Docker image. See [IMPLEMENTATION.md](./IMPLEMENTATION.md) for the
|
|
full design and its still-open questions (version history, per-secret-key
|
|
granularity).
|
|
|
|
## License
|
|
|
|
MIT. See [LICENSE](./LICENSE).
|