chore: remove go.work

vantagectl/ becomes the root of gitea.hostxtra.co.uk/vantage/vantage-ctl.
The command keeps the name vantagectl; only the repository and the image
path change, to vantage/vantage-ctl.

chart-release.yml's render checks are repointed at the new image. The
chart itself has no default backup.image and fails loudly without one, so
an existing cluster keeps working until someone changes the value.

go.work stays, now with a single use ./server entry: without it a go.work
further up the developer's filesystem is picked up instead.

.gitattributes

@@ -0,0 +1 @@
+graphify-out/graph.json merge=graphify

.gitea/workflows/agent-release.yml

@@ -1,117 +0,0 @@
-name: Agent Release
-
-on:
-    push:
-        tags:
-            - "agent/v*"
-
-jobs:
-    build:
-        runs-on: ubuntu-docker
-        container: node:26
-        steps:
-            - name: Checkout
-              uses: actions/checkout@v4
-
-            - name: Set up Go
-              uses: actions/setup-go@v5
-              with:
-                  go-version: "1.26"
-                  cache: true
-                  cache-dependency-path: agent/go.sum
-
-            - name: Extract version
-              id: version
-              run: echo "VERSION=${GITHUB_REF_NAME#agent/}" >> $GITHUB_OUTPUT
-
-            - name: Build
-              working-directory: agent
-              env:
-                  VERSION: ${{ steps.version.outputs.VERSION }}
-              run: |
-                  mkdir -p dist
-                  GOOS=linux GOARCH=amd64 go build \
-                    -ldflags="-s -w -X main.Version=${VERSION}" \
-                    -o dist/vantage-agent-linux-amd64 ./cmd
-                  GOOS=linux GOARCH=arm64 go build \
-                    -ldflags="-s -w -X main.Version=${VERSION}" \
-                    -o dist/vantage-agent-linux-arm64 ./cmd
-                  GOOS=windows GOARCH=amd64 go build \
-                    -ldflags="-s -w -X main.Version=${VERSION}" \
-                    -o dist/vantage-agent-windows-amd64.exe ./cmd
-
-            - name: Checksums
-              working-directory: agent/dist
-              run: sha256sum vantage-agent-linux-amd64 vantage-agent-linux-arm64 vantage-agent-windows-amd64.exe > checksums.txt
-
-            - name: Create release
-              uses: https://gitea.com/actions/gitea-release-action@v1
-              with:
-                  token: ${{ secrets.RELEASE_TOKEN }}
-                  files: |
-                      agent/dist/vantage-agent-linux-amd64
-                      agent/dist/vantage-agent-linux-arm64
-                      agent/dist/vantage-agent-windows-amd64.exe
-                      agent/dist/checksums.txt
-
-    msi:
-        needs: build
-        runs-on: windows-2022
-        steps:
-            - name: Checkout
-              uses: actions/checkout@v4
-
-            - name: Set up Go
-              uses: actions/setup-go@v5
-              with:
-                  go-version: "1.26"
-                  cache: true
-                  cache-dependency-path: agent/go.sum
-
-            - name: Extract version
-              id: version
-              shell: pwsh
-              run: |
-                  $v = "${{ github.ref_name }}" -replace '^agent/v', ''
-                  "VERSION=$v" | Out-File -Append $env:GITHUB_OUTPUT
-                  # MSI ProductVersion must be numeric x.x.x.x
-                  "MSIVERSION=$v.0" | Out-File -Append $env:GITHUB_OUTPUT
-
-            - name: Build agent exe
-              working-directory: agent
-              shell: pwsh
-              env:
-                  VERSION: ${{ steps.version.outputs.VERSION }}
-              run: |
-                  $env:GOOS = "windows"; $env:GOARCH = "amd64"
-                  go build -ldflags="-s -w -X main.Version=$env:VERSION" -o ../installer/vantage-agent-windows-amd64.exe ./cmd
-
-            - name: Install WiX
-              shell: pwsh
-              run: dotnet tool install --global wix --version 5.*
-
-            - name: Build MSI
-              working-directory: installer
-              shell: pwsh
-              run: |
-                  $env:PATH = "$env:PATH;$env:USERPROFILE\.dotnet\tools"
-                  wix build vantage-agent.wxs -d Version=${{ steps.version.outputs.MSIVERSION }} -o vantage-agent.msi
-                  (Get-FileHash vantage-agent.msi -Algorithm SHA256).Hash.ToLower() + "  vantage-agent.msi" | Out-File -Encoding ascii checksums-msi.txt
-
-            - name: Attach MSI to release
-              working-directory: installer
-              shell: pwsh
-              env:
-                  TOKEN: ${{ secrets.RELEASE_TOKEN }}
-              run: |
-                  $api = "${{ github.server_url }}/api/v1/repos/${{ github.repository }}"
-                  $tag = [uri]::EscapeDataString("${{ github.ref_name }}")
-                  $headers = @{ Authorization = "token $env:TOKEN" }
-                  # gitea-release-action can't find a slashed tag, so append via the API directly
-                  $rel = Invoke-RestMethod -Headers $headers -Uri "$api/releases/tags/$tag"
-                  foreach ($f in "vantage-agent.msi", "checksums-msi.txt") {
-                      $name = [uri]::EscapeDataString($f)
-                      Invoke-RestMethod -Headers $headers -Method Post -InFile $f `
-                        -ContentType "application/octet-stream" `
-                        -Uri "$api/releases/$($rel.id)/assets?name=$name"
-                  }

.gitea/workflows/chart-release.yml

@@ -0,0 +1,239 @@
+name: Chart Release
+
+on:
+    # Every push that touches the chart is validated. Publishing is separate and
+    # deliberate: a chart version is immutable in the registry once pushed, so
+    # it must come from a tag someone chose, not from whatever landed on main.
+    # No `paths` filter on push, deliberately. A paths filter applies to tag
+    # pushes too, so tagging a commit that happened not to touch the chart
+    # would skip the publish entirely — a release that silently does nothing.
+    # Validation is seconds of helm rendering; running it on every push to main
+    # is cheaper than that failure mode.
+    push:
+        branches:
+            - main
+        tags:
+            - "chart/v*"
+    pull_request:
+        paths:
+            - "deploy/chart/**"
+    workflow_dispatch:
+
+env:
+    CHART_DIR: deploy/chart/vantage
+    HELM_VERSION: v3.16.3
+
+jobs:
+    chart:
+        runs-on: ubuntu-docker
+        container: alpine:3.21
+        steps:
+            # git for actions/checkout, curl for both the Helm download and the
+            # registry upload, tar because the Helm tarball is not self-extracting.
+            - name: Setup
+              run: apk add --no-cache bash curl git tar nodejs npm
+
+            - name: Install Helm
+              run: |
+                  set -eu
+                  curl -fsSL "https://get.helm.sh/helm-${HELM_VERSION}-linux-amd64.tar.gz" \
+                    | tar -xz -C /tmp linux-amd64/helm
+                  mv /tmp/linux-amd64/helm /usr/local/bin/helm
+                  helm version --short
+
+            - name: Checkout
+              uses: actions/checkout@v4
+
+            - name: Lint
+              run: helm lint "$CHART_DIR"
+
+            # Rendering is the real test. `helm lint` accepts a chart whose
+            # templates fail to execute, and every guard in this chart is a
+            # template `fail` that only fires during rendering.
+            - name: Render default values
+              run: helm template test "$CHART_DIR" > /dev/null
+
+            - name: Render a multi-replica install
+              run: |
+                  helm template test "$CHART_DIR" \
+                    --set server.replicaCount=3 \
+                    --set web.replicaCount=3 > /dev/null
+
+            # The reaper deletes whole instances, so "does this env appear only
+            # in cloud mode" is worth asserting rather than eyeballing.
+            - name: Check the reaper is cloud-only
+              run: |
+                  set -eu
+                  if helm template test "$CHART_DIR" | grep -q FREE_INSTANCE_REAP_AFTER; then
+                      echo "FREE_INSTANCE_REAP_AFTER is set on a self-hosted render"
+                      exit 1
+                  fi
+                  if ! helm template test "$CHART_DIR" \
+                        --set server.env.deploymentType=cloud \
+                      | grep -q FREE_INSTANCE_REAP_AFTER; then
+                      echo "FREE_INSTANCE_REAP_AFTER is missing from a cloud render"
+                      exit 1
+                  fi
+                  echo "ok: reaper configured in cloud mode only"
+
+            - name: Render with backups enabled
+              run: |
+                  helm template test "$CHART_DIR" \
+                    --set backup.enabled=true \
+                    --set backup.image=gitea.hostxtra.co.uk/vantage/vantage-ctl:latest \
+                    --set backup.pvcName=vantage-backups > /dev/null
+
+            - name: Render against external Redis and MongoDB
+              run: |
+                  helm template test "$CHART_DIR" \
+                    --set redis.enabled=false \
+                    --set redis.addr=redis.example.com:6379 \
+                    --set mongo.enabled=false \
+                    --set server.env.mongoUri=mongodb://mongo.example.com:27017/vantage > /dev/null
+
+            - name: Render with the Traefik ingress
+              run: |
+                  helm template test "$CHART_DIR" \
+                    --set ingress.enabled=true \
+                    --set ingress.web.host=vantage.example.com \
+                    --set ingress.grpc.host=agents.example.com \
+                    --set ingress.tls.certResolver=letsencrypt \
+                    --set server.env.grpcHost=agents.example.com:443 > /dev/null
+
+            # The shape the cloud deployment actually uses: a wildcard tenant
+            # namespace, /api and /auth routed at the edge, and no apex — that
+            # belongs to the marketing site, which this chart does not deploy.
+            - name: Render a wildcard host with edge-routed API paths
+              run: |
+                  helm template test "$CHART_DIR" \
+                    --set ingress.enabled=true \
+                    --set 'ingress.web.host=*.vantage.example.com' \
+                    --set ingress.api.enabled=true \
+                    --set ingress.grpc.host=agents.example.com \
+                    --set server.env.grpcHost=agents.example.com:443 \
+                    --set ingress.tls.secretName=vantage-tls \
+                    --set ingress.tls.grpcSecretName=agents-tls > /dev/null
+
+            # The guards are load-bearing, so their absence is a regression the
+            # same way a broken render is. Each of these must fail.
+            - name: Check the guards still refuse bad values
+              run: |
+                  set -eu
+
+                  refuses() {
+                      desc="$1"; shift
+                      if helm template test "$CHART_DIR" "$@" > /dev/null 2>&1; then
+                          echo "GUARD MISSING: $desc was accepted"
+                          exit 1
+                      fi
+                      echo "ok: refused $desc"
+                  }
+
+                  refuses "mongo disabled with an in-chart URI" \
+                      --set mongo.enabled=false
+                  refuses "redis disabled with no external address" \
+                      --set redis.enabled=false
+                  refuses "multiple replicas on a ReadWriteOnce volume" \
+                      --set server.replicaCount=2 --set server.persistence.enabled=true
+                  refuses "ingress with no web host" \
+                      --set ingress.enabled=true
+                  refuses "edge-routed API with an empty path list" \
+                      --set ingress.enabled=true \
+                      --set ingress.web.host=vantage.example.com \
+                      --set ingress.grpc.enabled=false \
+                      --set ingress.api.enabled=true \
+                      --set 'ingress.api.paths=null'
+                  refuses "gRPC ingress with no host" \
+                      --set ingress.enabled=true \
+                      --set ingress.web.host=vantage.example.com \
+                      --set server.env.grpcHost=agents.example.com:443
+                  refuses "an ingress that leaves /api unrouted" \
+                      --set ingress.enabled=true \
+                      --set ingress.web.host=vantage.example.com \
+                      --set ingress.grpc.enabled=false \
+                      --set ingress.api.enabled=false
+                  refuses "gRPC ingress while grpcHost is still in-cluster" \
+                      --set ingress.enabled=true \
+                      --set ingress.web.host=vantage.example.com \
+                      --set ingress.grpc.host=agents.example.com
+                  refuses "backup enabled with no pvcName" \
+                      --set backup.enabled=true \
+                      --set backup.image=gitea.hostxtra.co.uk/vantage/vantage-ctl:latest
+                  refuses "backup enabled with no image" \
+                      --set backup.enabled=true \
+                      --set backup.pvcName=vantage-backups
+
+            - name: Read the chart version
+              id: chart
+              run: |
+                  set -eu
+                  VERSION="$(grep '^version:' "$CHART_DIR/Chart.yaml" | awk '{print $2}')"
+                  echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+                  echo "chart version is $VERSION"
+
+            # Chart.yaml is the source of truth for the version; the tag only
+            # says "publish this one". A mismatch is a mistake worth stopping
+            # for — the alternative is stamping the tag over Chart.yaml, which
+            # leaves the repository disagreeing with what was published.
+            - name: Check the tag matches Chart.yaml
+              if: startsWith(github.ref, 'refs/tags/chart/v')
+              run: |
+                  set -eu
+                  TAG_VERSION="${GITHUB_REF_NAME#chart/v}"
+                  CHART_VERSION="${{ steps.chart.outputs.version }}"
+                  if [ "$TAG_VERSION" != "$CHART_VERSION" ]; then
+                      echo "tag chart/v$TAG_VERSION does not match Chart.yaml version $CHART_VERSION"
+                      echo "bump version: in $CHART_DIR/Chart.yaml, or retag."
+                      exit 1
+                  fi
+
+            - name: Package
+              run: |
+                  set -eu
+                  mkdir -p dist
+                  helm package "$CHART_DIR" --destination dist
+                  ls -l dist
+
+            - name: Publish to the Gitea chart registry
+              if: startsWith(github.ref, 'refs/tags/chart/v')
+              env:
+                  # github.server_url is this Gitea instance, so the registry
+                  # host needs no variable of its own and cannot drift from it.
+                  REGISTRY: ${{ github.server_url }}/api/packages/${{ github.repository_owner }}/helm/api/charts
+                  # The same pair server-deploy.yml uses for `docker login`.
+                  # RELEASE_TOKEN, not REGISTRY_PASSWORD: the latter is named in
+                  # the docs but set by no workflow, and an unset secret becomes
+                  # an empty password, which Gitea reports as "Failed to
+                  # authenticate user" rather than as a missing credential.
+                  REGISTRY_USER: ${{ secrets.REGISTRY_USER }}
+                  REGISTRY_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+                  CHART_VERSION: ${{ steps.chart.outputs.version }}
+              run: |
+                  set -eu
+                  PKG="dist/vantage-${CHART_VERSION}.tgz"
+                  test -f "$PKG"
+
+                  # Checked explicitly, because the failure it prevents is a
+                  # 401 that looks like a permissions problem on the token that
+                  # was never sent.
+                  if [ -z "${REGISTRY_USER}" ] || [ -z "${REGISTRY_TOKEN}" ]; then
+                      echo "REGISTRY_USER or RELEASE_TOKEN is not set on this repository."
+                      echo "RELEASE_TOKEN needs the write:package scope to publish a chart."
+                      exit 1
+                  fi
+
+                  echo "publishing to ${REGISTRY} as ${REGISTRY_USER}"
+
+                  # --fail-with-body so an HTTP error is a failed step with the
+                  # server's explanation, rather than a green run that published
+                  # nothing. A repeated version is rejected by the registry;
+                  # that is the intended behaviour, not something to retry past.
+                  curl --fail-with-body -sS \
+                       --user "${REGISTRY_USER}:${REGISTRY_TOKEN}" \
+                       -X POST \
+                       --upload-file "$PKG" \
+                       "$REGISTRY"
+
+                  echo "published vantage ${CHART_VERSION}"
+                  echo "  helm repo add vantage ${{ github.server_url }}/api/packages/${{ github.repository_owner }}/helm"
+                  echo "  helm install vantage vantage/vantage --version ${CHART_VERSION}"

.gitea/workflows/server-deploy.yml

@@ -4,16 +4,105 @@ on:
     push:
         branches:
             - main
+    # Manual runs rebuild everything: there is no "before" commit to diff
+    # against, which the change detection below treats as "build it all". That
+    # is also the escape hatch for a repo VARIABLE change — editing HQ_URL
+    # pushes no commit, so nothing would rebuild on its own.
+    workflow_dispatch:
 
 jobs:
     deploy:
         runs-on: ubuntu-docker
         container: docker:dind
         steps:
-            - name: Setup Node
-              run: apk add --update nodejs npm
+            # git is needed twice over: actions/checkout clones with it, and the
+            # change detection below diffs with it.
+            - name: Setup
+              run: apk add --update nodejs npm git
+
             - name: Checkout
               uses: actions/checkout@v4
+              with:
+                  # The default shallow clone has one commit, which cannot be
+                  # diffed against the previous push.
+                  fetch-depth: 0
+
+            - name: Work out what changed
+              id: changed
+              run: |
+                  set -eu
+
+                  BEFORE="${{ github.event.before }}"
+                  ZERO="0000000000000000000000000000000000000000"
+
+                  # Build everything whenever the comparison cannot be trusted:
+                  # a manual run, a brand-new branch, or a force-push whose old
+                  # head is no longer in the repository. Listing every tracked
+                  # file makes every filter below match, so there is no second
+                  # code path to keep correct.
+                  if [ -z "$BEFORE" ] || [ "$BEFORE" = "$ZERO" ] || ! git cat-file -e "${BEFORE}^{commit}" 2>/dev/null; then
+                      echo "No usable base commit — building every image."
+                      git ls-files > /tmp/changed.txt
+                  else
+                      git diff --name-only "$BEFORE" HEAD > /tmp/changed.txt
+                  fi
+
+                  echo "--- changed files ---"
+                  cat /tmp/changed.txt
+                  echo "---------------------"
+
+                  # A change to the workflow itself can change a build arg, and
+                  # a build arg is baked into the image, so it rebuilds all.
+                  if grep -qE '^\.gitea/workflows/' /tmp/changed.txt; then
+                      ALL=1
+                  else
+                      ALL=0
+                  fi
+
+                  flag() {
+                      name="$1"
+                      pattern="$2"
+                      if [ "$ALL" = "1" ] || grep -qE "$pattern" /tmp/changed.txt; then
+                          echo "$name=true" >> "$GITHUB_OUTPUT"
+                          echo "build $name"
+                      else
+                          echo "$name=false" >> "$GITHUB_OUTPUT"
+                          echo "skip  $name"
+                      fi
+                  }
+
+                  # shared/ is gone from this repository: it is the private
+                  # module gitea.hostxtra.co.uk/vantage/vantage-shared, pinned
+                  # per service in its own go.mod. A change over there reaches
+                  # a service when somebody bumps that pin, which is a commit
+                  # under the service's own directory and so already matches
+                  # below. There is no longer a directory whose change fans out
+                  # to three images, and no longer a way to ship a service
+                  # against a shared/ it was never built with.
+                  #
+                  # proto/ is gone too. It documents the wire types, and it
+                  # moved to sit beside the hand-written pb it describes, so
+                  # that a message added to one is added to the other in the
+                  # same commit. Nothing here reads it.
+                  flag server    '^(server/|default_steps/|go\.work)'
+
+                  # web/ uses its own directory as the build context, so
+                  # nothing outside it can affect it. It is the only front end
+                  # left here: the marketing site and the docs went to
+                  # vantage-site and vantage-docs, the HQ console to
+                  # vantage-admin.
+                  flag web       '^web/'
+
+            # vantage-shared is private, so every Go build below needs a
+            # credential for it. A netrc is written once here rather than a
+            # token being passed as a build arg, which would survive in the
+            # builder layer's history.
+            - name: Write the module fetch credential
+              run: |
+                  umask 077
+                  printf 'machine gitea.hostxtra.co.uk\nlogin %s\npassword %s\n' \
+                    "${{ secrets.REGISTRY_USER }}" "${{ secrets.RELEASE_TOKEN }}" \
+                    > "$HOME/.netrc"
 
             - name: Log in to registry
               run: |
@@ -21,17 +110,48 @@ jobs:
                     docker login ${{ vars.DOCKER_HOST }} \
                       -u "${{ secrets.REGISTRY_USER }}" --password-stdin
 
+            - name: Set up Go
+              if: steps.changed.outputs.server == 'true'
+              uses: actions/setup-go@v5
+              with:
+                  go-version: "1.26"
+                  cache: true
+                  cache-dependency-path: server/go.sum
+              env:
+                  GOPRIVATE: gitea.hostxtra.co.uk/*
+
+            - name: Verify the OpenAPI document is current
+              if: steps.changed.outputs.server == 'true'
+              env:
+                  GOPRIVATE: gitea.hostxtra.co.uk/*
+              run: |
+                  go install github.com/swaggo/swag/v2/cmd/swag@v2.0.0-rc5
+                  cd server
+                  go mod download gitea.hostxtra.co.uk/vantage/vantage-shared
+                  SHARED_DIR="$(go list -m -f '{{.Dir}}' gitea.hostxtra.co.uk/vantage/vantage-shared)"
+                  if [ -z "$SHARED_DIR" ] || [ ! -d "$SHARED_DIR" ]; then
+                      echo "vantage-shared source not in the module cache: '$SHARED_DIR'" >&2
+                      exit 1
+                  fi
+                  swag init --generalInfo cmd/main.go --dir "./,$SHARED_DIR" --output internal/api/docs --outputTypes json --v3.1
+                  mv -f internal/api/docs/swagger.json internal/api/docs/openapi.json
+                  git diff --exit-code internal/api/docs/openapi.json
+
             - name: Build and push server image
+              if: steps.changed.outputs.server == 'true'
               run: |
                   IMAGE="${{ vars.DOCKER_HOST }}/${{ github.repository_owner }}/vantage/server:latest"
-                  docker build -t "$IMAGE" -f server/Dockerfile server/
+                  docker build --secret id=netrc,src="$HOME/.netrc" \
+                    -t "$IMAGE" -f server/Dockerfile .
                   docker push "$IMAGE"
 
             - name: Build and push web image
+              if: steps.changed.outputs.web == 'true'
               run: |
                   IMAGE="${{ vars.DOCKER_HOST }}/${{ github.repository_owner }}/vantage/web:latest"
                   docker build \
-                    --build-arg NEXT_PUBLIC_API_URL="${{ vars.API_URL }}" \
+                    --build-arg NEXT_PUBLIC_HQ_URL="${{ vars.HQ_URL }}" \
                     -t "$IMAGE" \
                     -f web/Dockerfile web/
                   docker push "$IMAGE"
+

.gitignore

@@ -2,10 +2,17 @@ node_modules
 dist
 build
 .env
-docs
+.env.bck
+.env.live
+docs/*
+!docs/superpowers/
 .superpowers
 installer/vantage-agent-windows-amd64.exe
 installer/*.msi
 installer/nssm.zip
 installer/checksums-msi.txt
-.next
+.next
+*.tsbuildinfo
+graphify-out
+docker-compose.live.yml
+.claude

agent/cmd/main.go

@@ -1,39 +0,0 @@
-package main
-
-import (
-	"context"
-	"flag"
-	"log"
-	"os/signal"
-	"syscall"
-
-	"github.com/mrhid6/vantage/agent/internal/config"
-	agentsync "github.com/mrhid6/vantage/agent/internal/sync"
-)
-
-var Version = "dev"
-
-func main() {
-	genKey := flag.String("generate-key", "", "Generate SSH keypair and upload with this label")
-	flag.Parse()
-
-	cfg, err := config.Load()
-	if err != nil {
-		log.Fatalf("failed to load config: %v", err)
-	}
-
-	if *genKey != "" {
-		if err := agentsync.GenerateAndUpload(cfg, *genKey); err != nil {
-			log.Fatalf("key generation failed: %v", err)
-		}
-		return
-	}
-
-	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
-	defer stop()
-
-	log.Printf("vantage-agent %s starting (server=%s, poll=%s)", Version, cfg.ServerURL, cfg.PollInterval)
-	if err := agentsync.Run(ctx, cfg, Version); err != nil {
-		log.Fatalf("agent error: %v", err)
-	}
-}

agent/go.mod

@@ -1,16 +0,0 @@
-module github.com/mrhid6/vantage/agent
-
-go 1.26
-
-require (
-	google.golang.org/grpc v1.64.0
-	gopkg.in/yaml.v3 v3.0.1
-)
-
-require (
-	golang.org/x/net v0.25.0 // indirect
-	golang.org/x/sys v0.20.0 // indirect
-	golang.org/x/text v0.15.0 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20240521202816-d264139d666e // indirect
-	google.golang.org/protobuf v1.34.1 // indirect
-)

agent/go.sum

@@ -1,18 +0,0 @@
-github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
-github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
-golang.org/x/net v0.25.0 h1:d/OCCoBEUq33pjydKrGQhw7IlUPI2Oylr+8qLx49kac=
-golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM=
-golang.org/x/sys v0.20.0 h1:Od9JTbYCk261bKm4M/mw7AklTlFYIa0bIp9BgSm1S8Y=
-golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/text v0.15.0 h1:h1V/4gjBv8v9cjcR6+AR5+/cIYK5N/WAgiv4xlsEtAk=
-golang.org/x/text v0.15.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20240521202816-d264139d666e h1:Elxv5MwEkCI9f5SkoL6afed6NTdxaGoAo39eANBwHL8=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20240521202816-d264139d666e/go.mod h1:EfXuqaE1J41VCDicxHzUDm+8rk+7ZdXzHV0IhO/I6s0=
-google.golang.org/grpc v1.64.0 h1:KH3VH9y/MgNQg1dE7b3XfVK0GsPSIzJwdF617gUSbvY=
-google.golang.org/grpc v1.64.0/go.mod h1:oxjF8E3FBnjp+/gVFYdWacaLDx9na1aqy9oovLpxQYg=
-google.golang.org/protobuf v1.34.1 h1:9ddQBjfCyZPOHPUiPxpYESBLc+T8P3E+Vo4IbKZgFWg=
-google.golang.org/protobuf v1.34.1/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
-gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

agent/internal/checker/checker.go

@@ -1,226 +0,0 @@
-// Package checker runs service checks (http/tcp/icmp/tls) and returns a uniform
-// Result. It has no dependency on models or pb so it can be duplicated verbatim
-// into the agent module (agent-run monitors) — callers map their own monitor
-// representation onto Spec.
-package checker
-
-import (
-	"context"
-	"crypto/tls"
-	"fmt"
-	"io"
-	"net"
-	"net/http"
-	"os"
-	"strings"
-	"time"
-)
-
-// Check types (mirror models.Monitor* constants).
-const (
-	TypeHTTP = "http"
-	TypeTCP  = "tcp"
-	TypeICMP = "icmp"
-	TypeTLS  = "tls"
-)
-
-// Spec is a self-contained description of a single check.
-type Spec struct {
-	Type           string
-	URL            string
-	Host           string
-	Port           int
-	Method         string
-	ExpectedStatus int
-	Keyword        string
-	TLSWarnDays    int
-	Insecure       bool // skip TLS certificate verification (HTTP checks)
-	TimeoutSec     int
-}
-
-// Result is the uniform outcome of running a check.
-type Result struct {
-	Up         bool
-	LatencyMs  int
-	Message    string
-	CertExpiry *time.Time
-}
-
-func (s Spec) timeout() time.Duration {
-	t := s.TimeoutSec
-	if t <= 0 || t > 10 {
-		t = 10
-	}
-	return time.Duration(t) * time.Second
-}
-
-// Run executes the check described by s.
-func Run(ctx context.Context, s Spec) Result {
-	switch s.Type {
-	case TypeHTTP:
-		return runHTTP(ctx, s)
-	case TypeTCP:
-		return runTCP(ctx, s)
-	case TypeICMP:
-		return runICMP(ctx, s)
-	case TypeTLS:
-		return runTLS(ctx, s)
-	default:
-		return Result{Message: "unknown check type: " + s.Type}
-	}
-}
-
-func runHTTP(ctx context.Context, s Spec) Result {
-	method := s.Method
-	if method == "" {
-		method = http.MethodGet
-	}
-	expect := s.ExpectedStatus
-	if expect == 0 {
-		expect = 200
-	}
-	client := &http.Client{Timeout: s.timeout()}
-	if s.Insecure {
-		client.Transport = &http.Transport{TLSClientConfig: &tls.Config{InsecureSkipVerify: true}} //nolint:gosec // opt-in per monitor
-	}
-	start := time.Now()
-	req, err := http.NewRequestWithContext(ctx, method, s.URL, nil)
-	if err != nil {
-		return Result{Message: err.Error()}
-	}
-	resp, err := client.Do(req)
-	if err != nil {
-		return Result{LatencyMs: msSince(start), Message: err.Error()}
-	}
-	defer resp.Body.Close()
-	res := Result{LatencyMs: msSince(start), Up: true}
-	if resp.TLS != nil && len(resp.TLS.PeerCertificates) > 0 {
-		exp := resp.TLS.PeerCertificates[0].NotAfter
-		res.CertExpiry = &exp
-	}
-	if resp.StatusCode != expect {
-		return Result{LatencyMs: res.LatencyMs, CertExpiry: res.CertExpiry, Message: fmt.Sprintf("status %d (want %d)", resp.StatusCode, expect)}
-	}
-	if s.Keyword != "" {
-		body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
-		if !strings.Contains(string(body), s.Keyword) {
-			return Result{LatencyMs: res.LatencyMs, CertExpiry: res.CertExpiry, Message: "keyword not found"}
-		}
-	}
-	return res
-}
-
-func runTCP(ctx context.Context, s Spec) Result {
-	addr := net.JoinHostPort(s.Host, fmt.Sprint(s.Port))
-	start := time.Now()
-	d := net.Dialer{Timeout: s.timeout()}
-	conn, err := d.DialContext(ctx, "tcp", addr)
-	if err != nil {
-		return Result{LatencyMs: msSince(start), Message: err.Error()}
-	}
-	conn.Close()
-	return Result{Up: true, LatencyMs: msSince(start)}
-}
-
-func runTLS(ctx context.Context, s Spec) Result {
-	port := s.Port
-	if port == 0 {
-		port = 443
-	}
-	addr := net.JoinHostPort(s.Host, fmt.Sprint(port))
-	start := time.Now()
-	d := net.Dialer{Timeout: s.timeout()}
-	conn, err := tls.DialWithDialer(&d, "tcp", addr, &tls.Config{ServerName: s.Host})
-	if err != nil {
-		return Result{LatencyMs: msSince(start), Message: err.Error()}
-	}
-	defer conn.Close()
-	certs := conn.ConnectionState().PeerCertificates
-	if len(certs) == 0 {
-		return Result{LatencyMs: msSince(start), Message: "no peer certificate"}
-	}
-	exp := certs[0].NotAfter
-	res := Result{LatencyMs: msSince(start), CertExpiry: &exp}
-	warn := s.TLSWarnDays
-	if warn <= 0 {
-		warn = 14
-	}
-	remaining := time.Until(exp)
-	if remaining <= 0 {
-		res.Message = "certificate expired"
-		return res
-	}
-	if remaining <= time.Duration(warn)*24*time.Hour {
-		res.Message = fmt.Sprintf("certificate expires in %d days", int(remaining.Hours()/24))
-		return res
-	}
-	res.Up = true
-	return res
-}
-
-func msSince(t time.Time) int { return int(time.Since(t).Milliseconds()) }
-
-// runICMP sends a single ICMP echo request and waits for the reply. Requires
-// raw-socket privileges (the agent and server run as root). Returns down with a
-// descriptive message when the socket cannot be opened or no reply arrives.
-func runICMP(ctx context.Context, s Spec) Result {
-	dst, err := net.ResolveIPAddr("ip4", s.Host)
-	if err != nil {
-		return Result{Message: err.Error()}
-	}
-	conn, err := net.ListenPacket("ip4:icmp", "0.0.0.0")
-	if err != nil {
-		return Result{Message: "icmp socket: " + err.Error()}
-	}
-	defer conn.Close()
-
-	id := os.Getpid() & 0xffff
-	pkt := icmpEcho(id, 1)
-	deadline := time.Now().Add(s.timeout())
-	if d, ok := ctx.Deadline(); ok && d.Before(deadline) {
-		deadline = d
-	}
-	_ = conn.SetDeadline(deadline)
-
-	start := time.Now()
-	if _, err := conn.WriteTo(pkt, dst); err != nil {
-		return Result{Message: err.Error()}
-	}
-	reply := make([]byte, 1500)
-	for {
-		n, peer, err := conn.ReadFrom(reply)
-		if err != nil {
-			return Result{LatencyMs: msSince(start), Message: "no reply"}
-		}
-		// Skip the IPv4 header (20 bytes) to reach the ICMP message.
-		if n < 28 || peer.String() != dst.String() {
-			continue
-		}
-		if reply[20] == 0 { // ICMP echo reply type
-			return Result{Up: true, LatencyMs: msSince(start)}
-		}
-	}
-}
-
-func icmpEcho(id, seq int) []byte {
-	// Type(8)=echo request, Code=0, Checksum, ID, Seq, no payload.
-	b := []byte{8, 0, 0, 0, byte(id >> 8), byte(id), byte(seq >> 8), byte(seq)}
-	cs := icmpChecksum(b)
-	b[2] = byte(cs >> 8)
-	b[3] = byte(cs)
-	return b
-}
-
-func icmpChecksum(b []byte) uint16 {
-	var sum uint32
-	for i := 0; i < len(b)-1; i += 2 {
-		sum += uint32(b[i])<<8 | uint32(b[i+1])
-	}
-	if len(b)%2 == 1 {
-		sum += uint32(b[len(b)-1]) << 8
-	}
-	for sum>>16 != 0 {
-		sum = (sum & 0xffff) + (sum >> 16)
-	}
-	return ^uint16(sum)
-}

agent/internal/config/config.go

@@ -1,59 +0,0 @@
-package config
-
-import (
-	"os"
-	"path/filepath"
-	"runtime"
-	"time"
-
-	"gopkg.in/yaml.v3"
-)
-
-// ConfigDir returns the platform-specific config directory.
-func ConfigDir() string {
-	if runtime.GOOS == "windows" {
-		base := os.Getenv("ProgramData")
-		if base == "" {
-			base = `C:\ProgramData`
-		}
-		return filepath.Join(base, "vantage")
-	}
-	return "/etc/vantage"
-}
-
-func configPath() string { return filepath.Join(ConfigDir(), "config.yaml") }
-
-type Config struct {
-	ServerURL    string        `yaml:"server_url"`
-	ServerID     string        `yaml:"server_id"`
-	PreRegToken  string        `yaml:"pre_reg_token"`
-	AgentToken   string        `yaml:"agent_token"`
-	PollInterval time.Duration `yaml:"poll_interval"`
-	TLS          bool          `yaml:"tls"`
-}
-
-func Load() (*Config, error) {
-	data, err := os.ReadFile(configPath())
-	if err != nil {
-		return nil, err
-	}
-	var cfg Config
-	if err := yaml.Unmarshal(data, &cfg); err != nil {
-		return nil, err
-	}
-	if cfg.PollInterval == 0 {
-		cfg.PollInterval = 30 * time.Second
-	}
-	return &cfg, nil
-}
-
-func Save(cfg *Config) error {
-	data, err := yaml.Marshal(cfg)
-	if err != nil {
-		return err
-	}
-	if err := os.MkdirAll(ConfigDir(), 0700); err != nil {
-		return err
-	}
-	return os.WriteFile(configPath(), data, 0600)
-}

agent/internal/config/config_test.go

@@ -1,20 +0,0 @@
-package config
-
-import (
-	"runtime"
-	"strings"
-	"testing"
-)
-
-func TestConfigDirByOS(t *testing.T) {
-	d := ConfigDir()
-	if runtime.GOOS == "windows" {
-		if !strings.Contains(strings.ToLower(d), "programdata") {
-			t.Fatalf("windows config dir = %q, want ProgramData path", d)
-		}
-	} else {
-		if d != "/etc/vantage" {
-			t.Fatalf("unix config dir = %q, want /etc/vantage", d)
-		}
-	}
-}

agent/internal/exec/exec.go

@@ -1,164 +0,0 @@
-package exec
-
-import (
-	"bufio"
-	"context"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"runtime"
-	"strings"
-	"sync"
-	"time"
-
-	"github.com/mrhid6/vantage/agent/internal/grpc/pb"
-)
-
-// streamWriter forwards every write to emit() as an ordered chunk. Used as both
-// Stdout and Stderr so output interleaves in real execution order. The mutex
-// ensures a single stdout/stderr write is not interleaved mid-slice with another.
-type streamWriter struct {
-	mu   sync.Mutex
-	seq  uint64
-	emit func(seq uint64, data []byte)
-}
-
-func (w *streamWriter) Write(p []byte) (int, error) {
-	w.mu.Lock()
-	defer w.mu.Unlock()
-	if w.emit != nil {
-		buf := make([]byte, len(p))
-		copy(buf, p)
-		w.emit(w.seq, buf)
-		w.seq++
-	}
-	return len(p), nil
-}
-
-// WorkspacePath returns the per-run working directory for a workspace id. The
-// same id always maps to the same path so RunStep and the cleanup command agree.
-func WorkspacePath(workspaceID string) string {
-	return filepath.Join(os.TempDir(), "vantage-run-"+workspaceID)
-}
-
-// RunStep writes the script to a temp file, provides a WORKFLOW_ENV file for
-// the script to append KEY=value output to, executes it under the requested
-// interpreter, and streams output via emit, returning the terminal result
-// with empty stdout/stderr but populated exit_code/output_env.
-//
-// When the command carries a WorkspaceId the step runs with that per-run working
-// directory as its cwd (created here if missing); the server removes it once the
-// run finishes. The script and env files always live in a private temp dir so
-// they never leak into the shared workspace.
-func RunStep(cmd *pb.RunStepCmd, emit func(seq uint64, data []byte)) *pb.StepResult {
-	res := &pb.StepResult{CommandId: "", OutputEnv: map[string]string{}}
-
-	dir, err := os.MkdirTemp("", "vantage-step-")
-	if err != nil {
-		res.ExitCode = 1
-		res.Stderr = "create temp dir: " + err.Error()
-		return res
-	}
-	defer os.RemoveAll(dir)
-
-	workDir := ""
-	if cmd.WorkspaceId != "" {
-		workDir = WorkspacePath(cmd.WorkspaceId)
-		if err := os.MkdirAll(workDir, 0700); err != nil {
-			res.ExitCode = 1
-			res.Stderr = "create workspace: " + err.Error()
-			return res
-		}
-	}
-
-	envFile := filepath.Join(dir, "workflow_env")
-	if err := os.WriteFile(envFile, nil, 0600); err != nil {
-		res.ExitCode = 1
-		res.Stderr = "create env file: " + err.Error()
-		return res
-	}
-
-	var scriptPath string
-	var c *exec.Cmd
-	timeout := time.Duration(cmd.TimeoutSeconds) * time.Second
-	if timeout <= 0 {
-		timeout = 30 * time.Minute
-	}
-	ctx, cancel := context.WithTimeout(context.Background(), timeout)
-	defer cancel()
-
-	switch cmd.Interpreter {
-	case "powershell":
-		scriptPath = filepath.Join(dir, "step.ps1")
-		if err := os.WriteFile(scriptPath, []byte(cmd.Script), 0600); err != nil {
-			res.ExitCode = 1
-			res.Stderr = err.Error()
-			return res
-		}
-		shell := "pwsh"
-		if runtime.GOOS == "windows" {
-			if _, err := exec.LookPath("pwsh"); err != nil {
-				shell = "powershell.exe"
-			}
-		}
-		c = exec.CommandContext(ctx, shell, "-NoProfile", "-NonInteractive", "-File", scriptPath)
-	default: // "bash"
-		scriptPath = filepath.Join(dir, "step.sh")
-		if err := os.WriteFile(scriptPath, []byte(cmd.Script), 0700); err != nil {
-			res.ExitCode = 1
-			res.Stderr = err.Error()
-			return res
-		}
-		c = exec.CommandContext(ctx, "bash", scriptPath)
-	}
-
-	if workDir != "" {
-		c.Dir = workDir
-	}
-
-	c.Env = append(os.Environ(), "WORKFLOW_ENV="+envFile)
-	for k, v := range cmd.Env {
-		c.Env = append(c.Env, k+"="+v)
-	}
-
-	sw := &streamWriter{emit: emit}
-	c.Stdout = sw
-	c.Stderr = sw
-	runErr := c.Run()
-
-	// stdout/stderr are streamed via emit, not returned in the result.
-	if ctx.Err() == context.DeadlineExceeded {
-		res.ExitCode = 124
-		res.Stderr = "[vantage] step timed out"
-	} else if ee, ok := runErr.(*exec.ExitError); ok {
-		res.ExitCode = ee.ExitCode()
-	} else if runErr != nil {
-		res.ExitCode = 1
-		res.Stderr = "[vantage] " + runErr.Error()
-	}
-
-	res.OutputEnv = parseEnvFile(envFile)
-	return res
-}
-
-// parseEnvFile reads KEY=value lines (last write wins). Blank lines and lines
-// without '=' are ignored.
-func parseEnvFile(path string) map[string]string {
-	out := map[string]string{}
-	f, err := os.Open(path)
-	if err != nil {
-		return out
-	}
-	defer f.Close()
-	sc := bufio.NewScanner(f)
-	sc.Buffer(make([]byte, 0, 64*1024), 1024*1024)
-	for sc.Scan() {
-		line := sc.Text()
-		i := strings.IndexByte(line, '=')
-		if i <= 0 {
-			continue
-		}
-		out[line[:i]] = line[i+1:]
-	}
-	return out
-}

agent/internal/grpc/client.go

@@ -1,157 +0,0 @@
-package grpcclient
-
-import (
-	"context"
-	"crypto/tls"
-	"strings"
-	"time"
-
-	"github.com/mrhid6/vantage/agent/internal/grpc/pb"
-	"google.golang.org/grpc"
-	"google.golang.org/grpc/credentials"
-	"google.golang.org/grpc/credentials/insecure"
-	"google.golang.org/grpc/encoding"
-	"google.golang.org/grpc/keepalive"
-)
-
-func init() {
-	encoding.RegisterCodec(JSONCodec{})
-}
-
-type Client struct {
-	conn   *grpc.ClientConn
-	client pb.VantageClient
-}
-
-func New(serverURL string, useTLS bool) (*Client, error) {
-	serverURL = strings.TrimPrefix(serverURL, "https://")
-	serverURL = strings.TrimPrefix(serverURL, "http://")
-
-	// Send a ping every 30s so proxies with a 60s idle timeout don't kill the
-	// long-lived CommandStream when no commands are flowing.
-	dialOpts := []grpc.DialOption{
-		grpc.WithKeepaliveParams(keepalive.ClientParameters{
-			Time:                30 * time.Second,
-			Timeout:             10 * time.Second,
-			PermitWithoutStream: false,
-		}),
-	}
-
-	if useTLS {
-		tlsCfg := &tls.Config{
-			InsecureSkipVerify: false,
-		}
-		creds := credentials.NewTLS(tlsCfg)
-		dialOpts = append(dialOpts, grpc.WithTransportCredentials(creds))
-	} else {
-		dialOpts = append(dialOpts, grpc.WithTransportCredentials(insecure.NewCredentials()))
-	}
-
-	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-	defer cancel()
-
-	conn, err := grpc.DialContext(ctx, serverURL, dialOpts...)
-	if err != nil {
-		return nil, err
-	}
-
-	return &Client{
-		conn:   conn,
-		client: pb.NewVantageClient(conn),
-	}, nil
-}
-
-func (c *Client) Close() error {
-	return c.conn.Close()
-}
-
-func (c *Client) Register(serverID, preRegToken, hostname, ipAddress, osInfo string) (string, error) {
-	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-	defer cancel()
-
-	resp, err := c.client.Register(ctx, &pb.RegisterRequest{
-		ServerId:    serverID,
-		PreRegToken: preRegToken,
-		Hostname:    hostname,
-		IpAddress:   ipAddress,
-		OsInfo:      osInfo,
-	})
-	if err != nil {
-		return "", err
-	}
-	return resp.AgentToken, nil
-}
-
-func (c *Client) SyncKeys(serverID, agentToken, version string) ([]string, error) {
-	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-	defer cancel()
-
-	resp, err := c.client.SyncKeys(ctx, &pb.SyncRequest{
-		ServerId:     serverID,
-		AgentToken:   agentToken,
-		AgentVersion: version,
-	})
-	if err != nil {
-		return nil, err
-	}
-	return resp.PublicKeys, nil
-}
-
-func (c *Client) UploadGeneratedKey(serverID, agentToken, publicKey, privateKey, label string) (string, error) {
-	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-	defer cancel()
-
-	resp, err := c.client.UploadGeneratedKey(ctx, &pb.UploadKeyRequest{
-		ServerId:   serverID,
-		AgentToken: agentToken,
-		PublicKey:  publicKey,
-		PrivateKey: privateKey,
-		Label:      label,
-	})
-	if err != nil {
-		return "", err
-	}
-	return resp.KeyId, nil
-}
-
-func (c *Client) ReportUpdates(serverID, agentToken string, updates []pb.PackageUpdate) error {
-	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-	defer cancel()
-
-	_, err := c.client.ReportUpdates(ctx, &pb.ReportUpdatesRequest{
-		ServerId:   serverID,
-		AgentToken: agentToken,
-		Updates:    updates,
-	})
-	return err
-}
-
-func (c *Client) ReportInventory(report *pb.InventoryReport) error {
-	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-	defer cancel()
-	_, err := c.client.ReportInventory(ctx, report)
-	return err
-}
-
-func (c *Client) SyncMonitors(serverID, agentToken string) ([]pb.MonitorSpec, error) {
-	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-	defer cancel()
-	resp, err := c.client.SyncMonitors(ctx, &pb.SyncMonitorsRequest{ServerId: serverID, AgentToken: agentToken})
-	if err != nil {
-		return nil, err
-	}
-	return resp.Monitors, nil
-}
-
-func (c *Client) ReportChecks(serverID, agentToken string, results []pb.CheckResult) error {
-	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-	defer cancel()
-	_, err := c.client.ReportChecks(ctx, &pb.ReportChecksRequest{ServerId: serverID, AgentToken: agentToken, Results: results})
-	return err
-}
-
-// CommandStream opens a long-lived bidirectional stream for server-pushed commands.
-// The caller controls the stream lifetime via ctx.
-func (c *Client) CommandStream(ctx context.Context) (pb.Vantage_CommandStreamClient, error) {
-	return c.client.CommandStream(ctx)
-}

agent/internal/grpc/codec.go

@@ -1,17 +0,0 @@
-package grpcclient
-
-import "encoding/json"
-
-type JSONCodec struct{}
-
-func (JSONCodec) Marshal(v interface{}) ([]byte, error) {
-	return json.Marshal(v)
-}
-
-func (JSONCodec) Unmarshal(data []byte, v interface{}) error {
-	return json.Unmarshal(data, v)
-}
-
-func (JSONCodec) Name() string {
-	return "proto"
-}

agent/internal/grpc/pb/vantage.pb.go

@@ -1,351 +0,0 @@
-// Hand-written gRPC bindings for vantage.proto (agent side, JSON codec).
-
-package pb
-
-import (
-	"context"
-
-	"google.golang.org/grpc"
-	"google.golang.org/grpc/codes"
-	"google.golang.org/grpc/status"
-)
-
-type RegisterRequest struct {
-	ServerId    string `json:"server_id"`
-	PreRegToken string `json:"pre_reg_token"`
-	Hostname    string `json:"hostname"`
-	IpAddress   string `json:"ip_address"`
-	OsInfo      string `json:"os_info"`
-}
-
-type RegisterResponse struct {
-	AgentToken string `json:"agent_token"`
-}
-
-type SyncRequest struct {
-	ServerId     string `json:"server_id"`
-	AgentToken   string `json:"agent_token"`
-	AgentVersion string `json:"agent_version,omitempty"`
-}
-
-type SyncResponse struct {
-	PublicKeys []string `json:"public_keys"`
-}
-
-type UploadKeyRequest struct {
-	ServerId   string `json:"server_id"`
-	AgentToken string `json:"agent_token"`
-	PublicKey  string `json:"public_key"`
-	Label      string `json:"label"`
-	PrivateKey string `json:"private_key,omitempty"`
-}
-
-type UploadKeyResponse struct {
-	KeyId string `json:"key_id"`
-}
-
-// CommandStream message types
-
-type PackageUpdate struct {
-	Name           string `json:"name"`
-	CurrentVersion string `json:"current_version,omitempty"`
-	NewVersion     string `json:"new_version"`
-}
-
-type ReportUpdatesRequest struct {
-	ServerId   string          `json:"server_id"`
-	AgentToken string          `json:"agent_token"`
-	Updates    []PackageUpdate `json:"updates"`
-}
-
-type ReportUpdatesResponse struct{}
-
-// Inventory report message types
-
-type CPUReport struct {
-	Model    string  `json:"model,omitempty"`
-	Cores    int     `json:"cores,omitempty"`
-	UsagePct float64 `json:"usage_pct"`
-	Load1    float64 `json:"load1,omitempty"`
-}
-type MemReport struct {
-	TotalBytes uint64 `json:"total_bytes"`
-	UsedBytes  uint64 `json:"used_bytes"`
-}
-type PartitionReport struct {
-	Device     string `json:"device"`
-	Mountpoint string `json:"mountpoint"`
-	Fstype     string `json:"fstype,omitempty"`
-	TotalBytes uint64 `json:"total_bytes"`
-	UsedBytes  uint64 `json:"used_bytes"`
-}
-type InventoryReport struct {
-	ServerId      string            `json:"server_id"`
-	AgentToken    string            `json:"agent_token"`
-	IncludeStatic bool              `json:"include_static"`
-	CPU           *CPUReport        `json:"cpu,omitempty"`
-	Memory        *MemReport        `json:"memory,omitempty"`
-	SwapTotal     uint64            `json:"swap_total"`
-	SwapUsed      uint64            `json:"swap_used"`
-	Partitions    []PartitionReport `json:"partitions,omitempty"`
-	Kernel        string            `json:"kernel,omitempty"`
-}
-type InventoryReportResponse struct{}
-
-// Monitor sync / check report message types
-
-type MonitorSpec struct {
-	MonitorId      string `json:"monitor_id"`
-	Type           string `json:"type"`
-	URL            string `json:"url,omitempty"`
-	Host           string `json:"host,omitempty"`
-	Port           int    `json:"port,omitempty"`
-	Method         string `json:"method,omitempty"`
-	ExpectedStatus int    `json:"expected_status,omitempty"`
-	Keyword        string `json:"keyword,omitempty"`
-	TLSWarnDays    int    `json:"tls_warn_days,omitempty"`
-	Insecure       bool   `json:"insecure,omitempty"`
-	IntervalSec    int    `json:"interval_sec"`
-	Retries        int    `json:"retries"`
-}
-type SyncMonitorsRequest struct {
-	ServerId   string `json:"server_id"`
-	AgentToken string `json:"agent_token"`
-}
-type SyncMonitorsResponse struct {
-	Monitors []MonitorSpec `json:"monitors,omitempty"`
-}
-type CheckResult struct {
-	MonitorId      string `json:"monitor_id"`
-	Up             bool   `json:"up"`
-	LatencyMs      int    `json:"latency_ms"`
-	Message        string `json:"message,omitempty"`
-	CertExpiryUnix int64  `json:"cert_expiry_unix,omitempty"`
-}
-type ReportChecksRequest struct {
-	ServerId   string        `json:"server_id"`
-	AgentToken string        `json:"agent_token"`
-	Results    []CheckResult `json:"results,omitempty"`
-}
-type ReportChecksResponse struct{}
-
-type ApplyUpdatesCmd struct{}
-
-type ServerCommand struct {
-	CommandId        string               `json:"command_id"`
-	GenerateKey      *GenerateKeyCmd      `json:"generate_key,omitempty"`
-	DeleteKey        *DeleteKeyCmd        `json:"delete_key,omitempty"`
-	UpdateAgent      *UpdateAgentCmd      `json:"update_agent,omitempty"`
-	ApplyUpdates     *ApplyUpdatesCmd     `json:"apply_updates,omitempty"`
-	RunStep          *RunStepCmd          `json:"run_step,omitempty"`
-	CleanupWorkspace *CleanupWorkspaceCmd `json:"cleanup_workspace,omitempty"`
-}
-
-// CleanupWorkspaceCmd tells the agent to recursively remove the run's working
-// directory once all steps on that server have finished.
-type CleanupWorkspaceCmd struct {
-	WorkspaceId string `json:"workspace_id"`
-}
-
-type DeleteKeyCmd struct {
-	Label string `json:"label"`
-}
-
-type UpdateAgentCmd struct {
-	Version      string `json:"version"`
-	GiteaBaseURL string `json:"gitea_base_url"`
-}
-
-type GenerateKeyCmd struct {
-	Label      string `json:"label"`
-	KeyType    string `json:"key_type,omitempty"`
-	KeySize    int    `json:"key_size,omitempty"`
-	Passphrase string `json:"passphrase,omitempty"`
-	Comment    string `json:"comment,omitempty"`
-}
-
-type AgentMessage struct {
-	ServerId   string            `json:"server_id"`
-	AgentToken string            `json:"agent_token"`
-	Ready      *AgentReady       `json:"ready,omitempty"`
-	Result     *CommandResult    `json:"result,omitempty"`
-	StepResult *StepResult       `json:"step_result,omitempty"`
-	StepOutput *StepOutputChunk  `json:"step_output,omitempty"`
-}
-
-type AgentReady struct{}
-
-type CommandResult struct {
-	CommandId string `json:"command_id"`
-	Success   bool   `json:"success"`
-	Message   string `json:"message"`
-}
-
-type RunStepCmd struct {
-	Interpreter    string            `json:"interpreter"`
-	Script         string            `json:"script"`
-	Env            map[string]string `json:"env,omitempty"`
-	TimeoutSeconds int               `json:"timeout_seconds,omitempty"`
-	// WorkspaceId names the per-run working directory the agent creates and uses
-	// as the step's cwd. Empty means run in the agent's default directory.
-	WorkspaceId string `json:"workspace_id,omitempty"`
-}
-
-type StepResult struct {
-	CommandId string            `json:"command_id"`
-	ExitCode  int               `json:"exit_code"`
-	Stdout    string            `json:"stdout,omitempty"`
-	Stderr    string            `json:"stderr,omitempty"`
-	OutputEnv map[string]string `json:"output_env,omitempty"`
-}
-
-type StepOutputChunk struct {
-	CommandId string `json:"command_id"`
-	Seq       uint64 `json:"seq"`
-	Data      []byte `json:"data,omitempty"`
-	Eof       bool   `json:"eof,omitempty"`
-}
-
-// CommandStream client-side interface
-
-type Vantage_CommandStreamClient interface {
-	Send(*AgentMessage) error
-	Recv() (*ServerCommand, error)
-	grpc.ClientStream
-}
-
-type vantageCommandStreamClient struct {
-	grpc.ClientStream
-}
-
-func (c *vantageCommandStreamClient) Send(m *AgentMessage) error {
-	return c.ClientStream.SendMsg(m)
-}
-
-func (c *vantageCommandStreamClient) Recv() (*ServerCommand, error) {
-	m := new(ServerCommand)
-	if err := c.ClientStream.RecvMsg(m); err != nil {
-		return nil, err
-	}
-	return m, nil
-}
-
-// CommandStream server-side interface (included for completeness)
-
-type Vantage_CommandStreamServer interface {
-	Send(*ServerCommand) error
-	Recv() (*AgentMessage, error)
-	grpc.ServerStream
-}
-
-type keyManagerCommandStreamServer struct {
-	grpc.ServerStream
-}
-
-func (s *keyManagerCommandStreamServer) Send(m *ServerCommand) error {
-	return s.ServerStream.SendMsg(m)
-}
-
-func (s *keyManagerCommandStreamServer) Recv() (*AgentMessage, error) {
-	m := new(AgentMessage)
-	if err := s.ServerStream.RecvMsg(m); err != nil {
-		return nil, err
-	}
-	return m, nil
-}
-
-type VantageClient interface {
-	Register(ctx context.Context, in *RegisterRequest, opts ...grpc.CallOption) (*RegisterResponse, error)
-	SyncKeys(ctx context.Context, in *SyncRequest, opts ...grpc.CallOption) (*SyncResponse, error)
-	UploadGeneratedKey(ctx context.Context, in *UploadKeyRequest, opts ...grpc.CallOption) (*UploadKeyResponse, error)
-	ReportUpdates(ctx context.Context, in *ReportUpdatesRequest, opts ...grpc.CallOption) (*ReportUpdatesResponse, error)
-	ReportInventory(ctx context.Context, in *InventoryReport, opts ...grpc.CallOption) (*InventoryReportResponse, error)
-	SyncMonitors(ctx context.Context, in *SyncMonitorsRequest, opts ...grpc.CallOption) (*SyncMonitorsResponse, error)
-	ReportChecks(ctx context.Context, in *ReportChecksRequest, opts ...grpc.CallOption) (*ReportChecksResponse, error)
-	CommandStream(ctx context.Context, opts ...grpc.CallOption) (Vantage_CommandStreamClient, error)
-}
-
-type UnimplementedVantageServer struct{}
-
-func (UnimplementedVantageServer) Register(context.Context, *RegisterRequest) (*RegisterResponse, error) {
-	return nil, status.Errorf(codes.Unimplemented, "not implemented")
-}
-func (UnimplementedVantageServer) SyncKeys(context.Context, *SyncRequest) (*SyncResponse, error) {
-	return nil, status.Errorf(codes.Unimplemented, "not implemented")
-}
-func (UnimplementedVantageServer) UploadGeneratedKey(context.Context, *UploadKeyRequest) (*UploadKeyResponse, error) {
-	return nil, status.Errorf(codes.Unimplemented, "not implemented")
-}
-
-type keyManagerClient struct {
-	cc grpc.ClientConnInterface
-}
-
-func NewVantageClient(cc grpc.ClientConnInterface) VantageClient {
-	return &keyManagerClient{cc}
-}
-
-func (c *keyManagerClient) Register(ctx context.Context, in *RegisterRequest, opts ...grpc.CallOption) (*RegisterResponse, error) {
-	out := new(RegisterResponse)
-	if err := c.cc.Invoke(ctx, "/vantage.v1.Vantage/Register", in, out, opts...); err != nil {
-		return nil, err
-	}
-	return out, nil
-}
-
-func (c *keyManagerClient) SyncKeys(ctx context.Context, in *SyncRequest, opts ...grpc.CallOption) (*SyncResponse, error) {
-	out := new(SyncResponse)
-	if err := c.cc.Invoke(ctx, "/vantage.v1.Vantage/SyncKeys", in, out, opts...); err != nil {
-		return nil, err
-	}
-	return out, nil
-}
-
-func (c *keyManagerClient) UploadGeneratedKey(ctx context.Context, in *UploadKeyRequest, opts ...grpc.CallOption) (*UploadKeyResponse, error) {
-	out := new(UploadKeyResponse)
-	if err := c.cc.Invoke(ctx, "/vantage.v1.Vantage/UploadGeneratedKey", in, out, opts...); err != nil {
-		return nil, err
-	}
-	return out, nil
-}
-
-func (c *keyManagerClient) ReportUpdates(ctx context.Context, in *ReportUpdatesRequest, opts ...grpc.CallOption) (*ReportUpdatesResponse, error) {
-	out := new(ReportUpdatesResponse)
-	if err := c.cc.Invoke(ctx, "/vantage.v1.Vantage/ReportUpdates", in, out, opts...); err != nil {
-		return nil, err
-	}
-	return out, nil
-}
-
-func (c *keyManagerClient) ReportInventory(ctx context.Context, in *InventoryReport, opts ...grpc.CallOption) (*InventoryReportResponse, error) {
-	out := new(InventoryReportResponse)
-	if err := c.cc.Invoke(ctx, "/vantage.v1.Vantage/ReportInventory", in, out, opts...); err != nil {
-		return nil, err
-	}
-	return out, nil
-}
-
-func (c *keyManagerClient) SyncMonitors(ctx context.Context, in *SyncMonitorsRequest, opts ...grpc.CallOption) (*SyncMonitorsResponse, error) {
-	out := new(SyncMonitorsResponse)
-	if err := c.cc.Invoke(ctx, "/vantage.v1.Vantage/SyncMonitors", in, out, opts...); err != nil {
-		return nil, err
-	}
-	return out, nil
-}
-
-func (c *keyManagerClient) ReportChecks(ctx context.Context, in *ReportChecksRequest, opts ...grpc.CallOption) (*ReportChecksResponse, error) {
-	out := new(ReportChecksResponse)
-	if err := c.cc.Invoke(ctx, "/vantage.v1.Vantage/ReportChecks", in, out, opts...); err != nil {
-		return nil, err
-	}
-	return out, nil
-}
-
-func (c *keyManagerClient) CommandStream(ctx context.Context, opts ...grpc.CallOption) (Vantage_CommandStreamClient, error) {
-	desc := &grpc.StreamDesc{StreamName: "CommandStream", ServerStreams: true, ClientStreams: true}
-	stream, err := c.cc.NewStream(ctx, desc, "/vantage.v1.Vantage/CommandStream", opts...)
-	if err != nil {
-		return nil, err
-	}
-	return &vantageCommandStreamClient{stream}, nil
-}

agent/internal/inventory/collect_linux.go

@@ -1,157 +0,0 @@
-//go:build linux
-
-package inventory
-
-import (
-	"bufio"
-	"os"
-	"strconv"
-	"strings"
-	"syscall"
-	"time"
-
-	"github.com/mrhid6/vantage/agent/internal/grpc/pb"
-)
-
-func collect(r *pb.InventoryReport, includeStatic bool) {
-	r.CPU.UsagePct = cpuUsage()
-	r.CPU.Load1 = load1()
-	memTotal, memAvail, swapTotal, swapFree := meminfo()
-	if memTotal > memAvail {
-		r.Memory.UsedBytes = memTotal - memAvail
-	}
-	if swapTotal > swapFree {
-		r.SwapUsed = swapTotal - swapFree
-	}
-	if includeStatic {
-		r.Memory.TotalBytes = memTotal
-		r.SwapTotal = swapTotal
-		r.CPU.Model, r.CPU.Cores = cpuStatic()
-		r.Kernel = kernel()
-		r.Partitions = partitions()
-	}
-}
-
-func readProc(path string) string { b, _ := os.ReadFile(path); return string(b) }
-
-func cpuSample() (idle, total uint64) {
-	f, err := os.Open("/proc/stat")
-	if err != nil {
-		return
-	}
-	defer f.Close()
-	sc := bufio.NewScanner(f)
-	if sc.Scan() {
-		fields := strings.Fields(sc.Text()) // cpu user nice system idle iowait ...
-		for i, v := range fields[1:] {
-			n, _ := strconv.ParseUint(v, 10, 64)
-			total += n
-			if i == 3 { // idle
-				idle = n
-			}
-		}
-	}
-	return
-}
-
-func cpuUsage() float64 {
-	i1, t1 := cpuSample()
-	time.Sleep(100 * time.Millisecond)
-	i2, t2 := cpuSample()
-	dt := float64(t2 - t1)
-	if dt <= 0 {
-		return 0
-	}
-	return (1 - float64(i2-i1)/dt) * 100
-}
-
-func load1() float64 {
-	fields := strings.Fields(readProc("/proc/loadavg"))
-	if len(fields) > 0 {
-		v, _ := strconv.ParseFloat(fields[0], 64)
-		return v
-	}
-	return 0
-}
-
-func meminfo() (total, avail, swapTotal, swapFree uint64) {
-	f, err := os.Open("/proc/meminfo")
-	if err != nil {
-		return
-	}
-	defer f.Close()
-	sc := bufio.NewScanner(f)
-	for sc.Scan() {
-		fields := strings.Fields(sc.Text())
-		if len(fields) < 2 {
-			continue
-		}
-		kb, _ := strconv.ParseUint(fields[1], 10, 64)
-		b := kb * 1024
-		switch strings.TrimSuffix(fields[0], ":") {
-		case "MemTotal":
-			total = b
-		case "MemAvailable":
-			avail = b
-		case "SwapTotal":
-			swapTotal = b
-		case "SwapFree":
-			swapFree = b
-		}
-	}
-	return
-}
-
-func cpuStatic() (model string, cores int) {
-	f, err := os.Open("/proc/cpuinfo")
-	if err != nil {
-		return
-	}
-	defer f.Close()
-	sc := bufio.NewScanner(f)
-	for sc.Scan() {
-		line := sc.Text()
-		if strings.HasPrefix(line, "processor") {
-			cores++
-		} else if strings.HasPrefix(line, "model name") && model == "" {
-			if i := strings.Index(line, ":"); i >= 0 {
-				model = strings.TrimSpace(line[i+1:])
-			}
-		}
-	}
-	return
-}
-
-func kernel() string {
-	return strings.TrimSpace(readProc("/proc/sys/kernel/osrelease"))
-}
-
-func partitions() []pb.PartitionReport {
-	allowed := map[string]bool{"ext4": true, "xfs": true, "btrfs": true, "zfs": true, "vfat": true, "ntfs": true, "ext3": true}
-	f, err := os.Open("/proc/mounts")
-	if err != nil {
-		return nil
-	}
-	defer f.Close()
-	var out []pb.PartitionReport
-	seen := map[string]bool{}
-	sc := bufio.NewScanner(f)
-	for sc.Scan() {
-		fields := strings.Fields(sc.Text())
-		if len(fields) < 3 || !allowed[fields[2]] || seen[fields[1]] {
-			continue
-		}
-		seen[fields[1]] = true
-		var st syscall.Statfs_t
-		if syscall.Statfs(fields[1], &st) != nil {
-			continue
-		}
-		total := st.Blocks * uint64(st.Bsize)
-		free := st.Bavail * uint64(st.Bsize)
-		out = append(out, pb.PartitionReport{
-			Device: fields[0], Mountpoint: fields[1], Fstype: fields[2],
-			TotalBytes: total, UsedBytes: total - free,
-		})
-	}
-	return out
-}

agent/internal/inventory/collect_other.go

@@ -1,8 +0,0 @@
-//go:build !linux
-
-package inventory
-
-import "github.com/mrhid6/vantage/agent/internal/grpc/pb"
-
-// collect is a no-op best-effort stub on non-Linux platforms.
-func collect(r *pb.InventoryReport, includeStatic bool) {}

agent/internal/inventory/inventory.go

@@ -1,11 +0,0 @@
-package inventory
-
-import "github.com/mrhid6/vantage/agent/internal/grpc/pb"
-
-// Collect gathers metrics always and static hardware info when includeStatic.
-// Platform specifics are provided by collect_linux.go / collect_other.go.
-func Collect(includeStatic bool) *pb.InventoryReport {
-	r := &pb.InventoryReport{IncludeStatic: includeStatic, CPU: &pb.CPUReport{}, Memory: &pb.MemReport{}}
-	collect(r, includeStatic)
-	return r
-}

agent/internal/keys/keys.go

@@ -1,228 +0,0 @@
-package keys
-
-import (
-	"crypto/md5"
-	"encoding/base64"
-	"fmt"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"strings"
-)
-
-const authorizedKeysPath = "/root/.ssh/authorized_keys"
-const sshConfigPath = "/root/.ssh/config"
-const managedConfigPath = "/root/.ssh/vantage.conf"
-const includeDirective = "Include /root/.ssh/vantage.conf"
-
-func ReadAuthorizedKeys() ([]string, error) {
-	data, err := os.ReadFile(authorizedKeysPath)
-	if os.IsNotExist(err) {
-		return nil, nil
-	}
-	if err != nil {
-		return nil, err
-	}
-
-	var lines []string
-	for _, line := range strings.Split(string(data), "\n") {
-		line = strings.TrimSpace(line)
-		if line != "" && !strings.HasPrefix(line, "#") {
-			lines = append(lines, line)
-		}
-	}
-	return lines, nil
-}
-
-func WriteAuthorizedKeys(keys []string) error {
-	dir := filepath.Dir(authorizedKeysPath)
-	if err := os.MkdirAll(dir, 0700); err != nil {
-		return fmt.Errorf("mkdir %s: %w", dir, err)
-	}
-
-	content := strings.Join(keys, "\n")
-	if len(keys) > 0 {
-		content += "\n"
-	}
-
-	tmpPath := authorizedKeysPath + ".tmp"
-	if err := os.WriteFile(tmpPath, []byte(content), 0600); err != nil {
-		return fmt.Errorf("write tmp: %w", err)
-	}
-
-	if err := os.Rename(tmpPath, authorizedKeysPath); err != nil {
-		os.Remove(tmpPath)
-		return fmt.Errorf("rename: %w", err)
-	}
-
-	return os.Chmod(authorizedKeysPath, 0600)
-}
-
-func FingerprintLines(lines []string) map[string]bool {
-	fp := make(map[string]bool, len(lines))
-	for _, line := range lines {
-		fp[fingerprint(line)] = true
-	}
-	return fp
-}
-
-func StateChanged(current, desired []string) bool {
-	if len(current) != len(desired) {
-		return true
-	}
-	cur := FingerprintLines(current)
-	for _, line := range desired {
-		if !cur[fingerprint(line)] {
-			return true
-		}
-	}
-	return false
-}
-
-func fingerprint(pubKey string) string {
-	parts := strings.Fields(pubKey)
-	if len(parts) < 2 {
-		return pubKey
-	}
-	raw, err := base64.StdEncoding.DecodeString(parts[1])
-	if err != nil {
-		return pubKey
-	}
-	sum := md5.Sum(raw)
-	var pairs []string
-	for _, b := range sum {
-		pairs = append(pairs, fmt.Sprintf("%02x", b))
-	}
-	return "MD5:" + strings.Join(pairs, ":")
-}
-
-// KeyGenOptions controls how ssh-keygen is invoked.
-type KeyGenOptions struct {
-	KeyType    string // ed25519 (default), rsa, ecdsa
-	KeySize    int    // bits; used for rsa and ecdsa
-	Passphrase string // empty = no passphrase
-	Comment    string // embedded in the public key
-}
-
-// GenerateKeyPair generates an SSH keypair and returns the public key.
-// The private key is written to keyPath; keyPath+".pub" holds the public key.
-func GenerateKeyPair(keyPath string, opts KeyGenOptions) (string, error) {
-	if err := os.MkdirAll(filepath.Dir(keyPath), 0700); err != nil {
-		return "", err
-	}
-
-	keyType := opts.KeyType
-	if keyType == "" {
-		keyType = "ed25519"
-	}
-
-	args := []string{
-		"-t", keyType,
-		"-f", keyPath,
-		"-N", opts.Passphrase,
-		"-C", opts.Comment,
-	}
-	if opts.KeySize > 0 && keyType != "ed25519" {
-		args = append(args, "-b", fmt.Sprintf("%d", opts.KeySize))
-	}
-
-	cmd := exec.Command("ssh-keygen", args...)
-	out, err := cmd.CombinedOutput()
-	if err != nil {
-		return "", fmt.Errorf("ssh-keygen: %w: %s", err, out)
-	}
-
-	pubData, err := os.ReadFile(keyPath + ".pub")
-	if err != nil {
-		return "", fmt.Errorf("read pubkey: %w", err)
-	}
-	return strings.TrimSpace(string(pubData)), nil
-}
-
-// AddSSHIdentity writes an IdentityFile entry for keyPath into the managed
-// vantage.conf include file, and ensures ~/.ssh/config includes it.
-func AddSSHIdentity(keyPath string) error {
-	if err := os.MkdirAll(filepath.Dir(sshConfigPath), 0700); err != nil {
-		return fmt.Errorf("mkdir .ssh: %w", err)
-	}
-
-	if err := ensureIncludeDirective(); err != nil {
-		return err
-	}
-
-	// Read existing managed config (it may not exist yet).
-	var existing string
-	data, err := os.ReadFile(managedConfigPath)
-	if err != nil && !os.IsNotExist(err) {
-		return fmt.Errorf("read %s: %w", managedConfigPath, err)
-	}
-	existing = string(data)
-
-	line := "IdentityFile " + keyPath
-	for _, l := range strings.Split(existing, "\n") {
-		if strings.TrimSpace(l) == line {
-			return nil // already present
-		}
-	}
-
-	if existing != "" && !strings.HasSuffix(existing, "\n") {
-		existing += "\n"
-	}
-	updated := existing + line + "\n"
-
-	if err := os.WriteFile(managedConfigPath, []byte(updated), 0600); err != nil {
-		return fmt.Errorf("write %s: %w", managedConfigPath, err)
-	}
-	return nil
-}
-
-// RemoveSSHIdentity removes the IdentityFile entry for keyPath from the managed config.
-func RemoveSSHIdentity(keyPath string) error {
-	data, err := os.ReadFile(managedConfigPath)
-	if os.IsNotExist(err) {
-		return nil
-	}
-	if err != nil {
-		return fmt.Errorf("read %s: %w", managedConfigPath, err)
-	}
-
-	line := "IdentityFile " + keyPath
-	var kept []string
-	for _, l := range strings.Split(strings.TrimRight(string(data), "\n"), "\n") {
-		if strings.TrimSpace(l) != line {
-			kept = append(kept, l)
-		}
-	}
-
-	content := strings.Join(kept, "\n")
-	if len(kept) > 0 {
-		content += "\n"
-	}
-	if err := os.WriteFile(managedConfigPath, []byte(content), 0600); err != nil {
-		return fmt.Errorf("write %s: %w", managedConfigPath, err)
-	}
-	return nil
-}
-
-// ensureIncludeDirective adds "Include /root/.ssh/vantage.conf" to the top
-// of ~/.ssh/config if it is not already present. The Include must appear before
-// any Host stanzas to be effective for all connections.
-func ensureIncludeDirective() error {
-	data, err := os.ReadFile(sshConfigPath)
-	if err != nil && !os.IsNotExist(err) {
-		return fmt.Errorf("read %s: %w", sshConfigPath, err)
-	}
-
-	for _, l := range strings.Split(string(data), "\n") {
-		if strings.TrimSpace(l) == includeDirective {
-			return nil // already present
-		}
-	}
-
-	// Prepend the Include directive so it takes effect before any Host blocks.
-	updated := includeDirective + "\n" + string(data)
-	if err := os.WriteFile(sshConfigPath, []byte(updated), 0600); err != nil {
-		return fmt.Errorf("write %s: %w", sshConfigPath, err)
-	}
-	return nil
-}

agent/internal/monitors/monitors.go

@@ -1,166 +0,0 @@
-// Package monitors runs agent-side service checks. It polls the server for the
-// monitors assigned to this agent (SyncMonitors), runs each on its own interval
-// using the local checker package, and reports results back (ReportChecks).
-package monitors
-
-import (
-	"context"
-	"log"
-	"sync"
-	"time"
-
-	"github.com/mrhid6/vantage/agent/internal/checker"
-	"github.com/mrhid6/vantage/agent/internal/config"
-	grpcclient "github.com/mrhid6/vantage/agent/internal/grpc"
-	"github.com/mrhid6/vantage/agent/internal/grpc/pb"
-)
-
-// syncInterval controls how often the agent re-fetches its assigned monitors.
-const syncInterval = 30 * time.Second
-
-type runner struct {
-	intervalSec int
-	cancel      context.CancelFunc
-}
-
-// Run starts the agent monitor loop and blocks until ctx is cancelled.
-func Run(ctx context.Context, cfg *config.Config) {
-	active := map[string]*runner{}
-	var mu sync.Mutex
-
-	// results is a shared channel every check writes to; a single reporter
-	// goroutine batches and ships them so we make one ReportChecks call per tick.
-	results := make(chan pb.CheckResult, 64)
-	go reporter(ctx, cfg, results)
-
-	syncOnce := func() {
-		specs, err := fetchSpecs(cfg)
-		if err != nil {
-			log.Printf("monitors: sync: %v", err)
-			return
-		}
-		want := map[string]pb.MonitorSpec{}
-		for _, s := range specs {
-			want[s.MonitorId] = s
-		}
-
-		mu.Lock()
-		defer mu.Unlock()
-		for id, r := range active {
-			s, ok := want[id]
-			if !ok || s.IntervalSec != r.intervalSec {
-				r.cancel()
-				delete(active, id)
-			}
-		}
-		for id, s := range want {
-			if _, ok := active[id]; ok {
-				continue
-			}
-			rctx, cancel := context.WithCancel(ctx)
-			active[id] = &runner{intervalSec: s.IntervalSec, cancel: cancel}
-			go runSpec(rctx, s, results)
-		}
-	}
-
-	syncOnce()
-	t := time.NewTicker(syncInterval)
-	defer t.Stop()
-	for {
-		select {
-		case <-ctx.Done():
-			return
-		case <-t.C:
-			syncOnce()
-		}
-	}
-}
-
-func fetchSpecs(cfg *config.Config) ([]pb.MonitorSpec, error) {
-	client, err := grpcclient.New(cfg.ServerURL, cfg.TLS)
-	if err != nil {
-		return nil, err
-	}
-	defer client.Close()
-	return client.SyncMonitors(cfg.ServerID, cfg.AgentToken)
-}
-
-func runSpec(ctx context.Context, s pb.MonitorSpec, out chan<- pb.CheckResult) {
-	interval := time.Duration(s.IntervalSec) * time.Second
-	if interval <= 0 {
-		interval = 60 * time.Second
-	}
-	spec := checker.Spec{
-		Type:           s.Type,
-		URL:            s.URL,
-		Host:           s.Host,
-		Port:           s.Port,
-		Method:         s.Method,
-		ExpectedStatus: s.ExpectedStatus,
-		Keyword:        s.Keyword,
-		TLSWarnDays:    s.TLSWarnDays,
-		Insecure:       s.Insecure,
-		TimeoutSec:     s.IntervalSec,
-	}
-
-	run := func() {
-		res := checker.Run(ctx, spec)
-		cr := pb.CheckResult{MonitorId: s.MonitorId, Up: res.Up, LatencyMs: res.LatencyMs, Message: res.Message}
-		if res.CertExpiry != nil {
-			cr.CertExpiryUnix = res.CertExpiry.Unix()
-		}
-		select {
-		case out <- cr:
-		case <-ctx.Done():
-		}
-	}
-
-	run()
-	t := time.NewTicker(interval)
-	defer t.Stop()
-	for {
-		select {
-		case <-ctx.Done():
-			return
-		case <-t.C:
-			run()
-		}
-	}
-}
-
-// reporter batches results on a short interval and ships each batch in one call.
-func reporter(ctx context.Context, cfg *config.Config, in <-chan pb.CheckResult) {
-	t := time.NewTicker(5 * time.Second)
-	defer t.Stop()
-	var batch []pb.CheckResult
-	flush := func() {
-		if len(batch) == 0 {
-			return
-		}
-		client, err := grpcclient.New(cfg.ServerURL, cfg.TLS)
-		if err != nil {
-			log.Printf("monitors: report dial: %v", err)
-			batch = nil
-			return
-		}
-		if err := client.ReportChecks(cfg.ServerID, cfg.AgentToken, batch); err != nil {
-			log.Printf("monitors: report: %v", err)
-		}
-		client.Close()
-		batch = nil
-	}
-	for {
-		select {
-		case <-ctx.Done():
-			flush()
-			return
-		case r := <-in:
-			batch = append(batch, r)
-			if len(batch) >= 32 {
-				flush()
-			}
-		case <-t.C:
-			flush()
-		}
-	}
-}

agent/internal/sync/sync.go

@@ -1,587 +0,0 @@
-package agentsync
-
-import (
-	"context"
-	"crypto/sha256"
-	"encoding/hex"
-	"fmt"
-	"io"
-	"log"
-	"net"
-	"net/http"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"runtime"
-	"strings"
-	"sync"
-	"time"
-
-	"github.com/mrhid6/vantage/agent/internal/config"
-	agentexec "github.com/mrhid6/vantage/agent/internal/exec"
-	grpcclient "github.com/mrhid6/vantage/agent/internal/grpc"
-	"github.com/mrhid6/vantage/agent/internal/grpc/pb"
-	"github.com/mrhid6/vantage/agent/internal/inventory"
-	"github.com/mrhid6/vantage/agent/internal/keys"
-	"github.com/mrhid6/vantage/agent/internal/monitors"
-	"github.com/mrhid6/vantage/agent/internal/updates"
-)
-
-func Run(ctx context.Context, cfg *config.Config, version string) error {
-	client, err := grpcclient.New(cfg.ServerURL, cfg.TLS)
-	if err != nil {
-		return fmt.Errorf("dial grpc: %w", err)
-	}
-	defer client.Close()
-
-	// Register if we have a pre-reg token
-	if cfg.PreRegToken != "" {
-		log.Println("registering with server...")
-		hostname, _ := os.Hostname()
-		ipAddress := localIP()
-		osInfo := fmt.Sprintf("%s %s", runtime.GOOS, runtime.GOARCH)
-
-		agentToken, err := client.Register(cfg.ServerID, cfg.PreRegToken, hostname, ipAddress, osInfo)
-		if err != nil {
-			return fmt.Errorf("registration failed: %w", err)
-		}
-
-		cfg.AgentToken = agentToken
-		cfg.PreRegToken = ""
-		if err := config.Save(cfg); err != nil {
-			return fmt.Errorf("save config: %w", err)
-		}
-		log.Println("registration successful")
-
-		client.Close()
-		client, err = grpcclient.New(cfg.ServerURL, cfg.TLS)
-		if err != nil {
-			return fmt.Errorf("reconnect: %w", err)
-		}
-	}
-
-	if cfg.AgentToken == "" {
-		return fmt.Errorf("no agent token available — registration required")
-	}
-
-	// Start the command stream alongside the poll loop.
-	go runCommandStream(ctx, cfg)
-
-	// Check for OS updates on startup and then hourly.
-	go runUpdateCheck(ctx, cfg)
-
-	// Report host inventory: metrics every 30s, full static snapshot every 15 min.
-	go runInventory(ctx, cfg)
-
-	// Run agent-side service monitors assigned to this server.
-	go monitors.Run(ctx, cfg)
-
-	ticker := time.NewTicker(cfg.PollInterval)
-	defer ticker.Stop()
-
-	// Run immediately on startup
-	if err := poll(client, cfg, version); err != nil {
-		log.Printf("poll error: %v", err)
-	}
-
-	for {
-		select {
-		case <-ctx.Done():
-			return nil
-		case <-ticker.C:
-			if err := poll(client, cfg, version); err != nil {
-				log.Printf("poll error: %v", err)
-			}
-		}
-	}
-}
-
-func poll(client *grpcclient.Client, cfg *config.Config, version string) error {
-	desired, err := client.SyncKeys(cfg.ServerID, cfg.AgentToken, version)
-	if err != nil {
-		return fmt.Errorf("SyncKeys: %w", err)
-	}
-
-	// Windows agents register and heartbeat only — no authorized_keys management.
-	if runtime.GOOS != "linux" {
-		return nil
-	}
-
-	current, err := keys.ReadAuthorizedKeys()
-	if err != nil {
-		return fmt.Errorf("read authorized_keys: %w", err)
-	}
-
-	if !keys.StateChanged(current, desired) {
-		log.Println("authorized_keys unchanged, skipping write")
-		return nil
-	}
-
-	if err := keys.WriteAuthorizedKeys(desired); err != nil {
-		return fmt.Errorf("write authorized_keys: %w", err)
-	}
-	log.Printf("authorized_keys updated (%d keys)", len(desired))
-	return nil
-}
-
-// runCommandStream maintains a persistent bidirectional stream with the server
-// for instant command delivery. Reconnects with exponential backoff on failure.
-func runCommandStream(ctx context.Context, cfg *config.Config) {
-	backoff := time.Second
-	const maxBackoff = 2 * time.Minute
-
-	for {
-		select {
-		case <-ctx.Done():
-			return
-		default:
-		}
-
-		if err := connectAndHandleStream(ctx, cfg); err != nil {
-			if ctx.Err() != nil {
-				return
-			}
-			log.Printf("command stream error: %v, reconnecting in %s", err, backoff)
-			select {
-			case <-ctx.Done():
-				return
-			case <-time.After(backoff):
-			}
-			if backoff < maxBackoff {
-				backoff *= 2
-			}
-		} else {
-			backoff = time.Second
-		}
-	}
-}
-
-func connectAndHandleStream(ctx context.Context, cfg *config.Config) error {
-	client, err := grpcclient.New(cfg.ServerURL, cfg.TLS)
-	if err != nil {
-		return fmt.Errorf("dial: %w", err)
-	}
-	defer client.Close()
-
-	stream, err := client.CommandStream(ctx)
-	if err != nil {
-		return fmt.Errorf("open stream: %w", err)
-	}
-
-	if err := stream.Send(&pb.AgentMessage{
-		ServerId:   cfg.ServerID,
-		AgentToken: cfg.AgentToken,
-		Ready:      &pb.AgentReady{},
-	}); err != nil {
-		return fmt.Errorf("send auth: %w", err)
-	}
-
-	log.Println("command stream connected")
-
-	// grpc streams are not safe for concurrent Send; RunStep results are sent
-	// from per-command goroutines, so all sends on this stream must go through
-	// this mutex-protected helper.
-	var sendMu sync.Mutex
-	send := func(msg *pb.AgentMessage) error {
-		sendMu.Lock()
-		defer sendMu.Unlock()
-		return stream.Send(msg)
-	}
-
-	for {
-		cmd, err := stream.Recv()
-		if err != nil {
-			return fmt.Errorf("recv: %w", err)
-		}
-
-		if cmd.GenerateKey != nil {
-			go handleGenerateKey(cfg, cmd)
-		}
-		if cmd.DeleteKey != nil {
-			go handleDeleteKey(cmd)
-		}
-		if cmd.UpdateAgent != nil {
-			go handleUpdateAgent(cmd)
-		}
-		if cmd.ApplyUpdates != nil {
-			go handleApplyUpdates(cfg, cmd)
-		}
-		if cmd.CleanupWorkspace != nil {
-			go handleCleanupWorkspace(cmd)
-		}
-		if cmd.RunStep != nil {
-			go func(rc *pb.RunStepCmd, cid string) {
-				emit := func(seq uint64, data []byte) {
-					_ = send(&pb.AgentMessage{
-						ServerId:   cfg.ServerID,
-						AgentToken: cfg.AgentToken,
-						StepOutput: &pb.StepOutputChunk{CommandId: cid, Seq: seq, Data: data},
-					})
-				}
-				res := agentexec.RunStep(rc, emit)
-				res.CommandId = cid
-				// Final eof marker so the server closes the log file.
-				_ = send(&pb.AgentMessage{
-					ServerId:   cfg.ServerID,
-					AgentToken: cfg.AgentToken,
-					StepOutput: &pb.StepOutputChunk{CommandId: cid, Eof: true},
-				})
-				_ = send(&pb.AgentMessage{
-					ServerId:   cfg.ServerID,
-					AgentToken: cfg.AgentToken,
-					StepResult: res,
-				})
-			}(cmd.RunStep, cmd.CommandId)
-			continue
-		}
-	}
-}
-
-func runUpdateCheck(ctx context.Context, cfg *config.Config) {
-	const interval = time.Hour
-
-	doCheck := func() {
-		pkgs, err := updates.CheckAvailable()
-		if err != nil {
-			log.Printf("update check error: %v", err)
-			return
-		}
-		pbUpdates := make([]pb.PackageUpdate, len(pkgs))
-		for i, p := range pkgs {
-			pbUpdates[i] = pb.PackageUpdate{
-				Name:           p.Name,
-				CurrentVersion: p.CurrentVersion,
-				NewVersion:     p.NewVersion,
-			}
-		}
-		client, err := grpcclient.New(cfg.ServerURL, cfg.TLS)
-		if err != nil {
-			log.Printf("update report dial error: %v", err)
-			return
-		}
-		defer client.Close()
-		if err := client.ReportUpdates(cfg.ServerID, cfg.AgentToken, pbUpdates); err != nil {
-			log.Printf("ReportUpdates error: %v", err)
-			return
-		}
-		log.Printf("reported %d available OS updates", len(pkgs))
-	}
-
-	doCheck()
-	ticker := time.NewTicker(interval)
-	defer ticker.Stop()
-	for {
-		select {
-		case <-ctx.Done():
-			return
-		case <-ticker.C:
-			doCheck()
-		}
-	}
-}
-
-// runInventory reports host metrics every 30s and a full static snapshot every
-// 15 min (and once immediately on startup so static fields populate without delay).
-func runInventory(ctx context.Context, cfg *config.Config) {
-	client, err := grpcclient.New(cfg.ServerURL, cfg.TLS)
-	if err != nil {
-		log.Printf("inventory dial error: %v", err)
-		return
-	}
-	defer client.Close()
-
-	report := func(static bool) {
-		r := inventory.Collect(static)
-		r.ServerId = cfg.ServerID
-		r.AgentToken = cfg.AgentToken
-		if err := client.ReportInventory(r); err != nil {
-			log.Printf("report inventory: %v", err)
-		}
-	}
-
-	report(true) // full snapshot on startup
-	ticker := time.NewTicker(30 * time.Second)
-	defer ticker.Stop()
-	tick := 0
-	for {
-		select {
-		case <-ctx.Done():
-			return
-		case <-ticker.C:
-			tick++
-			report(tick%30 == 0) // every 30th tick = 15 min → include static
-		}
-	}
-}
-
-func handleApplyUpdates(cfg *config.Config, cmd *pb.ServerCommand) {
-	log.Printf("applying OS updates (cmd=%s)…", cmd.CommandId)
-	if err := updates.ApplyAll(); err != nil {
-		log.Printf("OS upgrade failed (cmd=%s): %v", cmd.CommandId, err)
-		return
-	}
-	log.Printf("OS updates applied successfully (cmd=%s)", cmd.CommandId)
-
-	// Re-report the (now empty) update list so the server reflects the new state.
-	client, err := grpcclient.New(cfg.ServerURL, cfg.TLS)
-	if err != nil {
-		return
-	}
-	defer client.Close()
-	_ = client.ReportUpdates(cfg.ServerID, cfg.AgentToken, nil)
-}
-
-func handleCleanupWorkspace(cmd *pb.ServerCommand) {
-	id := cmd.CleanupWorkspace.WorkspaceId
-	dir := agentexec.WorkspacePath(id)
-	if err := os.RemoveAll(dir); err != nil {
-		log.Printf("cleanup workspace %s failed (cmd=%s): %v", dir, cmd.CommandId, err)
-		return
-	}
-	log.Printf("removed run workspace %s (cmd=%s)", dir, cmd.CommandId)
-}
-
-func handleDeleteKey(cmd *pb.ServerCommand) {
-	label := cmd.DeleteKey.Label
-	keyPath := fmt.Sprintf("/root/.ssh/vantage_%s", strings.ReplaceAll(label, " ", "_"))
-
-	if err := keys.RemoveSSHIdentity(keyPath); err != nil {
-		log.Printf("remove ssh identity failed (cmd=%s): %v", cmd.CommandId, err)
-	}
-
-	for _, path := range []string{keyPath, keyPath + ".pub"} {
-		if err := os.Remove(path); err != nil && !os.IsNotExist(err) {
-			log.Printf("delete key file %s (cmd=%s): %v", path, cmd.CommandId, err)
-		}
-	}
-	log.Printf("deleted local key files for %q (cmd=%s)", label, cmd.CommandId)
-}
-
-func handleUpdateAgent(cmd *pb.ServerCommand) {
-	if runtime.GOOS == "windows" {
-		handleUpdateAgentWindows(cmd)
-		return
-	}
-
-	u := cmd.UpdateAgent
-	arch := runtime.GOARCH // "amd64" or "arm64"
-	tag := "agent%2Fv" + u.Version
-	binaryURL := fmt.Sprintf("%s/mrhid6/vantage/releases/download/%s/vantage-agent-linux-%s", u.GiteaBaseURL, tag, arch)
-	checksumURL := fmt.Sprintf("%s/mrhid6/vantage/releases/download/%s/checksums.txt", u.GiteaBaseURL, tag)
-
-	log.Printf("updating agent to v%s from %s (cmd=%s)", u.Version, u.GiteaBaseURL, cmd.CommandId)
-
-	// Download binary
-	tmpBin := "/tmp/vantage-agent-update"
-	if err := downloadFile(binaryURL, tmpBin); err != nil {
-		log.Printf("update download failed (cmd=%s): %v", cmd.CommandId, err)
-		return
-	}
-
-	// Download and verify checksum
-	checksumData, err := httpGetBytes(checksumURL)
-	if err != nil {
-		log.Printf("update checksum fetch failed (cmd=%s): %v", cmd.CommandId, err)
-		return
-	}
-	if err := verifyChecksum(tmpBin, fmt.Sprintf("vantage-agent-linux-%s", arch), checksumData); err != nil {
-		log.Printf("update checksum mismatch (cmd=%s): %v", cmd.CommandId, err)
-		os.Remove(tmpBin)
-		return
-	}
-
-	if err := os.Chmod(tmpBin, 0755); err != nil {
-		log.Printf("update chmod failed (cmd=%s): %v", cmd.CommandId, err)
-		return
-	}
-	if err := os.Rename(tmpBin, "/usr/local/bin/vantage-agent"); err != nil {
-		log.Printf("update replace binary failed (cmd=%s): %v", cmd.CommandId, err)
-		return
-	}
-
-	log.Printf("agent binary replaced, restarting service (cmd=%s)", cmd.CommandId)
-	exec.Command("systemctl", "restart", "vantage-agent").Run()
-}
-
-// handleUpdateAgentWindows downloads the latest MSI and launches msiexec to
-// perform a MajorUpgrade. msiexec is started DETACHED (via "cmd /c start") so
-// that when the upgrade stops the VantageAgent service, nssm's process-tree
-// kill of this agent does not also kill the installer mid-flight. Config
-// (server_id, agent_token) is preserved by setup.ps1 on upgrade.
-func handleUpdateAgentWindows(cmd *pb.ServerCommand) {
-	u := cmd.UpdateAgent
-	tag := "agent%2Fv" + u.Version
-	msiURL := fmt.Sprintf("%s/mrhid6/vantage/releases/download/%s/vantage-agent.msi", u.GiteaBaseURL, tag)
-	checksumURL := fmt.Sprintf("%s/mrhid6/vantage/releases/download/%s/checksums-msi.txt", u.GiteaBaseURL, tag)
-
-	log.Printf("updating agent to v%s from %s (cmd=%s)", u.Version, u.GiteaBaseURL, cmd.CommandId)
-
-	msiPath := filepath.Join(os.TempDir(), "vantage-agent-update.msi")
-	if err := downloadFile(msiURL, msiPath); err != nil {
-		log.Printf("update download failed (cmd=%s): %v", cmd.CommandId, err)
-		return
-	}
-
-	checksumData, err := httpGetBytes(checksumURL)
-	if err != nil {
-		log.Printf("update checksum fetch failed (cmd=%s): %v", cmd.CommandId, err)
-		return
-	}
-	if err := verifyChecksum(msiPath, "vantage-agent.msi", checksumData); err != nil {
-		log.Printf("update checksum mismatch (cmd=%s): %v", cmd.CommandId, err)
-		os.Remove(msiPath)
-		return
-	}
-
-	logPath := filepath.Join(os.TempDir(), "vantage-agent-msi.log")
-	log.Printf("launching msiexec for upgrade to v%s (cmd=%s)", u.Version, cmd.CommandId)
-	// "start" detaches msiexec from this process tree so the service stop
-	// during the upgrade does not terminate the installer.
-	up := exec.Command("cmd", "/c", "start", "", "/wait", "msiexec", "/i", msiPath, "/qn", "/norestart", "/l*v", logPath)
-	if err := up.Start(); err != nil {
-		log.Printf("failed to launch msiexec (cmd=%s): %v", cmd.CommandId, err)
-		return
-	}
-}
-
-func downloadFile(url, dest string) error {
-	resp, err := http.Get(url) //nolint:gosec
-	if err != nil {
-		return err
-	}
-	defer resp.Body.Close()
-	if resp.StatusCode != http.StatusOK {
-		return fmt.Errorf("HTTP %d from %s", resp.StatusCode, url)
-	}
-	f, err := os.Create(dest)
-	if err != nil {
-		return err
-	}
-	defer f.Close()
-	_, err = io.Copy(f, resp.Body)
-	return err
-}
-
-func httpGetBytes(url string) ([]byte, error) {
-	resp, err := http.Get(url) //nolint:gosec
-	if err != nil {
-		return nil, err
-	}
-	defer resp.Body.Close()
-	if resp.StatusCode != http.StatusOK {
-		return nil, fmt.Errorf("HTTP %d from %s", resp.StatusCode, url)
-	}
-	return io.ReadAll(resp.Body)
-}
-
-func verifyChecksum(filePath, filename string, checksumData []byte) error {
-	f, err := os.Open(filePath)
-	if err != nil {
-		return err
-	}
-	defer f.Close()
-	h := sha256.New()
-	if _, err := io.Copy(h, f); err != nil {
-		return err
-	}
-	actual := hex.EncodeToString(h.Sum(nil))
-
-	for _, line := range strings.Split(string(checksumData), "\n") {
-		fields := strings.Fields(line)
-		if len(fields) == 2 && fields[1] == filename {
-			if fields[0] != actual {
-				return fmt.Errorf("expected %s got %s", fields[0], actual)
-			}
-			return nil
-		}
-	}
-	return fmt.Errorf("no checksum entry found for %s", filename)
-}
-
-func handleGenerateKey(cfg *config.Config, cmd *pb.ServerCommand) {
-	g := cmd.GenerateKey
-	label := g.Label
-	keyPath := fmt.Sprintf("/root/.ssh/vantage_%s", strings.ReplaceAll(label, " ", "_"))
-
-	opts := keys.KeyGenOptions{
-		KeyType:    g.KeyType,
-		KeySize:    g.KeySize,
-		Passphrase: g.Passphrase,
-		Comment:    g.Comment,
-	}
-	pubKey, err := keys.GenerateKeyPair(keyPath, opts)
-	if err != nil {
-		log.Printf("key generation failed (cmd=%s): %v", cmd.CommandId, err)
-		return
-	}
-
-	privKeyData, err := os.ReadFile(keyPath)
-	if err != nil {
-		log.Printf("read private key failed (cmd=%s): %v", cmd.CommandId, err)
-		return
-	}
-
-	client, err := grpcclient.New(cfg.ServerURL, cfg.TLS)
-	if err != nil {
-		log.Printf("dial for key upload failed (cmd=%s): %v", cmd.CommandId, err)
-		return
-	}
-	defer client.Close()
-
-	keyID, err := client.UploadGeneratedKey(cfg.ServerID, cfg.AgentToken, pubKey, string(privKeyData), label)
-	if err != nil {
-		log.Printf("key upload failed (cmd=%s): %v", cmd.CommandId, err)
-		return
-	}
-
-	if err := keys.AddSSHIdentity(keyPath); err != nil {
-		log.Printf("add ssh identity failed (cmd=%s): %v", cmd.CommandId, err)
-	}
-	log.Printf("generated and uploaded key %q (key_id=%s, cmd=%s)", label, keyID, cmd.CommandId)
-}
-
-func localIP() string {
-	addrs, err := net.InterfaceAddrs()
-	if err != nil {
-		return ""
-	}
-	for _, addr := range addrs {
-		if ipNet, ok := addr.(*net.IPNet); ok && !ipNet.IP.IsLoopback() {
-			if ipNet.IP.To4() != nil {
-				return ipNet.IP.String()
-			}
-		}
-	}
-	return ""
-}
-
-// GenerateAndUpload generates an SSH keypair and uploads the public key to the server.
-func GenerateAndUpload(cfg *config.Config, label string) error {
-	client, err := grpcclient.New(cfg.ServerURL, cfg.TLS)
-	if err != nil {
-		return err
-	}
-	defer client.Close()
-
-	keyPath := fmt.Sprintf("/root/.ssh/vantage_%s", strings.ReplaceAll(label, " ", "_"))
-	pubKey, err := keys.GenerateKeyPair(keyPath, keys.KeyGenOptions{Comment: label})
-	if err != nil {
-		return err
-	}
-
-	privKeyData, err := os.ReadFile(keyPath)
-	if err != nil {
-		return fmt.Errorf("read private key: %w", err)
-	}
-
-	keyID, err := client.UploadGeneratedKey(cfg.ServerID, cfg.AgentToken, pubKey, string(privKeyData), label)
-	if err != nil {
-		return err
-	}
-
-	if err := keys.AddSSHIdentity(keyPath); err != nil {
-		log.Printf("add ssh identity: %v", err)
-	}
-	log.Printf("uploaded generated key %s (key_id=%s)", label, keyID)
-	return nil
-}

agent/internal/updates/updates.go

@@ -1,239 +0,0 @@
-package updates
-
-import (
-	"bufio"
-	"bytes"
-	"context"
-	"os/exec"
-	"strings"
-	"time"
-)
-
-type PackageUpdate struct {
-	Name           string
-	CurrentVersion string
-	NewVersion     string
-}
-
-func detectPM() string {
-	for _, pm := range []string{"apt-get", "dnf", "yum", "pacman", "zypper", "apk"} {
-		if _, err := exec.LookPath(pm); err == nil {
-			if pm == "apt-get" {
-				return "apt"
-			}
-			return pm
-		}
-	}
-	return ""
-}
-
-// CheckAvailable returns the list of packages with available upgrades.
-// Returns nil, nil when no supported package manager is found.
-func CheckAvailable() ([]PackageUpdate, error) {
-	switch detectPM() {
-	case "apt":
-		return checkApt()
-	case "dnf":
-		return checkDnfYum("dnf")
-	case "yum":
-		return checkDnfYum("yum")
-	case "pacman":
-		return checkPacman()
-	case "zypper":
-		return checkZypper()
-	case "apk":
-		return checkApk()
-	default:
-		return nil, nil
-	}
-}
-
-// ApplyAll runs a full non-interactive upgrade using the detected package manager.
-func ApplyAll() error {
-	switch detectPM() {
-	case "apt":
-		// Refresh lists first, then upgrade.
-		ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
-		defer cancel()
-		if err := exec.CommandContext(ctx, "apt-get", "update", "-qq").Run(); err != nil {
-			return err
-		}
-		return exec.CommandContext(ctx, "apt-get", "upgrade", "-y").Run()
-	case "dnf":
-		return exec.Command("dnf", "upgrade", "-y").Run()
-	case "yum":
-		return exec.Command("yum", "upgrade", "-y").Run()
-	case "pacman":
-		return exec.Command("pacman", "-Syu", "--noconfirm").Run()
-	case "zypper":
-		return exec.Command("zypper", "update", "-y").Run()
-	case "apk":
-		return exec.Command("apk", "upgrade").Run()
-	default:
-		return nil
-	}
-}
-
-func checkApt() ([]PackageUpdate, error) {
-	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
-	defer cancel()
-	// Best-effort refresh; ignore errors (cached data is fine).
-	exec.CommandContext(ctx, "apt-get", "update", "-qq").Run() //nolint:errcheck
-
-	out, err := exec.Command("apt", "list", "--upgradable").Output()
-	if err != nil {
-		return nil, err
-	}
-	var updates []PackageUpdate
-	scanner := bufio.NewScanner(bytes.NewReader(out))
-	for scanner.Scan() {
-		line := scanner.Text()
-		// Format: package/suite version arch [upgradable from: old-ver]
-		if !strings.Contains(line, "[upgradable from:") {
-			continue
-		}
-		parts := strings.Fields(line)
-		if len(parts) < 2 {
-			continue
-		}
-		name := strings.SplitN(parts[0], "/", 2)[0]
-		newVer := parts[1]
-		oldVer := ""
-		if idx := strings.Index(line, "upgradable from: "); idx != -1 {
-			rest := line[idx+len("upgradable from: "):]
-			oldVer = strings.TrimSuffix(strings.TrimSpace(rest), "]")
-		}
-		updates = append(updates, PackageUpdate{Name: name, CurrentVersion: oldVer, NewVersion: newVer})
-	}
-	return updates, nil
-}
-
-func checkDnfYum(pm string) ([]PackageUpdate, error) {
-	cmd := exec.Command(pm, "check-update")
-	out, err := cmd.Output()
-	// Exit code 100 means updates are available — not an error.
-	if exitErr, ok := err.(*exec.ExitError); ok && exitErr.ExitCode() == 100 {
-		err = nil
-	}
-	if err != nil {
-		return nil, err
-	}
-	var updates []PackageUpdate
-	pastHeader := false
-	scanner := bufio.NewScanner(bytes.NewReader(out))
-	for scanner.Scan() {
-		line := scanner.Text()
-		if !pastHeader {
-			if strings.TrimSpace(line) == "" {
-				pastHeader = true
-			}
-			continue
-		}
-		parts := strings.Fields(line)
-		if len(parts) < 2 {
-			continue
-		}
-		// name.arch  new-version  repo
-		name := strings.SplitN(parts[0], ".", 2)[0]
-		updates = append(updates, PackageUpdate{Name: name, NewVersion: parts[1]})
-	}
-	return updates, nil
-}
-
-func checkPacman() ([]PackageUpdate, error) {
-	out, _ := exec.Command("pacman", "-Qu").Output()
-	var updates []PackageUpdate
-	scanner := bufio.NewScanner(bytes.NewReader(out))
-	for scanner.Scan() {
-		parts := strings.Fields(scanner.Text())
-		// Format: package old-version -> new-version
-		if len(parts) < 4 {
-			continue
-		}
-		updates = append(updates, PackageUpdate{Name: parts[0], CurrentVersion: parts[1], NewVersion: parts[3]})
-	}
-	return updates, nil
-}
-
-func checkZypper() ([]PackageUpdate, error) {
-	out, err := exec.Command("zypper", "list-updates").Output()
-	if err != nil {
-		return nil, err
-	}
-	var updates []PackageUpdate
-	scanner := bufio.NewScanner(bytes.NewReader(out))
-	for scanner.Scan() {
-		line := scanner.Text()
-		// Data rows start with "v |" (available) or "i |" (installed but updatable).
-		if !strings.HasPrefix(line, "v |") && !strings.HasPrefix(line, "i |") {
-			continue
-		}
-		parts := strings.Split(line, "|")
-		if len(parts) < 5 {
-			continue
-		}
-		updates = append(updates, PackageUpdate{
-			Name:           strings.TrimSpace(parts[2]),
-			CurrentVersion: strings.TrimSpace(parts[3]),
-			NewVersion:     strings.TrimSpace(parts[4]),
-		})
-	}
-	return updates, nil
-}
-
-func checkApk() ([]PackageUpdate, error) {
-	out, err := exec.Command("apk", "list", "--upgradable").Output()
-	if err != nil {
-		return nil, err
-	}
-	var updates []PackageUpdate
-	scanner := bufio.NewScanner(bytes.NewReader(out))
-	for scanner.Scan() {
-		line := scanner.Text()
-		if !strings.Contains(line, "[upgradable") {
-			continue
-		}
-		parts := strings.Fields(line)
-		if len(parts) < 1 {
-			continue
-		}
-		pkgVer := parts[0]
-		name := apkName(pkgVer)
-		newVer := apkVersion(pkgVer)
-		oldVer := ""
-		if idx := strings.Index(line, "upgradable from:"); idx != -1 {
-			rest := strings.TrimSpace(line[idx+len("upgradable from:"):])
-			rest = strings.TrimSuffix(rest, "]")
-			oldVer = apkVersion(strings.TrimSpace(rest))
-		}
-		updates = append(updates, PackageUpdate{Name: name, CurrentVersion: oldVer, NewVersion: newVer})
-	}
-	return updates, nil
-}
-
-func apkName(pkgVer string) string {
-	parts := strings.Split(pkgVer, "-")
-	var name []string
-	for _, p := range parts {
-		if len(p) > 0 && p[0] >= '0' && p[0] <= '9' {
-			break
-		}
-		name = append(name, p)
-	}
-	return strings.Join(name, "-")
-}
-
-func apkVersion(pkgVer string) string {
-	parts := strings.Split(pkgVer, "-")
-	var ver []string
-	inVer := false
-	for _, p := range parts {
-		if !inVer && len(p) > 0 && p[0] >= '0' && p[0] <= '9' {
-			inVer = true
-		}
-		if inVer {
-			ver = append(ver, p)
-		}
-	}
-	return strings.Join(ver, "-")
-}

claude.md

@@ -1,351 +0,0 @@
-# Vantage
-
-A self-hosted SSH key management system. A central server (Go + Next.js + MongoDB) manages public key assignments across servers. A lightweight Go agent runs on each managed server, polls the central server via gRPC, and atomically rewrites `/root/.ssh/authorized_keys` to match the desired state.
-
----
-
-## Architecture Overview
-
-```
-┌─────────────────────────────────┐
-│  Next.js Frontend               │
-│  - Upload/manage keys           │
-│  - Add servers (install script) │
-│  - Assign/revoke per server     │
-└────────────┬────────────────────┘
-             │ REST
-┌────────────▼────────────────────┐
-│  Go Backend                     │
-│  - REST API for frontend        │
-│  - gRPC server for agents       │
-│  - MongoDB                      │
-└────────────┬────────────────────┘
-             │ gRPC (TLS)
-┌────────────▼────────────────────┐
-│  Go Agent (per server)          │
-│  - Polls every 30s              │
-│  - Rewrites authorized_keys     │
-│  - Can generate SSH keypairs    │
-└─────────────────────────────────┘
-```
-
----
-
-## Repository Structure
-
-```
-vantage/
-├── agent/
-│   ├── cmd/main.go
-│   └── internal/
-│       ├── config/
-│       ├── grpc/
-│       ├── keys/
-│       └── sync/
-├── server/
-│   ├── cmd/main.go
-│   └── internal/
-│       ├── api/          # REST handlers for Next.js
-│       ├── grpc/         # gRPC server implementation
-│       ├── models/       # MongoDB models
-│       └── services/
-│           ├── keys.go
-│           ├── servers.go
-│           └── sync.go   # builds desired state per server
-├── web/
-│   ├── app/
-│   └── components/
-├── proto/
-│   └── vantage/v1/vantage.proto
-├── deploy/
-│   ├── docker-compose.yml
-│   └── agent.service
-└── .gitea/
-    └── workflows/
-        ├── agent-release.yml
-        └── server-deploy.yml
-```
-
----
-
-## gRPC API
-
-```protobuf
-syntax = "proto3";
-package vantage.v1;
-
-service Vantage {
-  rpc Register(RegisterRequest)           returns (RegisterResponse);
-  rpc SyncKeys(SyncRequest)               returns (SyncResponse);
-  rpc UploadGeneratedKey(UploadKeyRequest) returns (UploadKeyResponse);
-}
-
-message RegisterRequest {
-  string server_id      = 1;
-  string pre_reg_token  = 2;
-  string hostname       = 3;
-  string ip_address     = 4;
-  string os_info        = 5;
-}
-message RegisterResponse {
-  string agent_token = 1;
-}
-
-message SyncRequest {
-  string server_id   = 1;
-  string agent_token = 2;
-}
-message SyncResponse {
-  repeated string public_keys = 1; // full authorized_keys lines
-}
-
-message UploadKeyRequest {
-  string server_id   = 1;
-  string agent_token = 2;
-  string public_key  = 3;
-  string label       = 4;
-}
-message UploadKeyResponse {
-  string key_id = 1;
-}
-```
-
-No streaming — polling only. Poll interval: **30 seconds**.
-
----
-
-## MongoDB Collections
-
-### `servers`
-
-```json
-{
-    "_id": "ObjectId",
-    "server_id": "uuid",
-    "hostname": "proxmox-node-1",
-    "ip_address": "10.10.10.5",
-    "os_info": "Ubuntu 24.04",
-    "pre_reg_token": "abc123",
-    "pre_reg_expires": "ISODate",
-    "agent_token_hash": "sha256...",
-    "status": "pending|active|offline",
-    "last_seen": "ISODate",
-    "created_at": "ISODate"
-}
-```
-
-- `pre_reg_token` is cleared after the agent successfully calls `Register()`
-- `agent_token_hash` stores SHA-256 of the token — never plaintext
-- `status` transitions: `pending` → `active` on first `Register()`, `offline` if last_seen exceeds threshold
-
-### `keys`
-
-```json
-{
-    "_id": "ObjectId",
-    "key_id": "uuid",
-    "label": "dom-macbook",
-    "public_key": "ssh-ed25519 AAAA...",
-    "fingerprint": "SHA256:...",
-    "source": "uploaded|generated",
-    "generated_by_server_id": "uuid",
-    "created_at": "ISODate"
-}
-```
-
-### `assignments`
-
-```json
-{
-    "_id": "ObjectId",
-    "key_id": "uuid",
-    "server_id": "uuid",
-    "assigned_at": "ISODate",
-    "revoked_at": "ISODate | null"
-}
-```
-
-- `revoked_at: null` = key is active on that server
-- Revocation is soft — set `revoked_at`, agent picks it up on next poll
-
----
-
-## Agent Lifecycle
-
-### Config file — `/etc/vantage/config.yaml`
-
-```yaml
-server_url: "vantage.yourdomain.com:9090"
-server_id: "<uuid>"
-pre_reg_token: "<token>" # removed after first successful Register()
-agent_token: "" # written by agent after Register()
-poll_interval: 30s
-tls: true
-```
-
-Config file permissions: `0600`. Config directory: `0700`.
-
-### Startup flow
-
-```
-1. Load config
-2. If pre_reg_token present:
-     → call Register(server_id, pre_reg_token, hostname, ip, os_info)
-     → save returned agent_token to config
-     → delete pre_reg_token from config
-3. Enter poll loop
-```
-
-### Poll loop (every 30s)
-
-```
-1. Call SyncKeys(server_id, agent_token)
-2. Receive []public_keys
-3. Compute fingerprints of current /root/.ssh/authorized_keys
-4. If state unchanged → skip write
-5. If changed:
-     → write to /root/.ssh/authorized_keys.tmp
-     → os.Rename() to /root/.ssh/authorized_keys  (atomic)
-     → chmod 0600
-```
-
-### Key generation (on demand)
-
-- Triggered by a flag or API call from the server
-- Runs `ssh-keygen` via `exec.Command`
-- Uploads public key via `UploadGeneratedKey()`
-- Private key stays local on the machine
-
-### Systemd unit — `/etc/systemd/system/vantage-agent.service`
-
-```ini
-[Unit]
-Description=Vantage Agent
-After=network.target
-
-[Service]
-ExecStart=/usr/local/bin/vantage-agent
-Restart=always
-RestartSec=10
-User=root
-
-[Install]
-WantedBy=multi-user.target
-```
-
----
-
-## Server Registration Flow
-
-1. Click **Add Server** in the UI
-2. Backend generates a short-lived pre-registration token (TTL: 1 hour) and a `server_id`
-3. UI displays a one-liner install command with copy button:
-    ```bash
-    curl -fsSL https://vantage.yourdomain.com/install | \
-      bash -s -- --server-id=<id> --token=<token>
-    ```
-4. Install script:
-    - Detects arch (`amd64` / `arm64`)
-    - Downloads agent binary from Gitea release
-    - Verifies SHA-256 checksum
-    - Writes `/etc/vantage/config.yaml`
-    - Installs and starts systemd unit
-5. On first `SyncKeys` call, server marks status as `active`
-
-The backend serves `/install` dynamically, injecting the latest agent version by querying the Gitea API for the most recent `agent/v*` release tag.
-
----
-
-## Security
-
-- gRPC over TLS (Let's Encrypt or self-signed with cert pinning on the agent)
-- Agent authenticates with a per-server token stored at `/etc/vantage/config.yaml` (`0600`)
-- Server stores `SHA-256(agent_token)` — never the plaintext token
-- Private keys generated by agents are encrypted at rest in MongoDB (AES-256)
-- `authorized_keys` written as `0600`, owned by root
-- Pre-registration tokens are short-lived (1 hour) and single-use
-- Agent runs as `root` (required for `/root/.ssh/authorized_keys` writes)
-
----
-
-## Frontend Routes
-
-| Route           | Purpose                                                              |
-| --------------- | -------------------------------------------------------------------- |
-| `/servers`      | List all servers, online/offline status badge, last seen timestamp   |
-| `/servers/new`  | Displays the one-liner install script with copy button               |
-| `/servers/[id]` | Keys installed on this server, trigger key generation, remove server |
-| `/keys`         | All keys — label, fingerprint, source, assigned count                |
-| `/keys/[id]`    | Assign key to servers, revoke per server                             |
-
----
-
-## CI/CD — Gitea Actions
-
-### Agent release — `.gitea/workflows/agent-release.yml`
-
-Triggered by a `agent/v*` tag. Cross-compiles for `linux/amd64` and `linux/arm64`, creates a Gitea release with binaries and checksums.
-
-```yaml
-on:
-    push:
-        tags:
-            - "agent/v*"
-```
-
-Build command:
-
-```bash
-GOOS=linux GOARCH=amd64 go build \
-  -ldflags="-s -w -X main.Version=${VERSION}" \
-  -o dist/vantage-agent-linux-amd64 ./cmd
-```
-
-Release assets:
-
-- `vantage-agent-linux-amd64`
-- `vantage-agent-linux-arm64`
-- `checksums.txt`
-
-### Server deploy — `.gitea/workflows/server-deploy.yml`
-
-Triggered on pushes to `main` touching `server/**`, `web/**`, or `proto/**`. Builds and pushes Docker images to the Gitea container registry, then deploys via SSH:
-
-```bash
-cd /opt/vantage && docker compose pull && docker compose up -d --remove-orphans
-```
-
-### Tagging convention
-
-```bash
-# Release a new agent version
-git tag agent/v1.0.0 && git push origin agent/v1.0.0
-
-# Server + web deploy automatically on push to main
-git push origin main
-```
-
-### Required Gitea secrets / variables
-
-| Name                | Type     | Value                                      |
-| ------------------- | -------- | ------------------------------------------ |
-| `RELEASE_TOKEN`     | Secret   | Gitea API token with `write:release` scope |
-| `REGISTRY_USER`     | Secret   | Gitea username                             |
-| `REGISTRY_PASSWORD` | Secret   | Gitea token with `write:packages` scope    |
-| `DEPLOY_HOST`       | Secret   | IP/hostname of the server VM               |
-| `DEPLOY_USER`       | Secret   | SSH user for deploy                        |
-| `DEPLOY_SSH_KEY`    | Secret   | Private key for deploy SSH                 |
-| `GITEA_HOST`        | Variable | `gitea.hostxtra.co.uk`                     |
-
----
-
-## Design Decisions
-
-- **gRPC over REST for agent communication** — strong typing, easy versioning, bi-directional streaming available later if push-based updates are needed
-- **Poll-only, no streaming** — 30s interval is sufficient for a homelab; simplifies agent implementation
-- **Outbound-only agent connections** — no inbound firewall holes required on managed servers
-- **Atomic `authorized_keys` rewrite** — write to `.tmp` then `os.Rename()` prevents partial writes
-- **Fingerprint diffing before write** — avoids unnecessary disk writes on unchanged state
-- **Soft revocation** — `revoked_at` timestamp rather than hard deletes; preserves audit history
-- **root only** — manages `/root/.ssh/authorized_keys` only; no per-user key management
-- **Gitea releases for agent binaries** — slots into existing act_runner CI pipeline; install script queries Gitea API for latest version at serve time

default_steps/step.bash.apply_package_updates.json

@@ -0,0 +1,12 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Apply Package Updates",
+  "description": "Apply all pending OS package updates. Supports apt, dnf, yum, zypper, apk and pacman.",
+  "interpreter": "bash",
+  "script": "set -u\nif command -v apt-get >/dev/null 2>&1; then\n    export DEBIAN_FRONTEND=noninteractive\n    apt-get update -qq && apt-get -y -qq upgrade\nelif command -v dnf >/dev/null 2>&1; then\n    dnf -y upgrade\nelif command -v yum >/dev/null 2>&1; then\n    yum -y update\nelif command -v zypper >/dev/null 2>&1; then\n    zypper --non-interactive update\nelif command -v apk >/dev/null 2>&1; then\n    apk update && apk upgrade\nelif command -v pacman >/dev/null 2>&1; then\n    pacman -Syu --noconfirm\nelse\n    echo \"no supported package manager found\"\n    exit 1\nfi\nretVal=$?\nif [ $retVal -ne 0 ]; then\n    echo \"package update failed\"\n    exit 1\nfi\necho \"packages up to date\"\n# Debian and Ubuntu drop this file when a new kernel or libc needs a restart.\n# Reported rather than acted on: rebooting a fleet is a decision, not a detail.\nif [ -f /var/run/reboot-required ]; then\n    echo \"REBOOT_REQUIRED=true\" >> $WORKFLOW_ENV\n    echo \"a reboot is required to finish applying updates\"\nelse\n    echo \"REBOOT_REQUIRED=false\" >> $WORKFLOW_ENV\nfi",
+  "declared_outputs": [
+    "REBOOT_REQUIRED"
+  ],
+  "declared_inputs": [],
+  "secret_refs": []
+}

default_steps/step.bash.check_port.json

@@ -0,0 +1,23 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Check Port Is Listening",
+  "description": "Fail unless something is listening on a TCP port.",
+  "interpreter": "bash",
+  "script": "set -u\nhost=\"${host:-127.0.0.1}\"\nif command -v nc >/dev/null 2>&1; then\n    nc -z -w 5 \"$host\" \"$port\" >/dev/null 2>&1\n    ok=$?\nelse\n    # bash builds /dev/tcp in, so this needs nothing installed.\n    timeout 5 bash -c \"cat < /dev/null > /dev/tcp/$host/$port\" >/dev/null 2>&1\n    ok=$?\nfi\nif [ $ok -ne 0 ]; then\n    echo \"PORT_OPEN=false\" >> $WORKFLOW_ENV\n    echo \"nothing listening on $host:$port\"\n    exit 1\nfi\necho \"PORT_OPEN=true\" >> $WORKFLOW_ENV\necho \"$host:$port is open\"",
+  "declared_outputs": [
+    "PORT_OPEN"
+  ],
+  "declared_inputs": [
+    {
+      "name": "host",
+      "default": "127.0.0.1",
+      "description": "host to test"
+    },
+    {
+      "name": "port",
+      "default": "",
+      "description": "TCP port to test"
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.bash.copy_path.json

@@ -0,0 +1,23 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Copy File/Directory",
+  "description": "Copy a file or directory, preserving mode, ownership and timestamps.",
+  "interpreter": "bash",
+  "script": "set -u\nif [ ! -e \"$source\" ]; then\n    echo \"source $source does not exist\"\n    exit 1\nfi\ncp -a \"$source\" \"$destination\" || { echo \"failed to copy $source to $destination\"; exit 1; }\necho \"copied $source to $destination\"\necho \"DEST_PATH=$destination\" >> $WORKFLOW_ENV",
+  "declared_outputs": [
+    "DEST_PATH"
+  ],
+  "declared_inputs": [
+    {
+      "name": "source",
+      "default": "",
+      "description": "path to copy from"
+    },
+    {
+      "name": "destination",
+      "default": "",
+      "description": "path to copy to"
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.bash.create_directory.json

@@ -0,0 +1,23 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Create Directory",
+  "description": "Create a directory, including any missing parents.",
+  "interpreter": "bash",
+  "script": "set -u\nmkdir -p \"$path\" || { echo \"failed to create $path\"; exit 1; }\nif [ -n \"${mode:-}\" ]; then\n    chmod \"$mode\" \"$path\" || { echo \"failed to set mode $mode on $path\"; exit 1; }\nfi\necho \"created $path\"\necho \"DIR_PATH=$path\" >> $WORKFLOW_ENV",
+  "declared_outputs": [
+    "DIR_PATH"
+  ],
+  "declared_inputs": [
+    {
+      "name": "path",
+      "default": "",
+      "description": "directory to create"
+    },
+    {
+      "name": "mode",
+      "default": "",
+      "description": "optional octal mode, e.g. 0750"
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.bash.delete_path.json

@@ -0,0 +1,16 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Delete File/Directory",
+  "description": "Delete a path. Refuses the root filesystem and an empty value.",
+  "interpreter": "bash",
+  "script": "set -u\n# A step that runs as root on every server in a selector has to refuse the\n# one input that would wipe the fleet. An unset variable expands to empty,\n# so the empty case is the accident this actually guards against.\ncase \"$path\" in\n    \"\"|\"/\"|\"/.\"|\"/..\")\n        echo \"refusing to delete '$path'\"\n        exit 1\n        ;;\nesac\nif [ ! -e \"$path\" ]; then\n    echo \"$path does not exist, nothing to do\"\n    exit 0\nfi\nrm -rf \"$path\" || { echo \"failed to delete $path\"; exit 1; }\necho \"deleted $path\"",
+  "declared_outputs": [],
+  "declared_inputs": [
+    {
+      "name": "path",
+      "default": "",
+      "description": "path to delete"
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.bash.disk_usage.json

@@ -0,0 +1,24 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Disk Usage Report",
+  "description": "Report usage for a mount point and fail past a threshold.",
+  "interpreter": "bash",
+  "script": "set -u\nmount=\"${mountPoint:-/}\"\nlimit=\"${maxPercent:-90}\"\ndf -h \"$mount\"\nused=$(df --output=pcent \"$mount\" | tail -1 | tr -dc \"0-9\")\navail=$(df -h --output=avail \"$mount\" | tail -1 | tr -d \" \")\necho \"DISK_USED_PERCENT=$used\" >> $WORKFLOW_ENV\necho \"DISK_AVAILABLE=$avail\" >> $WORKFLOW_ENV\nif [ \"$used\" -ge \"$limit\" ]; then\n    echo \"$mount is ${used}% full, at or over the ${limit}% limit\"\n    exit 1\nfi\necho \"$mount is ${used}% full, ${avail} available\"",
+  "declared_outputs": [
+    "DISK_USED_PERCENT",
+    "DISK_AVAILABLE"
+  ],
+  "declared_inputs": [
+    {
+      "name": "mountPoint",
+      "default": "/",
+      "description": "mount point to measure"
+    },
+    {
+      "name": "maxPercent",
+      "default": "90",
+      "description": "fail at or above this percentage"
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.bash.docker_compose_up.json

@@ -0,0 +1,16 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Docker Compose Pull and Up",
+  "description": "Pull the latest images for a compose project and recreate its containers.",
+  "interpreter": "bash",
+  "script": "set -u\ncd \"$projectDir\" || { echo \"no such directory: $projectDir\"; exit 1; }\nif docker compose version >/dev/null 2>&1; then\n    dc=\"docker compose\"\nelif command -v docker-compose >/dev/null 2>&1; then\n    dc=\"docker-compose\"\nelse\n    echo \"docker compose is not installed\"\n    exit 1\nfi\n$dc pull || { echo \"pull failed\"; exit 1; }\n$dc up -d --remove-orphans || { echo \"up failed\"; exit 1; }\n$dc ps",
+  "declared_outputs": [],
+  "declared_inputs": [
+    {
+      "name": "projectDir",
+      "default": "",
+      "description": "directory holding docker-compose.yml"
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.bash.download_file.json

@@ -0,0 +1,16 @@
+{
+    "kind": "vantage.step/v1",
+    "name": "Download File (Linux)",
+    "description": "Download a file over HTTP to a local path",
+    "interpreter": "bash",
+    "script": "out=$(mktemp -p ./)\necho \"Downloading file from $url\"\nwget -q $url -O $out\nretVal=$?\nif [ $retVal -ne 0 ]; then\n    echo \"failed to download file from url\"\n    exit 1\nfi\necho \"FILE_PATH=$out\" \u003e\u003e $WORKFLOW_ENV",
+    "declared_outputs": ["FILE_PATH"],
+    "declared_inputs": [
+        {
+            "name": "url",
+            "default": "",
+            "description": ""
+        }
+    ],
+    "secret_refs": []
+}

default_steps/step.bash.enable_linux_service.json

@@ -0,0 +1,16 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Enable Linux Service",
+  "description": "Enable a systemd unit so it starts on boot.",
+  "interpreter": "bash",
+  "script": "set -u\necho \"enabling service $serviceName\"\nsystemctl enable \"$serviceName\" || { echo \"failed to enable $serviceName\"; exit 1; }\necho \"$serviceName enabled\"",
+  "declared_outputs": [],
+  "declared_inputs": [
+    {
+      "name": "serviceName",
+      "default": "",
+      "description": "systemd unit to enable"
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.bash.extract_archive.json

@@ -0,0 +1,23 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Extract Archive",
+  "description": "Extract a tar, tar.gz, tar.bz2, tar.xz or zip archive into a directory.",
+  "interpreter": "bash",
+  "script": "set -u\ndest=\"${destination:-.}\"\nif [ ! -f \"$archive\" ]; then\n    echo \"archive $archive does not exist\"\n    exit 1\nfi\nmkdir -p \"$dest\"\ncase \"$archive\" in\n    *.tar.gz|*.tgz)   tar -xzf \"$archive\" -C \"$dest\" ;;\n    *.tar.bz2|*.tbz2) tar -xjf \"$archive\" -C \"$dest\" ;;\n    *.tar.xz|*.txz)   tar -xJf \"$archive\" -C \"$dest\" ;;\n    *.tar)            tar -xf  \"$archive\" -C \"$dest\" ;;\n    *.zip)\n        command -v unzip >/dev/null 2>&1 || { echo \"unzip is not installed\"; exit 1; }\n        unzip -oq \"$archive\" -d \"$dest\"\n        ;;\n    *)\n        echo \"unsupported archive type: $archive\"\n        exit 1\n        ;;\nesac\nretVal=$?\nif [ $retVal -ne 0 ]; then\n    echo \"failed to extract $archive\"\n    exit 1\nfi\necho \"extracted $archive into $dest\"\necho \"EXTRACT_DIR=$dest\" >> $WORKFLOW_ENV",
+  "declared_outputs": [
+    "EXTRACT_DIR"
+  ],
+  "declared_inputs": [
+    {
+      "name": "archive",
+      "default": "",
+      "description": "archive file to extract"
+    },
+    {
+      "name": "destination",
+      "default": ".",
+      "description": "directory to extract into"
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.bash.get_hostname.json

@@ -0,0 +1,10 @@
+{
+    "kind": "vantage.step/v1",
+    "name": "Get Host Name",
+    "description": "Gets the agents hostname",
+    "interpreter": "bash",
+    "script": "HOSTNAME=$(hostname)\necho $HOSTNAME\necho \"HOSTNAME=$HOSTNAME\" \u003e\u003e $WORKFLOW_ENV",
+    "declared_outputs": ["HOSTNAME"],
+    "declared_inputs": [],
+    "secret_refs": []
+}

default_steps/step.bash.http_health_check.json

@@ -0,0 +1,33 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "HTTP Health Check",
+  "description": "Request a URL and fail unless it answers with the expected status.",
+  "interpreter": "bash",
+  "script": "set -u\nexpected=\"${expectedStatus:-200}\"\nattempts=\"${retries:-3}\"\ndelay=\"${retryDelay:-5}\"\nstatus=\"\"\ni=1\n# Retries live in the script rather than in on_failure: a service coming up\n# after a restart wants a few seconds, not a whole step re-dispatched.\nwhile [ \"$i\" -le \"$attempts\" ]; do\n    status=$(curl -s -o /dev/null -w \"%{http_code}\" --max-time 10 \"$url\" || echo \"000\")\n    echo \"attempt $i: $url returned $status\"\n    if [ \"$status\" = \"$expected\" ]; then\n        break\n    fi\n    i=$(( i + 1 ))\n    if [ \"$i\" -le \"$attempts\" ]; then sleep \"$delay\"; fi\ndone\necho \"HTTP_STATUS=$status\" >> $WORKFLOW_ENV\nif [ \"$status\" != \"$expected\" ]; then\n    echo \"$url returned $status, expected $expected\"\n    exit 1\nfi\necho \"$url is healthy\"",
+  "declared_outputs": [
+    "HTTP_STATUS"
+  ],
+  "declared_inputs": [
+    {
+      "name": "url",
+      "default": "",
+      "description": "URL to request"
+    },
+    {
+      "name": "expectedStatus",
+      "default": "200",
+      "description": "HTTP status that counts as healthy"
+    },
+    {
+      "name": "retries",
+      "default": "3",
+      "description": "how many attempts before failing"
+    },
+    {
+      "name": "retryDelay",
+      "default": "5",
+      "description": "seconds between attempts"
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.bash.list_directory.json

@@ -0,0 +1,16 @@
+{
+    "kind": "vantage.step/v1",
+    "name": "List Directory",
+    "description": "Lists the files in the specified path",
+    "interpreter": "bash",
+    "script": "if [ ! -e $path ]; then\n    echo \"file or directory doesn't exist: $path\"\n    exit 1\nfi\nls -l $path",
+    "declared_outputs": [],
+    "declared_inputs": [
+        {
+            "name": "path",
+            "default": "./",
+            "description": ""
+        }
+    ],
+    "secret_refs": []
+}

default_steps/step.bash.memory_usage.json

@@ -0,0 +1,13 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Memory Usage Report",
+  "description": "Report memory usage as a percentage of total.",
+  "interpreter": "bash",
+  "script": "set -u\nfree -h\ntotal=$(free -m | awk \"/^Mem:/ {print \\$2}\")\nused=$(free -m | awk \"/^Mem:/ {print \\$3}\")\npct=$(( used * 100 / total ))\necho \"MEM_USED_PERCENT=$pct\" >> $WORKFLOW_ENV\necho \"MEM_USED_MB=$used\" >> $WORKFLOW_ENV\necho \"memory ${pct}% used (${used}MB of ${total}MB)\"",
+  "declared_outputs": [
+    "MEM_USED_PERCENT",
+    "MEM_USED_MB"
+  ],
+  "declared_inputs": [],
+  "secret_refs": []
+}

default_steps/step.bash.reboot_server.json

@@ -0,0 +1,16 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Reboot Server",
+  "description": "Schedule a reboot a minute out, so the step reports success before the machine goes down.",
+  "interpreter": "bash",
+  "script": "set -u\ndelay=\"${delayMinutes:-1}\"\n# Scheduled rather than immediate on purpose: `shutdown -r now` kills the\n# agent before it can report, and the run records a failure on a server\n# that did exactly what it was told.\necho \"rebooting in $delay minute(s)\"\nshutdown -r \"+$delay\" \"Reboot requested by Vantage\" || { echo \"failed to schedule a reboot\"; exit 1; }",
+  "declared_outputs": [],
+  "declared_inputs": [
+    {
+      "name": "delayMinutes",
+      "default": "1",
+      "description": "minutes to wait before rebooting"
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.bash.restart_linux_service.json

@@ -0,0 +1,16 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Restart Linux Service",
+  "description": "Restart a systemd unit and fail if it does not come back up.",
+  "interpreter": "bash",
+  "script": "set -u\necho \"restarting service $serviceName\"\nsystemctl restart \"$serviceName\" || { echo \"failed to restart $serviceName\"; exit 1; }\nsystemctl is-active --quiet \"$serviceName\" || {\n    echo \"$serviceName did not come back up\"\n    systemctl status \"$serviceName\" --no-pager --lines=20 || true\n    exit 1\n}\necho \"$serviceName is active\"",
+  "declared_outputs": [],
+  "declared_inputs": [
+    {
+      "name": "serviceName",
+      "default": "",
+      "description": "systemd unit to restart, e.g. nginx"
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.bash.service_status.json

@@ -0,0 +1,19 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Linux Service Status",
+  "description": "Report whether a systemd unit is active and enabled. Does not fail on a stopped unit.",
+  "interpreter": "bash",
+  "script": "set -u\nstate=$(systemctl is-active \"$serviceName\" 2>/dev/null || true)\nenabled=$(systemctl is-enabled \"$serviceName\" 2>/dev/null || true)\necho \"$serviceName: state=$state enabled=$enabled\"\necho \"SERVICE_STATE=$state\" >> $WORKFLOW_ENV\necho \"SERVICE_ENABLED=$enabled\" >> $WORKFLOW_ENV",
+  "declared_outputs": [
+    "SERVICE_STATE",
+    "SERVICE_ENABLED"
+  ],
+  "declared_inputs": [
+    {
+      "name": "serviceName",
+      "default": "",
+      "description": "systemd unit to inspect"
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.bash.set_permissions.json

@@ -0,0 +1,31 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Set Permissions and Ownership",
+  "description": "Set the mode and optionally the owner of a path.",
+  "interpreter": "bash",
+  "script": "set -u\nif [ ! -e \"$path\" ]; then\n    echo \"$path does not exist\"\n    exit 1\nfi\nrecurse=\"\"\nif [ \"${recursive:-false}\" = \"true\" ]; then\n    recurse=\"-R\"\nfi\nif [ -n \"${mode:-}\" ]; then\n    chmod $recurse \"$mode\" \"$path\" || { echo \"failed to set mode\"; exit 1; }\n    echo \"set mode $mode on $path\"\nfi\nif [ -n \"${owner:-}\" ]; then\n    chown $recurse \"$owner\" \"$path\" || { echo \"failed to set owner\"; exit 1; }\n    echo \"set owner $owner on $path\"\nfi",
+  "declared_outputs": [],
+  "declared_inputs": [
+    {
+      "name": "path",
+      "default": "",
+      "description": "path to change"
+    },
+    {
+      "name": "mode",
+      "default": "",
+      "description": "octal mode, e.g. 0640"
+    },
+    {
+      "name": "owner",
+      "default": "",
+      "description": "owner, e.g. root:root"
+    },
+    {
+      "name": "recursive",
+      "default": "false",
+      "description": "true to apply recursively"
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.bash.start_linx_service.json

@@ -0,0 +1,16 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Start Linux Service",
+  "description": "Start a linux systemd service",
+  "interpreter": "bash",
+  "script": "echo \"starting service $serviceName\"\nsystemctl start $serviceName\nretVal=$?\nif [ $retVal -ne 0 ]; then\n    echo \"failed to start service\"\n    exit 1\nfi",
+  "declared_outputs": [],
+  "declared_inputs": [
+    {
+      "name": "serviceName",
+      "default": "",
+      "description": ""
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.bash.stop_linux_service.json

@@ -0,0 +1,16 @@
+{
+    "kind": "vantage.step/v1",
+    "name": "Stop Linux Service",
+    "description": "Stops a linux systemd service",
+    "interpreter": "bash",
+    "script": "echo \"stopping service $serviceName\"\nsystemctl stop $serviceName\nretVal=$?\nif [ $retVal -ne 0 ]; then\n    echo \"failed to stop service\"\n    exit 1\nfi",
+    "declared_outputs": [],
+    "declared_inputs": [
+        {
+            "name": "serviceName",
+            "default": "",
+            "description": ""
+        }
+    ],
+    "secret_refs": []
+}

default_steps/step.bash.tail_log.json

@@ -0,0 +1,21 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Tail Log File",
+  "description": "Print the last N lines of a file, for reading a log after a deployment step.",
+  "interpreter": "bash",
+  "script": "set -u\nlines=\"${lines:-50}\"\nif [ ! -f \"$path\" ]; then\n    echo \"$path does not exist\"\n    exit 1\nfi\necho \"last $lines lines of $path:\"\ntail -n \"$lines\" \"$path\"",
+  "declared_outputs": [],
+  "declared_inputs": [
+    {
+      "name": "path",
+      "default": "",
+      "description": "log file to read"
+    },
+    {
+      "name": "lines",
+      "default": "50",
+      "description": "how many lines to print"
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.bash.tls_expiry.json

@@ -0,0 +1,29 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "TLS Certificate Expiry",
+  "description": "Report days remaining on a TLS certificate and fail under a threshold.",
+  "interpreter": "bash",
+  "script": "set -u\nport=\"${port:-443}\"\nmin=\"${minDays:-14}\"\ncommand -v openssl >/dev/null 2>&1 || { echo \"openssl is not installed\"; exit 1; }\n# -servername sends SNI, without which a shared host returns the wrong\n# certificate and the expiry reported here belongs to someone else.\nend=$(echo | openssl s_client -servername \"$host\" -connect \"$host:$port\" 2>/dev/null \\\n    | openssl x509 -noout -enddate | cut -d= -f2)\nif [ -z \"$end\" ]; then\n    echo \"could not read a certificate from $host:$port\"\n    exit 1\nfi\nendEpoch=$(date -d \"$end\" +%s)\nnowEpoch=$(date +%s)\ndays=$(( (endEpoch - nowEpoch) / 86400 ))\necho \"CERT_DAYS_REMAINING=$days\" >> $WORKFLOW_ENV\necho \"CERT_EXPIRES=$end\" >> $WORKFLOW_ENV\necho \"$host:$port expires in $days days ($end)\"\nif [ \"$days\" -lt \"$min\" ]; then\n    echo \"fewer than $min days remaining\"\n    exit 1\nfi",
+  "declared_outputs": [
+    "CERT_DAYS_REMAINING",
+    "CERT_EXPIRES"
+  ],
+  "declared_inputs": [
+    {
+      "name": "host",
+      "default": "",
+      "description": "hostname to check"
+    },
+    {
+      "name": "port",
+      "default": "443",
+      "description": "TLS port"
+    },
+    {
+      "name": "minDays",
+      "default": "14",
+      "description": "fail below this many days remaining"
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.powershell.download_file.json

@@ -0,0 +1,23 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Download File (Windows)",
+  "description": "Download a file over HTTP to a local path.",
+  "interpreter": "powershell",
+  "script": "$ErrorActionPreference = \"Stop\"\n$url  = $env:url\n$dest = if ($env:destination) { $env:destination } else { Join-Path $env:TEMP ([System.IO.Path]::GetFileName($url)) }\nWrite-Output \"downloading $url\"\ntry {\n    # -UseBasicParsing keeps this working on Server Core, where the IE\n    # engine Invoke-WebRequest otherwise reaches for is not installed.\n    Invoke-WebRequest -Uri $url -OutFile $dest -UseBasicParsing\n} catch {\n    Write-Output \"failed to download: $_\"\n    exit 1\n}\nWrite-Output \"saved to $dest\"\nAdd-Content -Path $env:WORKFLOW_ENV -Value \"FILE_PATH=$dest\"",
+  "declared_outputs": [
+    "FILE_PATH"
+  ],
+  "declared_inputs": [
+    {
+      "name": "url",
+      "default": "",
+      "description": "URL to download"
+    },
+    {
+      "name": "destination",
+      "default": "",
+      "description": "where to save it; defaults to a file in TEMP"
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.powershell.reboot_windows_server.json

@@ -0,0 +1,16 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Reboot Windows Server",
+  "description": "Schedule a reboot a minute out, so the step reports success before the machine goes down.",
+  "interpreter": "powershell",
+  "script": "$ErrorActionPreference = \"Stop\"\n$delay = if ($env:delaySeconds) { [int]$env:delaySeconds } else { 60 }\nWrite-Output \"rebooting in $delay second(s)\"\n& shutdown.exe /r /t $delay /c \"Reboot requested by Vantage\"\nif ($LASTEXITCODE -ne 0) {\n    Write-Output \"failed to schedule a reboot\"\n    exit 1\n}",
+  "declared_outputs": [],
+  "declared_inputs": [
+    {
+      "name": "delaySeconds",
+      "default": "60",
+      "description": "seconds to wait before rebooting"
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.powershell.restart_windows_service.json

@@ -0,0 +1,16 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Restart Windows Service",
+  "description": "Restart a Windows service and fail if it does not come back up.",
+  "interpreter": "powershell",
+  "script": "$ErrorActionPreference = \"Stop\"\n$name = $env:serviceName\nWrite-Output \"restarting service $name\"\ntry {\n    Restart-Service -Name $name -Force\n} catch {\n    Write-Output \"failed to restart ${name}: $_\"\n    exit 1\n}\n$svc = Get-Service -Name $name\nif ($svc.Status -ne \"Running\") {\n    Write-Output \"$name is $($svc.Status), not Running\"\n    exit 1\n}\nWrite-Output \"$name is running\"",
+  "declared_outputs": [],
+  "declared_inputs": [
+    {
+      "name": "serviceName",
+      "default": "",
+      "description": "Windows service name to restart"
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.powershell.windows_disk_report.json

@@ -0,0 +1,24 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Windows Disk Report",
+  "description": "Report free space on a drive and fail past a usage threshold.",
+  "interpreter": "powershell",
+  "script": "$ErrorActionPreference = \"Stop\"\n$letter = if ($env:driveLetter) { $env:driveLetter } else { \"C\" }\n$limit  = if ($env:maxPercent)  { [int]$env:maxPercent } else { 90 }\n$d = Get-PSDrive -Name $letter -ErrorAction SilentlyContinue\nif ($null -eq $d) {\n    Write-Output \"drive $letter not found\"\n    exit 1\n}\n$total  = $d.Used + $d.Free\n$pct    = [math]::Round(($d.Used / $total) * 100)\n$freeGb = [math]::Round($d.Free / 1GB, 1)\nWrite-Output \"${letter}: is $pct% full, $freeGb GB free\"\nAdd-Content -Path $env:WORKFLOW_ENV -Value \"DISK_USED_PERCENT=$pct\"\nAdd-Content -Path $env:WORKFLOW_ENV -Value \"DISK_FREE_GB=$freeGb\"\nif ($pct -ge $limit) {\n    Write-Output \"at or over the $limit% limit\"\n    exit 1\n}",
+  "declared_outputs": [
+    "DISK_USED_PERCENT",
+    "DISK_FREE_GB"
+  ],
+  "declared_inputs": [
+    {
+      "name": "driveLetter",
+      "default": "C",
+      "description": "drive letter, without a colon"
+    },
+    {
+      "name": "maxPercent",
+      "default": "90",
+      "description": "fail at or above this percentage"
+    }
+  ],
+  "secret_refs": []
+}

default_steps/step.powershell.windows_service_status.json

@@ -0,0 +1,19 @@
+{
+  "kind": "vantage.step/v1",
+  "name": "Windows Service Status",
+  "description": "Report a Windows service's status and start type. Does not fail on a stopped service.",
+  "interpreter": "powershell",
+  "script": "$ErrorActionPreference = \"Stop\"\n$name = $env:serviceName\n$svc = Get-Service -Name $name -ErrorAction SilentlyContinue\nif ($null -eq $svc) {\n    Write-Output \"$name is not installed\"\n    Add-Content -Path $env:WORKFLOW_ENV -Value \"SERVICE_STATE=missing\"\n    Add-Content -Path $env:WORKFLOW_ENV -Value \"SERVICE_START_TYPE=none\"\n    exit 0\n}\nWrite-Output \"${name}: $($svc.Status), start type $($svc.StartType)\"\nAdd-Content -Path $env:WORKFLOW_ENV -Value \"SERVICE_STATE=$($svc.Status)\"\nAdd-Content -Path $env:WORKFLOW_ENV -Value \"SERVICE_START_TYPE=$($svc.StartType)\"",
+  "declared_outputs": [
+    "SERVICE_STATE",
+    "SERVICE_START_TYPE"
+  ],
+  "declared_inputs": [
+    {
+      "name": "serviceName",
+      "default": "",
+      "description": "Windows service name to inspect"
+    }
+  ],
+  "secret_refs": []
+}

deploy/agent.service

@@ -1,23 +0,0 @@
-[Unit]
-Description=Vantage Agent
-Documentation=https://github.com/your-org/vantage
-After=network.target
-Wants=network-online.target
-
-[Service]
-Type=simple
-ExecStart=/usr/local/bin/vantage-agent
-Restart=always
-RestartSec=10
-User=root
-StandardOutput=journal
-StandardError=journal
-SyslogIdentifier=vantage-agent
-
-# Security hardening
-NoNewPrivileges=true
-ProtectSystem=false
-ProtectHome=false
-
-[Install]
-WantedBy=multi-user.target

deploy/chart/vantage/Chart.yaml

@@ -0,0 +1,6 @@
+apiVersion: v2
+name: vantage
+description: Helm chart for the Vantage stack (Redis, MongoDB, guacd, server, web)
+type: application
+version: 1.1.0
+appVersion: "1.0.8"

deploy/chart/vantage/templates/NOTES.txt

@@ -0,0 +1,79 @@
+Vantage has been deployed as release "{{ .Release.Name }}" in namespace "{{ .Release.Namespace }}".
+
+Services created:
+{{- if .Values.redis.enabled }}
+  - {{ .Release.Name }}-redis   (ClusterIP {{ .Values.redis.port }})
+{{- else }}
+  - Redis: not deployed, using external {{ .Values.redis.addr }}
+{{- end }}
+{{- if .Values.mongo.enabled }}
+  - {{ .Release.Name }}-mongo   (ClusterIP {{ .Values.mongo.port }})
+{{- else }}
+  - MongoDB: not deployed, using the external server.env.mongoUri
+{{- end }}
+  - {{ .Release.Name }}-guacd   ({{ .Values.guacd.service.type }} {{ .Values.guacd.service.port }})
+  - {{ .Release.Name }}-server  ({{ .Values.server.service.type }} http:{{ .Values.server.service.httpPort }} grpc:{{ .Values.server.service.grpcPort }})
+  - {{ .Release.Name }}-web     ({{ .Values.web.service.type }} {{ .Values.web.service.port }})
+
+Scaling (server.replicaCount / web.replicaCount):
+  - Both scale. Pin the image tags first — replicas on different builds serve
+    mismatched web asset hashes, and mixed server versions share one bus.
+  - server replicas route agent commands, step results and console relays to
+    each other over Redis, so every replica must use the SAME Redis. Workflow
+    logs are in MongoDB, not on a volume.
+  - Background work (monitor scheduler, Free reaper, log and audit retention,
+    the offline sweep) runs on one replica at a time under a Redis leader lock.
+  - server.persistence must be off to scale past one replica on a ReadWriteOnce
+    volume. Nothing writes to it any more.
+{{- if gt (int .Values.server.replicaCount) 1 }}
+  - Console relays are reached by pod IP; guacd must be able to dial pod IPs
+    directly (it can, inside the cluster network).
+{{- end }}
+{{- if .Values.server.migrationJob.enabled }}
+  - Migrations run in the {{ .Release.Name }}-migrate Job before each upgrade;
+    the pods skip them. Its logs are kept: kubectl logs job/{{ .Release.Name }}-migrate
+{{- end }}
+
+{{- if .Values.ingress.enabled }}
+
+Ingress (Traefik):
+  - Browsers:    https://{{ .Values.ingress.web.host }}
+{{- range .Values.ingress.web.extraHosts }}
+                 https://{{ . }}
+{{- end }}
+    {{ join ", " .Values.ingress.api.paths }} go to the server; everything else to web.
+    web proxies nothing, so those paths must be routed here or by a terminator
+    in front of this ingress.
+{{- if .Values.ingress.grpc.enabled }}
+  - Agents:      {{ .Values.ingress.grpc.host }} (gRPC, h2c behind TLS)
+    Agents dial server.env.grpcHost, currently {{ tpl .Values.server.env.grpcHost . }}.
+    Point DNS for both hostnames at the Traefik load balancer.
+{{- if not .Values.ingress.tls.enabled }}
+  - WARNING: ingress.tls.enabled is false. Agent tokens and session cookies
+    would cross the network in clear.
+{{- else if and (not .Values.ingress.tls.certResolver) (not .Values.ingress.tls.secretName) }}
+  - WARNING: TLS is on but neither ingress.tls.secretName nor
+    ingress.tls.certResolver is set, so Traefik will serve its self-signed
+    default certificate, which no agent and no browser will trust.
+{{- end }}
+{{- end }}
+{{- end }}
+
+By default the server/web/guacd services are ClusterIP only (no host port publishing,
+unlike the original docker-compose file). To expose them externally, set
+server.service.type / web.service.type / guacd.service.type to NodePort or LoadBalancer,
+or add an Ingress on top of the -web and -server services.
+
+Quick access via port-forward, e.g.:
+  kubectl port-forward svc/{{ .Release.Name }}-web {{ .Values.web.service.port }}:{{ .Values.web.service.port }}
+  kubectl port-forward svc/{{ .Release.Name }}-server {{ .Values.server.service.httpPort }}:{{ .Values.server.service.httpPort }}
+{{- if not .Values.backup.enabled }}
+
+No backups are scheduled. Vantage encrypts SSH private keys, vault secrets and
+SSO client secrets with KEY_ENCRYPTION_KEY, and that key is not stored anywhere
+but your own configuration — a database restored without it is permanently
+unreadable.
+
+Set backup.enabled, backup.image and backup.pvcName, and store
+KEY_ENCRYPTION_KEY somewhere that survives this cluster.
+{{- end }}

deploy/chart/vantage/templates/_helpers.tpl

@@ -0,0 +1,102 @@
+{{/*
+Common name helpers
+*/}}
+{{- define "vantage.fullname" -}}
+{{ .Release.Name }}
+{{- end -}}
+
+{{- define "vantage.labels" -}}
+app.kubernetes.io/instance: {{ .Release.Name }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end -}}
+
+{{/*
+vantage.server.env renders the server container's environment.
+
+It lives here because two workloads need it identically: the Deployment and the
+pre-upgrade migration Job. A Job that connected to a different database than the
+pods it migrates for would be worse than no Job at all, so there is one copy and
+both read it.
+*/}}
+{{- define "vantage.server.env" -}}
+- name: MONGO_URI
+  {{- $mongoUri := tpl .Values.server.env.mongoUri . }}
+  {{- if and (not .Values.mongo.enabled) (contains (printf "%s-mongo" .Release.Name) $mongoUri) }}
+  {{- fail "mongo.enabled is false, so server.env.mongoUri must point at an external MongoDB rather than the in-chart one" }}
+  {{- end }}
+  value: {{ $mongoUri | quote }}
+- name: REDIS_ADDR
+  {{- if .Values.redis.enabled }}
+  value: "{{ .Release.Name }}-redis:{{ .Values.redis.port }}"
+  {{- else }}
+  {{- if not .Values.redis.addr }}
+  {{- fail "redis.enabled is false, so redis.addr must be set to an external Redis host:port" }}
+  {{- end }}
+  value: {{ .Values.redis.addr | quote }}
+  {{- end }}
+{{- if .Values.redis.auth.existingSecret }}
+- name: REDIS_USERNAME
+  valueFrom:
+    secretKeyRef:
+      name: {{ .Values.redis.auth.existingSecret }}
+      key: {{ .Values.redis.auth.usernameKey }}
+      optional: true
+- name: REDIS_PASSWORD
+  valueFrom:
+    secretKeyRef:
+      name: {{ .Values.redis.auth.existingSecret }}
+      key: {{ .Values.redis.auth.passwordKey }}
+{{- else }}
+{{- if .Values.redis.auth.username }}
+- name: REDIS_USERNAME
+  value: {{ .Values.redis.auth.username | quote }}
+{{- end }}
+{{- if .Values.redis.auth.password }}
+- name: REDIS_PASSWORD
+  value: {{ .Values.redis.auth.password | quote }}
+{{- end }}
+{{- end }}
+- name: GRPC_HOST
+  value: {{ .Values.server.env.grpcHost | quote }}
+- name: GRPC_PORT
+  value: {{ .Values.server.service.grpcPort | quote }}
+- name: HTTP_PORT
+  value: {{ .Values.server.service.httpPort | quote }}
+- name: KEY_ENCRYPTION_KEY
+  value: {{ .Values.server.env.keyEncryptionKey | quote }}
+- name: GUACD_ADDR
+  value: "{{ .Release.Name }}-guacd:{{ .Values.guacd.service.port }}"
+- name: APP_ROOT_LABEL
+  value: {{ .Values.server.env.appRootLabel | quote }}
+- name: PROXY_ADVERTISE_HOST
+  value: {{ .Values.server.env.proxyAdvertiseHost | quote }}
+- name: PROXY_LISTEN_HOST
+  value: {{ .Values.server.env.proxyListenHost | quote }}
+- name: TRUSTED_PROXIES
+  value: {{ .Values.server.env.trustedProxies | quote }}
+{{- if eq .Values.server.env.deploymentType "cloud" }}
+- name: VANTAGE_DEPLOYMENT
+  value: "cloud"
+- name: FREE_INSTANCE_REAP_AFTER
+  value: {{ .Values.server.env.freeInstanceReapAfter | quote }}
+{{- end }}
+- name: POD_IP
+  valueFrom:
+    fieldRef:
+      fieldPath: status.podIP
+{{- end -}}
+
+{{/*
+vantage.backup.env renders the environment vantagectl needs.
+
+It reads the SAME values the server does rather than taking its own, because a
+backup that connected to a different database, or stamped a fingerprint of a
+different key, than the deployment it is backing up would be worse than no
+backup: it would look like one.
+*/}}
+{{- define "vantage.backup.env" -}}
+- name: MONGO_URI
+  value: {{ tpl .Values.server.env.mongoUri . | quote }}
+- name: KEY_ENCRYPTION_KEY
+  value: {{ .Values.server.env.keyEncryptionKey | quote }}
+{{- end -}}

deploy/chart/vantage/templates/backup-cronjob.yaml

@@ -0,0 +1,56 @@
+{{- if .Values.backup.enabled }}
+{{- if not .Values.backup.pvcName }}
+{{- fail "backup.enabled requires backup.pvcName: a backup needs somewhere durable to land, and the chart cannot guess where that is" }}
+{{- end }}
+{{- if not .Values.backup.image }}
+{{- fail "backup.enabled requires backup.image: the vantagectl image to run" }}
+{{- end }}
+apiVersion: batch/v1
+kind: CronJob
+metadata:
+  name: {{ include "vantage.fullname" . }}-backup
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: backup
+spec:
+  schedule: {{ .Values.backup.schedule | quote }}
+  concurrencyPolicy: Forbid
+  successfulJobsHistoryLimit: {{ .Values.backup.successfulJobsHistoryLimit }}
+  failedJobsHistoryLimit: {{ .Values.backup.failedJobsHistoryLimit }}
+  jobTemplate:
+    spec:
+      backoffLimit: 2
+      template:
+        metadata:
+          labels:
+            {{- include "vantage.labels" . | nindent 12 }}
+            app.kubernetes.io/component: backup
+        spec:
+          restartPolicy: Never
+          containers:
+            - name: vantagectl
+              image: {{ .Values.backup.image | quote }}
+              args:
+                - backup
+                - --out
+                - /backups
+                {{- with .Values.backup.exclude }}
+                - --exclude
+                - {{ join "," . | quote }}
+                {{- end }}
+              env:
+                # Referenced, never redeclared. A backup job holding its own
+                # copy of KEY_ENCRYPTION_KEY is a second place for it to be
+                # wrong, and the fingerprint it stamps would then be a
+                # fingerprint of the wrong key.
+                {{- include "vantage.backup.env" . | nindent 16 }}
+              volumeMounts:
+                - name: backups
+                  mountPath: /backups
+              resources:
+                {{- toYaml .Values.backup.resources | nindent 16 }}
+          volumes:
+            - name: backups
+              persistentVolumeClaim:
+                claimName: {{ .Values.backup.pvcName | quote }}
+{{- end }}

deploy/chart/vantage/templates/guacd.yaml

@@ -0,0 +1,47 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ .Release.Name }}-guacd
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: guacd
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app.kubernetes.io/instance: {{ .Release.Name }}
+      app.kubernetes.io/component: guacd
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/instance: {{ .Release.Name }}
+        app.kubernetes.io/component: guacd
+    spec:
+      {{- if .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml .Values.imagePullSecrets | nindent 8 }}
+      {{- end }}
+      containers:
+        - name: guacd
+          image: "{{ .Values.guacd.image.repository }}:{{ .Values.guacd.image.tag }}"
+          ports:
+            - containerPort: 4822
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ .Release.Name }}-guacd
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: guacd
+spec:
+  type: {{ .Values.guacd.service.type }}
+  {{- if eq .Values.guacd.service.type "ClusterIP" }}
+  clusterIP: None
+  {{- end }}
+  selector:
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/component: guacd
+  ports:
+    - port: {{ .Values.guacd.service.port }}
+      targetPort: 4822

deploy/chart/vantage/templates/ingress.yaml

@@ -0,0 +1,174 @@
+{{- if .Values.ingress.enabled }}
+{{/*
+Two hostnames, because the two audiences arrive over different protocols.
+
+Browsers reach the web host, and the path decides what answers: /api, /auth,
+/public, /install* and /update* go to the server, everything else to `web`.
+
+That split is not optional and ingress.api.enabled defaults to true. `web`
+proxies nothing — it holds no address for the server at all — so with these
+paths absent the UI loads and every request it makes 404s against Next. The
+setting remains a value only so an installation terminating in front of this
+ingress can route the prefixes itself; it must be routed somewhere.
+
+The web host is normally a wildcard — `*.vantage.example.com` — because that is
+the per-tenant instance namespace; APP_ROOT_LABEL resolves the instance from the
+label. Kubernetes wildcard hosts match exactly one label, so this does not match
+the apex, and on the deployment this chart was written for it must not: the apex
+is the marketing site, a separate application in the vantage-site repository.
+extraHosts exists for a genuine second name, not for
+reclaiming the apex.
+
+Agents reach the server's gRPC port, which is plain h2c — the server holds no
+certificates of its own, TLS has always been terminated by whatever sits in
+front. Traefik will not speak h2c to a backend unless told to, and it is told
+per Service, which is why the gRPC route gets a Service of its own below rather
+than reusing the two-port one. Annotating the shared Service would force h2c on
+its HTTP port too.
+*/}}
+{{- $tls := .Values.ingress.tls }}
+{{- $webHost := required "ingress.enabled requires ingress.web.host" .Values.ingress.web.host }}
+{{- $hosts := prepend .Values.ingress.web.extraHosts $webHost }}
+{{- $apiPaths := .Values.ingress.api.paths }}
+{{- if and .Values.ingress.api.enabled (not $apiPaths) }}
+{{- fail "ingress.api.enabled requires at least one path in ingress.api.paths" }}
+{{- end }}
+{{- if not .Values.ingress.api.enabled }}
+{{- fail "ingress.api.enabled=false leaves /api, /auth and /public unrouted: web proxies nothing. Route those prefixes to the server at your own terminator, or leave this enabled." }}
+{{- end }}
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: {{ .Release.Name }}-web
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: web
+  annotations:
+    traefik.ingress.kubernetes.io/router.entrypoints: {{ .Values.ingress.entrypoint | quote }}
+    {{- if and $tls.enabled $tls.certResolver }}
+    traefik.ingress.kubernetes.io/router.tls: "true"
+    traefik.ingress.kubernetes.io/router.tls.certresolver: {{ $tls.certResolver | quote }}
+    {{- else if $tls.enabled }}
+    traefik.ingress.kubernetes.io/router.tls: "true"
+    {{- end }}
+    {{- with .Values.ingress.annotations }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+spec:
+  {{- if .Values.ingress.className }}
+  ingressClassName: {{ .Values.ingress.className }}
+  {{- end }}
+  {{- if and $tls.enabled $tls.secretName }}
+  tls:
+    - hosts:
+        {{- range $hosts }}
+        - {{ . | quote }}
+        {{- end }}
+      secretName: {{ $tls.secretName }}
+  {{- end }}
+  rules:
+    {{- range $host := $hosts }}
+    - host: {{ $host | quote }}
+      http:
+        paths:
+          {{- /*
+            The API paths come first and, more importantly, are longer. Traefik
+            derives router priority from rule length, so Host(x) &&
+            PathPrefix(/api) outranks Host(x) && PathPrefix(/) without anyone
+            having to assign priorities by hand. Order within the list is for
+            the reader; the length is what decides.
+          */}}
+          {{- if $.Values.ingress.api.enabled }}
+          {{- range $apiPaths }}
+          - path: {{ . | quote }}
+            pathType: Prefix
+            backend:
+              service:
+                name: {{ $.Release.Name }}-server
+                port:
+                  number: {{ $.Values.server.service.httpPort }}
+          {{- end }}
+          {{- end }}
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: {{ $.Release.Name }}-web
+                port:
+                  number: {{ $.Values.web.service.port }}
+    {{- end }}
+{{- if .Values.ingress.grpc.enabled }}
+{{- $grpcHost := required "ingress.grpc.enabled requires ingress.grpc.host" .Values.ingress.grpc.host }}
+{{/*
+GRPC_HOST is what an agent is told to dial, and it is baked into every install
+one-liner. Left pointing at the in-cluster Service while agents are expected to
+arrive through the ingress, every install would succeed and every agent would
+fail to connect — with nothing in the control plane saying why.
+*/}}
+{{- $grpcEnv := tpl .Values.server.env.grpcHost . }}
+{{- if contains (printf "%s-server" .Release.Name) $grpcEnv }}
+{{- fail (printf "ingress.grpc.enabled routes agents through %s, but server.env.grpcHost is still the in-cluster address %q. Agents dial the value of grpcHost, so set it to the public gRPC address (for example %q)." $grpcHost $grpcEnv (printf "%s:443" $grpcHost)) }}
+{{- end }}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ .Release.Name }}-server-grpc
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: server
+  annotations:
+    # The server speaks h2c: it terminates no TLS itself. Without this Traefik
+    # dials the backend as HTTP/1.1 and every agent handshake fails.
+    traefik.ingress.kubernetes.io/service.serversscheme: h2c
+spec:
+  type: ClusterIP
+  selector:
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/component: server
+  ports:
+    - name: grpc
+      port: {{ .Values.server.service.grpcPort }}
+      targetPort: {{ .Values.server.service.grpcPort }}
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: {{ .Release.Name }}-grpc
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: server
+  annotations:
+    traefik.ingress.kubernetes.io/router.entrypoints: {{ .Values.ingress.entrypoint | quote }}
+    {{- if and $tls.enabled $tls.certResolver }}
+    traefik.ingress.kubernetes.io/router.tls: "true"
+    traefik.ingress.kubernetes.io/router.tls.certresolver: {{ $tls.certResolver | quote }}
+    {{- else if $tls.enabled }}
+    traefik.ingress.kubernetes.io/router.tls: "true"
+    {{- end }}
+    {{- with .Values.ingress.grpc.annotations }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+spec:
+  {{- if .Values.ingress.className }}
+  ingressClassName: {{ .Values.ingress.className }}
+  {{- end }}
+  {{- if and $tls.enabled $tls.grpcSecretName }}
+  tls:
+    - hosts:
+        - {{ $grpcHost | quote }}
+      secretName: {{ $tls.grpcSecretName }}
+  {{- end }}
+  rules:
+    - host: {{ $grpcHost | quote }}
+      http:
+        paths:
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: {{ .Release.Name }}-server-grpc
+                port:
+                  number: {{ .Values.server.service.grpcPort }}
+{{- end }}
+{{- end }}

deploy/chart/vantage/templates/migrate-job.yaml

@@ -0,0 +1,68 @@
+{{- if .Values.server.migrationJob.enabled }}
+{{/*
+Schema setup, lifted out of the serving pods.
+
+Every server process used to run migrations, index builders and default-step
+seeding at boot. With one replica that is fine. With two it is not: 0004 renames
+the orgs collection to instances, and a sibling reading it mid-rename is a
+corruption, not a retry.
+
+A Helm hook Job runs it once, before any pod of the new version starts. The
+Deployment then sets VANTAGE_SKIP_MIGRATIONS, which is what makes the Job's
+existence load-bearing rather than decorative — if you disable the Job, the
+pods go back to migrating themselves and you must go back to one replica.
+
+hook-weight orders this after the dependency waits; before-hook-creation deletes
+the previous Job so a repeat upgrade is not blocked by an immutable object. The
+Job is deliberately NOT deleted on success: its logs are the record of what the
+upgrade did to the database.
+*/}}
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: {{ .Release.Name }}-migrate
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: migrate
+  annotations:
+    "helm.sh/hook": pre-install,pre-upgrade
+    "helm.sh/hook-weight": "0"
+    "helm.sh/hook-delete-policy": before-hook-creation
+spec:
+  backoffLimit: {{ .Values.server.migrationJob.backoffLimit }}
+  # A migration that has not finished in this long is stuck, and a stuck
+  # migration should fail the upgrade rather than hold it open forever.
+  activeDeadlineSeconds: {{ .Values.server.migrationJob.activeDeadlineSeconds }}
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/instance: {{ .Release.Name }}
+        app.kubernetes.io/component: migrate
+    spec:
+      restartPolicy: Never
+      {{- if .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml .Values.imagePullSecrets | nindent 8 }}
+      {{- end }}
+      {{- if .Values.mongo.enabled }}
+      # Only Mongo. The Job never opens Redis, and waiting on a Redis this
+      # chart may not even deploy would block an upgrade for no reason.
+      initContainers:
+        - name: wait-for-mongo
+          image: busybox:1.36
+          command:
+            - sh
+            - -c
+            - |
+              until nc -z {{ .Release.Name }}-mongo {{ .Values.mongo.port }}; do
+                echo "waiting for mongo..."; sleep 2;
+              done
+      {{- end }}
+      containers:
+        - name: migrate
+          image: "{{ .Values.server.image.repository }}:{{ .Values.server.image.tag }}"
+          env:
+            {{- include "vantage.server.env" . | nindent 12 }}
+            - name: VANTAGE_MIGRATE_ONLY
+              value: "true"
+{{- end }}

deploy/chart/vantage/templates/mongo.yaml

@@ -0,0 +1,92 @@
+{{- if .Values.mongo.enabled }}
+{{- if .Values.mongo.persistence.enabled }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ .Release.Name }}-mongo-data
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: mongo
+spec:
+  accessModes:
+    - {{ .Values.mongo.persistence.accessMode }}
+  {{- if .Values.mongo.persistence.storageClass }}
+  storageClassName: {{ .Values.mongo.persistence.storageClass }}
+  {{- end }}
+  resources:
+    requests:
+      storage: {{ .Values.mongo.persistence.size }}
+---
+{{- end }}
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ .Release.Name }}-mongo
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: mongo
+spec:
+  replicas: 1
+  strategy:
+    type: Recreate
+  selector:
+    matchLabels:
+      app.kubernetes.io/instance: {{ .Release.Name }}
+      app.kubernetes.io/component: mongo
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/instance: {{ .Release.Name }}
+        app.kubernetes.io/component: mongo
+    spec:
+      {{- if .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml .Values.imagePullSecrets | nindent 8 }}
+      {{- end }}
+      containers:
+        - name: mongo
+          image: "{{ .Values.mongo.image.repository }}:{{ .Values.mongo.image.tag }}"
+          ports:
+            - containerPort: {{ .Values.mongo.port }}
+          volumeMounts:
+            - name: mongo-data
+              mountPath: /data/db
+          livenessProbe:
+            exec:
+              command: ["mongosh", "--quiet", "--eval", "db.adminCommand('ping')"]
+            initialDelaySeconds: 10
+            periodSeconds: 10
+            timeoutSeconds: 5
+            failureThreshold: 5
+          readinessProbe:
+            exec:
+              command: ["mongosh", "--quiet", "--eval", "db.adminCommand('ping')"]
+            initialDelaySeconds: 5
+            periodSeconds: 10
+            timeoutSeconds: 5
+            failureThreshold: 5
+      volumes:
+        - name: mongo-data
+          {{- if .Values.mongo.persistence.enabled }}
+          persistentVolumeClaim:
+            claimName: {{ .Release.Name }}-mongo-data
+          {{- else }}
+          emptyDir: {}
+          {{- end }}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ .Release.Name }}-mongo
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: mongo
+spec:
+  type: ClusterIP
+  selector:
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/component: mongo
+  ports:
+    - port: {{ .Values.mongo.port }}
+      targetPort: {{ .Values.mongo.port }}
+{{- end }}

deploy/chart/vantage/templates/redis.yaml

@@ -0,0 +1,92 @@
+{{- if .Values.redis.enabled }}
+{{- if .Values.redis.persistence.enabled }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ .Release.Name }}-redis-data
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: redis
+spec:
+  accessModes:
+    - {{ .Values.redis.persistence.accessMode }}
+  {{- if .Values.redis.persistence.storageClass }}
+  storageClassName: {{ .Values.redis.persistence.storageClass }}
+  {{- end }}
+  resources:
+    requests:
+      storage: {{ .Values.redis.persistence.size }}
+---
+{{- end }}
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ .Release.Name }}-redis
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: redis
+spec:
+  replicas: 1
+  strategy:
+    type: Recreate
+  selector:
+    matchLabels:
+      app.kubernetes.io/instance: {{ .Release.Name }}
+      app.kubernetes.io/component: redis
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/instance: {{ .Release.Name }}
+        app.kubernetes.io/component: redis
+    spec:
+      {{- if .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml .Values.imagePullSecrets | nindent 8 }}
+      {{- end }}
+      containers:
+        - name: redis
+          image: "{{ .Values.redis.image.repository }}:{{ .Values.redis.image.tag }}"
+          ports:
+            - containerPort: {{ .Values.redis.port }}
+          volumeMounts:
+            - name: redis-data
+              mountPath: /data
+          livenessProbe:
+            exec:
+              command: ["redis-cli", "ping"]
+            initialDelaySeconds: 10
+            periodSeconds: 10
+            timeoutSeconds: 5
+            failureThreshold: 5
+          readinessProbe:
+            exec:
+              command: ["redis-cli", "ping"]
+            initialDelaySeconds: 5
+            periodSeconds: 10
+            timeoutSeconds: 5
+            failureThreshold: 5
+      volumes:
+        - name: redis-data
+          {{- if .Values.redis.persistence.enabled }}
+          persistentVolumeClaim:
+            claimName: {{ .Release.Name }}-redis-data
+          {{- else }}
+          emptyDir: {}
+          {{- end }}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ .Release.Name }}-redis
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: redis
+spec:
+  type: ClusterIP
+  selector:
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/component: redis
+  ports:
+    - port: {{ .Values.redis.port }}
+      targetPort: {{ .Values.redis.port }}
+{{- end }}

deploy/chart/vantage/templates/server.yaml

@@ -0,0 +1,181 @@
+{{- if and .Values.server.persistence.enabled (not .Values.server.persistence.useHostPath) }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ .Release.Name }}-server-data
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: server
+spec:
+  accessModes:
+    - {{ .Values.server.persistence.accessMode }}
+  {{- if .Values.server.persistence.storageClass }}
+  storageClassName: {{ .Values.server.persistence.storageClass }}
+  {{- end }}
+  resources:
+    requests:
+      storage: {{ .Values.server.persistence.size }}
+---
+{{- end }}
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ .Release.Name }}-server
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: server
+spec:
+  {{- $replicas := int .Values.server.replicaCount }}
+  replicas: {{ $replicas }}
+  {{- if and .Values.server.persistence.enabled (eq .Values.server.persistence.accessMode "ReadWriteOnce") }}
+  # A ReadWriteOnce volume cannot be mounted by a second pod at all, and cannot
+  # be handed to a new pod while the old one still holds it. Persistence is off
+  # by default now that nothing writes to it; if it is on, replicas are capped
+  # at one and updates go through Recreate.
+  {{- if gt $replicas 1 }}
+  {{- fail "server.persistence.enabled with a ReadWriteOnce volume cannot be combined with server.replicaCount > 1. Nothing in the server writes to that volume any more (workflow logs live in MongoDB); set server.persistence.enabled=false, or use a ReadWriteMany accessMode if you are keeping it for another reason." }}
+  {{- end }}
+  strategy:
+    type: Recreate
+  {{- end }}
+  selector:
+    matchLabels:
+      app.kubernetes.io/instance: {{ .Release.Name }}
+      app.kubernetes.io/component: server
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/instance: {{ .Release.Name }}
+        app.kubernetes.io/component: server
+    spec:
+      # The server stops gRPC before draining HTTP, so that every CommandStream
+      # handler returns and releases its agent's presence claim. A claim left
+      # behind outlives the pod for its 30s TTL, and during that window other
+      # replicas dispatch commands to a process that has exited — surfacing to
+      # the operator as "agent offline" on an agent that is perfectly healthy.
+      # 10s for gRPC plus 10s for the HTTP drain, with headroom.
+      terminationGracePeriodSeconds: {{ .Values.server.terminationGracePeriodSeconds }}
+      {{- if .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml .Values.imagePullSecrets | nindent 8 }}
+      {{- end }}
+      {{- if or .Values.redis.enabled .Values.mongo.enabled }}
+      # Wait for the dependencies this chart deploys to be reachable,
+      # approximating compose's `depends_on: condition: service_healthy`. An
+      # external Redis or Mongo is assumed to be up already — waiting on one
+      # would only turn someone else's outage into a stuck pod.
+      initContainers:
+        {{- if .Values.redis.enabled }}
+        - name: wait-for-redis
+          image: busybox:1.36
+          command:
+            - sh
+            - -c
+            - |
+              until nc -z {{ .Release.Name }}-redis {{ .Values.redis.port }}; do
+                echo "waiting for redis..."; sleep 2;
+              done
+        {{- end }}
+        {{- if .Values.mongo.enabled }}
+        - name: wait-for-mongo
+          image: busybox:1.36
+          command:
+            - sh
+            - -c
+            - |
+              until nc -z {{ .Release.Name }}-mongo {{ .Values.mongo.port }}; do
+                echo "waiting for mongo..."; sleep 2;
+              done
+        {{- end }}
+      {{- end }}
+      containers:
+        - name: server
+          image: "{{ .Values.server.image.repository }}:{{ .Values.server.image.tag }}"
+          ports:
+            - containerPort: {{ .Values.server.service.httpPort }}
+            - containerPort: {{ .Values.server.service.grpcPort }}
+          env:
+            {{- include "vantage.server.env" . | nindent 12 }}
+            {{- if .Values.server.migrationJob.enabled }}
+            # Schema setup ran in the pre-upgrade Job. Pods that repeated it
+            # would race each other, and the rename migration is not a race
+            # that tolerates a loser.
+            - name: VANTAGE_SKIP_MIGRATIONS
+              value: "true"
+            {{- end }}
+          # Liveness never touches Mongo or Redis: restarting every pod cannot
+          # fix a database outage, and each restart drops every agent command
+          # stream and console session it was carrying. Readiness does check
+          # both, so a pod that cannot serve leaves the Service and stays up.
+          startupProbe:
+            httpGet:
+              path: /healthz
+              port: {{ .Values.server.service.httpPort }}
+            periodSeconds: 5
+            # Generous: without the migration Job this pod runs every migration
+            # before it listens, and the rename has a ten-minute budget.
+            failureThreshold: 150
+          livenessProbe:
+            httpGet:
+              path: /healthz
+              port: {{ .Values.server.service.httpPort }}
+            periodSeconds: 20
+            failureThreshold: 3
+          readinessProbe:
+            httpGet:
+              path: /readyz
+              port: {{ .Values.server.service.httpPort }}
+            periodSeconds: 10
+            failureThreshold: 3
+          {{- if .Values.server.persistence.enabled }}
+          # Nothing in the server writes here any more — workflow logs moved to
+          # MongoDB so that every replica can read and write them. The mount
+          # remains only so an operator upgrading from a file-log release can
+          # still reach the old files before turning persistence off.
+          volumeMounts:
+            - name: server-data
+              mountPath: /data
+      volumes:
+        - name: server-data
+          persistentVolumeClaim:
+            claimName: {{ .Release.Name }}-server-data
+          {{- end }}
+---
+{{- if gt (int .Values.server.replicaCount) 1 }}
+apiVersion: policy/v1
+kind: PodDisruptionBudget
+metadata:
+  name: {{ .Release.Name }}-server
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: server
+spec:
+  # Agents reconnect on their own, but a drain that took every replica at once
+  # would disconnect every agent in the fleet simultaneously and stall every
+  # workflow run in flight.
+  minAvailable: 1
+  selector:
+    matchLabels:
+      app.kubernetes.io/instance: {{ .Release.Name }}
+      app.kubernetes.io/component: server
+---
+{{- end }}
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ .Release.Name }}-server
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: server
+spec:
+  type: {{ .Values.server.service.type }}
+  selector:
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/component: server
+  ports:
+    - name: http
+      port: {{ .Values.server.service.httpPort }}
+      targetPort: {{ .Values.server.service.httpPort }}
+    - name: grpc
+      port: {{ .Values.server.service.grpcPort }}
+      targetPort: {{ .Values.server.service.grpcPort }}

deploy/chart/vantage/templates/web.yaml

@@ -0,0 +1,78 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ .Release.Name }}-web
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: web
+spec:
+  # web holds no per-process state: sessions live in Redis and every request is
+  # proxied to the server. It is the one component here that scales freely.
+  replicas: {{ .Values.web.replicaCount }}
+  selector:
+    matchLabels:
+      app.kubernetes.io/instance: {{ .Release.Name }}
+      app.kubernetes.io/component: web
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/instance: {{ .Release.Name }}
+        app.kubernetes.io/component: web
+    spec:
+      {{- if .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml .Values.imagePullSecrets | nindent 8 }}
+      {{- end }}
+      initContainers:
+        - name: wait-for-server
+          image: busybox:1.36
+          command:
+            - sh
+            - -c
+            - |
+              until nc -z {{ .Release.Name }}-server {{ .Values.server.service.httpPort }}; do
+                echo "waiting for server..."; sleep 2;
+              done
+      containers:
+        - name: web
+          image: "{{ .Values.web.image.repository }}:{{ .Values.web.image.tag }}"
+          ports:
+            - containerPort: {{ .Values.web.service.port }}
+          # /healthz is served by this Next process. /api never reaches this
+          # pod at all — the ingress routes it to the server — so there is no
+          # backend address to configure and no probe here that could report
+          # the backend's health by accident.
+          startupProbe:
+            httpGet:
+              path: /healthz
+              port: {{ .Values.web.service.port }}
+            periodSeconds: 3
+            failureThreshold: 20
+          livenessProbe:
+            httpGet:
+              path: /healthz
+              port: {{ .Values.web.service.port }}
+            periodSeconds: 20
+            failureThreshold: 3
+          readinessProbe:
+            httpGet:
+              path: /healthz
+              port: {{ .Values.web.service.port }}
+            periodSeconds: 10
+            failureThreshold: 3
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ .Release.Name }}-web
+  labels:
+    {{- include "vantage.labels" . | nindent 4 }}
+    app.kubernetes.io/component: web
+spec:
+  type: {{ .Values.web.service.type }}
+  selector:
+    app.kubernetes.io/instance: {{ .Release.Name }}
+    app.kubernetes.io/component: web
+  ports:
+    - port: {{ .Values.web.service.port }}
+      targetPort: {{ .Values.web.service.port }}

deploy/chart/vantage/values.yaml

@@ -0,0 +1,135 @@
+# Default values for the vantage chart.
+
+redis:
+    enabled: true
+    addr: ""
+    image:
+        repository: redis
+        tag: "8"
+    persistence:
+        enabled: true
+        size: 1Gi
+        storageClass: ""
+        accessMode: ReadWriteOnce
+    port: 6379
+    auth:
+        username: ""
+        password: ""
+        existingSecret: ""
+        usernameKey: username
+        passwordKey: password
+
+mongo:
+    enabled: true
+    image:
+        repository: mongo
+        tag: "7"
+    persistence:
+        enabled: true
+        size: 5Gi
+        storageClass: ""
+        accessMode: ReadWriteOnce
+    port: 27017
+
+guacd:
+    image:
+        repository: docker.io/guacamole/guacd
+        tag: "1.6.0"
+    service:
+        type: ClusterIP
+        port: 4822
+
+server:
+    replicaCount: 1
+    # Must exceed the server's own stop sequence (10s gRPC GracefulStop + 10s
+    # HTTP drain) or the kubelet SIGKILLs mid-shutdown, which is exactly the
+    # abrupt exit that leaves agent presence claims stranded in Redis.
+    terminationGracePeriodSeconds: 30
+    migrationJob:
+        enabled: true
+        backoffLimit: 0
+        activeDeadlineSeconds: 900
+    image:
+        repository: gitea.hostxtra.co.uk/mrhid6/vantage/server
+        tag: latest
+    service:
+        type: ClusterIP
+        httpPort: 8080
+        grpcPort: 9090
+    env:
+        mongoUri: "mongodb://{{ .Release.Name }}-mongo:27017/vantage"
+        grpcHost: "{{ .Release.Name }}-server:9090"
+        keyEncryptionKey: ""
+        appRootLabel: vantage
+        proxyAdvertiseHost: "{{ .Release.Name }}-server"
+        proxyListenHost: "0.0.0.0"
+        trustedProxies: "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
+    persistence:
+        enabled: false
+        size: 1Gi
+        storageClass: ""
+        accessMode: ReadWriteOnce
+        hostPath: /data
+
+web:
+    replicaCount: 1
+    image:
+        repository: gitea.hostxtra.co.uk/mrhid6/vantage/web
+        tag: latest
+    service:
+        type: ClusterIP
+        port: 3000
+
+ingress:
+    enabled: false
+    className: traefik
+    entrypoint: websecure
+    annotations: {}
+    web:
+        host: ""
+        extraHosts: []
+    # Not optional: web proxies nothing, so these prefixes reach the server
+    # only through this ingress. Turning it off serves the UI with a dead API.
+    api:
+        enabled: true
+        paths:
+            - /api/
+            - /auth/
+            - /public/
+            - /update
+            - /install
+            - /update.ps1
+            - /install.ps1
+    grpc:
+        enabled: true
+        host: ""
+        annotations: {}
+    tls:
+        enabled: true
+        secretName: ""
+        grpcSecretName: ""
+        certResolver: ""
+
+imagePullSecrets: []
+
+# Scheduled backups.
+#
+# Off by default, deliberately. A backup with nowhere durable to land is a
+# false sense of safety, and the chart cannot know where that is — pvcName
+# must name a volume you have decided will outlive the cluster.
+#
+# There is no restore manifest here on purpose: a restore is an operator
+# decision with a confirmation attached, and must never be something a
+# `helm upgrade` can trigger. Run one as a `kubectl run` Job with
+# --confirm-db.
+backup:
+    enabled: false
+    schedule: "0 2 * * *"
+    image: ""
+    pvcName: ""
+    # Collections to leave out. Recorded in each archive's manifest, so an
+    # archive can never claim to be complete when it is not.
+    exclude: []
+    successfulJobsHistoryLimit: 3
+    failedJobsHistoryLimit: 3
+    resources: {}

deploy/docker-compose.yml

@@ -1,56 +0,0 @@
-services:
-  redis:
-    image: redis:8
-    restart: unless-stopped
-    volumes:
-      - redis_data:/data
-    healthcheck:
-      test:
-        - CMD
-        - redis-cli
-        - ping
-      interval: 10s
-      timeout: 5s
-      retries: 5
-  guacd:
-    image: docker.io/guacamole/guacd:1.6.0
-    restart: unless-stopped
-    ports:
-      - 4822:4822
-  server:
-    image: gitea.hostxtra.co.uk/mrhid6/vantage/server:latest
-    restart: unless-stopped
-    ports:
-      - 8080:8080
-      - 9090:9090
-    environment:
-      MONGO_URI: ${MONGO_URI:-}
-      REDIS_ADDR: redis:6379
-      GITEA_HOST: ${GITEA_HOST}
-      PUBLIC_HOST: ${PUBLIC_HOST}
-      GRPC_HOST: ${GRPC_HOST}
-      GRPC_PORT: "9090"
-      HTTP_PORT: "8080"
-      OIDC_ISSUER: ${OIDC_ISSUER:-}
-      OIDC_CLIENT_ID: ${OIDC_CLIENT_ID:-}
-      OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET:-}
-      OIDC_REDIRECT_URL: ${OIDC_REDIRECT_URL:-}
-      KEY_ENCRYPTION_KEY: ${KEY_ENCRYPTION_KEY:-}
-      VANTAGE_WORKFLOW_LOG_DIR: ${VANTAGE_WORKFLOW_LOG_DIR:-}
-      GUACD_ADDR: guacd:4822
-    depends_on:
-      redis:
-        condition: service_healthy
-    volumes:
-      - ./data:/data
-  web:
-    image: gitea.hostxtra.co.uk/mrhid6/vantage/web:latest
-    restart: unless-stopped
-    ports:
-      - 3000:3000
-    depends_on:
-      - server
-volumes:
-  mongo_data: null
-  redis_data: null
-networks: {}

deploy/docker/.env.example

@@ -0,0 +1,20 @@
+# Vantage self-hosted — copy to .env and fill in.
+# Used by: docker compose up -d
+
+# --- Required ---
+
+# host:port agents dial for gRPC. No default; boot fails without it.
+# Must be reachable from managed servers. Use the public host, port 9090.
+GRPC_HOST=vantage.yourdomain.com:9090
+
+# 64-char hex (32 bytes) for AES-256-GCM. Required for private keys,
+# secrets, OIDC secrets, RDP/VNC credentials.
+# Generate: openssl rand -hex 32
+KEY_ENCRYPTION_KEY=
+
+# --- Optional (defaults shown) ---
+
+# MongoDB is bundled in this compose file. Override only to use an external DB.
+MONGO_URI=mongodb://mongo:27017/vantage
+
+# Where workflow run logs are written inside the server container.

deploy/docker/docker-compose.yml

@@ -0,0 +1,72 @@
+services:
+    redis:
+        image: redis:8
+        restart: unless-stopped
+        volumes:
+            - redis_data:/data
+        healthcheck:
+            test:
+                - CMD
+                - redis-cli
+                - ping
+            interval: 10s
+            timeout: 5s
+            retries: 5
+    mongo:
+        image: mongo:7
+        restart: unless-stopped
+        volumes:
+            - mongo_data:/data/db
+        healthcheck:
+            test:
+                - CMD
+                - mongosh
+                - --quiet
+                - --eval
+                - "db.adminCommand('ping')"
+            interval: 10s
+            timeout: 5s
+            retries: 5
+    guacd:
+        image: docker.io/guacamole/guacd:1.6.0
+        restart: unless-stopped
+        ports:
+            - 4822:4822
+    server:
+        image: gitea.hostxtra.co.uk/mrhid6/vantage/server:latest
+        restart: unless-stopped
+        ports:
+            - 8080:8080
+            - 9090:9090
+        environment:
+            MONGO_URI: ${MONGO_URI:-mongodb://mongo:27017/vantage}
+            REDIS_ADDR: redis:6379
+            GRPC_HOST: ${GRPC_HOST}
+            GRPC_PORT: "9090"
+            HTTP_PORT: "8080"
+            KEY_ENCRYPTION_KEY: ${KEY_ENCRYPTION_KEY:-}
+            GUACD_ADDR: guacd:4822
+            PROXY_ADVERTISE_HOST: server
+            TRUSTED_PROXIES: ${TRUSTED_PROXIES:-10.0.0.0/8,172.16.0.0/12,192.168.0.0/16}
+        depends_on:
+            redis:
+                condition: service_healthy
+            mongo:
+                condition: service_healthy
+        volumes:
+            - ./data:/data
+    web:
+        image: gitea.hostxtra.co.uk/mrhid6/vantage/web:latest
+        restart: unless-stopped
+        ports:
+            - 3000:3000
+        # No API_URL: web proxies nothing. The reverse proxy in front of this
+        # deployment must route /api, /auth, /public, /install*, /update* to
+        # server:8080 and everything else to web:3000. Reaching web:3000
+        # directly serves the UI and every API call 404s.
+        depends_on:
+            - server
+volumes:
+    mongo_data: null
+    redis_data: null
+networks: {}

docs/superpowers/plans/2026-07-20-fleet-inventory.md

@@ -1,866 +0,0 @@
-# Fleet Inventory Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Agents collect CPU/RAM/swap/disk/partition inventory and report it to the server via a new `ReportInventory` RPC; the server stores the latest snapshot per server and the UI displays it.
-
-**Architecture:** New unary gRPC `ReportInventory` (mirrors existing `ReportUpdates`). Agent runs a 30s metrics ticker (CPU/RAM/swap usage) and, every 15 min, a full static collection (disks, partitions, CPU model, kernel). Server upserts an embedded `inventory` sub-doc on the `servers` document with merge rules that preserve static fields between slow ticks.
-
-**Tech Stack:** Go (gin, mongo-driver v2, hand-written JSON-codec gRPC), `/proc` readers, Next.js 16 + react-query + Tailwind.
-
-## Global Constraints
-
-- **No tests this iteration.** Verify with `go build ./...`, `go vet ./...`, `npm run build`.
-- gRPC uses a JSON codec: edit **both** `server/internal/grpc/pb/vantage.pb.go` and `agent/internal/grpc/pb/vantage.pb.go` identically, plus `proto/vantage/v1/vantage.proto` as documentation. No codegen. Mirror the existing `ReportUpdates` RPC wiring exactly (service interface, `_Vantage_*_Handler`, client method, `Vantage_ServiceDesc`).
-- Mongo: `db.Col("servers")`, `context.WithTimeout`. Follow `server/internal/services/servers.go`.
-- Agent already runs as root; `/proc` is readable. Linux is primary; Windows collectors may return empty.
-- Module path `github.com/mrhid6/vantage`.
-- Do not add heavy dependencies; implement `/proc` parsing directly.
-
----
-
-## Task 1: Inventory model + gRPC messages
-
-**Files:**
-- Modify: `server/internal/models/server.go`
-- Modify: `proto/vantage/v1/vantage.proto`
-- Modify: `server/internal/grpc/pb/vantage.pb.go`
-- Modify: `agent/internal/grpc/pb/vantage.pb.go`
-
-**Interfaces:**
-- Produces: `models.Inventory` (+ `CPUInfo`, `MemInfo`, `Partition`) and `Server.Inventory *Inventory`. pb structs `InventoryReport`, `CPUReport`, `MemReport`, `PartitionReport`, `InventoryReportResponse`. Service method `ReportInventory` on both client and server interfaces.
-
-- [ ] **Step 1: Add model structs**
-
-In `server/internal/models/server.go` add (keep the existing `import "time"`):
-
-```go
-type CPUInfo struct {
-	Model    string  `bson:"model,omitempty" json:"model,omitempty"`
-	Cores    int     `bson:"cores,omitempty" json:"cores,omitempty"`
-	UsagePct float64 `bson:"usage_pct" json:"usage_pct"`
-	Load1    float64 `bson:"load1,omitempty" json:"load1,omitempty"`
-}
-
-type MemInfo struct {
-	TotalBytes uint64 `bson:"total_bytes" json:"total_bytes"`
-	UsedBytes  uint64 `bson:"used_bytes" json:"used_bytes"`
-}
-
-type Partition struct {
-	Device     string `bson:"device" json:"device"`
-	Mountpoint string `bson:"mountpoint" json:"mountpoint"`
-	Fstype     string `bson:"fstype,omitempty" json:"fstype,omitempty"`
-	TotalBytes uint64 `bson:"total_bytes" json:"total_bytes"`
-	UsedBytes  uint64 `bson:"used_bytes" json:"used_bytes"`
-}
-
-type Inventory struct {
-	CPU            CPUInfo     `bson:"cpu" json:"cpu"`
-	Memory         MemInfo     `bson:"memory" json:"memory"`
-	SwapTotalBytes uint64      `bson:"swap_total_bytes" json:"swap_total_bytes"`
-	SwapUsedBytes  uint64      `bson:"swap_used_bytes" json:"swap_used_bytes"`
-	Partitions     []Partition `bson:"partitions,omitempty" json:"partitions,omitempty"`
-	Kernel         string      `bson:"kernel,omitempty" json:"kernel,omitempty"`
-	MetricsAt      *time.Time  `bson:"metrics_at,omitempty" json:"metrics_at,omitempty"`
-	StaticAt       *time.Time  `bson:"static_at,omitempty" json:"static_at,omitempty"`
-}
-```
-
-Add to the `Server` struct: `Inventory *Inventory \`bson:"inventory,omitempty" json:"inventory,omitempty"\``.
-
-- [ ] **Step 2: Document RPC in proto**
-
-In `proto/vantage/v1/vantage.proto`, add to the service: `rpc ReportInventory(InventoryReport) returns (InventoryReportResponse);` and the messages `InventoryReport`, `CPUReport`, `MemReport`, `PartitionReport`, `InventoryReportResponse` per spec §4.
-
-- [ ] **Step 3: Add pb structs + RPC wiring (server pb)**
-
-In `server/internal/grpc/pb/vantage.pb.go` add the message structs:
-
-```go
-type CPUReport struct {
-	Model    string  `json:"model,omitempty"`
-	Cores    int     `json:"cores,omitempty"`
-	UsagePct float64 `json:"usage_pct"`
-	Load1    float64 `json:"load1,omitempty"`
-}
-type MemReport struct {
-	TotalBytes uint64 `json:"total_bytes"`
-	UsedBytes  uint64 `json:"used_bytes"`
-}
-type PartitionReport struct {
-	Device     string `json:"device"`
-	Mountpoint string `json:"mountpoint"`
-	Fstype     string `json:"fstype,omitempty"`
-	TotalBytes uint64 `json:"total_bytes"`
-	UsedBytes  uint64 `json:"used_bytes"`
-}
-type InventoryReport struct {
-	ServerId      string            `json:"server_id"`
-	AgentToken    string            `json:"agent_token"`
-	IncludeStatic bool              `json:"include_static"`
-	CPU           *CPUReport        `json:"cpu,omitempty"`
-	Memory        *MemReport        `json:"memory,omitempty"`
-	SwapTotal     uint64            `json:"swap_total"`
-	SwapUsed      uint64            `json:"swap_used"`
-	Partitions    []PartitionReport `json:"partitions,omitempty"`
-	Kernel        string            `json:"kernel,omitempty"`
-}
-type InventoryReportResponse struct{}
-```
-
-Then mirror the `ReportUpdates` RPC plumbing for `ReportInventory`. Locate every `ReportUpdates` reference in this file and add the parallel `ReportInventory`:
-- `VantageServer` interface: add `ReportInventory(context.Context, *InventoryReport) (*InventoryReportResponse, error)`.
-- `UnimplementedVantageServer`: add the stub returning `Unimplemented`.
-- `VantageClient` interface + `keyManagerClient`: add the client method `Invoke`-ing `/vantage.v1.Vantage/ReportInventory`.
-- `Vantage_ServiceDesc.Methods`: add `{MethodName: "ReportInventory", Handler: _Vantage_ReportInventory_Handler}`.
-- Add `_Vantage_ReportInventory_Handler` copied from `_Vantage_ReportUpdates_Handler` with types swapped.
-
-- [ ] **Step 4: Mirror pb structs + wiring (agent pb)**
-
-Apply the identical additions to `agent/internal/grpc/pb/vantage.pb.go`.
-
-- [ ] **Step 5: Verify build**
-
-Run: `cd server && go build ./... && cd ../agent && go build ./...`
-Expected: both succeed.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add server/internal/models/server.go proto/vantage/v1/vantage.proto server/internal/grpc/pb/vantage.pb.go agent/internal/grpc/pb/vantage.pb.go
-git commit -m "feat(proto): add ReportInventory RPC and inventory model"
-```
-
----
-
-## Task 2: Server handler + store service
-
-**Files:**
-- Create: `server/internal/services/inventory.go`
-- Modify: `server/internal/grpc/server.go`
-
-**Interfaces:**
-- Consumes: `pb.InventoryReport` (T1), `db.Col("servers")`.
-- Produces: `services.StoreInventory(serverID string, r *pb.InventoryReport) error`; gRPC method `(*vantageServer).ReportInventory`.
-
-- [ ] **Step 1: Write the store service**
-
-```go
-package services
-
-import (
-	"context"
-	"time"
-
-	"github.com/mrhid6/vantage/server/internal/db"
-	"github.com/mrhid6/vantage/server/internal/grpc/pb"
-	"go.mongodb.org/mongo-driver/v2/bson"
-)
-
-// StoreInventory upserts the latest inventory snapshot onto the server document.
-// Metrics fields update every call; static fields only when r.IncludeStatic.
-func StoreInventory(serverID string, r *pb.InventoryReport) error {
-	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-	defer cancel()
-
-	now := time.Now()
-	set := bson.M{"inventory.metrics_at": now}
-	if r.CPU != nil {
-		set["inventory.cpu.usage_pct"] = r.CPU.UsagePct
-		set["inventory.cpu.load1"] = r.CPU.Load1
-	}
-	if r.Memory != nil {
-		set["inventory.memory.used_bytes"] = r.Memory.UsedBytes
-	}
-	set["inventory.swap_used_bytes"] = r.SwapUsed
-
-	if r.IncludeStatic {
-		set["inventory.static_at"] = now
-		set["inventory.swap_total_bytes"] = r.SwapTotal
-		set["inventory.kernel"] = r.Kernel
-		if r.CPU != nil {
-			set["inventory.cpu.model"] = r.CPU.Model
-			set["inventory.cpu.cores"] = r.CPU.Cores
-		}
-		if r.Memory != nil {
-			set["inventory.memory.total_bytes"] = r.Memory.TotalBytes
-		}
-		parts := make([]bson.M, 0, len(r.Partitions))
-		for _, p := range r.Partitions {
-			parts = append(parts, bson.M{
-				"device": p.Device, "mountpoint": p.Mountpoint, "fstype": p.Fstype,
-				"total_bytes": p.TotalBytes, "used_bytes": p.UsedBytes,
-			})
-		}
-		set["inventory.partitions"] = parts
-	}
-
-	_, err := db.Col("servers").UpdateOne(ctx, bson.M{"server_id": serverID}, bson.M{"$set": set})
-	return err
-}
-```
-
-- [ ] **Step 2: Add the gRPC handler**
-
-In `server/internal/grpc/server.go`, add (mirroring the existing `ReportUpdates` handler that validates the agent token):
-
-```go
-func (s *vantageServer) ReportInventory(ctx context.Context, req *pb.InventoryReport) (*pb.InventoryReportResponse, error) {
-	srv, err := services.ValidateAgentToken(req.ServerId, req.AgentToken)
-	if err != nil {
-		return nil, status.Errorf(codes.Unauthenticated, "invalid agent token")
-	}
-	if err := services.StoreInventory(srv.ServerID, req); err != nil {
-		log.Printf("store inventory for %s: %v", srv.ServerID, err)
-	}
-	return &pb.InventoryReportResponse{}, nil
-}
-```
-
-Confirm `status`, `codes`, `log` are already imported in the file (they are, used by other handlers).
-
-- [ ] **Step 3: Verify build**
-
-Run: `cd server && go build ./... && go vet ./...`
-Expected: success.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add server/internal/services/inventory.go server/internal/grpc/server.go
-git commit -m "feat(server): store inventory and handle ReportInventory RPC"
-```
-
----
-
-## Task 3: Agent collectors
-
-**Files:**
-- Create: `agent/internal/inventory/collect_linux.go`
-- Create: `agent/internal/inventory/collect_other.go`
-- Create: `agent/internal/inventory/inventory.go`
-
-**Interfaces:**
-- Produces: `inventory.Collect(includeStatic bool) *pb.InventoryReport`.
-
-- [ ] **Step 1: Common entry (`inventory.go`)**
-
-```go
-package inventory
-
-import "github.com/mrhid6/vantage/agent/internal/grpc/pb"
-
-// Collect gathers metrics always and static hardware info when includeStatic.
-// Platform specifics are provided by collect_linux.go / collect_other.go.
-func Collect(includeStatic bool) *pb.InventoryReport {
-	r := &pb.InventoryReport{IncludeStatic: includeStatic, CPU: &pb.CPUReport{}, Memory: &pb.MemReport{}}
-	collect(r, includeStatic)
-	return r
-}
-```
-
-- [ ] **Step 2: Linux collector (`collect_linux.go`)**
-
-Build-tagged `//go:build linux`. Implement `collect(r *pb.InventoryReport, includeStatic bool)`:
-- CPU usage: read `/proc/stat` first line twice ~100ms apart, compute `1 - idleDelta/totalDelta` × 100 → `r.CPU.UsagePct`.
-- Load: first field of `/proc/loadavg` → `r.CPU.Load1`.
-- Mem/swap: parse `/proc/meminfo` (`MemTotal`, `MemAvailable`, `SwapTotal`, `SwapFree`; used = total − available; swap used = swaptotal − swapfree) → `r.Memory.*`, `r.SwapUsed`, and on static `r.SwapTotal`.
-- Static only: `/proc/cpuinfo` (`model name`, count `processor` lines) → `r.CPU.Model/Cores`; `/proc/meminfo MemTotal` → `r.Memory.TotalBytes`; kernel via `syscall.Uname` or read `/proc/sys/kernel/osrelease` → `r.Kernel`; partitions from `/proc/mounts` filtered to fstypes in {ext4,xfs,btrfs,zfs,vfat,ntfs} then `syscall.Statfs` for total/used → `r.Partitions`.
-
-```go
-//go:build linux
-
-package inventory
-
-import (
-	"bufio"
-	"os"
-	"strconv"
-	"strings"
-	"syscall"
-	"time"
-
-	"github.com/mrhid6/vantage/agent/internal/grpc/pb"
-)
-
-func collect(r *pb.InventoryReport, includeStatic bool) {
-	r.CPU.UsagePct = cpuUsage()
-	r.CPU.Load1 = load1()
-	memTotal, memAvail, swapTotal, swapFree := meminfo()
-	if memTotal > memAvail {
-		r.Memory.UsedBytes = memTotal - memAvail
-	}
-	if swapTotal > swapFree {
-		r.SwapUsed = swapTotal - swapFree
-	}
-	if includeStatic {
-		r.Memory.TotalBytes = memTotal
-		r.SwapTotal = swapTotal
-		r.CPU.Model, r.CPU.Cores = cpuStatic()
-		r.Kernel = kernel()
-		r.Partitions = partitions()
-	}
-}
-
-func readProc(path string) string { b, _ := os.ReadFile(path); return string(b) }
-
-func cpuSample() (idle, total uint64) {
-	f, err := os.Open("/proc/stat")
-	if err != nil {
-		return
-	}
-	defer f.Close()
-	sc := bufio.NewScanner(f)
-	if sc.Scan() {
-		fields := strings.Fields(sc.Text()) // cpu user nice system idle iowait ...
-		for i, v := range fields[1:] {
-			n, _ := strconv.ParseUint(v, 10, 64)
-			total += n
-			if i == 3 { // idle
-				idle = n
-			}
-		}
-	}
-	return
-}
-
-func cpuUsage() float64 {
-	i1, t1 := cpuSample()
-	time.Sleep(100 * time.Millisecond)
-	i2, t2 := cpuSample()
-	dt := float64(t2 - t1)
-	if dt <= 0 {
-		return 0
-	}
-	return (1 - float64(i2-i1)/dt) * 100
-}
-
-func load1() float64 {
-	fields := strings.Fields(readProc("/proc/loadavg"))
-	if len(fields) > 0 {
-		v, _ := strconv.ParseFloat(fields[0], 64)
-		return v
-	}
-	return 0
-}
-
-func meminfo() (total, avail, swapTotal, swapFree uint64) {
-	f, err := os.Open("/proc/meminfo")
-	if err != nil {
-		return
-	}
-	defer f.Close()
-	sc := bufio.NewScanner(f)
-	for sc.Scan() {
-		fields := strings.Fields(sc.Text())
-		if len(fields) < 2 {
-			continue
-		}
-		kb, _ := strconv.ParseUint(fields[1], 10, 64)
-		b := kb * 1024
-		switch strings.TrimSuffix(fields[0], ":") {
-		case "MemTotal":
-			total = b
-		case "MemAvailable":
-			avail = b
-		case "SwapTotal":
-			swapTotal = b
-		case "SwapFree":
-			swapFree = b
-		}
-	}
-	return
-}
-
-func cpuStatic() (model string, cores int) {
-	f, err := os.Open("/proc/cpuinfo")
-	if err != nil {
-		return
-	}
-	defer f.Close()
-	sc := bufio.NewScanner(f)
-	for sc.Scan() {
-		line := sc.Text()
-		if strings.HasPrefix(line, "processor") {
-			cores++
-		} else if strings.HasPrefix(line, "model name") && model == "" {
-			if i := strings.Index(line, ":"); i >= 0 {
-				model = strings.TrimSpace(line[i+1:])
-			}
-		}
-	}
-	return
-}
-
-func kernel() string {
-	return strings.TrimSpace(readProc("/proc/sys/kernel/osrelease"))
-}
-
-func partitions() []pb.PartitionReport {
-	allowed := map[string]bool{"ext4": true, "xfs": true, "btrfs": true, "zfs": true, "vfat": true, "ntfs": true, "ext3": true}
-	f, err := os.Open("/proc/mounts")
-	if err != nil {
-		return nil
-	}
-	defer f.Close()
-	var out []pb.PartitionReport
-	seen := map[string]bool{}
-	sc := bufio.NewScanner(f)
-	for sc.Scan() {
-		fields := strings.Fields(sc.Text())
-		if len(fields) < 3 || !allowed[fields[2]] || seen[fields[1]] {
-			continue
-		}
-		seen[fields[1]] = true
-		var st syscall.Statfs_t
-		if syscall.Statfs(fields[1], &st) != nil {
-			continue
-		}
-		total := st.Blocks * uint64(st.Bsize)
-		free := st.Bavail * uint64(st.Bsize)
-		out = append(out, pb.PartitionReport{
-			Device: fields[0], Mountpoint: fields[1], Fstype: fields[2],
-			TotalBytes: total, UsedBytes: total - free,
-		})
-	}
-	return out
-}
-```
-
-- [ ] **Step 3: Non-linux stub (`collect_other.go`)**
-
-```go
-//go:build !linux
-
-package inventory
-
-import "github.com/mrhid6/vantage/agent/internal/grpc/pb"
-
-// collect is a no-op best-effort stub on non-Linux platforms.
-func collect(r *pb.InventoryReport, includeStatic bool) {}
-```
-
-- [ ] **Step 4: Verify build**
-
-Run: `cd agent && go build ./... && go vet ./...`
-Expected: success (build both native and, if convenient, `GOOS=windows go build ./...`).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add agent/internal/inventory/
-git commit -m "feat(agent): /proc-based inventory collectors"
-```
-
----
-
-## Task 4: Agent client method + scheduler
-
-**Files:**
-- Modify: `agent/internal/grpc/client.go`
-- Modify: the agent main loop (`agent/cmd/main.go` or `agent/internal/sync/sync.go` — wherever the poll loop/tickers live).
-
-**Interfaces:**
-- Consumes: `inventory.Collect` (T3), pb (T1).
-- Produces: `(*Client).ReportInventory(report *pb.InventoryReport) error`; a running ticker that reports metrics every 30s and static every 15 min.
-
-- [ ] **Step 1: Add client method**
-
-In `agent/internal/grpc/client.go`, mirroring `ReportUpdates`:
-
-```go
-func (c *Client) ReportInventory(report *pb.InventoryReport) error {
-	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-	defer cancel()
-	_, err := c.client.ReportInventory(ctx, report)
-	return err
-}
-```
-
-The report already carries `ServerId`/`AgentToken`; ensure the caller sets them (see Step 2).
-
-- [ ] **Step 2: Add the scheduler to the agent loop**
-
-Find where the agent starts its poll loop (the goroutine that calls `SyncKeys`/`ReportUpdates`). Add a parallel inventory ticker. `serverID`, `agentToken`, and the `*Client` are in scope there:
-
-```go
-	go func() {
-		tick := 0
-		t := time.NewTicker(30 * time.Second)
-		defer t.Stop()
-		report := func(static bool) {
-			r := inventory.Collect(static)
-			r.ServerId = serverID
-			r.AgentToken = agentToken
-			if err := client.ReportInventory(r); err != nil {
-				log.Printf("report inventory: %v", err)
-			}
-		}
-		report(true) // send a full snapshot on startup
-		for range t.C {
-			tick++
-			report(tick%30 == 0) // every 30th tick = 15 min → include static
-		}
-	}()
-```
-
-Add imports `"github.com/mrhid6/vantage/agent/internal/inventory"`, `time`, `log` if missing. Match variable names to the actual loop (e.g. the client may be named `c`).
-
-- [ ] **Step 3: Verify build**
-
-Run: `cd agent && go build ./... && go vet ./...`
-Expected: success.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add agent/internal/grpc/client.go agent/
-git commit -m "feat(agent): schedule inventory reporting (30s metrics, 15m static)"
-```
-
----
-
-## Task 5: Frontend — inventory panel on server detail
-
-**Files:**
-- Modify: `web/lib/api.ts` (extend the `Server`/server-detail type with `inventory`)
-- Modify: `web/app/servers/[id]/page.tsx` (add panel; enable polling)
-
-**Interfaces:**
-- Consumes: server-detail query.
-
-- [ ] **Step 1: Add the inventory type**
-
-In `web/lib/api.ts`, add and attach to the server type used by the detail page:
-
-```ts
-export interface Inventory {
-  cpu: { model?: string; cores?: number; usage_pct: number; load1?: number };
-  memory: { total_bytes: number; used_bytes: number };
-  swap_total_bytes: number;
-  swap_used_bytes: number;
-  partitions?: { device: string; mountpoint: string; fstype?: string; total_bytes: number; used_bytes: number }[];
-  kernel?: string;
-  metrics_at?: string;
-  static_at?: string;
-}
-```
-
-Add `inventory?: Inventory;` to the server detail interface.
-
-- [ ] **Step 2: Add a `formatBytes` helper + Inventory panel**
-
-In `web/app/servers/[id]/page.tsx`, add a helper and a panel component. Enable polling on the server-detail `useQuery` with `refetchInterval: 30000`.
-
-```tsx
-function formatBytes(n: number): string {
-  if (!n) return "0 B";
-  const u = ["B", "KB", "MB", "GB", "TB"];
-  const i = Math.floor(Math.log(n) / Math.log(1024));
-  return `${(n / Math.pow(1024, i)).toFixed(1)} ${u[i]}`;
-}
-
-function UsageBar({ used, total }: { used: number; total: number }) {
-  const pct = total > 0 ? Math.min(100, (used / total) * 100) : 0;
-  return (
-    <div className="h-2 w-full overflow-hidden rounded-full bg-surface-2">
-      <div className={`h-full rounded-full ${pct > 90 ? "bg-danger" : "bg-accent"}`} style={{ width: `${pct}%` }} />
-    </div>
-  );
-}
-
-function InventoryPanel({ inv }: { inv: Inventory }) {
-  return (
-    <Card>
-      <h2 className="mb-4 text-lg font-semibold text-text-primary">Inventory</h2>
-      <div className="grid gap-4 sm:grid-cols-2">
-        <div>
-          <div className="mb-1 flex justify-between text-sm"><span className="text-text-secondary">CPU</span><span className="text-text-primary">{inv.cpu.usage_pct.toFixed(0)}%</span></div>
-          <UsageBar used={inv.cpu.usage_pct} total={100} />
-          <p className="mt-1 text-xs text-text-secondary">{inv.cpu.model} · {inv.cpu.cores} cores · load {inv.cpu.load1?.toFixed(2)}</p>
-        </div>
-        <div>
-          <div className="mb-1 flex justify-between text-sm"><span className="text-text-secondary">Memory</span><span className="text-text-primary">{formatBytes(inv.memory.used_bytes)} / {formatBytes(inv.memory.total_bytes)}</span></div>
-          <UsageBar used={inv.memory.used_bytes} total={inv.memory.total_bytes} />
-          <div className="mb-1 mt-3 flex justify-between text-sm"><span className="text-text-secondary">Swap</span><span className="text-text-primary">{formatBytes(inv.swap_used_bytes)} / {formatBytes(inv.swap_total_bytes)}</span></div>
-          <UsageBar used={inv.swap_used_bytes} total={inv.swap_total_bytes} />
-        </div>
-      </div>
-      {inv.partitions && inv.partitions.length > 0 && (
-        <div className="mt-5">
-          <h3 className="mb-2 text-sm font-medium text-text-secondary">Partitions</h3>
-          <div className="space-y-3">
-            {inv.partitions.map((p) => (
-              <div key={p.mountpoint}>
-                <div className="mb-1 flex justify-between text-xs">
-                  <span className="font-mono text-text-primary">{p.mountpoint}</span>
-                  <span className="text-text-secondary">{formatBytes(p.used_bytes)} / {formatBytes(p.total_bytes)} · {p.fstype}</span>
-                </div>
-                <UsageBar used={p.used_bytes} total={p.total_bytes} />
-              </div>
-            ))}
-          </div>
-        </div>
-      )}
-      {inv.kernel && <p className="mt-4 text-xs text-text-secondary">Kernel {inv.kernel}</p>}
-    </Card>
-  );
-}
-```
-
-Render `{server.inventory && <InventoryPanel inv={server.inventory} />}` in the page body (ensure `Card`, `Inventory` are imported). Match how the page currently reads the server object.
-
-- [ ] **Step 3: Verify build**
-
-Run: `cd web && npm run build`
-Expected: success.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add web/lib/api.ts web/app/servers/[id]/page.tsx
-git commit -m "feat(web): inventory panel on server detail"
-```
-
----
-
-## Task 6: End-to-end manual verification
-
-- [ ] **Step 1: Build all**
-
-Run: `cd server && go build ./... && cd ../agent && go build ./... && cd ../web && npm run build`
-Expected: all succeed.
-
-- [ ] **Step 2: Smoke (if environment available)**
-
-With server + Mongo + a connected Linux agent: within ~30s the server detail page shows CPU %, RAM/swap bars; within 15 min (or on agent restart, which sends a full snapshot immediately) partitions, CPU model and kernel appear. Confirm metrics update roughly every 30s.
-
-- [ ] **Step 3: Commit any fixes**
-
-```bash
-git add -A
-git commit -m "fix: fleet inventory verification fixes"
-```
-
----
-
-# Service Monitoring (uptime-kuma replacement)
-
-Extends the fleet work: in-app service monitors replacing uptime-kuma. Monitors (HTTP/TCP/ICMP/TLS) run **server-side** (public endpoints) or **agent-side** (agent probes its own host). Both runners feed one server-side ingest pipeline: state → incidents → rollups → notifications.
-
-**Design:** validated in brainstorm 2026-07-21. Hybrid runners, all 4 check types, latest+incidents+rollups history, multi-channel notify (webhook/SMTP/Discord/Slack/Telegram), dedicated `SyncMonitors`/`ReportChecks` RPCs.
-
-**Build order — 3 phases, each shippable:**
-- **P1 (Tasks 7–10):** data model, checker pkg, server scheduler, ingest pipeline, `/monitors` UI. Server-run only. No agent, no notify.
-- **P2 (Tasks 11–12):** `SyncMonitors` + `ReportChecks` RPCs, agent checker + scheduler, agent-run monitors bound to a server.
-- **P3 (Tasks 13–14):** notification channels + dispatch + settings UI.
-
-## Monitoring Global Constraints
-
-- Same as fleet: no tests this iteration; verify with `go build ./...`, `go vet ./...`, `npm run build`. JSON-codec gRPC — edit both pb files identically, mirror `ReportUpdates` wiring. Separate Go modules, so the checker pkg is **duplicated** in `server/` and `agent/` (same convention as pb files).
-- Reuse existing patterns: REST handlers like `server/internal/api`, services like `server/internal/services/servers.go`, `db.Col(...)`, react-query + Tailwind UI like `web/app/servers`.
-
----
-
-## Task 7: Monitoring data model + checker package (server)
-
-**Files:**
-- Create: `server/internal/models/monitor.go`
-- Create: `server/internal/checker/checker.go` (+ `http.go`, `tcp.go`, `icmp.go`, `tls.go`)
-
-**Interfaces:**
-- Produces: `models.Monitor` (+ `MonitorState`, `MonitorTarget`), `models.Incident`, `models.Rollup`. `checker.Run(ctx, models.Monitor) checker.Result` where `Result{Up bool; LatencyMs int; Message string; CertExpiry *time.Time}`.
-
-- [ ] **Step 1: Model**
-
-```go
-type MonitorTarget struct {
-	URL            string `bson:"url,omitempty" json:"url,omitempty"`
-	Host           string `bson:"host,omitempty" json:"host,omitempty"`
-	Port           int    `bson:"port,omitempty" json:"port,omitempty"`
-	Method         string `bson:"method,omitempty" json:"method,omitempty"`
-	ExpectedStatus int    `bson:"expected_status,omitempty" json:"expected_status,omitempty"`
-	Keyword        string `bson:"keyword,omitempty" json:"keyword,omitempty"`
-	TLSWarnDays    int    `bson:"tls_warn_days,omitempty" json:"tls_warn_days,omitempty"`
-}
-type MonitorState struct {
-	Status       string     `bson:"status" json:"status"` // up|down|pending
-	LastCheckAt  *time.Time `bson:"last_check_at,omitempty" json:"last_check_at,omitempty"`
-	LatencyMs    int        `bson:"latency_ms" json:"latency_ms"`
-	Message      string     `bson:"message,omitempty" json:"message,omitempty"`
-	CertExpiryAt *time.Time `bson:"cert_expiry_at,omitempty" json:"cert_expiry_at,omitempty"`
-	Fails        int        `bson:"fails" json:"fails"` // consecutive failures
-}
-type Monitor struct {
-	MonitorID   string        `bson:"monitor_id" json:"monitor_id"`
-	Name        string        `bson:"name" json:"name"`
-	Type        string        `bson:"type" json:"type"` // http|tcp|icmp|tls
-	Target      MonitorTarget `bson:"target" json:"target"`
-	IntervalSec int           `bson:"interval_sec" json:"interval_sec"`
-	Runner      string        `bson:"runner" json:"runner"` // "server" or a server_id
-	Retries     int           `bson:"retries" json:"retries"` // consecutive fails before down
-	Enabled     bool          `bson:"enabled" json:"enabled"`
-	ChannelIDs  []string      `bson:"channel_ids,omitempty" json:"channel_ids,omitempty"`
-	State       MonitorState  `bson:"state" json:"state"`
-	CreatedAt   time.Time     `bson:"created_at" json:"created_at"`
-}
-type Incident struct {
-	IncidentID string     `bson:"incident_id" json:"incident_id"`
-	MonitorID  string     `bson:"monitor_id" json:"monitor_id"`
-	StartedAt  time.Time  `bson:"started_at" json:"started_at"`
-	ResolvedAt *time.Time `bson:"resolved_at,omitempty" json:"resolved_at,omitempty"`
-	Cause      string     `bson:"cause,omitempty" json:"cause,omitempty"`
-}
-type Rollup struct {
-	MonitorID   string    `bson:"monitor_id" json:"monitor_id"`
-	PeriodStart time.Time `bson:"period_start" json:"period_start"` // hour bucket
-	Checks      int       `bson:"checks" json:"checks"`
-	UpCount     int       `bson:"up_count" json:"up_count"`
-	SumLatency  int64     `bson:"sum_latency" json:"sum_latency"`
-}
-```
-
-- [ ] **Step 2: Checker package** — `Run(ctx, m)` switches on `m.Type`:
-  - **http**: `http.Client` GET/HEAD `m.Target.URL`, assert status == ExpectedStatus (default 200), optional `Keyword` body contains; capture TLS peer cert expiry when https.
-  - **tcp**: `net.DialTimeout("tcp", host:port)`, latency = dial time.
-  - **icmp**: raw ICMP echo (agent/server run as root). Fall back to `net.Dial("ip4:icmp")`; on permission error return down with message.
-  - **tls**: `tls.Dial`, read `ConnectionState().PeerCertificates[0].NotAfter` → `CertExpiry`; down if within `TLSWarnDays` or expired.
-  - All: wrap with per-check timeout (min(IntervalSec, 10s)); `Result.Message` = short reason on failure.
-
-- [ ] **Step 3: Verify build** — `cd server && go build ./... && go vet ./...`
-
-- [ ] **Step 4: Commit** — `feat(server): monitor model + checker package`
-
----
-
-## Task 8: Ingest pipeline + rollups service
-
-**Files:**
-- Create: `server/internal/services/monitors.go`
-
-**Interfaces:**
-- Produces: `IngestResult(monitorID string, res checker.Result) error` — the single entry both runners use. `ListMonitors`, `GetMonitor`, `CreateMonitor`, `UpdateMonitor`, `DeleteMonitor`, `ListIncidents(monitorID)`, `UptimeRollups(monitorID, since)`.
-
-- [ ] **Step 1: `IngestResult`** — load monitor; compute new status with `Retries` threshold (increment `state.Fails` on failure, flip to `down` only when `Fails >= Retries`; reset + flip `up` on success). On **transition**: open incident (`down`) or resolve open incident (`up`), and enqueue notification (P3 — leave a `// TODO(P3): dispatch` hook now). Always `$set` state fields. Upsert current-hour `Rollup` (`$inc` checks/up_count/sum_latency). Use `db.Col("monitors")`, `db.Col("incidents")`, `db.Col("monitor_rollups")`, `context.WithTimeout`.
-
-- [ ] **Step 2: CRUD + queries** — standard service funcs mirroring `services/servers.go`. `UptimeRollups` aggregates buckets since a cutoff → uptime % + avg latency series.
-
-- [ ] **Step 3: Verify build** — `go build ./... && go vet ./...`
-
-- [ ] **Step 4: Commit** — `feat(server): monitor ingest pipeline, incidents, rollups`
-
----
-
-## Task 9: Server scheduler + REST API
-
-**Files:**
-- Create: `server/internal/monitorsched/scheduler.go`
-- Create: `server/internal/api/monitors.go`
-- Modify: server bootstrap (wherever services/gRPC start) to launch the scheduler; router registration where `api` routes are mounted.
-
-**Interfaces:**
-- Produces: a scheduler that ticks enabled `runner=="server"` monitors on their `IntervalSec` and calls `checker.Run` → `services.IngestResult`. REST: `GET/POST /api/monitors`, `GET/PUT/DELETE /api/monitors/:id`, `GET /api/monitors/:id/incidents`, `GET /api/monitors/:id/uptime`.
-
-- [ ] **Step 1: Scheduler** — on boot load monitors; per-monitor goroutine or a min-heap wheel keyed on next-run. Only `runner=="server"`. Reload on CRUD (simplest: re-read every N sec, or a reload channel fired by the service). Skip disabled.
-
-- [ ] **Step 2: REST handlers** — mirror an existing `server/internal/api` handler file for style + auth middleware. JSON in/out of `models.Monitor`.
-
-- [ ] **Step 3: Verify build** — `go build ./... && go vet ./...`
-
-- [ ] **Step 4: Commit** — `feat(server): server-run monitor scheduler + REST API`
-
----
-
-## Task 10: Frontend — monitors UI (P1)
-
-**Files:**
-- Modify: `web/lib/api.ts` (Monitor types + bindings)
-- Create: `web/app/monitors/page.tsx` (list), `web/app/monitors/[id]/page.tsx` (detail), `web/app/monitors/new/page.tsx` (create/edit form)
-- Modify: main nav to add **Monitors** (same place Steps was added)
-
-**Interfaces:**
-- Consumes: `/api/monitors*` (T9).
-
-- [ ] **Step 1: Types + api bindings** — `Monitor`, `MonitorState`, `Incident`, uptime series; `api.monitors.list/get/create/update/remove/incidents/uptime`.
-- [ ] **Step 2: List page** — table: name, type, status badge (up/down/pending), uptime % (24h), latency, last check. `refetchInterval: 30000`.
-- [ ] **Step 3: Detail page** — status header, heartbeat/uptime bars (24h + 30d from rollups), latency chart, incident timeline, cert expiry, assigned channels (read-only until P3).
-- [ ] **Step 4: Create/edit form** — type-dependent fields (URL vs host/port), interval, retries, runner select (`server` or a registered server for agent-run — server option only wired in P2), enabled.
-- [ ] **Step 5: Verify build** — `cd web && npm run build`
-- [ ] **Step 6: Commit** — `feat(web): monitors list/detail/form UI`
-
----
-
-## Task 11: SyncMonitors + ReportChecks RPCs (P2)
-
-**Files:**
-- Modify: `proto/vantage/v1/vantage.proto`, `server/internal/grpc/pb/vantage.pb.go`, `agent/internal/grpc/pb/vantage.pb.go`, `server/internal/grpc/server.go`, `agent/internal/grpc/client.go`
-
-**Interfaces:**
-- Produces: `SyncMonitors(server_id, agent_token) -> repeated MonitorSpec`; `ReportChecks(server_id, agent_token, repeated CheckResult) -> ReportChecksResponse`. `MonitorSpec{monitor_id, type, target fields, interval_sec, retries}`. `CheckResult{monitor_id, up, latency_ms, message, cert_expiry_unix}`.
-
-- [ ] **Step 1: pb structs + proto** — add messages to both pb files + proto doc.
-- [ ] **Step 2: Wire both RPCs** — mirror `ReportUpdates` plumbing (interface, Unimplemented stub, client method, `Vantage_ServiceDesc.Methods`, `_Vantage_*_Handler`) in both pb files. Server handlers on `vantageServer` (after `ReportUpdates` at server.go:78): `SyncMonitors` returns monitors where `runner==req.ServerId && enabled`; `ReportChecks` validates token then loops `services.IngestResult`. Client methods on `*Client` in client.go (after `ReportUpdates` at client.go:117).
-- [ ] **Step 3: Verify build** — both modules `go build ./... && go vet ./...`
-- [ ] **Step 4: Commit** — `feat(proto): SyncMonitors + ReportChecks RPCs`
-
----
-
-## Task 12: Agent checker + scheduler (P2)
-
-**Files:**
-- Create: `agent/internal/checker/` (duplicate of server checker pkg)
-- Create: `agent/internal/monitors/monitors.go` (poll + run + report loop)
-- Modify: agent main loop to start it (alongside the sync loop in `agent/internal/sync` / the inventory ticker from Task 4)
-
-**Interfaces:**
-- Consumes: `client.SyncMonitors`, `client.ReportChecks`, agent `checker`.
-
-- [ ] **Step 1: Duplicate checker pkg** into agent module (identical logic; imports agent pb).
-- [ ] **Step 2: Monitor loop** — poll `SyncMonitors` every 30s for assigned specs; per-spec ticker on `IntervalSec` runs `checker.Run`; batch `CheckResult`s and `ReportChecks`. `serverID`/`agentToken`/`*Client` in scope from the existing loop.
-- [ ] **Step 3: Verify build** — `cd agent && go build ./... && go vet ./...` (+ `GOOS=windows go build ./...`; icmp may no-op on Windows).
-- [ ] **Step 4: Commit** — `feat(agent): agent-run monitor scheduler`
-
----
-
-## Task 13: Notification channels + dispatch (P3)
-
-**Files:**
-- Create: `server/internal/models/channel.go`, `server/internal/services/channels.go`, `server/internal/notify/` (`dispatch.go`, `webhook.go`, `smtp.go`, `discord.go`, `slack.go`, `telegram.go`), `server/internal/api/channels.go`
-- Modify: `server/internal/services/monitors.go` (replace the P2 `// TODO(P3): dispatch` hook)
-
-**Interfaces:**
-- Produces: `models.NotificationChannel{channel_id, name, type, config map, enabled}`. `notify.Dispatch(channel, event)` where `event` = monitor + old/new status + message. `notify.Test(channel)`.
-
-- [ ] **Step 1: Model + CRUD service + REST** (`/api/channels*`, incl. `POST /api/channels/:id/test`).
-- [ ] **Step 2: Dispatch abstraction** — webhook/discord/slack/telegram are HTTP POST with per-type JSON payload; SMTP via `net/smtp`. Per-monitor routing via `monitor.ChannelIDs`; resend interval so an ongoing `down` re-alerts at most every N min (track `last_notified_at` on monitor state).
-- [ ] **Step 3: Fire on transition** — in `IngestResult`, on up/down flip resolve channels and `notify.Dispatch` each (goroutine, best-effort, log failures).
-- [ ] **Step 4: Verify build** — `go build ./... && go vet ./...`
-- [ ] **Step 5: Commit** — `feat(server): multi-channel monitor notifications`
-
----
-
-## Task 14: Frontend — notification settings (P3)
-
-**Files:**
-- Modify: `web/lib/api.ts` (channel types + bindings), `web/app/settings/` (add notifications section/page)
-- Modify: monitor create/edit form (Task 10) to select channels
-
-**Interfaces:**
-- Consumes: `/api/channels*`.
-
-- [ ] **Step 1: Channel types + api bindings.**
-- [ ] **Step 2: Settings UI** — list/add/edit channels, type-dependent config fields, **Test** button hitting `/api/channels/:id/test`.
-- [ ] **Step 3: Wire channel multi-select** into the monitor form.
-- [ ] **Step 4: Verify build** — `cd web && npm run build`
-- [ ] **Step 5: Commit** — `feat(web): notification channel settings UI`
-
----
-
-## Self-Review Notes
-
-- **Spec coverage:** §3 model → T1; §4 RPC → T1; §5 collectors + scheduler → T3, T4; §6 handler/store → T2; §7 frontend → T5. Split cadence (30s metrics / 15m static) in T4 scheduler; merge rules preserving static in T2 `StoreInventory`. Tests omitted per Global Constraints.
-- **Startup snapshot:** agent sends `Collect(true)` immediately so static fields populate without waiting 15 min.
-- **Types consistent:** `InventoryReport` field names identical across proto, both pb files, store service, and TS interface (`usage_pct`, `used_bytes`, `total_bytes`, `swap_*`).
-- **Follow-ups (out of scope):** time-series history, usage alerting, Windows collectors, servers-list CPU/RAM badges.
-- **Monitoring (Tasks 7–14):** hybrid runner service-monitor replacing uptime-kuma, added 2026-07-21. 3 phases — P1 server-run engine+UI (T7–10), P2 agent-run RPCs (T11–12), P3 multi-channel notify (T13–14). Single `IngestResult` pipeline for both runners; checker pkg duplicated per module (pb convention). Design: brainstorm 2026-07-21. Follow-ups out of scope: status pages, maintenance windows, per-check auth headers, ICMP on Windows.

docs/superpowers/plans/2026-08-24-status-pages-mockup.html

@@ -0,0 +1,641 @@
+<title>Vantage Status Pages</title>
+<style>
+  :root{
+    color-scheme: dark;
+    /* Vantage web/ dark tokens, copied verbatim from web/app/globals.css.
+       This mockup commits to one theme because web/ does. */
+    --ground:#071628; --panel:#0d2138; --panel-2:#102842; --well:#04101f;
+    --ink:#e4ecf6; --ink-2:#9fb3ca; --ink-3:#71879f;
+    --rule:#1e3855; --rule-soft:#172c44;
+    --accent:#5b9be8; --accent-hover:#7fb2f0; --accent-ink:#04101f;
+    --up:#4fb484; --pend:#d6a63f; --down:#e2705a; --logo:#7fb2f0;
+    --shadow:0 1px 0 rgba(0,0,0,.35), 0 20px 44px -26px rgba(0,0,0,.85);
+    --sans: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+    --mono: ui-monospace, "Cascadia Mono", "SF Mono", "JetBrains Mono", Menlo, Consolas, monospace;
+    --r:4px;
+  }
+  *{box-sizing:border-box;margin:0;padding:0}
+  body{background:var(--ground);color:var(--ink);font-family:var(--sans);-webkit-font-smoothing:antialiased;line-height:1.5}
+  a{color:inherit}
+  :focus-visible{outline:2px solid var(--accent);outline-offset:2px}
+
+  .page{max-width:1180px;margin:0 auto;padding:48px 24px 96px;display:flex;flex-direction:column;gap:56px}
+
+  .lede h1{font-size:1.6rem;font-weight:800;letter-spacing:-.035em;text-wrap:balance}
+  .lede p{color:var(--ink-2);font-size:.9rem;max-width:65ch;margin-top:8px}
+
+  .cap{font-family:var(--mono);font-size:.68rem;text-transform:uppercase;letter-spacing:.1em;color:var(--ink-2)}
+
+  .board{display:flex;flex-direction:column;gap:10px}
+  .board__head{display:flex;align-items:baseline;justify-content:space-between;gap:16px;flex-wrap:wrap}
+  .board__route{font-family:var(--mono);font-size:.7rem;color:var(--ink-3)}
+  .frame{border:1px solid var(--rule);border-radius:var(--r);background:var(--ground);box-shadow:var(--shadow);overflow:hidden}
+
+  /* address strip — shows the URL scheme being approved */
+  .addr{display:flex;align-items:center;gap:10px;background:var(--well);border-bottom:1px solid var(--rule);padding:9px 14px}
+  .addr__dots{display:flex;gap:5px}
+  .addr__dots i{width:8px;height:8px;border-radius:999px;background:var(--rule);display:block}
+  .addr__url{font-family:var(--mono);font-size:.72rem;color:var(--ink-2);overflow-x:auto;white-space:nowrap}
+  .addr__url b{color:var(--ink);font-weight:600}
+  .addr__tag{margin-left:auto;font-family:var(--mono);font-size:.62rem;text-transform:uppercase;letter-spacing:.1em;color:var(--ink-3);border:1px solid var(--rule);border-radius:999px;padding:2px 8px;white-space:nowrap}
+
+  /* ---------- public status page ---------- */
+  .pub{padding:40px 28px 32px}
+  .pub__inner{max-width:720px;margin:0 auto;display:flex;flex-direction:column;gap:28px}
+  .pub__head{display:flex;align-items:center;gap:14px}
+  .mark{width:38px;height:38px;border-radius:var(--r);background:var(--panel-2);border:1px solid var(--rule);display:grid;place-items:center;color:var(--logo);font-family:var(--mono);font-weight:700;font-size:.85rem;flex-shrink:0}
+  .pub__head h2{font-size:1.35rem;font-weight:800;letter-spacing:-.03em}
+  .pub__head p{color:var(--ink-2);font-size:.85rem;margin-top:2px}
+
+  .overall{display:flex;align-items:center;gap:11px;border:1px solid;border-radius:var(--r);padding:14px 16px;font-weight:600;font-size:.95rem}
+  .overall--down{background:rgba(226,112,90,.10);border-color:rgba(226,112,90,.30);color:var(--down)}
+  .glyph{width:16px;height:16px;flex-shrink:0}
+
+  .banner{border:1px solid var(--rule);background:var(--panel);border-radius:var(--r);padding:12px 14px;font-size:.85rem;color:var(--ink-2);display:flex;gap:10px}
+  .banner b{color:var(--ink);font-weight:600}
+
+  .group{display:flex;flex-direction:column;gap:10px}
+  .group > .cap{padding-left:2px}
+
+  .card{border:1px solid var(--rule);background:var(--panel);border-radius:var(--r)}
+  .rows > * + *{border-top:1px solid var(--rule-soft)}
+
+  .comp{padding:16px}
+  .comp__top{display:flex;align-items:center;justify-content:space-between;gap:16px;margin-bottom:10px}
+  .comp__name{font-weight:600;font-size:.92rem}
+  .state{display:inline-flex;align-items:center;gap:7px;font-size:.78rem;color:var(--ink-2);white-space:nowrap}
+  .dot{width:7px;height:7px;border-radius:999px;display:block;flex-shrink:0}
+  .dot--up{background:var(--up)} .dot--down{background:var(--down)}
+  .dot--maint{background:var(--accent)} .dot--pend{background:var(--pend)}
+  .dot--none{background:var(--rule)}
+
+  .bar{display:flex;gap:2px;overflow-x:auto;padding-bottom:2px}
+  .bar span{height:26px;width:3px;border-radius:999px;flex:0 0 auto;background:var(--rule)}
+  .bar .up{background:var(--up)} .bar .down{background:var(--down)}
+  .bar .maint{background:var(--accent)} .bar .none{background:var(--rule)}
+  .scale{display:flex;justify-content:space-between;margin-top:7px;font-size:.7rem;color:var(--ink-3)}
+  .scale b{color:var(--ink-2);font-weight:600;font-variant-numeric:tabular-nums}
+
+  .inc{padding:14px 16px}
+  .inc__top{display:flex;align-items:baseline;justify-content:space-between;gap:14px}
+  .inc__title{font-weight:600;font-size:.92rem}
+  .inc__meta{font-size:.75rem;color:var(--ink-3);margin-top:3px}
+  .inc__affects{font-size:.75rem;color:var(--ink-2);margin-top:5px}
+  .pill{font-family:var(--mono);font-size:.62rem;text-transform:uppercase;letter-spacing:.1em;border-radius:999px;padding:3px 9px;border:1px solid;white-space:nowrap}
+  .pill--inv{color:var(--down);border-color:rgba(226,112,90,.35);background:rgba(226,112,90,.10)}
+  .pill--mon{color:var(--pend);border-color:rgba(214,166,63,.35);background:rgba(214,166,63,.10)}
+  .pill--res{color:var(--up);border-color:rgba(79,180,132,.35);background:rgba(79,180,132,.10)}
+  .pill--sch{color:var(--accent);border-color:rgba(91,155,232,.35);background:rgba(91,155,232,.10)}
+  .pill--draft{color:var(--ink-2);border-color:var(--rule);background:var(--panel-2)}
+  .pill--live{color:var(--up);border-color:rgba(79,180,132,.35);background:rgba(79,180,132,.10)}
+
+  .timeline{margin-top:12px;border-left:1px solid var(--rule);padding-left:14px;display:flex;flex-direction:column;gap:12px}
+  .tl__head{display:flex;align-items:baseline;gap:9px}
+  .tl__st{font-family:var(--mono);font-size:.62rem;text-transform:uppercase;letter-spacing:.1em;color:var(--ink-2)}
+  .tl__at{font-size:.7rem;color:var(--ink-3);font-variant-numeric:tabular-nums}
+  .tl__body{font-size:.85rem;margin-top:3px;color:var(--ink)}
+
+  .pub__foot{text-align:center;font-size:.72rem;color:var(--ink-3);padding-top:6px}
+
+  /* ---------- editor ---------- */
+  .app{display:grid;grid-template-columns:236px 1fr;min-height:660px}
+  .side{background:var(--panel);border-right:1px solid var(--rule);display:flex;flex-direction:column}
+  .side__brand{height:64px;display:flex;align-items:center;gap:12px;padding:0 20px;border-bottom:1px solid var(--rule);flex-shrink:0}
+  .side__brand .mark{width:32px;height:32px;font-size:.78rem}
+  .side__brand b{font-size:1rem;font-weight:800;letter-spacing:-.035em;display:block;line-height:1.2}
+  .side__nav{padding:16px 12px;display:flex;flex-direction:column;gap:16px}
+  .navgrp + .navgrp{border-top:1px solid var(--rule);padding-top:16px}
+  .navgrp > .cap{padding:0 12px 6px}
+  .navgrp ul{list-style:none;display:flex;flex-direction:column;gap:4px}
+  .navgrp a{position:relative;display:flex;align-items:center;gap:12px;border-radius:var(--r);padding:9px 12px;font-size:.85rem;font-weight:500;color:var(--ink-2);text-decoration:none}
+  .navgrp a:hover{background:var(--panel-2);color:var(--ink)}
+  .navgrp a.on{background:var(--panel-2);color:var(--ink);font-weight:600}
+  .navgrp a.on::before{content:"";position:absolute;left:0;top:4px;bottom:4px;width:2px;border-radius:999px;background:var(--accent)}
+  .navgrp svg{width:16px;height:16px;flex-shrink:0;opacity:.9}
+
+  .main{padding:26px 28px 36px;display:flex;flex-direction:column;gap:22px;min-width:0}
+  .back{font-size:.78rem;color:var(--ink-2);text-decoration:none;display:inline-flex;gap:6px;align-items:center}
+  .back:hover{color:var(--ink)}
+  .phead{display:flex;align-items:flex-start;justify-content:space-between;gap:20px;flex-wrap:wrap}
+  .phead h2{font-size:1.3rem;font-weight:800;letter-spacing:-.03em}
+  .record{display:flex;align-items:center;gap:8px;margin-top:6px}
+  .record code{font-family:var(--mono);font-size:.72rem;color:var(--ink-2);background:var(--well);border:1px solid var(--rule);border-radius:var(--r);padding:3px 8px}
+  .copy{background:none;border:0;color:var(--ink-3);cursor:pointer;font-size:.72rem;font-family:var(--mono)}
+  .copy:hover{color:var(--accent)}
+  .acts{display:flex;gap:9px;flex-wrap:wrap}
+  .btn{font-size:.82rem;font-weight:600;border-radius:var(--r);padding:8px 14px;border:1px solid var(--rule);background:var(--panel);color:var(--ink);cursor:pointer;text-decoration:none;display:inline-flex;align-items:center;gap:7px}
+  .btn:hover{background:var(--panel-2)}
+  .btn--p{background:var(--accent);border-color:var(--accent);color:var(--accent-ink)}
+  .btn--p:hover{background:var(--accent-hover)}
+
+  .panel{border:1px solid var(--rule);background:var(--panel);border-radius:var(--r)}
+  .panel__head{display:flex;align-items:center;justify-content:space-between;gap:14px;padding:13px 16px;border-bottom:1px solid var(--rule)}
+  .panel__head h3{font-size:.95rem;font-weight:700}
+  .panel__head p{font-size:.76rem;color:var(--ink-3);margin-top:2px}
+  .panel__body{padding:16px;display:flex;flex-direction:column;gap:16px}
+
+  .fields{display:grid;grid-template-columns:repeat(auto-fit,minmax(230px,1fr));gap:14px}
+  .field{display:flex;flex-direction:column;gap:6px;min-width:0}
+  .field > label{font-size:.76rem;font-weight:600;color:var(--ink-2)}
+  .field .hint{font-size:.72rem;color:var(--ink-3)}
+  .in{background:var(--well);border:1px solid var(--rule);border-radius:var(--r);padding:8px 11px;font:inherit;font-size:.85rem;color:var(--ink);width:100%}
+  .in::placeholder{color:var(--ink-3)}
+  .in:focus{outline:2px solid var(--accent);outline-offset:-1px;border-color:var(--accent)}
+  .in--mono{font-family:var(--mono);font-size:.8rem}
+
+  .toggle{display:flex;align-items:center;justify-content:space-between;gap:16px;background:var(--panel-2);border:1px solid var(--rule);border-radius:var(--r);padding:12px 14px}
+  .toggle p{font-size:.76rem;color:var(--ink-3);margin-top:3px;max-width:52ch}
+  .toggle b{font-size:.85rem}
+  .sw{width:38px;height:21px;border-radius:999px;background:var(--up);border:0;position:relative;cursor:pointer;flex-shrink:0}
+  .sw::after{content:"";position:absolute;top:2px;left:19px;width:17px;height:17px;border-radius:999px;background:var(--accent-ink)}
+  .sw[aria-checked="false"]{background:var(--rule)}
+  .sw[aria-checked="false"]::after{left:2px;background:var(--ink-3)}
+
+  .sect{border:1px solid var(--rule);border-radius:var(--r);background:var(--panel-2)}
+  .sect__head{display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1px solid var(--rule)}
+  .sect__head .in{max-width:220px}
+  .sect__head .rm{margin-left:auto}
+  .rm{background:none;border:0;color:var(--ink-3);font-size:.75rem;cursor:pointer;font-family:var(--mono)}
+  .rm:hover{color:var(--down)}
+  .entry{display:grid;grid-template-columns:1fr 1fr auto;gap:12px;align-items:center;padding:11px 12px}
+  .entry + .entry{border-top:1px solid var(--rule-soft)}
+  .entry__mon{display:flex;flex-direction:column;gap:2px;min-width:0}
+  .entry__mon b{font-size:.84rem;font-weight:600}
+  .entry__mon span{font-family:var(--mono);font-size:.68rem;color:var(--ink-3)}
+  .adds{display:flex;gap:9px;flex-wrap:wrap;padding:0 12px 12px}
+
+  .inc-row{display:flex;align-items:flex-start;justify-content:space-between;gap:14px;padding:13px 14px}
+  .inc-row + .inc-row{border-top:1px solid var(--rule-soft)}
+  .inc-row__l{min-width:0}
+  .inc-row__l b{font-size:.88rem;font-weight:600;display:block}
+  .inc-row__l span{font-size:.74rem;color:var(--ink-3)}
+  .inc-row__r{display:flex;align-items:center;gap:9px;flex-shrink:0}
+
+  .notes{border-top:1px solid var(--rule);padding-top:14px;display:flex;flex-direction:column;gap:7px}
+  .notes li{font-size:.82rem;color:var(--ink-2);display:flex;gap:10px;list-style:none}
+  .notes li b{color:var(--ink);font-weight:600}
+  .notes .k{font-family:var(--mono);font-size:.66rem;text-transform:uppercase;letter-spacing:.1em;color:var(--ink-3);flex:0 0 76px;padding-top:2px}
+
+  @media (max-width:820px){
+    .app{grid-template-columns:1fr}
+    .side{display:none}
+    .entry{grid-template-columns:1fr}
+    .page{padding:32px 16px 64px}
+  }
+</style>
+
+<div class="page">
+
+  <header class="lede">
+    <p class="cap" style="margin-bottom:10px">Vantage · status pages · mockup for approval</p>
+    <h1>Two screens: what the public sees, and what the operator edits</h1>
+    <p>Drawn with the real <code style="font-family:var(--mono);font-size:.85em">web/</code> dark tokens and the existing sidebar idioms, so what gets approved here is what gets built. The public page is shown mid-incident rather than all-green, because that is the state it exists for.</p>
+  </header>
+
+  <!-- ================= PUBLIC ================= -->
+  <section class="board">
+    <div class="board__head">
+      <p class="cap">1 · Public status page</p>
+      <p class="board__route">web/app/status/[pageId]/page.tsx · no auth, no sidebar</p>
+    </div>
+
+    <div class="frame">
+      <div class="addr">
+        <span class="addr__dots"><i></i><i></i><i></i></span>
+        <span class="addr__url">https://acme.vantage.example.com<b>/status/api</b></span>
+        <span class="addr__tag">signed out</span>
+      </div>
+
+      <div class="pub">
+        <div class="pub__inner">
+
+          <div class="pub__head">
+            <div class="mark">AC</div>
+            <div>
+              <h2>Acme Platform Status</h2>
+              <p>Live availability for the Acme API and dashboard.</p>
+            </div>
+          </div>
+
+          <div class="overall overall--down">
+            <svg class="glyph" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" aria-hidden="true">
+              <circle cx="8" cy="8" r="6.4"/><path d="M8 4.8v3.6M8 11.1h.01" stroke-linecap="round"/>
+            </svg>
+            Service disruption
+          </div>
+
+          <div class="banner">
+            <svg class="glyph" viewBox="0 0 16 16" fill="none" stroke="var(--accent)" stroke-width="1.6" aria-hidden="true" style="margin-top:2px">
+              <circle cx="8" cy="8" r="6.4"/><path d="M8 7.4v3.8M8 5.1h.01" stroke-linecap="round"/>
+            </svg>
+            <span><b>Europe region only.</b> US and APAC are unaffected. Follow this page for updates.</span>
+          </div>
+
+          <div class="group">
+            <p class="cap">Active</p>
+            <div class="card">
+              <article class="inc">
+                <div class="inc__top">
+                  <div>
+                    <p class="inc__title">Elevated error rates on database writes</p>
+                    <p class="inc__meta">Started 24 Aug 2026, 09:12 UTC</p>
+                  </div>
+                  <span class="pill pill--mon">monitoring</span>
+                </div>
+                <p class="inc__affects">Affects Primary database, Public API</p>
+                <div class="timeline">
+                  <div>
+                    <div class="tl__head"><span class="tl__st">monitoring</span><span class="tl__at">11:40 UTC</span></div>
+                    <p class="tl__body">Failover completed. Write latency is back to normal and we are watching for recurrence before calling this resolved.</p>
+                  </div>
+                  <div>
+                    <div class="tl__head"><span class="tl__st">identified</span><span class="tl__at">09:48 UTC</span></div>
+                    <p class="tl__body">A failing disk on the primary database node is causing write timeouts. Failover to the standby node is in progress.</p>
+                  </div>
+                  <div>
+                    <div class="tl__head"><span class="tl__st">investigating</span><span class="tl__at">09:15 UTC</span></div>
+                    <p class="tl__body">We are investigating a rise in write errors affecting the API.</p>
+                  </div>
+                </div>
+              </article>
+            </div>
+          </div>
+
+          <div class="group">
+            <p class="cap">Scheduled maintenance</p>
+            <div class="card">
+              <article class="inc">
+                <div class="inc__top">
+                  <div>
+                    <p class="inc__title">Object storage capacity upgrade</p>
+                    <p class="inc__meta">31 Aug 2026, 02:00 – 04:00 UTC</p>
+                  </div>
+                  <span class="pill pill--sch">scheduled</span>
+                </div>
+                <p class="inc__affects">Affects Object storage</p>
+              </article>
+            </div>
+          </div>
+
+          <div class="group">
+            <p class="cap">API</p>
+            <div class="card rows">
+              <div class="comp" data-bar="api" data-state="down">
+                <div class="comp__top">
+                  <span class="comp__name">Public API</span>
+                  <span class="state"><i class="dot dot--down"></i>Down</span>
+                </div>
+                <div class="bar"></div>
+                <div class="scale"><span>90 days ago</span><span><b>99.81%</b> uptime</span><span>Today</span></div>
+              </div>
+              <div class="comp" data-bar="hooks" data-state="up">
+                <div class="comp__top">
+                  <span class="comp__name">Webhook delivery</span>
+                  <span class="state"><i class="dot dot--up"></i>Operational</span>
+                </div>
+                <div class="bar"></div>
+                <div class="scale"><span>90 days ago</span><span><b>99.99%</b> uptime</span><span>Today</span></div>
+              </div>
+            </div>
+          </div>
+
+          <div class="group">
+            <p class="cap">Web</p>
+            <div class="card rows">
+              <div class="comp" data-bar="dash" data-state="up">
+                <div class="comp__top">
+                  <span class="comp__name">Dashboard</span>
+                  <span class="state"><i class="dot dot--up"></i>Operational</span>
+                </div>
+                <div class="bar"></div>
+                <div class="scale"><span>90 days ago</span><span><b>99.97%</b> uptime</span><span>Today</span></div>
+              </div>
+            </div>
+          </div>
+
+          <div class="group">
+            <p class="cap">Data</p>
+            <div class="card rows">
+              <div class="comp" data-bar="db" data-state="down">
+                <div class="comp__top">
+                  <span class="comp__name">Primary database</span>
+                  <span class="state"><i class="dot dot--down"></i>Down</span>
+                </div>
+                <div class="bar"></div>
+                <div class="scale"><span>90 days ago</span><span><b>99.62%</b> uptime</span><span>Today</span></div>
+              </div>
+              <div class="comp" data-bar="obj" data-state="maint">
+                <div class="comp__top">
+                  <span class="comp__name">Object storage</span>
+                  <span class="state"><i class="dot dot--maint"></i>Maintenance</span>
+                </div>
+                <div class="bar"></div>
+                <div class="scale"><span>90 days ago</span><span><b>99.94%</b> uptime</span><span>Today</span></div>
+              </div>
+              <div class="comp" data-bar="new" data-state="up">
+                <div class="comp__top">
+                  <span class="comp__name">Search index</span>
+                  <span class="state"><i class="dot dot--up"></i>Operational</span>
+                </div>
+                <div class="bar"></div>
+                <div class="scale"><span>90 days ago</span><span><b>100.00%</b> uptime</span><span>Today</span></div>
+              </div>
+            </div>
+          </div>
+
+          <div class="group">
+            <p class="cap">Past incidents</p>
+            <div class="card rows">
+              <article class="inc">
+                <div class="inc__top">
+                  <div>
+                    <p class="inc__title">Public API unavailable</p>
+                    <p class="inc__meta">2 Aug 2026, 14:02 UTC — resolved 14:19 UTC</p>
+                  </div>
+                  <span class="pill pill--res">resolved</span>
+                </div>
+                <p class="inc__affects">Affects Public API</p>
+              </article>
+              <article class="inc">
+                <div class="inc__top">
+                  <div>
+                    <p class="inc__title">Slow dashboard loads in Europe</p>
+                    <p class="inc__meta">17 Jul 2026, 08:30 UTC — resolved 10:05 UTC</p>
+                  </div>
+                  <span class="pill pill--res">resolved</span>
+                </div>
+                <p class="inc__affects">Affects Dashboard</p>
+              </article>
+            </div>
+          </div>
+
+          <p class="pub__foot">Updated 24 Aug 2026, 11:58 UTC · refreshes every 60 seconds</p>
+        </div>
+      </div>
+    </div>
+
+    <ul class="notes">
+      <li><span class="k">Redacted</span><span>No target URL, host, port or failure text anywhere on this page. <b>Search index</b> shows the no-data tail as grey cells rather than claiming 100% for days before it existed.</span></li>
+      <li><span class="k">Maintenance</span><span><b>Object storage</b> reads as Maintenance, not Down — but its uptime figure is untouched. The window changes how it is drawn, never what the numbers say.</span></li>
+      <li><span class="k">Colour</span><span>Every state carries a word and a shape as well as a hue. The page is readable with colour vision differences and in greyscale print.</span></li>
+    </ul>
+  </section>
+
+  <!-- ================= EDITOR ================= -->
+  <section class="board">
+    <div class="board__head">
+      <p class="cap">2 · Status page editor</p>
+      <p class="board__route">web/app/(app)/status-pages/[pageId]/page.tsx · owner or admin</p>
+    </div>
+
+    <div class="frame">
+      <div class="app">
+        <aside class="side">
+          <div class="side__brand">
+            <div class="mark">V</div>
+            <div>
+              <b>Vantage</b>
+              <span class="cap">Acme Ltd</span>
+            </div>
+          </div>
+          <nav class="side__nav">
+            <div class="navgrp">
+              <p class="cap">Fleet</p>
+              <ul>
+                <li><a href="#"><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5"><rect x="2" y="3" width="12" height="4" rx="1"/><rect x="2" y="9" width="12" height="4" rx="1"/></svg>Servers</a></li>
+                <li><a href="#"><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5"><rect x="2.5" y="2.5" width="11" height="11" rx="1.5"/><path d="M6 6h4v4H6z"/></svg>Workloads</a></li>
+                <li><a href="#"><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"><path d="M1.5 8.5h3l2-4 3 7 2-3h3"/></svg>Monitors</a></li>
+              </ul>
+            </div>
+            <div class="navgrp">
+              <p class="cap">Access</p>
+              <ul>
+                <li><a href="#"><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5"><circle cx="5.5" cy="8" r="3"/><path d="M8.5 8h6M12 8v2.5"/></svg>SSH Keys</a></li>
+                <li><a href="#"><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5"><rect x="3" y="7" width="10" height="6.5" rx="1.5"/><path d="M5.5 7V5a2.5 2.5 0 015 0v2"/></svg>Secrets</a></li>
+              </ul>
+            </div>
+            <div class="navgrp">
+              <p class="cap">Instance</p>
+              <ul>
+                <li><a href="#" class="on"><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5"><rect x="2" y="3" width="12" height="10" rx="1.5"/><path d="M4.5 10.5v-2M8 10.5v-4M11.5 10.5v-3" stroke-linecap="round"/></svg>Status Pages</a></li>
+                <li><a href="#"><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M3 3h10v10H3z"/><path d="M5.5 6.5h5M5.5 9.5h3"/></svg>Audit Log</a></li>
+                <li><a href="#"><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5"><circle cx="8" cy="8" r="2.2"/><path d="M8 1.8v1.6M8 12.6v1.6M14.2 8h-1.6M3.4 8H1.8"/></svg>Settings</a></li>
+              </ul>
+            </div>
+          </nav>
+        </aside>
+
+        <div class="main">
+          <a class="back" href="#">
+            <svg class="glyph" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><path d="M9.5 3.5L5 8l4.5 4.5"/></svg>
+            All status pages
+          </a>
+
+          <div class="phead">
+            <div>
+              <h2>Acme Platform Status</h2>
+              <div class="record">
+                <code>acme.vantage.example.com/status/api</code>
+                <button class="copy" type="button">copy</button>
+              </div>
+            </div>
+            <div class="acts">
+              <a class="btn" href="#">
+                <svg class="glyph" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"><path d="M6.5 3.5h6v6M12.5 3.5L7 9"/><path d="M11 10.5v2h-8v-8h2"/></svg>
+                View page
+              </a>
+              <button class="btn btn--p" type="button">Save changes</button>
+            </div>
+          </div>
+
+          <div class="panel">
+            <div class="panel__head">
+              <div>
+                <h3>Details</h3>
+                <p>What visitors see at the top of the page.</p>
+              </div>
+              <span class="pill pill--live">published</span>
+            </div>
+            <div class="panel__body">
+              <div class="toggle">
+                <div>
+                  <b>Published</b>
+                  <p>Anyone with the link can read this page. Unpublished pages return not found, so you can compose before announcing.</p>
+                </div>
+                <button class="sw" type="button" role="switch" aria-checked="true" aria-label="Published"></button>
+              </div>
+              <div class="fields">
+                <div class="field">
+                  <label for="f-title">Title</label>
+                  <input class="in" id="f-title" value="Acme Platform Status">
+                </div>
+                <div class="field">
+                  <label for="f-id">Page address</label>
+                  <input class="in in--mono" id="f-id" value="api" disabled>
+                  <span class="hint">Fixed once created — the link is already out there.</span>
+                </div>
+                <div class="field">
+                  <label for="f-desc">Description</label>
+                  <input class="in" id="f-desc" value="Live availability for the Acme API and dashboard.">
+                </div>
+                <div class="field">
+                  <label for="f-logo">Logo URL</label>
+                  <input class="in in--mono" id="f-logo" placeholder="https://acme.example.com/logo.svg">
+                </div>
+              </div>
+              <div class="field">
+                <label for="f-ban">Notice</label>
+                <input class="in" id="f-ban" value="Europe region only. US and APAC are unaffected. Follow this page for updates.">
+                <span class="hint">Shown above everything else. Clear it to remove the notice.</span>
+              </div>
+            </div>
+          </div>
+
+          <div class="panel">
+            <div class="panel__head">
+              <div>
+                <h3>Components</h3>
+                <p>Monitors grouped for the public page. Grouping here is separate from the groups on Monitors.</p>
+              </div>
+              <button class="btn" type="button">Add section</button>
+            </div>
+            <div class="panel__body">
+
+              <div class="sect">
+                <div class="sect__head">
+                  <input class="in" value="API" aria-label="Section name">
+                  <button class="rm" type="button">remove section</button>
+                </div>
+                <div class="entry">
+                  <div class="entry__mon">
+                    <b>prod-api-eu-health</b>
+                    <span>http · every 30s</span>
+                  </div>
+                  <input class="in" value="Public API" aria-label="Public name for prod-api-eu-health">
+                  <button class="rm" type="button">remove</button>
+                </div>
+                <div class="entry">
+                  <div class="entry__mon">
+                    <b>hooks-dispatch-probe</b>
+                    <span>http · every 60s</span>
+                  </div>
+                  <input class="in" value="Webhook delivery" aria-label="Public name for hooks-dispatch-probe">
+                  <button class="rm" type="button">remove</button>
+                </div>
+                <div class="adds"><button class="btn" type="button">Add monitor</button></div>
+              </div>
+
+              <div class="sect">
+                <div class="sect__head">
+                  <input class="in" value="Data" aria-label="Section name">
+                  <button class="rm" type="button">remove section</button>
+                </div>
+                <div class="entry">
+                  <div class="entry__mon">
+                    <b>pg-primary-10-0-0-5</b>
+                    <span>tcp · every 30s</span>
+                  </div>
+                  <input class="in" value="Primary database" aria-label="Public name for pg-primary-10-0-0-5">
+                  <button class="rm" type="button">remove</button>
+                </div>
+                <div class="entry">
+                  <div class="entry__mon">
+                    <b>minio-gw</b>
+                    <span>http · every 60s</span>
+                  </div>
+                  <input class="in" placeholder="minio-gw" aria-label="Public name for minio-gw">
+                  <button class="rm" type="button">remove</button>
+                </div>
+                <div class="adds"><button class="btn" type="button">Add monitor</button></div>
+              </div>
+
+            </div>
+          </div>
+
+          <div class="panel">
+            <div class="panel__head">
+              <div>
+                <h3>Incidents</h3>
+                <p>Written by you. Outages Vantage detects appear on the page automatically.</p>
+              </div>
+              <div class="acts">
+                <button class="btn" type="button">Schedule maintenance</button>
+                <button class="btn btn--p" type="button">Open incident</button>
+              </div>
+            </div>
+            <div>
+              <div class="inc-row">
+                <div class="inc-row__l">
+                  <b>Elevated error rates on database writes</b>
+                  <span>Opened 09:12 UTC · 3 updates · affects Primary database, Public API</span>
+                </div>
+                <div class="inc-row__r">
+                  <span class="pill pill--mon">monitoring</span>
+                  <button class="btn" type="button">Post update</button>
+                </div>
+              </div>
+              <div class="inc-row">
+                <div class="inc-row__l">
+                  <b>Object storage capacity upgrade</b>
+                  <span>31 Aug, 02:00–04:00 UTC · affects Object storage</span>
+                </div>
+                <div class="inc-row__r">
+                  <span class="pill pill--sch">scheduled</span>
+                  <button class="btn" type="button">Edit</button>
+                </div>
+              </div>
+              <div class="inc-row">
+                <div class="inc-row__l">
+                  <b>Slow dashboard loads in Europe</b>
+                  <span>17 Jul · resolved after 1h 35m · affects Dashboard</span>
+                </div>
+                <div class="inc-row__r">
+                  <span class="pill pill--res">resolved</span>
+                  <button class="btn" type="button">Edit</button>
+                </div>
+              </div>
+            </div>
+          </div>
+
+        </div>
+      </div>
+    </div>
+
+    <ul class="notes">
+      <li><span class="k">Naming</span><span>The monitor's own identifier stays visible on the left; the <b>public name</b> is a separate field beside it. An empty field falls back to the identifier, which the placeholder shows — so publishing an internal name is always a visible choice.</span></li>
+      <li><span class="k">Address</span><span>The page address is fixed after creation and the record line carries the whole URL, click to copy. It is what gets pasted into a support article.</span></li>
+      <li><span class="k">Copy</span><span>Buttons name the outcome: <b>Open incident</b>, <b>Post update</b>, <b>Schedule maintenance</b> — the same words the public timeline then shows.</span></li>
+    </ul>
+  </section>
+
+</div>
+
+<script>
+  // 90 daily cells per component. Seeded rather than random so the mockup is
+  // stable between reloads and reviewers are looking at the same picture.
+  const PATTERNS = {
+    api:   { downs: [2, 22], maint: [], noData: 0 },
+    hooks: { downs: [], maint: [], noData: 0 },
+    dash:  { downs: [38], maint: [], noData: 0 },
+    db:    { downs: [0, 1, 12, 13, 47], maint: [], noData: 0 },
+    obj:   { downs: [61], maint: [0], noData: 0 },
+    new:   { downs: [], maint: [], noData: 61 }
+  };
+
+  document.querySelectorAll(".comp").forEach((comp) => {
+    const p = PATTERNS[comp.dataset.bar];
+    const bar = comp.querySelector(".bar");
+    const frag = document.createDocumentFragment();
+    for (let i = 89; i >= 0; i--) {
+      const cell = document.createElement("span");
+      let cls = "up";
+      if (i >= 90 - p.noData) cls = "none";
+      else if (p.maint.includes(i)) cls = "maint";
+      else if (p.downs.includes(i)) cls = "down";
+      cell.className = cls;
+      cell.title = cls === "none" ? "no data" : cls === "maint" ? "maintenance" : cls === "down" ? "outage" : "operational";
+      frag.appendChild(cell);
+    }
+    bar.appendChild(frag);
+  });
+</script>

docs/superpowers/specs/2026-07-20-fleet-inventory-design.md

@@ -1,142 +0,0 @@
-# Fleet Inventory — Design
-
-**Date:** 2026-07-20
-**Status:** Approved (design) — ready for implementation planning
-**Scope:** Fleet Inventory only. Server Workflows and SaaS/auth are separate sub-projects.
-
----
-
-## 1. Summary
-
-Each agent collects hardware/OS inventory about its host and reports it to the server, which stores the latest snapshot per server and surfaces it in the UI. Two cadences:
-
-- **Metrics (near-real-time):** CPU load/usage, RAM used/total, swap used/total — every **30s** (aligned with existing poll rhythm).
-- **Static inventory (slow):** disks, partitions and their usage, CPU model/cores, total RAM, OS details — every **15 min**.
-
-Transport: a **new unary gRPC `ReportInventory` RPC** (mirrors the existing `ReportUpdates` pattern). No streaming.
-
----
-
-## 2. Locked decisions
-
-| Topic | Decision |
-|-------|----------|
-| Transport | New `ReportInventory` unary RPC. |
-| Cadence | Metrics every 30s; static inventory every 15 min. One RPC carries both, but static fields are only populated on the 15-min tick (empty/omitted otherwise → server keeps prior static snapshot). |
-| Storage | Latest snapshot embedded on the `servers` document (`inventory` sub-doc). No history/time-series in v1. |
-| Collection | Pure-Go where practical (`/proc`, `gopsutil`-style). Agent already runs as root. |
-| Platform | Linux primary; Windows agent populates what it can, leaves the rest empty. |
-
----
-
-## 3. Data model
-
-Add an `Inventory` sub-document to the existing `Server` model (`server/internal/models/server.go`):
-
-```go
-type CPUInfo struct {
-	Model    string  `bson:"model,omitempty" json:"model,omitempty"`
-	Cores    int     `bson:"cores,omitempty" json:"cores,omitempty"`
-	UsagePct float64 `bson:"usage_pct" json:"usage_pct"`         // metrics tick
-	Load1    float64 `bson:"load1,omitempty" json:"load1,omitempty"`
-}
-
-type MemInfo struct {
-	TotalBytes uint64 `bson:"total_bytes" json:"total_bytes"`
-	UsedBytes  uint64 `bson:"used_bytes" json:"used_bytes"`       // metrics tick
-}
-
-type Partition struct {
-	Device     string `bson:"device" json:"device"`
-	Mountpoint string `bson:"mountpoint" json:"mountpoint"`
-	Fstype     string `bson:"fstype,omitempty" json:"fstype,omitempty"`
-	TotalBytes uint64 `bson:"total_bytes" json:"total_bytes"`
-	UsedBytes  uint64 `bson:"used_bytes" json:"used_bytes"`
-}
-
-type Inventory struct {
-	CPU            CPUInfo     `bson:"cpu" json:"cpu"`
-	Memory         MemInfo     `bson:"memory" json:"memory"`
-	SwapTotalBytes uint64      `bson:"swap_total_bytes" json:"swap_total_bytes"`
-	SwapUsedBytes  uint64      `bson:"swap_used_bytes" json:"swap_used_bytes"`
-	Partitions     []Partition `bson:"partitions,omitempty" json:"partitions,omitempty"`
-	Kernel         string      `bson:"kernel,omitempty" json:"kernel,omitempty"`
-	MetricsAt      *time.Time  `bson:"metrics_at,omitempty" json:"metrics_at,omitempty"`
-	StaticAt       *time.Time  `bson:"static_at,omitempty" json:"static_at,omitempty"`
-}
-```
-
-Add `Inventory *Inventory` field to `Server`.
-
-Server-side update rules:
-- Metrics fields (`cpu.usage_pct`, `cpu.load1`, `memory.used_bytes`, swap used) always updated + `metrics_at`.
-- Static fields (`cpu.model/cores`, `memory.total_bytes`, `partitions`, `kernel`, swap total) updated only when the report includes them (non-zero/non-empty) + `static_at`.
-
----
-
-## 4. gRPC protocol (`proto/vantage/v1/vantage.proto` + both `pb.go` files)
-
-```protobuf
-rpc ReportInventory(InventoryReport) returns (InventoryReportResponse);
-
-message InventoryReport {
-  string server_id    = 1;
-  string agent_token  = 2;
-  bool   include_static = 3; // true on the 15-min tick
-  CPUReport cpu       = 4;
-  MemReport memory    = 5;
-  uint64 swap_total   = 6;
-  uint64 swap_used    = 7;
-  repeated PartitionReport partitions = 8; // only when include_static
-  string kernel       = 9;                 // only when include_static
-}
-message CPUReport { string model = 1; int32 cores = 2; double usage_pct = 3; double load1 = 4; }
-message MemReport { uint64 total_bytes = 1; uint64 used_bytes = 2; }
-message PartitionReport { string device = 1; string mountpoint = 2; string fstype = 3; uint64 total_bytes = 4; uint64 used_bytes = 5; }
-message InventoryReportResponse {}
-```
-
-Hand-written JSON-codec structs added to `server/internal/grpc/pb/vantage.pb.go` and `agent/internal/grpc/pb/vantage.pb.go`, plus the RPC method wiring (service interface, client method, handler registration) mirroring `ReportUpdates`.
-
----
-
-## 5. Agent collection (`agent/internal/inventory/`)
-
-- `Collect(includeStatic bool) *pb.InventoryReport` — reads:
-  - CPU usage: sample `/proc/stat` delta; load from `/proc/loadavg`; model/cores from `/proc/cpuinfo` (static).
-  - Memory/swap: `/proc/meminfo`.
-  - Partitions: `/proc/mounts` filtered to real filesystems + `statfs` for total/used (static).
-  - Kernel: `uname` / `/proc/version` (static).
-  - Windows: best-effort via `wmic`/PS or leave empty.
-- Scheduler in the agent main loop: a 30s ticker calls `Collect(false)` and `ReportInventory`; every 30th tick (15 min) calls `Collect(true)`.
-- Reuse existing gRPC client; add `Client.ReportInventory(...)` like `ReportUpdates`.
-
-Prefer implementing the `/proc` readers directly (no new heavy deps) unless a `gopsutil` dependency is already vendored.
-
----
-
-## 6. Server handler + service
-
-- gRPC handler `ReportInventory` in `server/internal/grpc/server.go`: validate agent token (`ValidateAgentToken`), then call `services.StoreInventory(serverID, report)`.
-- `services.StoreInventory` (in `server/internal/services/inventory.go`): builds the `$set` per the update rules in §3 and `UpdateOne` on `servers`.
-
----
-
-## 7. Frontend
-
-Surface inventory on the existing server detail page (`web/app/servers/[id]/page.tsx`) — add an "Inventory" panel:
-- CPU usage gauge + model/cores, load.
-- RAM used/total bar, swap bar.
-- Partitions table: device, mount, fstype, used/total with a usage bar.
-- "Updated Xs ago" from `metrics_at`/`static_at`.
-
-Optionally add compact CPU/RAM badges to the servers list (`web/app/servers/page.tsx`). Reuse `@/components/ui` + Tailwind tokens. Poll the server detail query while the page is open (react-query `refetchInterval` ~30s) so metrics stay fresh.
-
----
-
-## 8. Out of scope
-
-- Time-series history / graphs (only latest snapshot stored).
-- Alerting thresholds on usage (settings/alerts is a separate concern).
-- Per-process / network / GPU inventory.
-- Tests (skipped, consistent with the Workflows iteration).

docs/superpowers/specs/2026-07-20-saas-auth-orgs-design.md

@@ -1,142 +0,0 @@
-# SaaS: Auth + Organizations — Design
-
-**Date:** 2026-07-20
-**Status:** Approved (design) — ready for implementation planning
-**Scope:** Local auth + organizations + per-org OIDC, and org-scoping of existing data. Billing/plan-limits explicitly deferred. Fleet Inventory and Server Workflows are separate sub-projects.
-
----
-
-## 1. Summary
-
-Turn Vantage from a single-admin, single global-OIDC tool into a multi-tenant app:
-
-1. **Replace** the global Authentik/env-based OIDC with **local email/password accounts** as the primary login.
-2. **Organizations** — every user belongs to an org; every domain object (servers, keys, secrets, assignments, workflows, steps, runs, audit) carries an `org_id` and all queries are scoped to the caller's org.
-3. **Per-org OpenID** — an org admin can configure their own OIDC provider (issuer/client id/secret); users in that org can then sign in through it.
-
-No billing, no seat/server limits this iteration (schema leaves room).
-
----
-
-## 2. Locked decisions
-
-| Topic | Decision |
-|-------|----------|
-| Primary auth | Local email + password (bcrypt). Replaces global Authentik. |
-| Org SSO | Per-org OIDC provider, configured by org admin, resolved dynamically at login. |
-| Isolation | `org_id` on every collection; every service query filtered by org. Enforced in the request layer via session→org. |
-| Roles | `owner`, `admin`, `member` (v1: owner/admin can manage users + org OIDC + all resources; member can use resources). Keep minimal. |
-| Bootstrapping | First-run creates the initial org + owner account (setup flow) when no users exist. |
-| Sessions | Keep existing Redis session store; session now carries `user_id`, `org_id`, `role`, `email`. |
-| Agent auth | Unchanged (per-server agent tokens). Servers gain `org_id`; agent RPCs resolve org from the server record. |
-
----
-
-## 3. Data model
-
-### `orgs`
-```json
-{ "_id":"ObjectId", "org_id":"uuid", "name":"Acme", "created_at":"ISODate" }
-```
-
-### `users`
-```json
-{
-  "_id":"ObjectId", "user_id":"uuid", "org_id":"uuid",
-  "email":"a@b.com", "password_hash":"bcrypt...", "role":"owner|admin|member",
-  "auth_source":"local|oidc", "created_at":"ISODate", "last_login":"ISODate|null"
-}
-```
-Unique index on `email` (global — email identifies the account and its org).
-
-### `org_oidc` (per-org provider config)
-```json
-{
-  "_id":"ObjectId", "org_id":"uuid",
-  "issuer":"https://id.acme.com", "client_id":"...",
-  "client_secret_enc":"AES...",         // encrypted with existing crypto.go
-  "redirect_url":"https://vantage.../auth/oidc/callback",
-  "enabled": true, "updated_at":"ISODate"
-}
-```
-
-### Existing collections — add `org_id`
-`servers`, `keys`, `assignments`, `secrets`, `workflows`, `workflow_steps`, `workflow_runs`, `audit` each gain `org_id string`. A **migration** backfills all existing documents into a default org (see §7).
-
----
-
-## 4. Auth flows
-
-### Local
-- `POST /auth/register` — only allowed during first-run bootstrap (creates org + owner) OR by an org admin inviting a user (see below). Not open self-serve.
-- `POST /auth/login` — email + password → verify bcrypt → create session with `{user_id, org_id, role, email}`.
-- `POST /auth/logout` — destroy session.
-- `GET /auth/me` — returns current user + org.
-
-### Org-admin user management
-- `GET /api/org/users` / `POST /api/org/users` (create local user in caller's org) / `PUT /api/org/users/:id/role` / `DELETE /api/org/users/:id`.
-
-### Per-org OIDC
-- `GET/PUT /api/org/oidc` — read/save the caller org's provider config (admin only). Secret stored encrypted.
-- `GET /auth/oidc/start?org=<org_id or slug>` — look up org's `org_oidc`, build the OIDC provider on demand (cache per org), redirect to authorize.
-- `GET /auth/oidc/callback` — exchange code, match/provision the user by email **within that org**, create session.
-  - If the email exists in the org → log in. If not → provision a `member` with `auth_source=oidc` (org admin can promote). Reject if email belongs to a different org.
-
-### First-run bootstrap
-- `GET /auth/bootstrap-status` → `{ needs_setup: bool }` (true when `users` is empty).
-- Setup page collects org name + owner email/password → creates org + owner → session.
-
----
-
-## 5. Request scoping
-
-- `auth.Middleware` already loads the session; extend `Session` to include `OrgID`, `UserID`, `Role`. Add helper `auth.OrgID(c) string`.
-- **Every service function that reads/writes a scoped collection takes an `orgID` argument** and adds `"org_id": orgID` to its filter and on insert. Handlers pass `auth.OrgID(c)`.
-- Add a `requireRole(role)` gin middleware for admin-only routes (org user mgmt, org OIDC).
-- Agent-facing gRPC: resolve `org_id` from the `servers` record (already tied to `server_id`); inventory/keys/sync operate on that org implicitly.
-
----
-
-## 6. Removing global Authentik
-
-- Delete/retire env-driven `InitOIDC` global provider (`OIDC_ISSUER` etc.). Keep the `go-oidc`/`oauth2` machinery but move it behind the per-org resolver.
-- `authEnabled` global replaced by "auth always on" (there is always local auth). Update `middleware.go` accordingly (no more `if !authEnabled { next }` bypass — except the bootstrap endpoints and login/register which are unauthenticated).
-- Login page (`web/app/login` or existing) offers: email/password form + "Sign in with your organization's SSO" (enter org, redirect to `/auth/oidc/start`).
-
----
-
-## 7. Migration
-
-One-shot migration run at startup (idempotent):
-1. If `orgs` is empty AND `servers`/`keys`/etc. contain documents without `org_id`: create a **default org** ("Default").
-2. Set `org_id = <default>` on all existing `servers`, `keys`, `assignments`, `secrets`, `workflows`, `workflow_steps`, `workflow_runs`, `audit` documents missing it.
-3. If `OIDC_ISSUER` env was set previously and an admin email is known, optionally seed an owner user (documented manual step) — otherwise first-run bootstrap handles owner creation.
-Guard with a marker (e.g. a `migrations` collection entry) so it runs once.
-
----
-
-## 8. Frontend
-
-- **Login/Setup:** `web/app/login/page.tsx` (email/password + org SSO entry) and `web/app/setup/page.tsx` (first-run). Redirect logic based on `bootstrap-status` and `auth/me`.
-- **Org settings:** `web/app/settings/org/` — members list + invite/create user + role management; OIDC provider form (issuer/client id/secret/enabled).
-- Existing pages unchanged functionally but now implicitly org-scoped by the backend. Show current org + user in the sidebar/header.
-
----
-
-## 9. Security
-
-- Passwords: bcrypt (cost ≥ 12). Never returned.
-- Org OIDC client secret encrypted at rest (reuse `services/crypto.go` AES).
-- Cross-org access prevented at the service layer (org_id in every filter) — the primary isolation boundary. Handlers must never accept an `org_id` from the client; always derive from session.
-- OIDC callback must bind the returned identity to the org that initiated the flow (state carries org_id) to prevent org-mixing.
-- Role checks on all org-admin mutations.
-
----
-
-## 10. Out of scope
-
-- Billing, plans, seat/server limits.
-- Cross-org resource sharing, org switching for a single user (one user = one org in v1).
-- SCIM / directory sync, SAML.
-- Email delivery for invites (create-user sets a password or invite token; email sending deferred — document as manual/console output).
-- Tests (skipped, consistent with prior iterations).

docs/superpowers/specs/2026-08-13-windows-agent-parity-design.md

@@ -0,0 +1,297 @@
+# Windows agent parity: OS updates and workloads
+
+Date: 2026-08-13
+
+## Goal
+
+Bring the Windows agent up to the Linux agent on two subsystems: OS update
+check/apply, and the workload registry (collection, control, logs). Everything
+else about the Windows agent stays as it is.
+
+Out of scope, deliberately:
+
+- **Package inventory and CVE findings.** `trivy-db` carries no Windows feed, so
+  a Windows finding needs a different source, a different matcher and a
+  different version comparison. That is its own project, and until it exists a
+  Windows host correctly reports `status: unsupported` rather than "0 findings".
+- **SSH key management on Windows.** `administrators_authorized_keys` is a real
+  possibility but a separate decision.
+- **winget.** Third-party app upgrades are a different question from OS
+  patching, and winget is absent on Server Core and older builds.
+
+## Current state
+
+The Windows agent registers, heartbeats, reports inventory, runs workflow steps
+through PowerShell, relays console connections and self-updates via MSI. Four
+gates stop it doing more:
+
+| Gate | Location |
+| --- | --- |
+| `runtime.GOOS != "linux"` early return | `agent/internal/workloads/workloads.go`, `agent/internal/sync/workloads.go` (twice) |
+| package-manager detection finds nothing | `agent/internal/updates/updates.go` (`detectPM`) |
+| hard error | `agent/internal/packages/packages.go` (out of scope here) |
+| `authorized_keys` write skipped | `agent/internal/sync/sync.go` (out of scope here) |
+
+## Approach
+
+The platform split moves into the agent, expressed as build tags following the
+existing `inventory/collect_linux.go` / `collect_windows.go` /
+`collect_other.go` precedent. The control plane stays OS-blind: `ReportWorkloads`,
+`ControlWorkload`, `WorkloadLogs` and `ApplyUpdates` need no changes at all,
+because a Windows service is reported as the same `unit` kind a systemd service
+is.
+
+Build tags rather than `runtime.GOOS` switches so PowerShell command strings do
+not ship in the Linux binary, and so a platform left unimplemented is a compile
+error rather than a silent no-op at runtime.
+
+## Updates
+
+### Layout
+
+```
+agent/internal/updates/
+  updates.go          # PackageUpdate; CheckAvailable/ApplyAll declared once
+  updates_linux.go    # existing detectPM, checkApt/DnfYum/Pacman/Zypper/Apk, ApplyAll
+  updates_windows.go  # Windows Update COM, driven through PowerShell
+  updates_other.go    # //go:build !linux && !windows — no-ops
+```
+
+`updates_other.go` carries the build constraint for the same reason
+`inventory/collect_other.go` does: `_other` is not a GOOS suffix, so without the
+constraint the file compiles everywhere and collides.
+
+### Checking
+
+One PowerShell invocation, `-NoProfile -NonInteractive`, emitting JSON:
+
+```powershell
+$searcher = (New-Object -ComObject Microsoft.Update.Session).CreateUpdateSearcher()
+$result = $searcher.Search("IsInstalled=0 and Type='Software' and IsHidden=0")
+```
+
+The Windows Update COM API is used rather than the `PSWindowsUpdate` module
+because it is present on every supported Windows, needs no PowerShell Gallery
+install, and works unchanged against a WSUS server on an air-gapped fleet. The
+agent runs as `LocalSystem`, which has the rights the API requires.
+
+Each result maps to a `PackageUpdate`:
+
+| Field | Value |
+| --- | --- |
+| `Name` | the update Title |
+| `CurrentVersion` | empty |
+| `NewVersion` | the KB article ID, e.g. `KB5034123` |
+
+`CurrentVersion` is empty because a Windows update is not a version bump of a
+named package, and inventing a current version would put a wrong string in front
+of an operator. The KB ID goes in `NewVersion` because it is the identifier
+people actually search for.
+
+Timeout: 10 minutes. The first search after a boot contacts Microsoft Update and
+is routinely slow.
+
+### Applying
+
+The same COM session: `CreateUpdateDownloader` then `CreateUpdateInstaller`,
+over the updates returned by the search above, skipping any that require user
+input. EULAs are accepted programmatically; an update whose EULA cannot be
+accepted is skipped rather than failing the batch.
+
+The operation fails when the installer's `ResultCode` is not 2 (succeeded) or 3
+(succeeded with errors).
+
+Timeout: 60 minutes. A patch-Tuesday cumulative genuinely takes that long, and
+the Linux path's existing 5-minute cap is already tight.
+
+**The agent never reboots the host.** A control plane silently restarting a
+production server is unrecoverable from the UI, and the reboot is a decision a
+person or a workflow makes. Instead the need for one is reported.
+
+### Reboot required
+
+A new field `reboot_required` on `InventoryReport`, added to
+`proto/vantage/v1/vantage.proto` and to both hand-written `pb` copies
+(`agent/internal/grpc/pb`, `server/internal/grpc/pb`) in the same commit.
+
+It travels on the inventory report rather than the update report because it is a
+host property like the kernel version, and it is set on the **static** snapshot
+only — every 15 minutes rather than every 30 seconds. A host rebooted by hand
+clears the flag in a quarter of an hour instead of showing it for up to a full
+one, and the detection costs a PowerShell process on Windows, which is not
+something to spawn twice a minute forever.
+
+It is set in `agentsync.runInventory`, not inside the `inventory` package, so
+`inventory` gains no dependency on `updates`.
+
+Both platforms set it, since parity is free here:
+
+- Linux: `/var/run/reboot-required` exists, or `dnf needs-restarting -r` exits
+  non-zero.
+- Windows: the `Microsoft.Update.SystemInfo` COM object's `RebootRequired`
+  property, falling back to the pending-reboot registry keys
+  (`Component Based Servicing\RebootPending`,
+  `WindowsUpdate\Auto Update\RebootRequired`,
+  `Session Manager\PendingFileRenameOperations`).
+
+`services.ReportInventory` stores it on `servers.inventory`.
+
+## Workloads
+
+### Layout
+
+```
+agent/internal/workloads/
+  workloads.go         # Result, Collect, Hash — Collect calls collectUnits
+  docker.go            # unchanged, shared: shells to the docker binary
+  systemd_linux.go     # was systemd.go
+  services_windows.go  # new: Win32_Service collection
+  control.go           # shared validation; platform halves split out
+  control_linux.go     # docker/systemctl, /proc/self/cgroup own-container check
+  control_windows.go   # Start/Stop/Restart-Service, VantageAgent protection
+  logs.go              # shared: capLog, MaxLogLines, MaxLogBytes
+  logs_linux.go        # docker logs / journalctl
+  logs_windows.go      # docker logs / Get-WinEvent
+```
+
+`Collect` loses its `runtime.GOOS != "linux"` return and calls
+`collectUnits(ctx)`, which is the systemd collector on Linux and the service
+collector on Windows. `runWorkloads` and `reportWorkloads` in
+`agent/internal/sync/workloads.go` lose all three of their platform returns.
+
+`docker.go` stays shared and ungated. It shells to the `docker` binary, which
+behaves identically on Windows, so a Docker Desktop or Mirantis host reports its
+containers with no new code. `DockerOK` / `DockerError` keep their existing
+three-state meaning: not installed (the common case, not a fault), installed but
+not responding, and running nothing.
+
+### Collecting Windows services
+
+`Get-CimInstance Win32_Service` converted to JSON — not `Get-Service`, which
+exposes neither `PathName` nor `StartMode`, and the filter needs both.
+
+A service is reported when its executable does **not** resolve under
+`%SystemRoot%\System32`, and it is running, failed, or has `StartMode=Auto`
+while stopped. This mirrors the systemd collector's intent: show what an
+operator installed, and show what is meant to be up but is not.
+
+Path parsing strips surrounding quotes and trailing arguments before the
+`%SystemRoot%` comparison. `"C:\Program Files\X\x.exe" -service` is one path
+with one argument, and splitting naively on whitespace misfiles a substantial
+share of a real fleet.
+
+Field mapping:
+
+| Workload field | Source |
+| --- | --- |
+| `Kind` | `"unit"` |
+| `ID` | `Name` (the service name) |
+| `Name` | `DisplayName` |
+| `State` | `running` / `stopped` / `failed`, from `State` plus `ExitCode` |
+| `Health`, `Image`, `Stack`, `Ports`, `Restarts` | unset |
+
+`Kind: "unit"` and the existing `systemd_ok` / `systemd_error` fields are reused
+rather than a `service` kind and `services_ok` fields being added. That would
+cost a proto change, both pb copies, the server model, the service layer and the
+web client, and would teach every existing consumer a second kind — to describe
+the same thing. The naming is corrected where it is read, in the UI, which knows
+the server's OS.
+
+`State` values match the ones the UI already colours, so no web change is needed
+for the rows themselves.
+
+### Protection
+
+The protected set stays computed and enforced agent-side, as it is on Linux: the
+control plane may name a target, but the agent decides what it will do to
+itself.
+
+On Windows the protected workload is the `VantageAgent` service — the NSSM
+service name written by `installer/setup.ps1` — matched case-insensitively,
+because Windows service names are. `detectOwnContainer` and its
+`/proc/self/cgroup` read move to `control_linux.go`; the Windows build returns
+no own-container ID.
+
+`ErrProtected` still surfaces as HTTP 409 from the API, and the reported
+`Protected` flag remains a courtesy that greys the button rather than the
+boundary.
+
+### Control
+
+`Start-Service`, `Stop-Service -Force`, `Restart-Service -Force`, under the same
+90-second `controlTimeout`, with the error text taken from PowerShell's stderr.
+
+`sc.exe` is avoided because it returns before the operation completes, which
+turns a timeout into a false success. `-Force` is required because
+`Stop-Service` without it refuses when other services depend on the target, and
+that refusal reads to an operator as a silent no-op.
+
+### Logs
+
+`Get-WinEvent` with a filter hashtable over the `System` and `Application` logs,
+provider names matching the service name, its display name, and
+`Service Control Manager`, newest first, capped by the requested tail.
+
+Each event is formatted as `<ISO 8601 timestamp>  <Level>  <Message>`, which is
+the same shape `journalctl --output=short-iso` produces, so the log dialog needs
+no per-platform rendering.
+
+Service Control Manager logs every service on the host under one provider, so
+its events are filtered client-side to those naming the target service.
+
+`capLog` is shared and unchanged: 500 lines and 256KB, whichever binds first,
+trimmed from the front. There is still no follow mode.
+
+An empty result returns an empty string and no error. A service that has logged
+nothing is normal, and an error there would read as a broken feature.
+
+## Server and web
+
+The server changes in one place: `services.ReportInventory` persists
+`reboot_required`.
+
+The web changes in three, all keyed on the same `os_info` test
+`MaintenanceTab.tsx` already uses (`server.os_info?.toLowerCase().includes("windows")`)
+rather than on `os_type`. `os_type` is stored and serialised but unread by
+`web/` today, and introducing a second Windows test in the same component is how
+the two come to disagree. `WorkloadList` takes the result as a prop, since it
+receives only a `serverId`:
+
+1. `web/components/workloads/WorkloadList.tsx` — takes an `isWindows` prop from
+   the server detail page, and the systemd status lines become
+   platform-worded. On Windows the error line reads "Windows services could not
+   be read" and the "systemd is not in use on this server" line is not rendered
+   at all. The empty-state line drops "on Linux only". The Docker lines are
+   unchanged.
+2. Server detail — a `Reboot required` pill beside the update count when the
+   flag is set, placed with the update panel because that is what caused it.
+3. The Updates panel's Windows copy describes a list of KB articles rather than
+   package upgrades, since `current_version` is empty on that platform.
+
+## Testing
+
+The Windows collectors are, in substance, parsers of PowerShell output. Parsing
+is separated from invocation and table-tested against captured real output. The
+`agent` module has no tests at all today, so these are the first — they live
+beside the parsers as ordinary `_test.go` files, run with `go test ./...` from
+`agent/`, and need no new dependency:
+
+- `Win32_Service` JSON, including a quoted path with arguments, a
+  `%SystemRoot%\System32` service that must be filtered out, a stopped
+  `StartMode=Auto` service that must be kept, and a failed service with a
+  non-zero `ExitCode`.
+- Update searcher JSON, including an update with no KB ID.
+- `Get-WinEvent` JSON, including a Service Control Manager event for another
+  service that must be filtered out.
+- Pending-reboot detection from registry key presence.
+
+`capLog` and `Hash` are unchanged and gain no tests.
+
+The invocation halves are verified by hand on a Windows host: check, apply,
+service start/stop/restart, a protected refusal on `VantageAgent`, and logs on
+both a chatty service and a silent one.
+
+`GOOS=windows go build ./...` and `GOOS=linux go build ./...` both belong in the
+implementation plan as explicit steps — a build-tag split is exactly the change
+that compiles on the machine you are sitting at and nowhere else. CI already
+cross-builds the agent on release, so no workflow change is needed.

docs/superpowers/specs/2026-08-24-status-pages-design.md

@@ -0,0 +1,286 @@
+# Public status pages
+
+Date: 2026-08-24
+
+## Goal
+
+Let an operator publish one or more public status pages from a Vantage
+instance, at `<slug>.vantage.<tld>/status/<page-id>`, showing the state of any
+monitors they choose, plus incidents and maintenance windows they author by
+hand. The pages are completely public: no session, no token, no login.
+
+Out of scope, deliberately:
+
+- **Custom domains** (`status.customer.com`). Needs certificate provisioning and
+  a host-to-page lookup that bypasses `hostSlug` entirely. Its own sub-project.
+- **Per-page themes.** `web/` is locked dark by design and a public page is not
+  the place to break that.
+- **Subscriber notifications.** Email or webhook on incident updates is a
+  notification subsystem, and one already exists for monitors; wiring the two
+  together is a separate decision.
+- **SLA reporting.** Uptime percentages are shown; contractual SLA calculation
+  with credits and exclusions is a different product.
+
+## Current state
+
+Everything needed to draw a status page already exists and is already scoped by
+instance:
+
+| Data | Where |
+| --- | --- |
+| Monitor identity and live state | `models.Monitor`, `Monitor.State` |
+| Outage records | `models.Incident`, opened when a monitor flips down |
+| Hourly uptime history | `models.Rollup` (`monitor_rollups`) |
+| Sub-hour history | `models.MonitorSample`, TTL-expired |
+| Instance from hostname | `auth.InstanceFromHost`, 60s cached |
+
+Three things do not exist: any concept of a page, any operator-authored
+incident, and any unauthenticated read path. The third is the constraint that
+shapes the rest — every route under `/api` carries `auth.Middleware`,
+`RequireScopes`, `RateLimitTokens` and `RequireActiveLicense` by virtue of where
+it is mounted, and `AssertScopeMapComplete` fails boot on an `/api` route with
+no scope entry.
+
+## Approach
+
+Two new collections hold the page and the authored incidents. A single
+assembly function reads them alongside the existing monitor data and emits a
+purpose-built public struct. The public route is mounted outside `/api`, is
+cached in Redis, and is rate limited per client address.
+
+The redaction boundary is the assembly function, and it is the security
+property of this whole feature.
+
+## Data model
+
+Both collections carry `instance_id` and both must be added to
+`services.ScopedCollections`, or their rows outlive a deleted instance.
+
+### `status_pages`
+
+One document per page. It is read whole, always, so its structure is embedded
+rather than joined: one page is one Mongo read is one cache fill.
+
+```
+_id, instance_id
+page_id        // operator-chosen slug, [a-z0-9-], 3-40 chars
+title, description, logo_url
+published      bool
+banner         { enabled, level, text }
+sections       [ { name, entries: [ { monitor_id, display_name } ] } ]
+created_at, updated_at
+```
+
+Unique index on `(instance_id, page_id)`. The slug is operator-chosen rather
+than random because it is a URL handed to customers and printed on support
+pages; a random identifier would be unguessable and unmemorable in equal
+measure.
+
+`published` exists so a page can be composed before anyone sees it. An
+unpublished page answers the same 404 as a page that does not exist — a
+distinct 403 would confirm it exists.
+
+Sections are page-local and unrelated to `Monitor.Group`, which is a display
+label on the authenticated monitors list. One monitor may appear under "API" on
+the customer page and "Edge" on the partner page, under two different display
+names. That is the point of the override: a monitor's internal name is often
+not a name you want published.
+
+The banner is three fields on the page rather than a collection, because it is
+one string with no lifecycle.
+
+### `status_incidents`
+
+Manual incidents and maintenance windows share one shape, because they share a
+timeline, an impact and a set of affected components; splitting them into two
+collections would duplicate all three.
+
+```
+_id, instance_id, incident_id
+page_ids           []string   // which pages show it
+kind               "incident" | "maintenance"
+title
+impact             // none | minor | major | critical
+affected_monitors  []string   // monitor_ids
+status             // incident:    investigating | identified | monitoring | resolved
+                   // maintenance: scheduled | in_progress | completed
+scheduled_start, scheduled_end   // maintenance only
+updates            [ { at, status, body, author } ]
+started_at, resolved_at, created_at, updated_at
+```
+
+Updates are embedded for the same reason sections are: they are few, and they
+are never read apart from their incident.
+
+`page_ids` is explicit rather than derived from `affected_monitors`. Deriving it
+would be less to fill in, but adding a monitor to a page later would
+retroactively republish old incidents to a new audience. An operator publishing
+to customers chooses that audience.
+
+### Auto-incidents are derived, never copied
+
+The existing `incidents` collection remains the only writer for
+monitor-detected outages. The public snapshot derives them at assembly time:
+filter to the monitors on the page, last 90 days, render as display name, start,
+end and duration.
+
+`Incident.Cause` is dropped. It is where `dial tcp 10.0.0.5:5432: connect
+refused` lives.
+
+Copying auto-incidents into `status_incidents` would be a second writer for the
+same fact, arriving by a different route with its own opportunity to disagree —
+the same argument that keeps `RefreshWorkloadsCmd` from returning workloads
+inline.
+
+### Maintenance does not rewrite uptime
+
+During a maintenance window, affected components render as "under maintenance"
+rather than down. The uptime percentage and the history bar still come from the
+rollups, unmodified.
+
+Rollups are the durable record. Bending them so a page looks better is a lie
+pointed the other way, and the operator who later asks "what was our actual
+availability" gets an answer that was edited for publication.
+
+## The redaction boundary
+
+`services.BuildStatusSnapshot(instanceID, pageID)` is the only function that
+reads `monitors`, `incidents`, `monitor_rollups` and `status_incidents` on
+behalf of an anonymous caller, and it emits a purpose-built struct.
+
+**`models.Monitor` is never marshalled to a public caller.** Target URL, host,
+port, method, keyword, `state.message`, `state.cert_expiry_at` and
+`channel_ids` all stay behind the boundary. A field added to `Monitor` next year
+is private by default rather than published by accident.
+
+What the snapshot contains, per entry: display name, current status, uptime
+percentage over the last 90 days, and a 90-day history bar of one cell per day.
+A cell is up, down, under maintenance, or no-data — `no-data` for days before
+the monitor existed, which is a distinct thing from a day it was down. No
+latency, no addresses, no failure text.
+
+## Public read path
+
+```
+GET /public/status/:pageId
+```
+
+Mounted on the gin root, not under `apiGroup`. Putting it under `/api` would
+require exempting it from authentication, scope enforcement, token rate
+limiting and the licence gate — four holes, each one something a later change
+can widen. Outside `/api` it needs none of them.
+
+The instance is resolved from the request host through `auth.InstanceFromHost`.
+A host with no instance label, an unknown slug, an unknown page and an
+unpublished page all answer **404**, identically.
+
+### The feature gate answers 200, not 403
+
+Status pages are gated by a new `license.FeatureStatusPages = "status_pages"`,
+on both the authoring routes and the public read.
+
+The public side checks inline rather than through `RequireFeature`, which
+aborts with a 403 JSON body. A public page needs to render an explanation:
+
+```json
+{ "available": false, "reason": "feature_unavailable", "title": "Acme Status" }
+```
+
+`reason` is `feature_unavailable` when the tier does not include the feature and
+`licence_inactive` when the licence has lapsed. The title is included so the
+page does not look broken; nothing else is.
+
+**This is not only a server change.** The feature must be added to admin's
+`plans` rows per `(deployment, tier)`, or every instance reads it as absent and
+the feature ships dark.
+
+### Cache
+
+Redis key `vantage:status:<instance_id>:<page_id>` holds the assembled JSON with
+a 30-second TTL. N visitors cost one Mongo read regardless of traffic.
+
+Authoring writes delete the key, so an operator posting an incident update sees
+it immediately rather than wondering for half a minute whether it saved.
+
+Redis rather than Next ISR because with `replicaCount > 1` each `web` pod would
+cache separately and two visitors would see different states during an incident.
+
+### Rate limit
+
+Per client address, one-minute fixed window, 120 requests, 429 with
+`Retry-After` — the same shape as `RateLimitTokens`, including its most
+important property: **when Redis is unavailable, allow rather than deny.** A
+status page must survive the outage it exists to report.
+
+### Trusted proxies
+
+Nothing calls `r.SetTrustedProxies`, so gin trusts every proxy and
+`c.ClientIP()` takes `X-Forwarded-For` verbatim. That is spoofable per request,
+which makes a per-address limiter decorative.
+
+This has not mattered so far because `ClientIP()` is only used for audit
+strings. It matters now, so this work adds a trusted-proxy configuration and
+sets it at boot. Without it the rate limit is theatre.
+
+## Authoring API
+
+Under `/api`, owner or admin, behind `RequireFeature("status_pages")`, every
+mutation audited:
+
+```
+GET,POST        /status-pages
+GET,PUT,DELETE  /status-pages/:pageId
+GET,POST        /status-pages/:pageId/incidents
+PUT,DELETE      /status-pages/:pageId/incidents/:incidentId
+POST            /status-pages/:pageId/incidents/:incidentId/updates
+```
+
+This adds a ninth scope resource, `status:read` and `status:write`. The entries
+are required, not optional: `AssertScopeMapComplete` fails boot on an `/api`
+route with no scope entry, which is exactly the safeguard working.
+
+Handlers need `@…` annotations and `openapi.json` must be regenerated and
+committed — `server-deploy.yml` runs `git diff --exit-code` against the
+committed copy, so a handler whose annotation drifted fails CI.
+
+## Frontend
+
+`web/app/status/[pageId]/page.tsx`, **outside the `(app)` route group**, so it
+inherits no sidebar, no session fetch and no auth redirect. Server-rendered
+against the Go endpoint, with a client refresh every 60 seconds.
+
+`web/next.config.ts` gains a `/public/:path*` rewrite so that client refresh
+reaches the server.
+
+The page stays dark, like the rest of `web/`, and carries no hex values — the
+existing token palette covers every state it needs.
+
+Authoring UI at `/status-pages` inside `(app)`, in the **Instance** sidebar
+group. It is `adminOnly`, and since the whole group is, a member sees the group
+disappear entirely rather than a labelled section with nothing under it.
+
+## Testing
+
+The snapshot tests are the ones that matter, because they are the redaction
+boundary made executable:
+
+- `BuildStatusSnapshot` output contains no target URL or host, no
+  `state.message`, no `incident.cause`, no `channel_ids`, no latency.
+- A monitor on no page never appears in any page's snapshot.
+- An unpublished page and an unknown page both 404.
+- Feature absent and licence inactive both return 200 with `available: false`
+  and the matching `reason`.
+- A cache hit performs no Mongo read; an authoring write invalidates the key.
+- Slug validation: character set, length, uniqueness within an instance.
+- Maintenance window renders the component as under maintenance while leaving
+  the uptime percentage untouched.
+
+## Migration and rollout
+
+No migration is needed — both collections are new and absent means empty. Index
+builders follow the `EnsureWorkflowIndexes` precedent and warn rather than being
+fatal: a missing index on a small collection degrades to a scan, which is no
+reason to refuse to serve the fleet.
+
+The feature ships dark until the `status_pages` feature is added to the plan
+rows in admin.

docs/superpowers/specs/2026-09-07-control-plane-backup-restore-design.md

@@ -0,0 +1,330 @@
+# Control plane backup and restore
+
+Date: 2026-09-07
+Status: approved, ready for implementation planning
+
+## Problem
+
+Vantage has no backup story. A self-hosted deployment holds its entire state in
+MongoDB and encrypts the sensitive half of it — SSH private keys, key
+passphrases, vault secrets, OIDC client secrets, RDP and VNC credentials — with
+AES-256-GCM under a single 32-byte key supplied as the `KEY_ENCRYPTION_KEY`
+environment variable.
+
+That key is a bare value. It carries no identifier, is not wrapped, and is not
+recorded anywhere alongside the data it protects. Restoring a database without
+it produces a control plane whose every secret is permanently unreadable, and
+nothing in the product tells an operator this before it happens.
+
+`mongodump` exists and operators can use it, but it says nothing about the
+encryption key, so the most common way to lose everything is to hold a perfectly
+good database dump and no key.
+
+## Goal
+
+A standalone command-line tool that backs up and restores a whole Vantage
+deployment, and that makes the key relationship impossible to get wrong by
+accident.
+
+Explicitly not a goal: point-in-time recovery, incremental backups, built-in
+storage backends, encryption of the archive itself, per-tenant export, and
+backups scheduled from inside the server. Each is a separate decision and
+several are better served by tools the operator already has.
+
+## Design
+
+### Scope of a backup
+
+One backup covers one MongoDB database: every collection in it, whether or not
+that collection is tenant-scoped. A deployment-level disaster recovery tool that
+skipped `migrations` or `vulndb_meta` would restore a database the server
+refuses to boot against.
+
+Collections are enumerated live with `ListCollectionNames` rather than read from
+a hardcoded list. This is the opposite choice to `services.ScopedCollections`,
+and deliberately so: that list can afford to be hand-maintained because
+`AssertNoScopedCollectionMissed` fails boot when it drifts. A backup tool has no
+such assertion available, so a second hand-maintained registry would drift
+silently and the first symptom would be a restore missing a collection nobody
+noticed was added.
+
+`--exclude` accepts collection names for the volume-heavy ones —
+`workflow_log_lines`, `monitor_samples`, `audit_logs`. Whatever is excluded is
+recorded in the manifest, so an archive can never claim to be complete when it
+is not.
+
+Redis is not backed up. It holds sessions only; losing it logs everyone out and
+nothing else, which is already the documented behaviour. The restore output says
+so explicitly rather than leaving an operator to wonder.
+
+### Where the code lives
+
+Two units.
+
+`shared/backup/` holds the logic: dump, restore, manifest construction, archive
+reading and writing, and key fingerprinting. It depends on the MongoDB driver
+and the standard library, and on no CLI framework. Keeping it in `shared/` and
+free of cobra is what lets `server` import it later if backups scheduled from
+inside the control plane are ever built, without pulling a command-line parser
+into the server binary.
+
+`vantagectl/` is a new module in `go.work`, importing `shared`. It holds the
+cobra command tree and nothing else. A separate module rather than a package
+under `shared/` because adding cobra to `shared/go.mod` would put cobra and
+pflag into the module graph of `server`, `admin` and `sitesvc`, none of which
+use them. Binaries are unaffected — Go links only what is imported — but three
+`go.sum` files would grow and three CI builds would fetch a dependency they do
+not need. `agent/` is already a separate module for the same reason.
+
+The tool imports nothing from `server/`. No `db.Col()`, no `services`, no config
+loader, and it never dials the REST or gRPC API. It needs only network reach to
+MongoDB, a database name, and `KEY_ENCRYPTION_KEY` in its own environment. This
+is what lets it run against a control plane that is down, half-migrated, or was
+deleted an hour ago — which is the only condition under which anyone runs a
+restore.
+
+### Dump implementation
+
+The dump is written against the MongoDB driver, not by shelling out to
+`mongodump`.
+
+Two reasons. `server`'s runtime image is `scratch` and carries no shell and no
+mongo tools, so a wrapper would depend on a matching `mongodump` version being
+installed on whatever host runs the tool. And the manifest must be written by
+the same process that read the documents, or the fingerprint and per-collection
+checksums are claims about data the writer never saw.
+
+The cost is that BSON round-tripping is ours to get right. Documents are written
+as raw BSON exactly as the driver returns them, without an intermediate map, so
+`ObjectId`, `Decimal128`, `DateTime`, binary subtypes and nulls survive
+unchanged. A round-trip test asserting byte-equal BSON is the guard.
+
+### Archive format
+
+A gzipped tar named `vantage-backup-<db>-<RFC3339>.tar.gz`:
+
+```
+manifest.json
+collections/<name>.bson            concatenated raw BSON documents
+indexes/<name>.json                index specifications
+```
+
+`manifest.json` carries:
+
+| Field | Purpose |
+| --- | --- |
+| `format_version` | Currently `1`. Restore refuses an unknown version rather than guessing at it |
+| `created_at` | RFC3339, UTC |
+| `vantage_version` | Build stamp of the tool that wrote the archive |
+| `hostname` | Provenance; which machine produced this |
+| `mongo_db` | Source database name |
+| `mongo_server_version` | Restore warns on a major version gap |
+| `key_fingerprint` | `sha256` of the raw 32 key bytes, hex, or `null`. Never the key |
+| `collections[]` | Per collection: name, document count, uncompressed bytes, `sha256` of the `.bson` member |
+| `excluded[]` | Collection names passed to `--exclude` |
+
+Per-collection checksums mean a truncated or corrupted archive is detected
+before a single document is written, rather than halfway through a restore.
+
+### Key custody
+
+The key never enters the archive. The archive is exactly as sensitive as a
+`mongodump` of the same database, and no more.
+
+What the archive carries is `sha256` of the raw key bytes. A hash of the key
+proves identity without being a hint at the value, which is what allows an
+operator to answer "will this archive restore into this deployment" without
+holding both in front of them.
+
+Backup refuses to run when `KEY_ENCRYPTION_KEY` is unset or malformed. An
+archive full of ciphertext whose key was never recorded is worse than no archive
+at all, because it looks like a backup. `--allow-no-key` exists for a deployment
+that genuinely stores no encrypted material; it stamps `key_fingerprint: null`,
+which restore then reports loudly rather than treating as a match.
+
+Restore compares the archive's fingerprint against the key in the current
+environment:
+
+- Fingerprints match: proceed.
+- Fingerprints differ: refuse, printing both.
+- Archive has a fingerprint, environment has no key: refuse.
+- `--ignore-key-mismatch`: proceed, having first printed exactly which
+  collections hold ciphertext that will be undecryptable — `keys`, `secrets`,
+  `auth_providers`, `console_sessions`, `settings`.
+
+### Restore semantics
+
+The order is fixed:
+
+1. Read `manifest.json` and check `format_version`.
+2. Verify every archive member against its manifest checksum. Nothing is written
+   before this passes.
+3. Apply the fingerprint rules above.
+4. Inspect the target: `ListCollectionNames` and document counts. A non-empty
+   database is refused, printing what was found. `--force` proceeds.
+5. Per collection: under `--force`, drop it first; then bulk-insert in batches
+   of 1000 with `ordered=false`.
+6. Replay index specifications from `indexes/<name>.json`, skipping `_id_`.
+7. Print a summary: collection, documents restored, indexes created.
+
+Restore is not idempotent, and says so. A second run without `--force` is
+refused because step 4 now finds data. A restore interrupted during step 5
+leaves a partial database that the next run refuses to touch — correct, because
+the alternative is a silent merge. There are no merge or upsert semantics at
+all: merging two control planes reconciles nothing and produces a fleet that
+half works, and upserting by `_id` resurrects rows deleted since the backup,
+which for revoked keys and deleted users is a security regression wearing the
+costume of a convenience.
+
+Index replay is fatal per collection when a unique index fails to build, and a
+warning when a non-unique one does. A unique index that cannot be created means
+the restored data violates it, and the unique indexes here — `(instance_id,
+email)`, instance slug, settings instance, the ESO token hash — are
+tenant-isolation properties rather than optimisations. The failure names the
+offending index.
+
+### Destructive confirmation
+
+Restore under `--force` requires a typed confirmation when stdin is a TTY.
+
+When stdin is not a TTY — a Kubernetes Job, a CI step, a cron entry — the
+confirmation comes from `--confirm-db <name>`, whose value must equal the
+resolved target database name or restore refuses. Naming the database in the
+argument means a copy-pasted restore command carries its intended target with
+it and cannot destroy a different one.
+
+A dynamic flag name containing the database name was considered and rejected:
+cobra registers flags before parsing, and the target database is not known at
+registration time.
+
+### Command surface
+
+```
+vantagectl                                     root; prints help
+├── backup    --out DIR|-  --exclude a,b  --allow-no-key
+├── restore   ARCHIVE  --force  --confirm-db NAME  --ignore-key-mismatch
+├── inspect   ARCHIVE
+└── verify    ARCHIVE
+```
+
+Persistent flags on the root command, so every subcommand accepts them and they
+are documented once: `--mongo-uri` (env `MONGO_URI`) and `--db` (env `MONGO_DB`,
+falling back to the URI path). There is no `--log-level`: the tool's entire
+output is what it is telling the operator, and a level that could hide a key
+warning is worth not having.
+
+Environment fallback is wired with an explicit `Changed` check on each flag
+rather than through viper. Viper is a configuration-file and remote-config
+system; this tool reads no configuration file, and pulling it in to call
+`os.Getenv` would make the largest dependency in the binary the one doing the
+smallest job.
+
+`inspect` prints the manifest — when the archive was made, by what version,
+which collections it holds, how many documents, what was excluded, and the key
+fingerprint — and contacts no database. It is what an operator runs to find out
+whether an archive they have found is worth anything.
+
+`verify` adds a live check: whether the archive's fingerprint matches the key in
+the current environment, and — when `--mongo-uri` is given — whether that key
+actually decrypts the target database. The second half is a probe: read one
+ciphertext field from `secrets`, `keys` or `auth_providers` and attempt to open
+it. A fingerprint comparison proves two archives agree; only a probe proves the
+key in hand opens the data in front of you. `verify` is the command that
+distinguishes "we have backups" from "we have backups that will restore", and
+the documentation recommends running it on a schedule.
+
+The probe needs AES-256-GCM open, which today lives in
+`server/internal/services/crypto.go` and cannot be imported from another module.
+Rather than copy it — the exact hazard `CLAUDE.md` names around mirrored token
+blocks and `web/lib/targets.ts` — the primitives move to a new `shared/cryptobox`
+package, and `services/crypto.go` becomes a thin delegation that keeps its
+existing unexported function names and its `KEY_ENCRYPTION_KEY` lookup. One
+implementation of the cipher, two callers.
+
+`--out -` streams the tarball to stdout, so piping into `aws s3 cp -`, `restic`
+or `age` covers storage and archive encryption without the tool growing backends
+of its own.
+
+### Distribution
+
+Three ways to run it, because the deployments that need it run Docker Compose,
+Kubernetes, or neither.
+
+**Loose binary.** A new `.gitea/workflows/vantagectl-release.yml`, triggered on
+`vantagectl/v*` tags, shaped like `agent-release.yml`. Builds `linux/amd64`,
+`linux/arm64`, `darwin/arm64` and `windows/amd64` with `CGO_ENABLED=0`, writes
+`checksums.txt`, and creates a Gitea release.
+
+**Container image.** `vantagectl/Dockerfile` — the repo's convention is a
+Dockerfile per module built from the repository root, because every Go module
+depends on `shared` through a replace directive — produces a `scratch`
+image holding the static binary and an explicitly copied `/tmp`, which the
+archive is staged in before compression — the same omission that silently
+disabled `vulnsched` on a scratch image. Pushed by `server-deploy.yml` as an
+eighth image.
+
+```bash
+docker run --rm --network vantage_default \
+  -e MONGO_URI -e MONGO_DB -e KEY_ENCRYPTION_KEY \
+  -v /backups:/out \
+  gitea.hostxtra.co.uk/mrhid6/vantagectl backup --out /out
+```
+
+**Kubernetes.** The chart gains `backup.enabled`, defaulting to **false**,
+rendering a `CronJob` that runs the same image and mounts the existing MongoDB
+and `KEY_ENCRYPTION_KEY` secrets by reference rather than re-declaring them.
+Output goes to a PVC named in values. The default is off because a backup with
+nowhere durable to land is a false sense of safety and the chart cannot know
+where that is; `NOTES.txt` says so on install.
+
+Restore in Kubernetes is the same image run as a one-shot `Job`. The chart ships
+no restore manifest: a restore is an operator decision with a confirmation
+attached to it, and must never be something a `helm upgrade` can trigger.
+
+`server-deploy.yml`'s rebuild trigger table gains a `vantagectl` row —
+`vantagectl/`, `shared/`, `go.work` — which makes `shared/` fan out to four Go
+images rather than three. That table is already called out in `CLAUDE.md` as a
+place where a missed entry ships a stale image.
+
+## Testing
+
+`shared/backup` is tested against a real MongoDB, via `testcontainers-go` if the
+module graph tolerates it and otherwise behind a `MONGO_TEST_URI` environment
+variable that skips when unset.
+
+Required cases:
+
+- Round trip: seed one document of every awkward BSON type — `ObjectId`,
+  `Decimal128`, `DateTime`, binary, null, nested arrays — back up, restore into
+  a second database, assert byte-equal BSON.
+- A single corrupted byte in a `.bson` member causes restore to refuse before
+  writing anything.
+- Fingerprint mismatch is refused; `--ignore-key-mismatch` proceeds and names
+  the ciphertext-bearing collections.
+- A non-empty target is refused; `--force` replaces it.
+- An excluded collection is absent from the archive and named in the manifest.
+- A unique index that cannot be built aborts the restore, naming the index.
+
+Fingerprint computation is a pure function and is tested without a database.
+
+## Documentation
+
+`docsite/docs/operations/backup-and-restore.md`, covering:
+
+- What `KEY_ENCRYPTION_KEY` is, that it is not in the backup, and that losing it
+  is unrecoverable. This comes first on the page, not as a note at the bottom.
+- The three run modes above, each as a command that can be copied.
+- A restore drill: restore into a scratch database and run `verify`, because an
+  untested backup is a hypothesis.
+- What is not covered: Redis sessions, the vulnerability database (re-pulled
+  automatically), and agent state on managed servers — agents reconnect on their
+  own and `servers.agent_token_hash` is in the backup, so no re-enrolment is
+  needed.
+
+`CLAUDE.md` gains a section describing the tool, since a new module, a new
+image, a new workflow and a new chart toggle are each something that drifts
+quietly.
+
+## Open questions
+
+None. Every decision above was settled during design.

installer/setup.ps1

@@ -1,140 +0,0 @@
-param(
-  [string]$ServerId,
-  [string]$Token,
-  [string]$ServerUrl,
-  [string]$InstallDir,
-  [switch]$Uninstall
-)
-
-$ErrorActionPreference = "Stop"
-$logDir = Join-Path $env:ProgramData "vantage"
-New-Item -ItemType Directory -Force -Path $logDir | Out-Null
-$log = Join-Path $logDir "install.log"
-
-function Write-Log($msg) {
-  $line = "{0} {1}" -f (Get-Date -Format "s"), $msg
-  Add-Content -Path $log -Value $line
-}
-
-# Fail native-exe (nssm) calls loudly: check $LASTEXITCODE after each call
-function Invoke-Native {
-  param([string]$File, [string[]]$Arguments)
-  Write-Log ("RUN: {0} {1}" -f $File, ($Arguments -join " "))
-  $out = & $File @Arguments 2>&1
-  if ($out) { Write-Log ("OUT: {0}" -f ($out -join "`n")) }
-  if ($LASTEXITCODE -ne 0) {
-    throw ("{0} exited {1}" -f $File, $LASTEXITCODE)
-  }
-}
-
-# Like Invoke-Native but never throws — for teardown, where a missing/stopped
-# service must not abort the uninstall.
-function Invoke-NativeSoft {
-  param([string]$File, [string[]]$Arguments)
-  Write-Log ("RUN(soft): {0} {1}" -f $File, ($Arguments -join " "))
-  # Native stderr merged via 2>&1 becomes terminating errors under
-  # ErrorActionPreference=Stop; force Continue in this scope so a benign nssm
-  # message (e.g. "service has not been started") never aborts setup.
-  $ErrorActionPreference = "Continue"
-  $out = & $File @Arguments 2>&1
-  if ($out) { Write-Log ("OUT: {0}" -f ($out -join "`n")) }
-  Write-Log ("EXIT: {0}" -f $LASTEXITCODE)
-}
-
-if ($Uninstall) {
-  try {
-    Write-Log "=== teardown start ==="
-    if (-not $InstallDir) { $InstallDir = $PSScriptRoot }
-    $nssm = Join-Path $InstallDir "nssm.exe"
-    if (Test-Path $nssm) {
-      Invoke-NativeSoft -File $nssm -Arguments @("stop", "VantageAgent")
-      Invoke-NativeSoft -File $nssm -Arguments @("remove", "VantageAgent", "confirm")
-    } else {
-      Write-Log "nssm.exe not found at $nssm - using sc.exe fallback"
-      Invoke-NativeSoft -File "sc.exe" -Arguments @("stop", "VantageAgent")
-      Invoke-NativeSoft -File "sc.exe" -Arguments @("delete", "VantageAgent")
-    }
-    Write-Log "=== teardown ok ==="
-    exit 0
-  }
-  catch {
-    Write-Log ("TEARDOWN ERROR: {0}" -f $_.Exception.Message)
-    # Never block uninstall
-    exit 0
-  }
-}
-
-try {
-  Write-Log "=== setup start ==="
-  Write-Log ("ServerId={0} ServerUrl={1} InstallDir={2}" -f $ServerId, $ServerUrl, $InstallDir)
-
-  $cfgDir = Join-Path $env:ProgramData "vantage"
-  New-Item -ItemType Directory -Force -Path $cfgDir | Out-Null
-  $cfgPath = Join-Path $cfgDir "config.yaml"
-
-  # Preserve existing config on upgrade. A MajorUpgrade re-runs this script with
-  # no SERVERID/TOKEN, so blindly rewriting would wipe the agent_token the agent
-  # persisted after Register(). Only (re)write when a ServerId is supplied
-  # (fresh install / explicit re-register).
-  if ((Test-Path $cfgPath) -and (-not $ServerId)) {
-    Write-Log "config.yaml exists and no ServerId supplied - preserving existing config (upgrade)"
-  }
-  else {
-    $cfg = @"
-server_url: "$ServerUrl"
-server_id: "$ServerId"
-pre_reg_token: "$Token"
-agent_token: ""
-poll_interval: 30s
-tls: true
-"@
-    Set-Content -Path $cfgPath -Value $cfg -Encoding utf8
-    Write-Log "wrote $cfgPath"
-
-    # Lock down ACL: SYSTEM + Administrators only
-    Invoke-Native -File "icacls" -Arguments @($cfgPath, "/inheritance:r", "/grant:r", "SYSTEM:F", "Administrators:F")
-  }
-
-  if (-not $InstallDir) { $InstallDir = $PSScriptRoot }
-  $nssm = Join-Path $InstallDir "nssm.exe"
-  $exe  = Join-Path $InstallDir "vantage-agent.exe"
-
-  if (-not (Test-Path $nssm)) { throw "nssm.exe not found at $nssm" }
-  if (-not (Test-Path $exe))  { throw "vantage-agent.exe not found at $exe" }
-
-  # Install only if the service isn't already registered (an upgrade may leave
-  # it in place). "nssm install" on an existing service errors otherwise.
-  $exists = Get-Service -Name "VantageAgent" -ErrorAction SilentlyContinue
-  if (-not $exists) {
-    Invoke-Native -File $nssm -Arguments @("install", "VantageAgent", $exe)
-  } else {
-    Write-Log "VantageAgent service already exists - updating binary path"
-    Invoke-Native -File $nssm -Arguments @("set", "VantageAgent", "Application", $exe)
-  }
-  Invoke-Native -File $nssm -Arguments @("set", "VantageAgent", "Start", "SERVICE_AUTO_START")
-
-  # Redirect service stdout/stderr to log files (nssm discards them otherwise)
-  # with online rotation at ~1MB.
-  $outLog = Join-Path $logDir "agent-stdout.log"
-  $errLog = Join-Path $logDir "agent-stderr.log"
-  Invoke-Native -File $nssm -Arguments @("set", "VantageAgent", "AppStdout", $outLog)
-  Invoke-Native -File $nssm -Arguments @("set", "VantageAgent", "AppStderr", $errLog)
-  Invoke-Native -File $nssm -Arguments @("set", "VantageAgent", "AppStdoutCreationDisposition", "4")
-  Invoke-Native -File $nssm -Arguments @("set", "VantageAgent", "AppStderrCreationDisposition", "4")
-  Invoke-Native -File $nssm -Arguments @("set", "VantageAgent", "AppRotateFiles", "1")
-  Invoke-Native -File $nssm -Arguments @("set", "VantageAgent", "AppRotateOnline", "1")
-  Invoke-Native -File $nssm -Arguments @("set", "VantageAgent", "AppRotateBytes", "1048576")
-
-  # Service is freshly (re)installed and stopped here (teardown removed the old
-  # one on upgrade), so start it. "restart" would try to stop a not-running
-  # service and emit a stderr error.
-  Invoke-NativeSoft -File $nssm -Arguments @("start", "VantageAgent")
-
-  Write-Log "=== setup ok ==="
-  exit 0
-}
-catch {
-  Write-Log ("ERROR: {0}" -f $_.Exception.Message)
-  Write-Log ($_.ScriptStackTrace)
-  exit 1
-}

installer/vantage-agent.wxs

@@ -1,82 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<?ifndef Version ?>
-<?define Version = "0.0.0.0" ?>
-<?endif?>
-<Wix xmlns="http://wixtoolset.org/schemas/v4/wxs">
-  <Package Name="Vantage Agent" Manufacturer="Vantage"
-           Version="$(var.Version)" UpgradeCode="7d1e6d2c-2a5f-4b3e-9c3a-8a1b2c3d4e5f"
-           Scope="perMachine">
-    <MajorUpgrade DowngradeErrorMessage="A newer version is already installed."
-                  Schedule="afterInstallInitialize" />
-    <MediaTemplate EmbedCab="yes" />
-
-    <!-- Public properties settable via msiexec: SERVERID, TOKEN, SERVERURL -->
-    <Property Id="SERVERID" Secure="yes" />
-    <Property Id="TOKEN" Secure="yes" />
-    <Property Id="SERVERURL" Secure="yes" />
-
-    <StandardDirectory Id="ProgramFiles64Folder">
-      <Directory Id="INSTALLDIR" Name="Vantage">
-        <Component Id="AgentExe" Guid="*">
-          <File Id="AgentExe" Source="vantage-agent-windows-amd64.exe" Name="vantage-agent.exe" KeyPath="yes" />
-        </Component>
-        <Component Id="NssmExe" Guid="*">
-          <File Id="NssmExe" Source="nssm.exe" Name="nssm.exe" KeyPath="yes" />
-        </Component>
-        <Component Id="SetupScript" Guid="*">
-          <File Id="SetupScript" Source="setup.ps1" Name="setup.ps1" KeyPath="yes" />
-        </Component>
-      </Directory>
-    </StandardDirectory>
-
-    <Feature Id="Main">
-      <ComponentRef Id="AgentExe" />
-      <ComponentRef Id="NssmExe" />
-      <ComponentRef Id="SetupScript" />
-    </Feature>
-
-    <!-- Write config.yaml, then install + start the service via nssm.
-         Implemented as sequenced CustomActions running a helper script.
-
-         Deferred CustomActions run out-of-process (and with Impersonate="no",
-         as SYSTEM) with NO access to the installer property table, so
-         "[SERVERID]"/"[TOKEN]"/"[SERVERURL]"/"[INSTALLDIR]" would resolve to
-         empty strings if referenced directly on the deferred action. The fix
-         is the standard CustomActionData marshaling pattern: an immediate
-         SetProperty (type 51) with the SAME Id as the deferred CustomAction
-         runs first (while property values are still visible) and resolves
-         the formatted string; the deferred Directory/ExeCommand CustomAction
-         that shares that Id then receives the resolved string back as its
-         CustomActionData, referenced here as "[WriteConfig]". This avoids
-         pulling in the WixToolset.Util extension (WixQuietExec64) purely to
-         get CustomActionData plumbing.
-
-         NOTE: this only builds/validates the MSI's XML in CI - it has not
-         been verified with a real install on Windows. Needs a smoke test
-         (msiexec /i, confirm C:\ProgramData\Vantage\config.yaml or similar
-         is written with the correct values, and the service starts) on an
-         actual Windows machine before this is trusted in production. -->
-    <SetProperty Id="WriteConfig"
-      Before="WriteConfig" Sequence="execute" Condition="NOT Installed"
-      Value='cmd.exe /c powershell -ExecutionPolicy Bypass -File "[INSTALLDIR]setup.ps1" -ServerId "[SERVERID]" -Token "[TOKEN]" -ServerUrl "[SERVERURL]"' />
-
-    <CustomAction Id="WriteConfig" Directory="INSTALLDIR" ExeCommand="[WriteConfig]"
-      Execute="deferred" Impersonate="no" Return="check" />
-
-    <!-- Teardown on uninstall: stop + remove the service BEFORE RemoveFiles
-         deletes nssm.exe/setup.ps1. Same CustomActionData marshaling pattern
-         as WriteConfig. REMOVE="ALL" = full uninstall (not a component-level
-         repair/modify). -->
-    <SetProperty Id="RemoveService"
-      Before="RemoveService" Sequence="execute" Condition="REMOVE=&quot;ALL&quot;"
-      Value='cmd.exe /c powershell -ExecutionPolicy Bypass -File "[INSTALLDIR]setup.ps1" -Uninstall' />
-
-    <CustomAction Id="RemoveService" Directory="INSTALLDIR" ExeCommand="[RemoveService]"
-      Execute="deferred" Impersonate="no" Return="ignore" />
-
-    <InstallExecuteSequence>
-      <Custom Action="WriteConfig" After="InstallFiles" Condition="NOT Installed" />
-      <Custom Action="RemoveService" Before="RemoveFiles" Condition="REMOVE=&quot;ALL&quot;" />
-    </InstallExecuteSequence>
-  </Package>
-</Wix>

proto/vantage/v1/vantage.proto

@@ -1,220 +0,0 @@
-syntax = "proto3";
-
-package vantage.v1;
-
-option go_package = "github.com/mrhid6/vantage/server/internal/grpc/pb";
-
-service Vantage {
-  rpc Register(RegisterRequest)                returns (RegisterResponse);
-  rpc SyncKeys(SyncRequest)                    returns (SyncResponse);
-  rpc UploadGeneratedKey(UploadKeyRequest)      returns (UploadKeyResponse);
-  rpc ReportUpdates(ReportUpdatesRequest)       returns (ReportUpdatesResponse);
-  rpc ReportInventory(InventoryReport)          returns (InventoryReportResponse);
-  rpc SyncMonitors(SyncMonitorsRequest)         returns (SyncMonitorsResponse);
-  rpc ReportChecks(ReportChecksRequest)         returns (ReportChecksResponse);
-  // Bidirectional stream: agent sends auth once, server pushes commands.
-  rpc CommandStream(stream AgentMessage)        returns (stream ServerCommand);
-}
-
-message RegisterRequest {
-  string server_id     = 1;
-  string pre_reg_token = 2;
-  string hostname      = 3;
-  string ip_address    = 4;
-  string os_info       = 5;
-}
-
-message RegisterResponse {
-  string agent_token = 1;
-}
-
-message SyncRequest {
-  string server_id    = 1;
-  string agent_token  = 2;
-  string agent_version = 3;
-}
-
-message SyncResponse {
-  repeated string public_keys = 1;
-}
-
-message UploadKeyRequest {
-  string server_id   = 1;
-  string agent_token = 2;
-  string public_key  = 3;
-  string label       = 4;
-  string private_key = 5;
-}
-
-message UploadKeyResponse {
-  string key_id = 1;
-}
-
-// CommandStream messages
-
-message AgentMessage {
-  string server_id   = 1;
-  string agent_token = 2;
-  oneof payload {
-    AgentReady    ready  = 3;
-    CommandResult result = 4;
-    StepResult step_result = 5;
-    StepOutputChunk step_output = 6;
-  }
-}
-
-message AgentReady {}
-
-message CommandResult {
-  string command_id = 1;
-  bool   success    = 2;
-  string message    = 3;
-}
-
-message PackageUpdate {
-  string name            = 1;
-  string current_version = 2;
-  string new_version     = 3;
-}
-
-message ReportUpdatesRequest {
-  string server_id   = 1;
-  string agent_token = 2;
-  repeated PackageUpdate updates = 3;
-}
-
-message ReportUpdatesResponse {}
-
-message CPUReport {
-  string model     = 1;
-  int32  cores     = 2;
-  double usage_pct = 3;
-  double load1     = 4;
-}
-
-message MemReport {
-  uint64 total_bytes = 1;
-  uint64 used_bytes  = 2;
-}
-
-message PartitionReport {
-  string device      = 1;
-  string mountpoint  = 2;
-  string fstype      = 3;
-  uint64 total_bytes = 4;
-  uint64 used_bytes  = 5;
-}
-
-message InventoryReport {
-  string server_id      = 1;
-  string agent_token    = 2;
-  bool   include_static = 3;
-  CPUReport cpu         = 4;
-  MemReport memory      = 5;
-  uint64 swap_total     = 6;
-  uint64 swap_used      = 7;
-  repeated PartitionReport partitions = 8;
-  string kernel         = 9;
-}
-
-message InventoryReportResponse {}
-
-message MonitorSpec {
-  string monitor_id      = 1;
-  string type            = 2;
-  string url             = 3;
-  string host            = 4;
-  int32  port            = 5;
-  string method          = 6;
-  int32  expected_status = 7;
-  string keyword         = 8;
-  int32  tls_warn_days   = 9;
-  int32  interval_sec    = 10;
-  int32  retries         = 11;
-  bool   insecure        = 12;
-}
-
-message SyncMonitorsRequest {
-  string server_id   = 1;
-  string agent_token = 2;
-}
-
-message SyncMonitorsResponse {
-  repeated MonitorSpec monitors = 1;
-}
-
-message CheckResult {
-  string monitor_id       = 1;
-  bool   up               = 2;
-  int32  latency_ms       = 3;
-  string message          = 4;
-  int64  cert_expiry_unix = 5;
-}
-
-message ReportChecksRequest {
-  string server_id   = 1;
-  string agent_token = 2;
-  repeated CheckResult results = 3;
-}
-
-message ReportChecksResponse {}
-
-message ApplyUpdatesCmd {}
-
-message ServerCommand {
-  string command_id = 1;
-  oneof command {
-    GenerateKeyCmd  generate_key  = 2;
-    DeleteKeyCmd    delete_key    = 3;
-    UpdateAgentCmd  update_agent  = 4;
-    ApplyUpdatesCmd apply_updates = 5;
-    RunStepCmd      run_step      = 6;
-    CleanupWorkspaceCmd cleanup_workspace = 7;
-  }
-}
-
-// CleanupWorkspaceCmd tells the agent to recursively remove the run's working
-// directory once all steps on that server have finished.
-message CleanupWorkspaceCmd {
-  string workspace_id = 1;
-}
-
-message DeleteKeyCmd {
-  string label = 1;
-}
-
-message UpdateAgentCmd {
-  string version       = 1; // e.g. "1.2.3"
-  string gitea_base_url = 2; // e.g. "https://gitea.example.com"
-}
-
-message GenerateKeyCmd {
-  string label      = 1;
-  string key_type   = 2; // ed25519 | rsa | ecdsa (default: ed25519)
-  int32  key_size   = 3; // bits; used for rsa and ecdsa
-  string passphrase = 4; // empty = no passphrase
-  string comment    = 5; // embedded in public key
-}
-
-message RunStepCmd {
-  string interpreter      = 1; // "bash" | "powershell"
-  string script           = 2;
-  map<string, string> env = 3;
-  int32  timeout_seconds  = 4;
-  string workspace_id     = 5; // per-run working dir the agent creates & uses as cwd
-}
-
-message StepResult {
-  string command_id             = 1;
-  int32  exit_code              = 2;
-  string stdout                 = 3;
-  string stderr                 = 4;
-  map<string, string> output_env = 5;
-}
-
-message StepOutputChunk {
-  string command_id = 1;
-  uint64 seq        = 2;
-  bytes  data       = 3;
-  bool   eof        = 4;
-}

server/Dockerfile

@@ -1,24 +1,47 @@
 # Build stage
+#
+# Context is still the repository root, not server/, because the runtime stage
+# copies default_steps/ from it.
+#
+# vantage-shared is a private module, so every step that resolves it needs a
+# credential. It arrives as a BuildKit secret rather than a build arg: an arg
+# is baked into the builder layer's history, and this one is a Gitea token.
 FROM golang:1.26 AS builder
 
-WORKDIR /app
+WORKDIR /src
 
-# Download dependencies first (layer cache)
-COPY go.mod go.sum ./
-RUN go mod download
+ENV GOPRIVATE=gitea.hostxtra.co.uk/*
 
-# Copy source and build
-COPY . .
+# Manifests first so the dependency layer caches independently of source edits.
+COPY server/go.mod server/go.sum ./server/
+RUN --mount=type=secret,id=netrc,target=/root/.netrc \
+    cd server && go mod download
+
+COPY server/ ./server/
 
 ARG VERSION=dev
-RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w -X main.Version=${VERSION}" -o /vantage-server ./cmd
+RUN --mount=type=secret,id=netrc,target=/root/.netrc \
+    cd server && CGO_ENABLED=0 GOOS=linux go build \
+      -ldflags="-s -w -X main.Version=${VERSION}" -o /vantage-server ./cmd
+
+# Staged so the scratch image below can have a /tmp. It cannot mkdir one
+# itself — scratch has no shell — and os.MkdirTemp fails outright without it.
+RUN mkdir -p /staging/tmp && chmod 1777 /staging/tmp
 
 # Runtime stage
 FROM scratch
 
 COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
+
+# vulndb unpacks the ~50MB trivy-db here. Without it the scheduler stops at
+# "temp dir: stat /tmp: no such file or directory" and no scanning happens,
+# while everything else in the process runs perfectly well.
+COPY --from=builder /staging/tmp /tmp
 COPY --from=builder /vantage-server /vantage-server
 
+COPY default_steps/ /opt/default-steps/
+ENV VANTAGE_DEFAULT_STEPS_DIR=/opt/default-steps
+
 EXPOSE 8080 9090
 
 ENTRYPOINT ["/vantage-server"]

server/cmd/main.go

@@ -2,88 +2,317 @@ package main
 
 import (
 	"context"
+	"errors"
 	"log"
+	"net/http"
 	"os"
+	"os/signal"
+	"strings"
+	"syscall"
 	"time"
 
+	// Embeds the IANA zone database in the binary. Load-bearing: server/Dockerfile
+	// builds on Alpine, which ships no zoneinfo, so without this
+	// time.LoadLocation("Europe/London") fails in production and every workflow
+	// schedule silently falls back to UTC.
+	_ "time/tzdata"
+
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/api"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/auth"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/bus"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/db"
+	grpcserver "gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/grpc"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/monitorsched"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/services"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/vulnsched"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/workflowsched"
 	"github.com/gin-gonic/gin"
-	"github.com/mrhid6/vantage/server/internal/api"
-	"github.com/mrhid6/vantage/server/internal/auth"
-	"github.com/mrhid6/vantage/server/internal/db"
-	grpcserver "github.com/mrhid6/vantage/server/internal/grpc"
-	"github.com/mrhid6/vantage/server/internal/monitorsched"
-	"github.com/mrhid6/vantage/server/internal/services"
 )
 
+//	@title			Vantage API
+//	@version		1.0
+//	@description	The Vantage control plane REST API. Authenticate with a browser session cookie, or with an API token created under Settings → API tokens.
+//	@BasePath		/api
+
+// Each @securityDefinitions.apikey block below is deliberately its own
+// comment group, separated by a real blank line rather than a bare "//": Go's
+// parser only splits ast.CommentGroups on an actual blank line, and
+// swag v2.0.0-rc5's parseSecAttributesV3 resolves a scheme's map key by
+// scanning from the start of whatever comment group it was handed — so three
+// stacked blocks sharing one group all collapse onto the first block's name.
+// Three groups means three independent scans, each finding its own name.
+
+//	@securityDefinitions.apikey	cookieAuth
+//	@in								cookie
+//	@name							km_session
+
+//	@securityDefinitions.apikey	bearerAuth
+//	@in								header
+//	@name							Authorization
+//	@description					An API token, sent as "Bearer vt_…". Scoped and optionally expiring.
+
+// @securityDefinitions.apikey	esoAuth
+// @in								header
+// @name							Authorization
+// @description					The External Secrets read token, rotated under Settings. It reaches /api/secrets/{group}/values and nothing else. It is a different credential from an API token, and the two must never be substituted for one another.
 func main() {
 	mongoURI := getEnv("MONGO_URI", "mongodb://localhost:27017")
-	dbName := getEnv("MONGO_DB", "vantage")
 
-	if err := db.Connect(mongoURI, dbName); err != nil {
+	// Two flags, so the schema work can be lifted out of the serving pods.
+	//
+	// Under Docker Compose neither is set and nothing changes: one process
+	// migrates and then serves. Under Kubernetes with more than one replica
+	// that is unsafe — every pod would run MigrateOrgToInstance at once, and
+	// renaming collections while a sibling reads them is not a race anyone
+	// wins. The chart therefore runs a pre-upgrade Job with MIGRATE_ONLY and
+	// starts the Deployment with SKIP_MIGRATIONS.
+	migrateOnly := boolEnv("VANTAGE_MIGRATE_ONLY")
+	skipMigrations := boolEnv("VANTAGE_SKIP_MIGRATIONS")
+
+	// Not required in migrate-only mode: that process never serves gRPC, and
+	// demanding it would put an agent-facing address in a Job that has no
+	// business knowing one.
+	if !migrateOnly && os.Getenv("GRPC_HOST") == "" {
+		log.Fatal("GRPC_HOST is required (host:port agents dial for gRPC)")
+	}
+
+	// DB name comes from the MONGO_URI path; "vantage" is the fallback.
+	if err := db.Connect(mongoURI, "vantage"); err != nil {
 		log.Fatalf("failed to connect to MongoDB: %v", err)
 	}
 	log.Println("connected to MongoDB")
 
+	if migrateOnly || !skipMigrations {
+		runSchemaSetup()
+	} else {
+		log.Println("VANTAGE_SKIP_MIGRATIONS set: assuming migrations ran elsewhere")
+	}
+
+	if migrateOnly {
+		log.Println("VANTAGE_MIGRATE_ONLY set: schema setup complete, exiting")
+		return
+	}
+
+	serve()
+}
+
+// runSchemaSetup performs every write that must happen exactly once before the
+// application serves: migrations, index builders and default step seeding. It
+// is fatal on anything that would leave the schema half-moved.
+func runSchemaSetup() {
+	// Migrations 0001 to 0003 still speak the pre-rename shape (orgs, org_id),
+	// so they must run before 0004 renames everything underneath them.
+	if err := services.RunMigrations(); err != nil {
+		log.Fatalf("migration failed: %v", err)
+	}
+	// 0002 must precede 0003: 0003 can create a "default" org, which pushes
+	// 0002 into its ambiguous multi-org branch.
+	if err := services.MigrateSettingsOrg(); err != nil {
+		log.Fatalf("settings org migration failed: %v", err)
+	}
+	if err := services.MigrateMissedOrgScopes(); err != nil {
+		log.Fatalf("missed org scope migration failed: %v", err)
+	}
+
+	// 0004 renames orgs to instances. It must run BEFORE the index builders:
+	// EnsureAuthIndexes creates instances.slug, which would create an empty
+	// instances collection and make 0004 refuse to rename onto it.
+	migCtx, migCancel := context.WithTimeout(context.Background(), 10*time.Minute)
+	migErr := services.MigrateOrgToInstance(migCtx, db.Database)
+	migCancel()
+	if migErr != nil {
+		log.Fatalf("instance rename migration failed: %v", migErr)
+	}
+
+	assertCtx, assertCancel := context.WithTimeout(context.Background(), 30*time.Second)
+	assertErr := services.AssertNoScopedCollectionMissed(assertCtx, db.Database)
+	assertCancel()
+	if assertErr != nil {
+		log.Fatalf("scoped collection check failed: %v", assertErr)
+	}
+
+	if err := services.EnsureAuthIndexes(); err != nil {
+		log.Fatalf("failed to ensure auth indexes: %v", err)
+	}
+
+	if err := services.EnsureAPITokenIndexes(); err != nil {
+		log.Fatalf("api token indexes: %v", err)
+	}
+
+	// 0005 runs AFTER EnsureAuthIndexes: the unique (instance_id, provider_id)
+	// index must exist before anything inserts providers, or a concurrent
+	// re-run could double-insert before the index is there to refuse it.
+	if err := services.MigrateAuthProviders(); err != nil {
+		log.Fatalf("auth provider migration failed: %v", err)
+	}
+
 	if err := services.EnsureSecretIndexes(); err != nil {
 		log.Printf("warning: failed to ensure secret indexes: %v", err)
 	}
 
+	if err := services.EnsureServerIndexes(); err != nil {
+		log.Printf("warning: failed to ensure server indexes: %v", err)
+	}
+
+	if err := services.EnsureSettingsIndexes(); err != nil {
+		log.Fatalf("failed to ensure settings indexes: %v", err)
+	}
+
 	if err := services.EnsureWorkflowIndexes(); err != nil {
 		log.Printf("warning: failed to ensure workflow indexes: %v", err)
 	}
 
-	if created, updated, err := services.SeedDefaultSteps(); err != nil {
-		log.Printf("warning: failed to seed default steps: %v", err)
-	} else {
-		log.Printf("default steps seeded: %d created, %d updated", created, updated)
+	if err := services.EnsureMonitorSampleIndexes(); err != nil {
+		log.Printf("warning: failed to ensure monitor sample indexes: %v", err)
 	}
 
-	services.StartLogSweeper()
+	if err := services.EnsureVulnIndexes(); err != nil {
+		log.Printf("warning: failed to ensure vuln indexes: %v", err)
+	}
 
+	if err := services.EnsureWorkloadIndexes(); err != nil {
+		log.Printf("warning: failed to ensure workload indexes: %v", err)
+	}
+
+	if err := services.EnsureStatusPageIndexes(); err != nil {
+		log.Printf("warning: failed to ensure status page indexes: %v", err)
+	}
+
+	if err := services.EnsureAuditIndexes(); err != nil {
+		log.Printf("warning: failed to ensure audit indexes: %v", err)
+	}
+
+	if instanceIDs, err := services.ListInstanceIDs(); err != nil {
+		log.Printf("warning: failed to list instances for default step seeding: %v", err)
+	} else {
+		for _, instanceID := range instanceIDs {
+			if created, updated, err := services.SeedDefaultSteps(instanceID); err != nil {
+				log.Printf("warning: failed to seed default steps for instance %s: %v", instanceID, err)
+			} else {
+				log.Printf("default steps seeded for instance %s: %d created, %d updated", instanceID, created, updated)
+			}
+		}
+	}
+
+}
+
+func serve() {
 	redisAddr := getEnv("REDIS_ADDR", "localhost:6379")
-	if err := auth.InitRedis(redisAddr); err != nil {
+	redisUser := os.Getenv("REDIS_USERNAME")
+	redisPass := os.Getenv("REDIS_PASSWORD")
+	if err := auth.InitRedis(redisAddr, redisUser, redisPass); err != nil {
 		log.Fatalf("failed to connect to Redis: %v", err)
 	}
 	log.Println("connected to Redis")
 
-	if err := auth.InitOIDC(context.Background()); err != nil {
-		log.Fatalf("failed to initialise OIDC: %v", err)
+	// The bus carries agent commands and step results between replicas. It is
+	// not optional even on a single-replica deployment: dispatch takes the same
+	// path either way, so the code exercised in production is the code
+	// exercised everywhere.
+	if err := bus.Init(redisAddr, redisUser, redisPass); err != nil {
+		log.Fatalf("failed to connect the message bus: %v", err)
+	}
+	log.Printf("message bus ready as node %s", bus.NodeID())
+
+	// Cancelled on SIGTERM/SIGINT. Everything below that takes a context — the
+	// housekeeping jobs, the leader lock — stops when the pod is asked to.
+	ctx, shutdown := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer shutdown()
+
+	stopGRPC, err := grpcserver.StartGRPC(9090)
+	if err != nil {
+		log.Fatalf("gRPC server error: %v", err)
 	}
 
-	// Background goroutine to mark offline servers
-	go func() {
+	// Everything below runs on exactly one replica at a time.
+	//
+	// These are cluster-singleton jobs, not per-pod work: N replicas would mean
+	// every monitor check firing N times, every incident notification delivered
+	// to the customer N times, every retention sweep deleting concurrently, and
+	// N reapers racing to purge the same instance. They share one lock rather
+	// than holding four, because they are one role — housekeeping — and
+	// splitting them would only spread that role across pods for no benefit.
+	bus.RunAsLeader(ctx, "housekeeping", func(jobCtx context.Context) {
+		services.StartLogSweeper(jobCtx)
+		services.StartAuditSweeper(jobCtx)
+		services.StartReaper(jobCtx)
+		monitorsched.Start(jobCtx)
+		workflowsched.Start(jobCtx, workflowsched.Deps{
+			TriggerWorkflow: services.TriggerWorkflow,
+			LogEvent:        services.LogEvent,
+		})
+
+		vulnsched.Start(jobCtx, vulnsched.Deps{
+			LogEvent:   services.LogEvent,
+			SendDigest: services.SendVulnDigest,
+		})
+		services.StartVulnSweeper(jobCtx)
+
 		ticker := time.NewTicker(2 * time.Minute)
 		defer ticker.Stop()
-		for range ticker.C {
-			if err := services.MarkOfflineServers(); err != nil {
-				log.Printf("mark offline error: %v", err)
+		for {
+			select {
+			case <-jobCtx.Done():
+				return
+			case <-ticker.C:
+				if err := services.MarkOfflineServers(); err != nil {
+					log.Printf("mark offline error: %v", err)
+				}
 			}
 		}
-	}()
+	})
 
-	// Start gRPC server
-	go func() {
-		if err := grpcserver.StartGRPC(9090); err != nil {
-			log.Fatalf("gRPC server error: %v", err)
-		}
-	}()
-
-	// Start the server-side monitor scheduler.
-	monitorsched.Start(context.Background())
-
-	// Start REST server
 	r := gin.New()
+	// Without this gin trusts every proxy and ClientIP() is whatever the
+	// caller wrote in X-Forwarded-For. That was survivable while ClientIP()
+	// only produced audit strings; the public status limiter makes it load
+	// bearing. Empty means trust nobody, which is correct for a direct
+	// exposure and wrong behind a proxy — hence the explicit setting.
+	if err := r.SetTrustedProxies(api.TrustedProxies()); err != nil {
+		log.Fatalf("trusted proxies: %v", err)
+	}
 	r.Use(gin.Recovery())
 	r.Use(gin.LoggerWithConfig(gin.LoggerConfig{SkipPaths: []string{"/api/console/tunnel"}}))
 	r.Use(corsMiddleware())
+	services.SetStatusRedis(auth.Redis())
+
 	api.RegisterRoutes(r)
 
-	log.Println("REST server listening on :8080")
-	if err := r.Run(":8080"); err != nil {
-		log.Fatalf("REST server error: %v", err)
+	if err := api.AssertScopeMapComplete(r); err != nil {
+		log.Fatalf("api scope map: %v", err)
 	}
+
+	srv := &http.Server{Addr: ":8080", Handler: r}
+	go func() {
+		log.Println("REST server listening on :8080")
+		if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+			log.Fatalf("REST server error: %v", err)
+		}
+	}()
+
+	<-ctx.Done()
+	log.Println("shutdown signal received")
+
+	// gRPC first, and this ordering is the point of the whole exercise. Stopping
+	// it runs each CommandStream handler's deferred release, which clears that
+	// agent's presence claim; until that happens another replica will keep
+	// dispatching commands to this process. Draining HTTP first would leave the
+	// claims held for the length of the drain.
+	stopGRPC()
+
+	drainCtx, cancelDrain := context.WithTimeout(context.Background(), httpDrainTimeout)
+	defer cancelDrain()
+	if err := srv.Shutdown(drainCtx); err != nil {
+		log.Printf("REST server shutdown: %v", err)
+	}
+	log.Println("shutdown complete")
 }
 
+// How long in-flight REST requests are given to finish. Console tunnels are
+// long-lived WebSockets that will not end on their own, so this is a ceiling
+// rather than a target; the relays behind them are already gone by this point.
+const httpDrainTimeout = 10 * time.Second
+
 func corsMiddleware() gin.HandlerFunc {
 	return func(c *gin.Context) {
 		c.Header("Access-Control-Allow-Origin", "*")
@@ -103,3 +332,14 @@ func getEnv(key, fallback string) string {
 	}
 	return fallback
 }
+
+// boolEnv reads a flag env var. Anything other than a recognised truthy value
+// is false, so a typo leaves the safe default (migrate here, serve here) rather
+// than silently skipping schema setup.
+func boolEnv(key string) bool {
+	switch strings.ToLower(strings.TrimSpace(os.Getenv(key))) {
+	case "1", "true", "yes", "on":
+		return true
+	}
+	return false
+}

server/go.mod

@@ -1,19 +1,43 @@
-module github.com/mrhid6/vantage/server
+module gitea.hostxtra.co.uk/mrhid6/vantage/server
 
 go 1.26
 
 require (
+	github.com/aquasecurity/trivy-db v0.0.0-20260713131703-4be526083c54
 	github.com/coreos/go-oidc/v3 v3.18.0
 	github.com/gin-gonic/gin v1.10.0
 	github.com/google/uuid v1.6.0
+	github.com/knqyf263/go-apk-version v0.0.0-20200609155635-041fdbb8563f
+	github.com/knqyf263/go-deb-version v0.0.0-20241115132648-6f4aee6ccd23
+	github.com/knqyf263/go-rpm-version v0.0.0-20240918084003-2afd7dc6a38f
+	github.com/opencontainers/image-spec v1.1.1
 	github.com/redis/go-redis/v9 v9.20.1
+	github.com/robfig/cron/v3 v3.0.1
 	github.com/wwt/guac v1.3.2
-	go.mongodb.org/mongo-driver/v2 v2.2.2
+	go.mongodb.org/mongo-driver/v2 v2.8.0
+	golang.org/x/crypto v0.54.0
 	golang.org/x/oauth2 v0.36.0
 	google.golang.org/grpc v1.64.0
+	oras.land/oras-go/v2 v2.6.2
 )
 
 require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/hyperboloide/lk v0.0.0-20251220053519-b291812e3216 // indirect
+	github.com/oklog/ulid/v2 v2.1.1 // indirect
+	github.com/opencontainers/go-digest v1.0.0 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/samber/lo v1.50.0 // indirect
+	github.com/samber/oops v1.18.1 // indirect
+	github.com/stretchr/objx v0.5.2 // indirect
+	github.com/stretchr/testify v1.11.1 // indirect
+	go.etcd.io/bbolt v1.4.3 // indirect
+	go.opentelemetry.io/otel v1.34.0 // indirect
+	go.opentelemetry.io/otel/trace v1.34.0 // indirect
+)
+
+require (
+	gitea.hostxtra.co.uk/vantage/vantage-shared v0.1.0
 	github.com/bytedance/sonic v1.11.6 // indirect
 	github.com/bytedance/sonic/loader v0.1.1 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
@@ -26,10 +50,9 @@ require (
 	github.com/go-playground/universal-translator v0.18.1 // indirect
 	github.com/go-playground/validator/v10 v10.20.0 // indirect
 	github.com/goccy/go-json v0.10.2 // indirect
-	github.com/golang/snappy v1.0.0 // indirect
 	github.com/gorilla/websocket v1.4.1 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
-	github.com/klauspost/compress v1.16.7 // indirect
+	github.com/klauspost/compress v1.17.6 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.10 // indirect
 	github.com/konsorten/go-windows-terminal-sequences v1.0.1 // indirect
 	github.com/leodido/go-urn v1.4.0 // indirect
@@ -41,16 +64,15 @@ require (
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/ugorji/go/codec v1.2.12 // indirect
 	github.com/xdg-go/pbkdf2 v1.0.0 // indirect
-	github.com/xdg-go/scram v1.1.2 // indirect
+	github.com/xdg-go/scram v1.2.0 // indirect
 	github.com/xdg-go/stringprep v1.0.4 // indirect
 	github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 // indirect
 	go.uber.org/atomic v1.11.0 // indirect
 	golang.org/x/arch v0.8.0 // indirect
-	golang.org/x/crypto v0.33.0 // indirect
-	golang.org/x/net v0.25.0 // indirect
-	golang.org/x/sync v0.11.0 // indirect
-	golang.org/x/sys v0.30.0 // indirect
-	golang.org/x/text v0.22.0 // indirect
+	golang.org/x/net v0.56.0 // indirect
+	golang.org/x/sync v0.22.0 // indirect
+	golang.org/x/sys v0.47.0 // indirect
+	golang.org/x/text v0.40.0 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20240521202816-d264139d666e // indirect
 	google.golang.org/protobuf v1.34.2 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect

server/go.sum

@@ -1,3 +1,9 @@
+gitea.hostxtra.co.uk/vantage/vantage-shared v0.1.0 h1:H6PCb8JHucrRiqPe9kGOhXUjBD66tKFHCP3qz5TjdZc=
+gitea.hostxtra.co.uk/vantage/vantage-shared v0.1.0/go.mod h1:dWjeOFLltQ8sv9Pnn1xRxGfWGgqa2fkG0esuaJLoPXQ=
+github.com/aquasecurity/bolt-fixtures v0.0.0-20200903104109-d34e7f983986 h1:2a30xLN2sUZcMXl50hg+PJCIDdJgIvIbVcKqLJ/ZrtM=
+github.com/aquasecurity/bolt-fixtures v0.0.0-20200903104109-d34e7f983986/go.mod h1:NT+jyeCzXk6vXR5MTkdn4z64TgGfE5HMLC8qfj5unl8=
+github.com/aquasecurity/trivy-db v0.0.0-20260713131703-4be526083c54 h1:4CZNoDkNfcuACevZeDraACGmP1+L0nKkRY52+jV8k1M=
+github.com/aquasecurity/trivy-db v0.0.0-20260713131703-4be526083c54/go.mod h1:iIEV2oGuZScvfyX2SMIn78iVMNnepgo0QuJJh/srgVI=
 github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
 github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
 github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
@@ -35,8 +41,8 @@ github.com/go-playground/validator/v10 v10.20.0 h1:K9ISHbSaI0lyB2eWMPJo+kOS/FBEx
 github.com/go-playground/validator/v10 v10.20.0/go.mod h1:dbuPbCMFw/DrkbEynArYaCwl3amGuJotoKCe95atGMM=
 github.com/goccy/go-json v0.10.2 h1:CrxCmQqYDkv1z7lO7Wbh2HN93uovUHgrECaO5ZrCXAU=
 github.com/goccy/go-json v0.10.2/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I=
-github.com/golang/snappy v1.0.0 h1:Oy607GVXHs7RtbggtPBnr2RmDArIsAefDwvrdWvRhGs=
-github.com/golang/snappy v1.0.0/go.mod h1:/XxbfmMg8lxefKM7IXC3fBNl/7bRcc72aCRzEWrmP2Q=
+github.com/goccy/go-yaml v1.19.0 h1:EmkZ9RIsX+Uq4DYFowegAuJo8+xdX3T/2dwNPXbxEYE=
+github.com/goccy/go-yaml v1.19.0/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
 github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
@@ -45,16 +51,26 @@ github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/gorilla/websocket v1.4.1 h1:q7AeDBpnBk8AogcD4DSag/Ukw/KV+YhzLj2bP5HvKCM=
 github.com/gorilla/websocket v1.4.1/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/hyperboloide/lk v0.0.0-20251220053519-b291812e3216 h1:Luh+sE/W2M+V0Y+jlZN7nJefLNHc4/y93xxl+rFD7k0=
+github.com/hyperboloide/lk v0.0.0-20251220053519-b291812e3216/go.mod h1:/OLW9HZj6qtQ7gWTGwuO3JrUZ+MC7I7TLRuNl14TYuo=
 github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
 github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
-github.com/klauspost/compress v1.16.7 h1:2mk3MPGNzKyxErAw8YaohYh69+pa4sIQSC0fPGCFR9I=
-github.com/klauspost/compress v1.16.7/go.mod h1:ntbaceVETuRiXiv4DpjP66DpAtAGkEQskQzEyD//IeE=
+github.com/klauspost/compress v1.17.6 h1:60eq2E/jlfwQXtvZEeBUYADs+BwKBWURIY+Gj2eRGjI=
+github.com/klauspost/compress v1.17.6/go.mod h1:/dCuZOvVtNoHsyb+cuJD3itjs3NbnF6KH9zAO4BDxPM=
 github.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
 github.com/klauspost/cpuid/v2 v2.2.10 h1:tBs3QSyvjDyFTq3uoc/9xFpCuOsJQFNPiAhYdw2skhE=
 github.com/klauspost/cpuid/v2 v2.2.10/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
+github.com/knqyf263/go-apk-version v0.0.0-20200609155635-041fdbb8563f h1:GvCU5GXhHq+7LeOzx/haG7HSIZokl3/0GkoUFzsRJjg=
+github.com/knqyf263/go-apk-version v0.0.0-20200609155635-041fdbb8563f/go.mod h1:q59u9px8b7UTj0nIjEjvmTWekazka6xIt6Uogz5Dm+8=
+github.com/knqyf263/go-deb-version v0.0.0-20241115132648-6f4aee6ccd23 h1:dWzdsqjh1p2gNtRKqNwuBvKqMNwnLOPLzVZT1n6DK7s=
+github.com/knqyf263/go-deb-version v0.0.0-20241115132648-6f4aee6ccd23/go.mod h1:lUaIXCWzf7BRKTY5iEcrYy1TfgbYLYVIS/B2vPkJzOc=
+github.com/knqyf263/go-rpm-version v0.0.0-20240918084003-2afd7dc6a38f h1:xt29M2T6STgldg+WEP51gGePQCsQvklmP2eIhPIBK3g=
+github.com/knqyf263/go-rpm-version v0.0.0-20240918084003-2afd7dc6a38f/go.mod h1:i4sF0l1fFnY1aiw08QQSwVAFxHEm311Me3WsU/X7nL0=
 github.com/knz/go-libedit v1.10.1/go.mod h1:MZTVkCWyz0oBc7JOWP3wNAzd002ZbM/5hgShxwh4x8M=
 github.com/konsorten/go-windows-terminal-sequences v1.0.1 h1:mweAR1A6xJ3oS2pRaGiHgQ4OO8tzTaLawm8vnODuwDk=
 github.com/konsorten/go-windows-terminal-sequences v1.0.1/go.mod h1:T0+1ngSBFLxvqU3pZ+m/2kptfBszLMUkC4ZK/EgS/cQ=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
 github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
@@ -64,28 +80,46 @@ github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
 github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e h1:fD57ERR4JtEqsWbfPhv4DMiApHyliiK5xCTNVSPiaAs=
+github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno=
+github.com/oklog/ulid/v2 v2.1.1 h1:suPZ4ARWLOJLegGFiZZ1dFAkqzhMjL3J1TzI+5wHz8s=
+github.com/oklog/ulid/v2 v2.1.1/go.mod h1:rcEKHmBBKfef9DhnvX7y1HZBYxjXb0cP5ExxNsTT1QQ=
+github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U=
+github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
+github.com/opencontainers/image-spec v1.1.1 h1:y0fUlFfIZhPF1W537XOLg0/fcx6zcHCJwooC2xJA040=
+github.com/opencontainers/image-spec v1.1.1/go.mod h1:qpqAh3Dmcf36wStyyWU+kCeDgrGnAve2nCC8+7h8Q0M=
+github.com/pborman/getopt v0.0.0-20170112200414-7148bc3a4c30/go.mod h1:85jBQOZwpVEaDAr341tbn15RS4fCAsIst0qp7i8ex1o=
 github.com/pelletier/go-toml/v2 v2.2.2 h1:aYUidT7k73Pcl9nb2gScu7NSrKCSHIDE89b3+6Wq+LM=
 github.com/pelletier/go-toml/v2 v2.2.2/go.mod h1:1t835xjRzz80PqgE6HHgN2JOsmgYu/h4qDAS4n929Rs=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/redis/go-redis/v9 v9.20.1 h1:sfCU6A8P3dXbKyWes02uxA2baehGux9dZHfEKtsTB1w=
 github.com/redis/go-redis/v9 v9.20.1/go.mod h1:v/M13XI1PVCDcm01VtPFOADfZtHf8YW3baQf57KlIkA=
+github.com/robfig/cron/v3 v3.0.1 h1:WdRxkvbJztn8LMz/QEvLN5sBU+xKpSqwwUO1Pjr4qDs=
+github.com/robfig/cron/v3 v3.0.1/go.mod h1:eQICP3HwyT7UooqI/z+Ov+PtYAWygg1TEWWzGIFLtro=
+github.com/samber/lo v1.50.0 h1:XrG0xOeHs+4FQ8gJR97zDz5uOFMW7OwFWiFVzqopKgY=
+github.com/samber/lo v1.50.0/go.mod h1:RjZyNk6WSnUFRKK6EyOhsRJMqft3G+pg7dCWHQCWvsc=
+github.com/samber/oops v1.18.1 h1:qjhZbqbdyhWBKntkY8sxrDNKA8b4c5VHlmI1rli7X7M=
+github.com/samber/oops v1.18.1/go.mod h1:xYqvimigkKV70HyLXiBZJFpIWi2CGcc6Xx7eV+2HycI=
 github.com/sirupsen/logrus v1.4.2 h1:SPIRibHv4MatM3XXNO2BJeFLZwZ2LvZgfQ5+UNI2im4=
 github.com/sirupsen/logrus v1.4.2/go.mod h1:tLMulIdttU9McNUspp0xgXVQah82FyeX6MwdIuYE2rE=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.1.1/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
 github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
 github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.5.1/go.mod h1:5W2xD1RspED5o8YsWQXVCued0rvSQ+mT+I5cxcmMvtA=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
 github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
-github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
 github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
 github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
 github.com/ugorji/go/codec v1.2.12 h1:9LC83zGrHhuUA9l16C9AHXAqEV/2wBQ4nkvumAE65EE=
@@ -94,8 +128,8 @@ github.com/wwt/guac v1.3.2 h1:sH6OFGa/1tBs7ieWBVlZe7t6F5JAOWBry/tqQL/Vup4=
 github.com/wwt/guac v1.3.2/go.mod h1:eKm+NrnK7A88l4UBEcYNpZQGMpZRryYKoz4D/0/n1C0=
 github.com/xdg-go/pbkdf2 v1.0.0 h1:Su7DPu48wXMwC3bs7MCNG+z4FhcyEuz5dlvchbq0B0c=
 github.com/xdg-go/pbkdf2 v1.0.0/go.mod h1:jrpuAogTd400dnrH08LKmI/xc1MbPOebTwRqcT5RDeI=
-github.com/xdg-go/scram v1.1.2 h1:FHX5I5B4i4hKRVRBCFRxq1iQRej7WO3hhBuJf+UUySY=
-github.com/xdg-go/scram v1.1.2/go.mod h1:RT/sEzTbU5y00aCK8UOx6R7YryM0iF1N2MOmC3kKLN4=
+github.com/xdg-go/scram v1.2.0 h1:bYKF2AEwG5rqd1BumT4gAnvwU/M9nBp2pTSxeZw7Wvs=
+github.com/xdg-go/scram v1.2.0/go.mod h1:3dlrS0iBaWKYVt2ZfA4cj48umJZ+cAEbR6/SjLA88I8=
 github.com/xdg-go/stringprep v1.0.4 h1:XLI/Ng3O1Atzq0oBs3TWm+5ZVgkq2aqdlvP9JtoZ6c8=
 github.com/xdg-go/stringprep v1.0.4/go.mod h1:mPGuuIYwz7CmR2bT9j4GbQqutWS1zV24gijq1dTyGkM=
 github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 h1:ilQV1hzziu+LLM3zUTJ0trRztfwgjqKnBWNtSRkbmwM=
@@ -103,8 +137,14 @@ github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78/go.mod h1:aL8wCCfTfS
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
 github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=
 github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s=
-go.mongodb.org/mongo-driver/v2 v2.2.2 h1:9cYuS3fl1Xhqwpfazso10V7BHQD58kCgtzhfAmJYz9c=
-go.mongodb.org/mongo-driver/v2 v2.2.2/go.mod h1:qQkDMhCGWl3FN509DfdPd4GRBLU/41zqF/k8eTRceps=
+go.etcd.io/bbolt v1.4.3 h1:dEadXpI6G79deX5prL3QRNP6JB8UxVkqo4UPnHaNXJo=
+go.etcd.io/bbolt v1.4.3/go.mod h1:tKQlpPaYCVFctUIgFKFnAlvbmB3tpy1vkTnDWohtc0E=
+go.mongodb.org/mongo-driver/v2 v2.8.0 h1:CxWDGQYY8QQwNjAl/aq2sfWakdnWZynnqJ9F4DhHbP8=
+go.mongodb.org/mongo-driver/v2 v2.8.0/go.mod h1:yOI9kBsufol30iFsl1slpdq1I0eHPzybRWdyYUs8K/0=
+go.opentelemetry.io/otel v1.34.0 h1:zRLXxLCgL1WyKsPVrgbSdMN4c0FMkDAskSTQP+0hdUY=
+go.opentelemetry.io/otel v1.34.0/go.mod h1:OWFPOQ+h4G8xpyjgqo4SxJYdDQ/qmRH+wivy7zzx9oI=
+go.opentelemetry.io/otel/trace v1.34.0 h1:+ouXS2V8Rd4hp4580a8q23bg0azF2nI8cqLYnC8mh/k=
+go.opentelemetry.io/otel/trace v1.34.0/go.mod h1:Svm7lSjQD7kG7KJ/MUHPVXSDGz2OX4h0M2jHBhmSfRE=
 go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=
 go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=
 golang.org/x/arch v0.0.0-20210923205945-b76863e36670/go.mod h1:5om86z9Hs0C8fWVUuoMHwpExlXzs5Tkyp9hOrfG7pp8=
@@ -112,20 +152,20 @@ golang.org/x/arch v0.8.0 h1:3wRIsP3pM4yUptoR96otTUOXI367OS0+c9eeRi9doIc=
 golang.org/x/arch v0.8.0/go.mod h1:FEVrYAQjsQXMVJ1nsMoVVXPZg6p2JE2mx8psSWTDQys=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
-golang.org/x/crypto v0.33.0 h1:IOBPskki6Lysi0lo9qQvbxiQ+FvsCC/YWOecCHAixus=
-golang.org/x/crypto v0.33.0/go.mod h1:bVdXmD7IV/4GdElGPozy6U7lWdRXA4qyRVGJV57uQ5M=
+golang.org/x/crypto v0.54.0 h1:YLIA59K4fiNzHzjnZt2tUJQjQtUWfWbeHBqKtk3eScw=
+golang.org/x/crypto v0.54.0/go.mod h1:KWL8ny2AZdGR2cWmzeHrp2azQPGogOv+HeQaVEXC2dk=
 golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
 golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
-golang.org/x/net v0.25.0 h1:d/OCCoBEUq33pjydKrGQhw7IlUPI2Oylr+8qLx49kac=
-golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM=
+golang.org/x/net v0.56.0 h1:Rw8j/hFzGvJUZwNBXnAtf5sVDVt+65SK2C7IxCxZt5o=
+golang.org/x/net v0.56.0/go.mod h1:D3Ku6r+V6JROoZK144D2XfMHFcMq/0zSfLelVTCFKec=
 golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
 golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.11.0 h1:GGz8+XQP4FvTTrjZPzNKTMFtSXH80RAzG+5ghFPgK9w=
-golang.org/x/sync v0.11.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190422165155-953cdadca894/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
@@ -133,16 +173,16 @@ golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBc
 golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.30.0 h1:QjkSwP/36a20jFYWkSue1YwXzLmsV5Gfq7Eiy72C1uc=
-golang.org/x/sys v0.30.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
 golang.org/x/text v0.3.8/go.mod h1:E6s5w1FMmriuDzIBO73fBruAKo1PCIq6d2Q6DHfQ8WQ=
-golang.org/x/text v0.22.0 h1:bofq7m3/HAFvbF51jz3Q9wLg3jkvSPuiZu/pD1XwgtM=
-golang.org/x/text v0.22.0/go.mod h1:YRoo4H8PVmsu+E3Ou7cqLVH8oXWIHVoX0jqUWALQhfY=
+golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
+golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
 golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
@@ -153,10 +193,14 @@ google.golang.org/grpc v1.64.0 h1:KH3VH9y/MgNQg1dE7b3XfVK0GsPSIzJwdF617gUSbvY=
 google.golang.org/grpc v1.64.0/go.mod h1:oxjF8E3FBnjp+/gVFYdWacaLDx9na1aqy9oovLpxQYg=
 google.golang.org/protobuf v1.34.2 h1:6xV6lTsCfpGD21XK49h7MhtcApnLqkfYgPcdHftf6hg=
 google.golang.org/protobuf v1.34.2/go.mod h1:qYOHts0dSfpeUzUFpOMr/WGzszTmLH+DiWniOlNbLDw=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f h1:BLraFXnmrev5lT+xlilqcH8XK9/i0At2xKjWk4p6zsU=
+gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 nullprogram.com/x/optparse v1.0.0/go.mod h1:KdyPE+Igbe0jQUrVfMqDMeJQIJZEuyV7pjYmp6pbG50=
+oras.land/oras-go/v2 v2.6.2 h1:N04RXngAp1LJKTG6ifz3xHPipasEkWr+hFmInja5YKo=
+oras.land/oras-go/v2 v2.6.2/go.mod h1:PlTtg4JTDJkDe8yVHpM2wz7/YDc00GVas+i4jAW2TZ4=
 rsc.io/pdf v0.1.1/go.mod h1:n8OzWcQ6Sp37PL01nO98y4iUCRdTGarVfzxY20ICaU4=

server/internal/api/auth_providers.go

@@ -0,0 +1,305 @@
+package api
+
+import (
+	"errors"
+	"net/http"
+
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/auth"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/models"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/services"
+	"github.com/coreos/go-oidc/v3/oidc"
+	"github.com/gin-gonic/gin"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+)
+
+type authProviderView struct {
+	models.AuthProvider
+	ClientSecretSet bool   `json:"client_secret_set"`
+	CallbackURL     string `json:"callback_url"`
+}
+
+func viewOf(c *gin.Context, p models.AuthProvider) authProviderView {
+	return authProviderView{
+		AuthProvider:    p,
+		ClientSecretSet: p.ClientSecretEnc != "",
+		CallbackURL:     auth.CallbackURL(c, p.ProviderID),
+	}
+}
+
+// listAuthPresets godoc
+//
+//	@Summary		List SSO presets
+//	@Description	Preset providers (Entra, Google, Okta, GitHub) that expand to a real issuer on save.
+//	@Tags			auth-providers
+//	@Produce		json
+//	@Success		200	{array}		auth.Preset
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/auth/presets [get]
+func listAuthPresets(c *gin.Context) {
+	c.JSON(http.StatusOK, auth.Presets())
+}
+
+// listAuthProviders godoc
+//
+//	@Summary		List SSO providers
+//	@Tags			auth-providers
+//	@Produce		json
+//	@Success		200	{array}		authProviderView
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/auth/providers [get]
+func listAuthProviders(c *gin.Context) {
+	providers, err := services.ListAuthProviders(auth.InstanceID(c))
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	out := make([]authProviderView, 0, len(providers))
+	for _, p := range providers {
+		out = append(out, viewOf(c, p))
+	}
+	c.JSON(http.StatusOK, out)
+}
+
+// createAuthProvider godoc
+//
+//	@Summary		Create an SSO provider
+//	@Tags			auth-providers
+//	@Accept			json
+//	@Produce		json
+//	@Param			body	body		object{name=string,preset=string,issuer_input=string,client_id=string,client_secret=string,enabled=bool}	true	"Provider parameters"
+//	@Success		201	{object}	authProviderView
+//	@Failure		400	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/auth/providers [post]
+func createAuthProvider(c *gin.Context) {
+	var body struct {
+		Name         string `json:"name"`
+		Preset       string `json:"preset"`
+		IssuerInput  string `json:"issuer_input"`
+		ClientID     string `json:"client_id"`
+		ClientSecret string `json:"client_secret"`
+		Enabled      bool   `json:"enabled"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	issuer, err := auth.ExpandIssuer(body.Preset, body.IssuerInput)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	instanceID := auth.InstanceID(c)
+	p, err := services.CreateAuthProvider(&models.AuthProvider{
+		InstanceID: instanceID,
+		Name:       body.Name,
+		Kind:       auth.KindFor(body.Preset),
+		Preset:     body.Preset,
+		Issuer:     issuer,
+		ClientID:   body.ClientID,
+		Scopes:     auth.DefaultScopes(body.Preset),
+		Enabled:    body.Enabled,
+	}, body.ClientSecret)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	services.LogEvent(instanceID, "auth_provider.create", actorFromCtx(c), "", "", p.Name)
+	c.JSON(http.StatusCreated, viewOf(c, *p))
+}
+
+// updateAuthProvider godoc
+//
+//	@Summary		Update an SSO provider
+//	@Tags			auth-providers
+//	@Accept			json
+//	@Produce		json
+//	@Param			id		path		string	true	"Provider ID"
+//	@Param			body	body		object{name=string,issuer_input=string,client_id=string,client_secret=string,enabled=bool,order=int}	true	"Fields to update"
+//	@Success		200	{object}	SavedResponse
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		409	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/auth/providers/{id} [put]
+func updateAuthProvider(c *gin.Context) {
+	var body struct {
+		Name         *string `json:"name"`
+		IssuerInput  *string `json:"issuer_input"`
+		ClientID     *string `json:"client_id"`
+		ClientSecret *string `json:"client_secret"`
+		Enabled      *bool   `json:"enabled"`
+		Order        *int    `json:"order"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	instanceID := auth.InstanceID(c)
+	providerID := c.Param("id")
+
+	existing, err := services.GetAuthProvider(instanceID, providerID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "provider not found"})
+		return
+	}
+
+	if err := guardProviderChange(instanceID, existing, body.Enabled, false); err != nil {
+		if errors.Is(err, services.ErrLockout) {
+			c.JSON(http.StatusConflict, gin.H{"error": err.Error(), "code": "last_provider"})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	in := services.AuthProviderUpdate{
+		Name: body.Name, ClientID: body.ClientID,
+		ClientSecret: body.ClientSecret, Enabled: body.Enabled, Order: body.Order,
+	}
+	if body.IssuerInput != nil {
+		issuer, err := auth.ExpandIssuer(existing.Preset, *body.IssuerInput)
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		in.Issuer = &issuer
+	}
+	if err := services.UpdateAuthProvider(instanceID, providerID, in); err != nil {
+		if errors.Is(err, mongo.ErrNoDocuments) {
+			c.JSON(http.StatusNotFound, gin.H{"error": "provider not found"})
+			return
+		}
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	// Issuer, client ID or secret may have changed; the cached discovery
+	// document was built from the old ones.
+	auth.EvictProvider(providerID)
+	services.LogEvent(instanceID, "auth_provider.update", actorFromCtx(c), "", "", existing.Name)
+	c.JSON(http.StatusOK, SavedResponse{Saved: true})
+}
+
+// deleteAuthProvider godoc
+//
+//	@Summary		Delete an SSO provider
+//	@Description	Refused when the instance would be left with no way in (no local login and no other enabled provider).
+//	@Tags			auth-providers
+//	@Produce		json
+//	@Param			id	path		string	true	"Provider ID"
+//	@Success		200	{object}	DeletedResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		409	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/auth/providers/{id} [delete]
+func deleteAuthProvider(c *gin.Context) {
+	instanceID := auth.InstanceID(c)
+	providerID := c.Param("id")
+
+	existing, err := services.GetAuthProvider(instanceID, providerID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "provider not found"})
+		return
+	}
+	if err := guardProviderChange(instanceID, existing, nil, true); err != nil {
+		if errors.Is(err, services.ErrLockout) {
+			c.JSON(http.StatusConflict, gin.H{"error": err.Error(), "code": "last_provider"})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if err := services.DeleteAuthProvider(instanceID, providerID); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	auth.EvictProvider(providerID)
+	services.LogEvent(instanceID, "auth_provider.delete", actorFromCtx(c), "", "", existing.Name)
+	c.JSON(http.StatusOK, DeletedResponse{Deleted: true})
+}
+
+// guardProviderChange asks whether the instance would still have a way in.
+// Deleting and disabling reach the same condition, so they share one answer.
+func guardProviderChange(instanceID string, existing *models.AuthProvider, enabled *bool, deleting bool) error {
+	losing := deleting || (enabled != nil && !*enabled)
+	if !losing || !existing.Enabled {
+		return nil
+	}
+	n, err := services.CountEnabledAuthProviders(instanceID)
+	if err != nil {
+		return err
+	}
+	return services.CheckLockout(services.IsLocalLoginEnabled(instanceID), n-1)
+}
+
+// ackAuthProviderNotice godoc
+//
+//	@Summary		Acknowledge a provider migration notice
+//	@Tags			auth-providers
+//	@Produce		json
+//	@Param			id	path		string	true	"Provider ID"
+//	@Success		200	{object}	AcknowledgedResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/auth/providers/{id}/ack-notice [post]
+func ackAuthProviderNotice(c *gin.Context) {
+	instanceID := auth.InstanceID(c)
+	providerID := c.Param("id")
+	existing, err := services.GetAuthProvider(instanceID, providerID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "provider not found"})
+		return
+	}
+	if err := services.AckAuthProviderNotice(instanceID, providerID); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	services.LogEvent(instanceID, "auth_provider.ack_notice", actorFromCtx(c), "", "", existing.Name)
+	c.JSON(http.StatusOK, AcknowledgedResponse{Acknowledged: true})
+}
+
+// testAuthProvider godoc
+//
+//	@Summary		Test an SSO provider's reachability
+//	@Description	Proves the configuration is reachable. It signs nobody in.
+//	@Tags			auth-providers
+//	@Produce		json
+//	@Param			id	path		string	true	"Provider ID"
+//	@Success		200	{object}	TestProviderResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/auth/providers/{id}/test [post]
+func testAuthProvider(c *gin.Context) {
+	instanceID := auth.InstanceID(c)
+	p, err := services.GetAuthProvider(instanceID, c.Param("id"))
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "provider not found"})
+		return
+	}
+	if p.Kind == models.KindOAuth2 {
+		// GitHub has no discovery document. The only meaningful check without
+		// a user token is that credentials are present.
+		if p.ClientID == "" || p.ClientSecretEnc == "" {
+			c.JSON(http.StatusOK, TestProviderResponse{OK: false, Message: "client ID and secret are required"})
+			return
+		}
+		c.JSON(http.StatusOK, TestProviderResponse{OK: true, Message: "credentials are configured"})
+		return
+	}
+	if _, err := oidc.NewProvider(c.Request.Context(), p.Issuer); err != nil {
+		c.JSON(http.StatusOK, TestProviderResponse{OK: false, Message: err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, TestProviderResponse{OK: true, Message: "discovery document fetched"})
+}

server/internal/api/channels.go

@@ -3,9 +3,10 @@ package api
 import (
 	"net/http"
 
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/auth"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/models"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/services"
 	"github.com/gin-gonic/gin"
-	"github.com/mrhid6/vantage/server/internal/models"
-	"github.com/mrhid6/vantage/server/internal/services"
 	"go.mongodb.org/mongo-driver/v2/bson"
 )
 
@@ -17,15 +18,46 @@ func registerChannelRoutes(g *gin.RouterGroup) {
 	g.POST("/channels/:id/test", testChannel)
 }
 
+// listChannels godoc
+//
+//	@Summary		List notification channels
+//	@Tags			channels
+//	@Produce		json
+//	@Success		200	{array}		models.NotificationChannel
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/channels [get]
 func listChannels(c *gin.Context) {
-	channels, err := services.ListChannels()
+	channels, err := services.ListChannels(auth.InstanceID(c))
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
-	c.JSON(http.StatusOK, channels)
+	// Redacted here rather than in the service: the dispatchers read the same
+	// documents and need the real credentials, so the masking belongs to the
+	// boundary that hands them to a client.
+	out := make([]models.NotificationChannel, 0, len(channels))
+	for _, ch := range channels {
+		out = append(out, ch.Redacted())
+	}
+	c.JSON(http.StatusOK, out)
 }
 
+// createChannel godoc
+//
+//	@Summary		Create a notification channel
+//	@Tags			channels
+//	@Accept			json
+//	@Produce		json
+//	@Param			body	body		models.NotificationChannel	true	"Channel to create"
+//	@Success		201	{object}	models.NotificationChannel
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		403	{object}	LimitExceededResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/channels [post]
 func createChannel(c *gin.Context) {
 	var ch models.NotificationChannel
 	if err := c.ShouldBindJSON(&ch); err != nil {
@@ -36,14 +68,31 @@ func createChannel(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, gin.H{"error": "name and type are required"})
 		return
 	}
-	created, err := services.CreateChannel(&ch)
+	created, err := services.CreateChannel(auth.InstanceID(c), &ch)
 	if err != nil {
+		if limitStatus(c, err) {
+			return
+		}
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
-	c.JSON(http.StatusCreated, created)
+	c.JSON(http.StatusCreated, created.Redacted())
 }
 
+// updateChannel godoc
+//
+//	@Summary		Update a notification channel
+//	@Tags			channels
+//	@Accept			json
+//	@Produce		json
+//	@Param			id		path	string											true	"Channel ID"
+//	@Param			body	body	object{name=string,type=string,config=map[string]string,enabled=bool}	true	"Fields to update"
+//	@Success		204
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/channels/{id} [put]
 func updateChannel(c *gin.Context) {
 	var body struct {
 		Name    *string            `json:"name"`
@@ -72,25 +121,46 @@ func updateChannel(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, gin.H{"error": "no fields to update"})
 		return
 	}
-	if err := services.UpdateChannel(c.Param("id"), upd); err != nil {
+	if err := services.UpdateChannel(auth.InstanceID(c), c.Param("id"), upd); err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
 	c.Status(http.StatusNoContent)
 }
 
+// deleteChannel godoc
+//
+//	@Summary		Delete a notification channel
+//	@Tags			channels
+//	@Param			id	path	string	true	"Channel ID"
+//	@Success		204
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/channels/{id} [delete]
 func deleteChannel(c *gin.Context) {
-	if err := services.DeleteChannel(c.Param("id")); err != nil {
+	if err := services.DeleteChannel(auth.InstanceID(c), c.Param("id")); err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
 	c.Status(http.StatusNoContent)
 }
 
+// testChannel godoc
+//
+//	@Summary		Send a test notification
+//	@Tags			channels
+//	@Produce		json
+//	@Param			id	path		string	true	"Channel ID"
+//	@Success		200	{object}	StatusResponse
+//	@Failure		502	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/channels/{id}/test [post]
 func testChannel(c *gin.Context) {
-	if err := services.TestChannel(c.Param("id")); err != nil {
+	if err := services.TestChannel(auth.InstanceID(c), c.Param("id")); err != nil {
 		c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
 		return
 	}
-	c.JSON(http.StatusOK, gin.H{"status": "sent"})
+	c.JSON(http.StatusOK, StatusResponse{Status: "sent"})
 }

server/internal/api/console.go

@@ -1,20 +1,37 @@
 package api
 
 import (
+	"errors"
+	"fmt"
+	"log"
 	"net"
 	"net/http"
 	"os"
 	"strconv"
 	"time"
 
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/auth"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/services"
 	"github.com/gin-gonic/gin"
-	"github.com/mrhid6/vantage/server/internal/services"
 	"github.com/wwt/guac"
 )
 
-// POST /api/console/connect
-// Body: { server_id, protocol, key_id?, rdp_username?, rdp_password? }
-// Returns: { session_id, token, ws_path }
+// consoleConnect godoc
+//
+//	@Summary		Open a browser console session
+//	@Description	Mints a one-time session token for the /console/tunnel websocket. Requires a live agent — answers 409 agent_offline otherwise.
+//	@Tags			console
+//	@Accept			json
+//	@Produce		json
+//	@Param			body	body		object{server_id=string,protocol=string,key_id=string,rdp_username=string,rdp_password=string,ssh_username=string}	true	"Session parameters"
+//	@Success		200	{object}	ConsoleConnectResponse
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		409	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/console/connect [post]
 func consoleConnect(c *gin.Context) {
 	var body struct {
 		ServerID    string `json:"server_id" binding:"required"`
@@ -29,13 +46,22 @@ func consoleConnect(c *gin.Context) {
 		return
 	}
 
-	srv, err := services.GetServer(body.ServerID)
+	srv, err := services.GetServer(auth.InstanceID(c), body.ServerID)
 	if err != nil {
 		c.JSON(http.StatusNotFound, gin.H{"error": "server not found"})
 		return
 	}
 
-	sess, err := services.CreateConsoleSession(body.ServerID, body.Protocol, body.KeyID, actorFromCtx(c), c.ClientIP())
+	if srv.Status != "active" {
+		c.JSON(http.StatusConflict, gin.H{
+			"error": "agent_offline",
+			"message": "The agent on this server is not connected. " +
+				"Console sessions are relayed by the agent, so it must be online.",
+		})
+		return
+	}
+
+	sess, err := services.CreateConsoleSession(auth.InstanceID(c), body.ServerID, body.Protocol, body.KeyID, actorFromCtx(c), c.ClientIP())
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
@@ -47,31 +73,29 @@ func consoleConnect(c *gin.Context) {
 	}
 
 	if (body.Protocol == "rdp" || body.Protocol == "vnc") && (body.RDPUsername != "" || body.RDPPassword != "") {
-		if err := services.StashConsoleRDPCreds(sess.SessionID, body.RDPUsername, body.RDPPassword); err != nil {
+		if err := services.StashConsoleRDPCreds(auth.InstanceID(c), sess.SessionID, body.RDPUsername, body.RDPPassword); err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
 		}
 	}
 
 	if body.Protocol == "ssh" {
-		if err := services.SetConsoleSSHUser(sess.SessionID, body.SSHUsername); err != nil {
+		if err := services.SetConsoleSSHUser(auth.InstanceID(c), sess.SessionID, body.SSHUsername); err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 			return
 		}
 	}
 
-	services.LogEvent("console.opened", actorFromCtx(c), srv.ServerID, "",
-		"console session opened ("+body.Protocol+")")
+	services.LogEvent(auth.InstanceID(c), "console.opened", actorFromCtx(c), srv.ServerID, "",
+		"console session opened ("+body.Protocol+", agent-relayed)")
 
-	c.JSON(http.StatusOK, gin.H{
-		"session_id": sess.SessionID,
-		"token":      token,
-		"ws_path":    "/api/console/tunnel",
+	c.JSON(http.StatusOK, ConsoleConnectResponse{
+		SessionID: sess.SessionID,
+		Token:     token,
+		WSPath:    "/api/console/tunnel",
 	})
 }
 
-// queryIntDefault reads a positive integer query param, falling back to def
-// when absent, unparseable, or non-positive.
 func queryIntDefault(r *http.Request, key string, def int) int {
 	v, err := strconv.Atoi(r.URL.Query().Get(key))
 	if err != nil || v <= 0 {
@@ -80,60 +104,152 @@ func queryIntDefault(r *http.Request, key string, def int) int {
 	return v
 }
 
-// GET /api/console/tunnel?token=... (WebSocket upgrade)
+// consoleTunnel upgrades the browser's WebSocket and joins it to guacd.
+//
+// Every branch here logs. That is deliberate and worth keeping: this handler
+// spans four hops (session store, agent dispatch, relay announcement, guacd),
+// any of which can fail, and the client is told the same near-useless thing by
+// most of them — a 500 that guacamole then reports as an *upstream* error,
+// naming the wrong hop entirely. Without a line per branch the only evidence a
+// failure leaves is a GIN status code, and with several replicas you cannot
+// even tell which process produced it.
+//
+// Lines are prefixed with the session ID so one attempt can be followed across
+// pods, and the pod's own hostname so it is obvious which one served it.
+// consoleTunnel godoc
+//
+//	@Summary		Console websocket tunnel
+//	@Description	Upgrades the browser's connection to a websocket and joins it to guacd, relayed through the agent. Consumes the one-time session token from /console/connect.
+//	@Tags			console
+//	@Param			token	query	string	true	"One-time session token"
+//	@Success		101
+//	@Failure		401	{object}	ErrorResponse
+//	@Failure		403	{object}	ErrorResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		409	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/console/tunnel [get]
 func consoleTunnel(c *gin.Context) {
+	host, _ := os.Hostname()
+
 	token := c.Query("token")
 	sessionID, err := services.VerifySessionToken(token)
 	if err != nil {
+		log.Printf("console[%s]: reject: invalid session token: %v", host, err)
 		c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid token"})
 		return
 	}
-	sess, err := services.GetConsoleSession(sessionID)
+
+	// Bound to the session from here on, so every later line correlates.
+	tlog := func(format string, args ...any) {
+		log.Printf("console[%s %s]: "+format, append([]any{host, sessionID}, args...)...)
+	}
+	tlog("tunnel opened by %s", actorFromCtx(c))
+
+	instanceID := auth.InstanceID(c)
+	sess, err := services.GetConsoleSession(instanceID, sessionID)
 	if err != nil {
+		tlog("reject: console session not found: %v", err)
 		c.JSON(http.StatusNotFound, gin.H{"error": "session not found"})
 		return
 	}
 
-	// User-bound: the caller (authenticated via session cookie) must be the same
-	// user who opened the session. Blocks a leaked token being used by someone else.
 	if actor := actorFromCtx(c); actor != sess.User {
+		tlog("reject: session belongs to %s, not %s", sess.User, actor)
 		c.JSON(http.StatusForbidden, gin.H{"error": "session belongs to another user"})
 		return
 	}
 
-	// Single-use: atomically spend the token so a replay within its TTL is rejected.
-	if err := services.ConsumeSessionToken(sessionID); err != nil {
+	if err := services.ConsumeSessionToken(instanceID, sessionID); err != nil {
+		tlog("reject: token already consumed: %v", err)
 		c.JSON(http.StatusUnauthorized, gin.H{"error": "token already used"})
 		return
 	}
 
-	srv, err := services.GetServer(sess.ServerID)
+	srv, err := services.GetServer(auth.InstanceID(c), sess.ServerID)
 	if err != nil {
+		tlog("reject: server %s not found: %v", sess.ServerID, err)
 		c.JSON(http.StatusNotFound, gin.H{"error": "server not found"})
 		return
 	}
+	tlog("server %s (%s), protocol %s", srv.ServerID, srv.Hostname, sess.Protocol)
 
-	// Decrypt private key + passphrase in-memory only (ssh).
 	var privKey, passphrase string
 	if sess.Protocol == "ssh" && sess.KeyID != "" {
-		privKey, err = services.GetPrivateKey(sess.KeyID)
+		privKey, err = services.GetPrivateKey(auth.InstanceID(c), sess.KeyID)
 		if err != nil {
+			tlog("reject: key %s has no private material: %v", sess.KeyID, err)
 			c.JSON(http.StatusBadRequest, gin.H{"error": "selected key has no private material"})
 			return
 		}
 		passphrase, _ = services.GetPassphrase(sess.KeyID)
+		tlog("ssh key %s loaded (passphrase=%t)", sess.KeyID, passphrase != "")
 	}
 
 	var rdpUser, rdpPass string
 	if sess.Protocol == "rdp" || sess.Protocol == "vnc" {
-		rdpUser, rdpPass, err = services.ConsumeConsoleRDPCreds(sessionID)
+		rdpUser, rdpPass, err = services.ConsumeConsoleRDPCreds(instanceID, sessionID)
 		if err != nil {
+			tlog("reject: could not consume %s credentials: %v", sess.Protocol, err)
 			c.JSON(http.StatusInternalServerError, gin.H{"error": "could not load credentials"})
 			return
 		}
+		tlog("%s credentials consumed (user=%t)", sess.Protocol, rdpUser != "")
 	}
-	gp, err := services.BuildGuacParams(srv, sess.Protocol, sess.SSHUsername, privKey, passphrase, rdpUser, rdpPass)
+
+	targetPort, err := services.TargetPort(srv, sess.Protocol)
 	if err != nil {
+		tlog("reject: no target port for %s: %v", sess.Protocol, err)
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	tlog("opening relay to %s:%d", srv.ServerID, targetPort)
+
+	relay, err := services.OpenConsoleProxy(instanceID, srv.ServerID, targetPort)
+	if err != nil {
+		if errors.Is(err, services.ErrAgentOffline) {
+			tlog("reject: agent offline")
+			c.JSON(http.StatusConflict, gin.H{"error": "agent_offline"})
+			return
+		}
+		// The client is deliberately told nothing specific, so this is the only
+		// place the real reason exists — a failed dispatch and a relay that was
+		// never announced are the same generic 500 to the browser.
+		tlog("reject: open relay: %v", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "could not open relay"})
+		return
+	}
+	tlog("relay %s ready at %s:%d", relay.ProxyID, relay.Host, relay.Port)
+	// guac.WebsocketServer.ServeHTTP returns before installing its
+	// OnDisconnect handler when the connect callback errors, which is exactly
+	// the path every relay failure this proxy introduces takes (the agent
+	// never claims it, dial_refused, guacd never dials, rejected). Emitting
+	// console.proxy_failed and ending the session here, unconditionally on
+	// teardown, is what makes those failures reach the audit log at all;
+	// OnDisconnect below only sees the rarer case of a session that was fully
+	// established and then failed.
+	defer func() {
+		relay.Close()
+		if reason := relay.Reason(); reason != "" {
+			tlog("relay %s ended: %s", relay.ProxyID, reason)
+			services.LogEvent(instanceID, "console.proxy_failed", actorFromCtx(c), srv.ServerID, "",
+				fmt.Sprintf("console relay failed: %s (proxy_id=%s, port=%d)", reason, relay.ProxyID, relay.Port))
+		} else {
+			tlog("relay %s closed cleanly", relay.ProxyID)
+		}
+		_ = services.EndConsoleSession(instanceID, sessionID)
+		tlog("tunnel finished")
+	}()
+
+	services.LogEvent(instanceID, "console.proxy_opened", actorFromCtx(c), srv.ServerID, "",
+		fmt.Sprintf("console relay opened (proxy_id=%s, port=%d)", relay.ProxyID, relay.Port))
+
+	gp, err := services.BuildGuacParams(sess.Protocol, sess.SSHUsername, privKey, passphrase,
+		rdpUser, rdpPass, relay.Host, relay.Port)
+	if err != nil {
+		tlog("reject: build guacd parameters: %v", err)
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
@@ -143,7 +259,6 @@ func consoleTunnel(c *gin.Context) {
 		guacdAddr = "guacd:4822"
 	}
 
-	// Build a guac tunnel config from our params.
 	connect := func(r *http.Request) (guac.Tunnel, error) {
 		config := guac.NewGuacamoleConfiguration()
 		config.Protocol = gp.Protocol
@@ -154,24 +269,41 @@ func consoleTunnel(c *gin.Context) {
 		config.OptimalScreenHeight = queryIntDefault(r, "height", 768)
 		config.OptimalResolution = queryIntDefault(r, "dpi", 96)
 
+		// Resolution is logged separately from the dial: a headless guacd
+		// Service returns pod addresses, and which one was picked is the
+		// difference between "guacd refused" and "we called the wrong guacd".
 		addr, err := net.ResolveTCPAddr("tcp", guacdAddr)
 		if err != nil {
+			tlog("guacd: resolve %s: %v", guacdAddr, err)
 			return nil, err
 		}
+		tlog("guacd: dialling %s (%s)", guacdAddr, addr.String())
+
 		conn, err := net.DialTCP("tcp", nil, addr)
 		if err != nil {
+			tlog("guacd: dial %s: %v", addr.String(), err)
 			return nil, err
 		}
+
+		// The handshake is where guacd connects onward to the relay, so a
+		// failure here is guacd reporting it could not reach %s:%d — the hop
+		// that has been hardest to see from either end.
 		stream := guac.NewStream(conn, guac.SocketTimeout)
 		if err := stream.Handshake(config); err != nil {
+			tlog("guacd: handshake for %s to relay %s:%d: %v",
+				gp.Protocol, relay.Host, relay.Port, err)
 			return nil, err
 		}
+		tlog("guacd: tunnel established (%s %dx%d)",
+			gp.Protocol, config.OptimalScreenWidth, config.OptimalScreenHeight)
 		return guac.NewSimpleTunnel(stream), nil
 	}
 
+	// Teardown (proxy_failed audit + EndConsoleSession) lives in the deferred
+	// func above, not here: this only fires once a tunnel was actually
+	// established, and letting both paths log would double the audit event.
 	wsServer := guac.NewWebsocketServer(connect)
-	wsServer.OnDisconnect = func(id string, r *http.Request, t guac.Tunnel) {
-		_ = services.EndConsoleSession(sessionID)
-	}
+	tlog("serving websocket")
 	wsServer.ServeHTTP(c.Writer, c.Request)
+	tlog("websocket returned")
 }

server/internal/api/docs/doc.go

@@ -0,0 +1,23 @@
+// Package docs holds the generated OpenAPI document and the vendored Scalar
+// bundle that renders it.
+//
+// openapi.json is generated by `swag init` and committed rather than built into
+// the image: server/Dockerfile produces a scratch runtime from a Go build
+// stage, and adding codegen there means putting the toolchain in the image.
+// server-deploy.yml regenerates and diffs it, so an annotation edited without
+// regenerating fails the build.
+//
+// scalar.standalone.js is vendored from
+// https://cdn.jsdelivr.net/npm/@scalar/api-reference@latest/dist/browser/standalone.js
+// and refreshed by hand. Fetched at build time it would break an air-gapped
+// install; fetched at page load it would break an air-gapped install more
+// visibly.
+package docs
+
+import _ "embed"
+
+//go:embed openapi.json
+var OpenAPI []byte
+
+//go:embed scalar.standalone.js
+var ScalarJS []byte

server/internal/api/handlers.go

@@ -1,48 +1,75 @@
 package api
 
 import (
+	"errors"
 	"fmt"
 	"net/http"
 	"os"
 	"strconv"
 
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/auth"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/models"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/services"
 	"github.com/gin-gonic/gin"
-	"github.com/mrhid6/vantage/server/internal/auth"
-	"github.com/mrhid6/vantage/server/internal/models"
-	"github.com/mrhid6/vantage/server/internal/services"
 )
 
 func actorFromCtx(c *gin.Context) string {
-	if sess := auth.GetSessionFromContext(c); sess != nil && sess.Email != "" {
-		return sess.Email
+	sess := auth.GetSessionFromContext(c)
+	if sess == nil || sess.Email == "" {
+		return "admin"
 	}
-	return "admin"
+	// The actor stays the human, because a token acts on their behalf and the
+	// log has to name somebody. The credential is appended so a person clicking
+	// and their CI job are told apart.
+	if sess.TokenID != "" {
+		return fmt.Sprintf("%s (via token:%s)", sess.Email, sess.TokenName)
+	}
+	return sess.Email
 }
 
 func RegisterRoutes(r *gin.Engine) {
+	r.GET("/healthz", handleHealthz)
+	r.GET("/readyz", handleReadyz)
+
 	r.GET("/install", handleInstallScript)
 	r.GET("/install.ps1", handleInstallScriptWindows)
 	r.GET("/update", handleUpdateScript)
 	r.GET("/update.ps1", handleUpdateScriptWindows)
 
-	// ESO read endpoint — bearer-token auth, not session auth, so Kubernetes
-	// External Secrets Operator can call it. Lives under /api (so the reverse
-	// proxy routes it to the backend) but on a distinct subpath to avoid
-	// colliding with the session-authed GET /api/secrets/:group. Returns a
-	// group as flat JSON.
 	r.GET("/api/secrets/:group/values", secretsReadAuth(), esoGetGroup)
 
-	// Auth endpoints (no session required)
-	r.GET("/auth/login", auth.HandleLogin)
-	r.GET("/auth/callback", auth.HandleCallback)
-	r.GET("/auth/logout", auth.HandleLogout)
+	r.GET("/auth/bootstrap-status", auth.HandleBootstrapStatus)
+	r.POST("/auth/bootstrap", auth.HandleBootstrap)
+	r.POST("/auth/login", auth.HandleLocalLogin)
+	r.POST("/auth/logout", auth.HandleLogout)
 	r.GET("/auth/me", auth.HandleMe)
+	r.GET("/auth/oidc/:providerId/start", auth.HandleSSOStart)
+	r.GET("/auth/oidc/:providerId/callback", auth.HandleSSOCallback)
+	r.GET("/auth/providers", auth.HandleListPublicProviders)
+
+	// Completely public: no session, no token, no licence gate. Mounted here
+	// rather than under /api precisely so that none of those apply.
+	r.GET("/public/status/:pageId", RateLimitPublicStatus(), getPublicStatusPage)
 
-	// API endpoints protected by session middleware
 	apiGroup := r.Group("/api")
 	apiGroup.Use(auth.Middleware())
+	// Scope enforcement sits between authentication and the licence gate, and
+	// no-ops for cookie sessions. It is mounted here rather than per route so
+	// a route added later is covered by where it lives, not by memory.
+	apiGroup.Use(RequireScopes())
+	apiGroup.Use(RateLimitTokens())
+	// Deny by default: every non-GET route under /api is gated unless it is on
+	// the exemption list in licence.go. A route added later is covered because
+	// of where it is mounted, not because someone remembered.
+	apiGroup.Use(RequireActiveLicense())
 	{
+		apiGroup.GET("/license", getLicence)
+		apiGroup.POST("/license", auth.RequireRole("owner"), postLicence)
+
 		apiGroup.GET("/servers", listServers)
+		// Static segment, registered alongside /servers/:id exactly as
+		// /servers/new already is — gin resolves statics ahead of wildcards.
+		apiGroup.GET("/servers/tags", listKnownTags)
 		apiGroup.POST("/servers", createServer)
 		apiGroup.GET("/servers/new", newServer)
 		apiGroup.POST("/servers/new", newServer)
@@ -51,14 +78,28 @@ func RegisterRoutes(r *gin.Engine) {
 		apiGroup.POST("/servers/:id/generate-key", generateKey)
 		apiGroup.POST("/servers/:id/update-agent", updateAgent)
 		apiGroup.POST("/servers/:id/apply-updates", applyUpdates)
+		apiGroup.PUT("/servers/:id/tags", putServerTags)
 
 		apiGroup.GET("/agent/latest-version", getLatestAgentVersion)
 
 		apiGroup.GET("/audit", listAuditEvents)
 
-		apiGroup.GET("/settings", getSettings)
-		apiGroup.PUT("/settings", saveSettings)
-		apiGroup.POST("/settings/secrets-token", rotateSecretsToken)
+		apiGroup.GET("/tokens", listTokens)
+		apiGroup.GET("/tokens/scopes", listTokenScopes)
+		apiGroup.POST("/tokens", createToken)
+		apiGroup.DELETE("/tokens/:id", revokeToken)
+
+		apiGroup.GET("/openapi.json", getOpenAPI)
+		apiGroup.GET("/docs", getAPIDocs)
+		apiGroup.GET("/docs/scalar.js", getScalarJS)
+
+		settings := apiGroup.Group("/settings")
+		settings.Use(auth.RequireRole("owner", "admin"))
+		{
+			settings.GET("", getSettings)
+			settings.PUT("", saveSettings)
+			settings.POST("/secrets-token", rotateSecretsToken)
+		}
 
 		apiGroup.GET("/secrets", listSecretGroups)
 		apiGroup.POST("/secrets", createSecretGroup)
@@ -76,17 +117,80 @@ func RegisterRoutes(r *gin.Engine) {
 		apiGroup.POST("/keys/:id/assign", assignKey)
 		apiGroup.DELETE("/keys/:id/assign/:serverId", revokeAssignment)
 
-		apiGroup.POST("/console/connect", consoleConnect)
-		apiGroup.GET("/console/tunnel", consoleTunnel)
+		apiGroup.POST("/console/connect", RequireFeature("console"), consoleConnect)
+		apiGroup.GET("/console/tunnel", RequireFeature("console"), consoleTunnel)
 
 		registerWorkflowRoutes(apiGroup)
 		registerMonitorRoutes(apiGroup)
 		registerChannelRoutes(apiGroup)
+
+		instance := apiGroup.Group("/instance")
+		instance.Use(auth.RequireRole("owner", "admin"))
+		{
+			instance.GET("/users", listInstanceUsers)
+			instance.POST("/users", createInstanceUser)
+			instance.PUT("/users/:id/role", updateInstanceUserRole)
+			instance.DELETE("/users/:id", deleteInstanceUser)
+		}
+
+		providers := apiGroup.Group("/auth/providers")
+		providers.Use(auth.RequireRole("owner", "admin"), RequireFeature("oidc"))
+		{
+			providers.GET("", listAuthProviders)
+			providers.POST("", createAuthProvider)
+			providers.PUT("/:id", updateAuthProvider)
+			providers.DELETE("/:id", deleteAuthProvider)
+			providers.POST("/:id/test", testAuthProvider)
+			providers.POST("/:id/ack-notice", ackAuthProviderNotice)
+		}
+		apiGroup.GET("/auth/presets", auth.RequireRole("owner", "admin"), listAuthPresets)
+
+		apiGroup.GET("/vulnerabilities", listVulnerabilities)
+		apiGroup.GET("/vulnerabilities/summary", vulnerabilitySummary)
+		apiGroup.POST("/vulnerabilities/rescan", auth.RequireRole("owner", "admin"), rescanVulnerabilities)
+		apiGroup.POST("/vulnerabilities/:id/accept", auth.RequireRole("owner", "admin"), acceptFinding)
+		apiGroup.DELETE("/vulnerabilities/:id/accept", auth.RequireRole("owner", "admin"), unacceptFinding)
+		apiGroup.GET("/servers/:id/vulnerabilities", listServerVulnerabilities)
+		apiGroup.GET("/servers/:id/packages", getServerPackages)
+		apiGroup.GET("/packages/search", searchPackages)
+		apiGroup.GET("/vuln-rules", listVulnRules)
+		apiGroup.POST("/vuln-rules", auth.RequireRole("owner", "admin"), createVulnRule)
+		apiGroup.PUT("/vuln-rules/:id", auth.RequireRole("owner", "admin"), updateVulnRule)
+		apiGroup.DELETE("/vuln-rules/:id", auth.RequireRole("owner", "admin"), deleteVulnRule)
+
+		// Control actions and log reads are owner|admin: container output is
+		// arbitrary and cannot be masked, so a member who can see the fleet
+		// still cannot read its logs.
+		apiGroup.GET("/workloads", listWorkloads)
+		apiGroup.GET("/servers/:id/workloads", getServerWorkloads)
+		apiGroup.POST("/servers/:id/workloads/refresh", refreshServerWorkloads)
+		apiGroup.POST("/servers/:id/workloads/:wid/action", auth.RequireRole("owner", "admin"), controlWorkload)
+		apiGroup.GET("/servers/:id/workloads/:wid/logs", auth.RequireRole("owner", "admin"), getWorkloadLogs)
+
+		registerStatusPageRoutes(apiGroup)
 	}
 }
 
+// listServers godoc
+//
+//	@Summary		List servers
+//	@Description	Returns every server in the instance, optionally filtered by tag (repeatable, key:value).
+//	@Tags			servers
+//	@Produce		json
+//	@Param			tag	query		[]string	false	"Filter by tag as key:value, repeatable"
+//	@Success		200	{array}		models.Server
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers [get]
 func listServers(c *gin.Context) {
-	servers, err := services.ListServers()
+	sel, err := services.ParseTagFilters(c.QueryArray("tag"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	servers, err := services.ListServersFiltered(auth.InstanceID(c), sel)
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
@@ -94,35 +198,127 @@ func listServers(c *gin.Context) {
 	c.JSON(http.StatusOK, servers)
 }
 
-func createServer(c *gin.Context) {
-	s, token, err := services.CreateServer()
+// listKnownTags godoc
+//
+//	@Summary		List known tags
+//	@Description	Returns every tag key currently used by any server, with the values seen for each.
+//	@Tags			servers
+//	@Produce		json
+//	@Success		200	{object}	map[string][]string
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers/tags [get]
+func listKnownTags(c *gin.Context) {
+	tags, err := services.KnownTags(auth.InstanceID(c))
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
-	c.JSON(http.StatusCreated, gin.H{
-		"server":    s,
-		"token":     token,
-		"server_id": s.ServerID,
+	c.JSON(http.StatusOK, tags)
+}
+
+// putServerTags godoc
+//
+//	@Summary		Replace a server's tags
+//	@Description	Replaces the whole tag map for a server. Last write wins.
+//	@Tags			servers
+//	@Accept			json
+//	@Produce		json
+//	@Param			id		path		string				true	"Server ID"
+//	@Param			body	body		object{tags=map[string]string}	true	"New tag map"
+//	@Success		200	{object}	TagsResponse
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers/{id}/tags [put]
+func putServerTags(c *gin.Context) {
+	var body struct {
+		Tags map[string]string `json:"tags"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid body"})
+		return
+	}
+
+	instanceID := auth.InstanceID(c)
+	serverID := c.Param("id")
+
+	before, err := services.GetServer(instanceID, serverID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "server not found"})
+		return
+	}
+
+	if err := services.SetServerTags(instanceID, serverID, body.Tags); err != nil {
+		if errors.Is(err, services.ErrInvalidTag) {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	services.LogEvent(instanceID, "server.tags_updated", actorFromCtx(c), serverID, "",
+		fmt.Sprintf("tags %v -> %v", before.Tags, body.Tags))
+	c.JSON(http.StatusOK, TagsResponse{Tags: body.Tags})
+}
+
+// createServer godoc
+//
+//	@Summary		Add a server
+//	@Description	Creates a server record and a single-use pre-registration token (TTL 1 hour).
+//	@Tags			servers
+//	@Produce		json
+//	@Success		201	{object}	CreateServerResponse
+//	@Failure		403	{object}	LimitExceededResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers [post]
+func createServer(c *gin.Context) {
+	s, token, err := services.CreateServer(auth.InstanceID(c))
+	if err != nil {
+		if limitStatus(c, err) {
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusCreated, CreateServerResponse{
+		Server:   s,
+		Token:    token,
+		ServerID: s.ServerID,
 	})
 }
 
+// newServer godoc
+//
+//	@Summary		Add a server (install page)
+//	@Description	Identical to POST /servers; also reachable by GET for the install page. Mints a new pre-registration token.
+//	@Tags			servers
+//	@Produce		json
+//	@Success		200	{object}	NewServerResponse
+//	@Failure		403	{object}	LimitExceededResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers/new [get]
+//	@Router			/servers/new [post]
 func newServer(c *gin.Context) {
-	s, token, err := services.CreateServer()
+	s, token, err := services.CreateServer(auth.InstanceID(c))
 	if err != nil {
+		if limitStatus(c, err) {
+			return
+		}
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
-	services.LogEvent("server.created", actorFromCtx(c), s.ServerID, "", "pre-registration token issued")
+	services.LogEvent(auth.InstanceID(c), "server.created", actorFromCtx(c), s.ServerID, "", "pre-registration token issued")
 
-	giteaHost := os.Getenv("GITEA_HOST")
-	if giteaHost == "" {
-		giteaHost = "gitea.example.com"
-	}
-	host := os.Getenv("PUBLIC_HOST")
-	if host == "" {
-		host = "https://vantage.example.com"
-	}
+	host := publicHostFromRequest(c)
 
 	installCmd := fmt.Sprintf(
 		`curl -fsSL "%s/install?server_id=%s&token=%s" | bash`,
@@ -134,39 +330,57 @@ func newServer(c *gin.Context) {
 		host, s.ServerID, token,
 	)
 
-	c.JSON(http.StatusOK, gin.H{
-		"server_id":          s.ServerID,
-		"pre_reg_token":      token,
-		"install_command":    installCmd,
-		"install_command_ps": installCmdPS,
+	c.JSON(http.StatusOK, NewServerResponse{
+		ServerID:         s.ServerID,
+		PreRegToken:      token,
+		InstallCommand:   installCmd,
+		InstallCommandPS: installCmdPS,
 	})
 }
 
+// getServer godoc
+//
+//	@Summary		Get a server
+//	@Description	Returns a server together with its resolved key assignments.
+//	@Tags			servers
+//	@Produce		json
+//	@Param			id	path		string	true	"Server ID"
+//	@Success		200	{object}	ServerDetailResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers/{id} [get]
 func getServer(c *gin.Context) {
 	id := c.Param("id")
-	s, err := services.GetServer(id)
+	s, err := services.GetServer(auth.InstanceID(c), id)
 	if err != nil {
 		c.JSON(http.StatusNotFound, gin.H{"error": "server not found"})
 		return
 	}
 
-	assignments, _ := services.GetAssignmentsWithKeysForServer(id)
+	assignments, _ := services.GetAssignmentsWithKeysForServer(auth.InstanceID(c), id)
 
-	// Build response matching ServerWithKeys shape expected by frontend
-	type serverResponse struct {
-		*models.Server
-		Keys interface{} `json:"keys"`
-	}
-	c.JSON(http.StatusOK, serverResponse{
+	c.JSON(http.StatusOK, ServerDetailResponse{
 		Server: s,
 		Keys:   assignments,
 	})
 }
 
+// deleteServer godoc
+//
+//	@Summary		Delete a server
+//	@Tags			servers
+//	@Produce		json
+//	@Param			id	path		string	true	"Server ID"
+//	@Success		200	{object}	DeletedResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers/{id} [delete]
 func deleteServer(c *gin.Context) {
 	id := c.Param("id")
-	s, _ := services.GetServer(id)
-	if err := services.DeleteServer(id); err != nil {
+	s, _ := services.GetServer(auth.InstanceID(c), id)
+	if err := services.DeleteServer(auth.InstanceID(c), id); err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
@@ -174,10 +388,25 @@ func deleteServer(c *gin.Context) {
 	if s != nil {
 		hostname = s.Hostname
 	}
-	services.LogEvent("server.deleted", actorFromCtx(c), id, "", fmt.Sprintf("server %s deleted", hostname))
-	c.JSON(http.StatusOK, gin.H{"deleted": true})
+	services.LogEvent(auth.InstanceID(c), "server.deleted", actorFromCtx(c), id, "", fmt.Sprintf("server %s deleted", hostname))
+	c.JSON(http.StatusOK, DeletedResponse{Deleted: true})
 }
 
+// generateKey godoc
+//
+//	@Summary		Generate a key on a server
+//	@Description	Dispatches an agent command that generates a keypair on the target server and reports it back.
+//	@Tags			keys
+//	@Accept			json
+//	@Produce		json
+//	@Param			id		path		string					true	"Server ID"
+//	@Param			body	body		object{label=string,key_type=string,key_size=int,passphrase=string,comment=string}	false	"Key generation parameters"
+//	@Success		202	{object}	GenerateKeyResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		503	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers/{id}/generate-key [post]
 func generateKey(c *gin.Context) {
 	id := c.Param("id")
 
@@ -193,7 +422,7 @@ func generateKey(c *gin.Context) {
 		body.Label = "generated"
 	}
 
-	s, err := services.GetServer(id)
+	s, err := services.GetServer(auth.InstanceID(c), id)
 	if err != nil {
 		c.JSON(http.StatusNotFound, gin.H{"error": "server not found"})
 		return
@@ -211,16 +440,26 @@ func generateKey(c *gin.Context) {
 		return
 	}
 
-	services.LogEvent("key.generation_dispatched", actorFromCtx(c), s.ServerID, "", fmt.Sprintf("key generation dispatched (label=%s type=%s)", body.Label, body.KeyType))
-	c.JSON(http.StatusAccepted, gin.H{
-		"message":    "key generation command sent to agent",
-		"command_id": cmdID,
-		"server_id":  s.ServerID,
+	services.LogEvent(auth.InstanceID(c), "key.generation_dispatched", actorFromCtx(c), s.ServerID, "", fmt.Sprintf("key generation dispatched (label=%s type=%s)", body.Label, body.KeyType))
+	c.JSON(http.StatusAccepted, GenerateKeyResponse{
+		Message:   "key generation command sent to agent",
+		CommandID: cmdID,
+		ServerID:  s.ServerID,
 	})
 }
 
+// listKeys godoc
+//
+//	@Summary		List keys
+//	@Tags			keys
+//	@Produce		json
+//	@Success		200	{array}		models.Key
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/keys [get]
 func listKeys(c *gin.Context) {
-	keys, err := services.ListKeys()
+	keys, err := services.ListKeys(auth.InstanceID(c))
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
@@ -228,6 +467,19 @@ func listKeys(c *gin.Context) {
 	c.JSON(http.StatusOK, keys)
 }
 
+// createKey godoc
+//
+//	@Summary		Upload a key
+//	@Tags			keys
+//	@Accept			json
+//	@Produce		json
+//	@Param			body	body		object{label=string,public_key=string,private_key=string,passphrase=string}	true	"Key material"
+//	@Success		201	{object}	models.Key
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/keys [post]
 func createKey(c *gin.Context) {
 	var body struct {
 		Label      string `json:"label" binding:"required"`
@@ -240,49 +492,80 @@ func createKey(c *gin.Context) {
 		return
 	}
 
-	key, err := services.CreateKey(body.Label, body.PublicKey, "uploaded", "", body.PrivateKey, body.Passphrase)
+	key, err := services.CreateKey(auth.InstanceID(c), body.Label, body.PublicKey, "uploaded", "", body.PrivateKey, body.Passphrase)
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
-	services.LogEvent("key.uploaded", actorFromCtx(c), "", key.KeyID, fmt.Sprintf("key '%s' uploaded", key.Label))
+	services.LogEvent(auth.InstanceID(c), "key.uploaded", actorFromCtx(c), "", key.KeyID, fmt.Sprintf("key '%s' uploaded", key.Label))
 	c.JSON(http.StatusCreated, key)
 }
 
+// getPrivateKey godoc
+//
+//	@Summary		Get a key's private material
+//	@Description	Returns the decrypted private key. Reading is a keys:read action even though the material is sensitive.
+//	@Tags			keys
+//	@Produce		json
+//	@Param			id	path		string	true	"Key ID"
+//	@Success		200	{object}	PrivateKeyResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/keys/{id}/private-key [get]
 func getPrivateKey(c *gin.Context) {
 	id := c.Param("id")
-	plaintext, err := services.GetPrivateKey(id)
+	plaintext, err := services.GetPrivateKey(auth.InstanceID(c), id)
 	if err != nil {
 		c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
 		return
 	}
-	c.JSON(http.StatusOK, gin.H{"private_key": plaintext})
+	c.JSON(http.StatusOK, PrivateKeyResponse{PrivateKey: plaintext})
 }
 
+// getKey godoc
+//
+//	@Summary		Get a key
+//	@Description	Returns a key together with the servers it is assigned to.
+//	@Tags			keys
+//	@Produce		json
+//	@Param			id	path		string	true	"Key ID"
+//	@Success		200	{object}	KeyDetailResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/keys/{id} [get]
 func getKey(c *gin.Context) {
 	id := c.Param("id")
-	key, err := services.GetKey(id)
+	key, err := services.GetKey(auth.InstanceID(c), id)
 	if err != nil {
 		c.JSON(http.StatusNotFound, gin.H{"error": "key not found"})
 		return
 	}
 
-	assignments, _ := services.GetAssignmentsWithServers(id)
+	assignments, _ := services.GetAssignmentsWithServers(auth.InstanceID(c), id)
 
-	type keyResponse struct {
-		*models.Key
-		Assignments any `json:"assignments"`
-	}
-	c.JSON(http.StatusOK, keyResponse{
+	c.JSON(http.StatusOK, KeyDetailResponse{
 		Key:         key,
 		Assignments: assignments,
 	})
 }
 
+// deleteKey godoc
+//
+//	@Summary		Delete a key
+//	@Tags			keys
+//	@Produce		json
+//	@Param			id	path		string	true	"Key ID"
+//	@Success		200	{object}	DeletedResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/keys/{id} [delete]
 func deleteKey(c *gin.Context) {
 	id := c.Param("id")
-	k, _ := services.GetKey(id)
-	if err := services.DeleteKey(id); err != nil {
+	k, _ := services.GetKey(auth.InstanceID(c), id)
+	if err := services.DeleteKey(auth.InstanceID(c), id); err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
@@ -290,10 +573,24 @@ func deleteKey(c *gin.Context) {
 	if k != nil {
 		label = k.Label
 	}
-	services.LogEvent("key.deleted", actorFromCtx(c), "", id, fmt.Sprintf("key '%s' deleted", label))
-	c.JSON(http.StatusOK, gin.H{"deleted": true})
+	services.LogEvent(auth.InstanceID(c), "key.deleted", actorFromCtx(c), "", id, fmt.Sprintf("key '%s' deleted", label))
+	c.JSON(http.StatusOK, DeletedResponse{Deleted: true})
 }
 
+// assignKey godoc
+//
+//	@Summary		Assign a key to a server
+//	@Tags			keys
+//	@Accept			json
+//	@Produce		json
+//	@Param			id		path		string							true	"Key ID"
+//	@Param			body	body		object{server_id=string}	true	"Target server"
+//	@Success		201	{object}	models.Assignment
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/keys/{id}/assign [post]
 func assignKey(c *gin.Context) {
 	keyID := c.Param("id")
 	var body struct {
@@ -304,39 +601,76 @@ func assignKey(c *gin.Context) {
 		return
 	}
 
-	a, err := services.AssignKey(keyID, body.ServerID)
+	a, err := services.AssignKey(auth.InstanceID(c), keyID, body.ServerID)
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
-	services.LogEvent("key.assigned", actorFromCtx(c), body.ServerID, keyID, fmt.Sprintf("key %s assigned to server %s", keyID, body.ServerID))
+	services.LogEvent(auth.InstanceID(c), "key.assigned", actorFromCtx(c), body.ServerID, keyID, fmt.Sprintf("key %s assigned to server %s", keyID, body.ServerID))
 	c.JSON(http.StatusCreated, a)
 }
 
+// revokeAssignment godoc
+//
+//	@Summary		Revoke a key assignment
+//	@Description	Soft revocation: sets revoked_at rather than deleting, preserving audit history.
+//	@Tags			keys
+//	@Produce		json
+//	@Param			id			path		string	true	"Key ID"
+//	@Param			serverId	path		string	true	"Server ID"
+//	@Success		200	{object}	RevokedResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/keys/{id}/assign/{serverId} [delete]
 func revokeAssignment(c *gin.Context) {
 	keyID := c.Param("id")
 	serverID := c.Param("serverId")
 
-	if err := services.RevokeAssignment(keyID, serverID); err != nil {
+	if err := services.RevokeAssignment(auth.InstanceID(c), keyID, serverID); err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
-	services.LogEvent("key.revoked", actorFromCtx(c), serverID, keyID, fmt.Sprintf("key %s revoked from server %s", keyID, serverID))
-	c.JSON(http.StatusOK, gin.H{"revoked": true})
+	services.LogEvent(auth.InstanceID(c), "key.revoked", actorFromCtx(c), serverID, keyID, fmt.Sprintf("key %s revoked from server %s", keyID, serverID))
+	c.JSON(http.StatusOK, RevokedResponse{Revoked: true})
 }
 
+// getLatestAgentVersion godoc
+//
+//	@Summary		Get the latest agent version
+//	@Description	Reads the latest agent/v* tag from the Gitea release API.
+//	@Tags			servers
+//	@Produce		json
+//	@Success		200	{object}	AgentVersionResponse
+//	@Failure		503	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/agent/latest-version [get]
 func getLatestAgentVersion(c *gin.Context) {
 	version, err := services.GetLatestAgentVersion()
 	if err != nil {
 		c.JSON(http.StatusServiceUnavailable, gin.H{"error": err.Error()})
 		return
 	}
-	c.JSON(http.StatusOK, gin.H{"version": version})
+	c.JSON(http.StatusOK, AgentVersionResponse{Version: version})
 }
 
+// updateAgent godoc
+//
+//	@Summary		Update a server's agent
+//	@Description	Dispatches UpdateAgentCmd to the agent, telling it to download and replace itself.
+//	@Tags			servers
+//	@Produce		json
+//	@Param			id	path		string	true	"Server ID"
+//	@Success		202	{object}	UpdateAgentResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		503	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers/{id}/update-agent [post]
 func updateAgent(c *gin.Context) {
 	id := c.Param("id")
-	s, err := services.GetServer(id)
+	s, err := services.GetServer(auth.InstanceID(c), id)
 	if err != nil {
 		c.JSON(http.StatusNotFound, gin.H{"error": "server not found"})
 		return
@@ -347,16 +681,29 @@ func updateAgent(c *gin.Context) {
 		c.JSON(http.StatusServiceUnavailable, gin.H{"error": err.Error()})
 		return
 	}
-	services.LogEvent("agent.update_dispatched", actorFromCtx(c), s.ServerID, "", fmt.Sprintf("agent update dispatched to %s (version %s)", s.Hostname, version))
-	c.JSON(http.StatusAccepted, gin.H{
-		"message": "update command sent to agent",
-		"version": version,
+	services.LogEvent(auth.InstanceID(c), "agent.update_dispatched", actorFromCtx(c), s.ServerID, "", fmt.Sprintf("agent update dispatched to %s (version %s)", s.Hostname, version))
+	c.JSON(http.StatusAccepted, UpdateAgentResponse{
+		Message: "update command sent to agent",
+		Version: version,
 	})
 }
 
+// applyUpdates godoc
+//
+//	@Summary		Apply pending OS updates on a server
+//	@Description	Dispatches ApplyUpdatesCmd. Exempt from the licence gate: security patching is never paywalled.
+//	@Tags			servers
+//	@Produce		json
+//	@Param			id	path		string	true	"Server ID"
+//	@Success		202	{object}	MessageResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		503	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/servers/{id}/apply-updates [post]
 func applyUpdates(c *gin.Context) {
 	id := c.Param("id")
-	s, err := services.GetServer(id)
+	s, err := services.GetServer(auth.InstanceID(c), id)
 	if err != nil {
 		c.JSON(http.StatusNotFound, gin.H{"error": "server not found"})
 		return
@@ -366,15 +713,19 @@ func applyUpdates(c *gin.Context) {
 		c.JSON(http.StatusServiceUnavailable, gin.H{"error": err.Error()})
 		return
 	}
-	services.LogEvent("updates.applied", actorFromCtx(c), s.ServerID, "", fmt.Sprintf("package update command dispatched to %s", s.Hostname))
-	c.JSON(http.StatusAccepted, gin.H{"message": "apply updates command sent to agent"})
+	services.LogEvent(auth.InstanceID(c), "updates.applied", actorFromCtx(c), s.ServerID, "", fmt.Sprintf("package update command dispatched to %s", s.Hostname))
+	c.JSON(http.StatusAccepted, MessageResponse{Message: "apply updates command sent to agent"})
 }
 
+// handleUpdateScript serves a dynamically generated shell script that
+// downloads and installs the latest agent. Deliberately not in the generated
+// OpenAPI document: it is registered on the bare engine, not under the /api
+// group the document's BasePath assumes, so a @Router annotation here would
+// publish /api/update — a path that 404s — rather than the real top-level
+// /update. It serves a shell script, not JSON, so there is nothing lost by
+// leaving it out of a JSON API reference.
 func handleUpdateScript(c *gin.Context) {
-	giteaHost := os.Getenv("GITEA_HOST")
-	if giteaHost == "" {
-		giteaHost = "gitea.example.com"
-	}
+	giteaHost := "gitea.hostxtra.co.uk"
 
 	script := fmt.Sprintf(`#!/usr/bin/env bash
 set -euo pipefail
@@ -389,7 +740,7 @@ case "$ARCH" in
 esac
 
 # Get latest agent release tag
-LATEST=$(curl -fsSL "https://${GITEA_HOST}/api/v1/repos/mrhid6/vantage/releases?limit=10" \
+LATEST=$(curl -fsSL "https://${GITEA_HOST}/api/v1/repos/vantage/vantage-agent/releases?limit=10" \
   | grep -o '"tag_name":"agent/v[^"]*"' | head -1 | sed 's/"tag_name":"//;s/"//')
 
 if [ -z "$LATEST" ]; then
@@ -399,8 +750,8 @@ fi
 
 VERSION="${LATEST#agent/}"
 LATEST_ENCODED="${LATEST/\//%%2F}"
-BINARY_URL="https://${GITEA_HOST}/mrhid6/vantage/releases/download/${LATEST_ENCODED}/vantage-agent-linux-${ARCH}"
-CHECKSUM_URL="https://${GITEA_HOST}/mrhid6/vantage/releases/download/${LATEST_ENCODED}/checksums.txt"
+BINARY_URL="https://${GITEA_HOST}/vantage/vantage-agent/releases/download/${LATEST_ENCODED}/vantage-agent-linux-${ARCH}"
+CHECKSUM_URL="https://${GITEA_HOST}/vantage/vantage-agent/releases/download/${LATEST_ENCODED}/checksums.txt"
 
 echo "Updating vantage-agent to ${VERSION} (${ARCH})..."
 
@@ -426,23 +777,59 @@ echo "vantage-agent updated to ${VERSION} and restarted."
 	c.String(http.StatusOK, script)
 }
 
+// listAuditEvents godoc
+//
+//	@Summary		List audit events
+//	@Description	Every mutating API path writes an audit event. Paginated with a total, since a short page is not proof of the end of the log.
+//	@Tags			audit
+//	@Produce		json
+//	@Param			q			query		string	false	"Free-text search"
+//	@Param			category	query		string	false	"Filter by category"
+//	@Param			limit		query		int		false	"Max events to return"
+//	@Param			skip		query		int		false	"Events to skip"
+//	@Success		200	{object}	AuditEventsResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/audit [get]
 func listAuditEvents(c *gin.Context) {
-	limit := int64(100)
+	f := services.AuditFilter{
+		Search:   c.Query("q"),
+		Category: c.Query("category"),
+	}
 	if l := c.Query("limit"); l != "" {
 		if n, err := strconv.ParseInt(l, 10, 64); err == nil && n > 0 {
-			limit = n
+			f.Limit = n
 		}
 	}
-	events, err := services.ListAuditEvents(limit)
+	if s := c.Query("skip"); s != "" {
+		if n, err := strconv.ParseInt(s, 10, 64); err == nil && n >= 0 {
+			f.Skip = n
+		}
+	}
+
+	events, total, err := services.ListAuditEvents(auth.InstanceID(c), f)
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
-	c.JSON(http.StatusOK, events)
+	// An object rather than a bare array: a page is meaningless without the
+	// total it came from, and a short page is not proof of the end of the log.
+	c.JSON(http.StatusOK, AuditEventsResponse{Events: events, Total: total})
 }
 
+// getSettings godoc
+//
+//	@Summary		Get instance settings
+//	@Tags			settings
+//	@Produce		json
+//	@Success		200	{object}	models.Settings
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/settings [get]
 func getSettings(c *gin.Context) {
-	s, err := services.GetSettings()
+	s, err := services.GetSettings(auth.InstanceID(c))
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
@@ -450,24 +837,58 @@ func getSettings(c *gin.Context) {
 	c.JSON(http.StatusOK, s)
 }
 
+// saveSettings godoc
+//
+//	@Summary		Save instance settings
+//	@Description	Owner and admin only. Refuses a change that would leave neither local login nor an enabled auth provider.
+//	@Tags			settings
+//	@Accept			json
+//	@Produce		json
+//	@Param			body	body		object{alerts=models.AlertSettings,workflow_log_retention_days=int,local_login_enabled=bool,api_token_max_days=int}	true	"Settings to save"
+//	@Success		200	{object}	SavedResponse
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		409	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/settings [put]
 func saveSettings(c *gin.Context) {
 	var body struct {
 		Alerts                   models.AlertSettings `json:"alerts"`
-		Email                    models.EmailSettings `json:"email"`
 		WorkflowLogRetentionDays *int                 `json:"workflow_log_retention_days"`
+		LocalLoginEnabled        *bool                `json:"local_login_enabled"`
+		APITokenMaxDays          *int                 `json:"api_token_max_days"`
 	}
 	if err := c.ShouldBindJSON(&body); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
-	if err := services.SaveSettings(body.Alerts, body.Email, body.WorkflowLogRetentionDays); err != nil {
+	if body.APITokenMaxDays != nil && *body.APITokenMaxDays < 0 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "api_token_max_days cannot be negative"})
+		return
+	}
+	if err := services.SaveSettings(auth.InstanceID(c), body.Alerts, body.WorkflowLogRetentionDays, body.LocalLoginEnabled, body.APITokenMaxDays); err != nil {
+		if errors.Is(err, services.ErrLockout) {
+			c.JSON(http.StatusConflict, gin.H{"error": err.Error(), "code": "local_login_required"})
+			return
+		}
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
-	services.LogEvent("settings.updated", actorFromCtx(c), "", "", "alert settings updated")
-	c.JSON(http.StatusOK, gin.H{"saved": true})
+	services.LogEvent(auth.InstanceID(c), "settings.updated", actorFromCtx(c), "", "", "alert settings updated")
+	if body.APITokenMaxDays != nil {
+		services.LogEvent(auth.InstanceID(c), "settings.token_policy_updated", actorFromCtx(c), "", "",
+			fmt.Sprintf("API token maximum lifetime set to %d day(s); 0 means no cap", *body.APITokenMaxDays))
+	}
+	c.JSON(http.StatusOK, SavedResponse{Saved: true})
 }
 
+// handleInstallScript serves a dynamically generated shell script that
+// downloads, verifies and installs the agent, seeded with a pre-registration
+// token. Deliberately not in the generated OpenAPI document, for the same
+// reason as handleUpdateScript: it is registered on the bare engine, outside
+// the /api group the document's BasePath assumes, so a @Router annotation
+// would publish a /api/install path that 404s.
 func handleInstallScript(c *gin.Context) {
 	serverID := c.Query("server_id")
 	token := c.Query("token")
@@ -476,14 +897,7 @@ func handleInstallScript(c *gin.Context) {
 	if giteaHost == "" {
 		giteaHost = "gitea.example.com"
 	}
-	publicHost := os.Getenv("PUBLIC_HOST")
-	if publicHost == "" {
-		publicHost = "vantage.example.com"
-	}
 	grpcHost := os.Getenv("GRPC_HOST")
-	if grpcHost == "" {
-		grpcHost = publicHost
-	}
 
 	script := fmt.Sprintf(`#!/usr/bin/env bash
 set -euo pipefail
@@ -491,9 +905,6 @@ set -euo pipefail
 SERVER_ID="%s"
 TOKEN="%s"
 GITEA_HOST="%s"
-KM_HOST="%s"
-KM_HOST="${KM_HOST#https://}"
-KM_HOST="${KM_HOST#http://}"
 GRPC_HOST="%s"
 GRPC_HOST="${GRPC_HOST#https://}"
 GRPC_HOST="${GRPC_HOST#http://}"
@@ -506,7 +917,7 @@ case "$ARCH" in
 esac
 
 # Get latest agent release tag
-LATEST=$(curl -fsSL "https://${GITEA_HOST}/api/v1/repos/mrhid6/vantage/releases?limit=10" \
+LATEST=$(curl -fsSL "https://${GITEA_HOST}/api/v1/repos/vantage/vantage-agent/releases?limit=10" \
   | grep -o '"tag_name":"agent/v[^"]*"' | head -1 | sed 's/"tag_name":"//;s/"//')
 
 if [ -z "$LATEST" ]; then
@@ -516,8 +927,8 @@ fi
 
 VERSION="${LATEST#agent/}"
 LATEST_ENCODED="${LATEST/\//%%2F}"
-BINARY_URL="https://${GITEA_HOST}/mrhid6/vantage/releases/download/${LATEST_ENCODED}/vantage-agent-linux-${ARCH}"
-CHECKSUM_URL="https://${GITEA_HOST}/mrhid6/vantage/releases/download/${LATEST_ENCODED}/checksums.txt"
+BINARY_URL="https://${GITEA_HOST}/vantage/vantage-agent/releases/download/${LATEST_ENCODED}/vantage-agent-linux-${ARCH}"
+CHECKSUM_URL="https://${GITEA_HOST}/vantage/vantage-agent/releases/download/${LATEST_ENCODED}/checksums.txt"
 
 echo "Installing vantage-agent ${VERSION} (${ARCH})..."
 
@@ -566,7 +977,7 @@ systemctl daemon-reload
 systemctl enable --now vantage-agent
 
 echo "vantage-agent installed and started."
-`, serverID, token, giteaHost, publicHost, grpcHost)
+`, serverID, token, giteaHost, grpcHost)
 
 	c.Header("Content-Type", "text/x-shellscript")
 	c.String(http.StatusOK, script)

server/internal/api/health.go

@@ -0,0 +1,61 @@
+package api
+
+import (
+	"context"
+	"net/http"
+	"time"
+
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/auth"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/db"
+	"github.com/gin-gonic/gin"
+)
+
+// The two probes answer different questions on purpose.
+//
+// /healthz is liveness: the process is up and serving. It touches nothing
+// external, because a Mongo outage must not make Kubernetes restart every
+// server pod — a restart loop cannot fix someone else's database, and it
+// destroys every open command stream and console session on the way.
+//
+// /readyz is readiness: this pod can serve a request end to end, which needs
+// both Mongo and Redis. A failing readiness probe pulls the pod out of the
+// Service and leaves it running, which is the behaviour that matters during a
+// dependency blip.
+//
+// Both sit outside /api, so neither the session middleware nor the licence
+// gate applies. Neither reveals anything beyond up or down.
+
+const probeTimeout = 2 * time.Second
+
+func handleHealthz(c *gin.Context) {
+	c.JSON(http.StatusOK, gin.H{"status": "ok"})
+}
+
+func handleReadyz(c *gin.Context) {
+	ctx, cancel := context.WithTimeout(c.Request.Context(), probeTimeout)
+	defer cancel()
+
+	checks := gin.H{"mongo": "ok", "redis": "ok"}
+	ready := true
+
+	if db.Client == nil {
+		checks["mongo"] = "not initialised"
+		ready = false
+	} else if err := db.Client.Ping(ctx, nil); err != nil {
+		checks["mongo"] = "unreachable"
+		ready = false
+	}
+
+	if err := auth.PingRedis(ctx); err != nil {
+		checks["redis"] = "unreachable"
+		ready = false
+	}
+
+	status := http.StatusOK
+	state := "ok"
+	if !ready {
+		status = http.StatusServiceUnavailable
+		state = "unready"
+	}
+	c.JSON(status, gin.H{"status": state, "checks": checks})
+}

server/internal/api/install_ps1.go

@@ -12,17 +12,9 @@ func handleInstallScriptWindows(c *gin.Context) {
 	serverID := c.Query("server_id")
 	token := c.Query("token")
 
-	giteaHost := os.Getenv("GITEA_HOST")
-	if giteaHost == "" {
-		giteaHost = "gitea.example.com"
-	}
+	giteaHost := "gitea.hostxtra.co.uk"
+
 	grpcHost := os.Getenv("GRPC_HOST")
-	if grpcHost == "" {
-		grpcHost = os.Getenv("PUBLIC_HOST")
-	}
-	if grpcHost == "" {
-		grpcHost = "vantage.example.com"
-	}
 
 	script := fmt.Sprintf(
 		"#Requires -RunAsAdministrator\n"+
@@ -33,11 +25,11 @@ func handleInstallScriptWindows(c *gin.Context) {
 			"$GiteaHost = \"%s\"\n"+
 			"$ServerUrl = \"%s\" -replace '^https?://',''\n"+
 			"\n"+
-			"$rel = Invoke-RestMethod -Uri \"https://$GiteaHost/api/v1/repos/mrhid6/vantage/releases?limit=10\"\n"+
+			"$rel = Invoke-RestMethod -Uri \"https://$GiteaHost/api/v1/repos/vantage/vantage-agent/releases?limit=10\"\n"+
 			"$tag = ($rel | Where-Object { $_.tag_name -like 'agent/v*' } | Select-Object -First 1).tag_name\n"+
 			"if (-not $tag) { throw \"Could not determine latest agent version\" }\n"+
 			"$enc = $tag -replace '/','%%2F'\n"+
-			"$base = \"https://$GiteaHost/mrhid6/vantage/releases/download/$enc\"\n"+
+			"$base = \"https://$GiteaHost/vantage/vantage-agent/releases/download/$enc\"\n"+
 			"\n"+
 			"$tmp = Join-Path $env:TEMP \"vantage-agent.msi\"\n"+
 			"Invoke-WebRequest -Uri \"$base/vantage-agent.msi\" -OutFile $tmp\n"+
@@ -55,14 +47,8 @@ func handleInstallScriptWindows(c *gin.Context) {
 	c.String(http.StatusOK, script)
 }
 
-// handleUpdateScriptWindows serves a PowerShell one-liner that upgrades an
-// already-installed Windows agent. No server_id/token needed: the MSI is a
-// MajorUpgrade and setup.ps1 preserves the existing config on upgrade.
 func handleUpdateScriptWindows(c *gin.Context) {
-	giteaHost := os.Getenv("GITEA_HOST")
-	if giteaHost == "" {
-		giteaHost = "gitea.example.com"
-	}
+	giteaHost := "gitea.hostxtra.co.uk"
 
 	script := fmt.Sprintf(
 		"#Requires -RunAsAdministrator\n"+
@@ -70,11 +56,11 @@ func handleUpdateScriptWindows(c *gin.Context) {
 			"\n"+
 			"$GiteaHost = \"%s\"\n"+
 			"\n"+
-			"$rel = Invoke-RestMethod -Uri \"https://$GiteaHost/api/v1/repos/mrhid6/vantage/releases?limit=10\"\n"+
+			"$rel = Invoke-RestMethod -Uri \"https://$GiteaHost/api/v1/repos/vantage/vantage-agent/releases?limit=10\"\n"+
 			"$tag = ($rel | Where-Object { $_.tag_name -like 'agent/v*' } | Select-Object -First 1).tag_name\n"+
 			"if (-not $tag) { throw \"Could not determine latest agent version\" }\n"+
 			"$enc = $tag -replace '/','%%2F'\n"+
-			"$base = \"https://$GiteaHost/mrhid6/vantage/releases/download/$enc\"\n"+
+			"$base = \"https://$GiteaHost/vantage/vantage-agent/releases/download/$enc\"\n"+
 			"\n"+
 			"$tmp = Join-Path $env:TEMP \"vantage-agent.msi\"\n"+
 			"Invoke-WebRequest -Uri \"$base/vantage-agent.msi\" -OutFile $tmp\n"+

server/internal/api/instance.go

@@ -0,0 +1,177 @@
+package api
+
+import (
+	"errors"
+	"net/http"
+
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/auth"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/models"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/services"
+	"github.com/gin-gonic/gin"
+)
+
+// listInstanceUsers godoc
+//
+//	@Summary		List instance members
+//	@Tags			instance-users
+//	@Produce		json
+//	@Success		200	{array}		models.User
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/instance/users [get]
+func listInstanceUsers(c *gin.Context) {
+	users, err := services.ListUsers(auth.InstanceID(c))
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, users)
+}
+
+func actorMayGrantOwner(c *gin.Context) bool {
+	return auth.Role(c) == models.RoleOwner
+}
+
+// createInstanceUser godoc
+//
+//	@Summary		Create an instance member
+//	@Description	Only an owner can create another owner.
+//	@Tags			instance-users
+//	@Accept			json
+//	@Produce		json
+//	@Param			body	body		object{email=string,password=string,role=string}	true	"New member"
+//	@Success		201	{object}	models.User
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		403	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/instance/users [post]
+func createInstanceUser(c *gin.Context) {
+	var body struct {
+		Email    string `json:"email"`
+		Password string `json:"password"`
+		Role     string `json:"role"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil || body.Email == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "email required"})
+		return
+	}
+	if body.Role == "" {
+		body.Role = models.RoleMember
+	}
+	if !models.ValidRole(body.Role) {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "role must be one of owner, admin, or member"})
+		return
+	}
+	if body.Role == models.RoleOwner && !actorMayGrantOwner(c) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "only an owner can create another owner"})
+		return
+	}
+	u, err := services.CreateUser(auth.InstanceID(c), body.Email, body.Password, body.Role, "local")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusCreated, u)
+}
+
+// updateInstanceUserRole godoc
+//
+//	@Summary		Change an instance member's role
+//	@Description	A caller cannot change their own role. Only an owner can change owner roles.
+//	@Tags			instance-users
+//	@Accept			json
+//	@Produce		json
+//	@Param			id		path		string					true	"User ID"
+//	@Param			body	body		object{role=string}	true	"New role"
+//	@Success		200	{object}	OKResponse
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		403	{object}	ErrorResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		409	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/instance/users/{id}/role [put]
+func updateInstanceUserRole(c *gin.Context) {
+	var body struct {
+		Role string `json:"role"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil || body.Role == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "role required"})
+		return
+	}
+	if !models.ValidRole(body.Role) {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "role must be one of owner, admin, or member"})
+		return
+	}
+
+	instanceID, targetID := auth.InstanceID(c), c.Param("id")
+	if targetID == auth.UserID(c) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "you cannot change your own role"})
+		return
+	}
+	target, err := services.GetUserInInstance(instanceID, targetID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "user not found"})
+		return
+	}
+	if (body.Role == models.RoleOwner || target.Role == models.RoleOwner) && !actorMayGrantOwner(c) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "only an owner can change owner roles"})
+		return
+	}
+
+	if err := services.UpdateUserRole(instanceID, targetID, body.Role); err != nil {
+		c.JSON(orgUserErrStatus(err), gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, OKResponse{OK: true})
+}
+
+// deleteInstanceUser godoc
+//
+//	@Summary		Remove an instance member
+//	@Description	A caller cannot remove their own account. Only an owner can remove another owner.
+//	@Tags			instance-users
+//	@Produce		json
+//	@Param			id	path		string	true	"User ID"
+//	@Success		200	{object}	DeletedResponse
+//	@Failure		403	{object}	ErrorResponse
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		409	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/instance/users/{id} [delete]
+func deleteInstanceUser(c *gin.Context) {
+	instanceID, targetID := auth.InstanceID(c), c.Param("id")
+	if targetID == auth.UserID(c) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "you cannot remove your own account"})
+		return
+	}
+	target, err := services.GetUserInInstance(instanceID, targetID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "user not found"})
+		return
+	}
+	if target.Role == models.RoleOwner && !actorMayGrantOwner(c) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "only an owner can remove another owner"})
+		return
+	}
+
+	if err := services.DeleteUser(instanceID, targetID); err != nil {
+		c.JSON(orgUserErrStatus(err), gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, DeletedResponse{Deleted: true})
+}
+
+func orgUserErrStatus(err error) int {
+	// 409 rather than 403: the caller has the right to manage members, and the
+	// request is refused because of the resource's state, not their permissions.
+	if errors.Is(err, services.ErrLastOwner) || errors.Is(err, services.ErrHQManaged) {
+		return http.StatusConflict
+	}
+	return http.StatusInternalServerError
+}

server/internal/api/licence.go

@@ -0,0 +1,272 @@
+package api
+
+import (
+	"errors"
+	"net/http"
+	"sync"
+	"time"
+
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/auth"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/services"
+	"gitea.hostxtra.co.uk/vantage/vantage-shared/license"
+	"github.com/gin-gonic/gin"
+)
+
+// licenceExemptPaths are routes that must work while a licence is expired or
+// missing, because they are how a customer recovers or stays safe.
+//
+//	/api/license          pasting a valid licence is the way out of degraded mode
+//	apply-updates         security patching is never paywalled
+//
+// All DELETE requests are exempt separately (see RequireActiveLicense): a
+// customer downgraded below their current usage must be able to delete their
+// way back under the cap.
+var licenceExemptPaths = map[string]bool{
+	"/api/license": true,
+}
+
+// mutatingGETs are routes that change state despite their method. GET is
+// otherwise always allowed through, so these have to be named explicitly:
+// GET /api/servers/new mints a pre-registration token, which is a creation.
+var mutatingGETs = map[string]bool{
+	"/api/servers/new": true,
+}
+
+func licenceExempt(c *gin.Context) bool {
+	if c.Request.Method == http.MethodDelete {
+		return true
+	}
+	if licenceExemptPaths[c.FullPath()] {
+		return true
+	}
+	if c.FullPath() == "/api/servers/:id/apply-updates" {
+		return true
+	}
+	return false
+}
+
+// RequireActiveLicense blocks mutating requests when the licence is not valid.
+//
+// Mounted on the /api group, so a route added tomorrow is gated because of where
+// it lives rather than because someone remembered. GET and HEAD always pass —
+// reading is never blocked.
+func RequireActiveLicense() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if (c.Request.Method == http.MethodGet || c.Request.Method == http.MethodHead) &&
+			!mutatingGETs[c.FullPath()] {
+			c.Next()
+			return
+		}
+		if licenceExempt(c) {
+			c.Next()
+			return
+		}
+
+		st := services.GetLicenseState(auth.InstanceID(c))
+		if st.Active() {
+			c.Next()
+			return
+		}
+
+		c.AbortWithStatusJSON(http.StatusForbidden, gin.H{
+			"error":  "license_required",
+			"state":  st.Status,
+			"reason": st.Reason,
+		})
+	}
+}
+
+// RequireFeature blocks a route when the licence does not grant a feature.
+func RequireFeature(name string) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		st := services.GetLicenseState(auth.InstanceID(c))
+		if st.Feature(name) {
+			c.Next()
+			return
+		}
+		c.AbortWithStatusJSON(http.StatusForbidden, gin.H{
+			"error":   "feature_unavailable",
+			"feature": name,
+		})
+	}
+}
+
+type licenceResponse struct {
+	InstanceID    string               `json:"instance_id"`
+	State         license.State        `json:"state"`
+	Reason        string               `json:"reason,omitempty"`
+	Tier          string               `json:"tier,omitempty"`
+	SupportLevel  string               `json:"support_level,omitempty"`
+	ExpiresAt     *time.Time           `json:"expires_at,omitempty"`
+	DaysRemaining *int                 `json:"days_remaining,omitempty"`
+	Limits        license.Limits       `json:"limits"`
+	Features      map[string]bool      `json:"features"`
+	Usage         licenceUsageResponse `json:"usage"`
+	Source        string               `json:"source"`
+	// Deployment is what tells the UI whether this instance owns its licence.
+	// On cloud the licence is injected by admin and there is nothing for a
+	// customer to paste, so the UI sends them to the portal instead.
+	Deployment string `json:"deployment"`
+}
+
+type licenceUsageResponse struct {
+	Servers      int `json:"servers"`
+	Monitors     int `json:"monitors"`
+	SecretGroups int `json:"secret_groups"`
+	Channels     int `json:"channels"`
+}
+
+// getLicence godoc
+//
+//	@Summary		Get this instance's licence state
+//	@Tags			licence
+//	@Produce		json
+//	@Success		200	{object}	licenceResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/license [get]
+func getLicence(c *gin.Context) {
+	instanceID := auth.InstanceID(c)
+	st := services.GetLicenseState(instanceID)
+	servers, monitors, groups, channels := services.LicenseUsage(instanceID)
+
+	resp := licenceResponse{
+		InstanceID:   instanceID,
+		State:        st.Status,
+		Reason:       st.Reason,
+		Tier:         st.Tier,
+		SupportLevel: st.SupportLevel,
+		ExpiresAt:    st.ExpiresAt,
+		Limits:       st.Limits,
+		Features:     st.Features,
+		Usage:        licenceUsageResponse{Servers: servers, Monitors: monitors, SecretGroups: groups, Channels: channels},
+		Source:       st.Source,
+		Deployment:   services.DeploymentMode(),
+	}
+	if st.ExpiresAt != nil {
+		d := int(time.Until(*st.ExpiresAt).Hours() / 24)
+		resp.DaysRemaining = &d
+	}
+	c.JSON(http.StatusOK, resp)
+}
+
+var (
+	licencePostMu     sync.Mutex
+	licencePostCounts = map[string][]time.Time{}
+)
+
+const licencePostLimit = 10
+
+// licencePostAllowed permits 10 attempts per instance per hour.
+func licencePostAllowed(instanceID string) bool {
+	cutoff := time.Now().Add(-time.Hour)
+
+	licencePostMu.Lock()
+	defer licencePostMu.Unlock()
+
+	kept := licencePostCounts[instanceID][:0]
+	for _, t := range licencePostCounts[instanceID] {
+		if t.After(cutoff) {
+			kept = append(kept, t)
+		}
+	}
+	if len(kept) >= licencePostLimit {
+		licencePostCounts[instanceID] = kept
+		return false
+	}
+	licencePostCounts[instanceID] = append(kept, time.Now())
+	return true
+}
+
+// postLicence godoc
+//
+//	@Summary		Set this instance's licence
+//	@Description	Self-hosted only; a cloud instance's licence is injected by admin and this endpoint answers 409 cloud_managed. Exempt from the licence gate, since pasting a valid licence is the way out of degraded mode. Rate limited to 10 attempts per instance per hour.
+//	@Tags			licence
+//	@Accept			json
+//	@Produce		json
+//	@Param			body	body		object{blob=string}	true	"Licence key blob"
+//	@Success		200	{object}	LicencePostResponse
+//	@Failure		400	{object}	LicenceErrorResponse
+//	@Failure		409	{object}	LicenceErrorResponse
+//	@Failure		429	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/license [post]
+func postLicence(c *gin.Context) {
+	instanceID := auth.InstanceID(c)
+
+	// A cloud instance's licence is written by admin straight into the database
+	// (admin/internal/inject), never through this endpoint, so refusing here
+	// cannot break injection. Hiding the form in web/ is a courtesy; this is the
+	// boundary, the same split as an hq-managed user's role.
+	if services.DeploymentMode() == license.DeploymentCloud {
+		c.JSON(http.StatusConflict, gin.H{
+			"error":  "This instance's licence is managed in Vantage HQ and cannot be set here.",
+			"reason": "cloud_managed",
+		})
+		return
+	}
+
+	if !licencePostAllowed(instanceID) {
+		c.JSON(http.StatusTooManyRequests, gin.H{
+			"error": "Too many licence attempts. Try again later.",
+		})
+		return
+	}
+
+	var body struct {
+		Blob string `json:"blob"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "a licence key is required"})
+		return
+	}
+
+	st, err := services.StoreLicense(instanceID, body.Blob)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{
+			"error":  licenceRejectionMessage(err.Error(), instanceID),
+			"reason": err.Error(),
+		})
+		return
+	}
+
+	services.LogEvent(instanceID, "license.updated", actorFromCtx(c), "", "",
+		"licence accepted (tier "+st.Tier+")")
+	c.JSON(http.StatusOK, LicencePostResponse{State: st.Status, Tier: st.Tier, ExpiresAt: st.ExpiresAt})
+}
+
+// licenceRejectionMessage turns a machine reason into something a person can act
+// on. The instance ID is included in the mismatch case because that is the one
+// piece of information the customer needs and cannot guess.
+func licenceRejectionMessage(reason, instanceID string) string {
+	switch reason {
+	case license.ReasonBadSignature:
+		return "This licence key is not valid. Check it was copied in full."
+	case license.ReasonDeploymentMismatch:
+		return "This licence was issued for a different instance type."
+	case license.ReasonInstanceMismatch:
+		return "This licence was issued for a different instance. Your instance ID is " + instanceID + "."
+	case license.ReasonNoLicense:
+		return "No licence key was provided."
+	default:
+		return "This licence could not be accepted."
+	}
+}
+
+// limitStatus maps a LimitError to a 403 body. Handlers that create countable
+// resources call this so the UI gets a machine-readable limit name.
+func limitStatus(c *gin.Context, err error) bool {
+	var le *services.LimitError
+	if !errors.As(err, &le) {
+		return false
+	}
+	c.JSON(http.StatusForbidden, LimitExceededResponse{
+		Error:   "limit_exceeded",
+		Limit:   le.Limit,
+		Current: le.Current,
+		Max:     le.Max,
+	})
+	return true
+}

server/internal/api/monitors.go

@@ -2,11 +2,13 @@ package api
 
 import (
 	"net/http"
+	"strconv"
 	"time"
 
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/auth"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/models"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/services"
 	"github.com/gin-gonic/gin"
-	"github.com/mrhid6/vantage/server/internal/models"
-	"github.com/mrhid6/vantage/server/internal/services"
 	"go.mongodb.org/mongo-driver/v2/bson"
 )
 
@@ -18,10 +20,21 @@ func registerMonitorRoutes(g *gin.RouterGroup) {
 	g.DELETE("/monitors/:id", deleteMonitor)
 	g.GET("/monitors/:id/incidents", getMonitorIncidents)
 	g.GET("/monitors/:id/uptime", getMonitorUptime)
+	g.GET("/monitors/:id/samples", getMonitorSamples)
 }
 
+// listMonitors godoc
+//
+//	@Summary		List monitors
+//	@Tags			monitors
+//	@Produce		json
+//	@Success		200	{array}		models.Monitor
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/monitors [get]
 func listMonitors(c *gin.Context) {
-	monitors, err := services.ListMonitors()
+	monitors, err := services.ListMonitors(auth.InstanceID(c))
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
@@ -29,6 +42,20 @@ func listMonitors(c *gin.Context) {
 	c.JSON(http.StatusOK, monitors)
 }
 
+// createMonitor godoc
+//
+//	@Summary		Create a monitor
+//	@Tags			monitors
+//	@Accept			json
+//	@Produce		json
+//	@Param			body	body		models.Monitor	true	"Monitor to create"
+//	@Success		201	{object}	models.Monitor
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		403	{object}	LimitExceededResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/monitors [post]
 func createMonitor(c *gin.Context) {
 	var m models.Monitor
 	if err := c.ShouldBindJSON(&m); err != nil {
@@ -39,7 +66,14 @@ func createMonitor(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, gin.H{"error": "name and type are required"})
 		return
 	}
-	created, err := services.CreateMonitor(&m)
+	if err := services.CheckMonitorLimit(auth.InstanceID(c)); err != nil {
+		if limitStatus(c, err) {
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	created, err := services.CreateMonitor(auth.InstanceID(c), &m)
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
@@ -47,8 +81,20 @@ func createMonitor(c *gin.Context) {
 	c.JSON(http.StatusCreated, created)
 }
 
+// getMonitor godoc
+//
+//	@Summary		Get a monitor
+//	@Tags			monitors
+//	@Produce		json
+//	@Param			id	path		string	true	"Monitor ID"
+//	@Success		200	{object}	models.Monitor
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/monitors/{id} [get]
 func getMonitor(c *gin.Context) {
-	m, err := services.GetMonitor(c.Param("id"))
+	m, err := services.GetMonitor(auth.InstanceID(c), c.Param("id"))
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
@@ -60,9 +106,24 @@ func getMonitor(c *gin.Context) {
 	c.JSON(http.StatusOK, m)
 }
 
+// updateMonitor godoc
+//
+//	@Summary		Update a monitor
+//	@Tags			monitors
+//	@Accept			json
+//	@Produce		json
+//	@Param			id		path	string												true	"Monitor ID"
+//	@Param			body	body	object{name=string,group=string,type=string,target=models.MonitorTarget,interval_sec=int,runner=string,retries=int,enabled=bool,channel_ids=[]string}	true	"Fields to update"
+//	@Success		204
+//	@Failure		400	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/monitors/{id} [put]
 func updateMonitor(c *gin.Context) {
 	var body struct {
 		Name        *string               `json:"name"`
+		Group       *string               `json:"group"`
 		Type        *string               `json:"type"`
 		Target      *models.MonitorTarget `json:"target"`
 		IntervalSec *int                  `json:"interval_sec"`
@@ -79,6 +140,9 @@ func updateMonitor(c *gin.Context) {
 	if body.Name != nil {
 		upd["name"] = *body.Name
 	}
+	if body.Group != nil {
+		upd["group"] = *body.Group
+	}
 	if body.Type != nil {
 		upd["type"] = *body.Type
 	}
@@ -104,23 +168,54 @@ func updateMonitor(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, gin.H{"error": "no fields to update"})
 		return
 	}
-	if err := services.UpdateMonitor(c.Param("id"), upd); err != nil {
+	if err := services.UpdateMonitor(auth.InstanceID(c), c.Param("id"), upd); err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
 	c.Status(http.StatusNoContent)
 }
 
+// deleteMonitor godoc
+//
+//	@Summary		Delete a monitor
+//	@Tags			monitors
+//	@Param			id	path	string	true	"Monitor ID"
+//	@Success		204
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/monitors/{id} [delete]
 func deleteMonitor(c *gin.Context) {
-	if err := services.DeleteMonitor(c.Param("id")); err != nil {
+	if err := services.DeleteMonitor(auth.InstanceID(c), c.Param("id")); err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
 	c.Status(http.StatusNoContent)
 }
 
+// getMonitorIncidents godoc
+//
+//	@Summary		List a monitor's incidents
+//	@Tags			monitors
+//	@Produce		json
+//	@Param			id	path		string	true	"Monitor ID"
+//	@Success		200	{array}		models.Incident
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/monitors/{id}/incidents [get]
 func getMonitorIncidents(c *gin.Context) {
-	incidents, err := services.ListIncidents(c.Param("id"), 50)
+	m, err := services.GetMonitor(auth.InstanceID(c), c.Param("id"))
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if m == nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "monitor not found"})
+		return
+	}
+	incidents, err := services.ListIncidents(auth.InstanceID(c), c.Param("id"), 50)
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
@@ -128,9 +223,74 @@ func getMonitorIncidents(c *gin.Context) {
 	c.JSON(http.StatusOK, incidents)
 }
 
+// getMonitorSamples godoc
+//
+//	@Summary		Get a monitor's individual check results
+//	@Description	Raw check results for the last `minutes` minutes, oldest first. Samples expire after 48 hours; use the uptime rollups for longer ranges.
+//	@Tags			monitors
+//	@Produce		json
+//	@Param			id		path		string	true	"Monitor ID"
+//	@Param			minutes	query		int		false	"Window in minutes (default 60, max 2880)"
+//	@Success		200	{array}		models.MonitorSample
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/monitors/{id}/samples [get]
+func getMonitorSamples(c *gin.Context) {
+	m, err := services.GetMonitor(auth.InstanceID(c), c.Param("id"))
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if m == nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "monitor not found"})
+		return
+	}
+	// Clamped rather than rejected: the window is a view setting, and the only
+	// honest answer past the TTL is the shorter window anyway.
+	minutes := 60
+	if raw := c.Query("minutes"); raw != "" {
+		if n, convErr := strconv.Atoi(raw); convErr == nil && n > 0 {
+			minutes = n
+		}
+	}
+	if max := int(services.MonitorSampleTTL.Minutes()); minutes > max {
+		minutes = max
+	}
+	samples, err := services.MonitorSamples(auth.InstanceID(c), c.Param("id"), time.Now().Add(-time.Duration(minutes)*time.Minute))
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, samples)
+}
+
+// getMonitorUptime godoc
+//
+//	@Summary		Get a monitor's uptime rollups
+//	@Description	Hourly rollups for the last 30 days.
+//	@Tags			monitors
+//	@Produce		json
+//	@Param			id	path		string	true	"Monitor ID"
+//	@Success		200	{array}		models.Rollup
+//	@Failure		404	{object}	ErrorResponse
+//	@Failure		500	{object}	ErrorResponse
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/monitors/{id}/uptime [get]
 func getMonitorUptime(c *gin.Context) {
+	m, err := services.GetMonitor(auth.InstanceID(c), c.Param("id"))
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if m == nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "monitor not found"})
+		return
+	}
 	since := time.Now().Add(-30 * 24 * time.Hour)
-	rollups, err := services.UptimeRollups(c.Param("id"), since)
+	rollups, err := services.UptimeRollups(auth.InstanceID(c), c.Param("id"), since)
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return

server/internal/api/openapi.go

@@ -0,0 +1,71 @@
+package api
+
+import (
+	"net/http"
+
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/api/docs"
+	"github.com/gin-gonic/gin"
+)
+
+// scalarPage renders the reference against this instance's own spec, so "Try
+// it" acts on the reader's API with the reader's session.
+const scalarPage = `<!doctype html>
+<html>
+  <head>
+    <title>Vantage API</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script src="/api/docs/scalar.js"></script>
+    <script>
+      Scalar.createApiReference('#app', {
+        url: '/api/openapi.json',
+        theme: 'deepSpace',
+      })
+    </script>
+  </body>
+</html>`
+
+// getOpenAPI godoc
+//
+//	@Summary		Get the OpenAPI document
+//	@Description	Generated from swaggo annotations at build time and committed; served verbatim.
+//	@Tags			docs
+//	@Produce		json
+//	@Success		200	{object}	map[string]any
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/openapi.json [get]
+func getOpenAPI(c *gin.Context) {
+	c.Data(http.StatusOK, "application/json; charset=utf-8", docs.OpenAPI)
+}
+
+// getScalarJS godoc
+//
+//	@Summary		Get the vendored Scalar bundle
+//	@Description	Served locally rather than from a CDN so the reference page works on an air-gapped install.
+//	@Tags			docs
+//	@Produce		application/javascript
+//	@Success		200	{string}	string	"javascript bundle"
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/docs/scalar.js [get]
+func getScalarJS(c *gin.Context) {
+	c.Data(http.StatusOK, "application/javascript; charset=utf-8", docs.ScalarJS)
+}
+
+// getAPIDocs godoc
+//
+//	@Summary		API reference page
+//	@Description	Renders the Scalar reference against this instance's own OpenAPI document.
+//	@Tags			docs
+//	@Produce		html
+//	@Success		200	{string}	string	"HTML page"
+//	@Security		cookieAuth
+//	@Security		bearerAuth
+//	@Router			/docs [get]
+func getAPIDocs(c *gin.Context) {
+	c.Data(http.StatusOK, "text/html; charset=utf-8", []byte(scalarPage))
+}

server/internal/api/publichost.go

@@ -0,0 +1,51 @@
+package api
+
+import (
+	"net"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+func publicHostFromRequest(c *gin.Context) string {
+	host := c.Request.Host
+	if h := firstForwarded(c.GetHeader("X-Forwarded-Host")); h != "" {
+		host = h
+	}
+	if host == "" {
+		return "https://vantage.example.com"
+	}
+	return schemeFor(c, host) + "://" + host
+}
+
+func schemeFor(c *gin.Context, host string) string {
+	if p := firstForwarded(c.GetHeader("X-Forwarded-Proto")); p != "" {
+		return p
+	}
+	if c.Request.TLS != nil {
+		return "https"
+	}
+	if isLoopback(host) {
+		return "http"
+	}
+	return "https"
+}
+
+func firstForwarded(v string) string {
+	if v == "" {
+		return ""
+	}
+	return strings.TrimSpace(strings.Split(v, ",")[0])
+}
+
+func isLoopback(host string) bool {
+	h, _, err := net.SplitHostPort(host)
+	if err != nil {
+		h = host
+	}
+	if h == "localhost" || strings.HasSuffix(h, ".localhost") {
+		return true
+	}
+	ip := net.ParseIP(h)
+	return ip != nil && ip.IsLoopback()
+}