From 071b7e9b01e41d4048b1bbb3d9caaac4c8a526de Mon Sep 17 00:00:00 2001
From: Anders Betts <anders.betts@gmail.com>
Date: Thu, 17 Sep 2026 21:48:00 +0200
Subject: Add token login to bokfctl and enforce admin scope for tokens

- bokfctl: --token / BOKFD_TOKEN via client_token_login
- tokens must carry the admin scope for admin commands (was bypassed)
- docs: token-based snapshot for restic backups
---
 docs/DEPLOY.md   | 32 +++++++++++++++++++++++++++++++-
 docs/PROTOCOL.md |  4 +++-
 2 files changed, 34 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md
index 8d36453..eb3ec1c 100644
--- a/docs/DEPLOY.md
+++ b/docs/DEPLOY.md
@@ -170,12 +170,42 @@ Develop against this org; agents get their own API token
 
 ## Backup and restore
 
+`backup.snapshot` makes a consistent copy of the live WAL database with
+`VACUUM INTO`; the result lands in `var/db/backup/` as
+`bokfd-<timestamp>.db` (the response carries its SHA-256). Interactive:
+
 ```sh
 docker compose exec -e BOKFD_PASSWORD='<pw>' bokfd \
     bokfctl --user admin backup.snapshot
-ls var/db/backup              # <db>-<timestamp>.db + .sha256
+ls var/db/backup
+```
+
+For unattended backups (restic, cron) use an admin-scoped token instead of
+the password, created once:
+
+```sh
+docker compose exec -e BOKFD_PASSWORD='<pw>' bokfd \
+    bokfctl --user admin token.create '{"label":"backup","scopes":["admin"]}'
+# store the token (shown once) in a root-only file, e.g. /etc/bokf/bokfd-backup.env:
+#   BOKFD_TOKEN=bokf_...
 ```
 
+Then, before every restic run: take a snapshot through the daemon and let
+restic read only the snapshots — never the live database:
+
+```sh
+. /etc/bokf/bokfd-backup.env
+docker compose --project-directory /mnt/data/bokf exec -T -e BOKFD_TOKEN \
+    bokfd bokfctl backup.snapshot >/dev/null
+find /mnt/data/bokf/var/db/backup -name 'bokfd-*.db' -mtime +14 -delete
+restic backup --exclude='/mnt/data/bokf/var/db/bokfd.db*' \
+    --exclude='/mnt/data/bokf/var/run' /mnt/data/bokf
+```
+
+The WAL and shared-memory files (`bokfd.db-wal`, `bokfd.db-shm`) must be
+excluded together with the main file; an inconsistent copy of a live SQLite
+database is worse than no backup.
+
 Restore:
 
 ```sh
diff --git a/docs/PROTOCOL.md b/docs/PROTOCOL.md
index e9c4331..25c9250 100644
--- a/docs/PROTOCOL.md
+++ b/docs/PROTOCOL.md
@@ -95,7 +95,9 @@ and returns an opaque, high-entropy session id:
 - A token is bound to one user and one org, has scopes (`read`, `write`,
   `admin`) and is an independent audit actor (label shown in history).
 - Tokens are the intended mechanism for agents and for accountant/viewer
-  access. They can be revoked immediately (`token.revoke`).
+  access. They can be revoked immediately (`token.revoke`). Scopes are
+  enforced for every command, including admin commands: `backup.snapshot`
+  and `user.*` need a token with the `admin` scope.
 
 ### 4.3 Roles and permissions
 
-- 
cgit v1.3