feature: the router serves S3-compatible object storage with versitygw, with one S3 account per user and buckets owned by users.

ADR.md

@@ -1278,3 +1278,44 @@ method.
 Consequences: A change to one family of paths touches one module and the routing in `handler`.
 State shared between requests, such as the open shells, lives in the module that owns it; other
 modules change it and never rebind it.
+
+## ADR-48: Object storage is versitygw with its POSIX backend, one S3 account per user
+
+Status: Accepted
+
+Context: The router's users and services want S3-compatible storage for backups of other
+systems, Terraform state and artifacts. Ubuntu 24.04 has no S3 server; its rclone 1.60 predates
+`rclone serve s3`. versitygw (Apache-2.0) is an S3 gateway that keeps buckets as plain folders
+(POSIX backend) and has its own IAM. It publishes `.deb` files for amd64 and arm64, and an Admin
+API, signed like S3, to manage accounts and bucket owners. Its LDAP IAM needs each secret stored in
+plain text in the directory. S3 signs with a shared secret, so the directory's passwords cannot
+serve as S3 credentials.
+
+Decision:
+
+- **Installation:** versitygw is pinned to a version and the SHA-256 of each architecture's
+  `.deb` (`vpnrouter_s3`). It is downloaded and installed on demand by
+  `vpn-router-install@s3.service`.
+- **Service:** `vpn-router-s3.service` runs it with the internal IAM in
+  `/var/lib/vpn-router/s3/iam` and the buckets in `/var/lib/vpn-router/s3/data`. Its S3 API and
+  its Admin API are on loopback ports, and Caddy serves the S3 API at
+  `https://<wan.local_fqdn>:<s3.port>` with path-style addresses, which need no wildcard name.
+- **Root keys:** setup makes them once, in `/etc/vpn-router/s3.env`.
+- **Calls:** the router calls the Admin API and S3's DeleteBucket with its own Signature Version 4
+  signer, from the standard library, so no secret appears on a command line.
+- **Accounts:**
+  - Each user or service account has at most one S3 account, of the role `user`, so a bucket's
+    owner is a user.
+  - `/etc/vpn-router/s3-accounts.json` records the owner, the key and the secret.
+  - The account follows its user: an unknown secret while the user is disabled, its own secret
+    when the user is enabled, and removal with the user.
+
+Consequences:
+
+- **Accounts:** a user has one key pair; replacing its secret replaces it for every client.
+- **Secrets:** they are kept by the router in two root-only files, versitygw's IAM and the
+  record, as S3 needs them to check signatures.
+- **Ownership:** a removed user's buckets keep the account as their owner until an admin gives
+  them to another user.
+- **Backups and upgrades:** the buckets are in backups only with `backup.s3`. A new versitygw
+  comes with a new vpn-router release, not from apt.