keep/IMPLEMENTATION.md

# keep — implementation notes

Design-stage document. Nothing here is built yet; this is the spec to
build against, not a description of existing code.

## Threat model

- The server operator can be assumed hostile-but-honest, same posture as
  `wisp`: they might try to read stored secrets, but the design should
  make that cryptographically impossible, not just policy-forbidden.
- The server **can** see: which vaults exist, which recipients exist,
  which recipients are granted access to which vaults, payload size, and
  access timestamps (who pulled/pushed what, when). It **cannot** see:
  secret values, the symmetric key that encrypts any payload, or any
  recipient's private key.
- **Not defended against**: a compromised recipient machine. If a
  deploy box with legitimate access to a vault is compromised, the
  attacker gets everything that machine's identity can decrypt — same as
  any secrets manager, self-hosted or not. Revoking that recipient stops
  *future* pulls; it does not retroactively invalidate secrets already
  decrypted and sitting in that machine's memory/disk/logs. **The fix for
  a compromised recipient is always rotating the underlying secrets
  (`keep push` with new values), not just revoking the recipient.** This
  is a standard, correct caveat that applies to every system built this
  way (age, sops, Vault, all of them) — worth stating explicitly because
  it's the single most common misunderstanding of what "revoke" buys you.
- **Not defended against**: a recipient with legitimate access
  deliberately exfiltrating secrets they're authorized to read. Same
  out-of-scope boundary wisp draws around a recipient re-sharing a
  decrypted file — access control stops unauthorized reads, not
  authorized-then-malicious ones.

## Crypto scheme

Per-vault, adapting the `age`/`sops`/PGP multi-recipient pattern (see
README's "Core model") to libsodium primitives already used elsewhere in
this project family:

- **Payload encryption**: `crypto_secretbox` (XSalsa20-Poly1305), same
  primitive `wisp` uses for its blobs. A fresh random 256-bit symmetric
  key per push.
- **Key wrapping**: for each recipient granted access, the vault's
  symmetric key is sealed to that recipient's X25519 public key via
  `crypto_box` (or `crypto_box_seal` if the pusher's own identity
  shouldn't need to be verifiable by the server — anonymous sealing, matches
  how `flit`'s `Identity.seal()` already works, since the server has no
  business knowing which recipient's key was used to encrypt which
  wrapped copy beyond the recipient it's addressed to).
- **Identity**: Ed25519 signing keypair per client, with the same
  sign-to-curve25519 conversion `flit`/`waste-go` already do
  (`crypto_sign_ed25519_pk_to_curve25519` /
  `..._sk_to_curve25519`) to derive the X25519 keypair used for the
  box-sealing above. One identity type, reused for both signing (proving
  who's pushing/pulling, for the access log) and encryption (wrapping),
  exactly like the existing projects already do.
- **Push authentication**: a push should be signed by the pusher's
  Ed25519 key so the access log records a real identity, not just "someone
  with write access to this vault." Whether *anyone* with any registered
  identity can push to a vault they're a recipient of, or whether push
  requires a separate "can write" grant distinct from "can read," is an
  open question below.

## Data model

Flat schema, matching the minimalism already established in `wisp` and
`npm-statuspage` (no unnecessary normalization — a vault is identified by
its own key string, not a foreign-keyed `projects`/`environments` pair):

```sql
CREATE TABLE IF NOT EXISTS vaults (
  vault_key    TEXT PRIMARY KEY,     -- e.g. "wisp/production" — free-form, app-chosen
  ciphertext   BLOB NOT NULL,        -- crypto_secretbox(payload, vault_symmetric_key)
  nonce        BLOB NOT NULL,
  updated_at   INTEGER NOT NULL,
  updated_by   TEXT NOT NULL         -- recipient_id of whoever last pushed
);

CREATE TABLE IF NOT EXISTS recipients (
  recipient_id TEXT PRIMARY KEY,     -- short label-derived slug, e.g. "wisp-prod-deploy"
  label        TEXT NOT NULL,        -- human-readable, e.g. "wisp production deploy key"
  public_key   TEXT NOT NULL,        -- hex Ed25519 pubkey
  created_at   INTEGER NOT NULL
);

-- The multi-recipient key-wrapping table. One row per (vault, recipient)
-- pair that currently has access. Deleting a row IS the revocation —
-- no separate "enabled" flag needed.
CREATE TABLE IF NOT EXISTS vault_grants (
  vault_key      TEXT NOT NULL REFERENCES vaults(vault_key),
  recipient_id   TEXT NOT NULL REFERENCES recipients(recipient_id),
  wrapped_key    BLOB NOT NULL,      -- crypto_box_seal(vault_symmetric_key, recipient_pubkey)
  granted_at     INTEGER NOT NULL,
  PRIMARY KEY (vault_key, recipient_id)
);

-- Access log — metadata only, exactly what the threat model says the
-- server is allowed to know.
CREATE TABLE IF NOT EXISTS access_log (
  id           INTEGER PRIMARY KEY AUTOINCREMENT,
  vault_key    TEXT NOT NULL,
  recipient_id TEXT NOT NULL,
  action       TEXT NOT NULL,        -- 'pull' | 'push'
  accessed_at  INTEGER NOT NULL
);
```

A vault with zero rows in `vault_grants` is unreadable by anyone —
including, notably, whoever pushed it, unless they granted themselves
access first. This is intentional: creating a vault and granting access
to it are separate steps, so a vault can't accidentally be pushed
"open" to nobody or to a stale recipient list left over from a template.

## Rotation

`keep push <vault>` with new secret values:

1. Generate a fresh random symmetric key.
2. Encrypt the new payload under it.
3. Look up every current row in `vault_grants` for this vault.
4. Re-wrap the new symmetric key for every one of those recipients'
   public keys (already have them via `recipients.public_key`).
5. Replace `vaults.ciphertext`/`nonce` and all `vault_grants.wrapped_key`
   rows for this vault, atomically (single transaction).

The old symmetric key and old wrapped copies are simply gone —
overwritten, not versioned, in v1 (see Open Questions on whether
version history is worth adding).

## Revocation

Deleting one `vault_grants` row (`vault_key`, `recipient_id`) removes
that recipient's ability to `pull` — the very next pull attempt with
their identity finds no wrapped-key row and is rejected. No re-encryption
of the payload needed; every other recipient's access is untouched.

As stated in the threat model: this stops *future* pulls only. If
revocation is happening because a machine may have been compromised,
follow it with `keep push` to actually rotate the secret values, not just
the grant.

## CLI surface (sketch)

```
keep identity init                        -- generate + persist a local Ed25519 keypair (~/.keep/identity)
keep identity show                        -- print this machine's public key, for registering as a recipient

keep push <vault> [--file .env]           -- encrypt + upload; requires this identity to already be a grantee
keep pull <vault> [--format=env|json]     -- fetch + decrypt; requires a grant for this identity

# admin operations — see below for how these are authenticated
keep recipient add --label "..." --pubkey <hex>
keep recipient list
keep recipient remove <recipient_id>
keep grant <vault> <recipient_id>
keep revoke <vault> <recipient_id>
keep log <vault>                          -- tail the access log for one vault
```

### Admin operations need their own authorization story

Adding/removing recipients and granting/revoking vault access is a
different trust level than pushing/pulling a specific vault you already
have a grant for. Options, in rough order of how much new infrastructure
they cost:

1. **Bootstrap admin identity**: the first recipient ever registered is
   implicitly the admin; admin operations require a signature from that
   identity. Cheapest — no new credential type — but doesn't scale past
   "it's just me" without more thought.
2. **Separate `ADMIN_PASSWORD`**, same pattern as `wisp`'s proposed
   invite-links admin gate and `npm-statuspage`'s admin panel (both
   already built/proposed as of this writing) — a shared password
   distinct from any recipient identity, gating a small admin HTTP
   surface (could be CLI-driven hitting password-gated endpoints, or a
   minimal web page like npm-statuspage's).
3. **Per-vault admin grants** — a `vault_grants.can_admin` boolean
   alongside read access, so admin authority is scoped per-vault instead
   of global. More correct, more to build; probably not v1.

Leaning toward (2) for v1 — it's proven twice already elsewhere in this
project family, and a global admin password is an acceptable trust model
for "one person or small team running their own homelab," which is the
actual scale this is being built for.

## Deploy integration

The actual motivating use case — a deploy script pulling secrets instead
of assuming a hand-copied `.env` already exists on the target machine:

```bash
#!/usr/bin/env bash
# top of an existing deploy-*.sh script, e.g. waste-go's deploy-daemon.sh
set -euo pipefail

keep pull wisp/production --format=env > .env
# ...rest of the existing deploy script, unchanged, now consuming a
# freshly-pulled .env instead of one that was manually placed there
```

Requires the deploy machine to have a `keep` identity already registered
and granted access to the relevant vault — a one-time setup step per
machine (`keep identity init` once, then an admin grants that machine's
public key access to whichever vaults it needs).

## Security considerations

- Every point already covered under Threat Model applies; this section
  covers implementation-level details that aren't strictly part of the
  threat model but matter for correctness.
- **Grant/revoke and push must not race.** If a push and a grant/revoke
  happen concurrently, the re-wrap step in `push` (which reads current
  `vault_grants` and re-wraps for all of them) must see a consistent
  snapshot — wrap the read-grants-then-write-wrapped-keys sequence in a
  single SQLite transaction, same discipline as wisp's atomic confirm-token
  consumption.
- **The access log is genuinely useful, not just decorative** — the
  README's whole pitch versus a static `age`-encrypted file in git is
  "you can tell who actually pulled what, when." Make sure `pull`
  failures (wrong/no grant) are *also* logged, not just successes — a
  spike of failed pulls from an unexpected identity is exactly the kind
  of signal this feature exists to surface.
- **Recipient private keys are the actual crown jewels**, same as
  `flit`/`waste-go`'s existing identity model. `keep identity init`
  should follow the same local-storage discipline those already use
  (`~/.flit/`-style, not committed anywhere, not transmitted anywhere
  except the public half).

## Open questions

- **Version history**: keep only the latest payload per vault (simplest,
  matches the "this predates rollback needs" scope), or retain N previous
  versions for `keep pull --version=N` rollback? Leaning toward: skip for
  v1, revisit if a real rollback need shows up.
- **Push authorization**: does having a *read* grant (`vault_grants` row)
  imply push rights too, or is push a separate capability? Leaning toward:
  read implies write for v1 (simpler, matches "small team, own homelab"
  scale) — a `can_write` flag on `vault_grants` is the natural extension
  if that turns out to be wrong.
- **Per-secret-key granularity**: v1 treats a vault as one opaque
  `.env`-shaped blob (matches the actual current pain point: whole files
  get copied around, not individual keys). If a use case emerges for
  "grant access to just the DB password, not the whole bundle," that's a
  genuinely different data model (per-key rows, each separately wrapped)
  — don't half-build it speculatively now.
- **Admin auth mechanism** — see the three options under CLI surface
  above; needs a decision before build, not deferred to implementation
  time, since it shapes the admin API surface.