keep/PROPOSAL-announce-and-agent.md

Proposal: announce + a self-deploying agent, with a no-keep fallback

Status: proposed, not built. Self-contained — written so a fresh agent with no prior conversation context can pick this up and implement it without anything explained first.

Context (read this first)

Full background on keep is in README.md and IMPLEMENTATION.md — read both before touching code. The relevant existing pieces for this proposal:

• src/server/db.ts — SQLite (better-sqlite3, WAL mode). vaults, recipients, vault_grants, vault_grants_previous, access_log.
• src/server/routes.ts — recipient-authenticated (signed-request) routes: push, pull, grant, log, plus exists and recipients (both used by the CLI to compute who to re-wrap for).
• src/server/auth.ts — requireRecipientAuth (Ed25519 signature over method+path+timestamp+body-hash, verified against req.originalUrl with the query string stripped — see IMPLEMENTATION.md's "What was verified end-to-end" for a bug that already bit this exact mechanism once) and requireAdminAuth (X-Admin-Password header).
• src/cli/ — identity.ts, recipient.ts, vault.ts, signedFetch.ts (note: signedFetch's path param must never include a query string — see the comment there for why).
• scripts/deploy.sh — pulls <project>/<env> from keep into $DEPLOY_ROOT/<project>/.env, then docker compose up -d. Assumes the vault already exists and this machine already has a grant on it.
• .gitea/workflows/docker.yml (present in keep, wisp, npm-statuspage) — builds and pushes an image to the Gitea container registry on every push to main. Does not currently deploy anything — that's a manual step today.

Motivation

The CI workflow already produces a fresh image on every push. Deployment is still a manual "SSH in and run the deploy script" step. The obvious fix — CI SSHes into the VPS and runs the deploy — was considered and rejected: it means a standing SSH credential with production-deploy rights sits in Gitea's CI secrets, reachable by whatever's executing on the shared runner across all ~17 projects it builds. A compromised build step in any one project could then reach every other project's deploy target. That's a real regression from where keep already left things (see IMPLEMENTATION.md's resolved "read no longer implies write" — the whole point was not concentrating reach into one identity).

The fix that doesn't reintroduce that problem: reverse the direction. CI never reaches into a VPS. Instead, CI tells keep "there's a new image for this project," and each VPS — which already has to run something locally to redeploy itself — polls keep for that signal and acts on it locally, using an identity and grant it already legitimately holds. keep's server never executes anything remotely; it stays a pure relay, same posture as everything else it does.

Not every project will have been migrated to keep yet. Bootstrapping a project (register a recipient, grant it, push the first vault) is a real, deliberate step per project, and there'll be a period — maybe a long one — where some of the ~17 projects have it and some don't. The self-deploying agent has to work identically well for both, defaulting to exactly what happens today (a plain docker compose pull && up -d against whatever's already on disk) for anything not yet bootstrapped, rather than either blocking deploys entirely or hard-failing on missing vaults.

Design

1. announce — a distinct verb from push/pull

An image tag isn't a secret. It doesn't belong inside the encrypted vault payload alongside real credentials — that's a category mismatch (deploy metadata living inside a secrets blob), not just an implementation convenience either way. announce is its own small mechanism:

CREATE TABLE IF NOT EXISTS vault_announcements (
  vault_key     TEXT PRIMARY KEY,
  tag           TEXT NOT NULL,
  announced_at  INTEGER NOT NULL,
  announced_by  TEXT NOT NULL   -- recipient_id
);

One row per vault — like the vault's own one-previous-version retention, this is "latest known state," not a history. If a real audit trail of every announce is wanted later, access_log already records the action; this table is just the fast-path "what's the current tag" read, kept separate from the log on purpose (reading current state back out of an append-only log is the wrong tool for that job — same reasoning IMPLEMENTATION.md already gives for why vault_grants_previous is a real table and not a log replay).

2. API

POST /api/vaults/:key/announce   -- { tag: string } — requires ANY grant on the vault (read-only is enough; announcing isn't a secrets mutation)
GET  /api/vaults/:key/announce   -- { tag, announcedAt, announcedBy } | 404 if nothing announced yet — requires a grant, same as pull

Both go through requireRecipientAuth, identical shape to the existing routes. POST only requires a grant (not write) — reuse hasGrant, not hasWriteGrant — since this isn't a mutation of the vault's secret content, just a signal, and CI's identity for a project should be able to stay read-only even after this feature exists. (This is worth stating explicitly since a naive implementation might reach for hasWriteGrant by analogy with push — resist that; it would silently widen CI's required permissions for no real reason.)

3. CLI

keep announce <vault> --tag <tag>     -- POST, requires a grant on <vault>
keep watch <vault> [--interval 60]    -- polls GET .../announce every N seconds, prints the tag on change, exits nonzero if the vault doesn't exist / no grant (see fallback below)

keep watch is deliberately dumb — plain polling, not a websocket or long-poll. Matches npm-statuspage's existing polling pattern, and a 60-second detection lag for a deploy is fine. Don't build push-based notification for this; it's more machinery for a problem polling already solves adequately.

4. The agent script and its fallback

This is the part the fallback requirement is actually about. One script per VPS, running on a timer (systemd timer or cron, not a long-lived daemon — matches this project's bias toward simple, restartable, stateless-between-runs tooling), one invocation per project it's responsible for:

#!/usr/bin/env bash
# agent.sh <project> [env] — self-deploy check for one project. Meant to
# run on a schedule (cron/systemd timer), not as a daemon.
set -euo pipefail

project="${1:?usage: agent.sh <project> [env]}"
env="${2:-production}"
root="${DEPLOY_ROOT:-/opt/docker}"
dir="$root/$project"
vault="$project/$env"

if [ ! -d "$dir" ]; then
  echo "error: $dir does not exist" >&2
  exit 1
fi

cd "$dir"

# Best-effort: does this machine have a working keep grant on this
# vault at all? If not — project not yet bootstrapped onto keep, or
# this box was never granted access — fall through to the plain path.
# Every keep call below is allowed to fail; failure just means "keep
# isn't available for this project," not "the deploy is broken."
if keep pull "$vault" --out .env.new 2>/dev/null; then
  mv .env.new .env
  docker compose pull -q
  docker compose up -d
else
  rm -f .env.new
  # No keep vault (or no grant) for this project — deploy exactly as it
  # would have worked before keep existed: whatever .env is already
  # sitting here (possibly none, if the compose file doesn't need one),
  # plain pull + up. This path must never hard-fail just because keep
  # doesn't know about this project.
  docker compose pull -q
  docker compose up -d
fi

Notice announce/watch aren't actually load-bearing in this version — the agent above just runs on a timer and lets docker compose pull figure out for itself whether there's anything new (a no-op if the digest hasn't changed, idempotent either way). That's deliberate: a dumb periodic compose pull && up -d is already a complete, correct baseline deploy strategy on its own, keep-bootstrapped or not. announce sits on top as an optimization for bootstrapped projects, not a requirement for the agent to function — see the next section.

5. Where announce/watch actually earn their keep

For a project that has been bootstrapped, there are two independent benefits, worth keeping conceptually separate:

• Secrets sourcing — keep pull instead of a hand-placed .env. Available the moment a vault exists and this machine has a grant. Already true of deploy.sh today; unchanged by this proposal.
• Fast, precise redeploy — instead of every VPS blindly polling docker compose pull on a fixed timer for every project it hosts (harmless, but imprecise and up to a full interval late), a bootstrapped project's agent can keep watch and react within seconds of the CI announce step, and only for the project that actually changed rather than sweeping all of them.

A fancier version of the agent script could branch on keep watch succeeding vs. not to decide between "wait for a watch event" and "just poll on the dumb timer" — deliberately not speccing that split here. Ship the dumb-timer-plus-opportunistic-keep-pull version first (above); it already satisfies the fallback requirement completely, and whether the watch-driven fast path is worth the added complexity should be judged after living with the dumb version for a while, not designed in advance of any real signal that polling latency is actually a problem.

6. CI workflow addition

One step appended to the existing docker.yml, after the existing build-and-push step, best-effort (must not fail the build if this project hasn't been bootstrapped onto keep yet):

- name: announce to keep
  continue-on-error: true
  run: keep announce myapp/production --tag ${{ steps.meta.outputs.short_sha }}

continue-on-error: true is load-bearing, not incidental — a project without a keep identity registered yet must still build and push its image successfully. This step failing should be silent/expected for any not-yet-bootstrapped project, not a red X on the workflow.

Security considerations

• announce leaks a little more than push/pull did: the tag itself is now server-visible (previously, if you were being strict, even the fact that a new image existed wasn't something keep needed to know). This is an intentional, accepted tradeoff — a git short-SHA or version tag isn't sensitive, and the whole feature only works if keep can see it.
• Requiring only a read grant (not write) to announce means a compromised read-only CI identity could announce a false tag, pointing the fleet at an attacker-chosen image — worth flagging even though keep never pulls or runs that image itself, only relays the string. The actual docker compose pull on each VPS still pulls from the configured registry using the tag it was told, so this is equivalent in severity to that CI identity's build step being compromised in the first place (it could already push a bad image under a legitimate tag) — not a new capability, just worth stating plainly rather than leaving implicit.
• The fallback path must never silently downgrade a bootstrapped project to running with a stale .env because of a transient keep outage. As written, keep pull failing for any reason (network blip, keep server down, not just "not bootstrapped") falls through to "deploy with whatever .env is already on disk" — for an already-bootstrapped project, that's the previous keep pull's output, still valid, not a downgrade. This only becomes a real problem if a bootstrapped project's very first deploy attempt coincides with keep being unreachable, in which case there's no .env on disk yet at all and docker compose up will fail for the mundane reason that required env vars are missing — a loud, obvious failure, not a silent wrong-secrets one.

Open questions

• Per-project agent scheduling — one cron line per project, or one script that loops over every directory under $DEPLOY_ROOT? Leaning toward one-line-per-project (explicit, greppable in crontab, no surprise when a new project directory silently starts getting picked up) over auto-discovery.
• Does watch ever get used, or does the dumb-timer version turn out to be good enough forever? Deliberately left unbuilt (see "Where announce/watch actually earn their keep") until there's a real signal it's worth the added complexity.
• Multi-VPS fan-out for one project — if a project ever runs on more than one box, announce already supports that for free (any number of agents can poll the same vault's announce endpoint), but this hasn't been exercised and might reveal something not accounted for here.