# 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.