keep/IMPLEMENTATION.md

keep — implementation notes

Design-stage document, now implemented — kept as the record of why the design looks the way it does, not just a description of the code.

Threat model

• The server operator can be assumed hostile-but-honest: 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. Access control stops unauthorized reads, not authorized-then-malicious ones — the same boundary any system like this draws.

Crypto scheme

Per-vault, adapting the age/sops/PGP multi-recipient pattern (see README's "Core model") to libsodium primitives:

• Payload encryption: crypto_secretbox (XSalsa20-Poly1305). 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_seal — anonymous sealing, since the server has no business knowing which specific identity wrapped a copy beyond the recipient it's addressed to.
• Identity: Ed25519 signing keypair per client, with the standard sign-to-curve25519 conversion (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).
• Push authentication: every push is 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," was an open question at design time — resolved as "read implies write" for v1 (see Open Questions).

Data model

Flat schema — no unnecessary normalization; a vault is identified by its own key string, not a foreign-keyed projects/environments pair:

CREATE TABLE IF NOT EXISTS vaults (
  vault_key    TEXT PRIMARY KEY,     -- e.g. "myapp/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. "prod-deploy-a1b2c3"
  label        TEXT NOT NULL,        -- human-readable, e.g. "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

keep identity init                        -- generate + persist a local Ed25519 keypair (~/.keep/identity.json)
keep identity show                        -- print this machine's public key, for registering as a recipient
keep identity set-id <recipient-id>       -- record the id an admin assigned after registering this identity

keep push <vault> [--file .env]           -- encrypt + upload; requires this identity to already be a grantee
keep pull <vault> [--format env|json] [--out <path>]   -- fetch + decrypt; requires a grant for this identity
keep grant <vault> <recipient-id>         -- add a new recipient to a vault you already have access to
keep log <vault>                          -- tail the access log for one vault

# admin operations — gated by ADMIN_PASSWORD, see below
keep recipient add --label "..." --pubkey <hex>
keep recipient list
keep recipient remove <recipient-id>
keep revoke <vault> <recipient-id>

Admin operations need their own authorization story

Adding/removing recipients and revoking vault access is a different trust level than pushing/pulling a specific vault you already have a grant for. Options considered, 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 — a shared password distinct from any recipient identity, gating a small admin HTTP surface. This is what got built: same shape as a password-gated admin panel, disabled entirely (503) rather than boot-failing when unset.
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; not v1.

Went with (2) — 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 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:

#!/usr/bin/env bash
set -euo pipefail

keep pull myapp/production --format env --out .env
# ...rest of an 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). See INTEGRATION.md for where this pattern does and doesn't fit an existing deploy setup.

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 — the read-grants-then-write-wrapped-keys sequence runs inside a single SQLite transaction.
• 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." pull failures (wrong/no grant) are logged too, 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. keep identity init persists the local keypair at ~/.keep/identity.json (mode 0o600, directory 0o700) — not committed anywhere, not transmitted anywhere except the public half.

What was verified end-to-end

Two independent local identities against a real running server (and separately against the built Docker image): registration, a push, pulling as the pusher, pulling as an ungranted second identity (correctly rejected), granting the second identity access without re-pushing, pulling as the now-granted second identity (correctly decrypts the same underlying secret via its own sealed key copy), admin revocation, a subsequent rotation confirming the revoked identity is excluded from the new wrap set, and rejection of both missing and malformed signed-request auth.

One real implementation bug caught during this process, worth recording: Express's req.path inside a sub-router is relative to that router's mount point (e.g. /vaults/x/pull instead of /api/vaults/x/pull), which would have silently mismatched a client that signs the full request path. Fixed by verifying against req.originalUrl (path portion only) instead, which stays consistent regardless of router nesting.

Resolved design decisions

These were open questions at initial implementation; resolved as follows.

Version history: one previous version, not full history

Full N-version history (what Vault/AWS Secrets Manager do) conflates two different needs that deserve different treatment: "I pushed a typo'd value, let me roll back" wants a safety net; "this credential leaked" wants the old value to stop existing anywhere retrievable, which a kept version directly undermines. Resolution: retain exactly the immediately previous payload as a rollback safety net (keep pull --previous), plus an explicit hard-rotate mode (keep push --purge) that skips retention entirely for compromise-driven rotations. Not full history — the two real use cases are served without the complexity (or the confused security story) of an unbounded log of past secret values.

Push authorization: read no longer implies write

The original "read implies write" v1 simplification was a real least-privilege gap: an automated deploy identity that only ever needs to pull a vault also had the power to overwrite it — a compromised read-only consumer could push garbage values or silently exclude other recipients from the next rotation. Fixed rather than deferred, since the cost of closing it is low and the cost of retrofitting it later (once grants without write intent already exist) is higher: vault_grants gained a can_write column (1 by default, so nothing existing changes behavior), enforced in the push handler, with keep grant --read-only to create a read-only grant explicitly.

Per-secret-key granularity: resolved by not building it

The right answer for "different recipients need different subsets of secrets" is splitting into more vaults (myapp/db, myapp/api, each with their own recipient list), not partial-access ACLs within one blob. A vault staying the permission boundary keeps the mental model simple and auditable; per-key wrapping would solve the same problem with materially more complexity for no real gain over just making more vaults. No code change — this documents the escape hatch instead of leaving a dangling TODO.