Add API tokens for scripts and CI (0.57.0)

A session token is the wrong credential for automation. It expires in an hour,
it is minted by typing a password, and revoking it signs every one of that
person's devices out. So automation gets its own credential, revocable on its
own, and showing up in the audit log as itself.

Three decisions worth recording, because each one is a place this could have
been built wrong.

**Only a hash is stored.** This is the opposite call from registry passwords one
release ago, and for a concrete reason: a registry password has to be handed
back to the registry, so it must be recoverable and is encrypted. A token is
only ever compared against, so it does not need to be — and not keeping it is
the difference between leaking the database and leaking everything the database
protects. It is shown once and cannot be recovered; a readable prefix is kept so
rows are still identifiable in the UI and the audit log. The hash is SHA-256,
deliberately not bcrypt: bcrypt is slow to make guessing low-entropy human
passwords expensive, and a token is 256 bits of secrets output, so the cost
would buy nothing and would land on every single API request.

**The scope is not folded into the User object.** get_current_user returns a
session-attached row; downgrading its role in place to represent a read-only
token would be written back to the database the next time anything committed
that user — logout-everywhere does exactly that. So the token row is stashed on
request.state and require_admin consults it, leaving the User untouched. The
same lookup caps a token at its owner's authority rather than trusting the scope
alone, so a demoted admin's token drops to read-only with them and a disabled
account's tokens stop working.

**A token cannot make itself permanent.** Creating tokens and creating users now
require a signed-in session, via a require_session dependency that rejects
token-authenticated requests. Without it, a leaked CI credential could mint a
second one and survive its own revocation — the failure mode where revoking the
leak does nothing. This is the one behaviour change for existing installs:
scripted user creation now needs a login.

The WebSocket routes still take JWTs only. They carry logs, the terminal and the
deploy console, which a CI job has no use for, and leaving them alone keeps the
token surface to the REST API.

19 tests, covering what is stored, that a read token really is read-only while
its owner is an admin, that demoting and disabling the owner both take effect,
expiry, tampering, the throttle on last-used writes, and that a token can
neither mint another nor create a user. Verified end to end against a running
app: two tokens, both scopes, revocation, and no plaintext anywhere in the
database or the list response.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

README.md

@@ -13,6 +13,42 @@ as intuitive as Dockge, as capable as Portainer for Compose workflows.
 > (Auto-update) + Phase 23 (Secrets & configs) + Phase 24 (Design System v2)
 > complete.
 
+## Upgrading to 0.57.0 — API tokens
+
+**Settings → API tokens** issues long-lived bearer tokens for scripts and CI, so
+automation stops needing a password and an hourly login:
+
+```bash
+curl -H "Authorization: Bearer sp_…" https://stackpilot.example/api/stacks
+curl -X POST -H "Authorization: Bearer sp_…" \
+     https://stackpilot.example/api/stacks/immich/update
+```
+
+Each token can be revoked on its own, without signing anyone's browser out.
+
+**Scopes.** A token is either *read-only* or *full access*, and the choice is
+independent of who created it — an admin can hand a monitoring script a token
+that cannot change a thing. A token never outranks its owner either: demote the
+account and its tokens drop to read-only with it, disable the account and they
+stop working.
+
+**A token cannot make itself permanent.** Creating tokens and creating user
+accounts both now require a signed-in session, so a leaked CI credential cannot
+quietly mint a second one that survives the first being revoked. This is the one
+behaviour change for existing installs: if you were scripting user creation, it
+needs a login rather than a token.
+
+**Stored hashed.** Unlike registry passwords — which have to be handed back to a
+registry — a token is only ever compared against, so only a SHA-256 of it is
+kept. It is shown once, when you create it, and cannot be recovered; the UI
+keeps a readable prefix (`sp_AbCdEfGh…`) so you can tell rows apart in the list
+and in the audit log. Tokens record when they were last used, so a stale one is
+easy to spot.
+
+Optional expiry in days, `token.create` / `token.revoke` in the audit log, and
+the whole section is admin-only. The live WebSocket streams (logs, terminal,
+deploy console) still need a session token — a CI job has no use for them.
+
 ## Upgrading to 0.56.0 — private registries, and a silent bug fixed
 
 **Update checks on private images were lying.** StackPilot asks the registry for
@@ -353,6 +389,10 @@ it is what your saved destination credentials are encrypted with.
   compose** converter.
 - **Dashboard** — system resource bar, stack grid with quick actions, and a
   recent-activity audit feed.
+- **API tokens** — long-lived bearer tokens for scripts and CI, read-only or
+  full access, revocable one at a time, stored hashed and shown once. A token
+  can never do more than the account that owns it, and cannot create tokens or
+  users — those need a signed-in session.
 - **Private registries** — a login per registry (Settings → Private registries)
   used both by StackPilot's own update checks and by `docker compose pull`,
   which it reaches through a generated `DOCKER_CONFIG`. Passwords are encrypted
@@ -904,6 +944,17 @@ GET  /api/dashboard/funnel[?refresh=true]   (stack-health funnel, 30s TTL cache)
 GET  /api/dashboard/summary                 (containers, uptime series, ops activity)
 ```
 
+### API token endpoints
+
+```
+GET    /api/auth/tokens        (admin; the token itself is never returned)
+POST   /api/auth/tokens        ({"name","scope":"read"|"admin","expires_in_days"?})
+DELETE /api/auth/tokens/{id}   (revoke)
+```
+
+Authenticate with `Authorization: Bearer sp_…` on any REST endpoint. Managing
+tokens and users is deliberately excluded — those need a session.
+
 ### Private registry endpoints
 
 ```
@@ -929,6 +980,10 @@ GET    /api/stacks/icons/logo/{slug}   (one catalog logo, served from our cache)
 
 - The Docker socket is only ever touched by the backend process; it is never
   proxied to the browser.
+- API tokens are stored as a SHA-256 hash and shown exactly once. SHA-256 rather
+  than bcrypt on purpose: a token is 256 bits of `secrets` output, so guessing
+  is not the threat bcrypt's cost would be defending against — and that cost
+  would land on every API request.
 - Registry passwords and backup-destination credentials are encrypted at rest
   (Fernet, key derived from `SECRET_KEY`). The generated Docker CLI config that
   carries them for `compose pull` is written 0600 inside the data volume.