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](./README.md) and
[IMPLEMENTATION.md](./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:

```sql
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:

```bash
#!/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):

```yaml
- 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.