Wire Forge-native release infrastructure

docs/PLATFORM_SERVICES.md

@@ -0,0 +1,99 @@
+# Platform Services
+
+Burrow's next platform layer is split into service boundaries that can be
+enabled independently after their security and rollback checks pass.
+
+## Identity and KMS
+
+`infra/identity` owns Google Cloud KMS and Workload Identity Federation
+resources for the Burrow Google project:
+
+- project id: `project-88c23ce9-918a-470a-b33`
+- project number: `416198671487`
+- key ring: `burrow-identity`
+- intended keys: Authentik signing, SAML CA signing, release signing
+
+The WIF path is for Authentik-backed Forgejo runners. Runners should exchange an
+OIDC token for a short-lived Google credential instead of carrying static
+service-account JSON.
+
+Release storage uses provider-neutral upload wrappers. Garage is the required
+S3-compatible primary target. GCS is the first backup target and remains the
+compatibility source for current
+Sparkle/store follow-on jobs:
+
+- release artifacts: `burrow-net-releases`
+- signed package repositories: `burrow-net-packages`
+- private Nix cache backup: `burrow-net-nix-cache`
+
+Forgejo jobs authenticate to the same Google project through Authentik-backed
+WIF, then use `gcloud storage` for upload/download and Google KMS for release
+and repository signatures. No rclone transport or Google service-account JSON
+key is part of the release path.
+
+`services.burrow.garage` is enabled by the forge host. It provides the host
+activation point for Garage API, static-web, and admin listeners, and
+bootstraps the initial single-node layout plus the `attic`, `burrow-releases`,
+and `burrow-packages` buckets. It creates separate owner/write keys for Attic,
+release artifacts, and package repositories, plus a read-only backup key for
+the scheduled Garage-to-GCS mirror.
+
+Garage is now the primary object-storage surface for release/package uploads and
+the Nix cache. It uses host-local storage for object data and metadata; it does
+not fan out writes to multiple object-store backends. Multi-cloud failover
+should be implemented as explicit Garage bucket mirrors/backups, with GCS as the
+first backup target.
+
+## Nix Cache
+
+`nix.burrow.net` is the Burrow Nix binary cache surface. The forge host runs
+Attic behind Caddy and stores cache chunks in the Garage `attic` bucket through
+Garage's local S3 API. Workers can use `https://nix.burrow.net/burrow` once the
+cache public key is published as `BURROW_NIX_CACHE_PUBLIC_KEY` in Forgejo. The
+host bootstrap also creates `/var/lib/burrow/nix-cache/ci-push-token`; seal it
+as `BURROW_NIX_CACHE_PUSH_TOKEN` before enabling broad cache publication.
+
+## Observability
+
+`graphs.burrow.net` is backed by Grafana with Authentik SSO. The forge host now
+imports `services.burrow.observability`, which starts local Prometheus,
+OpenTelemetry collector, and Jaeger services. NixOS provisions Grafana
+datasources; OpenTofu manages checked-in dashboards for the Burrow overview,
+Headscale, and the broader Prometheus/OpenTelemetry/Jaeger spine.
+
+Jaeger is local-only at first and is queried through Grafana. Headscale metrics
+are scraped locally. Tailscale SaaS metrics are optional until the OAuth
+credential file exists.
+
+## OpenBao
+
+`vault.burrow.net` is the planned OpenBao surface. The repository now has:
+
+- `infra/openbao` for KMS seal wrapping and OpenBao auth/policy resources
+- `services.burrow.openbao` as a disabled-by-default NixOS switch point
+- `Scripts/openbao-tofu.sh` for stack-local OpenTofu operations
+
+OpenBao should not be enabled until the KMS seal key, bootstrap token handling,
+backup/restore procedure, and Authentik roles are verified.
+
+## Jitsi Meet
+
+`meet.burrow.net` is the planned Jitsi Meet surface. The repository now has
+`services.burrow.jitsi` as a disabled-by-default NixOS switch point.
+
+Jitsi is not just an HTTP service. The rollout needs DNS, TLS, XMPP/prosody
+state, and an explicit UDP media-port decision before activation.
+
+## Mail and Webmail
+
+`inbox.burrow.net` is the intended webmail surface. Stalwart is the planned mail
+server, but this flake does not currently expose the expected Stalwart NixOS
+option. Forward Email remains the current production mail path until the
+Stalwart module name, ports, DKIM rotation, backup target, spam policy, and
+migration steps are pinned in a follow-up BEP update.
+
+## MCP Hub
+
+The MCP hub should be extracted to `compatible.systems/burrow/mcp-hub`. Until
+that repository exists, `services/mcp-hub/` records the extraction boundary and
+tool inventory.