Document updating the dashboard server

The README only covered the first install, so the admin page update stalled at a step that wasn't written down: nginx serves its own copy of public/ in /var/www, and without copying it a new page quietly falls back to index.html. "Updating the server" covers: backing up the database, pulling and listing what changed, Python packages, copying the web files, restarting, health checks, which deploy/ templates map to which installed files, and redeploying collectors when they change. A rollback section restores the database before starting the older API (which refuses a newer database), using sqlite3 .restore rather than cp because of the WAL file. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Add an admin page for managing collector API keys
2026-10-08 14:24:51 -06:00 · 2026-10-08 13:52:29 -06:00 · 2026-10-08 13:36:27 -06:00
37 changed files with 1983 additions and 74 deletions
@@ -79,9 +79,23 @@ The OpenAPI schema is at `/api/v1/openapi.json`.
  signed-in user can see every tenant. Sessions last 12 hours; signing in again is usually silent.
  The dashboard shows who's signed in; **Sign out** also signs out of Microsoft in that browser,
  otherwise the next visit would sign straight back in.
 - **Admins:** the sign-in names in `BACKUP_DASH_ADMINS` (in `/etc/backup-dashboard/backup-dashboard.env`,
  comma-separated) get an **Admin** link to the API keys page. Restart the API after changing it.
 - **Collectors:** per-collector bearer keys, checked by the app. Only a SHA-256 hash is stored.
-  To revoke one, run `python manage.py revoke-key NAME`. `/api/v1/ingest` is the only path that
+  `/api/v1/ingest` is the only path that doesn't need Microsoft sign-in.
-  doesn't need Microsoft sign-in.
+
 ### Managing API keys
 On the **Admin** page (`/admin.html`), admins can:
 - **Create** a key. It's shown once, with a copy button. Paste it when a collector's installer
  asks for the API key.
 - **See** each key's status, when it was last used and for which company, and who created it.
  Active keys quiet for over 24 hours are flagged, since collectors report hourly.
 - **Revoke** a key. The collectors using it are refused from their next run. This can't be undone,
  and names stay taken, so the history stays unambiguous.
 The same is possible from the server with `manage.py` (`create-key`, `list-keys`, `revoke-key`),
 recorded as created/revoked by `manage.py (<user>)`.
 ### Microsoft 365 sign-in setup
@@ -138,6 +152,12 @@ BACKUP_DASH_SERVE_STATIC=1 uvicorn --factory app.main:create_app --reload
 # → http://localhost:8000
 ```
 Collector tests (PowerShell 7 + Pester; see [collectors/tests](collectors/tests/README.md)):
 ```powershell
 ./collectors/tests/Invoke-CollectorTests.ps1
 ```
 ## Deployment (Linux, nginx)
 1. Copy the repo to `/opt/backup-dashboard`, create a venv at `/opt/backup-dashboard/venv`, and run `pip install -r backend/requirements.txt`.
@@ -153,3 +173,88 @@ BACKUP_DASH_SERVE_STATIC=1 uvicorn --factory app.main:create_app --reload
 Back up the SQLite file with `sqlite3 backup-dashboard.db ".backup copy.db"`. Don't use a plain `cp`
 while the service is running.
 ### Updating the server
 After changes are merged into `main`, on the dashboard server:
 1. **Back up the database.** It takes seconds, and an update may upgrade the database's structure
   when the API restarts, which only this backup can reverse. Needs the `sqlite3` package:
   ```bash
   sudo -u backupdash sqlite3 /var/lib/backup-dashboard/backup-dashboard.db ".backup /var/lib/backup-dashboard/before-update.db"
   ```
 2. **Pull, and see what changed** (the list tells you whether steps 7 and 8 apply):
   ```bash
   sudo git -C /opt/backup-dashboard pull
   ```
   ```bash
   git -C /opt/backup-dashboard diff --stat ORIG_HEAD HEAD
   ```
 3. **Python packages.** Does nothing unless `backend/requirements.txt` changed:
   ```bash
   sudo /opt/backup-dashboard/venv/bin/pip install -q -r /opt/backup-dashboard/backend/requirements.txt
   ```
 4. **Web files.** nginx serves its own copy in `/var/www`, so a pull alone doesn't change what
   browsers get. If this step is skipped, new pages quietly show the dashboard instead (nginx
   falls back to `index.html` for files it doesn't have):
   ```bash
   sudo rsync -a /opt/backup-dashboard/public/ /var/www/backup-dashboard/public/
   ```
   Browsers pick up the new files on their next page load.
 5. **Restart the API**, which loads the new code and settings and upgrades the database if needed:
   ```bash
   sudo systemctl restart backup-dashboard-api
   ```
 6. **Check it's healthy.** The first should print `{"status":"ok"}`; the log shouldn't show errors:
   ```bash
   curl -s http://127.0.0.1:8000/api/v1/health
   ```
   ```bash
   journalctl -u backup-dashboard-api -n 20 --no-pager
   ```
 7. **If files in `deploy/` changed:** those are templates whose installed copies live elsewhere,
   so a pull doesn't update them. Compare each changed one with its installed copy (e.g.
   `diff /opt/backup-dashboard/deploy/oauth2-proxy.service /etc/systemd/system/oauth2-proxy.service`)
   and bring the changes across:
   | Changed in the repo | Installed copy | After updating it |
   |---|---|---|
   | `deploy/backup-dashboard.env` | `/etc/backup-dashboard/backup-dashboard.env` | Add any new settings, keeping your values; restart the API |
   | `deploy/backup-dashboard-api.service` | `/etc/systemd/system/backup-dashboard-api.service` | `sudo systemctl daemon-reload`, restart the API |
   | `deploy/nginx.conf` | Your nginx site config | Keep your server name and certificate paths; `sudo nginx -t && sudo systemctl reload nginx` |
   | `deploy/oauth2-proxy.cfg` | `/etc/oauth2-proxy/backup-dashboard.cfg` | Keep your IDs and secrets; `sudo systemctl restart oauth2-proxy` |
   | `deploy/oauth2-proxy.service` | `/etc/systemd/system/oauth2-proxy.service` | `sudo systemctl daemon-reload && sudo systemctl restart oauth2-proxy` |
 8. **If files in `collectors/` changed:** the backup servers keep running their installed copy.
   On each affected server, copy over the whole `collectors` folder, re-run that collector's
   installer, and do a dry run (see its README). The changes are already covered by the
   collector tests (`./collectors/tests/Invoke-CollectorTests.ps1`) if you want to run them first.
 **If something goes wrong**, go back to the version from before step 2 (`ORIG_HEAD`). The order
 matters: an older API won't start on a database a newer one has upgraded, so restore the database
 before starting it.
 1. Stop the API:
   ```bash
   sudo systemctl stop backup-dashboard-api
   ```
 2. Check whether the update upgraded the database: if these two numbers differ, it did.
   ```bash
   for db in backup-dashboard before-update; do sudo -u backupdash sqlite3 /var/lib/backup-dashboard/$db.db "PRAGMA user_version"; done
   ```
   If so, restore the backup from step 1 (`.restore`, not `cp`: it also deals with SQLite's `-wal`
   file). Runs reported since the backup drop out of the history, since collectors have already
   marked them as sent; backups themselves are unaffected.
   ```bash
   sudo -u backupdash sqlite3 /var/lib/backup-dashboard/backup-dashboard.db ".restore /var/lib/backup-dashboard/before-update.db"
   ```
 3. Go back to the previous code and web files, then start the API:
   ```bash
   sudo git -C /opt/backup-dashboard checkout ORIG_HEAD
   ```
   ```bash
   sudo rsync -a /opt/backup-dashboard/public/ /var/www/backup-dashboard/public/ && sudo systemctl start backup-dashboard-api
   ```
 Once the problem is fixed, return to `main` with `sudo git -C /opt/backup-dashboard checkout main`
 and update as above.
@@ -0,0 +1,44 @@
 """Admin API: managing collector API keys. Only for users in BACKUP_DASH_ADMINS."""
 import logging
 import sqlite3
 from typing import Annotated
 from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel, StringConstraints
 from . import db, keys
 from .auth import require_admin, require_page_request
 log = logging.getLogger("backup_dashboard")
 router = APIRouter(prefix="/api/v1/admin", dependencies=[Depends(require_admin)])
 class NewKey(BaseModel):
    name: Annotated[str, StringConstraints(strip_whitespace=True, pattern=f"^{keys.NAME_PATTERN}$")]
@router.get("/keys")
 def list_keys(conn: sqlite3.Connection = Depends(db.get_db)):
    return {"keys": keys.list_keys(conn)}
@router.post("/keys", status_code=201, dependencies=[Depends(require_page_request)])
 def create_key(body: NewKey, admin: str = Depends(require_admin), conn: sqlite3.Connection = Depends(db.get_db)):
    try:
        record, secret = keys.create_key(conn, body.name, created_by=admin)
    except keys.KeyNameTaken:
        raise HTTPException(409, f"A key named {body.name!r} already exists (revoked keys keep their names)") from None
    log.info("admin %s created API key %r", admin, body.name)
    # The key itself is returned this once; only its hash is stored
    return {"key": record, "secret": secret}
@router.post("/keys/{key_id}/revoke", dependencies=[Depends(require_page_request)])
 def revoke_key(key_id: int, admin: str = Depends(require_admin), conn: sqlite3.Connection = Depends(db.get_db)):
    record = keys.revoke_key(conn, key_id, revoked_by=admin)
    if record is None:
        raise HTTPException(404, "Key not found")
    log.info("admin %s revoked API key %r", admin, record["name"])
    return {"key": record}
@@ -1,14 +1,16 @@
-"""Collector (machine) authentication.
+"""Authentication and authorisation.
-Dashboard *users* are authenticated by nginx in front of the app (Microsoft 365 sign-in via
+Collectors (machines) authenticate with API keys, checked here. Dashboard *users* sign in with
-oauth2-proxy), so nothing here deals with people.
+Microsoft 365 in nginx (via oauth2-proxy), which then tells the app who they are in
 X-Forwarded-* headers it sets itself (a browser can't supply them). The app only decides whether
 that user is an admin.
 """
 import hashlib
 import secrets
 import sqlite3
-from fastapi import Depends, Header, HTTPException
+from fastapi import Depends, Header, HTTPException, Request
 from .db import get_db
 from .timeutil import to_db, utcnow
@@ -25,6 +27,35 @@ def hash_key(key: str) -> str:
    return hashlib.sha256(key.encode()).hexdigest()
 def current_user(request: Request) -> str | None:
    """The signed-in user's sign-in name, lowercase; None without Microsoft sign-in (e.g. dev)."""
    user = request.headers.get("x-forwarded-email") or request.headers.get("x-forwarded-preferred-username")
    return user.strip().lower() if user and user.strip() else None
 def is_admin(request: Request) -> bool:
    user = current_user(request)
    return user is not None and user in request.app.state.settings.admins
 def require_admin(request: Request) -> str:
    if not is_admin(request):
        raise HTTPException(403, "Admins only. Admins are listed in BACKUP_DASH_ADMINS on the server.")
    return current_user(request)
 # Changes made from the admin page must carry this header. A page on another site can't add a
 # custom header to a request to the dashboard (the browser would first ask the API, which allows
 # no other origins), so a signed-in admin's browser can't be used to forge them.
 PAGE_HEADER = "X-Requested-By"
 PAGE_HEADER_VALUE = "backup-dashboard"
 def require_page_request(x_requested_by: str | None = Header(None)) -> None:
    if x_requested_by != PAGE_HEADER_VALUE:
        raise HTTPException(403, f"Missing {PAGE_HEADER} header")
 def require_ingest_key(
    authorization: str | None = Header(None),
    conn: sqlite3.Connection = Depends(get_db),
@@ -5,7 +5,7 @@ from pathlib import Path
 from fastapi import Request
-SCHEMA_VERSION = 1
+SCHEMA_VERSION = 2
 SCHEMA = """
 CREATE TABLE IF NOT EXISTS tenants (
@@ -67,6 +67,17 @@ def connect(path: Path | str) -> sqlite3.Connection:
    return conn
 # Changes since SCHEMA (which is v1), applied in order to bring any database up to SCHEMA_VERSION
 MIGRATIONS = {
    2: [
        # Who created/revoked a key from the admin page, and which company it last reported for
        "ALTER TABLE api_keys ADD COLUMN created_by TEXT",
        "ALTER TABLE api_keys ADD COLUMN revoked_by TEXT",
        "ALTER TABLE api_keys ADD COLUMN last_used_tenant TEXT",
    ],
 }
 def init_db(path: Path | str) -> None:
    conn = connect(path)
    try:
@@ -74,8 +85,12 @@ def init_db(path: Path | str) -> None:
        version = conn.execute("PRAGMA user_version").fetchone()[0]
        if version > SCHEMA_VERSION:
            raise RuntimeError(f"Database schema v{version} is newer than this app (v{SCHEMA_VERSION})")
-        conn.executescript(SCHEMA)
+        conn.executescript(SCHEMA)  # v1 tables, for a new database
-        conn.execute(f"PRAGMA user_version = {SCHEMA_VERSION}")
+        with transaction(conn):
            for target in range(max(version, 1) + 1, SCHEMA_VERSION + 1):
                for statement in MIGRATIONS[target]:
                    conn.execute(statement)
            conn.execute(f"PRAGMA user_version = {SCHEMA_VERSION}")
    finally:
        conn.close()
@@ -0,0 +1,55 @@
 """Collector API keys: create, list, revoke. Used by the admin API and manage.py."""
 import re
 import sqlite3
 from typing import Any
 from .auth import generate_key, hash_key
 from .timeutil import to_db, utcnow
 # Letters, digits, '.', '_', '-'; starts with a letter or digit. E.g. "veeam-acme", "mars.fs01"
 NAME_PATTERN = r"[A-Za-z0-9][A-Za-z0-9._-]{0,63}"
 _FIELDS = "id, name, created_at, created_by, last_used_at, last_used_tenant, revoked_at, revoked_by"
 class KeyNameTaken(Exception):
    pass
 def valid_name(name: str) -> bool:
    return re.fullmatch(NAME_PATTERN, name) is not None
 def list_keys(conn: sqlite3.Connection) -> list[dict[str, Any]]:
    # Active keys first, then by name
    rows = conn.execute(f"SELECT {_FIELDS} FROM api_keys ORDER BY revoked_at IS NOT NULL, name").fetchall()
    return [dict(r) for r in rows]
 def get_key(conn: sqlite3.Connection, key_id: int) -> dict[str, Any] | None:
    row = conn.execute(f"SELECT {_FIELDS} FROM api_keys WHERE id = ?", (key_id,)).fetchone()
    return dict(row) if row else None
 def create_key(conn: sqlite3.Connection, name: str, created_by: str) -> tuple[dict[str, Any], str]:
    """Returns the stored key's record and the key itself, which isn't stored and can't be shown again."""
    secret = generate_key()
    try:
        key_id = conn.execute(
            "INSERT INTO api_keys (name, key_hash, created_at, created_by) VALUES (?, ?, ?, ?) RETURNING id",
            (name, hash_key(secret), to_db(utcnow()), created_by),
        ).fetchone()[0]
    except sqlite3.IntegrityError:
        # Names stay taken after revocation, so the audit trail stays unambiguous
        raise KeyNameTaken(name) from None
    return get_key(conn, key_id), secret
 def revoke_key(conn: sqlite3.Connection, key_id: int, revoked_by: str) -> dict[str, Any] | None:
    """Revokes the key (no-op if already revoked). Returns its record, or None if there's no such key."""
    conn.execute(
        "UPDATE api_keys SET revoked_at = ?, revoked_by = ? WHERE id = ? AND revoked_at IS NULL",
        (to_db(utcnow()), revoked_by, key_id),
    )
    return get_key(conn, key_id)
@@ -7,8 +7,8 @@ from pathlib import Path
 from fastapi import APIRouter, Depends, FastAPI, HTTPException, Query, Request
-from . import db, repo
+from . import admin, db, repo
-from .auth import require_ingest_key
+from .auth import is_admin, require_ingest_key
 from .models import IngestIn
 from .settings import HISTORY_DAYS, Settings, load_settings
 from .timeutil import to_db, utcnow
@@ -32,6 +32,7 @@ def me(request: Request):
    return {
        "email": request.headers.get("x-forwarded-email") or None,
        "name": request.headers.get("x-forwarded-preferred-username") or request.headers.get("x-forwarded-user") or None,
        "is_admin": is_admin(request),
    }
@@ -75,6 +76,8 @@ def ingest(
    conn: sqlite3.Connection = Depends(db.get_db),
 ):
    job_id, run_id = repo.ingest(conn, item)
    # Shown on the admin page, so you can tell what each key is used for
    conn.execute("UPDATE api_keys SET last_used_tenant = ? WHERE name = ?", (item.tenant, key_name))
    log.info("ingest key=%s tenant=%r job=%r run=%s", key_name, item.tenant, item.job.name, run_id)
    return {"job_id": job_id, "run_id": run_id}
@@ -118,6 +121,7 @@ def create_app(settings: Settings | None = None) -> FastAPI:
    )
    app.state.settings = settings
    app.include_router(router)
    app.include_router(admin.router)
    if settings.serve_static:
        from fastapi.staticfiles import StaticFiles
@@ -15,6 +15,8 @@ class Settings:
    retention_days: int = 90
    # Dev only: serve ../public from the API so you can run without nginx.
    serve_static: bool = False
    # Microsoft 365 sign-in names allowed into the admin pages (lowercase)
    admins: frozenset[str] = frozenset()
 def read_env_file(path: Path) -> dict[str, str]:
@@ -40,4 +42,10 @@ def load_settings() -> Settings:
        db_path=Path(env.get("BACKUP_DASH_DB", "backup-dashboard.db")),
        retention_days=max(HISTORY_DAYS, int(env.get("BACKUP_DASH_RETENTION_DAYS", "90"))),
        serve_static=env.get("BACKUP_DASH_SERVE_STATIC") == "1",
        admins=parse_admins(env.get("BACKUP_DASH_ADMINS", "")),
    )
 def parse_admins(value: str) -> frozenset[str]:
    """'[email protected], [email protected]' -> {'[email protected]', '[email protected]'}"""
    return frozenset(part.strip().lower() for part in value.replace(";", ",").split(",") if part.strip())
@@ -15,41 +15,48 @@ Run it as the service user so files it creates stay writable by the API:
 """
 import argparse
 import getpass
 import random
 import sys
 from datetime import timedelta
 from pathlib import Path
-from app import db, repo
+from app import db, keys, repo
 from app.auth import generate_key, hash_key
 from app.models import IngestIn
 from app.settings import DEFAULT_ENV_FILE, load_settings
-from app.timeutil import to_db, utcnow
+from app.timeutil import utcnow
 def cli_user() -> str:
    # Recorded as who created/revoked a key; the admin page records the signed-in user instead
    try:
        return f"manage.py ({getpass.getuser()})"
    except Exception:
        return "manage.py"
 def create_key(conn, args):
-    key = generate_key()
+    if not keys.valid_name(args.name):
        sys.exit("Key names use letters, digits, '.', '_' and '-', starting with a letter or digit")
    try:
-        conn.execute(
+        _, secret = keys.create_key(conn, args.name, created_by=cli_user())
-            "INSERT INTO api_keys (name, key_hash, created_at) VALUES (?, ?, ?)",
+    except keys.KeyNameTaken:
            (args.name, hash_key(key), to_db(utcnow())),
        )
    except db.sqlite3.IntegrityError:
        sys.exit(f"A key named {args.name!r} already exists")
-    print(f"API key for {args.name!r} (shown once, store it in the collector's config):\n{key}")
+    print(f"API key for {args.name!r} (shown once, store it in the collector's config):\n{secret}")
 def list_keys(conn, args):
-    for r in conn.execute("SELECT name, created_at, last_used_at, revoked_at FROM api_keys ORDER BY name"):
+    for k in keys.list_keys(conn):
-        state = f"revoked {r['revoked_at']}" if r["revoked_at"] else "active"
+        state = f"revoked {k['revoked_at']}" if k["revoked_at"] else "active"
-        print(f"{r['name']:<30} {state:<30} created {r['created_at']}  last used {r['last_used_at'] or 'never'}")
+        tenant = f" ({k['last_used_tenant']})" if k["last_used_tenant"] else ""
        print(f"{k['name']:<30} {state:<30} created {k['created_at']}  last used {k['last_used_at'] or 'never'}{tenant}")
 def revoke_key(conn, args):
-    cur = conn.execute(
+    row = conn.execute("SELECT id FROM api_keys WHERE name = ? AND revoked_at IS NULL", (args.name,)).fetchone()
-        "UPDATE api_keys SET revoked_at = ? WHERE name = ? AND revoked_at IS NULL", (to_db(utcnow()), args.name)
+    if row is None:
-    )
+        sys.exit(f"No active key named {args.name!r}")
-    sys.exit(0 if cur.rowcount else f"No active key named {args.name!r}")
+    keys.revoke_key(conn, row["id"], revoked_by=cli_user())
 def list_jobs(conn, args):
@@ -0,0 +1,146 @@
 import sqlite3
 import pytest
 from fastapi.testclient import TestClient
 from app import db
 from app.main import create_app
 from app.settings import Settings, parse_admins
 ADMIN = {"X-Forwarded-Email": "[email protected]"}
 PAGE = {"X-Requested-By": "backup-dashboard"}
 ADMIN_PAGE = ADMIN | PAGE
@pytest.fixture
 def client(tmp_path):
    settings = Settings(db_path=tmp_path / "test.db", admins=frozenset({"[email protected]"}))
    with TestClient(create_app(settings)) as c:
        yield c
 def create(client, name="veeam-acme", headers=ADMIN_PAGE):
    return client.post("/api/v1/admin/keys", json={"name": name}, headers=headers)
 def ingest(client, secret, tenant="Acme"):
    return client.post(
        "/api/v1/ingest",
        json={"tenant": tenant, "source_system": "Veeam B&R", "job": {"external_id": "j1", "name": "Job"}},
        headers={"Authorization": f"Bearer {secret}"},
    )
 def test_parse_admins():
    assert parse_admins(" [email protected], [email protected];[email protected] ,") == {
        "[email protected]", "[email protected]", "[email protected]"}
    assert parse_admins("") == frozenset()
 def test_me_says_whether_the_user_is_an_admin(client):
    assert client.get("/api/v1/me", headers=ADMIN).json()["is_admin"] is True
    assert client.get("/api/v1/me", headers={"X-Forwarded-Email": "[email protected]"}).json()["is_admin"] is False
    assert client.get("/api/v1/me").json()["is_admin"] is False
@pytest.mark.parametrize("headers", [{}, {"X-Forwarded-Email": "[email protected]"}])
 def test_admin_pages_are_admins_only(client, headers):
    assert client.get("/api/v1/admin/keys", headers=headers).status_code == 403
    assert create(client, headers=headers | PAGE).status_code == 403
    assert client.post("/api/v1/admin/keys/1/revoke", headers=headers | PAGE).status_code == 403
 def test_admin_match_ignores_case_and_accepts_the_sign_in_name(client):
    assert client.get("/api/v1/admin/keys", headers={"X-Forwarded-Email": "[email protected]"}).status_code == 200
    assert client.get("/api/v1/admin/keys", headers={"X-Forwarded-Preferred-Username": "[email protected]"}).status_code == 200
 def test_changes_need_the_page_header(client):
    # Without it, a page on another site could make a signed-in admin's browser send the request
    assert create(client, headers=ADMIN).status_code == 403
    secret = create(client).json()["secret"]
    key_id = client.get("/api/v1/admin/keys", headers=ADMIN).json()["keys"][0]["id"]
    assert client.post(f"/api/v1/admin/keys/{key_id}/revoke", headers=ADMIN).status_code == 403
    assert ingest(client, secret).status_code == 200  # still active
@pytest.mark.parametrize("name", ["", " ", "-leading-dash", "has space", "a" * 65, "semi;colon"])
 def test_rejects_bad_key_names(client, name):
    assert create(client, name=name).status_code == 422
 def test_created_key_is_shown_once_and_works_for_ingest(client):
    r = create(client, name="  veeam-acme  ")
    assert r.status_code == 201
    body = r.json()
    assert body["secret"].startswith("bdk_")
    assert body["key"]["name"] == "veeam-acme"
    assert body["key"]["created_by"] == "[email protected]"
    listed = client.get("/api/v1/admin/keys", headers=ADMIN).json()["keys"]
    assert "secret" not in listed[0] and "key_hash" not in listed[0]
    assert ingest(client, body["secret"]).status_code == 200
 def test_key_records_when_and_for_which_company_it_was_last_used(client):
    secret = create(client).json()["secret"]
    ingest(client, secret, tenant="Acme Corp")
    key = client.get("/api/v1/admin/keys", headers=ADMIN).json()["keys"][0]
    assert key["last_used_at"] is not None
    assert key["last_used_tenant"] == "Acme Corp"
 def test_duplicate_names_are_refused_even_after_revoking(client):
    key_id = create(client).json()["key"]["id"]
    assert create(client).status_code == 409
    client.post(f"/api/v1/admin/keys/{key_id}/revoke", headers=ADMIN_PAGE)
    assert create(client).status_code == 409
 def test_revoking_stops_the_key_and_records_who(client):
    created = create(client).json()
    r = client.post(f"/api/v1/admin/keys/{created['key']['id']}/revoke", headers=ADMIN_PAGE)
    assert r.status_code == 200
    assert r.json()["key"]["revoked_by"] == "[email protected]"
    assert r.json()["key"]["revoked_at"] is not None
    assert ingest(client, created["secret"]).status_code == 401
 def test_revoking_twice_keeps_the_first_revocation(client):
    key_id = create(client).json()["key"]["id"]
    first = client.post(f"/api/v1/admin/keys/{key_id}/revoke", headers=ADMIN_PAGE).json()["key"]
    again = client.post(f"/api/v1/admin/keys/{key_id}/revoke",
                        headers={"X-Forwarded-Email": "[email protected]"} | PAGE).json()["key"]
    assert again["revoked_at"] == first["revoked_at"]
 def test_revoking_an_unknown_key_is_404(client):
    assert client.post("/api/v1/admin/keys/999/revoke", headers=ADMIN_PAGE).status_code == 404
 def test_lists_active_keys_first(client):
    for name in ("b-key", "a-key", "c-key"):
        create(client, name=name)
    a_id = next(k["id"] for k in client.get("/api/v1/admin/keys", headers=ADMIN).json()["keys"] if k["name"] == "a-key")
    client.post(f"/api/v1/admin/keys/{a_id}/revoke", headers=ADMIN_PAGE)
    names = [k["name"] for k in client.get("/api/v1/admin/keys", headers=ADMIN).json()["keys"]]
    assert names == ["b-key", "c-key", "a-key"]
 def test_upgrades_a_version_1_database_keeping_its_keys(tmp_path):
    path = tmp_path / "old.db"
    conn = sqlite3.connect(path)
    conn.executescript(db.SCHEMA)  # the v1 schema, as deployed before admin pages
    conn.execute("INSERT INTO api_keys (name, key_hash, created_at) VALUES ('old-key', 'abc', '2026-10-01T00:00:00Z')")
    conn.execute("PRAGMA user_version = 1")
    conn.commit()
    conn.close()
    db.init_db(path)
    db.init_db(path)  # and running it again is harmless
    conn = db.connect(path)
    assert conn.execute("PRAGMA user_version").fetchone()[0] == db.SCHEMA_VERSION
    row = dict(conn.execute("SELECT * FROM api_keys").fetchone())
    assert row["name"] == "old-key"
    assert {"created_by", "revoked_by", "last_used_tenant"} <= row.keys()
    conn.close()
@@ -125,6 +125,6 @@ def test_tenant_name_is_case_insensitive(client):
 def test_me_reports_signed_in_user_from_proxy_headers(client):
-    assert client.get("/api/v1/me").json() == {"email": None, "name": None}
+    assert client.get("/api/v1/me").json() == {"email": None, "name": None, "is_admin": False}
    r = client.get("/api/v1/me", headers={"X-Forwarded-Email": "[email protected]", "X-Forwarded-User": "abc-123"})
-    assert r.json() == {"email": "[email protected]", "name": "abc-123"}
+    assert r.json() == {"email": "[email protected]", "name": "abc-123", "is_admin": False}
@@ -14,7 +14,7 @@ named `<SERVER> - Azure Backup` by default.
 Runs under Windows PowerShell 5.1 (`powershell.exe`), which the agent's `MSOnlineBackup` module
 targets and which every supported Windows Server has.
-1. On the dashboard host, create a key for this server:
+1. Create a key for this server on the dashboard's **Admin** page, or on the dashboard host:
   ```bash
   python manage.py create-key mars-acme-fs01
   ```
@@ -7,7 +7,8 @@
 #   ./Send-MarsBackupStatus.ps1 -ConfigPath ./my-test-config.json -DryRun
 # Fixed to the top of the hour, and IDs derived from times, so repeated runs see the same jobs
-$now = Get-Date -Minute 0 -Second 0 -Millisecond 0
+# MOCK_NOW (ISO 8601, set by the test suite) pins the time everything is relative to
 $now = if ($env:MOCK_NOW) { [datetime]$env:MOCK_NOW } else { Get-Date -Minute 0 -Second 0 -Millisecond 0 }
 $notSet = [datetime]::new(1601, 1, 1)
 function New-StableGuid([string]$Seed) {
    [guid]::new([Security.Cryptography.MD5]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($Seed)))
@@ -0,0 +1,139 @@
 # The collector installers, with stand-ins for the Windows-only commands they call (icacls, Task
 # Scheduler, Unblock-File, the API key prompt). Checks what each would write and register.
 BeforeAll {
    Import-Module (Join-Path $PSScriptRoot 'TestHelpers.psm1') -Force
    $collectorsDir = Split-Path -Parent $PSScriptRoot
    $shell = if ($env:COLLECTOR_TEST_SHELL) { $env:COLLECTOR_TEST_SHELL } else { (Get-Process -Id $PID).Path }
    $pwshPath = (Get-Process -Id $PID).Path  # stands in for an installed PowerShell 7
    # Runs one installer in a fresh process and sandbox; returns what it wrote and registered
    function Invoke-Installer {
        param([string]$Collector, [string]$Arguments, [switch]$NoProductModule)
        $sandbox = New-TestDir 'installer'
        $src = Join-Path $sandbox 'collectors'
        Copy-Item -Path $collectorsDir -Destination $src -Recurse
        $installer = (Get-ChildItem (Join-Path $src $Collector) -Filter 'Install-*.ps1').FullName
        # The test runner isn't elevated
        (Get-Content $installer) -notmatch '^#Requires -RunAsAdministrator' | Set-Content $installer
        foreach ($d in 'ProgramData', 'ProgramFiles', 'SystemRoot') { New-Item -ItemType Directory -Path (Join-Path $sandbox $d) | Out-Null }
        $record = Join-Path $sandbox 'record.txt'
        $stubs = @'
 function global:Record($what) { Add-Content $env:REC_FILE $what }
 function global:Read-Host { param([switch]$AsSecureString, $Prompt) ConvertTo-SecureString 'bdk_testkey' -AsPlainText -Force }
 function global:icacls.exe { Record "icacls $($args -join ' ')"; $global:LASTEXITCODE = 0 }
 function global:Unblock-File { param($Path) Record "unblock $(Split-Path -Leaf $Path)" }
 function global:Get-Module { param([switch]$ListAvailable, $Name) if (-not $env:STUB_NO_MODULE) { [pscustomobject]@{ Name = $Name } } }
 function global:New-ScheduledTaskAction { param($Execute, $Argument) Record "exe $Execute"; Record "args $Argument" }
 function global:New-ScheduledTaskTrigger { param([switch]$Once, $At, $RepetitionInterval) Record "every $([int]$RepetitionInterval.TotalMinutes)" }
 function global:New-ScheduledTaskPrincipal { param($UserId, $LogonType, $RunLevel) Record "principal $UserId $LogonType $RunLevel" }
 function global:New-ScheduledTaskSettingsSet { param($ExecutionTimeLimit, $MultipleInstances, [switch]$StartWhenAvailable) Record "settings $MultipleInstances" }
 function global:Register-ScheduledTask { param($TaskName, $Action, $Trigger, $Principal, $Settings, $Description, [switch]$Force) Record "task $TaskName" }
 '@
        $env:REC_FILE = $record
        $env:STUB_NO_MODULE = if ($NoProductModule) { '1' } else { '' }
        $saved = @{ ProgramData = $env:ProgramData; ProgramFiles = $env:ProgramFiles; SystemRoot = $env:SystemRoot }
        try {
            foreach ($d in $saved.Keys) { Set-Item "env:$d" (Join-Path $sandbox $d) }
            Push-Location (Split-Path $installer)
            $output = @(& $shell -NoProfile -NonInteractive -Command "$stubs; & '$installer' $Arguments" 2>&1 | ForEach-Object { "$_" })
        } finally {
            Pop-Location
            foreach ($d in $saved.Keys) { Set-Item "env:$d" $saved[$d] }
        }
        $configFile = Get-ChildItem (Join-Path (Join-Path $sandbox 'ProgramData') 'BackupDashboard') -Filter '*-collector.json' -ErrorAction SilentlyContinue
        $installDir = Join-Path (Join-Path $sandbox 'ProgramFiles') 'BackupDashboard'
        return [pscustomobject]@{
            Output   = $output -join "`n"
            Config   = if ($configFile) { Get-Content $configFile.FullName -Raw | ConvertFrom-Json } else { $null }
            Files    = @(Get-ChildItem $installDir -ErrorAction SilentlyContinue | ForEach-Object Name | Sort-Object)
            Record   = @(if (Test-Path $record) { Get-Content $record })
            Sandbox  = $sandbox
        }
    }
 }
 Describe 'Collector installers' {
    Context 'Veeam' {
        BeforeAll { $i = Invoke-Installer veeam "-ApiUrl https://dash.example.com/ -Tenant 'Acme Corp' -PwshPath '$pwshPath'" }
        It 'writes the config, including the API key from the prompt' {
            $i.Config.ApiUrl | Should -Be 'https://dash.example.com'
            $i.Config.ApiKey | Should -Be 'bdk_testkey'
            $i.Config.Tenant | Should -Be 'Acme Corp'
            $i.Config.SourceSystem | Should -Be 'Veeam B&R'
            $i.Config.LookbackHours | Should -Be 48
        }
        It 'locks the config folder to SYSTEM and Administrators' {
            $i.Record | Where-Object { $_ -like 'icacls*' } | Should -BeLike '*/inheritance:r /grant:r `*S-1-5-18:(OI)(CI)F `*S-1-5-32-544:(OI)(CI)F'
        }
        It 'installs the collector and the shared module side by side, unblocked' {
            $i.Files | Should -Be @('BackupDashboard.Collector.psm1', 'Send-VeeamBackupStatus.ps1')
            $i.Record | Should -Contain 'unblock BackupDashboard.Collector.psm1'
            $i.Record | Should -Contain 'unblock Send-VeeamBackupStatus.ps1'
        }
        It 'registers an hourly SYSTEM task running the collector under PowerShell 7' {
            $i.Record | Should -Contain "exe $pwshPath"
            $i.Record | Where-Object { $_ -like 'args*' } | Should -BeLike '*-File "*Send-VeeamBackupStatus.ps1"'
            $i.Record | Should -Contain 'every 60'
            $i.Record | Should -Contain 'principal S-1-5-18 ServiceAccount Highest'
            $i.Record | Should -Contain 'settings IgnoreNew'
            $i.Record | Should -Contain 'task Backup Dashboard - Veeam collector'
        }
        It 'refuses a PowerShell 7 path that does not exist, before changing anything' {
            $bad = Invoke-Installer veeam "-ApiUrl https://dash.example.com -Tenant Acme -PwshPath '/no/such/pwsh.exe'"
            $bad.Output | Should -BeLike '*PowerShell 7 not found*'
            $bad.Config | Should -BeNullOrEmpty
            $bad.Files | Should -BeNullOrEmpty
        }
    }
    Context 'MARS' {
        It 'writes JobName, runs hourly under Windows PowerShell, and honours -IntervalMinutes' {
            $i = Invoke-Installer mars "-ApiUrl https://dash.example.com -Tenant 'Acme Corp' -JobName 'File Server' -IntervalMinutes 30"
            $i.Config.JobName | Should -Be 'File Server'
            $i.Config.SourceSystem | Should -Be 'Azure Backup (MARS)'
            $i.Files | Should -Be @('BackupDashboard.Collector.psm1', 'Send-MarsBackupStatus.ps1')
            $i.Record | Where-Object { $_ -like 'exe*' } | Should -BeLike '*WindowsPowerShell*powershell.exe'
            $i.Record | Should -Contain 'every 30'
            $i.Record | Should -Contain 'task Backup Dashboard - MARS collector'
        }
        It 'refuses to install where the MARS agent is missing, before changing anything' {
            $i = Invoke-Installer mars "-ApiUrl https://dash.example.com -Tenant Acme" -NoProductModule
            $i.Output | Should -BeLike '*MARS agent*not installed*'
            $i.Config | Should -BeNullOrEmpty
        }
    }
    Context 'Windows Server Backup' {
        It 'warns when the dashboard URL is not HTTPS' {
            $i = Invoke-Installer wsb "-ApiUrl http://dash.example.com -Tenant 'Acme Corp'"
            $i.Output | Should -BeLike '*not HTTPS*'
            $i.Files | Should -Be @('BackupDashboard.Collector.psm1', 'Send-WsbBackupStatus.ps1')
            $i.Record | Should -Contain 'task Backup Dashboard - WSB collector'
        }
        It 'refuses to install without the Windows Server Backup feature' {
            $i = Invoke-Installer wsb "-ApiUrl https://dash.example.com -Tenant Acme" -NoProductModule
            # (PowerShell wraps long error messages, so match a short part)
            $i.Output | Should -BeLike '*WindowsServerBackup PowerShell module is not available*'
            $i.Config | Should -BeNullOrEmpty
        }
    }
    Context 'VB365' {
        It 'writes the organization-to-company map, with no Tenant unless given' {
            $i = Invoke-Installer vb365 "-ApiUrl https://dash.example.com -OrganizationTenants @{ 'acme.onmicrosoft.com' = 'Acme Corp'; 'blue.onmicrosoft.com' = 'Bluewater' }"
            $i.Config.OrganizationTenants.'acme.onmicrosoft.com' | Should -Be 'Acme Corp'
            $i.Config.OrganizationTenants.'blue.onmicrosoft.com' | Should -Be 'Bluewater'
            $i.Config.PSObject.Properties.Name | Should -Not -Contain 'Tenant'
            $i.Record | Where-Object { $_ -like 'exe*' } | Should -BeLike '*powershell.exe'
        }
        It 'uses PowerShell 7 when given -PwshPath' {
            $i = Invoke-Installer vb365 "-ApiUrl https://dash.example.com -Tenant 'Solo Co' -PwshPath '$pwshPath'"
            $i.Config.Tenant | Should -Be 'Solo Co'
            $i.Record | Should -Contain "exe $pwshPath"
        }
    }
 }
@@ -0,0 +1,62 @@
 <#
 .SYNOPSIS
    Runs the collector test suite (Pester): the shared module, each collector against its mock,
    and the installers.
 .DESCRIPTION
    Needs PowerShell 7.2+ and Pester 5.5+:
        Install-Module Pester -MinimumVersion 5.5 -Scope CurrentUser
    Each collector runs in its own process, by default under the same PowerShell running the
    tests. On Windows, use -CollectorShell to run them under Windows PowerShell 5.1 instead, as
    the MARS, WSB and VB365 servers do.
    Exits non-zero if any test fails, so it can gate a commit or CI job.
 .EXAMPLE
    ./collectors/tests/Invoke-CollectorTests.ps1
 .EXAMPLE
    ./collectors/tests/Invoke-CollectorTests.ps1 -CollectorShell powershell.exe
 .EXAMPLE
    ./collectors/tests/Invoke-CollectorTests.ps1 -Path ./collectors/tests/Wsb.Tests.ps1
 #>
 #Requires -Version 7.2
 [CmdletBinding()]
 param(
    # powershell.exe / pwsh / a full path: the shell the collectors and installers run under
    [string]$CollectorShell,
    # Test files or folders to run; defaults to every *.Tests.ps1 here
    [string[]]$Path = @($PSScriptRoot),
    [ValidateSet('None', 'Normal', 'Detailed', 'Diagnostic')][string]$Output = 'Detailed'
 )
 $ErrorActionPreference = 'Stop'
 $pester = Get-Module -ListAvailable -Name Pester | Where-Object Version -GE '5.5' |
    Sort-Object Version -Descending | Select-Object -First 1
 if (-not $pester) {
    throw 'Pester 5.5 or newer is needed: Install-Module Pester -MinimumVersion 5.5 -Scope CurrentUser'
 }
 Import-Module $pester
 if ($CollectorShell) {
    $resolved = Get-Command $CollectorShell -ErrorAction SilentlyContinue
    if (-not $resolved) { throw "Shell not found: $CollectorShell" }
    $env:COLLECTOR_TEST_SHELL = $resolved.Source
 }
 $shellName = if ($env:COLLECTOR_TEST_SHELL) { $env:COLLECTOR_TEST_SHELL } else { "this PowerShell ($($PSVersionTable.PSVersion))" }
 Write-Host "Collectors run under: $shellName"
 # All temp folders for this run, removed at the end
 $env:COLLECTOR_TEST_TEMP = Join-Path ([IO.Path]::GetTempPath()) ("backup-dashboard-tests-" + [guid]::NewGuid().ToString('N').Substring(0, 8))
 try {
    $config = New-PesterConfiguration
    $config.Run.Path = $Path
    $config.Run.PassThru = $true
    $config.Output.Verbosity = $Output
    $result = Invoke-Pester -Configuration $config
 } finally {
    Remove-Item -Recurse -Force $env:COLLECTOR_TEST_TEMP -ErrorAction SilentlyContinue
    Remove-Item env:COLLECTOR_TEST_TEMP
 }
 exit $(if ($result.Result -eq 'Passed') { 0 } else { 1 })
@@ -0,0 +1,95 @@
 # Azure Backup (MARS agent) collector, against collectors/mars/tests/MockMars.ps1 (shapes from a
 # real agent, 2.0.9274: job times are UTC values with no UTC marking, ErrorInfo is always present).
 BeforeAll {
    Import-Module (Join-Path $PSScriptRoot 'TestHelpers.psm1') -Force
    $now = Set-MockNow
    $config = @{ ApiUrl = 'http://localhost:1'; ApiKey = 'bdk_x'; Tenant = 'Acme' }
    # MARS reports job times in UTC; the API should get them with +00:00
    function Utc([datetime]$Local) { ConvertTo-ApiTime $Local.ToUniversalTime() }
 }
 Describe 'MARS collector' {
    Context 'what it reports (dry run)' {
        BeforeAll {
            $r = Invoke-Collector mars -Config $config -DryRun
            $runs = @($r.Reports | Where-Object run | ForEach-Object run)
            $byStart = @{}
            foreach ($run in $runs) { $byStart[$run.started_at] = $run }
        }
        It 'runs cleanly' {
            $r.ExitCode | Should -Be 0
            $r.Log[-1] | Should -Be '[INFO] Reported 4 runs, 0 failures'
        }
        It 'reports the server as one job, named after it' {
            $r.Reports.job.external_id | Select-Object -Unique | Should -Be 'mars:srv01'
            $r.Reports.job.name | Select-Object -Unique | Should -Be 'SRV01 - Azure Backup'
            $r.Reports.source_system | Select-Object -Unique | Should -Be 'Azure Backup (MARS)'
        }
        It 'computes the next run from the schedule (daily at 21:00)' {
            $next = (Get-Date).Date.AddHours(21)
            if ((Get-Date) -ge $next) { $next = $next.AddDays(1) }
            $r.Reports[0].job.next_run_at | Should -Be (ConvertTo-ApiTime $next)
        }
        It 'treats job times as UTC (MARS gives UTC values without marking them)' {
            $byStart.Keys | Should -Contain (Utc $now.AddHours(-12))
            $byStart[(Utc $now.AddHours(-12))].finished_at | Should -Be (Utc $now.AddHours(-11.5))
        }
        It 'reports a completed backup as success, despite its (always present) ErrorInfo with code 0' {
            $run = $byStart[(Utc $now.AddHours(-12))]
            $run.status | Should -Be 'success'
            $run.message | Should -Be 'Backup completed successfully.'
            $run.size_bytes | Should -Be 523407872
            $run.details.datasources | Should -Be @('E:\')
        }
        It 'reports a completed backup with failed files as a warning, with the count and log' {
            $run = $byStart[(Utc $now.AddHours(-36))]
            $run.status | Should -Be 'warning'
            $run.message | Should -BeLike '*E:\: 12 file(s) failed to back up*'
            $run.message | Should -BeLike '*Failed file log: C:\Program Files\Microsoft Azure Recovery Services Agent\Temp\Errors.log*'
            $run.details.failed_files | Should -Be 12
            $run.details.failed_bytes | Should -Be 40MB
        }
        It 'reports a failed backup with its error code and parameters' {
            $run = $byStart[(Utc $now.AddHours(-30))]
            $run.status | Should -Be 'failed'
            $run.message | Should -BeLike '*Error code 100050 (Volume=E:)*'
        }
        It 'reports a backup in progress as running, without a finish time' {
            $run = $byStart[(Utc $now.AddMinutes(-10))]
            $run.status | Should -Be 'running'
            $run.PSObject.Properties.Name | Should -Not -Contain 'finished_at'
        }
        It 'ignores restores and backups outside the lookback window' {
            $runs.Count | Should -Be 4
        }
        It 'uses JobName from the config when set' {
            $named = Invoke-Collector mars -Config ($config + @{ JobName = 'File Server' }) -DryRun
            $named.Reports.job.name | Select-Object -Unique | Should -Be 'File Server'
            $named.Reports.job.external_id | Select-Object -Unique | Should -Be 'mars:srv01'
        }
    }
    Context 'sending to the API' {
        BeforeAll {
            $stub = Start-ApiStub
            $live = $config.Clone(); $live.ApiUrl = $stub.Url
            $first = Invoke-Collector mars -Config $live
            $firstRequests = Get-StubRequests $stub
            $second = Invoke-Collector mars -Config $live -WorkDir $first.WorkDir
            $secondRequests = Get-StubRequests $stub
        }
        AfterAll { Stop-ApiStub $stub }
        It 'sends every run on the first run' {
            $first.ExitCode | Should -Be 0
            $firstRequests.Count | Should -Be 4
        }
        It 'on the next run, resends only the backup in progress' {
            $first.State.Count | Should -Be 3
            $secondRequests.Count | Should -Be 1
            $secondRequests[0].Payload.run.status | Should -Be 'running'
        }
    }
 }
@@ -0,0 +1,136 @@
 # Tests for collectors/common/BackupDashboard.Collector.psm1, the code all collectors share.
 BeforeAll {
    Import-Module (Join-Path (Split-Path -Parent $PSScriptRoot) 'common/BackupDashboard.Collector.psm1') -Force
    Import-Module (Join-Path $PSScriptRoot 'TestHelpers.psm1') -Force
    function New-TempConfig([hashtable]$Values, [hashtable]$State) {
        $dir = New-TestDir 'module'
        $path = Join-Path $dir 'test-collector.json'
        $Values | ConvertTo-Json | Set-Content -Path $path
        if ($State) { $State | ConvertTo-Json | Set-Content -Path (Join-Path $dir 'test-collector.state.json') }
        return $path
    }
    $config = @{ ApiUrl = 'http://localhost:1'; ApiKey = 'bdk_x'; Tenant = 'Acme' }
 }
 Describe 'Get-FirstValue' {
    It 'returns the first property that has a value' {
        Get-FirstValue ([pscustomobject]@{ A = $null; B = ''; C = 'yes' }) @('A', 'B', 'C') | Should -Be 'yes'
    }
    It 'treats an empty collection as no value' {
        Get-FirstValue ([pscustomobject]@{ A = @(); B = 'yes' }) @('A', 'B') | Should -Be 'yes'
    }
    It 'returns a one-item list of objects (which [string] would turn into an empty string)' {
        $item = [pscustomobject]@{ Name = 'E:\' }
        $result = @(Get-FirstValue ([pscustomobject]@{ List = @($item) }) @('List'))
        $result.Count | Should -Be 1
        $result[0].Name | Should -Be 'E:\'
    }
    It 'returns $null for a missing property or object' {
        Get-FirstValue ([pscustomobject]@{ A = 1 }) @('Nope') | Should -BeNullOrEmpty
        Get-FirstValue $null @('A') | Should -BeNullOrEmpty
    }
    It 'keeps $false (a real value, not "missing")' {
        Get-FirstValue ([pscustomobject]@{ Enabled = $false }) @('Enabled') | Should -BeFalse
        $null -eq (Get-FirstValue ([pscustomobject]@{ Enabled = $false }) @('Enabled')) | Should -BeFalse
    }
 }
 Describe 'ConvertTo-IsoTime' {
    It 'gives local times their offset' {
        $local = [datetime]::new(2026, 10, 8, 21, 0, 0, [DateTimeKind]::Local)
        ConvertTo-IsoTime $local | Should -Be ([DateTimeOffset]$local).ToString("yyyy-MM-dd'T'HH:mm:sszzz")
    }
    It 'gives UTC times +00:00' {
        ConvertTo-IsoTime ([datetime]::new(2026, 10, 8, 3, 0, 5, [DateTimeKind]::Utc)) | Should -Be '2026-10-08T03:00:05+00:00'
    }
    It 'treats "not set" values as no time' {
        ConvertTo-IsoTime ([datetime]::MinValue) | Should -BeNullOrEmpty
        ConvertTo-IsoTime ([datetime]::new(1601, 1, 1)) | Should -BeNullOrEmpty  # MARS
        ConvertTo-IsoTime ([datetime]::new(1900, 1, 1)) | Should -BeNullOrEmpty  # Veeam
        ConvertTo-IsoTime $null | Should -BeNullOrEmpty
    }
 }
 Describe 'Initialize-Collector' {
    It 'requires ApiUrl, ApiKey and Tenant by default' {
        $path = New-TempConfig @{ ApiUrl = 'http://x'; ApiKey = 'bdk_x' }
        { Initialize-Collector -Name 'test' -ConfigPath $path } | Should -Throw "*missing 'Tenant'*"
    }
    It 'accepts a custom set of required keys' {
        $path = New-TempConfig @{ ApiUrl = 'http://x'; ApiKey = 'bdk_x' }
        { Initialize-Collector -Name 'test' -ConfigPath $path -RequiredKeys 'ApiUrl', 'ApiKey' } | Should -Not -Throw
    }
    It 'resolves LookbackHours: parameter, then config, then 48' {
        (Initialize-Collector -Name 'test' -ConfigPath (New-TempConfig $config)).LookbackHours | Should -Be 48
        (Initialize-Collector -Name 'test' -ConfigPath (New-TempConfig ($config + @{ LookbackHours = 720 }))).LookbackHours | Should -Be 720
        (Initialize-Collector -Name 'test' -ConfigPath (New-TempConfig ($config + @{ LookbackHours = 720 })) -LookbackHours 12).LookbackHours | Should -Be 12
    }
    It 'loads runs already sent from the state file' {
        $path = New-TempConfig $config @{ 'run-1' = [DateTimeOffset]::Now.ToUnixTimeSeconds() }
        $null = Initialize-Collector -Name 'test' -ConfigPath $path
        Test-RunSent 'run-1' | Should -BeTrue
        Test-RunSent 'run-2' | Should -BeFalse
    }
 }
 Describe 'Send-JobReport and Complete-Collector' {
    BeforeEach {
        $path = New-TempConfig $config @{
            'recent' = [DateTimeOffset]::Now.AddHours(-10).ToUnixTimeSeconds()
            'stale'  = [DateTimeOffset]::Now.AddHours(-100).ToUnixTimeSeconds()  # > 48h + 1 day ago
        }
        $statePath = Join-Path (Split-Path $path) 'test-collector.state.json'
        $job = [ordered]@{ external_id = 'j1'; name = 'Job'; next_run_at = $null }
    }
    It 'records a finished run as sent, but not a running one' {
        $null = Initialize-Collector -Name 'test' -ConfigPath $path -DryRun
        $null = Send-JobReport -Tenant 'Acme' -SourceSystem 'Test' -Job $job -Run ([ordered]@{ status = 'success' }) -SentKey 'done' -StartedAt (Get-Date) 6>&1
        $null = Send-JobReport -Tenant 'Acme' -SourceSystem 'Test' -Job $job -Run ([ordered]@{ status = 'running' }) -SentKey 'busy' -StartedAt (Get-Date) 6>&1
        Test-RunSent 'done' | Should -BeTrue
        Test-RunSent 'busy' | Should -BeFalse
    }
    It 'prints the payload in a dry run, with the job and run' {
        $null = Initialize-Collector -Name 'test' -ConfigPath $path -DryRun
        $printed = Send-JobReport -Tenant 'Acme' -SourceSystem 'Test' -Job $job -Run ([ordered]@{ status = 'success' }) -SentKey 'x' -StartedAt (Get-Date) 6>&1
        $payload = "$printed" | ConvertFrom-Json
        $payload.tenant | Should -Be 'Acme'
        $payload.source_system | Should -Be 'Test'
        $payload.job.external_id | Should -Be 'j1'
        $payload.run.status | Should -Be 'success'
    }
    It 'saves the state, dropping runs older than the lookback window plus a day' {
        $null = Initialize-Collector -Name 'test' -ConfigPath $path
        $null = Complete-Collector -Failures 0 6>&1
        $saved = Get-Content $statePath -Raw | ConvertFrom-Json
        $saved.PSObject.Properties.Name | Should -Be @('recent')
    }
    It "doesn't touch the state in a dry run" {
        $before = Get-Content $statePath -Raw
        $null = Initialize-Collector -Name 'test' -ConfigPath $path -DryRun
        $null = Complete-Collector -Failures 0 6>&1
        Get-Content $statePath -Raw | Should -Be $before
    }
    It 'returns exit code 1 when anything failed, 0 otherwise' {
        $null = Initialize-Collector -Name 'test' -ConfigPath $path -DryRun
        Complete-Collector -Failures 0 6>$null | Should -Be 0
        Complete-Collector -Failures 2 6>$null | Should -Be 1
    }
    It 'logs a summary with or without a job count' {
        $null = Initialize-Collector -Name 'test' -ConfigPath $path -DryRun
        "$(Complete-Collector -JobCount 3 -Failures 0 6>&1 | Select-Object -First 1)" | Should -Match 'Reported 3 jobs, 0 runs, 0 failures$'
        "$(Complete-Collector -Failures 1 6>&1 | Select-Object -First 1)" | Should -Match 'Reported 0 runs, 1 failures$'
    }
 }
 Describe 'Test-AuthRejected' {
    It 'is true only for HTTP 401' {
        $error401 = [pscustomobject]@{ Exception = [pscustomobject]@{ Response = [pscustomobject]@{ StatusCode = 401 } } }
        $error500 = [pscustomobject]@{ Exception = [pscustomobject]@{ Response = [pscustomobject]@{ StatusCode = 500 } } }
        $noResponse = [pscustomobject]@{ Exception = [pscustomobject]@{ Message = 'timeout' } }
        Test-AuthRejected $error401 | Should -BeTrue
        Test-AuthRejected $error500 | Should -BeFalse
        Test-AuthRejected $noResponse | Should -BeFalse
    }
 }
@@ -0,0 +1,43 @@
 # Collector tests
 Pester tests for the collectors, the shared module and the installers. Each collector runs against
 its mock (`collectors/<name>/tests/Mock*.ps1`, built from real servers' diagnostic output) and a
 stand-in for the ingest API, so no backup product or dashboard is needed.
 ```powershell
 Install-Module Pester -MinimumVersion 5.5 -Scope CurrentUser   # once
 ./collectors/tests/Invoke-CollectorTests.ps1                    # everything, ~15 s
 ./collectors/tests/Invoke-CollectorTests.ps1 -Path ./collectors/tests/Wsb.Tests.ps1
 ```
 Needs PowerShell 7.2+ to run the tests. Collectors run in their own process, under the same
 PowerShell by default. On Windows, run them under Windows PowerShell 5.1, as the MARS, WSB and
 VB365 servers do:
 ```powershell
 ./collectors/tests/Invoke-CollectorTests.ps1 -CollectorShell powershell.exe
 ```
 The runner exits non-zero if anything fails.
 ## What's covered
 | File | Checks |
 |---|---|
 | `Module.Tests.ps1` | `BackupDashboard.Collector.psm1`: property lookup, time format, config and lookback, state (recording sent runs, pruning), dry runs, exit codes, 401 detection |
 | `Veeam.Tests.ps1` | Next run from the live schedule (VBR 13), none for copy/disabled jobs; copy-job worker sessions; statuses and messages; state and resending; rejected key; missing config |
 | `Mars.Tests.ps1` | UTC job times; ErrorCode 0 isn't an error; failed files → warning; next run from the schedule; JobName; state |
 | `Wsb.Tests.ps1` | Culture-formatted times (en-US and en-GB); VMs nested in VirtualMachineList; HRESULTs; failure log only when relevant; running → finished merging on start time |
 | `Vb365.Tests.ps1` | Organization → company mapping; `[Warning]`/`[Failed]` log prefixes; retries; "187.2 MB" sizes; state |
 | `Installers.Tests.ps1` | Config written (incl. the VB365 map), files copied (collector + module), task registered (shell, interval, SYSTEM), refusals before changing anything |
 Each of these was a real bug or a real-server finding. To check the suite still catches them,
 put one back (e.g. read `$Job.ScheduleOptions.NextRun` instead of `GetScheduleOptions()` in the
 Veeam collector) and run the tests: they should fail.
 ## Adding a collector
 1. Write `collectors/<name>/tests/Mock<Name>.ps1` from the product's diagnostic output, taking
   its time from `$env:MOCK_NOW` like the others.
 2. Add `<name>` to `Invoke-Collector`'s `ValidateSet` in `TestHelpers.psm1`.
 3. Add `<Name>.Tests.ps1`, one `It` per behaviour confirmed on a real server.
@@ -0,0 +1,166 @@
 <#
    Helpers for the collector tests: run a collector against its mock in a separate PowerShell
    process, and stand in for the dashboard's ingest API.
    Each collector run gets its own process so the mocks' global functions and the collector's
    `exit` don't leak between tests. The shell is the one running the tests, or
    $env:COLLECTOR_TEST_SHELL (e.g. powershell.exe, to run the collectors under Windows
    PowerShell 5.1 like most servers do).
 #>
 $script:CollectorsDir = Split-Path -Parent $PSScriptRoot
 $script:Invariant = [Globalization.CultureInfo]::InvariantCulture
 # Temp folders for this test run live under one root, which Invoke-CollectorTests.ps1 removes
 function New-TestDir([string]$Prefix = 'test') {
    $root = if ($env:COLLECTOR_TEST_TEMP) { $env:COLLECTOR_TEST_TEMP } else { Join-Path ([IO.Path]::GetTempPath()) 'backup-dashboard-tests' }
    $dir = Join-Path $root ("$Prefix-" + [guid]::NewGuid().ToString('N').Substring(0, 12))
    New-Item -ItemType Directory -Path $dir -Force | Out-Null
    return $dir
 }
 function Get-TestShell {
    if ($env:COLLECTOR_TEST_SHELL) { return $env:COLLECTOR_TEST_SHELL }
    return (Get-Process -Id $PID).Path
 }
 <#
    Pins the time the mocks are relative to (the top of the current hour) for this test session,
    so a test can't fail because the hour turned over between the run and the assertions.
    Returns it as a local DateTime.
 #>
 function Set-MockNow {
    $now = Get-Date -Minute 0 -Second 0 -Millisecond 0
    $env:MOCK_NOW = $now.ToString('o', $script:Invariant)
    return [datetime]$env:MOCK_NOW
 }
 # The API's time format: "2026-10-08T21:00:00-06:00"
 function ConvertTo-ApiTime([datetime]$Value) {
    return ([DateTimeOffset]$Value).ToString("yyyy-MM-dd'T'HH:mm:sszzz", $script:Invariant)
 }
 # JSON with date-looking strings left as strings (PowerShell 7.5+ would otherwise make them DateTimes)
 function ConvertFrom-JsonText([string]$Json) {
    if ((Get-Command ConvertFrom-Json).Parameters.ContainsKey('DateKind')) {
        return $Json | ConvertFrom-Json -DateKind String
    }
    return $Json | ConvertFrom-Json
 }
 function ConvertTo-PSLiteral([string]$Value) { return "'" + $Value.Replace("'", "''") + "'" }
 <#
    Runs one collector against its mock. Returns:
      ExitCode  the collector's exit code (0 when it ends normally)
      Reports   in -DryRun, the payloads it would have sent
      Log       its log lines (timestamp stripped), from the console
      State     the sent-runs state file, as a hashtable (empty if none)
      WorkDir   pass back in to run again with the same config and state
 #>
 function Invoke-Collector {
    param(
        [Parameter(Mandatory, Position = 0)][ValidateSet('veeam', 'mars', 'wsb', 'vb365')][string]$Name,
        [Parameter(Mandatory)][hashtable]$Config,
        [string]$WorkDir,
        [switch]$DryRun,
        [string]$MockArgs = '',
        [string]$Culture = 'en-US',
        [string]$ExtraArgs = '',
        [string]$ComputerName = 'SRV01'
    )
    $dir = Join-Path $script:CollectorsDir $Name
    $script = (Get-ChildItem (Join-Path $dir 'Send-*.ps1')).FullName
    $mock = (Get-ChildItem (Join-Path (Join-Path $dir 'tests') 'Mock*.ps1')).FullName
    if (-not $WorkDir) {
        $WorkDir = New-TestDir $Name
    }
    $configPath = Join-Path $WorkDir "$Name-collector.json"
    $Config | ConvertTo-Json -Depth 5 | Set-Content -Path $configPath -Encoding UTF8
    $command = @(
        "[Globalization.CultureInfo]::CurrentCulture = '$Culture'"
        ". $(ConvertTo-PSLiteral $mock) $MockArgs"
        "& $(ConvertTo-PSLiteral $script) -ConfigPath $(ConvertTo-PSLiteral $configPath) $(if ($DryRun) { '-DryRun' }) $ExtraArgs"
        'exit $LASTEXITCODE'
    ) -join '; '
    $savedComputer = $env:COMPUTERNAME
    $env:COMPUTERNAME = $ComputerName
    try {
        $output = @(& (Get-TestShell) -NoProfile -NonInteractive -Command $command 2>&1 | ForEach-Object { "$_" })
        $exitCode = $LASTEXITCODE
    } finally {
        $env:COMPUTERNAME = $savedComputer
    }
    $state = @{}
    $statePath = Join-Path $WorkDir "$Name-collector.state.json"
    if (Test-Path $statePath) {
        $saved = ConvertFrom-JsonText (Get-Content $statePath -Raw)
        if ($saved) { foreach ($p in $saved.PSObject.Properties) { $state[$p.Name] = $p.Value } }
    }
    return [pscustomobject]@{
        ExitCode = $exitCode
        # Payloads are single-line JSON; a logged API error body spans several lines starting with '{'
        Reports  = @($output | Where-Object { $_ -match '^\{".*\}$' } | ForEach-Object { ConvertFrom-JsonText $_ })
        Log      = @($output | Where-Object { $_ -match '^\d{4}-\d\d-\d\d \d\d:\d\d:\d\d \[' } | ForEach-Object { $_.Substring(20) })
        Output   = $output
        State    = $state
        WorkDir  = $WorkDir
    }
 }
 <#
    A stand-in for the ingest API on a free localhost port. Records every request; answers 401
    for API keys containing "bad", 200 otherwise. Stop it with Stop-ApiStub.
 #>
 function Start-ApiStub {
    $probe = [Net.Sockets.TcpListener]::new([Net.IPAddress]::Loopback, 0)
    $probe.Start(); $port = $probe.LocalEndpoint.Port; $probe.Stop()
    $listener = [Net.HttpListener]::new()
    $listener.Prefixes.Add("http://localhost:$port/")
    $listener.Start()
    $requests = [Collections.Concurrent.ConcurrentQueue[object]]::new()
    $job = Start-ThreadJob -ArgumentList $listener, $requests -ScriptBlock {
        param($listener, $requests)
        while ($listener.IsListening) {
            try { $context = $listener.GetContext() } catch { break }
            $body = [IO.StreamReader]::new($context.Request.InputStream, [Text.Encoding]::UTF8).ReadToEnd()
            $auth = $context.Request.Headers['Authorization']
            $requests.Enqueue([pscustomobject]@{
                Path = $context.Request.Url.AbsolutePath; Auth = $auth
                ContentType = $context.Request.ContentType; Body = $body
            })
            $rejected = $auth -match 'bad'
            $reply = if ($rejected) { '{"detail":"Invalid or revoked API key"}' } else { '{"job_id":1,"run_id":1}' }
            $bytes = [Text.Encoding]::UTF8.GetBytes($reply)
            $context.Response.StatusCode = $(if ($rejected) { 401 } else { 200 })
            $context.Response.ContentType = 'application/json'
            $context.Response.OutputStream.Write($bytes, 0, $bytes.Length)
            $context.Response.Close()
        }
    }
    return [pscustomobject]@{ Url = "http://localhost:$port"; Listener = $listener; Requests = $requests; Job = $job }
 }
 # Takes the requests recorded since the last call; Body is the parsed JSON payload
 function Get-StubRequests($Stub) {
    $taken = @()
    $item = $null
    while ($Stub.Requests.TryDequeue([ref]$item)) {
        $item | Add-Member -NotePropertyName Payload -NotePropertyValue (ConvertFrom-JsonText $item.Body) -Force
        $taken += $item
    }
    return , $taken
 }
 function Stop-ApiStub($Stub) {
    $Stub.Listener.Stop()
    $Stub.Listener.Close()
    $Stub.Job | Stop-Job -PassThru | Remove-Job -Force
 }
 Export-ModuleMember -Function New-TestDir, Set-MockNow, ConvertTo-ApiTime, ConvertFrom-JsonText, Invoke-Collector,
    Start-ApiStub, Get-StubRequests, Stop-ApiStub
@@ -0,0 +1,116 @@
 # Veeam Backup for Microsoft 365 collector, against collectors/vb365/tests/MockVb365.ps1 (shapes from
 # a VB365 8.4 server: log items carry their status as a Title prefix, retries are separate sessions).
 BeforeAll {
    Import-Module (Join-Path $PSScriptRoot 'TestHelpers.psm1') -Force
    $now = Set-MockNow
    $base = @{ ApiUrl = 'http://localhost:1'; ApiKey = 'bdk_x' }
    function Get-JobRuns($Reports, [string]$JobName) {
        @($Reports | Where-Object { $_.job.name -eq $JobName -and $_.run } | ForEach-Object run)
    }
    function Get-Tenants($Reports) {
        $map = @{}
        foreach ($report in $Reports) { $map[$report.job.name] = $report.tenant }
        return $map
    }
 }
 Describe 'VB365 collector' {
    Context 'what it reports (dry run)' {
        BeforeAll {
            $r = Invoke-Collector vb365 -Config ($base + @{ Tenant = 'Default Co' }) -DryRun
            $acme = Get-JobRuns $r.Reports 'Acme 365 Backup'
            $blue = Get-JobRuns $r.Reports 'Bluewater 365 Backup'
        }
        It 'runs cleanly, reporting every job' {
            $r.ExitCode | Should -Be 0
            $r.Log[-1] | Should -Be '[INFO] Reported 3 jobs, 5 runs, 0 failures'
            $r.Reports.source_system | Select-Object -Unique | Should -Be 'Veeam Backup for M365'
        }
        It "uses each job's NextRun, and none for a disabled job" {
            $next = $now.Date.AddHours(17).AddDays($(if ($now.Hour -ge 17) { 1 } else { 0 }))
            ($r.Reports | Where-Object { $_.job.name -eq 'Acme 365 Backup' })[0].job.next_run_at | Should -Be (ConvertTo-ApiTime $next)
            ($r.Reports | Where-Object { $_.job.name -eq 'Bluewater Old Mailboxes' })[0].job.next_run_at | Should -BeNullOrEmpty
        }
        It 'reports a successful session with its size ("187.2 MB" in bytes) and objects' {
            $run = $acme | Where-Object status -EQ 'success'
            $run.started_at | Should -Be (ConvertTo-ApiTime $now.Date.AddDays(-1).AddHours(17))
            $run.size_bytes | Should -Be ([long](187.2 * 1MB))
            $run.details.processed_objects | Should -Be 568
            $run.details.organization | Should -Be 'acme.onmicrosoft.com'
            $run.message | Should -Be 'Job completed successfully.'
        }
        It 'reports a session in progress as running, without a finish time' {
            $run = $acme | Where-Object status -EQ 'running'
            $run.PSObject.Properties.Name | Should -Not -Contain 'finished_at'
            $run.message | Should -Be ''
        }
        It 'builds the message from [Warning]/[Failed] log items, without the prefix' {
            $run = $blue | Where-Object status -EQ 'warning'
            $run.message | Should -BeLike 'Processing mailbox [email protected] finished with warning: Item "Q3.pst" exceeds the maximum size*'
            # Literal check: in -like patterns, [Warning] is a character set
            $run.message.Contains('[Warning]') | Should -BeFalse
        }
        It 'ignores [Success] log items, even ones mentioning "error"' {
            ($blue | Where-Object status -EQ 'warning').message | Should -Not -BeLike '*error-reports*'
        }
        It 'flags a session VB365 will retry, and links the retry back to it' {
            $warning = $blue | Where-Object status -EQ 'warning'
            $retry = $blue | Where-Object { $_.details.retry_of }
            $warning.message | Should -BeLike '*Veeam will retry this job.'
            $warning.details.will_retry | Should -BeTrue
            $retry.status | Should -Be 'success'
            $retry.details.retry_of | Should -Be $warning.external_id
        }
        It 'reports a failed session with its error' {
            $run = $blue | Where-Object status -EQ 'failed'
            $run.message | Should -BeLike '*(401) Unauthorized*'
        }
        It 'skips sessions outside the lookback window' {
            Get-JobRuns $r.Reports 'Bluewater Old Mailboxes' | Should -BeNullOrEmpty
        }
    }
    Context 'which company a job appears under' {
        It 'uses OrganizationTenants (not case-sensitive), then Tenant for unmapped organizations' {
            $r = Invoke-Collector vb365 -DryRun -Config ($base + @{
                    Tenant = 'Default Co'; OrganizationTenants = @{ 'ACME.onmicrosoft.com' = 'Acme Corp' } })
            $tenants = Get-Tenants $r.Reports
            $tenants['Acme 365 Backup'] | Should -Be 'Acme Corp'
            $tenants['Bluewater 365 Backup'] | Should -Be 'Default Co'
        }
        It "falls back to the organization's name with no mapping and no Tenant" {
            $r = Invoke-Collector vb365 -Config $base -DryRun
            $r.ExitCode | Should -Be 0
            $tenants = Get-Tenants $r.Reports
            $tenants['Acme 365 Backup'] | Should -Be 'acme.onmicrosoft.com'
            $tenants['Bluewater 365 Backup'] | Should -Be 'bluewater.onmicrosoft.com'
        }
    }
    Context 'sending to the API' {
        BeforeAll {
            $stub = Start-ApiStub
            $live = $base + @{ Tenant = 'Default Co' }; $live.ApiUrl = $stub.Url
            $first = Invoke-Collector vb365 -Config $live
            $firstRequests = Get-StubRequests $stub
            $second = Invoke-Collector vb365 -Config $live -WorkDir $first.WorkDir
            $secondRequests = Get-StubRequests $stub
        }
        AfterAll { Stop-ApiStub $stub }
        It 'sends every session, remembering the finished ones' {
            $first.ExitCode | Should -Be 0
            @($firstRequests | Where-Object { $_.Payload.run }).Count | Should -Be 5
            $first.State.Count | Should -Be 4
        }
        It 'on the next run, resends only the running session (and refreshes every job)' {
            $resent = @($secondRequests | Where-Object { $_.Payload.run })
            $resent.Count | Should -Be 1
            $resent[0].Payload.run.status | Should -Be 'running'
            $secondRequests.Count | Should -Be 3
        }
    }
 }
@@ -0,0 +1,127 @@
 # Veeam B&R collector, against collectors/veeam/tests/MockVeeam.ps1 (shapes from a VBR 13 server).
 BeforeAll {
    Import-Module (Join-Path $PSScriptRoot 'TestHelpers.psm1') -Force
    $now = Set-MockNow
    $dash = [char]0x2013  # job names use an en dash, as real ones often do
    $fileServer = "File Server $dash Nightly"
    $config = @{ ApiUrl = 'http://localhost:1'; ApiKey = 'bdk_x'; Tenant = 'Acme' }
    function Get-Runs($Reports, [string]$JobName) {
        @($Reports | Where-Object { $_.job.name -eq $JobName -and $_.run } | ForEach-Object run)
    }
 }
 Describe 'Veeam collector' {
    Context 'what it reports (dry run)' {
        BeforeAll {
            $r = Invoke-Collector veeam -Config $config -DryRun
            $jobs = @{}
            foreach ($report in $r.Reports) { $jobs[$report.job.name] = $report.job }
        }
        It 'runs cleanly' {
            $r.ExitCode | Should -Be 0
            $r.Log[-1] | Should -Be '[INFO] Reported 5 jobs, 6 runs, 0 failures'
        }
        It 'reports every job, under the configured tenant' {
            $jobs.Keys | Sort-Object | Should -Be @('Cloud Copy', $fileServer, 'Offsite Copy', 'Old Exchange', "SQL01 $dash Logs")
            $r.Reports.tenant | Select-Object -Unique | Should -Be 'Acme'
            $r.Reports.source_system | Select-Object -Unique | Should -Be 'Veeam B&R'
        }
        It "reads the next run from the live schedule (VBR 13's ScheduleOptions property is empty)" {
            $jobs[$fileServer].next_run_at | Should -Be (ConvertTo-ApiTime $now.Date.AddDays(1).AddMinutes(15))
            $jobs["SQL01 $dash Logs"].next_run_at | Should -Be (ConvertTo-ApiTime $now.AddMinutes(40))
        }
        It 'gives no next run to immediate-mode copy jobs (their NextRun is stale), disabled or unscheduled jobs' {
            $jobs['Cloud Copy'].next_run_at | Should -BeNullOrEmpty
            $jobs['Old Exchange'].next_run_at | Should -BeNullOrEmpty
            $jobs['Offsite Copy'].next_run_at | Should -BeNullOrEmpty
        }
        It 'reports a successful session with its times and size' {
            $run = Get-Runs $r.Reports $fileServer | Where-Object status -EQ 'success'
            $run.started_at | Should -Be (ConvertTo-ApiTime $now.AddDays(-1).AddHours(-2))
            $run.finished_at | Should -Be (ConvertTo-ApiTime $now.AddDays(-1).AddHours(-1))
            $run.size_bytes | Should -Be 128GB
            $run.message | Should -Be 'Job completed successfully.'
            $run.details.objects | Should -Be 2
        }
        It 'reports a session in progress as running, without a finish time' {
            $run = Get-Runs $r.Reports $fileServer | Where-Object status -EQ 'running'
            $run.started_at | Should -Be (ConvertTo-ApiTime $now.AddMinutes(-20))
            $run.PSObject.Properties.Name | Should -Not -Contain 'finished_at'
            $run.message | Should -Be ''
        }
        It 'names the object behind a warning' {
            $run = Get-Runs $r.Reports "SQL01 $dash Logs"
            $run.status | Should -Be 'warning'
            $run.message | Should -BeLike 'SQL01: Warning - Failed to truncate transaction logs*'
            $run.details.objects_warning | Should -Be 1
        }
        It "includes a failure's reason and failed log lines, but not successful ones" {
            $run = Get-Runs $r.Reports 'Offsite Copy'
            $run.status | Should -Be 'failed'
            $run.message | Should -BeLike '*Unable to connect to repository NAS02*'
            $run.message | Should -BeLike '*Network path not found (0x80070035)*'
            $run.message | Should -Not -BeLike '*Preparing backup chain*'
        }
        It "files copy jobs' worker sessions under the copy job, naming the source" {
            $runs = Get-Runs $r.Reports 'Cloud Copy'
            $runs.status | Sort-Object | Should -Be @('success', 'warning')
            $runs.details.copied_from | Select-Object -Unique | Should -Be $fileServer
        }
        It "skips sessions outside the lookback window and from jobs it doesn't know" {
            @($r.Reports | Where-Object run).Count | Should -Be 6
            Get-Runs $r.Reports 'Old Exchange' | Should -BeNullOrEmpty
        }
    }
    Context 'sending to the API' {
        BeforeAll {
            $stub = Start-ApiStub
            $live = $config.Clone(); $live.ApiUrl = $stub.Url; $live.ApiKey = 'bdk_good'
            $first = Invoke-Collector veeam -Config $live
            $firstRequests = Get-StubRequests $stub
            $second = Invoke-Collector veeam -Config $live -WorkDir $first.WorkDir
            $secondRequests = Get-StubRequests $stub
        }
        AfterAll { Stop-ApiStub $stub }
        It 'posts each report to /api/v1/ingest with the API key, as UTF-8 JSON' {
            $first.ExitCode | Should -Be 0
            $firstRequests.Count | Should -Be 7
            $firstRequests.Path | Select-Object -Unique | Should -Be '/api/v1/ingest'
            $firstRequests.Auth | Select-Object -Unique | Should -Be 'Bearer bdk_good'
            $firstRequests.ContentType | Select-Object -Unique | Should -Be 'application/json; charset=utf-8'
        }
        It 'keeps non-ASCII job names intact' {
            $firstRequests.Payload.job.name | Should -Contain $fileServer
        }
        It 'remembers finished sessions, but not running ones' {
            $first.State.Count | Should -Be 5
        }
        It 'on the next run, resends only the running session (and refreshes every job)' {
            $resent = @($secondRequests | Where-Object { $_.Payload.run })
            $resent.Count | Should -Be 1
            $resent[0].Payload.run.status | Should -Be 'running'
            $secondRequests.Count | Should -Be 5
        }
    }
    Context 'problems' {
        It 'stops after the first job when the API key is rejected, exiting 1' {
            $stub = Start-ApiStub
            try {
                $r = Invoke-Collector veeam -Config @{ ApiUrl = $stub.Url; ApiKey = 'bdk_bad'; Tenant = 'Acme' }
                (Get-StubRequests $stub).Count | Should -Be 1
                $r.ExitCode | Should -Be 1
                $r.Log | Should -Contain '[ERROR] API key rejected; check ApiKey in the config. Stopping.'
            } finally { Stop-ApiStub $stub }
        }
        It 'exits 2 when the config lacks a tenant' {
            $r = Invoke-Collector veeam -Config @{ ApiUrl = 'http://localhost:1'; ApiKey = 'bdk_x' } -DryRun
            $r.ExitCode | Should -Be 2
            $r.Log[0] | Should -BeLike "*is missing 'Tenant'*"
        }
    }
 }
@@ -0,0 +1,108 @@
 # Windows Server Backup collector, against collectors/wsb/tests/MockWsb.ps1 (shapes from a Server
 # 2019 Hyper-V host: job times are culture-formatted local-time strings, HRESULTs are strings,
 # VMs are nested under a VirtualMachineList item).
 BeforeAll {
    Import-Module (Join-Path $PSScriptRoot 'TestHelpers.psm1') -Force
    $now = Set-MockNow
    $config = @{ ApiUrl = 'http://localhost:1'; ApiKey = 'bdk_x'; Tenant = 'Acme' }
    $vms = @('AAOG-EDM-AD1', 'Host Component')
    $hostComponentBytes = 447729
 }
 Describe 'Windows Server Backup collector' {
    Context 'what it reports (dry run)' {
        BeforeAll {
            $r = Invoke-Collector wsb -Config $config -DryRun
            $runs = @($r.Reports | Where-Object run | ForEach-Object run)
            $byStart = @{}
            foreach ($run in $runs) { $byStart[$run.started_at] = $run }
            function At([double]$HoursAgo) { $byStart[(ConvertTo-ApiTime $now.AddHours(-$HoursAgo))] }
        }
        It 'runs cleanly' {
            $r.ExitCode | Should -Be 0
            $r.Log[-1] | Should -Be '[INFO] Reported 4 runs, 0 failures'
        }
        It 'reports the server as one job, with the next backup from Get-WBSummary' {
            $r.Reports.job.external_id | Select-Object -Unique | Should -Be 'wsb:srv01'
            $r.Reports.job.name | Select-Object -Unique | Should -Be 'SRV01 - Windows Server Backup'
            $r.Reports.source_system | Select-Object -Unique | Should -Be 'Windows Server Backup'
            $next = $now.Date.AddHours(21).AddDays($(if ($now.Hour -ge 21) { 1 } else { 0 }))
            $r.Reports[0].job.next_run_at | Should -Be (ConvertTo-ApiTime $next)
        }
        It 'reads job times as local time, and sends no run ID (WSB jobs have none; the API keys on start time)' {
            (At 12).finished_at | Should -Be (ConvertTo-ApiTime $now.AddHours(-11.6))
            $runs | ForEach-Object { $_.PSObject.Properties.Name | Should -Not -Contain 'external_id' }
        }
        It 'reports a Hyper-V backup with its VMs (nested in VirtualMachineList) and size' {
            $run = At 12
            $run.status | Should -Be 'success'
            $run.message | Should -Be 'Backup completed successfully.'
            $run.details.items | Should -Be $vms
            $run.size_bytes | Should -Be (124756706036 + $hostComponentBytes)
        }
        It "doesn't cite the failure log for a success (WSB fills it in regardless)" {
            (At 12).message | Should -Not -BeLike '*Failure log*'
        }
        It 'reports a backup where one VM failed as a warning, naming the VM' {
            $run = At 36
            $run.status | Should -Be 'warning'
            $run.message | Should -BeLike '*AAOG-EDM-AD1 - Access is denied.*'
            $run.message | Should -BeLike '*Failure log: C:\Windows\Logs\WindowsServerBackup\Backup_Error.log*'
        }
        It 'reports a backup with an error HRESULT as failed, with the code in 0x8 form' {
            $run = At 30
            $run.status | Should -Be 'failed'
            $run.message | Should -BeLike '*The backup storage location could not be found.*'
            $run.message | Should -BeLike '*error 0x80042302*'
        }
        It 'reports a volume backup with its volumes and size' {
            $run = At 20
            $run.status | Should -Be 'success'
            $run.details.items | Should -Be @('C:', 'D:')
            $run.size_bytes | Should -Be (240GB)
        }
        It "ignores restores, old backups, and Get-WBJob's empty job when nothing is running" {
            $runs.Count | Should -Be 4
        }
        It 'reads dd/MM dates correctly on servers with other regional settings' {
            $gb = Invoke-Collector wsb -Config $config -DryRun -Culture 'en-GB'
            ($gb.Reports | ConvertTo-Json -Depth 6) | Should -Be ($r.Reports | ConvertTo-Json -Depth 6)
        }
        It 'reports a backup in progress as running, with no message' {
            $running = Invoke-Collector wsb -Config $config -DryRun -MockArgs '-WithRunningJob'
            $run = $running.Reports | Where-Object { $_.run.status -eq 'running' } | ForEach-Object run
            $run.started_at | Should -Be (ConvertTo-ApiTime $now.AddMinutes(-10))
            $run.message | Should -Be ''
            $run.PSObject.Properties.Name | Should -Not -Contain 'finished_at'
            $run.details.items | Should -Be $vms
        }
    }
    Context 'sending to the API' {
        BeforeAll {
            $stub = Start-ApiStub
            $live = $config.Clone(); $live.ApiUrl = $stub.Url
            $first = Invoke-Collector wsb -Config $live -MockArgs '-WithRunningJob'
            $firstRequests = Get-StubRequests $stub
            $second = Invoke-Collector wsb -Config $live -WorkDir $first.WorkDir -MockArgs '-RunningJobFinished'
            $secondRequests = Get-StubRequests $stub
        }
        AfterAll { Stop-ApiStub $stub }
        It 'sends every run, remembering the finished ones' {
            $first.ExitCode | Should -Be 0
            $firstRequests.Count | Should -Be 5
            $first.State.Count | Should -Be 4
        }
        It 'sends the finished backup once it ends, with the same start time, so the API merges it into the running one' {
            $running = $firstRequests.Payload.run | Where-Object status -EQ 'running'
            $secondRequests.Count | Should -Be 1
            $finished = $secondRequests[0].Payload.run
            $finished.status | Should -Be 'success'
            $finished.started_at | Should -Be $running.started_at
            $second.State.Count | Should -Be 5
        }
    }
 }
@@ -23,7 +23,7 @@ one with `python manage.py delete-job <id>`.
 ## Install (on the VB365 server, as an administrator)
-1. On the dashboard host, create a key for this server:
+1. Create a key for this server on the dashboard's **Admin** page, or on the dashboard host:
   ```bash
   python manage.py create-key vb365-01
   ```
@@ -8,7 +8,8 @@
 #   ./Send-Vb365BackupStatus.ps1 -ConfigPath ./my-test-config.json -DryRun
 # Fixed to the top of the hour, and IDs derived from names/times, so repeated runs see the same data
-$now = Get-Date -Minute 0 -Second 0 -Millisecond 0
+# MOCK_NOW (ISO 8601, set by the test suite) pins the time everything is relative to
 $now = if ($env:MOCK_NOW) { [datetime]$env:MOCK_NOW } else { Get-Date -Minute 0 -Second 0 -Millisecond 0 }
 function New-StableGuid([string]$Seed) {
    [guid]::new([Security.Cryptography.MD5]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($Seed)))
 }
@@ -9,7 +9,7 @@ Requires PowerShell 7 installed machine-wide (`winget install Microsoft.PowerShe
 which VBR 13's Veeam module expects. The Microsoft Store version won't work, because the SYSTEM
 account can't run it. The installer checks for this before changing anything.
-1. On the dashboard host, create a key for this server:
+1. Create a key for this server on the dashboard's **Admin** page, or on the dashboard host:
   ```bash
   python manage.py create-key veeam-acme
   ```
@@ -6,7 +6,8 @@
 # Fixed to the top of the hour, and IDs derived from names/times, so repeated runs see the same
 # jobs and sessions, like a real server
-$now = Get-Date -Minute 0 -Second 0 -Millisecond 0
+# MOCK_NOW (ISO 8601, set by the test suite) pins the time everything is relative to
 $now = if ($env:MOCK_NOW) { [datetime]$env:MOCK_NOW } else { Get-Date -Minute 0 -Second 0 -Millisecond 0 }
 function New-StableGuid([string]$Seed) {
    [guid]::new([Security.Cryptography.MD5]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($Seed)))
 }
@@ -15,7 +15,7 @@ Requires the Windows Server Backup feature with its PowerShell module
 (`Install-WindowsFeature Windows-Server-Backup`). Runs under Windows PowerShell 5.1
 (`powershell.exe`), which that module targets.
-1. On the dashboard host, create a key for this server:
+1. Create a key for this server on the dashboard's **Admin** page, or on the dashboard host:
   ```bash
   python manage.py create-key wsb-acme-dc01
   ```
@@ -6,11 +6,13 @@
 #
 #   . ./tests/MockWsb.ps1                  # nothing running
 #   . ./tests/MockWsb.ps1 -WithRunningJob  # a backup in progress
 #   . ./tests/MockWsb.ps1 -RunningJobFinished  # that same backup, now finished
 #   ./Send-WsbBackupStatus.ps1 -ConfigPath ./my-test-config.json -DryRun
-param([switch]$WithRunningJob)
+param([switch]$WithRunningJob, [switch]$RunningJobFinished)
 # Fixed to the top of the hour so repeated runs see the same jobs
-$now = Get-Date -Minute 0 -Second 0 -Millisecond 0
+# MOCK_NOW (ISO 8601, set by the test suite) pins the time everything is relative to
 $now = if ($env:MOCK_NOW) { [datetime]$env:MOCK_NOW } else { Get-Date -Minute 0 -Second 0 -Millisecond 0 }
 # Same format as the real cmdlet: short date + short time in the current culture
 function Format-WbTime($Value) {
@@ -83,6 +85,9 @@ $global:MockWsbPrevious = @(
    (New-MockJob 'Recovery' $now.AddHours(-5) $now.AddHours(-4) 'Completed'),  # a restore: must be ignored
    (New-MockJob 'Backup' $now.AddDays(-5) $now.AddDays(-5).AddHours(1) 'Completed')  # outside 48h lookback
 )
 if ($RunningJobFinished) {
    $global:MockWsbPrevious += New-MockJob 'Backup' $now.AddMinutes(-10) $now.AddMinutes(-2) 'Completed' -Items @(New-VmList 10GB)
 }
 $global:MockWsbSummary = [pscustomobject]@{
    NextBackupTime           = $now.Date.AddHours(21).AddDays($(if ($now.Hour -ge 21) { 1 } else { 0 }))
@@ -2,3 +2,5 @@
 # Read by both the API service and manage.py, so they always use the same database.
 BACKUP_DASH_DB=/var/lib/backup-dashboard/backup-dashboard.db
 BACKUP_DASH_RETENTION_DAYS=90
 # Microsoft 365 sign-in names (comma-separated) allowed into the admin pages (API key management)
 BACKUP_DASH_ADMINS=[email protected]
@@ -0,0 +1,103 @@
 <!doctype html>
 <html lang="en">
 <head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>API keys · Backup Monitor</title>
  <link rel="stylesheet" href="/css/styles.css">
  <script type="module" src="/js/admin.js"></script>
 </head>
 <body>
  <header class="topbar">
    <div class="topbar__nav">
      <a id="back-link" class="btn" href="/">← Dashboard</a>
      <h1 class="topbar__title">API keys</h1>
    </div>
    <div class="topbar__meta">
      <span id="signed-in" class="topbar__user" hidden>
        <span id="signed-in-email" class="muted"></span>
        <a id="sign-out" class="btn" href="#">Sign out</a>
      </span>
    </div>
  </header>
  <main class="container container--narrow">
    <div id="error-banner" class="banner banner--error" role="alert" hidden></div>
    <p id="not-admin" class="banner banner--info" hidden>
      Your account isn't an admin. Admins are the sign-in names listed in <code>BACKUP_DASH_ADMINS</code>
      in the server's settings file.
    </p>
    <div id="admin-content" hidden>
      <section class="panel" aria-labelledby="new-key-title">
        <h2 id="new-key-title" class="panel__title">New key</h2>
        <p class="muted">Create one key per collector install, so each can be revoked on its own.</p>
        <form id="new-key-form" class="new-key">
          <div class="field">
            <label for="key-name">Name</label>
            <span id="key-name-hint" class="hint">For example <code>veeam-acme</code> or <code>mars-acme-fs01</code>:
              letters, digits, <code>.</code>, <code>_</code> and <code>-</code>.</span>
            <input id="key-name" name="name" class="input" required maxlength="64"
                   pattern="[A-Za-z0-9][A-Za-z0-9._\-]{0,63}" autocomplete="off" spellcheck="false"
                   aria-describedby="key-name-hint" aria-errormessage="key-name-error">
            <div id="key-name-error" class="error-msg">
              Use up to 64 letters, digits, <code>.</code>, <code>_</code> or <code>-</code>, starting with a letter or digit.
            </div>
          </div>
          <button id="create-btn" class="btn btn--primary" type="submit">Create key</button>
          <p id="create-error" class="form-error" role="alert" hidden></p>
        </form>
        <div id="new-key-result" class="secret" hidden>
          <h3 id="new-key-result-title" class="secret__title" tabindex="-1">Copy the key for <span id="new-key-name"></span> now</h3>
          <p>It won't be shown again: the dashboard only keeps a hash of it. Paste it when the collector's
            installer asks for the API key.</p>
          <div class="secret__row">
            <code id="new-key-secret" class="secret__value"></code>
            <button id="copy-btn" class="btn" type="button">Copy</button>
          </div>
          <button id="done-btn" class="btn" type="button">Done, hide it</button>
        </div>
      </section>
      <section aria-labelledby="keys-title">
        <h2 id="keys-title" class="panel__title" tabindex="-1">Keys</h2>
        <div class="table-wrap">
          <table class="jobs keys">
            <thead>
              <tr>
                <th scope="col">Name</th>
                <th scope="col">Status</th>
                <th scope="col">Last used</th>
                <th scope="col">Created</th>
                <th scope="col"><span class="visually-hidden">Actions</span></th>
              </tr>
            </thead>
            <tbody id="keys-body"></tbody>
          </table>
          <p id="keys-empty" class="empty" hidden>No keys yet. Create one above for each collector.</p>
        </div>
      </section>
    </div>
    <!-- Announces results (created, copied, revoked) to screen readers -->
    <p id="status" class="visually-hidden" role="status"></p>
  </main>
  <dialog id="revoke-dialog" class="modal modal--small" aria-labelledby="revoke-title">
    <form method="dialog">
      <div class="modal__header">
        <h2 id="revoke-title" class="modal__title">Revoke <span id="revoke-name"></span>?</h2>
      </div>
      <div class="modal__body">
        <p>Collectors using this key will be refused from their next run. This can't be undone: to
          reconnect them, create a new key and re-run their installer.</p>
        <div class="dialog-actions">
          <button class="btn" value="cancel" autofocus>Cancel</button>
          <button class="btn btn--danger" value="revoke">Revoke key</button>
        </div>
      </div>
    </form>
  </dialog>
 </body>
 </html>
@@ -344,4 +344,81 @@ button.badge:hover { filter: brightness(0.95); }
 }
 .runs tbody tr:last-child td { border-bottom: none; }
 .runs tr.is-selected td { background: color-mix(in srgb, var(--accent) 16%, transparent); }
-.runs .badge { font-size: 0.75rem; padding: 0.1rem 0.5rem; }
+.runs .badge { font-size: 0.75rem; padding: 0.1rem 0.5rem; }
 /* ---------- Admin page ---------- */
 .container--narrow { max-width: 1100px; }
 .topbar__nav { display: flex; align-items: center; gap: 1rem; }
 .banner--info { background: var(--surface-alt); color: var(--text); border-color: var(--border); }
 .panel {
  margin-bottom: 1.5rem;
  padding: 1rem 1.25rem 1.25rem;
  background: var(--surface);
  border: 1px solid var(--border);
  border-radius: var(--radius);
  box-shadow: var(--shadow);
 }
 .panel__title { font-size: 1.05rem; margin: 0 0 0.25rem; }
 section > .panel__title { margin: 0 0 0.75rem; }
 .panel__title:focus { outline: none; }  /* focused from script after a change, not by the user */
 .panel p { margin: 0 0 0.75rem; }
 code {
  font-family: ui-monospace, SFMono-Regular, Consolas, monospace;
  font-size: 0.9em;
  overflow-wrap: anywhere;
 }
 /* New key form: label, hint above the input (so autocomplete can't cover it), error below */
 .new-key { display: flex; flex-wrap: wrap; align-items: flex-end; gap: 0.75rem; }
 .field { display: flex; flex-direction: column; gap: 0.25rem; flex: 1 1 22rem; max-width: 30rem; }
 .field label { font-weight: 600; }
 .hint { font-size: 0.85rem; color: var(--muted); }
 .field .input { width: 100%; }
 .error-msg { display: none; font-size: 0.85rem; color: var(--failed-fg); }
 /* Only after the user has interacted with the field (or tried to submit) */
 .field .input:user-invalid { border-color: var(--failed-bd); background: var(--failed-bg); }
 .field .input:user-invalid + .error-msg { display: block; }
 .form-error { flex-basis: 100%; margin: 0; color: var(--failed-fg); }
 .btn--primary { background: var(--accent); border-color: var(--accent); color: #fff; font-weight: 600; }
 .btn--primary:hover { filter: brightness(1.08); border-color: var(--accent); }
 .btn--danger { background: var(--failed-bd); border-color: var(--failed-bd); color: #fff; font-weight: 600; }
 .btn--danger-outline { color: var(--failed-fg); border-color: var(--failed-bd); background: transparent; }
 .btn--danger-outline:hover { background: var(--failed-bg); border-color: var(--failed-bd); }
 /* The one-time key */
 .secret {
  margin-top: 1rem;
  padding: 1rem;
  border: 1px solid var(--warning-bd);
  border-left-width: 4px;
  border-radius: 6px;
  background: var(--warning-bg);
 }
 .secret__title { margin: 0 0 0.5rem; font-size: 1rem; }
 .secret__title:focus { outline: none; }
 .secret__row { display: flex; gap: 0.5rem; align-items: stretch; margin-bottom: 0.75rem; flex-wrap: wrap; }
 .secret__value {
  flex: 1 1 20rem;
  padding: 0.45rem 0.75rem;
  background: var(--surface);
  border: 1px solid var(--border);
  border-radius: 6px;
  user-select: all;  /* one click selects the whole key */
 }
 /* Key table */
 .keys td { vertical-align: top; }
 .keys td .badge { margin-bottom: 0.25rem; }
 .keys td > .time__rel { display: block; }
 .keys .actions { text-align: right; width: 1%; }
 .keys tr.is-revoked td { color: var(--muted); }
 .keys tr.is-revoked code { text-decoration: line-through; }
 .stale-note { display: block; font-size: 0.8rem; font-weight: 600; color: var(--warning-fg); }
 /* Confirm dialog */
 .modal--small { width: min(460px, calc(100vw - 2rem)); }
 .modal--small .modal__body p { margin-top: 0; }
 .dialog-actions { display: flex; justify-content: flex-end; gap: 0.5rem; margin-top: 1rem; }
@@ -14,6 +14,7 @@
    <div class="topbar__meta">
      <span id="last-updated" class="muted" aria-live="polite">Loading…</span>
      <button id="refresh-btn" class="btn" type="button">Refresh</button>
      <a id="admin-link" class="btn" href="/admin.html" hidden>Admin</a>
      <!-- Filled in from /api/v1/me when signed in with Microsoft 365 -->
      <span id="signed-in" class="topbar__user" hidden>
        <span id="signed-in-email" class="muted"></span>
@@ -0,0 +1,228 @@
 // Admin page: create, list and revoke the API keys collectors use.
 import { getApi } from './api.js';
 import { el } from './dom.js';
 import { parseDate, formatDateTime, formatRelative } from './format.js';
 import { showSignedInUser } from './signed-in.js';
 const api = await getApi();
 // A collector runs hourly; an active key quiet for longer than this probably has a problem
 const STALE_HOURS = 24;
 const $ = (sel) => document.querySelector(sel);
 const dom = {
  backLink: $('#back-link'),
  signedIn: $('#signed-in'),
  signedInEmail: $('#signed-in-email'),
  signOut: $('#sign-out'),
  errorBanner: $('#error-banner'),
  notAdmin: $('#not-admin'),
  content: $('#admin-content'),
  form: $('#new-key-form'),
  name: $('#key-name'),
  createBtn: $('#create-btn'),
  createError: $('#create-error'),
  result: $('#new-key-result'),
  resultTitle: $('#new-key-result-title'),
  resultName: $('#new-key-name'),
  secret: $('#new-key-secret'),
  copyBtn: $('#copy-btn'),
  doneBtn: $('#done-btn'),
  keysTitle: $('#keys-title'),
  tbody: $('#keys-body'),
  empty: $('#keys-empty'),
  status: $('#status'),
  dialog: $('#revoke-dialog'),
  revokeName: $('#revoke-name'),
 };
 let keys = [];
 let pendingRevoke = null;
 // ---------- Feedback ----------
 // Screen-reader announcement. Cleared first so repeating the same message is announced again.
 // (A timer rather than requestAnimationFrame, which doesn't run while the tab is in the background.)
 function announce(message) {
  dom.status.textContent = '';
  setTimeout(() => { dom.status.textContent = message; }, 50);
 }
 function showError(message) {
  dom.errorBanner.textContent = message;
  dom.errorBanner.hidden = false;
 }
 // ---------- Key table ----------
 function timeBlock(date, ...extra) {
  return el('time', { class: 'time', datetime: date.toISOString(), title: date.toString() },
    el('span', {}, formatDateTime(date)),
    el('span', { class: 'time__rel' }, formatRelative(date), ...extra));
 }
 function statusCell(key) {
  if (key.revoked_at) {
    return el('td', {},
      el('span', { class: 'badge badge--unknown' }, 'Revoked'),
      el('span', { class: 'time__rel' }, formatDateTime(parseDate(key.revoked_at)),
        key.revoked_by ? ` by ${key.revoked_by}` : null));
  }
  return el('td', {}, el('span', { class: 'badge badge--success' }, 'Active'));
 }
 function lastUsedCell(key) {
  const lastUsed = parseDate(key.last_used_at);
  if (!lastUsed) {
    return el('td', {}, el('span', { class: 'muted' }, key.revoked_at ? 'Never' : 'Never: not installed yet?'));
  }
  const stale = !key.revoked_at && Date.now() - lastUsed.getTime() > STALE_HOURS * 3_600_000;
  return el('td', { class: stale ? 'is-stale' : null },
    timeBlock(lastUsed, key.last_used_tenant ? ` · ${key.last_used_tenant}` : null),
    stale ? el('span', { class: 'stale-note' }, `Quiet for over ${STALE_HOURS} hours`) : null);
 }
 function createdCell(key) {
  const created = parseDate(key.created_at);
  return el('td', {},
    created ? timeBlock(created) : el('span', { class: 'muted' }, 'Unknown'),
    key.created_by ? el('span', { class: 'time__rel' }, `by ${key.created_by}`) : null);
 }
 function renderKeys() {
  dom.tbody.replaceChildren(...keys.map((key) => el('tr', { class: key.revoked_at ? 'is-revoked' : null },
    el('td', {}, el('code', {}, key.name)),
    statusCell(key),
    lastUsedCell(key),
    createdCell(key),
    el('td', { class: 'actions' }, key.revoked_at ? null : el('button', {
      type: 'button',
      class: 'btn btn--danger-outline',
      'aria-haspopup': 'dialog',
      'aria-label': `Revoke ${key.name}`,
      dataset: { keyId: String(key.id) },
    }, 'Revoke')))));
  dom.empty.hidden = keys.length > 0;
 }
 async function loadKeys() {
  try {
    ({ keys } = await api.listKeys());
    dom.errorBanner.hidden = true;
    renderKeys();
  } catch (err) {
    showError(`Couldn't load the keys: ${err.message}`);
  }
 }
 // ---------- Creating a key ----------
 // Keep aria-invalid in step with :user-invalid (the browser doesn't sync them)
 function syncInvalid() {
  dom.name.setAttribute('aria-invalid', dom.name.matches(':user-invalid') ? 'true' : 'false');
 }
 dom.name.addEventListener('blur', syncInvalid);
 dom.name.addEventListener('invalid', syncInvalid);  // a submit attempt with a bad name
 dom.name.addEventListener('input', () => { if (dom.name.hasAttribute('aria-invalid')) syncInvalid(); });
 function showSecret(name, secret) {
  dom.resultName.textContent = name;
  dom.secret.textContent = secret;
  dom.copyBtn.textContent = 'Copy';
  dom.result.hidden = false;
  dom.resultTitle.focus();
 }
 function hideSecret() {
  dom.result.hidden = true;
  dom.secret.textContent = '';
 }
 // Only fires once the browser's own validation (required, pattern) has passed
 dom.form.addEventListener('submit', async (e) => {
  e.preventDefault();
  dom.createBtn.disabled = true;
  dom.createError.hidden = true;
  hideSecret();
  try {
    const { key, secret } = await api.createKey(dom.name.value.trim());
    dom.form.reset();
    dom.name.removeAttribute('aria-invalid');
    showSecret(key.name, secret);
    announce(`Key ${key.name} created. Copy it now: it won't be shown again.`);
    await loadKeys();
  } catch (err) {
    dom.createError.textContent = err.message;
    dom.createError.hidden = false;
  } finally {
    dom.createBtn.disabled = false;
  }
 });
 dom.copyBtn.addEventListener('click', async () => {
  try {
    await navigator.clipboard.writeText(dom.secret.textContent);
    dom.copyBtn.textContent = 'Copied';
    announce('Key copied to the clipboard.');
  } catch {
    // Clipboard access can be refused (permissions, non-secure context): select it for Ctrl+C instead
    getSelection().selectAllChildren(dom.secret);
    dom.copyBtn.textContent = 'Selected: press Ctrl+C';
    announce('Copy blocked by the browser. The key is selected: press Ctrl+C to copy it.');
  }
 });
 dom.doneBtn.addEventListener('click', () => {
  hideSecret();
  dom.name.focus();
 });
 // ---------- Revoking a key ----------
 dom.tbody.addEventListener('click', (e) => {
  const button = e.target.closest('button[data-key-id]');
  if (!button) return;
  pendingRevoke = keys.find((k) => String(k.id) === button.dataset.keyId) ?? null;
  if (!pendingRevoke) return;
  dom.revokeName.textContent = pendingRevoke.name;
  dom.dialog.returnValue = '';
  dom.dialog.showModal();
 });
 // returnValue is the clicked button's value; Esc leaves it empty, which cancels
 dom.dialog.addEventListener('close', async () => {
  const key = pendingRevoke;
  pendingRevoke = null;
  if (dom.dialog.returnValue !== 'revoke' || !key) return;
  try {
    await api.revokeKey(key.id);
    announce(`Key ${key.name} revoked.`);
    await loadKeys();
  } catch (err) {
    showError(`Couldn't revoke ${key.name}: ${err.message}`);
  }
  // Its Revoke button is gone, so focus would otherwise fall back to the page
  dom.keysTitle.focus();
 });
 // ---------- Start ----------
 async function main() {
  dom.backLink.href = `/${location.search}`;  // keeps ?mock=1
  let me;
  try {
    me = await api.getMe();
  } catch (err) {
    showError(`Couldn't check who's signed in: ${err.message}`);
    return;
  }
  showSignedInUser(me, dom);
  if (!me?.is_admin) {
    dom.notAdmin.hidden = false;
    return;
  }
  dom.content.hidden = false;
  await loadKeys();
 }
 main();
@@ -8,18 +8,41 @@ export class ApiError extends Error {
  }
 }
-async function request(path) {
+// The API's explanation from an error response: FastAPI's {"detail": "..."}, or for validation
 // errors {"detail": [{"msg": "..."}, ...]}
 async function errorDetail(res) {
  try {
    const { detail } = await res.json();
    if (typeof detail === 'string') return detail;
    if (Array.isArray(detail)) return detail.map((d) => d.msg).filter(Boolean).join('; ');
  } catch {
    // not JSON: fall back to the status code
  }
  return null;
 }
 async function request(path, { method = 'GET', body } = {}) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), CONFIG.requestTimeoutMs);
  const headers = { Accept: 'application/json' };
  if (method !== 'GET') {
    // Required by the API for changes: another site's page can't add it to a request here
    headers['X-Requested-By'] = 'backup-dashboard';
  }
  if (body !== undefined) headers['Content-Type'] = 'application/json';
  try {
    const res = await fetch(`${CONFIG.apiBaseUrl}${path}`, {
-      headers: { Accept: 'application/json' },
+      method,
-      credentials: 'same-origin', // ready for cookie/session auth behind nginx
+      headers,
      body: body === undefined ? undefined : JSON.stringify(body),
      credentials: 'same-origin', // the sign-in session cookie
      signal: controller.signal,
    });
    // 401 means the nginx/SSO session lapsed; a reload sends the user back through sign-in
    if (res.status === 401) throw new ApiError('Your session has expired. Reload the page to sign in again', 401);
-    if (!res.ok) throw new ApiError(`Server returned HTTP ${res.status}`, res.status);
+    if (!res.ok) {
      throw new ApiError((await errorDetail(res)) ?? `Server returned HTTP ${res.status}`, res.status);
    }
    return await res.json();
  } catch (err) {
    if (err.name === 'AbortError') throw new ApiError('Request timed out');
@@ -49,10 +72,24 @@ const httpApi = {
  getRun(id) {
    return request(`/runs/${encodeURIComponent(id)}`);
  },
-  /** GET /me → { email, name } of the Microsoft 365 user, both null without sign-in */
+  /** GET /me → { email, name, is_admin } of the Microsoft 365 user; email/name null without sign-in */
  getMe() {
    return request('/me');
  },
  // ----- Admin (403 for non-admins) -----
  /** GET /admin/keys → { keys: ApiKey[] } (active first) */
  listKeys() {
    return request('/admin/keys');
  },
  /** POST /admin/keys → { key: ApiKey, secret } — the secret is only ever returned here */
  createKey(name) {
    return request('/admin/keys', { method: 'POST', body: { name } });
  },
  /** POST /admin/keys/:id/revoke → { key: ApiKey } */
  revokeKey(id) {
    return request(`/admin/keys/${encodeURIComponent(id)}/revoke`, { method: 'POST' });
  },
 };
 // Mock is loaded lazily so it never ships in the production request path.
@@ -1,5 +1,7 @@
 import { CONFIG } from './config.js';
 import { getApi } from './api.js';
 import { el } from './dom.js';
 import { showSignedInUser } from './signed-in.js';
 import {
  parseDate, formatDateTime, formatTime, formatRelative, formatDuration, formatBytes,
 } from './format.js';
@@ -59,6 +61,7 @@ const dom = {
  signedIn: $('#signed-in'),
  signedInEmail: $('#signed-in-email'),
  signOut: $('#sign-out'),
  adminLink: $('#admin-link'),
  lastUpdated: $('#last-updated'),
  errorBanner: $('#error-banner'),
  dialog: $('#detail-dialog'),
@@ -67,19 +70,6 @@ const dom = {
  detailBody: $('#detail-body'),
 };
 // Tiny element builder. All text goes through append() → text nodes, so API data can never inject HTML.
 function el(tag, props = {}, ...children) {
  const node = document.createElement(tag);
  for (const [k, v] of Object.entries(props)) {
    if (v == null || v === false) continue;
    if (k === 'class') node.className = v;
    else if (k === 'dataset') Object.assign(node.dataset, v);
    else node.setAttribute(k, v === true ? '' : v);
  }
  node.append(...children.flat().filter((c) => c != null && c !== false));
  return node;
 }
 // ---------- Rendering ----------
 function statusBadge(status, { asButton = false, opensDialog = false, dataset = null, title = null } = {}) {
  const { label, icon } = STATUS[status];
@@ -527,20 +517,9 @@ dom.search.addEventListener('input', () => {
 dom.refreshBtn.addEventListener('click', () => refresh().then(schedulePoll));
 // ---------- Signed-in user ----------
 async function showSignedInUser() {
  try {
    const me = await api.getMe();
    const who = me?.email || me?.name;
    if (!who) return;  // no Microsoft 365 sign-in in front of the dashboard (dev, mock)
    dom.signedInEmail.textContent = who;
    dom.signOut.href = CONFIG.signOutUrl;
    dom.signedIn.hidden = false;
  } catch (err) {
    console.error(err);  // not worth a banner: the jobs request will surface real problems
  }
 }
 // ---------- Boot ----------
-showSignedInUser();
+api.getMe().then(
  (me) => showSignedInUser(me, dom),
  (err) => console.error(err),  // not worth a banner: the jobs request will surface real problems
 );
 refresh().then(schedulePoll);
@@ -0,0 +1,12 @@
 // Tiny element builder. All text goes through append() → text nodes, so API data can never inject HTML.
 export function el(tag, props = {}, ...children) {
  const node = document.createElement(tag);
  for (const [k, v] of Object.entries(props)) {
    if (v == null || v === false) continue;
    if (k === 'class') node.className = v;
    else if (k === 'dataset') Object.assign(node.dataset, v);
    else node.setAttribute(k, v === true ? '' : v);
  }
  node.append(...children.flat().filter((c) => c != null && c !== false));
  return node;
 }
@@ -96,6 +96,18 @@ for (const job of JOBS) {
 }
 const delay = (ms) => new Promise((r) => setTimeout(r, ms));
 // Sample API keys for the admin page: one healthy, one gone quiet, one never used, one revoked
 const KEYS = [
  { id: 1, name: 'veeam-acme', created_at: iso(-40 * DAY), created_by: '[email protected]',
    last_used_at: iso(-12 * MIN), last_used_tenant: 'Acme Corp', revoked_at: null, revoked_by: null },
  { id: 2, name: 'mars-bluewater-fs01', created_at: iso(-20 * DAY), created_by: 'manage.py (backupdash)',
    last_used_at: iso(-3 * DAY), last_used_tenant: 'Bluewater Dental', revoked_at: null, revoked_by: null },
  { id: 3, name: 'wsb-northfield-dc01', created_at: iso(-2 * HR), created_by: '[email protected]',
    last_used_at: null, last_used_tenant: null, revoked_at: null, revoked_by: null },
  { id: 4, name: 'veeam-old-server', created_at: iso(-90 * DAY), created_by: 'manage.py (backupdash)',
    last_used_at: iso(-31 * DAY), last_used_tenant: 'Acme Corp', revoked_at: iso(-30 * DAY), revoked_by: '[email protected]' },
 ];
 const summary = ({ details, every_h, last_status, duration_seconds, size_bytes, ...rest }) => rest;
 export const mockApi = {
@@ -127,6 +139,31 @@ export const mockApi = {
    throw new Error('Run not found');
  },
  async getMe() {
-    return { email: null, name: null };  // no sign-in in mock mode
+    // No sign-in in mock mode, but show the admin pages so they can be tried out
    return { email: null, name: null, is_admin: true };
  },
  async listKeys() {
    await delay(200);
    return { keys: [...KEYS].sort((a, b) => (!!a.revoked_at - !!b.revoked_at) || a.name.localeCompare(b.name)) };
  },
  async createKey(name) {
    await delay(300);
    if (KEYS.some((k) => k.name === name)) {
      throw new Error(`A key named '${name}' already exists (revoked keys keep their names)`);
    }
    const key = { id: KEYS.length + 1, name, created_at: new Date().toISOString(), created_by: '[email protected]',
                  last_used_at: null, last_used_tenant: null, revoked_at: null, revoked_by: null };
    KEYS.push(key);
    const random = crypto.getRandomValues(new Uint8Array(32));
    return { key, secret: `bdk_mock_${btoa(String.fromCharCode(...random)).replace(/[+/=]/g, '')}` };
  },
  async revokeKey(id) {
    await delay(200);
    const key = KEYS.find((k) => k.id === id);
    if (!key) throw new Error('Key not found');
    key.revoked_at ??= new Date().toISOString();
    key.revoked_by ??= '[email protected]';
    return { key };
  },
 };
@@ -0,0 +1,18 @@
 import { CONFIG } from './config.js';
 /**
 * Fills in the top bar's "signed in as … / Sign out" from /api/v1/me, and shows the Admin link
 * to admins. Pass the elements that exist on the page; missing ones are skipped.
 */
 export function showSignedInUser(me, { signedIn, signedInEmail, signOut, adminLink } = {}) {
  const who = me?.email || me?.name;
  if (who && signedIn) {  // nothing to show without Microsoft 365 sign-in (dev, mock)
    signedInEmail.textContent = who;
    signOut.href = CONFIG.signOutUrl;
    signedIn.hidden = false;
  }
  if (me?.is_admin && adminLink) {
    adminLink.href = `/admin.html${location.search}`;  // keeps ?mock=1
    adminLink.hidden = false;
  }
 }