Record approved expiring exception for exact shared signing key

Preserve the HIGH finding and auditable approval; fail closed on expiry, file or finding changes, and keep all other security gates enforced.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

.circleci/config.yml

@@ -1,32 +0,0 @@
-# Golang CircleCI 2.0 configuration file
-#
-# Check https://circleci.com/docs/2.0/language-go/ for more details
-version: 2
-jobs:
-  machinery:
-    docker:
-      - image: kerberos/base:91ab4d4
-    working_directory: /go/src/github.com/{{ORG_NAME}}/{{REPO_NAME}}
-    steps:
-      - checkout
-      - run: apt-get update && apt-get install -y --no-install-recommends libavcodec-dev libavformat-dev libswscale-dev libjpeg62-turbo-dev
-      - run: cd machinery && go mod download
-      - run: cd machinery && go test -v ./...
-      - run: cd machinery && go vet
-
-  ui:
-    docker:
-      - image: cimg/python:3.9.13-node
-    steps:
-      - checkout
-      - run: node --version
-      - run: cd ui && yarn
-      - run: cd ui && yarn test --passWithNoTests
-      - run: cd ui && yarn build
-
-workflows:
-  version: 2
-  build:
-    jobs:
-      - machinery
-      - ui

.devcontainer/Dockerfile

@@ -1,2 +1,26 @@
-FROM kerberos/devcontainer:b2bc659
-LABEL AUTHOR=Kerberos.io
+FROM mcr.microsoft.com/devcontainers/go:1.25-trixie
+
+# Install node environment
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    nodejs \
+    npm \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install ffmpeg
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    ffmpeg \
+    libavcodec-extra \
+    libavutil-dev \
+    libavformat-dev \
+    libavfilter-dev \
+    libavdevice-dev \
+    libswscale-dev \
+    libswresample-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+USER vscode
+
+# Install go swagger
+RUN go install github.com/swaggo/swag/cmd/swag@latest

.devcontainer/devcontainer.json

@@ -1,33 +1,24 @@
-// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
-// https://github.com/microsoft/vscode-dev-containers/tree/v0.245.2/containers/docker-existing-dockerfile
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/python
 {
-	"name": "A Dockerfile containing FFmpeg, OpenCV, Go and Yarn",
-	// Sets the run context to one level up instead of the .devcontainer folder.
-	"context": "..",
-	// Update the 'dockerFile' property if you aren't using the standard 'Dockerfile' filename.
-	"dockerFile": "./Dockerfile",
-	// Use 'forwardPorts' to make a list of ports inside the container available locally.
-	"forwardPorts": [
-		3000,
-		80
+	"name": "go:1.24-trixie",
+	"runArgs": [
+		"--name=agent",
+		"--network=host"
 	],
-	// Uncomment the next line to run commands after the container is created - for example installing curl.
-	"postCreateCommand": "cd ui && yarn install && yarn build && cd ../machinery && go mod download",
-	"features": {
-		"ghcr.io/devcontainers-contrib/features/ansible:1": {}
-	},
+	"dockerFile": "Dockerfile",
 	"customizations": {
 		"vscode": {
 			"extensions": [
-				"ms-kubernetes-tools.vscode-kubernetes-tools",
-				"GitHub.copilot"
+				"GitHub.copilot",
+				"ms-azuretools.vscode-docker",
+				"mongodb.mongodb-vscode"
 			]
 		}
 	},
-	// Uncomment when using a ptrace-based debugger like C++, Go, and Rust
-	// "runArgs": [ "--cap-add=SYS_PTRACE", "--security-opt", "seccomp=unconfined" ],
-	// Uncomment to use the Docker CLI from inside the container. See https://aka.ms/vscode-remote/samples/docker-from-docker.
-	// "mounts": [ "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind" ],
-	// Uncomment to connect as a non-root user if you've added one. See https://aka.ms/vscode-remote/containers/non-root.
-	// "remoteUser": "vscode"
+	"forwardPorts": [
+		3000,
+		8082
+	],
+	"postCreateCommand": "cd ui && yarn install && yarn build && cd ../machinery && go mod download && bash ./verify-moq-devcontainer.sh"
 }

.dockerignore

@@ -0,0 +1,42 @@
+# Only application sources are needed by the production build.
+**
+!Dockerfile
+!machinery/
+!machinery/**
+!ui/
+!ui/**
+!deployments/
+deployments/*
+!deployments/docker/
+deployments/docker/*
+!deployments/docker/assemble-rootfs.sh
+
+**/.git
+**/.env
+**/.env.*
+**/.git-credentials
+**/.netrc
+**/.npmrc
+**/.yarnrc.yml
+**/.aws
+**/.ssh
+**/.kube
+**/node_modules
+**/.DS_Store
+**/*.test
+**/*.pprof
+**/coverage.out
+machinery/main
+machinery/vendor
+machinery/go.work
+machinery/go.work.sum
+machinery/www
+machinery/data/**
+!machinery/data/config/
+!machinery/data/config/config.json
+!machinery/data/config/user.json
+!machinery/data/test-480p.mp4
+ui/build
+ui/coverage
+ui/.npmrc
+ui/.yarnrc

.github/scripts/image-evidence.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+"""Validate BuildKit provenance and retain resolved base-image materials."""
+
+import json
+from pathlib import Path
+import re
+import sys
+
+
+def materials(value):
+    if isinstance(value, dict):
+        if "uri" in value and value["uri"].startswith(("pkg:docker/", "docker-image://")):
+            digest = value.get("digest", {}).get("sha256", "")
+            if not re.fullmatch(r"[a-f0-9]{64}", digest):
+                raise ValueError(f"Missing base-image digest: {value['uri']}")
+            yield value
+        for child in value.values():
+            yield from materials(child)
+    elif isinstance(value, list):
+        for child in value:
+            yield from materials(child)
+
+
+if __name__ == "__main__":
+    directory = Path(sys.argv[1])
+    provenance = json.loads((directory / "provenance.json").read_text())
+    bases = list(materials(provenance))
+    if not bases:
+        raise SystemExit("Missing provenance/base-image materials")
+    (directory / "base-image-digests.json").write_text(json.dumps(bases, indent=2) + "\n")

.github/scripts/image-policy.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""Fail-closed source/application and image scans with redacted evidence."""
+
+import argparse
+from datetime import datetime, timezone
+import hashlib
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+
+
+def secret_identity(target, finding):
+    return (target, finding.get("RuleID"), finding.get("Category"),
+            finding.get("Severity"), finding.get("StartLine"), finding.get("EndLine"))
+
+
+def approve_shared_key(report, source_root, policy, now=None):
+    """Bind the one reviewed exception to an unchanged file and exact finding."""
+    now = now or datetime.now(timezone.utc)
+    records = policy.get("exceptions")
+    if not isinstance(records, list) or len(records) != 1:
+        raise ValueError("Exactly one shared-key exception record is required")
+    record = records[0]
+    if not isinstance(record, dict) or record.get("id") != "shared-recording-signing-key":
+        raise ValueError("Unexpected scan exception")
+    if record.get("status") != "approved" or not all(
+        isinstance(record.get(key), str) and record[key].strip()
+        for key in ("owner", "approved_by", "reason", "approval_url", "expires")
+    ):
+        raise ValueError("Shared-key exception lacks approval/owner/reason/evidence/expiry")
+    if record["approval_url"] != "https://github.com/kerberos-io/agent/pull/350":
+        raise ValueError("Shared-key exception must reference its reviewed PR record")
+    expires = datetime.fromisoformat(record["expires"].replace("Z", "+00:00"))
+    if expires.tzinfo is None or expires <= now:
+        raise ValueError("Shared-key exception expired or lacks timezone")
+    if (record.get("target") != "machinery/src/config/main.go"
+            or record.get("rule_id") != "private-key"
+            or record.get("category") != "AsymmetricPrivateKey"
+            or record.get("severity") != "HIGH"
+            or type(record.get("start_line")) is not int
+            or record["start_line"] < 1
+            or record.get("end_line") != record["start_line"]):
+        raise ValueError("Shared-key exception has an unexpected finding scope")
+    root = Path(source_root).resolve()
+    path = root / record["target"]
+    if path.resolve() != path or hashlib.sha256(path.read_bytes()).hexdigest() != record.get("file_sha256"):
+        raise ValueError("Shared-key source file changed or is a symlink; renewed review required")
+    expected = (record["target"], record["rule_id"], record["category"],
+                record["severity"], record["start_line"], record["end_line"])
+    matches = [
+        finding for result in report["Results"]
+        for finding in result.get("Secrets", [])
+        if secret_identity(result.get("Target"), finding) == expected
+    ]
+    if len(matches) != 1:
+        raise ValueError("Shared-key exception must match exactly one existing source finding")
+    return [dict(record)]
+
+
+def check_report(report, image=False, source=False, approved_exceptions=()):
+    if report.get("SchemaVersion") != 2 or not isinstance(report.get("Results"), list):
+        raise ValueError("Missing or unsupported Trivy report")
+    failures = []
+    approved_secrets = {
+        (record["target"], record["rule_id"], record["category"], record["severity"],
+         record["start_line"], record["end_line"])
+        for record in approved_exceptions
+    } if source and not image else set()
+    for result in report["Results"]:
+        if result.get("Errors"):
+            failures.append(f"Scan errors in {result.get('Target')}: {result['Errors']}")
+        if result.get("MisconfSummary", {}).get("Exceptions", 0):
+            failures.append(f"Unapproved misconfiguration exceptions in {result.get('Target')}")
+        for kind in ("Vulnerabilities", "Secrets", "Misconfigurations"):
+            for finding in result.get(kind, []):
+                if kind == "Misconfigurations" and finding.get("Status") == "PASS":
+                    continue
+                if kind == "Misconfigurations" and finding.get("Status") != "FAIL":
+                    failures.append(f"Unexpected/suppressed misconfiguration status: {finding.get('Status')}")
+                severity = finding.get("Severity", "UNKNOWN")
+                if kind == "Secrets" and secret_identity(result.get("Target"), finding) in approved_secrets:
+                    continue
+                if severity not in ("LOW", "MEDIUM"):
+                    failures.append(f"{result.get('Target')}: {kind}: "
+                                    f"{finding.get('VulnerabilityID', finding.get('ID', finding.get('RuleID')))} "
+                                    f"{severity}")
+    if image:
+        # A scratch image without package metadata must not yield a false clean OS scan.
+        if not report.get("Metadata", {}).get("OS", {}).get("Family"):
+            failures.append("No OS detected: preserve runtime OS/package metadata")
+        if not any(r.get("Class") == "os-pkgs" and r.get("Packages")
+                   for r in report["Results"]):
+            failures.append("No OS package inventory detected")
+        if not any(r.get("Type") == "gobinary" and r.get("Packages")
+                   for r in report["Results"]):
+            failures.append("No Go application package inventory detected")
+    if source and not any(
+        r.get("Type") == "yarn" and r.get("Target", "").replace("\\", "/").endswith("ui/yarn.lock")
+        and r.get("Packages") for r in report["Results"]
+    ):
+        failures.append("Missing production UI yarn.lock package inventory")
+    return failures
+
+
+def redact_report(value):
+    """Keep findings actionable without persisting matches, excerpts or image env/history."""
+    if isinstance(value, list):
+        return [redact_report(item) for item in value]
+    if not isinstance(value, dict):
+        return value
+    result = {}
+    for key, child in value.items():
+        if key.lower() in {"imageconfig", "buildinfo"}:
+            continue
+        if key.lower() in {
+            "match", "code", "lines", "source", "sourcecode", "snippet", "context",
+            "content",
+        }:
+            result[key] = "[REDACTED]"
+        elif key == "Errors":
+            result[key] = ["[REDACTED scanner error]"] if child else []
+        elif key in ("Secrets", "Misconfigurations"):
+            allowed = {
+                "ID", "AVDID", "RuleID", "Type", "Category", "Title", "Severity",
+                "Status", "StartLine", "EndLine", "References",
+            }
+            result[key] = [
+                {field: finding[field] for field in allowed if field in finding}
+                | {"SourceExcerpt": "[REDACTED]"}
+                for finding in child
+            ]
+        else:
+            result[key] = redact_report(child)
+    return result
+
+
+def scan(target, output, platform=None):
+    output.mkdir(parents=True, exist_ok=True)
+    config = output / "scanner.yaml"
+    ignore = output / "empty.ignore"
+    secret_config = output / "secret.yaml"
+    config.write_text("{}\n")
+    secret_config.write_text("{}\n")
+    ignore.write_text("")
+    # Do not consume repository trivy.yaml/.trivyignore or TRIVY_* overrides.
+    env = {k: v for k, v in os.environ.items() if not k.startswith("TRIVY_")}
+    command = [
+        "trivy", "image" if platform else "fs", "--config", str(config),
+        "--cache-dir", ".ci-tools/trivy-cache",
+        "--ignorefile", str(ignore), "--secret-config", str(secret_config),
+        "--format", "json", "--exit-code", "0",
+        "--scanners", "vuln,secret,misconfig",
+        "--severity", "UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL", "--timeout", "20m",
+        "--list-all-pkgs", "--detection-priority", "comprehensive",
+    ]
+    if platform:
+        command += ["--platform", platform, "--pkg-types", "os,library",
+                    "--image-config-scanners", "secret,misconfig"]
+    else:
+        # Include development/build dependencies too: none are silently exempted.
+        # Trivy marks Dev packages using the adjacent package.json and yarn.lock.
+        command += ["--pkg-types", "library", "--include-dev-deps"]
+    command.append(target)
+    # Never write raw scanner output, even on scanner failure/interruption. stderr
+    # may contain source excerpts too; retain only a safe exit-status diagnostic.
+    completed = subprocess.run(command, env=env, stdout=subprocess.PIPE,
+                               stderr=subprocess.PIPE, text=True, check=False)
+    (output / "scanner.log").write_text(
+        f"Trivy exit status: {completed.returncode}\n"
+        "Raw scanner stdout/stderr omitted; scan.json is redacted before persistence.\n")
+    if completed.returncode:
+        raise ValueError(f"Trivy failed with exit status {completed.returncode}; raw diagnostics withheld")
+    try:
+        report = redact_report(json.loads(completed.stdout))
+    except ValueError:
+        raise ValueError("Invalid scanner JSON; raw output withheld") from None
+    (output / "scan.json").write_text(json.dumps(report, indent=2) + "\n")
+    approved = []
+    exception_failures = []
+    if not platform:
+        try:
+            policy = json.loads(Path(__file__).with_name("image-scan-exceptions.json").read_text())
+            (output / "exception-policy.json").write_text(json.dumps(policy, indent=2) + "\n")
+            approved = approve_shared_key(report, target, policy)
+        except (OSError, ValueError, TypeError, KeyError) as error:
+            exception_failures.append(f"Shared-key exception invalid: {error}")
+    (output / "exception-decisions.json").write_text(json.dumps({
+        "approved_exceptions": approved, "failures": exception_failures,
+    }, indent=2) + "\n")
+    failures = exception_failures + check_report(
+        report, image=bool(platform), source=not platform, approved_exceptions=approved)
+    if not platform:
+        inventory = [{
+            "target": result.get("Target"), "type": result.get("Type"),
+            "packages": [{"name": pkg.get("Name"), "version": pkg.get("Version"),
+                          "scope": "development" if pkg.get("Dev") else "production-or-unclassified"}
+                         for pkg in result.get("Packages", [])],
+        } for result in report["Results"] if result.get("Packages")]
+        (output / "application-inventory.json").write_text(json.dumps({
+            "policy": "All production and development/build dependencies are gated; "
+                      "only the reviewed, exact shared-key secret exception may apply.",
+            "inventories": inventory,
+        }, indent=2) + "\n")
+    converted = subprocess.run([
+        "trivy", "convert", "--cache-dir", ".ci-tools/trivy-cache",
+        "--format", "spdx-json", "--output", str(output / "sbom.spdx.json"),
+        str(output / "scan.json"),
+    ], env=env, stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False)
+    if converted.returncode:
+        raise ValueError(f"SPDX conversion failed with exit status {converted.returncode}")
+    sbom = json.loads((output / "sbom.spdx.json").read_text())
+    if not sbom.get("spdxVersion") or not sbom.get("packages"):
+        failures.append("Missing/empty SPDX SBOM")
+    return failures
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("target", help="Repository root, or final image reference with --platform")
+    parser.add_argument("output", type=Path, help="Directory for redacted reports and SPDX SBOM")
+    parser.add_argument("--platform", help="Image platform, e.g. linux/amd64; omit for source/UI scanning")
+    args = parser.parse_args()
+    args.output.mkdir(parents=True, exist_ok=True)
+    approved = []
+    try:
+        failures = scan(args.target, args.output, args.platform)
+        approved = json.loads((args.output / "exception-decisions.json").read_text())["approved_exceptions"]
+    except (OSError, ValueError, subprocess.CalledProcessError) as error:
+        failures = [f"Scanner/evidence error: {error}"]
+    (args.output / "policy.json").write_text(json.dumps({
+        "target": args.target, "platform": args.platform, "failures": failures,
+        "approved_exceptions": approved, "passed": not failures,
+    }, indent=2) + "\n")
+    for failure in failures:
+        print(failure, file=sys.stderr)
+    return int(bool(failures))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/scripts/image-release-policy.json

@@ -0,0 +1,13 @@
+{
+  "required_exceptions": [
+    {
+      "id": "remote-terminal-pty",
+      "status": "pending",
+      "reason": "The product retains functional remote terminal/PTY support, contrary to the no-shell baseline.",
+      "owner": null,
+      "expires": null,
+      "approved_by": null,
+      "approval_url": null
+    }
+  ]
+}

.github/scripts/image-release-policy.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Release-only policy gate. Approval records require a reviewed repository change."""
+
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+import sys
+
+
+def check_policy(policy, now=None):
+    now = now or datetime.now(timezone.utc)
+    records = policy.get("required_exceptions")
+    if not isinstance(records, list) or not records:
+        return ["Required exception records are missing"]
+    if {record.get("id") for record in records} != {"remote-terminal-pty"}:
+        return ["Required remote-terminal-pty exception record is missing or unexpected"]
+    failures = []
+    for record in records:
+        name = record["id"]
+        if record.get("status") != "approved":
+            failures.append(f"{name}: required exception is PENDING, not approved")
+            continue
+        if not all(isinstance(record.get(key), str) and record[key].strip()
+                   for key in ("owner", "approved_by", "reason", "approval_url", "expires")):
+            failures.append(f"{name}: missing owner/approver/reason/approval evidence/expiry")
+            continue
+        if not record["approval_url"].startswith("https://github.com/kerberos-io/agent/"):
+            failures.append(f"{name}: approval must reference this repository's reviewed record")
+        try:
+            expires = datetime.fromisoformat(record["expires"].replace("Z", "+00:00"))
+            if expires.tzinfo is None or expires <= now:
+                failures.append(f"{name}: approval expired or lacks timezone")
+        except ValueError:
+            failures.append(f"{name}: invalid approval expiry")
+    return failures
+
+
+if __name__ == "__main__":
+    try:
+        failures = check_policy(json.loads(Path(sys.argv[1]).read_text()))
+    except (OSError, ValueError, TypeError, KeyError) as error:
+        failures = [f"Invalid release policy: {error}"]
+    for failure in failures:
+        print(failure, file=sys.stderr)
+    sys.exit(bool(failures))

.github/scripts/image-scan-exceptions.json

@@ -0,0 +1,20 @@
+{
+  "exceptions": [
+    {
+      "id": "shared-recording-signing-key",
+      "status": "approved",
+      "owner": "@cedricve",
+      "approved_by": "@cedricve",
+      "approval_url": "https://github.com/kerberos-io/agent/pull/350",
+      "expires": "2026-12-05T23:59:59Z",
+      "reason": "User approved temporary retention of the existing shared recording-signing key to preserve recording verification trust and startup behavior. Anyone possessing this shared private key can forge signatures under that identity.",
+      "target": "machinery/src/config/main.go",
+      "file_sha256": "e28a0bf6ae892559709e8ec534cfc7b7cb55180e33415461d966c1afe53ca25b",
+      "rule_id": "private-key",
+      "category": "AsymmetricPrivateKey",
+      "severity": "HIGH",
+      "start_line": 710,
+      "end_line": 710
+    }
+  ]
+}

.github/scripts/install-trivy.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# Public OCI index pins the platform-specific executable without GitHub API access.
+version=0.76.1
+image=ghcr.io/aquasecurity/trivy:0.76.1@sha256:790fd66d1697395d8693d1acaa1ea702406a20f109b6fc7bac8db623eca6c06c
+evidence_dir="${1:-evidence/scanner-install}"
+mkdir -p "$evidence_dir" .ci-tools
+stage=host-platform
+platform=
+cid=
+finish() {
+  result=$?
+  trap - EXIT
+  if [[ -n "$cid" ]]; then
+    docker rm -f "$cid" >/dev/null 2>&1 || true
+  fi
+  rm -f .ci-tools/trivy.new
+  python3 - "$evidence_dir/install.json" "$result" "$stage" "$image" "$platform" "$version" <<'PY'
+import hashlib
+import json
+from pathlib import Path
+import sys
+path, code, stage, image, platform, version = sys.argv[1:]
+record = {
+    "status": "installed" if code == "0" else "failed",
+    "exit_code": int(code), "stage": stage, "image": image, "platform": platform,
+    "binary_source": "/usr/local/bin/trivy", "expected_version": version,
+}
+if code == "0":
+    record["binary_sha256"] = hashlib.sha256(Path(".ci-tools/trivy").read_bytes()).hexdigest()
+Path(path).write_text(json.dumps(record, indent=2) + "\n")
+PY
+  exit "$result"
+}
+trap finish EXIT
+case "$(uname -m)" in
+  x86_64) platform=linux/amd64 ;;
+  aarch64|arm64) platform=linux/arm64 ;;
+  *) echo "Unsupported scanner host architecture" >&2; exit 1 ;;
+esac
+stage=pull
+docker pull --platform "$platform" "$image"
+stage=create
+cid=$(docker create --platform "$platform" "$image")
+stage=extract
+docker cp "$cid:/usr/local/bin/trivy" .ci-tools/trivy.new
+chmod 0755 .ci-tools/trivy.new
+stage=verify-version
+.ci-tools/trivy.new --version | grep -Fx "Version: $version"
+mv .ci-tools/trivy.new .ci-tools/trivy
+stage=publish-path
+if [[ -n "${GITHUB_PATH:-}" ]]; then
+  echo "$PWD/.ci-tools" >> "$GITHUB_PATH"
+fi
+stage=complete

.github/scripts/test-image-policy.py

@@ -0,0 +1,288 @@
+#!/usr/bin/env python3
+"""Focused release guard tests; no registry, signing, or scanner network access."""
+
+from datetime import datetime, timezone
+import copy
+import hashlib
+import importlib.util
+import json
+from pathlib import Path
+import unittest
+from unittest.mock import patch
+import subprocess
+import tempfile
+
+
+ROOT = Path(__file__).parent
+
+
+def load(name):
+    spec = importlib.util.spec_from_file_location(name, ROOT / f"{name}.py")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+scanner = load("image-policy")
+release = load("image-release-policy")
+evidence = load("image-evidence")
+
+
+class ScanPolicyTests(unittest.TestCase):
+    def report(self, severity=None, kind="Vulnerabilities"):
+        result = {"Class": "os-pkgs", "Packages": [{"Name": "libc6"}]}
+        if severity:
+            result[kind] = [{"Severity": severity, "Status": "FAIL", "ID": "fixture"}]
+        return {"SchemaVersion": 2, "Metadata": {"OS": {"Family": "debian"}},
+                "Results": [result, {"Class": "lang-pkgs", "Type": "gobinary",
+                                     "Packages": [{"Name": "stdlib"}]}]}
+
+    def test_low_and_medium_are_not_blocking(self):
+        for severity in ("LOW", "MEDIUM"):
+            self.assertEqual(scanner.check_report(self.report(severity), image=True), [])
+
+    def test_high_critical_unknown_and_unrecognized_block(self):
+        for kind in ("Vulnerabilities", "Secrets", "Misconfigurations"):
+            for severity in ("HIGH", "CRITICAL", "UNKNOWN", "invalid"):
+                with self.subTest(kind=kind, severity=severity):
+                    self.assertTrue(scanner.check_report(self.report(severity, kind), image=True))
+
+    def test_missing_inventory_blocks_false_clean_scratch_scan(self):
+        report = self.report()
+        report["Metadata"] = {}
+        report["Results"] = []
+        self.assertEqual(len(scanner.check_report(report, image=True)), 3)
+
+    def test_empty_os_inventory_blocks(self):
+        report = self.report()
+        report["Results"][0]["Packages"] = []
+        self.assertTrue(scanner.check_report(report, image=True))
+
+    def test_report_errors_and_suppression_summary_block(self):
+        report = self.report()
+        report["Results"][0]["Errors"] = ["fixture scanner error"]
+        report["Results"][0]["MisconfSummary"] = {"Exceptions": 1}
+        self.assertEqual(len(scanner.check_report(report)), 2)
+
+    def test_missing_or_unsupported_report_blocks(self):
+        for report in ({}, {"SchemaVersion": 1, "Results": []}):
+            with self.assertRaises(ValueError):
+                scanner.check_report(report)
+
+    def test_suppressed_misconfiguration_blocks(self):
+        report = self.report("LOW", "Misconfigurations")
+        report["Results"][0]["Misconfigurations"][0]["Status"] = "EXCEPTION"
+        self.assertTrue(scanner.check_report(report))
+
+    def test_scanner_errors_are_not_ignored(self):
+        directory = unittest.mock.MagicMock()
+        with patch.object(scanner.subprocess, "run",
+                          side_effect=subprocess.CalledProcessError(1, ["trivy"])):
+            with self.assertRaises(subprocess.CalledProcessError):
+                scanner.scan("fixture", directory, "linux/amd64")
+
+    def test_source_requires_ui_lockfile_inventory(self):
+        report = self.report()
+        self.assertTrue(scanner.check_report(report, source=True))
+        report["Results"].append({"Type": "yarn", "Target": "ui/yarn.lock",
+                                   "Packages": [{"Name": "react", "Version": "17.0.2"}]})
+        self.assertEqual(scanner.check_report(report, source=True), [])
+        report["Results"][-1]["Vulnerabilities"] = [{"Severity": "HIGH", "VulnerabilityID": "fixture"}]
+        self.assertTrue(scanner.check_report(report, source=True))
+
+    def test_secret_and_source_excerpts_are_removed_without_waiving_findings(self):
+        marker = "sensitive-fixture-text-not-a-real-credential"
+        report = self.report("HIGH", "Secrets")
+        report["Metadata"]["ImageConfig"] = {"config": {"Env": [marker]}}
+        report["Metadata"]["BuildInfo"] = {"attrs": {"secret": marker}}
+        report["Results"][0]["Secrets"][0].update(
+            Match=marker, Code={"Lines": [{"Content": marker}]}, Message=marker,
+            UnexpectedFutureExcerptField=marker, RuleID="private-key-fixture")
+        report["Results"][0]["Misconfigurations"] = [{
+            "ID": "fixture", "Severity": "HIGH", "Status": "FAIL",
+            "Message": marker, "CauseMetadata": {"Code": {"Lines": [{"Content": marker}]}}
+        }]
+        report["Results"][0]["Errors"] = [marker]
+        redacted = scanner.redact_report(report)
+        self.assertNotIn(marker, json.dumps(redacted))
+        self.assertNotIn("ImageConfig", redacted["Metadata"])
+        self.assertTrue(scanner.check_report(redacted, image=True))
+        self.assertEqual(redacted["Results"][0]["Secrets"][0]["RuleID"], "private-key-fixture")
+
+    def test_source_scan_captures_output_in_memory_and_generates_sbom(self):
+        report = self.report()
+        report["Results"].append({"Type": "yarn", "Target": "ui/yarn.lock",
+                                   "Packages": [{"Name": "fixture", "Version": "1.0", "Dev": True}]})
+        directory = unittest.mock.MagicMock()
+        directory.__truediv__.return_value.read_text.return_value = json.dumps({
+            "spdxVersion": "SPDX-2.3", "packages": [{"name": "fixture"}]})
+        completed = subprocess.CompletedProcess(["trivy"], 0, stdout=json.dumps(report), stderr="")
+        with patch.object(scanner.subprocess, "run", return_value=completed) as run, \
+                patch.object(scanner, "approve_shared_key", return_value=[]):
+            self.assertEqual(scanner.scan("fixture", directory), [])
+        command = run.call_args_list[0].args[0]
+        self.assertIn("--include-dev-deps", command)
+        self.assertIn("vuln,secret,misconfig", command)
+        self.assertNotIn("--output", command)
+        self.assertEqual(run.call_args_list[0].kwargs["stdout"], subprocess.PIPE)
+        self.assertEqual(run.call_args_list[1].args[0][1], "convert")
+
+    def test_raw_scanner_error_diagnostics_are_not_persisted(self):
+        directory = unittest.mock.MagicMock()
+        marker = "sensitive-fixture-text-not-a-real-credential"
+        completed = subprocess.CompletedProcess(["trivy"], 1, stdout=marker, stderr=marker)
+        with patch.object(scanner.subprocess, "run", return_value=completed):
+            with self.assertRaisesRegex(ValueError, "exit status 1"):
+                scanner.scan("fixture", directory)
+        self.assertNotIn(marker, str(directory.mock_calls))
+
+
+class SharedKeyExceptionTests(unittest.TestCase):
+    NOW = datetime(2026, 11, 5, tzinfo=timezone.utc)
+
+    def setUp(self):
+        self.directory = tempfile.TemporaryDirectory()
+        self.addCleanup(self.directory.cleanup)
+        self.root = Path(self.directory.name)
+        self.path = self.root / "machinery/src/config/main.go"
+        self.path.parent.mkdir(parents=True)
+        self.path.write_text("non-secret source fixture\n")
+        self.policy = json.loads((ROOT / "image-scan-exceptions.json").read_text())
+        self.record = self.policy["exceptions"][0]
+        self.record["file_sha256"] = hashlib.sha256(self.path.read_bytes()).hexdigest()
+        self.finding = {
+            "RuleID": self.record["rule_id"], "Category": self.record["category"],
+            "Severity": "HIGH", "StartLine": 710, "EndLine": 710,
+        }
+        self.report = {"SchemaVersion": 2, "Results": [
+            {"Target": self.record["target"], "Secrets": [self.finding]},
+            {"Target": "ui/yarn.lock", "Type": "yarn", "Packages": [{"Name": "react"}]},
+        ]}
+
+    def approved(self):
+        return scanner.approve_shared_key(self.report, self.root, self.policy, self.NOW)
+
+    def test_exact_key_is_approved_but_finding_is_preserved(self):
+        original = copy.deepcopy(self.report)
+        approved = self.approved()
+        self.assertTrue(scanner.check_report(self.report, source=True))
+        self.assertEqual(scanner.check_report(
+            self.report, source=True, approved_exceptions=approved), [])
+        self.assertEqual(self.report, original)
+        self.assertEqual(approved[0]["id"], "shared-recording-signing-key")
+
+    def test_other_secrets_and_vulnerabilities_still_block(self):
+        approved = self.approved()
+        result = self.report["Results"][0]
+        result["Secrets"].append(dict(self.finding, StartLine=711, EndLine=711))
+        result["Vulnerabilities"] = [{"VulnerabilityID": "fixture", "Severity": "CRITICAL"}]
+        self.assertEqual(len(scanner.check_report(
+            self.report, source=True, approved_exceptions=approved)), 2)
+
+    def test_exception_never_applies_to_image_or_non_source_scans(self):
+        approved = self.approved()
+        self.assertTrue(scanner.check_report(self.report, approved_exceptions=approved))
+        self.assertTrue(scanner.check_report(
+            self.report, image=True, source=True, approved_exceptions=approved))
+
+    def test_expiry_is_enforced_at_boundary(self):
+        expiry = datetime(2026, 12, 5, 23, 59, 59, tzinfo=timezone.utc)
+        with self.assertRaisesRegex(ValueError, "expired"):
+            scanner.approve_shared_key(self.report, self.root, self.policy, expiry)
+        self.record["expires"] = "2026-12-05"
+        with self.assertRaisesRegex(ValueError, "timezone"):
+            self.approved()
+
+    def test_incomplete_or_unapproved_metadata_blocks(self):
+        for field in ("owner", "approved_by", "reason", "approval_url", "expires", "status"):
+            with self.subTest(field=field):
+                original = self.record[field]
+                self.record[field] = ""
+                with self.assertRaises(ValueError):
+                    self.approved()
+                self.record[field] = original
+        self.record["approval_url"] = "https://example.com/unreviewed"
+        with self.assertRaises(ValueError):
+            self.approved()
+
+    def test_changed_source_or_symlink_requires_review(self):
+        self.path.write_text("changed source fixture\n")
+        with self.assertRaisesRegex(ValueError, "changed"):
+            self.approved()
+        target = self.root / "other.go"
+        self.path.rename(target)
+        self.path.symlink_to(target)
+        with self.assertRaisesRegex(ValueError, "symlink"):
+            self.approved()
+
+    def test_changed_finding_does_not_match(self):
+        for field, value in (("RuleID", "other"), ("Category", "other"),
+                             ("Severity", "CRITICAL"), ("StartLine", 711), ("EndLine", 711)):
+            with self.subTest(field=field):
+                original = self.finding[field]
+                self.finding[field] = value
+                with self.assertRaisesRegex(ValueError, "exactly one"):
+                    self.approved()
+                self.finding[field] = original
+
+    def test_duplicate_missing_or_broadened_records_block(self):
+        self.policy["exceptions"].append(dict(self.record))
+        with self.assertRaises(ValueError):
+            self.approved()
+        self.policy["exceptions"].pop()
+        self.report["Results"][0]["Secrets"].append(dict(self.finding))
+        with self.assertRaisesRegex(ValueError, "exactly one"):
+            self.approved()
+        self.report["Results"][0]["Secrets"] = []
+        with self.assertRaisesRegex(ValueError, "exactly one"):
+            self.approved()
+        self.record["target"] = "../other.go"
+        with self.assertRaisesRegex(ValueError, "scope"):
+            self.approved()
+
+    def test_checked_in_record_matches_unchanged_source(self):
+        report = copy.deepcopy(self.report)
+        policy = json.loads((ROOT / "image-scan-exceptions.json").read_text())
+        self.assertEqual(len(scanner.approve_shared_key(
+            report, ROOT.parent.parent, policy, self.NOW)), 1)
+
+
+class ReleasePolicyTests(unittest.TestCase):
+    NOW = datetime(2026, 11, 4, tzinfo=timezone.utc)
+
+    def test_checked_in_state_blocks_publication(self):
+        state = json.loads((ROOT / "image-release-policy.json").read_text())
+        self.assertTrue(release.check_policy(state, self.NOW))
+
+    def test_missing_records_block(self):
+        for state in ({}, {"required_exceptions": []},
+                      {"required_exceptions": [{"id": "unrelated"}]}):
+            self.assertTrue(release.check_policy(state, self.NOW))
+
+    def test_expired_or_incomplete_approval_blocks(self):
+        state = json.loads((ROOT / "image-release-policy.json").read_text())
+        record = state["required_exceptions"][0]
+        record["status"] = "approved"
+        self.assertTrue(release.check_policy(state, self.NOW))
+        record.update(owner="test-fixture", approved_by="test-fixture",
+                      approval_url="https://github.com/kerberos-io/agent/issues/1",
+                      expires="2020-01-01T00:00:00Z")
+        self.assertTrue(release.check_policy(state, self.NOW))
+        record["expires"] = "invalid"
+        self.assertTrue(release.check_policy(state, self.NOW))
+        record["expires"] = "2027-01-01"
+        self.assertTrue(release.check_policy(state, self.NOW))
+
+
+class ProvenanceTests(unittest.TestCase):
+    def test_base_digest_retained(self):
+        material = {"uri": "pkg:docker/debian@trixie", "digest": {"sha256": "a" * 64}}
+        self.assertEqual(list(evidence.materials({"SLSA": {"materials": [material]}})), [material])
+
+    def test_missing_digest_rejected(self):
+        with self.assertRaises(ValueError):
+            list(evidence.materials({"uri": "pkg:docker/debian@trixie"}))
+
+
+if __name__ == "__main__":
+    unittest.main()

.github/workflows/docker-dev.yml

@@ -1,58 +0,0 @@
-name: Docker development build
-
-on:
-  push:
-    branches: [ develop ]
-
-jobs:
-  build-amd64:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        architecture: [amd64]
-    steps:
-    - name: Login to DockerHub
-      uses: docker/login-action@v2
-      with:
-        username: ${{ secrets.DOCKERHUB_USERNAME }}
-        password: ${{ secrets.DOCKERHUB_TOKEN }}
-    - name: Checkout
-      uses: actions/checkout@v3
-    - name: Set up QEMU
-      uses: docker/setup-qemu-action@v2
-    - name: Set up Docker Buildx
-      uses: docker/setup-buildx-action@v2
-    - name: Available platforms
-      run: echo ${{ steps.buildx.outputs.platforms }}
-    - name: Run Buildx
-      run: docker buildx build --platform linux/${{matrix.architecture}} -t kerberos/agent-dev:arch-$(echo ${{matrix.architecture}} | tr / -)-$(echo $GITHUB_SHA | cut -c1-7) --push . 
-    - name: Create new and append to manifest
-      run: docker buildx imagetools create -t kerberos/agent-dev:$(echo $GITHUB_SHA | cut -c1-7) kerberos/agent-dev:arch-$(echo ${{matrix.architecture}} | tr / -)-$(echo $GITHUB_SHA | cut -c1-7)
-    - name: Create new and append to latest manifest
-      run: docker buildx imagetools create -t kerberos/agent-dev:latest kerberos/agent-dev:arch-$(echo ${{matrix.architecture}} | tr / -)-$(echo $GITHUB_SHA | cut -c1-7)
-  build-other:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        #architecture: [arm64, arm/v7, arm/v6]
-        architecture: [arm64, arm/v7]
-    steps:
-    - name: Login to DockerHub
-      uses: docker/login-action@v2
-      with:
-        username: ${{ secrets.DOCKERHUB_USERNAME }}
-        password: ${{ secrets.DOCKERHUB_TOKEN }}
-    - name: Checkout
-      uses: actions/checkout@v3
-    - name: Set up QEMU
-      uses: docker/setup-qemu-action@v2
-    - name: Set up Docker Buildx
-      uses: docker/setup-buildx-action@v2
-    - name: Available platforms
-      run: echo ${{ steps.buildx.outputs.platforms }}
-    - name: Run Buildx
-      run: docker buildx build --platform linux/${{matrix.architecture}} -t kerberos/agent-dev:arch-$(echo ${{matrix.architecture}} | tr / -)-$(echo $GITHUB_SHA | cut -c1-7) --push . 
-    - name: Create new and append to manifest
-      run: docker buildx imagetools create --append -t kerberos/agent-dev:$(echo $GITHUB_SHA | cut -c1-7) kerberos/agent-dev:arch-$(echo ${{matrix.architecture}} | tr / -)-$(echo $GITHUB_SHA | cut -c1-7)
-    - name: Create new and append to manifest latest
-      run: docker buildx imagetools create --append -t kerberos/agent-dev:latest kerberos/agent-dev:arch-$(echo ${{matrix.architecture}} | tr / -)-$(echo $GITHUB_SHA | cut -c1-7)

.github/workflows/docker-nightly.yml

@@ -1,54 +0,0 @@
-name: Docker nightly build
-
-on:
-  # Triggers the workflow every day at 9PM (CET).
-  schedule:
-    - cron: "0 22 * * *"
-
-jobs:
-  build-amd64:
-      runs-on: ubuntu-latest
-      strategy:
-        matrix:
-          architecture: [amd64]
-      steps:
-      - name: Login to DockerHub
-        uses: docker/login-action@v2
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-      - name: Checkout
-        uses: actions/checkout@v3
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v2
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v2
-      - name: Available platforms
-        run: echo ${{ steps.buildx.outputs.platforms }}
-      - name: Run Buildx
-        run: docker buildx build --platform linux/${{matrix.architecture}} -t kerberos/agent-nightly:arch-$(echo ${{matrix.architecture}} | tr / -)-$(echo $GITHUB_SHA | cut -c1-7) --push . 
-      - name: Create new and append to manifest
-        run: docker buildx imagetools create -t kerberos/agent-nightly:$(echo $GITHUB_SHA | cut -c1-7) kerberos/agent-nightly:arch-$(echo ${{matrix.architecture}} | tr / -)-$(echo $GITHUB_SHA | cut -c1-7)
-  build-other:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        architecture: [arm64, arm/v7, arm/v6]
-    steps:
-    - name: Login to DockerHub
-      uses: docker/login-action@v2
-      with:
-        username: ${{ secrets.DOCKERHUB_USERNAME }}
-        password: ${{ secrets.DOCKERHUB_TOKEN }}
-    - name: Checkout
-      uses: actions/checkout@v3
-    - name: Set up QEMU
-      uses: docker/setup-qemu-action@v2
-    - name: Set up Docker Buildx
-      uses: docker/setup-buildx-action@v2
-    - name: Available platforms
-      run: echo ${{ steps.buildx.outputs.platforms }}
-    - name: Run Buildx
-      run: docker buildx build --platform linux/${{matrix.architecture}} -t kerberos/agent-nightly:arch-$(echo ${{matrix.architecture}} | tr / -)-$(echo $GITHUB_SHA | cut -c1-7) --push . 
-    - name: Create new and append to manifest
-      run: docker buildx imagetools create --append -t kerberos/agent-nightly:$(echo $GITHUB_SHA | cut -c1-7) kerberos/agent-nightly:arch-$(echo ${{matrix.architecture}} | tr / -)-$(echo $GITHUB_SHA | cut -c1-7)

.github/workflows/docker.yml

@@ -1,114 +0,0 @@
-name: Docker master build
-
-on:
-  push:
-    branches: [ master ]
-
-env:
-  REPO: kerberos/agent
-  
-jobs:
-  build-amd64:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    strategy:
-      matrix:
-        architecture: [amd64]
-    steps:
-      - name: Login to DockerHub
-        uses: docker/login-action@v2
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-      - name: Checkout
-        uses: actions/checkout@v3
-      - uses: benjlevesque/short-sha@v2.1
-        id: short-sha
-        with:
-          length: 7
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v2
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v2
-      - name: Available platforms
-        run: echo ${{ steps.buildx.outputs.platforms }}
-      - name: Run Buildx
-        run: docker buildx build --platform linux/$(echo ${{matrix.architecture}} | tr - /) -t $REPO-arch:arch-${{matrix.architecture}}-${{steps.short-sha.outputs.sha}} --push . 
-      - name: Create new and append to manifest
-        run: docker buildx imagetools create -t $REPO:${{ steps.short-sha.outputs.sha }} $REPO-arch:arch-${{matrix.architecture}}-${{steps.short-sha.outputs.sha}}
-      - name: Create new and append to manifest latest
-        run: docker buildx imagetools create -t $REPO:latest $REPO-arch:arch-${{matrix.architecture}}-${{steps.short-sha.outputs.sha}}
-      - name: Run Buildx with output
-        run: docker buildx build --platform linux/$(echo ${{matrix.architecture}} | tr - /) -t $REPO-arch:arch-$(echo ${{matrix.architecture}} | tr / -)-${{steps.short-sha.outputs.sha}} --output type=tar,dest=output-${{matrix.architecture}}.tar . 
-      - name: Strip binary
-        run: mkdir -p output/ && tar -xf output-${{matrix.architecture}}.tar -C output && rm output-${{matrix.architecture}}.tar && cd output/ && tar -cf ../agent-${{matrix.architecture}}.tar -C home/agent . && rm -rf output
-      # We'll make a GitHub release and push the build (tar) as an artifact
-      - uses: rickstaa/action-create-tag@v1
-        with:
-          tag: ${{ steps.short-sha.outputs.sha }}
-          message: "Release ${{ steps.short-sha.outputs.sha }}"
-      - name: Create a release  
-        uses: ncipollo/release-action@v1
-        with:
-          latest: true
-          name: ${{ steps.short-sha.outputs.sha }}
-          tag: ${{ steps.short-sha.outputs.sha }}
-          artifacts: "agent-${{matrix.architecture}}.tar"
-      # Taken from GoReleaser's own release workflow.
-      # The available Snapcraft Action has some bugs described in the issue below.
-      # The mkdirs are a hack for https://github.com/goreleaser/goreleaser/issues/1715.
-      #- name: Setup Snapcraft
-      #  run: |
-      #    sudo apt-get update
-      #    sudo apt-get -yq --no-install-suggests --no-install-recommends install snapcraft
-      #    mkdir -p $HOME/.cache/snapcraft/download
-      #    mkdir -p $HOME/.cache/snapcraft/stage-packages
-      #- name: Use Snapcraft
-      #  run: tar -xf agent-${{matrix.architecture}}.tar && snapcraft 
-  build-other:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    needs: build-amd64
-    strategy:
-      matrix:
-        architecture: [arm64, arm-v7, arm-v6]
-        #architecture: [arm64, arm-v7]
-    steps:
-    - name: Login to DockerHub
-      uses: docker/login-action@v2
-      with:
-        username: ${{ secrets.DOCKERHUB_USERNAME }}
-        password: ${{ secrets.DOCKERHUB_TOKEN }}
-    - name: Checkout
-      uses: actions/checkout@v3
-    - uses: benjlevesque/short-sha@v2.1
-      id: short-sha
-      with:
-        length: 7
-    - name: Set up QEMU
-      uses: docker/setup-qemu-action@v2
-    - name: Set up Docker Buildx
-      uses: docker/setup-buildx-action@v2
-    - name: Available platforms
-      run: echo ${{ steps.buildx.outputs.platforms }}
-    - name: Run Buildx
-      run: docker buildx build --platform linux/$(echo ${{matrix.architecture}} | tr - /) -t $REPO-arch:arch-${{matrix.architecture}}-${{steps.short-sha.outputs.sha}} --push . 
-    - name: Create new and append to manifest
-      run: docker buildx imagetools create --append -t $REPO:${{ steps.short-sha.outputs.sha }} $REPO-arch:arch-${{matrix.architecture}}-${{steps.short-sha.outputs.sha}}
-    - name: Create new and append to manifest latest
-      run: docker buildx imagetools create --append -t $REPO:latest $REPO-arch:arch-${{matrix.architecture}}-${{steps.short-sha.outputs.sha}}
-    - name: Run Buildx with output
-      run: docker buildx build --platform linux/$(echo ${{matrix.architecture}} | tr - /) -t $REPO-arch:arch-$(echo ${{matrix.architecture}} | tr / -)-${{steps.short-sha.outputs.sha}} --output type=tar,dest=output-${{matrix.architecture}}.tar . 
-    - name: Strip binary
-      run: mkdir -p output/ && tar -xf output-${{matrix.architecture}}.tar -C output && rm output-${{matrix.architecture}}.tar && cd output/ && tar -cf ../agent-${{matrix.architecture}}.tar -C home/agent . && rm -rf output
-    - name: Create a release  
-      uses: ncipollo/release-action@v1
-      with:
-        latest: true
-        allowUpdates: true
-        name: ${{ steps.short-sha.outputs.sha }}
-        tag: ${{ steps.short-sha.outputs.sha }}
-        artifacts: "agent-${{matrix.architecture}}.tar"
-  

.github/workflows/go.yml

@@ -2,35 +2,40 @@ name: Go
 
 on:
   push:
-    branches: [ develop, master ]
+    branches: [develop, master]
   pull_request:
-    branches: [ develop, master ]
+    branches: [develop, master]
 
 jobs:
-
   build:
     name: Build
     runs-on: ubuntu-latest
-    container:
-      image: kerberos/base:70d69dc
-
-
-    strategy:
-      matrix:
-        go-version: [1.17, 1.18, 1.19]
 
     steps:
-    - name: Set up Go ${{ matrix.go-version }}
-      uses: actions/setup-go@v2
-      with:
-        go-version: ${{ matrix.go-version }}
-    - name: Check out code into the Go module directory
-      uses: actions/checkout@v3
-    - name: Get dependencies
-      run: cd machinery && go mod download
-    - name: Build
-      run: cd machinery && go build -v ./...
-    - name: Vet
-      run: cd machinery && go vet -v ./...
-    - name: Test
-      run: cd machinery && go test -v ./...
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.26.10"
+          check-latest: true
+          cache: true
+          cache-dependency-path: machinery/go.sum
+      - name: Install native dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            build-essential \
+            libavcodec-dev \
+            libavutil-dev \
+            libswresample-dev \
+            libswscale-dev \
+            pkg-config
+      - name: Get dependencies
+        run: cd machinery && go mod download && go mod verify
+      - name: Build
+        run: cd machinery && go build -mod=readonly -trimpath -buildvcs=false -v ./...
+      - name: Vet
+        run: cd machinery && go vet -v ./...
+      - name: Test
+        run: cd machinery && go test -v ./...

.github/workflows/image-release.yml

@@ -0,0 +1,324 @@
+name: Verified image publication
+on:
+  workflow_call:
+    inputs:
+      tag:
+        type: string
+        default: ""
+      source_ref:
+        type: string
+        required: true
+      nightly:
+        type: boolean
+        default: false
+      publish_latest:
+        type: boolean
+        default: false
+    secrets:
+      DOCKER_USERNAME:
+        required: true
+      DOCKER_PASSWORD:
+        required: true
+
+permissions:
+  contents: read
+
+# No parallel run can overwrite a customer tag while another run verifies it.
+concurrency:
+  group: image-publication-${{ inputs.nightly && 'nightly' || 'release' }}
+  cancel-in-progress: false
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  resolve:
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    outputs:
+      sha: ${{ steps.source.outputs.sha }}
+      tag: ${{ steps.source.outputs.tag }}
+      created: ${{ steps.source.outputs.created }}
+      matrix: ${{ steps.source.outputs.matrix }}
+      repository: ${{ steps.source.outputs.repository }}
+      staging_repository: ${{ steps.source.outputs.staging_repository }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - name: Validate requested tag
+        env:
+          TAG: ${{ inputs.tag }}
+          NIGHTLY: ${{ inputs.nightly }}
+        run: |
+          if [[ "$NIGHTLY" != true && ! "$TAG" =~ ^[a-zA-Z0-9_][a-zA-Z0-9_.-]{0,127}$ ]]; then
+            echo "Invalid Docker tag" >&2
+            exit 1
+          fi
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          ref: ${{ inputs.source_ref }}
+          path: source
+          persist-credentials: false
+      - name: Resolve once for every architecture
+        id: source
+        env:
+          TAG: ${{ inputs.tag }}
+          NIGHTLY: ${{ inputs.nightly }}
+        run: |
+          sha=$(git -C source rev-parse HEAD)
+          [[ "$sha" =~ ^[a-f0-9]{40}$ ]]
+          created=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+          repository=kerberos/agent
+          staging_repository=kerberos/agent-arch
+          matrix='{"include":[{"architecture":"amd64","runner":"ubuntu-24.04"},{"architecture":"arm64","runner":"ubuntu-24.04-arm"}]}'
+          if [[ "$NIGHTLY" == true ]]; then
+            TAG="${sha:0:7}"
+            repository=kerberos/agent-nightly
+            staging_repository="$repository"
+            # Keep arm/v6: the pinned Go trixie base currently lacks this platform.
+            # Its build must fail rather than publishing an incomplete nightly index.
+            matrix='{"include":[{"architecture":"amd64","runner":"ubuntu-24.04"},{"architecture":"arm64","runner":"ubuntu-24.04-arm"},{"architecture":"arm/v7","runner":"ubuntu-24.04"},{"architecture":"arm/v6","runner":"ubuntu-24.04"}]}'
+          fi
+          {
+            echo "sha=$sha"
+            echo "tag=$TAG"
+            echo "created=$created"
+            echo "repository=$repository"
+            echo "staging_repository=$staging_repository"
+            echo "matrix=$matrix"
+          } >> "$GITHUB_OUTPUT"
+          mkdir -p evidence
+          printf '%s\n' "$sha" > evidence/source-revision.txt
+          printf '%s\n' "$created" > evidence/created.txt
+          printf '%s\n' "$TAG" > evidence/version.txt
+          cp .github/scripts/image-release-policy.json evidence/runtime-policy.json
+      - name: Validate fail-closed policy helpers
+        run: python3 .github/scripts/test-image-policy.py
+      - name: Keep existing GitHub release unpublished until gates pass
+        if: ${{ !inputs.nightly }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.source.outputs.tag }}
+        run: |
+          # A release:created event may refer to an already public release.
+          # Return it to draft immediately; do not imply this run has verified it.
+          gh api --paginate "repos/$GITHUB_REPOSITORY/releases" --jq '.[]' | jq -s . > evidence/releases.json
+          release_id=$(jq -r --arg tag "$TAG" '.[] | select(.tag_name == $tag) | .id' evidence/releases.json)
+          if [[ -n "$release_id" ]]; then
+            gh api --method PATCH "repos/$GITHUB_REPOSITORY/releases/$release_id" -F draft=true > evidence/draft-release.json
+          fi
+      - name: Install pinned public OCI scanner
+        run: bash .github/scripts/install-trivy.sh
+      - name: Source/UI dependency vulnerability, secret and misconfiguration gate with SPDX SBOM
+        run: python3 .github/scripts/image-policy.py source evidence/source
+      - name: Retain source policy evidence
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: image-source-evidence
+          path: evidence/
+          retention-days: 90
+          if-no-files-found: error
+
+  build:
+    needs: resolve
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJSON(needs.resolve.outputs.matrix) }}
+    env:
+      ARCH: ${{ matrix.architecture }}
+      VERSION: ${{ needs.resolve.outputs.tag }}
+      REVISION: ${{ needs.resolve.outputs.sha }}
+      CREATED: ${{ needs.resolve.outputs.created }}
+      STAGING_REPOSITORY: ${{ needs.resolve.outputs.staging_repository }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          ref: ${{ needs.resolve.outputs.sha }}
+          path: source
+          persist-credentials: false
+      - uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3
+        if: ${{ startsWith(matrix.architecture, 'arm/') }}
+      - uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
+      - uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+      - name: Build immutable staging image with maximal provenance
+        id: build
+        run: |
+          mkdir -p evidence
+          arch="${ARCH//\//-}"
+          echo "arch=$arch" >> "$GITHUB_OUTPUT"
+          staging="$STAGING_REPOSITORY:ci-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT-$arch"
+          printf '%s\n' "$REVISION" > evidence/source-revision.txt
+          docker buildx build --platform "linux/$ARCH" --provenance=mode=max \
+            --build-arg "VERSION=$VERSION" --build-arg "REVISION=$REVISION" --build-arg "CREATED=$CREATED" \
+            --label "org.opencontainers.image.version=$VERSION" \
+            --label "org.opencontainers.image.revision=$REVISION" \
+            --label "org.opencontainers.image.created=$CREATED" \
+            --label "org.opencontainers.image.source=https://github.com/$GITHUB_REPOSITORY" \
+            --metadata-file evidence/build-metadata.json --tag "$staging" --push source
+          digest=$(jq -er '."containerimage.digest"' evidence/build-metadata.json)
+          [[ "$digest" =~ ^sha256:[a-f0-9]{64}$ ]]
+          image="$STAGING_REPOSITORY@$digest"
+          printf '%s\n' "$image" > evidence/image.txt
+          docker buildx imagetools inspect "$image" --format '{{json .Provenance}}' > evidence/provenance.json
+          python3 .github/scripts/image-evidence.py evidence
+      - name: Extract release payload and smoke test the exact staged image
+        run: |
+          image=$(cat evidence/image.txt)
+          docker pull --platform "linux/$ARCH" "$image"
+          cid=$(docker create --platform "linux/$ARCH" "$image")
+          trap 'docker rm -f "$cid" >/dev/null' EXIT
+          docker cp "$cid:/home/agent" output
+          # Run the existing smoke interface, including emulated nightly architectures.
+          DOCKER_DEFAULT_PLATFORM="linux/$ARCH" sh source/deployments/docker/test-image.sh "$image"
+          arch="${ARCH//\//-}"
+          tar -cf "agent-$arch.tar" -C output .
+          rm -rf output
+      - name: Retain build evidence even on failure
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: image-build-${{ steps.build.outputs.arch || strategy.job-index }}
+          path: evidence/
+          retention-days: 90
+          if-no-files-found: error
+      - name: Retain existing binary artifacts
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: agent-${{ steps.build.outputs.arch }}.tar
+          path: agent-*.tar
+          if-no-files-found: error
+
+  verify-publish:
+    needs: [resolve, build]
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+      id-token: write
+    env:
+      REPOSITORY: ${{ needs.resolve.outputs.repository }}
+      STAGING_REPOSITORY: ${{ needs.resolve.outputs.staging_repository }}
+      VERSION: ${{ needs.resolve.outputs.tag }}
+      REVISION: ${{ needs.resolve.outputs.sha }}
+      PUBLISH_LATEST: ${{ inputs.publish_latest }}
+      MATRIX: ${{ needs.resolve.outputs.matrix }}
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          path: artifacts
+      - uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
+      - uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+      - name: Install scanner
+        run: bash .github/scripts/install-trivy.sh
+      - uses: sigstore/cosign-installer@faadad0cce49287aee09b3a48701e75088a2c6ad # v4.0.0
+        with:
+          cosign-release: v3.1.4
+      - name: Assemble candidate index without publishing version/latest
+        run: |
+          mkdir -p evidence
+          images=()
+          while IFS= read -r arch; do
+            directory="artifacts/image-build-${arch//\//-}"
+            [[ "$(cat "$directory/source-revision.txt")" == "$REVISION" ]]
+            image=$(cat "$directory/image.txt")
+            [[ "$image" =~ ^${STAGING_REPOSITORY}@sha256:[a-f0-9]{64}$ ]]
+            images+=("$image")
+          done < <(jq -r '.include[].architecture' <<< "$MATRIX")
+          candidate="$REPOSITORY:ci-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
+          docker buildx imagetools create --tag "$candidate" "${images[@]}"
+          digest=$(docker buildx imagetools inspect "$candidate" --format '{{.Manifest.Digest}}')
+          [[ "$digest" =~ ^sha256:[a-f0-9]{64}$ ]]
+          image="$REPOSITORY@$digest"
+          printf '%s\n' "$image" > evidence/final-image.txt
+          printf '%s\n' "$REVISION" > evidence/source-revision.txt
+          docker buildx imagetools inspect "$image" --raw > evidence/index.json
+          docker buildx imagetools inspect "$image" --format '{{json .Provenance}}' > evidence/provenance.json
+          python3 .github/scripts/image-evidence.py evidence
+          # Every requested runnable platform must be present, with no silent omissions.
+          jq -r '.manifests[] | select(.platform.os == "linux") |
+            .platform | .architecture + (if .variant and .architecture == "arm" then "/" + .variant else "" end)' \
+            evidence/index.json | sort > evidence/actual-platforms.txt
+          jq -r '.include[].architecture' <<< "$MATRIX" | sort > evidence/expected-platforms.txt
+          diff -u evidence/expected-platforms.txt evidence/actual-platforms.txt
+      - name: Scan every final-index platform and enforce findings/errors
+        run: |
+          image=$(cat evidence/final-image.txt)
+          failed=0
+          while IFS= read -r arch; do
+            # Generation uses exit-code 0 only for findings; the helper explicitly
+            # blocks HIGH/CRITICAL/UNKNOWN and any scanner/inventory/SBOM error.
+            if ! python3 .github/scripts/image-policy.py "$image" "evidence/${arch//\//-}" --platform "linux/$arch"; then
+              failed=1
+            fi
+          done < <(jq -r '.include[].architecture' <<< "$MATRIX")
+          exit "$failed"
+      - name: Required release policy exception gate
+        run: |
+          # The product deliberately retains remote terminal/PTY support.
+          # No approval exists. Keep this release-only gate separate from scans;
+          # there is no dispatch input/environment variable that can waive it.
+          cp .github/scripts/image-release-policy.json evidence/runtime-policy.json
+          python3 .github/scripts/image-release-policy.py evidence/runtime-policy.json
+      - name: Sign and verify the FINAL multi-platform digest using GitHub OIDC
+        run: |
+          image=$(cat evidence/final-image.txt)
+          # Fulcio's SAN is job_workflow_ref for this local reusable workflow,
+          # not the caller's filename. Bind the exact repository and executing ref.
+          # For example: https://github.com/kerberos-io/agent/.github/workflows/image-release.yml@refs/heads/master
+          identity="https://github.com/$GITHUB_REPOSITORY/.github/workflows/image-release.yml@$GITHUB_REF"
+          printf '%s\n' "$identity" > evidence/signing-identity.txt
+          cosign sign --yes --bundle evidence/signature.sigstore.json "$image"
+          cosign verify --certificate-identity "$identity" \
+            --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+            "$image" > evidence/signature-verification.json
+      - name: Publish only the already verified and signed digest
+        run: |
+          image=$(cat evidence/final-image.txt)
+          while IFS= read -r arch; do
+            arch="${arch//\//-}"
+            staged=$(cat "artifacts/image-build-$arch/image.txt")
+            # Preserve the existing architecture tag names, after all gates.
+            docker buildx imagetools create --tag "$STAGING_REPOSITORY:arch-$arch-$VERSION" "$staged"
+          done < <(jq -r '.include[].architecture' <<< "$MATRIX")
+          docker buildx imagetools create --tag "$REPOSITORY:$VERSION" "$image"
+          [[ "$(docker buildx imagetools inspect "$REPOSITORY:$VERSION" --format '{{.Manifest.Digest}}')" == "${image##*@}" ]]
+          if [[ "$PUBLISH_LATEST" == true ]]; then
+            docker buildx imagetools create --tag "$REPOSITORY:latest" "$image"
+            [[ "$(docker buildx imagetools inspect "$REPOSITORY:latest" --format '{{.Manifest.Digest}}')" == "${image##*@}" ]]
+          fi
+      - name: Retain final reports/SBOM/provenance/signature even on failure
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: image-final-evidence
+          path: evidence/
+          retention-days: 90
+          if-no-files-found: error
+      - name: Attach binaries and all evidence, then publish GitHub release
+        if: ${{ !inputs.nightly }}
+        run: |
+          tar -czf image-security-evidence.tar.gz evidence artifacts/image-*
+          # Create a draft only if absent. API errors must not masquerade as absence.
+          gh api --paginate "repos/$GITHUB_REPOSITORY/releases" --jq '.[]' | jq -s . > releases.json
+          if ! jq -e --arg tag "$VERSION" '.[] | select(.tag_name == $tag)' releases.json >/dev/null; then
+            gh release create "$VERSION" --target "$REVISION" --title "$VERSION" --notes "" --draft
+          fi
+          gh release upload "$VERSION" artifacts/agent-*.tar/agent-*.tar image-security-evidence.tar.gz --clobber
+          gh release edit "$VERSION" --draft=false --latest --title "$VERSION"

.github/workflows/issue-userstory-create.yml

@@ -0,0 +1,51 @@
+name: Create User Story Issue
+on:
+  workflow_dispatch:
+    inputs:
+      issue_title:
+        description: 'Title for the issue'
+        required: true
+      issue_description:
+        description: 'Brief description of the feature'
+        required: true
+      complexity:
+        description: 'Complexity of the feature'
+        required: true
+        type: choice
+        options:
+          - 'Low'
+          - 'Medium'
+          - 'High'
+        default: 'Medium'
+      duration:
+        description: 'Estimated duration'
+        required: true
+        type: choice
+        options:
+          - '1 day'
+          - '3 days'
+          - '1 week'
+          - '2 weeks'
+          - '1 month'
+        default: '1 week'
+
+jobs:
+  create-issue:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - name: Create Issue with User Story
+        uses: cedricve/llm-create-issue-user-story@main
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          azure_openai_api_key: ${{ secrets.AZURE_OPENAI_API_KEY }}
+          azure_openai_endpoint: ${{ secrets.AZURE_OPENAI_ENDPOINT }}
+          azure_openai_version: ${{ secrets.AZURE_OPENAI_VERSION }}
+          openai_model: ${{ secrets.OPENAI_MODEL }}
+          issue_title: ${{ github.event.inputs.issue_title }}
+          issue_description: ${{ github.event.inputs.issue_description }}
+          complexity: ${{ github.event.inputs.complexity }}
+          duration: ${{ github.event.inputs.duration }}
+          labels: 'user-story,feature'
+          assignees: ${{ github.actor }}

.github/workflows/nightly-build.yml

@@ -0,0 +1,19 @@
+name: Nightly build
+on:
+  schedule:
+    - cron: "0 22 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  nightly:
+    permissions:
+      contents: read
+      id-token: write
+    uses: ./.github/workflows/image-release.yml
+    with:
+      source_ref: master
+      nightly: true
+    secrets: inherit

.github/workflows/pr-build.yml

@@ -0,0 +1,119 @@
+name: Build pull request
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  build:
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - architecture: amd64
+            runner: ubuntu-24.04
+          - architecture: arm64
+            runner: ubuntu-24.04-arm
+    env:
+      ARCH: ${{ matrix.architecture }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - name: Initialize retained runtime/scanner state
+        run: |
+          mkdir -p evidence/scanner-install
+          printf '%s\n' '{"status":"not_started","reason":"waiting_for_native_build_and_smoke"}' \
+            > evidence/scanner-install/install.json
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          ref: ${{ github.sha }}
+          path: source
+          persist-credentials: false
+      - uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
+      - name: Validate fail-closed policy helpers
+        run: python3 .github/scripts/test-image-policy.py
+      - name: Build once, populating OCI metadata from CI
+        env:
+          BUILDX_METADATA_PROVENANCE: max
+        run: |
+          mkdir -p evidence/build
+          revision=$(git -C source rev-parse HEAD)
+          version="${revision:0:7}"
+          created=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+          printf '%s\n' "$revision" > evidence/build/source-revision.txt
+          # Classic Docker cannot load an attested index. Disable attestations
+          # only for this local export; BUILDX_METADATA_PROVENANCE=max retains
+          # full build provenance/materials separately, verified below.
+          docker buildx build --platform "linux/$ARCH" --provenance=false \
+            --build-arg "VERSION=$version" --build-arg "REVISION=$revision" --build-arg "CREATED=$created" \
+            --label "org.opencontainers.image.version=$version" \
+            --label "org.opencontainers.image.revision=$revision" \
+            --label "org.opencontainers.image.created=$created" \
+            --label "org.opencontainers.image.source=https://github.com/$GITHUB_REPOSITORY" \
+            --metadata-file evidence/build/build-metadata.json --tag "$ARCH" \
+            --output type=docker source
+          jq -e '."buildx.build.provenance" |
+            select(type == "object" and length > 0) |
+            select(.buildConfig | type == "object" and length > 0)' \
+            evidence/build/build-metadata.json > evidence/build/provenance.json
+          python3 .github/scripts/image-evidence.py evidence/build
+      - name: Extract release payload
+        run: |
+          cid=$(docker create "$ARCH")
+          trap 'docker rm -f "$cid" >/dev/null' EXIT
+          docker cp "$cid:/home/agent" "output-$ARCH"
+      - name: Test production image
+        id: smoke
+        run: sh source/deployments/docker/test-image.sh "$ARCH"
+      - name: Strip binary
+        run: tar -cf "agent-$ARCH.tar" -C "output-$ARCH" . && rm -rf "output-$ARCH"
+      - name: Install pinned public OCI scanner after runtime tests
+        run: bash .github/scripts/install-trivy.sh
+      - name: Source/UI dependency and final image gates with SPDX SBOMs
+        run: |
+          failed=0
+          if ! python3 .github/scripts/image-policy.py source evidence/source; then
+            failed=1
+          fi
+          if ! python3 .github/scripts/image-policy.py "$ARCH" "evidence/$ARCH" --platform "linux/$ARCH"; then
+            failed=1
+          fi
+          exit "$failed"
+      - name: Upload artifact only after secret and vulnerability gates pass
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: agent-${{ matrix.architecture }}.tar
+          path: agent-${{ matrix.architecture }}.tar
+          if-no-files-found: error
+      - name: Record runtime result independently of scanner availability
+        if: always()
+        env:
+          SMOKE_OUTCOME: ${{ steps.smoke.outcome }}
+        run: |
+          mkdir -p evidence
+          python3 - <<'PY'
+          import json
+          import os
+          from pathlib import Path
+          Path("evidence/runtime-smoke.json").write_text(json.dumps({
+              "architecture": os.environ["ARCH"],
+              "outcome": os.environ["SMOKE_OUTCOME"],
+              "workflow_revision": os.environ["GITHUB_SHA"],
+          }, indent=2) + "\n")
+          PY
+      - name: Retain reports on failure
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: image-pr-evidence-${{ matrix.architecture }}
+          path: evidence/
+          retention-days: 90
+          if-no-files-found: error

.github/workflows/pr-description.yaml

@@ -0,0 +1,17 @@
+name: Autofill PR description
+
+on: pull_request
+
+jobs:
+  openai-pr-description:
+    uses: uug-ai/workflows/.github/workflows/pr-description.yml@main
+    with:
+      pr_number: ${{ github.event.number }}
+      pull_request_url: ""
+      overwrite_description: true
+    secrets:
+      TOKEN: ${{ secrets.TOKEN }}
+      AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }}
+      OPENAI_MODEL: ${{ secrets.OPENAI_MODEL }}
+      AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }}
+      AZURE_OPENAI_VERSION: ${{ secrets.AZURE_OPENAI_VERSION }}

.github/workflows/react.yml

@@ -11,21 +11,22 @@ on:
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
 
     strategy:
       matrix:
-        node-version: [14.x, 16.x]
+        node-version: [22.x]
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v2
+      uses: actions/setup-node@v4
       with:
         node-version: ${{ matrix.node-version }}
+        cache: yarn
+        cache-dependency-path: ui/yarn.lock
     - name: Yarn install
-      run: cd ui && yarn
+      run: cd ui && yarn --frozen-lockfile
     - name: Yarn test
       run: cd ui && yarn test --passWithNoTests
     - name: Yarn build

.github/workflows/release-bump.yml

@@ -0,0 +1,36 @@
+name: Bump release
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: Which part of the version to bump
+        required: true
+        default: patch
+        type: choice
+        options: [major, minor, patch]
+
+permissions:
+  contents: read
+
+jobs:
+  bump-release:
+    permissions:
+      contents: write
+    # Verified revision supports reserving a tag with an unpublished draft.
+    uses: uug-ai/workflows/.github/workflows/release-bump.yml@f31d4260a833e82228ca0e9b9163231a970feeb8
+    with:
+      bump: ${{ inputs.bump }}
+      draft: true
+    secrets: inherit
+
+  release:
+    needs: bump-release
+    permissions:
+      contents: write
+      id-token: write
+    uses: ./.github/workflows/image-release.yml
+    with:
+      tag: ${{ needs.bump-release.outputs.tag }}
+      source_ref: ${{ format('refs/tags/{0}', needs.bump-release.outputs.tag) }}
+      publish_latest: true
+    secrets: inherit

.github/workflows/release-create.yml

@@ -0,0 +1,25 @@
+name: Create a new release
+on:
+  release:
+    types: [created]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Tag for the Docker image
+        required: true
+        default: test
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    permissions:
+      contents: write
+      id-token: write
+    uses: ./.github/workflows/image-release.yml
+    with:
+      tag: ${{ inputs.tag || github.event.release.tag_name }}
+      source_ref: ${{ github.event_name == 'release' && format('refs/tags/{0}', github.event.release.tag_name) || github.sha }}
+      publish_latest: ${{ github.event_name == 'workflow_dispatch' && inputs.tag == 'test' }}
+    secrets: inherit

.gitignore

@@ -1,6 +1,8 @@
 ui/node_modules
 ui/build
 ui/public/assets/env.js
+.DS_Store
+__debug*
 .idea
 machinery/www
 yarn.lock
@@ -10,5 +12,9 @@ machinery/data/recordings
 machinery/data/snapshots
 machinery/test*
 machinery/init-dev.sh
-machinery/.env
-deployments/docker/private-docker-compose.yaml
+machinery/.env.local
+machinery/vendor
+machinery/go.work
+machinery/go.work.sum
+deployments/docker/private-docker-compose.yaml
+video.mp4

.travis.yml

@@ -1,19 +0,0 @@
-language: go
-
-go:
-  - 1.12.x
-  - 1.13.x
-  - 1.14.x
-  - 1.15.x
-  - tip
-
-before_install:
-  - cd machinery
-  - go mod download
-
-script:
-  - go vet
-  - go test -race -coverprofile=coverage.txt -covermode=atomic
-
-after_success:
-  - bash <(curl -s https://codecov.io/bash)

.vscode/launch.json

@@ -0,0 +1,36 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Launch Golang",
+            "type": "go",
+            "request": "launch",
+            "mode": "auto",
+            "program": "${workspaceFolder}/machinery/main.go",
+            "args": [
+                "-action",
+                "run",
+                "-port",
+                "8082"
+            ],
+            "envFile": "${workspaceFolder}/machinery/.env.local",
+            "buildFlags": "--tags dynamic,moq",
+            "env": {
+                "GOWORK": "off"
+            },
+        },
+        {
+            "name": "Launch React",
+            "type": "node",
+            "request": "launch",
+            "cwd": "${workspaceFolder}/ui",
+            "runtimeExecutable": "yarn",
+            "runtimeArgs": [
+                "start"
+            ],
+        }
+    ]
+}

.vscode/tasks.json

@@ -0,0 +1,14 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "agent: moq verify",
+      "type": "shell",
+      "command": "bash ./verify-moq-devcontainer.sh",
+      "options": {
+        "cwd": "${workspaceFolder}/machinery"
+      },
+      "problemMatcher": []
+    }
+  ]
+}

Dockerfile

@@ -1,49 +1,63 @@
 
-FROM kerberos/base:dc12d68 AS build-machinery
-LABEL AUTHOR=Kerberos.io
+ARG GO_IMAGE=golang:1.26.10-trixie@sha256:a050dcceee6eb9bf110151662dfac7662f3bec40927c7dee48731e3d92083d42
+ARG RUNTIME_IMAGE=debian:trixie-slim@sha256:f6b08b09a05725f9431502d3b5714f5c4576e82c1a84fa1debe0c24a7e0c3ec4
+ARG VERSION=0.0.0
+FROM ${GO_IMAGE} AS build-machinery
+LABEL AUTHOR=uug.ai
+
+# Re-declare VERSION inside this stage so the value passed via
+# `--build-arg VERSION=...` (e.g. the release tag) is available below.
+# ARGs declared before the first FROM are not visible inside build stages.
+ARG VERSION
+ARG TARGETARCH
 
 ENV GOROOT=/usr/local/go
 ENV GOPATH=/go
 ENV PATH=$GOPATH/bin:$GOROOT/bin:/usr/local/lib:$PATH
-ENV GOSUMDB=off
+ENV GOTOOLCHAIN=local
+ENV CGO_ENABLED=1
 
 ##########################################
 # Installing some additional dependencies.
 
-RUN apt-get upgrade -y && apt-get update && apt-get install -y --no-install-recommends \
+RUN apt-get update && apt-get install -y --no-install-recommends \
 	git build-essential cmake pkg-config unzip libgtk2.0-dev \
-	curl ca-certificates libcurl4-openssl-dev libssl-dev libjpeg62-turbo-dev && \
+	curl ca-certificates libavcodec-dev libavutil-dev libcurl4-openssl-dev \
+	libssl-dev libjpeg62-turbo-dev libswscale-dev && \
 	rm -rf /var/lib/apt/lists/*
 
 ##############################################################################
-# Copy all the relevant source code in the Docker image, so we can build this.
+# Copy dependency metadata first so module downloads can be cached separately.
 
 RUN mkdir -p /go/src/github.com/kerberos-io/agent
-COPY machinery /go/src/github.com/kerberos-io/agent/machinery
+WORKDIR /go/src/github.com/kerberos-io/agent/machinery
+COPY machinery/go.mod machinery/go.sum ./
+RUN go version && go mod download && go mod verify
 
-##################################################################
-# Get the latest commit hash, so we know which version we're running
-COPY .git /go/src/github.com/kerberos-io/agent/.git
-RUN cd /go/src/github.com/kerberos-io/agent/.git && git log --format="%H" -n 1 | head -c7 > /go/src/github.com/kerberos-io/agent/machinery/version
-RUN cat /go/src/github.com/kerberos-io/agent/machinery/version
+##############################################################################
+# Copy the rest of the source after dependencies are primed.
+
+COPY machinery ./
 
 ##################
 # Build Machinery
 
-RUN cd /go/src/github.com/kerberos-io/agent/machinery && \
-	go mod download && \
-	go build -tags timetzdata,netgo,osusergo --ldflags '-s -w -extldflags "-static -latomic"' main.go && \
+RUN RESOLVED_VERSION="${VERSION:-0.0.0}" && \
+	printf '%s' "${RESOLVED_VERSION}" > version && \
+	BUILD_TAGS=timetzdata,netgo,osusergo && \
+	case "${TARGETARCH:-$(go env GOARCH)}" in amd64|arm64) BUILD_TAGS="moq,${BUILD_TAGS}" ;; esac && \
+	go build -mod=readonly -trimpath -buildvcs=false -o main -tags "${BUILD_TAGS}" --ldflags "-s -w -X github.com/kerberos-io/agent/machinery/src/utils.VERSION=${RESOLVED_VERSION}" . && \
 	mkdir -p /agent && \
 	mv main /agent && \
 	mv version /agent && \
 	mv data /agent && \
 	mkdir -p /agent/data/cloud && \
+	mkdir -p /agent/data/tus && \
 	mkdir -p /agent/data/snapshots && \
 	mkdir -p /agent/data/log && \
 	mkdir -p /agent/data/recordings && \
 	mkdir -p /agent/data/capture-test && \
-	mkdir -p /agent/data/config && \
-	rm -rf /go/src/gitlab.com/
+	mkdir -p /agent/data/config
 
 ####################################
 # Let's create a /dist folder containing just the files necessary for runtime.
@@ -57,19 +71,7 @@ RUN cp -r /agent ./
 
 RUN /dist/agent/main version
 
-###############################################
-# Build Bento4 -> we want fragmented mp4 files
-
-ENV BENTO4_VERSION 1.6.0-639
-RUN cd /tmp && git clone https://github.com/axiomatic-systems/Bento4 && cd Bento4 && \
-	git checkout tags/v${BENTO4_VERSION} && \
-	cd Build && \
-	cmake -DCMAKE_BUILD_TYPE=Release .. && \
-	make && \
-	mv /tmp/Bento4/Build/mp4fragment /dist/agent/ && \
-	rm -rf /tmp/Bento4
-
-FROM node:18.14.0-alpine3.16 AS build-ui
+FROM node:22-alpine@sha256:fe4f6d74e20370acb04ad889077d14d0f64a9c8ea6a42bc60cddf1e844699914 AS build-ui
 
 RUN apk update && apk upgrade --available && sync
 
@@ -77,9 +79,11 @@ RUN apk update && apk upgrade --available && sync
 # Build Web (React app)
 
 RUN mkdir -p /go/src/github.com/kerberos-io/agent/machinery/www
-COPY ui /go/src/github.com/kerberos-io/agent/ui
-RUN cd /go/src/github.com/kerberos-io/agent/ui && rm -rf yarn.lock && yarn config set network-timeout 300000 && \
-	yarn && yarn build
+WORKDIR /go/src/github.com/kerberos-io/agent/ui
+COPY ui/package.json ui/yarn.lock ./
+RUN yarn config set network-timeout 300000 && yarn --frozen-lockfile
+COPY ui ./
+RUN yarn build
 
 ####################################
 # Let's create a /dist folder containing just the files necessary for runtime.
@@ -91,60 +95,64 @@ RUN mkdir -p ./agent && cp -r /go/src/github.com/kerberos-io/agent/machinery/www
 ############################################
 # Publish main binary to GitHub release
 
-FROM alpine:latest
+FROM ${RUNTIME_IMAGE} AS runtime-rootfs
 
-############################
-# Protect by non-root user.
-
-RUN addgroup -S kerberosio && adduser -S agent -G kerberosio && addgroup agent video
+RUN apt-get update && apt-get install -y --no-install-recommends \
+	ca-certificates ffmpeg libatomic1 libstdc++6 \
+	dash coreutils findutils grep sed tzdata ncurses-base && \
+	groupadd --system --gid 999 kerberosio && \
+	useradd --system --uid 999 --gid kerberosio --groups video \
+		--home-dir /home/agent --no-create-home agent
 
 #################################
 # Copy files from previous images
 
-COPY --chown=0:0 --from=build-machinery /dist /
-COPY --chown=0:0 --from=build-ui /dist /
+COPY --chown=0:0 --from=build-machinery /dist/agent/ /runtime/home/agent/
+COPY --chown=0:0 --from=build-ui /dist/agent/ /runtime/home/agent/
+COPY deployments/docker/assemble-rootfs.sh /usr/local/bin/assemble-rootfs
 
-RUN apk update && apk add ca-certificates curl libstdc++ libc6-compat --no-cache && rm -rf /var/cache/apk/*
+RUN chmod 0755 /runtime/home/agent /runtime/home/agent/main && \
+	cp /runtime/home/agent/data/config/config.json /runtime/home/agent/data/config.template.json && \
+	chown -R agent:kerberosio /runtime/home/agent/data && \
+	sh /usr/local/bin/assemble-rootfs
 
-##################
-# Try running agent
+FROM scratch
 
-RUN mv /agent/* /home/agent/
-RUN cp /home/agent/mp4fragment /usr/local/bin/
-RUN /home/agent/main version
+COPY --from=runtime-rootfs /runtime/ /
 
-#######################
-# Make template config
+ENV PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+ENV HOME=/home/agent
+ENV XDG_CACHE_HOME=/tmp/agent-cache
+ENV AGENT_PORT=8080
 
-RUN cp /home/agent/data/config/config.json /home/agent/data/config.template.json
-
-###########################
-# Set permissions correctly
-
-RUN chown -R agent:kerberosio /home/agent/data
-RUN chown -R agent:kerberosio /home/agent/www
-
-###########################
-# Grant the necessary root capabilities to the process trying to bind to the privileged port
-RUN apk add libcap && setcap 'cap_net_bind_service=+ep' /home/agent/main
+ARG VERSION
+ARG REVISION=unknown
+ARG CREATED
+LABEL org.opencontainers.image.title="Kerberos Agent" \
+	org.opencontainers.image.description="Camera and media agent with a minimal dynamic scratch runtime" \
+	org.opencontainers.image.source="https://github.com/kerberos-io/agent" \
+	org.opencontainers.image.version="${VERSION}" \
+	org.opencontainers.image.revision="${REVISION}" \
+	org.opencontainers.image.created="${CREATED}" \
+	org.opencontainers.image.vendor="UUG.AI"
 
 ###################
 # Run non-root user
 
-USER agent
+USER 999:999
 
 ######################################
-# By default the app runs on port 80
+# The image uses an unprivileged HTTP port.
 
-EXPOSE 80
+EXPOSE 8080/tcp
 
 ######################################
 # Check if agent is still running
 
-HEALTHCHECK CMD curl --fail http://localhost:80 || exit 1   
+HEALTHCHECK --timeout=10s CMD ["/home/agent/main", "-action", "healthcheck"]
 
 ###################################################
 # Leeeeettttt'ssss goooooo!!!
 # Run the shizzle from the right working directory.
 WORKDIR /home/agent
-CMD ["./main", "-action", "run", "-port", "80"]
+CMD ["./main", "-action", "run"]

README-RTSPS-TLS.md

@@ -0,0 +1,645 @@
+# RTSPS and TLS certificates
+
+This guide explains how Kerberos Agent connects to an IP camera over RTSPS,
+how to issue a camera certificate with a private CA, and how to validate the
+complete trust path. It also explains why some apparently corrupted trust
+bundles can still allow a connection.
+
+The camera-specific steps were verified with a Bosch FLEXIDOME micro 3100i.
+Other Bosch firmware versions may use different labels or ports.
+
+The commands were tested with Smallstep CLI `0.30.6` and OpenSSL `3.5.6` on
+Debian. Check `step certificate sign --help` when using an older Smallstep CLI.
+The OpenSSL isolation flags `-no-CApath` and `-no-CAstore` require a version that
+lists them in `openssl s_client -help`.
+
+## Tested configuration
+
+| Setting | Value |
+| --- | --- |
+| Camera | Bosch FLEXIDOME micro 3100i |
+| Example camera address | `10.0.30.11` |
+| RTSPS port | `9554` |
+| Main stream | `rtsps://<user>:<password>@10.0.30.11:9554/?inst=1` |
+| Sub stream | `rtsps://<user>:<password>@10.0.30.11:9554/?inst=2` |
+| Certificate SAN | `IP Address:10.0.30.11` |
+| Bosch certificate usage | `HTTPS` |
+| Agent trust input | Issuing intermediate plus root CA |
+
+Replace the example address and certificate names throughout this guide. Keep
+camera credentials out of source control and percent-encode reserved URL
+characters in usernames and passwords.
+
+## Mental model
+
+### RTSPS, SRTSP, TLS, and SRTP
+
+- The standard URL scheme is `rtsps://`. Do not use `srtsp://`.
+- Bosch interfaces and documentation may use SRTSP or Secure RTSP as product
+  terminology.
+- RTSPS carries the RTSP control connection over TLS. With gortsplib, media is
+  normally interleaved over the same TCP/TLS connection for this camera.
+- SRTP is a separate media protection mechanism and is negotiated only when the
+  camera advertises an appropriate secure RTP profile.
+
+Encryption alone does not prove which camera the Agent reached. Verified TLS
+also checks that:
+
+1. The camera certificate is signed by a trusted authority.
+2. The certificate is valid at the current time.
+3. The URL host matches a certificate Subject Alternative Name (SAN).
+
+Modern Go verification uses SANs for identity. A Common Name alone is not
+sufficient. Connecting to `10.0.30.11` requires an IP SAN with that exact value,
+not `DNS:10.0.30.11` and not only a device-name DNS SAN.
+
+### Agent behavior
+
+Kerberos Agent uses gortsplib for RTSP and RTSPS. With the normal configuration,
+gortsplib receives a nil custom TLS configuration and Go performs standard
+certificate and hostname verification with the process trust pool.
+
+`AGENT_CAPTURE_IPCAMERA_RTSPS_INSECURE=true` is an explicit escape hatch that
+sets `InsecureSkipVerify` for camera clients. It should be false in a verified
+deployment.
+
+## Communication and certificate flow
+
+The certificate is used during the TLS handshake, before the first RTSP command
+is exchanged. It is not attached to `DESCRIBE`, `SETUP`, or `PLAY`, and the CA
+trust bundle is never sent to the camera.
+
+```mermaid
+sequenceDiagram
+  participant Agent as Kerberos Agent
+  participant Trust as Go trust pool
+  participant Camera as Camera RTSPS :9554
+
+  Agent->>Trust: Load system roots and append AGENT_CAPTURE_IPCAMERA_RTSPS_CA_FILE
+  Agent->>Camera: Open TCP connection
+  Agent->>Camera: Send TLS ClientHello
+  Camera-->>Agent: Send TLS ServerHello and camera certificate
+  Agent->>Trust: Verify chain, validity, serverAuth, and URL host against SAN
+  Trust-->>Agent: Accept or reject the camera identity
+  Agent->>Camera: Complete TLS handshake
+  Note over Agent,Camera: All following traffic is encrypted by TLS
+  Agent->>Camera: DESCRIBE with RTSP authentication
+  Camera-->>Agent: Return SDP and available media tracks
+  Agent->>Camera: SETUP selected video and audio tracks over TCP
+  Agent->>Camera: PLAY
+  Camera-->>Agent: Send interleaved RTP and RTCP media over TLS
+```
+
+The files and keys have distinct roles:
+
+| Material | Location | Purpose | Sent over the connection |
+| --- | --- | --- | --- |
+| Camera leaf certificate | Camera | Identifies the camera and binds its public key to its SAN | Yes, by the camera during the TLS handshake |
+| Camera private key | Camera | Proves that the camera owns the presented certificate | No |
+| Intermediate and root CA PEM bundle | Agent | Lets Go build and trust the camera certificate chain | No |
+| RTSP username and password | Agent configuration or URL | Authenticates the Agent to the RTSP service after TLS succeeds | An authentication response is sent inside TLS; its form depends on the RTSP authentication method |
+
+For an `rtsps://` URL, the Agent parses the URL and gives gortsplib the host and
+TLS settings. gortsplib opens the TCP connection and starts TLS. Go compares the
+certificate presented by the camera with the local trust pool, checks its
+validity period and server usage, and matches the URL hostname or IP address to
+the certificate SAN. Only a successful handshake creates the encrypted channel
+needed for the RTSP exchange.
+
+The Agent then sends `DESCRIBE`, selects the advertised video and audio tracks,
+sends `SETUP`, and starts delivery with `PLAY`. For the tested camera, gortsplib
+uses interleaved TCP, so the RTSP control messages and RTP/RTCP media remain
+inside the same encrypted TLS connection. Main stream, sub stream, and enabled
+audio backchannel clients each establish and verify their own connection.
+
+If certificate verification fails, the TLS handshake does not complete and no
+usable RTSP session is established. Setting
+`AGENT_CAPTURE_IPCAMERA_RTSPS_INSECURE=true` keeps traffic encrypted but skips
+certificate-chain and hostname verification, so an attacker could impersonate
+the camera. It is not equivalent to trusting the camera certificate.
+
+## Decide the certificate identity first
+
+Choose the stable name used in every Agent URL before creating the certificate:
+
+- For an IP URL, add that address as an IP SAN.
+- For a DNS URL, add the exact hostname as a DNS SAN.
+- Add both when clients legitimately use both forms.
+
+A certificate stops matching if the camera IP changes. Use a static address,
+DHCP reservation, or stable DNS name.
+
+## Configure RTSPS in the Bosch UI
+
+1. Sign in to the camera as an administrator.
+2. Open **Configuration**.
+3. Open **Network > Network Services**.
+4. Enable **RTSPS**.
+5. Confirm port `9554`, or record the configured alternative.
+6. Click **Set**.
+
+RTSP on port `554` and RTSPS on port `9554` are separate services. Enabling
+RTSPS does not make an `rtsp://` URL secure.
+
+## Generate the private key and CSR on the camera
+
+Keeping the TLS private key on the camera avoids exporting it to an operator
+workstation or deployment system.
+
+1. Open **Service > Certificates**.
+2. Click **Add**.
+3. Select **Generate signing request**.
+4. Select `RSA 2048bit` or the stronger option supported by all clients.
+5. Enter a unique file name, such as `agent-rtsps`.
+6. Enter a descriptive Common Name and any required organization fields.
+7. Click **Generate**.
+8. Download the resulting CSR from the certificate table.
+
+On the tested firmware, this form contains no SAN field. The downloaded CSR
+therefore has no IP SAN. The CA must add the SAN while signing.
+
+Inspect the CSR before signing:
+
+```bash
+openssl req -in camera.csr.pem -noout -verify -subject
+openssl req -in camera.csr.pem -noout -text
+```
+
+The first command must report `Certificate request self-signature verify OK`.
+An absent `Subject Alternative Name` section is expected for this firmware.
+
+## Prepare Smallstep
+
+Use an existing organizational CA when one is available. Creating a new CA
+creates a new long-lived trust domain that must be distributed, protected,
+backed up, and eventually rotated.
+
+### Install the CLI on Debian amd64
+
+```bash
+curl -fsSL \
+  https://dl.smallstep.com/cli/docs-ca-install/latest/step-cli_amd64.deb \
+  -o /tmp/step-cli_amd64.deb
+sudo dpkg -i /tmp/step-cli_amd64.deb
+rm /tmp/step-cli_amd64.deb
+step version
+```
+
+Use the official package matching the host architecture on other systems.
+
+### Create a dedicated offline CA
+
+Skip this section when using an existing CA.
+
+```bash
+umask 077
+mkdir -p "$HOME/.step/secrets" "$HOME/.step/camera"
+
+openssl rand -base64 48 > "$HOME/.step/secrets/camera_ca_password"
+chmod 600 "$HOME/.step/secrets/camera_ca_password"
+
+step ca init \
+  --pki \
+  --name "UUG Camera CA" \
+  --password-file "$HOME/.step/secrets/camera_ca_password"
+```
+
+This produces:
+
+```text
+$HOME/.step/certs/root_ca.crt
+$HOME/.step/certs/intermediate_ca.crt
+$HOME/.step/secrets/root_ca_key
+$HOME/.step/secrets/intermediate_ca_key
+$HOME/.step/secrets/camera_ca_password
+```
+
+The files under `secrets/` are sensitive. Keep them mode `600`, never commit
+them, and back them up to encrypted persistent storage. A devcontainer can be
+rebuilt or deleted; it is not sufficient as the only CA backup.
+
+## Add the SAN while signing
+
+Copy the camera CSR into a protected working directory:
+
+```bash
+cp camera.csr.pem "$HOME/.step/camera/camera.csr.pem"
+```
+
+Create `$HOME/.step/camera/bosch-rtsps.tpl`:
+
+```json
+{
+  "subject": {
+    "commonName": {{ toJson .Insecure.CR.Subject.CommonName }}
+  },
+  "ipAddresses": ["10.0.30.11"],
+  "keyUsage": ["keyEncipherment", "digitalSignature"],
+  "extKeyUsage": ["serverAuth", "clientAuth"]
+}
+```
+
+The template preserves the camera CSR public key, sets the IP identity, and
+creates a TLS leaf rather than a CA certificate.
+
+Sign it with a validity period that ends before the intermediate CA expires.
+A one-year leaf is preferable to a ten-year leaf when automated renewal is
+available:
+
+```bash
+step certificate sign \
+  --template "$HOME/.step/camera/bosch-rtsps.tpl" \
+  --bundle \
+  --not-after 8760h \
+  --password-file "$HOME/.step/secrets/camera_ca_password" \
+  "$HOME/.step/camera/camera.csr.pem" \
+  "$HOME/.step/certs/intermediate_ca.crt" \
+  "$HOME/.step/secrets/intermediate_ca_key" \
+  > "$HOME/.step/camera/bosch-rtsps-chain.pem"
+```
+
+For an online `step-ca`, do not assume `step ca sign` accepts a `--san` flag. It
+does not. Authorize SANs in the one-time token or configure a provisioner
+template that produces the required SANs.
+
+## Validate before upload
+
+Inspect the leaf certificate, which is the first PEM block in the chain file:
+
+```bash
+openssl x509 \
+  -in "$HOME/.step/camera/bosch-rtsps-chain.pem" \
+  -noout -subject -issuer -dates -ext subjectAltName -ext extendedKeyUsage
+```
+
+Confirm the SAN separately because some OpenSSL versions display only the last
+requested extension:
+
+```bash
+openssl x509 \
+  -in "$HOME/.step/camera/bosch-rtsps-chain.pem" \
+  -noout -ext subjectAltName
+```
+
+Verify the path and IP identity:
+
+```bash
+openssl verify \
+  -CAfile "$HOME/.step/certs/root_ca.crt" \
+  -untrusted "$HOME/.step/certs/intermediate_ca.crt" \
+  -verify_ip 10.0.30.11 \
+  "$HOME/.step/camera/bosch-rtsps-chain.pem"
+```
+
+Confirm that the signed leaf uses the exact public key from the camera CSR:
+
+```bash
+csr_key=$(
+  openssl req -in "$HOME/.step/camera/camera.csr.pem" -pubkey -noout |
+    openssl pkey -pubin -outform DER 2>/dev/null |
+    sha256sum | cut -d' ' -f1
+)
+
+cert_key=$(
+  openssl x509 -in "$HOME/.step/camera/bosch-rtsps-chain.pem" -pubkey -noout |
+    openssl pkey -pubin -outform DER 2>/dev/null |
+    sha256sum | cut -d' ' -f1
+)
+
+test "$csr_key" = "$cert_key"
+```
+
+Do not upload a certificate when any of these checks fail.
+
+## Upload and assign the certificate
+
+1. Return to **Service > Certificates**.
+2. Click **Add > Upload certificate**.
+3. Select the leaf-plus-intermediate PEM chain.
+4. Click **Upload** and wait for `100%`.
+5. Confirm that the former CSR row is now a `Certificate`.
+6. Confirm that the key icon is present. It proves that the camera associated
+   the certificate with its retained private key.
+7. Open the new certificate's **Usage** selector.
+8. Select only **HTTPS**.
+9. Leave **CBS client** assigned to the original Bosch `DeviceCertificate`.
+10. Click **Set** and wait for the table to reload.
+
+On the tested firmware, there is no separate SRTSP usage. RTSPS presents the
+certificate assigned to HTTPS. Reassigning HTTPS therefore changes both the
+web interface and RTSPS certificate.
+
+After saving, the expected split is:
+
+| Certificate | Usage |
+| --- | --- |
+| Private-CA camera certificate | `HTTPS` |
+| Bosch `DeviceCertificate` | `CBS client` |
+
+The browser may warn about the new HTTPS certificate until the private root CA
+is trusted by the workstation.
+
+## Account for the Bosch chain behavior
+
+The tested firmware served only the leaf certificate on ports `443` and `9554`,
+even when the uploaded file contained the leaf and intermediate. Uploading the
+intermediate separately as a trusted camera certificate did not change the
+served chain.
+
+Confirm the behavior:
+
+```bash
+openssl s_client \
+  -connect 10.0.30.11:9554 \
+  -showcerts </dev/null 2>/dev/null |
+  grep -c '^-----BEGIN CERTIFICATE-----$'
+```
+
+A result of `1` means the client must already have the issuing intermediate.
+Create a portable trust bundle containing the intermediate and root:
+
+```bash
+step certificate bundle \
+  "$HOME/.step/certs/intermediate_ca.crt" \
+  "$HOME/.step/certs/root_ca.crt" \
+  "$HOME/.step/camera/uug-camera-trust-bundle.pem"
+
+chmod 644 "$HOME/.step/camera/uug-camera-trust-bundle.pem"
+```
+
+The trust bundle is public material. The CA private keys and password are not.
+
+## Configure Kerberos Agent
+
+For a process running directly in the same environment:
+
+```dotenv
+AGENT_CAPTURE_IPCAMERA_RTSP="rtsps://<user>:<password>@10.0.30.11:9554/?inst=1"
+AGENT_CAPTURE_IPCAMERA_SUB_RTSP="rtsps://<user>:<password>@10.0.30.11:9554/?inst=2"
+AGENT_CAPTURE_IPCAMERA_RTSPS_INSECURE=false
+AGENT_CAPTURE_IPCAMERA_RTSPS_CA_FILE=/home/agent/data/config/uug-camera-trust-bundle.pem
+```
+
+For a container, mount the public bundle read-only at the exact path visible
+inside the container. The Agent image creates `/home/agent/data/config` and
+includes Debian's `ca-certificates` package:
+
+```bash
+docker run \
+  -v /secure/config/uug-camera-trust-bundle.pem:/home/agent/data/config/uug-camera-trust-bundle.pem:ro \
+  -e AGENT_CAPTURE_IPCAMERA_RTSPS_CA_FILE=/home/agent/data/config/uug-camera-trust-bundle.pem \
+  -e AGENT_CAPTURE_IPCAMERA_RTSPS_INSECURE=false \
+  -e 'AGENT_CAPTURE_IPCAMERA_RTSP=rtsps://<user>:<password>@10.0.30.11:9554/?inst=1' \
+  -e 'AGENT_CAPTURE_IPCAMERA_SUB_RTSP=rtsps://<user>:<password>@10.0.30.11:9554/?inst=2' \
+  kerberos/agent:latest
+```
+
+`AGENT_CAPTURE_IPCAMERA_RTSPS_CA_FILE` starts with the operating system's roots
+and appends the camera bundle only to the gortsplib TLS configuration. Other
+clients, including MoQ, Hub, and Vault, retain the normal public CA chain.
+Restart the Agent after changing trust files.
+
+Do not set `SSL_CERT_FILE` or `SSL_CERT_DIR` in production solely for camera
+trust. They are process-wide and can prevent other clients from validating
+public services. For a deliberate process-wide isolation test, mount an empty
+directory and set `SSL_CERT_DIR` to its path:
+
+```bash
+-v /secure/config/empty-ca-dir:/home/agent/data/config/empty-ca-dir:ro \
+-e SSL_CERT_DIR=/home/agent/data/config/empty-ca-dir
+```
+
+Do not use `SSL_CERT_DIR=`. Go treats an empty value as unset and scans its
+default certificate directories.
+
+Only use that mode when the Agent does not need public roots for other TLS
+connections.
+
+## Validate the live endpoints
+
+### Strict TLS and identity check
+
+Use only the specified bundle, without OpenSSL's default CA locations:
+
+```bash
+openssl s_client \
+  -brief \
+  -connect 10.0.30.11:9554 \
+  -verify_ip 10.0.30.11 \
+  -verify_return_error \
+  -CAfile "$HOME/.step/camera/uug-camera-trust-bundle.pem" \
+  -no-CApath \
+  -no-CAstore \
+  </dev/null
+```
+
+Repeat with port `443`. Both must report `Verification: OK`.
+
+Confirm that identity checking is active by repeating the command with a wrong
+address, such as `-verify_ip 10.0.30.12`. It must fail with an IP address
+mismatch.
+
+### Confirm the live leaf is the generated leaf
+
+```bash
+live_fingerprint=$(
+  openssl s_client -connect 10.0.30.11:9554 -showcerts </dev/null 2>/dev/null |
+    openssl x509 -noout -fingerprint -sha256 |
+    cut -d= -f2
+)
+
+local_fingerprint=$(
+  openssl x509 \
+    -in "$HOME/.step/camera/bosch-rtsps-chain.pem" \
+    -noout -fingerprint -sha256 |
+    cut -d= -f2
+)
+
+test "$live_fingerprint" = "$local_fingerprint"
+```
+
+### Validate the media path
+
+A successful TLS handshake does not prove that RTSP authentication, DESCRIBE,
+SETUP, PLAY, and RTP delivery work. Start a fresh Agent with verified TLS and
+confirm that it connects without an x509 error and receives frames. During the
+verified setup described here, a gortsplib probe completed all RTSP operations
+and received an RTP packet over TCP.
+
+## Why a tampered bundle may still connect
+
+Editing PEM text is not always a useful negative TLS test.
+
+### A certificate can still parse after a byte change
+
+Base64 can remain syntactically valid when one character changes. OpenSSL may
+still list the certificate subject and issuer even though a signature is now
+invalid. Parsing and signature verification are different operations.
+
+### Trust anchors are not validated through a parent
+
+Every certificate loaded into Go's root pool is a trust anchor, including a
+non-self-signed intermediate CA. Verification can terminate at that certificate.
+
+If tampering changes only the intermediate's signature from its parent root,
+but does not change its public key, that intermediate can still validate the
+camera leaf when it is trusted directly. Its now-invalid parent signature is
+not consulted at the trust boundary.
+
+This is equivalent to OpenSSL's partial-chain behavior:
+
+```bash
+openssl s_client \
+  -connect 10.0.30.11:9554 \
+  -verify_ip 10.0.30.11 \
+  -verify_return_error \
+  -partial_chain \
+  -CAfile tampered-bundle.pem \
+  -no-CApath \
+  -no-CAstore \
+  </dev/null
+```
+
+### `SSL_CERT_FILE` does not isolate Go from CA directories
+
+On Unix, Go uses `SSL_CERT_FILE` instead of its default aggregate CA file, but it
+still scans default certificate directories such as `/etc/ssl/certs`. Setting
+`SSL_CERT_FILE` alone therefore does not remove CA certificates installed with
+`update-ca-certificates`. `AGENT_CAPTURE_IPCAMERA_RTSPS_CA_FILE` is appended
+after this system pool is loaded; it does not replace the system roots.
+
+Blank values do not select empty trust sources. Both `SSL_CERT_FILE=` and
+`SSL_CERT_DIR=` are treated as unset, so Go falls back to its default aggregate
+CA file and certificate directories. To test with no trusted certificates on
+Linux, use a non-empty file path that contains no certificates and a non-empty
+directory path that contains no certificates:
+
+```bash
+mkdir -p /tmp/empty-ca-dir
+SSL_CERT_FILE=/dev/null \
+SSL_CERT_DIR=/tmp/empty-ca-dir \
+AGENT_CAPTURE_IPCAMERA_RTSPS_CA_FILE= \
+AGENT_CAPTURE_IPCAMERA_RTSPS_INSECURE=false \
+GOWORK=off \
+go run -tags moq . -action run -port 8080
+```
+
+That fresh process must fail with `x509: certificate signed by unknown
+authority`.
+
+Use exactly one camera trust-distribution approach when possible:
+
+1. Mount a private trust bundle and set
+  `AGENT_CAPTURE_IPCAMERA_RTSPS_CA_FILE`; or
+2. Install the CA certificates into the operating-system trust store.
+
+Using both is valid, but makes isolation tests less obvious.
+
+### Running processes can retain old roots
+
+A long-running Go process may already have loaded and cached the trust pool.
+Always start a new process after changing trust configuration during a negative
+test.
+
+## Perform a meaningful negative test
+
+Do not corrupt only the root or intermediate signature. Instead, give a fresh
+Agent process a completely unrelated CA and hide the default CA directories.
+
+```bash
+mkdir -p /tmp/empty-ca-dir
+
+openssl req \
+  -x509 -newkey rsa:2048 -nodes -days 1 \
+  -subj '/CN=Unrelated Test Root' \
+  -keyout /tmp/unrelated-test-root.key \
+  -out /tmp/unrelated-test-root.crt
+
+SSL_CERT_FILE=/dev/null \
+SSL_CERT_DIR=/tmp/empty-ca-dir \
+AGENT_CAPTURE_IPCAMERA_RTSPS_CA_FILE=/tmp/unrelated-test-root.crt \
+AGENT_CAPTURE_IPCAMERA_RTSPS_INSECURE=false \
+GOWORK=off \
+go run -tags moq . -action run -port 8080
+```
+
+The connection must fail with an unknown-authority or chain-building error.
+Delete the temporary test key and certificate afterward.
+
+To test bundle integrity rather than client distrust, validate the intermediate
+against the root explicitly:
+
+```bash
+openssl verify \
+  -CAfile "$HOME/.step/certs/root_ca.crt" \
+  -no-CApath \
+  -no-CAstore \
+  "$HOME/.step/certs/intermediate_ca.crt"
+```
+
+Store and compare approved SHA-256 fingerprints when detecting unauthorized
+certificate-file changes is a requirement.
+
+Restore an accidentally edited bundle from the protected CA certificates, then
+restart the Agent:
+
+```bash
+step certificate bundle -f \
+  "$HOME/.step/certs/intermediate_ca.crt" \
+  "$HOME/.step/certs/root_ca.crt" \
+  "$HOME/.step/camera/uug-camera-trust-bundle.pem"
+
+openssl verify \
+  -CAfile "$HOME/.step/certs/root_ca.crt" \
+  -no-CApath \
+  -no-CAstore \
+  "$HOME/.step/certs/intermediate_ca.crt"
+```
+
+## Optional system trust installation
+
+On Debian, install both public CA certificates when every process in the system
+should trust this camera PKI:
+
+```bash
+sudo install -m 0644 \
+  "$HOME/.step/certs/root_ca.crt" \
+  /usr/local/share/ca-certificates/uug-camera-ca.crt
+
+sudo install -m 0644 \
+  "$HOME/.step/certs/intermediate_ca.crt" \
+  /usr/local/share/ca-certificates/uug-camera-intermediate-ca.crt
+
+sudo update-ca-certificates
+```
+
+This creates links below `/etc/ssl/certs`. Remove those files and rerun
+`update-ca-certificates` before attempting an isolated trust-bundle test.
+
+## Renewal and recovery
+
+- Renew before the leaf or intermediate expires.
+- Generate a new camera CSR if the firmware cannot renew the existing key.
+- Sign the new CSR with all required SANs.
+- Upload and validate the new certificate before deleting the old one.
+- Preserve an alternate administrative access path while changing HTTPS usage.
+- Back up the CA certificates, encrypted CA keys, and password separately.
+- If the CA private keys are lost, create a new CA and redistribute its trust
+  before replacing camera certificates.
+
+## Production checklist
+
+- [ ] The Agent URL uses `rtsps://`, not `rtsp://` or `srtsp://`.
+- [ ] RTSPS is enabled on the camera and the configured port is reachable.
+- [ ] The certificate SAN exactly matches the Agent URL host.
+- [ ] The leaf public key matches the camera-generated CSR.
+- [ ] The certificate has `serverAuth` extended key usage.
+- [ ] The certificate expires before its issuer.
+- [ ] HTTPS is assigned to the private-CA certificate.
+- [ ] CBS client remains assigned to the Bosch device certificate.
+- [ ] The Agent has the intermediate and root CA certificates it needs.
+- [ ] `AGENT_CAPTURE_IPCAMERA_RTSPS_INSECURE=false`.
+- [ ] The Agent was restarted after trust changes.
+- [ ] A strict TLS check reports `Verification: OK`.
+- [ ] A real Agent connection receives RTP packets.
+- [ ] CA private keys and passwords are backed up outside the devcontainer.

README.md

@@ -3,7 +3,6 @@
 <a target="_blank" href="https://kerberos.io"><img src="https://img.shields.io/badge/kerberos-website-gray.svg?longCache=true&colorB=brightgreen" alt="Kerberos Agent"></a>
 <a target="_blank" href="https://doc.kerberos.io"><img src="https://img.shields.io/badge/kerberos-documentation-gray.svg?longCache=true&colorB=brightgreen" alt="Kerberos Agent"></a>
 
-<a target="_blank" href="https://circleci.com/gh/kerberos-io/agent"><img src="https://circleci.com/gh/kerberos-io/agent.svg?style=svg"/></a>
 <img src="https://github.com/kerberos-io/agent/workflows/Go/badge.svg"/>
 <img src="https://github.com/kerberos-io/agent/workflows/React/badge.svg"/>
 <img src="https://github.com/kerberos-io/agent/workflows/CodeQL/badge.svg"/>
@@ -17,20 +16,23 @@
 <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
 [![donate](https://brianmacdonald.github.io/Ethonate/svg/eth-donate-blue.svg)](https://brianmacdonald.github.io/Ethonate/address#0xf4a759C9436E2280Ea9cdd23d3144D95538fF4bE)
 <a target="_blank" href="https://twitter.com/kerberosio?ref_src=twsrc%5Etfw"><img src="https://img.shields.io/twitter/url.svg?label=Follow%20%40kerberosio&style=social&url=https%3A%2F%2Ftwitter.com%2Fkerberosio" alt="Twitter Widget"></a>
-[![Discord Shield](https://discordapp.com/api/guilds/1039619181731135499/widget.png?style=shield)](https://discord.gg/Bj77Vqfp2G)
 [![kerberosio](https://snapcraft.io/kerberosio/badge.svg)](https://snapcraft.io/kerberosio)
 
+[![Slack invite](https://img.shields.io/badge/join%20kerberos.io%20on%20slack-grey?style=for-the-badge&logo=slack)](https://joinslack.kerberos.io/)
+
 [**Docker Hub**](https://hub.docker.com/r/kerberos/agent) | [**Documentation**](https://doc.kerberos.io) | [**Website**](https://kerberos.io) | [**View Demo**](https://demo.kerberos.io)
 
+> Before you continue, this repository discusses one of the components of the Kerberos.io stack, the Kerberos Agent, in depth. If you are [looking for an end-to-end deployment guide have a look here](https://github.com/kerberos-io/deployment).
+
 Kerberos Agent is an isolated and scalable video (surveillance) management agent made available as Open Source under the MIT License. This means that all the source code is available for you or your company, and you can use, transform and distribute the source code; as long you keep a reference of the original license. Kerberos Agent can be used for commercial usage (which was not the case for v2). Read more [about the license here](LICENSE).
 
 ![Kerberos Agent go through UI](./assets/img/kerberos-agent-overview.gif)
 
 ## :thinking: Prerequisites
 
-- An IP camera which supports a RTSP H264 encoded stream,
-  - (or) a USB camera, Raspberry Pi camera or other camera, that [you can tranform to a valid RTSP H264 stream](https://github.com/kerberos-io/camera-to-rtsp).
-- Any hardware (ARMv6, ARMv7, ARM64, AMD) that can run a binary or container, for example: a Raspberry Pi, NVidia Jetson, Intel NUC, a VM, Bare metal machine or a full blown Kubernetes cluster.
+- An IP camera which supports a RTSP H264 or H265 encoded stream,
+  - (or) a USB camera, Raspberry Pi camera or other camera, that [you can transform to a valid RTSP H264 or H265 stream](https://github.com/kerberos-io/camera-to-rtsp).
+- Any hardware (ARMv6, ARMv7, ARM64, AMD64) that can run a binary or container, for example: a Raspberry Pi, NVidia Jetson, Intel NUC, a VM, Bare metal machine or a full blown Kubernetes cluster.
 
 ## :video_camera: Is my camera working?
 
@@ -46,41 +48,140 @@ There are a myriad of cameras out there (USB, IP and other cameras), and it migh
 
 ### Introduction
 
-3. [A world of Kerberos Agents](#a-world-of-kerberos-agents)
+1. [A world of Kerberos Agents](#a-world-of-kerberos-agents)
 
 ### Running and automation
 
-4. [How to run and deploy a Kerberos Agent](#how-to-run-and-deploy-a-kerberos-agent)
-5. [Access the Kerberos Agent](#access-the-kerberos-agent)
-6. [Configure and persist with volume mounts](#configure-and-persist-with-volume-mounts)
-7. [Configure with environment variables](#configure-with-environment-variables)
+1. [How to run and deploy a Kerberos Agent](#how-to-run-and-deploy-a-kerberos-agent)
+2. [Access the Kerberos Agent](#access-the-kerberos-agent)
+3. [Configure and persist with volume mounts](#configure-and-persist-with-volume-mounts)
+4. [Configure with environment variables](#configure-with-environment-variables)
+
+### Insights
+
+1. [Encryption](#encryption)
+2. [H264 vs H265](#h264-vs-h265)
 
 ### Contributing
 
-8. [Contribute with Codespaces](#contribute-with-codespaces)
-9. [Develop and build](#develop-and-build)
-10. [Building from source](#building-from-source)
-11. [Building for Docker](#building-for-docker)
+1. [Security vulnerability reporting](#security-vulnerability-reporting)
+1. [Contribute with Codespaces](#contribute-with-codespaces)
+2. [Develop and build](#develop-and-build)
+3. [Building from source](#building-from-source)
+4. [Building for Docker](#building-for-docker)
 
 ### Varia
 
-12. [Support our project](#support-our-project)
-13. [What is new?](#what-is-new)
-14. [Contributors](#contributors)
+1. [Support our project](#support-our-project)
+1. [What is new?](#what-is-new)
+1. [Contributors](#contributors)
+
+### Direct S3 recording layout
+
+Direct S3 uploads store recordings as
+`<s3.username>/yyyy/mm/dd/<timestamp>-<deviceKey>.mp4`. The timestamp is the
+recording's Unix timestamp in milliseconds, and the date is its UTC date, not the upload
+date. Timestamp and device key come from the recording's `.metadata` upload
+checkpoint, which stores the timestamp in milliseconds. The uploader also
+preserves checkpoint duration, FPS (when available), and encryption status as S3
+object metadata. The device key must be non-empty and contain no path separators.
+Retried uploads use the same object key, even after midnight. Millisecond
+precision keeps recordings starting within the same second distinct.
+
+This replaces the previous `<s3.username>/<filename>.mp4` layout for new uploads.
+Existing objects are not moved; consumers of direct S3 uploads must support both
+layouts when reading historical recordings. Updated Kerberos Vault deployments
+use the same filename and dated layout under the authenticated account directory
+for both direct Vault uploads and Hub-proxied uploads.
+
+Only historical recordings with missing, empty, or FPS-only queue markers fall
+back to the legacy filename format and configured Agent key. A structured
+checkpoint takes precedence over both the filename and current configured key;
+an invalid or unreadable checkpoint is reported as an upload error, not silently
+replaced with filename-derived values.
+For older structured checkpoints, missing camera name, region, and change count
+are recovered from a validated legacy filename. Populated checkpoint fields
+take precedence, and the checkpoint timestamp and device key remain authoritative.
+
+The shorter filename cannot be decoded by legacy filename-only consumers.
+Integrations must preserve structured recording metadata, including the device
+key (`productid`) and recording timestamp (`event-timestamp`), as well as the full
+object key.
+
+### Local recording layout
+
+New local recordings are stored under
+`data/recordings/yyyy/mm/dd/<timestamp>-<deviceKey>.mp4`, using the recording's UTC
+start date and Unix-millisecond timestamp. For example:
+`data/recordings/2026/01/02/1767355200123-device-key.mp4`.
+The filename no longer embeds the camera name, region, change count, or duration,
+and it does not change when the recording is finalized.
+Those attributes, together with FPS and encryption status, are captured in the
+`.metadata` upload checkpoint and sent as structured HTTP/tus metadata.
+
+Existing flat recordings and dated recordings with older long filenames remain
+supported without a migration. Recording lists, day filters, playback, uploaders,
+and automatic cleanup handle both filename formats and layouts. Upload queue
+checkpoints remain flat in `data/cloud/`. Successful-upload removal also resolves
+both local layouts. Deploy the updated Vault alongside Agent for canonical
+`<account-directory>/yyyy/mm/dd/<timestamp>-<deviceKey>.mp4` storage keys and
+metadata-driven Hub integration events.
+Directory decryption also processes dated subdirectories and writes each output
+to a sibling `decrypted/` directory; those outputs are excluded from recording
+lists and automatic cleanup.
 
 ## Quickstart - Docker
 
-The easiest to get your Kerberos Agent up and running is to use our public image on [Docker hub](https://hub.docker.com/r/kerberos/agent). Once you have selected a specific tag, run below `docker` command, which will open the web interface of your Kerberos agent on port `80`, and off you go. For a more configurable and persistent deployment have a look at [Running and automating a Kerberos Agent](#running-and-automating-a-kerberos-agent).
+The easiest way to get your Kerberos Agent up and running is to use our public image on [Docker hub](https://hub.docker.com/r/kerberos/agent). Once you have selected a specific tag, run `docker` command below, which will open the web interface of your Kerberos agent on port `80`, and off you go. For a more configurable and persistent deployment have a look at [Running and automating a Kerberos Agent](#running-and-automating-a-kerberos-agent).
 
-    docker run -p 80:80 --name mycamera -d --restart=always kerberos/agent:latest
+**Forthcoming hardened image** (use this mapping only after upgrading to a
+release containing these changes):
 
-If you want to connect to an USB or Raspberry Pi camera, [you'll need to run our side car container](https://github.com/kerberos-io/camera-to-rtsp) which proxy the camera to an RTSP stream. In that case you'll want to configure the Kerberos Agent container to run in the host network, so it can connect directly to the RTSP sidecar.
+    docker run -p 80:8080 --name mycamera -d --restart=always kerberos/agent:latest
+
+The hardened image listens on **8080 inside the container**, not 80. The mapping
+`-p 80:8080` keeps the browser URL `http://localhost/` unchanged. When upgrading,
+change the container side of existing `80:80` or `8082:80` mappings to
+`80:8080` or `8082:8080`. Kubernetes Services must use `targetPort: 8080`.
+Older published images still use their original port: these examples require a
+release containing the hardening changes; pin its published digest in production.
+For the currently published `v3.14.1`, retain the old mapping:
+
+    docker run -p 80:80 --name mycamera -d --restart=always kerberos/agent:v3.14.1
+
+The image uses a Go 1.26 scratch runtime with only required dynamic/media
+dependencies, numeric non-root UID/GID `999:999`, no file capabilities or
+setuid/setgid programs, and an application healthcheck (no curl-based probe).
+UI assets are immutable; demo mode selects its environment without rewriting them.
+Source builds require the patched Go 1.26.10 toolchain or newer.
+It supports dropping all capabilities and preventing privilege escalation:
+
+```sh
+docker run --cap-drop=ALL --security-opt=no-new-privileges:true \
+  -p 80:8080 --name mycamera -d kerberos/agent:latest
+```
+
+See the [image contract](deployments/docker/README.md#image-contract) for writable
+paths, health checks, supported architectures, signature/evidence requirements,
+and release-policy gaps. Functional remote-shell support remains a **pending
+policy exception**, so this is not a claim of full image-hardening baseline or
+CIS compliance.
+Release promotion is also blocked by remaining native-library scan findings;
+this PR is not release-qualified. The existing recording-signing key and trust
+behavior are retained under the user's narrowly scoped exception through
+December 5, 2026 (23:59:59 UTC), recorded for review in this PR. The finding
+remains visible in scan reports; other keys and findings are not exempted.
+
+If you want to connect to a USB or Raspberry Pi camera, [you'll need to run our side car container](https://github.com/kerberos-io/camera-to-rtsp) which proxies the camera to an RTSP stream. In that case you'll want to configure the Kerberos Agent container to run in the host network, so it can connect directly to the RTSP sidecar.
 
     docker run --network=host --name mycamera -d --restart=always kerberos/agent:latest
 
+With host networking, no port mapping applies: the hardened Agent is reachable
+on host port `8080` by default.
+
 ## Quickstart - Balena
 
-Run Kerberos Agent with [Balena Cloud](https://www.balena.io/) super powers. Monitor your Kerberos Agent with seamless remote access, over the air updates, an encrypted public `https` endpoint and many more. Checkout our application `video-surveillance` on [Balena Hub](https://hub.balena.io/apps/2064752/video-surveillance), and create your first or fleet of Kerberos Agent(s).
+Run Kerberos Agent with [Balena Cloud](https://www.balena.io/) super powers. Monitor your Kerberos Agent with seamless remote access, over the air updates, an encrypted public `https` endpoint and much more. Checkout our application `video-surveillance` on [Balena Hub](https://hub.balena.io/apps/2064752/video-surveillance), and create your first or fleet of Kerberos Agent(s).
 
 [![deploy with balena](https://balena.io/deploy.svg)](https://dashboard.balena-cloud.com/deploy?repoUrl=https://github.com/kerberos-io/balena-agent)
 
@@ -96,31 +197,37 @@ Once installed you can find your Kerberos Agent configration at `/var/snap/kerbe
 
 ## A world of Kerberos Agents
 
-The Kerberos Agent is an isolated and scalable video (surveillance) management agent with a strong focus on user experience, scalability, resilience, extension and integration. Next to the Kerberos Agent, Kerberos.io provides many other tools such as [Kerberos Factory](https://github.com/kerberos-io/factory), [Kerberos Vault](https://github.com/kerberos-io/vault) and [Kerberos Hub](https://github.com/kerberos-io/hub) to provide additional capabilities: bring your own cloud, bring your own storage, central overview, live streaming, machine learning etc.
+The Kerberos Agent is an isolated and scalable video (surveillance) management agent with a strong focus on user experience, scalability, resilience, extension and integration. Next to the Kerberos Agent, Kerberos.io provides many other tools such as [Kerberos Factory](https://github.com/kerberos-io/factory), [Kerberos Vault](https://github.com/kerberos-io/vault), and [Kerberos Hub](https://github.com/kerberos-io/hub) to provide additional capabilities: bring your own cloud, bring your own storage, central overview, live streaming, machine learning, etc.
 
-As mentioned above Kerberos.io applies the concept of agents. An agent is running next to (or on) your camera, and is processing a single camera feed. It applies motion based or continuous recording and make those recordings available through a user friendly web interface. A Kerberos Agent allows you to connect to other cloud services or integrates with custom applications. Kerberos Agent is used for personal usage and scales to enterprise production level deployments.
+[![Deployment Agent](./assets/img/edge-deployment-agent.svg)](https://github.com/kerberos-io/deployment)
+
+As mentioned above Kerberos.io applies the concept of agents. An agent is running next to (or on) your camera, and is processing a single camera feed. It applies motion based or continuous recording and makes those recordings available through a user friendly web interface. A Kerberos Agent allows you to connect to other cloud services or integrate with custom applications. Kerberos Agent is used for personal applications and scales to enterprise production level deployments. Learn more about the [deployment strategies here](<(https://github.com/kerberos-io/deployment)>).
 
 This repository contains everything you'll need to know about our core product, Kerberos Agent. Below you'll find a brief list of features and functions.
 
 - Low memory and CPU usage.
 - Simplified and modern user interface.
-- Multi architecture (ARMv7, ARMv8, amd64, etc).
-- Multi camera support: IP Cameras (H264), USB cameras and Raspberry Pi Cameras [through a RTSP proxy](https://github.com/kerberos-io/camera-to-rtsp).
+- Multi architecture (AMD64/ARM64 release images; [legacy ARM build limitations](deployments/docker/README.md#building-and-checking-the-image)).
+- Multi stream, for example recording in H265, live streaming and motion detection in H264.
+- Multi camera support: IP Cameras (H264 and H265), USB cameras and Raspberry Pi Cameras [through a RTSP proxy](https://github.com/kerberos-io/camera-to-rtsp).
 - Single camera per instance (e.g. one container per camera).
-- Primary and secondary stream setup (record full-res, stream low-res).
-- Low resolution streaming through MQTT and full resolution streaming through WebRTC.
-- Ability to specifiy conditions: offline mode, motion region, time table, continuous recording, etc.
-- Post- and pre-recording on motion detection.
-- Ability to create fragmented recordings, and streaming though HLS fMP4.
+- Low resolution streaming through MQTT and high resolution streaming through WebRTC (only supports H264/PCM).
+- Backchannel audio from Kerberos Hub to IP camera (requires PCM ULAW codec)
+- Audio (AAC) and video (H264/H265) recording in MP4 container.
+- End-to-end encryption through MQTT using RSA and AES (livestreaming, ONVIF, remote configuration, etc)
+- Conditional recording: offline mode, motion region, time table, continuous recording, webhook condition etc.
+- Post- and pre-recording for motion detection.
+- Encryption at rest using AES-256-CBC.
+- Ability to create fragmented recordings, and streaming through HLS fMP4.
 - [Deploy where you want](#how-to-run-and-deploy-a-kerberos-agent) with the tools you use: `docker`, `docker compose`, `ansible`, `terraform`, `kubernetes`, etc.
 - Cloud storage/persistance: Kerberos Hub, Kerberos Vault and Dropbox. [(WIP: Minio, Storj, Google Drive, FTP etc.)](https://github.com/kerberos-io/agent/issues/95)
-- WIP: Integrations (Webhooks, MQTT, Script, etc).
+- Outputs: trigger an integration (Webhooks, MQTT, Script, etc) when a specific event (motion detection or start recording ) occurs
 - REST API access and documentation through Swagger (trigger recording, update configuration, etc).
 - MIT License
 
 ## How to run and deploy a Kerberos Agent
 
-As described before a Kerberos Agent is a container, which can be deployed through various ways and automation tools such as `docker`, `docker compose`, `kubernetes` and the list goes on. To simplify your life we have come with concrete and working examples of deployments to help you speed up your Kerberos.io journey.
+A Kerberos Agent, as previously mentioned, is a container. You can deploy it using various methods and automation tools, including `docker`, `docker compose`, `kubernetes` and more. To streamline your Kerberos.io experience, we provide concrete deployment examples to speed up your Kerberos.io journey”
 
 We have documented the different deployment models [in the `deployments` directory](https://github.com/kerberos-io/agent/tree/master/deployments) of this repository. There you'll learn and find how to deploy using:
 
@@ -134,7 +241,7 @@ We have documented the different deployment models [in the `deployments` directo
 - [Balena](https://github.com/kerberos-io/agent/tree/master/deployments#8-balena)
 - [Snap](https://github.com/kerberos-io/agent/tree/master/deployments#9-snap)
 
-By default your Kerberos Agents will store all its configuration and recordings inside the container. To help you automate and have a more consistent data governance, you can attach volumes to configure and persist data of your Kerberos Agents, and/or configure each Kerberos Agent through environment variables.
+By default, your Kerberos Agents store all configuration and recordings within the container. To help you automate and have a more consistent data governance, you can attach volumes to configure and persist data of your Kerberos Agents and/or configure each Kerberos Agent through environment variables.
 
 ## Access the Kerberos Agent
 
@@ -149,90 +256,406 @@ The default username and password for the Kerberos Agent is:
 
 ## Configure and persist with volume mounts
 
-An example of how to mount a host directory is shown below using `docker`, but is applicable for [all the deployment models and tools described above](#running-and-automating-a-kerberos-agent).
+An example of how to mount a host directory is shown below using `docker`, but is applicable for [all of the deployment models and tools described above](#running-and-automating-a-kerberos-agent).
 
-You attach a volume to your container by leveraging the `-v` option. To mount your own configuration file and recordings folder, execute as following:
+You attach a volume to your container by leveraging the `-v` option. To mount your own configuration file and recordings folder, run the following commands:
 
-    docker run -p 80:80 --name mycamera \
+    docker run -p 80:8080 --name mycamera \
     -v $(pwd)/agent/config:/home/agent/data/config \
     -v $(pwd)/agent/recordings:/home/agent/data/recordings \
     -d --restart=always kerberos/agent:latest
 
-More example [can be found in the deployment section](https://github.com/kerberos-io/agent/tree/master/deployments) for each deployment and automation tool. Please note to verify the permissions of the directory/volume you are attaching. More information in [this issue](https://github.com/kerberos-io/agent/issues/80).
+More examples for each deployment and automation tool [can be found in the deployment section](https://github.com/kerberos-io/agent/tree/master/deployments). Be sure to verify the permissions of the directory/volume you are attaching. More information in [this issue](https://github.com/kerberos-io/agent/issues/80).
 
-    chmod -R 755 kerberos-agent/
-    chown 100:101 kerberos-agent/ -R
+The current image runs as UID `999`, GID `999`. Give that user ownership of
+the mounted directories (older image tags may use different IDs):
+
+    sudo chown -R 999:999 agent/config agent/recordings
+
+See [container permissions and hardening](deployments/docker/README.md#container-permissions-and-hardening)
+for reduced-capability deployment and migration guidance.
 
 ## Configure with environment variables
 
-Next to attaching the configuration file, it is also possible to override the configuration with environment variables. This makes deployments easier when leveraging `docker compose` or `kubernetes` deployments much easier and scalable. Using this approach we simplify automation through `ansible` and `terraform`.
+Next to attaching the configuration file, it is also possible to override the configuration with environment variables. This makes deploying with `docker compose` or `kubernetes` much easier and more scalable. Using this approach, we simplify automation through `ansible` and `terraform`.
 
-    docker run -p 80:80 --name mycamera \
+    docker run -p 80:8080 --name mycamera \
     -e AGENT_NAME=mycamera \
     -e AGENT_TIMEZONE=Europe/Brussels \
     -e AGENT_CAPTURE_IPCAMERA_RTSP=rtsp://fake.kerberos.io/stream \
     -e AGENT_CAPTURE_CONTINUOUS=true \
     -d --restart=always kerberos/agent:latest
 
+Set `AGENT_PORT` to change the Agent's internal HTTP port. The environment
+variable takes precedence over `-port`. When using Docker, publish the same
+container port:
+
+```bash
+docker run -p 8082:8082 \
+  -e AGENT_PORT=8082 \
+  --name mycamera \
+  -d --restart=always kerberos/agent:latest
+```
+
+### Health checks and API responses
+
+`GET /health` is an unauthenticated liveness and diagnostics endpoint for
+container orchestrators and external monitors. `healthy` means that the Agent
+HTTP process can serve requests. Camera streams and Hub connectivity are
+reported independently in the response, so an external camera or Hub outage
+does not make Docker restart an otherwise functioning Agent process. Successful
+probes return `200 OK` and are logged at debug level to avoid periodic health
+checks filling production logs.
+
+```bash
+curl http://localhost:8082/health
+```
+
+```json
+{
+  "httpStatusCode": 200,
+  "applicationStatusCode": "get_success",
+  "entityStatusCode": "healthy",
+  "message": "Healthy",
+  "metadata": {
+    "applicationName": "agent",
+    "applicationVersion": "0.0.0",
+    "timestamp": 1788710400,
+    "path": "/health"
+  },
+  "data": {
+    "health": {
+      "description": "Agent HTTP service is healthy",
+      "cameraConnected": true,
+      "mainStream": {
+        "configured": true,
+        "connected": true,
+        "packagesProcessed": 183421,
+        "fps": 29.97,
+        "resolution": {
+          "width": 1920,
+          "height": 1080
+        },
+        "lastPacketAt": 1788710399
+      },
+      "subStream": {
+        "configured": true,
+        "connected": true,
+        "packagesProcessed": 91710,
+        "fps": 15,
+        "resolution": {
+          "width": 640,
+          "height": 360
+        },
+        "lastPacketAt": 1788710399
+      },
+      "hub": {
+        "configured": true,
+        "connected": true,
+        "lastHeartbeatAttemptAt": 1788710398,
+        "lastSuccessfulHeartbeatAt": 1788710398
+      }
+    }
+  }
+}
+```
+
+Stream `packagesProcessed` counts complete encoded video access units processed
+since the Agent process started; it does not count individual fragmented RTP
+packets. `fps` is the latest PTS-derived frame-rate estimate. Resolution is the
+most recently observed encoded width and height. `lastPacketAt`, Hub heartbeat
+timestamps, and response metadata timestamps are Unix seconds; `0` means that
+no value has been observed yet. A stream can be configured but temporarily
+disconnected.
+
+Hub `configured` means heartbeat delivery is enabled and has the required URI
+and key. Hub `connected` means the most recent heartbeat succeeded and the last
+success is no more than three minutes old. A failed heartbeat marks it
+disconnected immediately while retaining the last-success timestamp for
+diagnosis.
+
+New JSON endpoints should use this Hub-compatible response envelope rather than
+adding unrelated top-level response shapes. HTTP status describes the transport
+result, `applicationStatusCode` describes the operation, `entityStatusCode` and
+`message` describe the domain outcome, `metadata` carries request/application
+context, and endpoint-specific content belongs in a typed `data` object. Client
+responses must contain safe messages only; detailed internal errors belong in
+structured logs. Existing endpoints retain their legacy response shapes until
+they are migrated deliberately.
+
+### Secure camera streams (RTSPS)
+
+The Agent accepts `rtsps://` camera URLs. Do not use `srtsp://`; RTSPS is RTSP over TLS. For a Bosch FLEXIDOME micro 3100i, enable **Secure RTSP** under **Network > Network Services** and use port `9554`:
+
+```bash
+AGENT_CAPTURE_IPCAMERA_RTSP='rtsps://username:password@camera.example:9554/?inst=1'
+AGENT_CAPTURE_IPCAMERA_SUB_RTSP='rtsps://username:password@camera.example:9554/?inst=2'
+```
+
+Certificate verification is enabled by default. The URL hostname or IP address must match the camera certificate SAN. On this Bosch firmware, RTSPS presents the certificate assigned to **HTTPS**; there is no separate SRTSP certificate usage. Leave **CBS client** assigned to the Bosch device certificate.
+
+For a private CA, mount a PEM trust bundle containing every CA certificate needed to build the camera certificate chain and set `AGENT_CAPTURE_IPCAMERA_RTSPS_CA_FILE` to its path inside the Agent. The bundle is appended to the system roots for camera RTSPS connections only. This Bosch firmware presents only its leaf certificate, so include both the issuing intermediate and root certificates in the bundle. As a temporary fallback, `AGENT_CAPTURE_IPCAMERA_RTSPS_INSECURE=true` disables certificate verification for camera streams only.
+
+See [RTSPS and TLS certificates](README-RTSPS-TLS.md) for the complete Bosch UI, private-CA, deployment, validation, and troubleshooting procedure.
+
 | Name                                    | Description                                                                                     | Default Value                  |
 | --------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------ |
-| `AGENT_MODE`                            | You can choose to run this in 'release' for production, and or 'demo' for showcasing.           | "release"                      |
-| `AGENT_TLS_INSECURE`                    | Specify if you want to use `InsecureSkipVerify` for the internal HTTP client.                   | "false"                        |
-| `AGENT_USERNAME`                        | The username used to authenticate against the Kerberos Agent login page.                        | "root"                         |
-| `AGENT_PASSWORD`                        | The password used to authenticate against the Kerberos Agent login page.                        | "root"                         |
-| `AGENT_KEY`                             | A unique identifier for your Kerberos Agent, this is auto-generated but can be overriden.       | ""                             |
-| `AGENT_NAME`                            | The agent friendly-name.                                                                        | "agent"                        |
-| `AGENT_TIMEZONE`                        | Timezone which is used for converting time.                                                     | "Africa/Ceuta"                 |
-| `AGENT_REMOVE_AFTER_UPLOAD`             | When enabled, recordings uploaded successfully to a storage will be removed from disk.          | "true"                         |
-| `AGENT_OFFLINE`                         | Makes sure no external connection is made.                                                      | "false"                        |
-| `AGENT_AUTO_CLEAN`                      | Cleans up the recordings directory.                                                             | "true"                         |
-| `AGENT_AUTO_CLEAN_MAX_SIZE`             | If `AUTO_CLEAN` enabled, set the max size of the recordings directory in (MB).                  | "100"                          |
-| `AGENT_TIME`                            | Enable the timetable for Kerberos Agent                                                         | "false"                        |
-| `AGENT_TIMETABLE`                       | A (weekly) time table to specify when to make recordings "start1,end1,start2,end2;start1..      | ""                             |
-| `AGENT_REGION_POLYGON`                  | A single polygon set for motion detection: "x1,y1;x2,y2;x3,y3;...                               | ""                             |
-| `AGENT_CAPTURE_IPCAMERA_RTSP`           | Full-HD RTSP endpoint to the camera you're targetting.                                          | ""                             |
-| `AGENT_CAPTURE_IPCAMERA_SUB_RTSP`       | Sub-stream RTSP endpoint used for livestreaming (WebRTC).                                       | ""                             |
-| `AGENT_CAPTURE_IPCAMERA_ONVIF`          | Mark as a compliant ONVIF device.                                                               | ""                             |
-| `AGENT_CAPTURE_IPCAMERA_ONVIF_XADDR`    | ONVIF endpoint/address running on the camera.                                                   | ""                             |
-| `AGENT_CAPTURE_IPCAMERA_ONVIF_USERNAME` | ONVIF username to authenticate against.                                                         | ""                             |
-| `AGENT_CAPTURE_IPCAMERA_ONVIF_PASSWORD` | ONVIF password to authenticate against.                                                         | ""                             |
-| `AGENT_CAPTURE_MOTION`                  | Toggle for enabling or disabling motion.                                                        | "true"                         |
-| `AGENT_CAPTURE_LIVEVIEW`                | Toggle for enabling or disabling liveview.                                                      | "true"                         |
-| `AGENT_CAPTURE_SNAPSHOTS`               | Toggle for enabling or disabling snapshot generation.                                           | "true"                         |
-| `AGENT_CAPTURE_RECORDING`               | Toggle for enabling making recordings.                                                          | "true"                         |
-| `AGENT_CAPTURE_CONTINUOUS`              | Toggle for enabling continuous "true" or motion "false".                                        | "false"                        |
-| `AGENT_CAPTURE_PRERECORDING`            | If `CONTINUOUS` set to `false`, specify the recording time (seconds) before after motion event. | "10"                           |
-| `AGENT_CAPTURE_POSTRECORDING`           | If `CONTINUOUS` set to `false`, specify the recording time (seconds) after motion event.        | "20"                           |
-| `AGENT_CAPTURE_MAXLENGTH`               | The maximum length of a single recording (seconds).                                             | "30"                           |
-| `AGENT_CAPTURE_PIXEL_CHANGE`            | If `CONTINUOUS` set to `false`, the number of pixel require to change before motion triggers.   | "150"                          |
-| `AGENT_CAPTURE_FRAGMENTED`              | Set the format of the recorded MP4 to fragmented (suitable for HLS).                            | "false"                        |
-| `AGENT_CAPTURE_FRAGMENTED_DURATION`     | If `AGENT_CAPTURE_FRAGMENTED` set to `true`, define the duration (seconds) of a fragment.       | "8"                            |
-| `AGENT_MQTT_URI`                        | A MQTT broker endpoint that is used for bi-directional communication (live view, onvif, etc)    | "tcp://mqtt.kerberos.io:1883"  |
-| `AGENT_MQTT_USERNAME`                   | Username of the MQTT broker.                                                                    | ""                             |
-| `AGENT_MQTT_PASSWORD`                   | Password of the MQTT broker.                                                                    | ""                             |
-| `AGENT_STUN_URI`                        | When using WebRTC, you'll need to provide a STUN server.                                        | "stun:turn.kerberos.io:8443"   |
-| `AGENT_TURN_URI`                        | When using WebRTC, you'll need to provide a TURN server.                                        | "turn:turn.kerberos.io:8443"   |
-| `AGENT_TURN_USERNAME`                   | TURN username used for WebRTC.                                                                  | "username1"                    |
-| `AGENT_TURN_PASSWORD`                   | TURN password used for WebRTC.                                                                  | "password1"                    |
-| `AGENT_CLOUD`                           | Store recordings in Kerberos Hub (s3), Kerberos Vault (kstorage) or Dropbox (dropbox).          | "s3"                           |
-| `AGENT_HUB_URI`                         | The Kerberos Hub API, defaults to our Kerberos Hub SAAS.                                        | "https://api.hub.domain.com"   |
-| `AGENT_HUB_KEY`                         | The access key linked to your account in Kerberos Hub.                                          | ""                             |
-| `AGENT_HUB_PRIVATE_KEY`                 | The secret access key linked to your account in Kerberos Hub.                                   | ""                             |
-| `AGENT_HUB_REGION`                      | The Kerberos Hub region, to which you want to upload.                                           | ""                             |
-| `AGENT_HUB_SITE`                        | The site ID of a site you've created in your Kerberos Hub account.                              | ""                             |
-| `AGENT_KERBEROSVAULT_URI`               | The Kerberos Vault API url.                                                                     | "https://vault.domain.com/api" |
-| `AGENT_KERBEROSVAULT_ACCESS_KEY`        | The access key of a Kerberos Vault account.                                                     | ""                             |
-| `AGENT_KERBEROSVAULT_SECRET_KEY`        | The secret key of a Kerberos Vault account.                                                     | ""                             |
-| `AGENT_KERBEROSVAULT_PROVIDER`          | A Kerberos Vault provider you have created (optional).                                          | ""                             |
-| `AGENT_KERBEROSVAULT_DIRECTORY`         | The directory, in the provider, where the recordings will be stored in.                         | ""                             |
-| `AGENT_DROPBOX_ACCESS_TOKEN`            | The Access Token from your Dropbox app, that is used to leverage the Dropbox SDK.               | ""                             |
-| `AGENT_DROPBOX_DIRECTORY`               | The directory, in the provider, where the recordings will be stored in.                         | ""                             |
+| `LOG_LEVEL`                                 | Level for logging, could be "info", "warning", "debug", "error" or "fatal".                     | "info"                         |
+| `LOG_OUTPUT`                                | Logging output format "json" or "text".                                                         | "text"                         |
+| `AGENT_PORT`                                | HTTP web server port. Overrides `-port`; use a port above 1024 in the hardened image. | "8080" hardened Docker; "80" legacy images/binaries |
+| `AGENT_MODE`                                | You can choose to run this in 'release' for production, and or 'demo' for showcasing.           | "release"                      |
+| `AGENT_TLS_INSECURE`                        | Specify if you want to use `InsecureSkipVerify` for the internal HTTP client.                   | "false"                        |
+| `AGENT_USERNAME`                            | The username used to authenticate against the Kerberos Agent login page.                        | "root"                         |
+| `AGENT_PASSWORD`                            | The password used to authenticate against the Kerberos Agent login page.                        | "root"                         |
+| `AGENT_KEY`                                 | A unique identifier for your Kerberos Agent, this is auto-generated but can be overriden.       | ""                             |
+| `AGENT_NAME`                                | The agent friendly-name.                                                                        | "agent"                        |
+| `AGENT_TIMEZONE`                            | Timezone which is used for converting time.                                                     | "Africa/Ceuta"                 |
+| `AGENT_REMOVE_AFTER_UPLOAD`                 | When enabled, recordings uploaded successfully to a storage will be removed from disk.          | "true"                         |
+| `AGENT_OFFLINE`                             | Makes sure no external connection is made.                                                      | "false"                        |
+| `AGENT_AUTO_CLEAN`                          | Cleans up the recordings directory.                                                             | "true"                         |
+| `AGENT_AUTO_CLEAN_MAX_SIZE`                 | If `AUTO_CLEAN` enabled, cap the recordings directory at this size (in MB). When unset/0, recordings may use the whole disk instead (see `AGENT_AUTO_CLEAN_MIN_FREE_SPACE`). | "100"                          |
+| `AGENT_AUTO_CLEAN_MIN_FREE_SPACE`           | When `AUTO_CLEAN` is enabled and no `MAX_SIZE` is set, keep at least this much free space (in MB) on the recordings disk before deleting the oldest (already-uploaded first) recordings. Defaults to 5% of the disk. | ""                             |
+| `AGENT_TIME`                                | Enable the timetable for Kerberos Agent                                                         | "false"                        |
+| `AGENT_TIMETABLE`                           | A (weekly) time table to specify when to make recordings "start1,end1,start2,end2;start1..      | ""                             |
+| `AGENT_REGION_POLYGON`                      | A single polygon set for motion detection: "x1,y1;x2,y2;x3,y3;...                               | ""                             |
+| `AGENT_CAPTURE_IPCAMERA_RTSP`               | Full-HD RTSP or RTSPS endpoint for the target camera.                                           | ""                             |
+| `AGENT_CAPTURE_IPCAMERA_SUB_RTSP`           | RTSP or RTSPS sub-stream endpoint used for livestreaming (WebRTC).                              | ""                             |
+| `AGENT_CAPTURE_IPCAMERA_RTSPS_CA_FILE`      | PEM CA bundle appended to the system roots for RTSPS camera certificate verification.           | ""                             |
+| `AGENT_CAPTURE_IPCAMERA_RTSPS_INSECURE`     | Disable RTSPS camera certificate verification; use only when a trusted CA cannot be installed.  | "false"                        |
+| `AGENT_CAPTURE_IPCAMERA_BASE_WIDTH`         | Force a specific width resolution for live view processing.                                     | ""                             |
+| `AGENT_CAPTURE_IPCAMERA_BASE_HEIGHT`        | Force a specific height resolution for live view processing.                                    | ""                             |
+| `AGENT_CAPTURE_IPCAMERA_ONVIF`              | Mark as a compliant ONVIF device.                                                               | ""                             |
+| `AGENT_CAPTURE_IPCAMERA_ONVIF_XADDR`        | ONVIF endpoint/address running on the camera.                                                   | ""                             |
+| `AGENT_CAPTURE_IPCAMERA_ONVIF_USERNAME`     | ONVIF username to authenticate against.                                                         | ""                             |
+| `AGENT_CAPTURE_IPCAMERA_ONVIF_PASSWORD`     | ONVIF password to authenticate against.                                                         | ""                             |
+| `AGENT_CAPTURE_IPCAMERA_ONVIF_CHANNEL`      | 1-based channel on multi-channel ONVIF devices (encoders, NVRs) used for PTZ, presets and focus. | "0" (first profile)            |
+| `AGENT_CAPTURE_MOTION`                      | Toggle for enabling or disabling motion.                                                        | "true"                         |
+| `AGENT_CAPTURE_LIVEVIEW`                    | Toggle for enabling or disabling liveview.                                                      | "true"                         |
+| `AGENT_CAPTURE_SNAPSHOTS`                   | Toggle for enabling or disabling snapshot generation.                                           | "true"                         |
+| `AGENT_CAPTURE_RECORDING`                   | Toggle for enabling making recordings.                                                          | "true"                         |
+| `AGENT_CAPTURE_CONTINUOUS`                  | Toggle for enabling continuous "true" or motion "false".                                        | "false"                        |
+| `AGENT_CAPTURE_PRERECORDING`                | If `CONTINUOUS` set to `false`, specify the recording time (seconds) before/after motion event. | "10"                           |
+| `AGENT_CAPTURE_POSTRECORDING`               | If `CONTINUOUS` set to `false`, specify the recording time (seconds) after motion event.        | "20"                           |
+| `AGENT_CAPTURE_MAXLENGTH`                   | The maximum length of a single recording (seconds).                                             | "30"                           |
+| `AGENT_CAPTURE_PIXEL_CHANGE`                | If `CONTINUOUS` set to `false`, the number of pixel require to change before motion triggers.   | "150"                          |
+| `AGENT_CAPTURE_FRAGMENTED`                  | Set the format of the recorded MP4 to fragmented (suitable for HLS).                            | "false"                        |
+| `AGENT_CAPTURE_FRAGMENTED_DURATION`         | If `AGENT_CAPTURE_FRAGMENTED` set to `true`, define the duration (seconds) of a fragment.       | "8"                            |
+| `AGENT_MQTT_URI`                            | MQTT broker endpoint for bi-directional communication. Accepts ActiveMQ `mqtt+ssl://` URLs.     | "tcp://mqtt.kerberos.io:1883"  |
+| `AGENT_MQTT_USERNAME`                       | Username of the MQTT broker.                                                                    | ""                             |
+| `AGENT_MQTT_PASSWORD`                       | Password of the MQTT broker.                                                                    | ""                             |
+| `AGENT_REMOTE_ACCESS_ENABLED`               | Allow encrypted Hub MQTT sessions to stream Agent logs and open an interactive shell. Enable only for trusted deployments. | "false"                        |
+| `AGENT_REALTIME_PROCESSING`                 | If `AGENT_REALTIME_PROCESSING` set to `true`, the agent will send key frames to the topic       | ""                             |
+| `AGENT_REALTIME_PROCESSING_TOPIC`           | The topic to which keyframes will be sent in base64 encoded format.                             | ""                             |
+| `AGENT_STUN_URI`                            | When using WebRTC, you'll need to provide a STUN server.                                        | "stun:turn-fra1.kerberos.io:3478"|
+| `AGENT_FORCE_TURN`                          | Force using a TURN server, by generating relay candidates only.                                 | "false"                        |
+| `AGENT_TURN_URI`                            | When using WebRTC, you'll need to provide a TURN server.                                        | "turn:turn-fra1.kerberos.io:3478"|
+| `AGENT_TURN_USERNAME`                       | TURN username used for WebRTC.                                                                  | "username1"                    |
+| `AGENT_TURN_PASSWORD`                       | TURN password used for WebRTC.                                                                  | "password1"                    |
+| `AGENT_CLOUD`                               | Store recordings in Kerberos Hub (s3), Kerberos Vault (kstorage), or Dropbox (dropbox).         | "s3"                           |
+| `AGENT_HUB_ENCRYPTION`                      | Turning on/off encryption of traffic from your Kerberos Agent to Kerberos Hub.                  | "true"                         |
+| `AGENT_HUB_URI`                             | The Kerberos Hub API, defaults to our Kerberos Hub SAAS.                                        | "https://api.hub.domain.com"   |
+| `AGENT_HUB_KEY`                             | The access key linked to your account in Kerberos Hub.                                          | ""                             |
+| `AGENT_HUB_PRIVATE_KEY`                     | The secret access key linked to your account in Kerberos Hub.                                   | ""                             |
+| `AGENT_HUB_REGION`                          | The Kerberos Hub region, to which you want to upload.                                           | ""                             |
+| `AGENT_HUB_SITE`                            | The site ID of a site you've created in your Kerberos Hub account.                              | ""                             |
+| `AGENT_TUS_CHUNK_SIZE_BYTES`                | Bytes sent in each resumable-upload PATCH. Set to `0` or a negative value to send all remaining bytes in one PATCH. | "8388608" (8 MiB)              |
+| `AGENT_KERBEROSVAULT_URI`                   | The Kerberos Vault API url.                                                                     | "https://vault.domain.com/api" |
+| `AGENT_KERBEROSVAULT_ACCESS_KEY`            | The access key of a Kerberos Vault account.                                                     | ""                             |
+| `AGENT_KERBEROSVAULT_SECRET_KEY`            | The secret key of a Kerberos Vault account.                                                     | ""                             |
+| `AGENT_KERBEROSVAULT_PROVIDER`              | A Kerberos Vault provider you have created (optional).                                          | ""                             |
+| `AGENT_KERBEROSVAULT_DIRECTORY`             | The directory, in the Kerberos vault, where the recordings will be stored.                      | ""                             |
+| `AGENT_KERBEROSVAULT_CUSTOM_HEADERS`        | JSON object of custom upload headers that Vault includes as integration metadata.               | `{"site_id":"site-1"}`         |
+| `AGENT_KERBEROSVAULT_SECONDARY_URI`         | The Kerberos Vault API url.                                                                     | "https://vault.domain.com/api" |
+| `AGENT_KERBEROSVAULT_SECONDARY_ACCESS_KEY`  | The access key of a secondary Kerberos Vault account.                                           | ""                             |
+| `AGENT_KERBEROSVAULT_SECONDARY_SECRET_KEY`  | The secret key of a secondary Kerberos Vault account.                                           | ""                             |
+| `AGENT_KERBEROSVAULT_SECONDARY_PROVIDER`    | A secondary Kerberos Vault provider you have created (optional).                                | ""                             |
+| `AGENT_KERBEROSVAULT_SECONDARY_DIRECTORY`   | The directory, in the secondary Kerberos vault, where the recordings will be stored.            | ""                             |
+| `AGENT_KERBEROSVAULT_SECONDARY_CUSTOM_HEADERS` | JSON object of custom upload headers for the secondary Vault.                                | `{"site_id":"site-1"}`         |
+| `AGENT_DROPBOX_ACCESS_TOKEN`                | The Access Token from your Dropbox app, that is used to leverage the Dropbox SDK.               | ""                             |
+| `AGENT_DROPBOX_DIRECTORY`                   | The directory, in Dropbox, where the recordings will be stored.                                 | ""                             |
+| `AGENT_ENCRYPTION`                          | Enable 'true' or disable 'false' end-to-end encryption for MQTT messages.                       | "false"                        |
+| `AGENT_ENCRYPTION_RECORDINGS`               | Enable 'true' or disable 'false' end-to-end encryption for recordings.                          | "false"                        |
+| `AGENT_ENCRYPTION_FINGERPRINT`              | The fingerprint of the keypair (public/private keys), so you know which one to use.             | ""                             |
+| `AGENT_ENCRYPTION_PRIVATE_KEY`              | The private key (assymetric/RSA) to decrypt and sign requests send over MQTT.                   | ""                             |
+| `AGENT_ENCRYPTION_SYMMETRIC_KEY`            | The symmetric key (AES) to encrypt and decrypt requests sent over MQTT.                         | ""                             |
+| `AGENT_SIGNING`                             | Enable 'true' or disable 'false' for signing recordings.                                        | "true"                         |
+| `AGENT_SIGNING_PRIVATE_KEY`                 | The private key (RSA) to sign the recordings fingerprint to validate origin.                    | "" - uses default one if empty |
+
+Remote console access is disabled unless `AGENT_REMOTE_ACCESS_ENABLED=true`.
+The Agent also rejects remote session messages unless Hub encryption or
+end-to-end MQTT encryption is configured and used. A remote shell runs inside
+the Agent process environment as the Agent operating-system user; it is not an
+SSH server and does not expose a new network port. Keep the feature disabled on
+deployments where Hub owners should not have operating-system access.
+
+### Resumable upload chunk size
+
+Hub and Vault resumable uploads use `AGENT_TUS_CHUNK_SIZE_BYTES` as the maximum
+body size of each tus `PATCH` request. The value is a number of bytes, not a
+number of chunks. If the variable is unset or invalid, the Agent uses 8 MiB:
+
+```dotenv
+# 8 MiB (default)
+AGENT_TUS_CHUNK_SIZE_BYTES=8388608
+
+# 4 MiB: more frequent checkpoints on unstable connections
+AGENT_TUS_CHUNK_SIZE_BYTES=4194304
+
+# Disable chunking and send all remaining bytes in one PATCH
+AGENT_TUS_CHUNK_SIZE_BYTES=0
+```
+
+Smaller chunks provide more frequent resumable checkpoints but create more HTTP
+requests. Larger chunks reduce request overhead but require more data to be
+retransmitted when a request fails.
+
+An HTTP 500 during resumable creation is a server/provider failure, not proof
+that the recording filename is invalid. Creation errors include up to 4 KiB of
+the server response, and the final retry error retains the latest failure cause.
+Created upload sessions remain usable if only the optional creation response
+body is interrupted; the successful response's `Location` is retained.
+Check the corresponding Hub/Vault logs and storage-provider configuration.
+As a temporary diagnostic workaround, set `AGENT_DISABLE_RESUMABLE_UPLOAD=true`
+and restart Agent to use ordinary uploads. This does not change the recording
+filename or remove its structured metadata, but interrupted uploads restart
+from the beginning. Remove the override after fixing the provider issue.
+
+### Custom metadata headers for Kerberos Vault
+
+Use `AGENT_KERBEROSVAULT_CUSTOM_HEADERS` to attach your own metadata (for
+example a site, line, or equipment identifier) to every recording uploaded to
+Kerberos Vault. The value is a JSON object whose keys are header names and whose
+values are strings. The Agent sends these as HTTP headers on every upload, and
+Vault adds them to the `metadata` object of its integration messages (Kafka,
+MQTT, SQS, RabbitMQ, etc.):
+
+```json
+{
+  "timestamp": "2026-09-24T15:06:45Z",
+  "key": "agent1/1790262405_3-425_agent1_0-0-0-0_-1_10000.mp4",
+  "device": "agent1",
+  "metadata": {
+    "site_id": "site-1",
+    "line_id": "line-2",
+    "equipment_id": "equipment-3"
+  }
+}
+```
+
+The value must be valid JSON on a single line, so wrap it in single quotes in a
+shell:
+
+```bash
+docker run -p 80:8080 --name mycamera \
+  -e AGENT_CLOUD=kstorage \
+  -e AGENT_KERBEROSVAULT_URI=https://vault.domain.com/api \
+  -e AGENT_KERBEROSVAULT_ACCESS_KEY=xxx \
+  -e AGENT_KERBEROSVAULT_SECRET_KEY=xxx \
+  -e AGENT_KERBEROSVAULT_DIRECTORY=agent1 \
+  -e AGENT_KERBEROSVAULT_CUSTOM_HEADERS='{"site_id":"site-1","line_id":"line-2","equipment_id":"equipment-3"}' \
+  -d --restart=always kerberos/agent:latest
+```
+
+In `docker compose` or an `.env` file:
+
+```yaml
+services:
+  agent:
+    image: kerberos/agent:latest
+    environment:
+      AGENT_CLOUD: kstorage
+      AGENT_KERBEROSVAULT_CUSTOM_HEADERS: '{"site_id":"site-1","line_id":"line-2","equipment_id":"equipment-3"}'
+```
+
+```dotenv
+AGENT_KERBEROSVAULT_CUSTOM_HEADERS={"site_id":"site-1","line_id":"line-2","equipment_id":"equipment-3"}
+```
+
+In Kubernetes, quote the value so YAML keeps it as a string:
+
+```yaml
+env:
+  - name: AGENT_KERBEROSVAULT_CUSTOM_HEADERS
+    value: '{"site_id":"site-1","line_id":"line-2","equipment_id":"equipment-3"}'
+```
+
+Use `AGENT_KERBEROSVAULT_SECONDARY_CUSTOM_HEADERS` for the secondary Vault. In
+ConfigMap deployments you can set shared defaults with the `GLOBAL_` prefix
+(for example `GLOBAL_AGENT_KERBEROSVAULT_CUSTOM_HEADERS`) and override them per
+agent with `AGENT_KERBEROSVAULT_CUSTOM_HEADERS`. You can also set the same JSON
+under **Settings → Persistence → Custom upload headers** in the Agent UI, which
+stores it as `kstorage.custom_headers` in `config.json`.
+
+The rules for this value are:
+
+- It must be a JSON object with string values. Numbers, `null`, arrays, and
+  nested objects are rejected.
+- It can contain up to 32 headers, with names up to 128 characters and values
+  up to 4096 bytes.
+- Header names must be valid HTTP tokens (letters, digits, and ``!#$%&'*+-.^_`|~``).
+  Keys are matched case-insensitively, so `site_id` and `SITE_ID` cannot both
+  be used.
+- Reserved names are rejected: anything starting with `X-Kerberos-`,
+  `Authorization`, `Cookie`, `Host`, `Content-Type`, `Content-Length`,
+  `Trace-Id`, tus protocol headers (`Tus-Resumable`, `Upload-*`), and
+  hop-by-hop headers.
+- Values cannot contain line breaks, tabs, or other control characters.
+
+If the value is invalid, the Agent logs an error and does not upload to that
+Vault until the configuration is fixed. The recording stays queued, so it will
+upload once the value is corrected. Header names reach Vault unchanged, but
+proxies may normalise their casing. If Vault redirects an upload to another
+host, the Agent removes the custom headers and Vault credentials before
+following the redirect.
+
+
+## Encryption
+
+You can encrypt your recordings and outgoing MQTT messages with your own AES and RSA keys by enabling the encryption settings. Once enabled, all your recordings will be encrypted using AES-256-CBC and your symmetric key. You can use the default `openssl` toolchain to decrypt the recordings with your AES key, as following:
+
+    openssl aes-256-cbc -d -md md5 -in encrypted.mp4 -out decrypted.mp4 -k your-key-96ab185xxxxxxxcxxxxxxxx6a59c62e8
+
+Or you can decrypt a folder of recordings, using the Kerberos Agent binary as following:
+
+    go run main.go -action decrypt ./data/recordings your-key-96ab185xxxxxxxcxxxxxxxx6a59c62e8
+
+Or for a single file:
+
+    go run main.go -action decrypt ./data/recordings/video.mp4 your-key-96ab185xxxxxxxcxxxxxxxx6a59c62e8
+
+## H264 vs H265
+
+If we talk about video encoders and decoders (codecs) there are 2 major video codecs on the market: H264 and H265. Taking into account your use case, you might use one over the other. We will provide an (not complete) overview of the advantages and disadvantages of each codec in the field of video surveillance and video analytics. If you would like to know more, you should look for additional resources on the internet (or if you like to read physical items, books still exists nowadays).
+
+- H264 (also known as AVC or MPEG-4 Part 10)
+
+  - Is the most common one and most widely supported for IP cameras.
+  - Supported in the majority of browsers, operating system, and third-party applications.
+  - Can be embedded in commercial and 3rd party applications.
+  - Different levels of compression (high, medium, low, ..)
+  - Better quality / compression ratio, shows less artifacts at medium compression ratios.
+  - Does support technologies such as WebRTC
+
+- H265 (also known as HEVC)
+  - Is not supported on legacy cameras, though becoming rapidly available on "newer" IP cameras.
+  - Might not always be supported due to licensing. For example not supported in browers on a Linux distro.
+  - Requires licensing when embedding in a commercial product (be careful).
+  - Higher levels of compression (50% more than H264).
+  - H265 shows artifacts in motion based environments (which is less with H264).
+  - Recording the same video (resolution, duration and FPS) in H264 and H265 will result in approx 50% the file size.
+  - Not supported in technologies such as WebRTC
+
+Conclusion: depending on the use case you might choose one over the other, and you can use both at the same time. For example you can use H264 (main stream) for livestreaming, and H265 (sub stream) for recording. If you wish to play recordings in a cross-platform and cross-browser environment, you might opt for H264 for better support.
+
+## Security vulnerability reporting
+
+If you found a potential security vulnerability, please use the private channels described in [SECURITY.md](SECURITY.md). Avoid opening public GitHub issues for sensitive findings.
 
 ## Contribute with Codespaces
 
-One of the major blockers for letting you contribute to an Open Source project is to setup your local development machine. Why? Because you might have already some tools and libraries installed that are used for other projects, and the libraries you would need for Kerberos Agent, for example FFmpeg, might require a different version. Welcome to the dependency hell..
+One of the major blockers for letting you contribute to an Open Source project is to set up your local development machine. Why? Because you might already have some tools and libraries installed that are used for other projects, and the libraries you would need for Kerberos Agent, for example FFmpeg, might require a different version. Welcome to dependency hell...
 
-By leveraging codespaces, which the Kerberos Agent repo supports, you will be able to setup the required development environment in a few minutes. By opening the `<> Code` tab on the top of the page, you will be able to create a codespace, [using the Kerberos Devcontainer](https://github.com/kerberos-io/devcontainer) base image. This image requires all the relevant dependencies: FFmpeg, OpenCV, Golang, Node, Yarn, etc.
+By leveraging codespaces, which the Kerberos Agent repo supports, you will be able to set up the required development environment in a few minutes. By opening the `<> Code` tab on the top of the page, you will be able to create a codespace, [using the Kerberos Devcontainer](https://github.com/kerberos-io/devcontainer) base image. This image requires all the relevant dependencies: FFmpeg, OpenCV, Golang, Node, Yarn, etc.
 
 ![Kerberos Agent codespace](assets/img/codespace.png)
 
@@ -259,12 +682,12 @@ On opening of the GitHub Codespace, some dependencies will be installed. Once th
       WS_URL: `${websocketprotocol}//${externalHost}/ws`,
     };
 
-Go and open two terminals one for the `ui` project and one for the `machinery` project.
+Go and open two terminals: one for the `ui` project and one for the `machinery` project.
 
 1.  Terminal A:
 
         cd machinery/
-        go run main.go -action run -port 80
+        go run . -action run -port 80
 
 2.  Terminal B:
 
@@ -275,11 +698,11 @@ Once executed, a popup will show up mentioning `portforwarding`. You should see
 
 ![Codespace make public](./assets/img/codespace-make-public.png)
 
-As mentioned above, copy the hostname of the `machinery` DNS name, and past it in the `ui/src/config.json` file. Once done reload, the `ui` page in your browser, and you should be able to access the login page with the default credentials `root` and `root`.
+As mentioned above, copy the hostname of the `machinery` DNS name, and paste it in the `ui/src/config.json` file. Once done, reload the `ui` page in your browser, and you should be able to access the login page with the default credentials `root` and `root`.
 
 ## Develop and build
 
-Kerberos Agent is divided in two parts a `machinery` and `web`. Both parts live in this repository in their relative folders. For development or running the application on your local machine, you have to run both the `machinery` and the `web` as described below. When running in production everything is shipped as only one artifact, read more about this at [Building for production](#building-for-production).
+The Kerberos Agent is divided in two parts: a `machinery` and `web` part. Both parts live in this repository in their relative folders. For development or running the application on your local machine, you have to run both the `machinery` and the `web` as described below. When running in production everything is shipped as only one artifact, read more about this at [Building for production](#building-for-production).
 
 ### UI
 
@@ -289,31 +712,39 @@ The `web` is a **React** project which is the main entry point for an end user t
     cd ui
     yarn start
 
-This will start a webserver and launches the web app on port `3000`.
+This starts the web app on port `3000`. In development, the UI connects to the
+Agent API on port `8082`. Override that port when needed:
+
+    REACT_APP_AGENT_API_PORT=9090 yarn start
 
 ![login-agent](./assets/img/agent-login.gif)
 
-Once signed in you'll see the dashboard page showing up. After successfull configuration of your agent, you'll should see a live view and possible events recorded to disk.
+Once signed in you'll see the dashboard page. After successfull configuration of your agent, you'll should see a live view and possible events recorded to disk.
 
 ![dashboard-agent](./assets/img/agent-dashboard.png)
 
 ### Machinery
 
-The `machinery` is a **Golang** project which delivers two functions: it acts as the Kerberos Agent which is doing all the heavy lifting with camera processing and other kinds of logic, on the other hand it acts as a webserver (Rest API) that allows communication from the web (React) or any other custom application. The API is documented using `swagger`.
+The `machinery` is a **Golang** project which delivers two functions: it acts as the Kerberos Agent which is doing all the heavy lifting with camera processing and other kinds of logic and on the other hand it acts as a webserver (Rest API) that allows communication from the web (React) or any other custom application. The API is documented using `swagger`.
 
 You can simply run the `machinery` using following commands.
 
     git clone https://github.com/kerberos-io/agent
     cd machinery
-    go run main.go -action run -port 80
+    go run . -action run -port 8082
 
-This will launch the Kerberos Agent and run a webserver on port `80`. You can change the port by your own preference. We strongly support the usage of [Goland](https://www.jetbrains.com/go/) or [Visual Studio Code](https://code.visualstudio.com/), as it comes with all the debugging and linting features builtin.
+This will launch the Kerberos Agent and run a webserver on port `8082`, matching
+the UI development default. You can change the port together with
+`REACT_APP_AGENT_API_PORT`. We strongly support the usage of
+[Goland](https://www.jetbrains.com/go/) or
+[Visual Studio Code](https://code.visualstudio.com/), as it comes with all the
+debugging and linting features built in.
 
 ![VSCode desktop](./assets/img/vscode-desktop.png)
 
 ## Building from source
 
-Running Kerberos Agent in production only require a single binary to run. Nevertheless, we have two parts, the `machinery` and the `web`, we merge them during build time. So this is what happens.
+Running Kerberos Agent in production only requires a single binary to run. Nevertheless, we have two parts: the `machinery` and the `web`, we merge them during build time. So this is what happens.
 
 ### UI
 
@@ -324,7 +755,7 @@ To build the Kerberos Agent web app, you simply have to run the `build` command
 
 ### Machinery
 
-Building the `machinery` is also super easy 🚀, by using `go build` you can create a single binary which ships it all; thank you Golang. After building you will endup with a binary called `main`, this is what contains everything you need to run Kerberos Agent.
+Building the `machinery` is also super easy 🚀, by using `go build` you can create a single binary which ships it all; thank you Golang. After building you will end up with a binary called `main`, this is what contains everything you need to run Kerberos Agent.
 
 Remember the build step of the `web` part, during build time we move the build directory to the `machinery` directory. Inside the `machinery` web server [we reference the](https://github.com/kerberos-io/agent/blob/master/machinery/src/routers/http/Server.go#L44) `build` directory. This makes it possible to just a have single web server that runs it all.
 
@@ -333,13 +764,69 @@ Remember the build step of the `web` part, during build time we move the build d
 
 ## Building for Docker
 
-Inside the root of this `agent` repository, you will find a `Dockerfile`. This file contains the instructions for building and shipping **Kerberos Agent**. Important to note is that start from a prebuild base image, `kerberos/base:xxx`.
-This base image contains already a couple of tools, such as Golang, FFmpeg and OpenCV. We do this for faster compilation times.
+Inside the root of this `agent` repository, you will find a `Dockerfile`. This file contains the instructions for building and shipping a **Kerberos Agent**. It uses Debian Trixie to support the native dependencies used by the Agent, including Media over QUIC.
 
 By running the `docker build` command, you will create the Kerberos Agent Docker image. After building you can simply run the image as a Docker container.
 
     docker build -t kerberos/agent .
 
+### Media over QUIC
+
+The standard AMD64 and ARM64 images include the optional MoQ publisher. Its Rust
+FFI archive requires CGO and glibc 2.38 or newer, which is why the standard image
+uses Debian Trixie. The publisher is disabled unless explicitly enabled at runtime:
+
+    docker run --rm -p 80:8080 \
+      -e AGENT_LIVE_MOQ_ENABLED=true \
+      -e AGENT_LIVE_MOQ_URL=https://relay.uug.ai/anon \
+      kerberos/agent
+
+`AGENT_LIVE_MOQ_BROADCAST_PREFIX` defaults to `devices`. MoQ viewers subscribe to
+a relay and never negotiate with the Agent, so every quality tier is published as
+its own broadcast and switching quality is simply a resubscribe:
+
+| Tier   | Broadcast                             | Source                                     |
+| ------ | ------------------------------------- | ------------------------------------------ |
+| `high` | `devices/<agent-key>/live.hang`       | highest-resolution camera stream           |
+| `low`  | `devices/<agent-key>/live-low.hang`   | sub stream (main stream when none is set)  |
+
+Each tier uploads every frame while it has subscribers. While idle, it continues
+to upload fresh keyframes only. This keeps the relay's latest cached GOP current,
+so a new viewer does not initially render the final frame from the previous
+viewer session, while avoiding the bandwidth cost of continuously sending every
+delta frame. `AGENT_LIVE_MOQ_QUALITY` accepts `high` or `low` to pin the Agent to
+a single tier; viewers requesting the other tier then find no broadcast. Any
+other value (including the default) publishes both. The initial implementation
+publishes H.264 video only.
+
+Two bounded duration settings tune recovery for unusual network conditions:
+
+| Variable | Default | Allowed range |
+| -------- | ------- | ------------- |
+| `AGENT_LIVE_MOQ_MAX_PACKET_AGE` | `1.5s` | `250ms` to `30s` |
+| `AGENT_LIVE_MOQ_WRITE_TIMEOUT` | `5s` | `1s` to `1m` |
+
+Values use Go duration syntax and are clamped to the documented range. The
+dashboard API's `recovery` object reports per-tier reconnects, last successful
+frame/write timing, native write timeouts, watchdog restarts/cooldown, dropped
+run-channel events, and run-worker shutdown timeouts.
+
+The `/anon` relay route is intended for interoperability testing. Production
+deployments must set `AGENT_LIVE_MOQ_URL` to a short-lived, device-scoped
+publisher URL issued by Hub API.
+
+To verify the native SDK in a development container, rebuild the Agent or shared
+monorepo devcontainer so it uses the Trixie base, then run the VS Code task
+`agent: moq verify`. The same check is available from a terminal:
+
+    cd machinery
+    bash ./verify-moq-devcontainer.sh
+
+The check requires glibc 2.38 or newer, runs the tagged package and in-process
+native QUIC lifecycle tests, links the complete Agent with `-tags moq`, and
+executes the resulting binary's version
+command. Both devcontainers also run this check during their post-create setup.
+
 ## What is new?
 
 This repository contains the next generation of Kerberos.io, **Kerberos Agent (v3)**, and is the successor of the machinery and web repositories. A switch in technologies and architecture has been made. This version is still under active development and can be followed on the [develop branch](https://github.com/kerberos-io/agent/tree/develop) and [project overview](https://github.com/kerberos-io/agent/projects/1).
@@ -350,7 +837,7 @@ Read more about this [at the FAQ](#faq) below.
 
 ## Contributors
 
-This project exists thanks to all the people who contribute.
+This project exists thanks to all the people who contribute. Bravo!
 
 <a href="https://github.com/kerberos-io/agent/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=kerberos-io/agent" />

SECURITY.md

@@ -0,0 +1,40 @@
+# Security Policy
+
+## Supported Versions
+
+We only provide security fixes for the latest release series on the `master` branch.
+
+## Reporting a Vulnerability
+
+Please do **not** open a public GitHub issue for potential security vulnerabilities.
+
+Use one of the private channels below:
+
+1. Preferred: GitHub private vulnerability reporting
+   - https://github.com/kerberos-io/agent/security/advisories/new
+2. Fallback: Email
+   - support@kerberos.io
+   - Optional CC: support@uug.ai
+
+Please include:
+
+- A short summary and impact.
+- Reproduction steps or proof of concept.
+- Affected version(s), commit hash, or deployment details.
+- Any proposed mitigation/workaround.
+- Your preferred attribution name.
+
+For faster triage, use this subject format in email:
+
+`[Security][Kerberos Agent] <short title>`
+
+## Response Expectations
+
+- Acknowledgement target: within 3 business days.
+- Triage/update target: within 7 business days after acknowledgement.
+
+If you do not receive a response in time, please resend your report and include your original timestamp.
+
+## Disclosure and Credits
+
+We follow coordinated disclosure. After a fix is available, we will credit reporters unless they prefer to stay anonymous.

build.sh

@@ -1,10 +0,0 @@
-export version=0.0.1
-export name=agent
-
-docker build -t $name .
-
-docker tag $name kerberos/$name:$version
-docker push kerberos/$name:$version
-
-docker tag $name kerberos/$name:latest
-docker push kerberos/$name:latest

deployments/ansible-openshift/README.md

@@ -2,6 +2,17 @@
 
 Kubernetes is great, but you might love OpenShift even more. In this directory you'll find some resources to deploy your Kerberos Agent in an OpenShift cluster using Ansible playbook. We'll review the different tasks of the Ansible playbook step by step; find the complete `playbook.yaml` here.
 
+The playbook's port mapping targets the forthcoming hardened image:
+`containerPort: 8080` and `targetPort: 8080`, with external Service port `80`
+unchanged. Previously published images, including `v3.14.1`, still need the old
+container port 80. Upgrade the image and mapping together and pin its published
+digest. See the [image contract](../docker/README.md#image-contract) for numeric
+UID/GID `999:999`, writable data/cache paths and release blockers. OpenShift SCCs
+may override the UID; provision matching volume permissions and verify your
+cluster's policy rather than granting privileged access. This legacy playbook's
+credential-debugging/certificate-validation settings also require production
+review; the image/port update does not certify the cluster deployment.
+
 ## Variabeles
 
 We'll have a few `variables` in our `playbook.yml` that will help us to setup secure connection with the OpenShift cluster. We need the `cluster_url` and the `username` and `password` of the OpenShift cluster. If you don't know where to find this, you can find this in the OpenShift web ui.

deployments/ansible-openshift/playbook.yml

@@ -111,7 +111,7 @@
                         mountPath: /home/agent/data/cloud
                         subPath: cloud
                     ports:
-                      - containerPort: 80
+                      - containerPort: 8080
                         protocol: TCP
 
     - name: Expose Kerberos Agent
@@ -136,5 +136,5 @@
             ports:
               - name: http
                 port: 80
-                targetPort: 80
+                targetPort: 8080
                 protocol: TCP

deployments/binary/README.md

@@ -9,7 +9,7 @@ Kerberos Agents are now also shipped as static binaries. Within the Docker image
 
 You can run the binary as following on port `8080`:
 
-    main run cameraname 8080
+    main -action=run -port=80
 
 ## Systemd
 
@@ -18,7 +18,7 @@ When running on a Linux OS you might consider to auto-start the Kerberos Agent u
     [Unit]
     Wants=network.target
     [Service]
-    ExecStart=/home/pi/agent/main run camera 80
+    ExecStart=/home/pi/agent/main -action=run -port=80
     WorkingDirectory=/home/pi/agent/
     [Install]
     WantedBy=multi-user.target

deployments/docker/README.md

@@ -4,17 +4,258 @@ The easiest, and let's say most natural, deployment is done [by utilising `docke
 
 ## 1. Running a single container
 
-We are creating Docker images as part of our CI/CD process. You'll find our Docker images on [Docker hub](https://hub.docker.com/r/kerberos/agent). Pick a specific tag of choice, or use latest. Once done run below command, this will open the web interface of your Kerberos agent on port 80.
+We publish production images on [Docker Hub](https://hub.docker.com/r/kerberos/agent).
+The following examples target the forthcoming hardened image, which listens on
+**8080 inside the container**. They preserve host port 80 and the browser URL
+`http://localhost/`:
 
-    docker run -p 80:80 --name mycamera -d kerberos/agent:latest
+    docker run -p 80:8080 --name mycamera -d kerberos/agent:latest
 
-Or for a develop build:
+**Migration:** releases published before this change, including `v3.14.1`, still
+listen on container port 80 and require `-p 80:80`. Do not change their mappings
+until upgrading the image too. The separate `kerberos/agent-dev` image is not
+migrated by this production-image change:
 
     docker run -p 80:80 --name mycamera -d kerberos/agent-dev:latest
 
 Feel free to use another port if your host system already has a workload running on `80`. For example `8082`.
 
-    docker run -p 8082:80 --name mycamera -d kerberos/agent:latest
+    docker run -p 8082:8080 --name mycamera -d kerberos/agent:latest
+
+## Image contract
+
+This contract describes the hardened production Dockerfile, not an already
+published release or a claim of full
+[image-hardening baseline](https://learn.uug.ai/guides/security/image-hardening/)
+compliance. Use a release's actual published multi-platform digest, for example
+`kerberos/agent:<version>@sha256:<digest>`, rather than treating mutable `latest`
+as immutable. No new release digest or signature is asserted by this PR.
+
+| Property | Contract |
+|---|---|
+| Identity | Fixed numeric `USER 999:999`, account `agent`, primary group `kerberosio`; not root and no privilege-changing startup. |
+| Startup | Working directory `/home/agent`; exec-form default command `./main -action run`. Standalone binary CLI defaults remain unchanged. |
+| Inbound HTTP | TCP `8080`, configurable with `AGENT_PORT` (overrides `-port`). Use an unprivileged port. Map host `80:8080`, or Service port `80` to `targetPort: 8080`. Terminate inbound TLS at a trusted proxy; the default listener is HTTP. |
+| Privileges | No bundled setuid/setgid programs or file capabilities. Run with all capabilities dropped and `no-new-privileges`; no `NET_BIND_SERVICE` is required. |
+| Writable application paths | Only `/home/agent/data/` (configuration, recordings, snapshots, cloud, tus checkpoints, capture tests and logs). Binary, UI assets and application home remain root-owned/read-only to UID 999. Demo mode serves its environment without rewriting UI assets. |
+| Temporary state | `/tmp`, `/var/tmp`; user font/media caches under `XDG_CACHE_HOME=/tmp/agent-cache`, owned by `999:999` with mode `0700`. Recreate that directory with these permissions when mounting a fresh tmpfs over `/tmp`. |
+| Health | Exec `/home/agent/main -action healthcheck`; five-second bounded localhost `/health` probe on the resolved port, no proxy/redirects, validates the Agent JSON envelope, exits nonzero on failure. Docker timeout is ten seconds. |
+| Readiness and metrics | `/health` is HTTP liveness, not proof of camera, MQTT or Hub readiness. Camera/Hub details are diagnostic. This image does not add a Prometheus metrics listener. |
+| Certificates/time | Debian CA bundle, OpenSSL configuration and timezone data retained. Mount a prepared CA bundle read-only and use `SSL_CERT_FILE` where appropriate for Go clients; native FFmpeg/OpenSSL clients may require their own CA configuration. Do not disable TLS verification as a substitute. |
+| Secrets | Inject application credentials/keys at runtime using the orchestrator's existing environment/configuration mechanisms. Change default credentials before exposing HTTP. Never build production config, `.env`, private keys or registry credentials into an image. No new generic `*_FILE` interface is provided. |
+| Outbound traffic | Configured RTSP/RTSPS/ONVIF camera endpoints, MQTT, Hub/Vault/storage HTTPS endpoints, DNS and optional telemetry; WebRTC may require configured STUN/TURN and negotiated UDP/TCP connectivity. Apply an allowlist suited to the actual enabled integrations. |
+| Architecture | Native AMD64 and ARM64 build/runtime checks; ARMv7 remains a legacy build target needing its own evidence. ARMv6 is blocked by the default builder manifest; see below. |
+
+### Container permissions and hardening
+
+The final image uses `FROM scratch` with an explicitly assembled Debian/glibc
+runtime rather than the whole Debian filesystem. FFmpeg and its required native
+libraries/plugins remain for camera/media functionality, including AAC-to-PCMU.
+Apt/dpkg executables, account/capability-management tools, curl, and bundled
+setuid/setgid permissions are absent. An application subcommand, not shell/curl,
+implements the healthcheck.
+
+```sh
+docker run --cap-drop=ALL --security-opt=no-new-privileges:true \
+  -p 80:8080 --name mycamera -d kerberos/agent:latest
+```
+
+Do not use `--privileged` for ordinary IP cameras. Local cameras still use the
+separate RTSP sidecar; any device access belongs to that sidecar. Host networking
+remains supported, but without a mapping the Agent is reachable on host port
+`8080`, not 80.
+
+The numeric `USER 999:999` does **not** automatically inherit supplementary video
+membership from `/etc/group`. If a deployment deliberately passes a video device
+to Agent, explicitly add the device's host GID: `--group-add 44` for GID 44,
+Compose `group_add: ["44"]`, or Kubernetes `supplementalGroups: [44]`. The runtime
+retains the `video` group record. Match the actual device permissions; this does
+not grant arbitrary device access or replace the separate local-camera sidecar.
+
+**Pending policy exception:** functional remote terminal sessions require
+`/bin/sh`, PTY devices, terminal data and basic GNU utilities. These remain for
+that feature, not healthchecks or debugging convenience. The user chose to
+preserve the feature, but no policy approver, exception owner or expiry has been
+provided. This is not an approved waiver or full baseline/CIS compliance.
+Baseline-qualified release promotion must remain blocked until the exception is
+formally resolved; do not silently remove the feature or manufacture approval.
+
+Bind mounts must be writable by the image's UID/GID; the container does not
+change host ownership at startup. Before migrating an older volume, check the
+user of the exact old and new image with `docker run --rm --entrypoint id IMAGE`
+and adjust only the mounted directories as necessary. For example:
+
+```sh
+sudo chown -R 999:999 agent/config agent/recordings
+```
+
+A read-only root filesystem is not enabled by default: `data/` needs initialized
+writable storage (and FFmpeg or shell sessions may need `/tmp` and `/var/tmp`).
+Empty bind mounts hide packaged configuration/media files; initialize
+them before use. Docker named volumes populate packaged contents on first use.
+Customers enabling read-only root must supply those writable mounts and cache
+ownership, keep the runtime's device/PTY mounts, and validate their enabled media
+and remote-access features. Apply CPU/memory/PID limits, seccomp/AppArmor and
+network policies appropriate to the deployment.
+
+### Building and checking the image
+
+Build from a clean checkout: the default configuration files under
+`machinery/data/config/` are included in the image, so do not replace them with
+production credentials before building. `.dockerignore` excludes local `.env`
+files, credential directories/configuration, test/profiling outputs, recordings,
+upload checkpoints, dependency directories, and unrelated
+repository files from the build context. The builder uses Go `1.26.10` with
+`GOTOOLCHAIN=local`, checksum database verification, and `go mod verify`. Builds
+use `-mod=readonly` to reject implicit module changes, `-trimpath` to omit local
+source paths, and `-buildvcs=false` to omit checkout metadata. CGO remains enabled
+for the native camera/media dependencies.
+
+Source builds require at least Go 1.26.10, matching the pinned security patch floor.
+The Go, Node, and Debian bases are pinned to verified multi-platform manifest
+digests, including AMD64 and ARM64 (and ARMv7 where previously supported).
+The pinned Debian image is used only to assemble the scratch runtime with
+glibc-compatible FFmpeg, CGO, and MoQ dependencies. Its native package dependency
+metadata selects the architecture's dynamic loader, shared libraries, media
+plugins/drivers, and associated data files. This is intentionally broader than
+an `ldd`-only copy, which misses dynamically loaded plugins. Certificates,
+OpenSSL configuration, time zones, font/MIME/pixbuf caches, account records, and
+standard writable `/tmp` and device mount points are retained. The runtime
+uses `XDG_CACHE_HOME=/tmp/agent-cache` for disposable user caches without making
+the application home writable. It contains package provenance in
+`/var/lib/dpkg/status` and license notices, but
+not the package manager. Update it by rebuilding and replacing the image rather
+than installing packages in a running container.
+
+```sh
+docker build --pull -t kerberos/agent:local .
+sh deployments/docker/test-image.sh kerberos/agent:local
+```
+
+The smoke check uses temporary containers and a Docker volume, cleans them up,
+and checks permissions, FFmpeg audio transcoding, H264/sample-video decoding,
+H265 encoding/decoding, font rendering, shell/PTY devices, volume
+initialization/writes, default and custom HTTP ports, health probes, and
+demo-mode startup with a read-only root and immutable UI assets. It enforces
+privileged low ports while running on 8080 with no capabilities and
+`no-new-privileges`, and also checks an overridden port `8082`. PR builds
+run it on native AMD64 and ARM64 runners. It does not replace testing against a
+real camera, hardware codecs/devices, an MQTT-mediated remote shell session, or
+all supported ARM variants. Review and refresh the
+base-image digests regularly for security updates; `--pull` alone does not update
+a pinned digest. `GO_IMAGE` and `RUNTIME_IMAGE` remain overrideable build arguments
+for compatible alternatives. The package repositories are not snapshot-pinned,
+so base digest pins do not make the entire build bit-for-bit reproducible.
+
+Architecture selections are unchanged by this hardening.
+The pinned `golang:1.26.10-trixie` manifest, like the previous Go 1.25 trixie base,
+has no `linux/arm/v6` variant, so the existing ARMv6 nightly target cannot be
+validated with the default base.
+ARMv6 needs a separately reviewed compatible builder/runtime combination; do
+not assume an ARMv7 image runs on ARMv6 hardware.
+
+### Release evidence, vulnerabilities and lifecycle
+
+The hardened release path must build/test the supported release architectures,
+block HIGH/CRITICAL vulnerability/secret/misconfiguration findings, retain scan
+reports and an SBOM, publish build provenance, and sign the **final
+multi-platform index digest**, not just one child manifest. A pending policy
+exception is not an approved scan exception. There are no approved
+vulnerability exceptions in this change; findings require remediation or a
+reviewed owner/expiry/approval record. Scanner/database failures must fail
+closed. Workflow definitions are not evidence that registry publication,
+signing, or scans have already succeeded.
+
+Source scans cover UI production **and build/development** dependencies and retain
+their application inventory/SBOM, because compiled browser assets hide lockfile
+metadata from final-rootfs scanners. Final-image evidence separately covers native
+packages and the Go binary. Current native-library findings remain release
+blockers. The existing embedded recording-signing key and trust behavior are
+retained under the user's time-limited source-secret exception, recorded for
+review in this PR in
+[image-scan-exceptions.json](../../.github/scripts/image-scan-exceptions.json).
+Owner and approver: `@cedricve`; expiry: **December 5, 2026, 23:59:59 UTC**.
+Anyone possessing this shared private key can forge signatures under its
+identity; the exception accepts that risk temporarily, it does not fix it.
+
+The exception matches only that source file's SHA-256, exact scanner rule,
+category, HIGH severity and line location, and requires exactly one match.
+Changes, missing/incomplete approval, expiry or duplicate findings fail closed.
+It cannot exempt an image finding, another secret, a vulnerability or a
+misconfiguration. The policy is loaded from the executing workflow's checkout,
+not the source directory being scanned. Retained `scan.json` still contains the
+redacted HIGH finding; `exception-policy.json`, `exception-decisions.json` and
+`policy.json` record the approval/application, without key material. Review the
+record in PR #350 before merging; repository owners must enforce required reviews.
+This exception does not approve the separate pending remote-terminal policy.
+
+The build jobs run compilation and production-image smoke tests before the
+security gates. A job that fails at **Source/UI dependency and final image gates
+with SPDX SBOMs** is not a compiler or startup failure; inspect its retained
+reports rather than disabling the gate. Patched Go dependencies are checked
+with `govulncheck` as well as the image/source scanner. The pinned
+`golang.org/x/crypto` revision is the official reviewed OpenPGP module split
+for [GO-2026-5932](https://pkg.go.dev/vuln/GO-2026-5932); Agent does not import the
+retired OpenPGP packages.
+
+Debian 13 stable, security and backports currently provide no patched FFmpeg
+7.1.x or libxml2 packages for the blocking findings on either AMD64 or ARM64.
+For example, Debian defers [CVE-2026-58049](https://security-tracker.debian.org/tracker/CVE-2026-58049)
+until an upstream 7.1.x fix; a fix exists in FFmpeg 9. A Wolfi FFmpeg 7 prototype
+had no vendor-scanner findings but still used the same affected upstream
+7.1.5 code and lacked the existing hardware accelerators. It was **not**
+adopted to obtain a misleading clean scan. A newer media stack needs matched
+CGO headers/libraries and validation of codecs, hardware acceleration and
+supported architectures, not an unreviewed mix of testing-distribution packages.
+The user has chosen to keep the default recording-signing key; no trust
+migration or startup change is implemented. Its source-secret finding becomes
+release-blocking again if the scoped exception expires or no longer matches.
+Any future removal would require a separately
+authorized migration: per-installation keys need verifier/public-key provisioning,
+while requiring an injected key changes startup for existing keyless installations.
+
+Before deploying, obtain the release's digest, source revision, supported
+platforms, per-platform SBOM/scan reports, provenance, signature certificate
+identity and policy approvals from its retained release evidence. Verify the
+signature against the **exact trusted workflow identity** and GitHub OIDC issuer,
+not an unrestricted identity regexp:
+
+Workflow artifacts `image-source-evidence` and `image-final-evidence` retain
+sanitized reports, source/application and per-platform SBOMs, provenance, base
+digests and the source revision for 90 days. Successful releases also attach
+`image-security-evidence.tar.gz`. After successful signing,
+`signing-identity.txt` records the exact
+`https://github.com/kerberos-io/agent/.github/workflows/image-release.yml@...`
+identity; the suffix is the executing workflow ref, not necessarily the source
+ref. Require the expected trusted ref, not merely any identity found in an
+artifact. Secret matches/source excerpts are redacted; findings are not waived.
+
+```sh
+# Set these from the trusted release's real evidence, not from this example.
+cosign verify --certificate-identity="$COSIGN_IDENTITY" \
+  --certificate-oidc-issuer=https://token.actions.githubusercontent.com \
+  "$AGENT_IMAGE"
+```
+
+`AGENT_IMAGE` must contain the immutable registry digest. Reject missing,
+mismatched, expired or unapproved evidence; neither a successful local build nor
+`FROM scratch` certifies the image is vulnerability-free. Registry credentials,
+OIDC permissions and repository release protections must be configured by the
+repository owner; this PR does not invent them or certify those external controls.
+
+Review pinned digests and native/package/module findings for every release and
+regularly between releases. Debian 13 has
+[full support until August 9, 2028 and LTS until June 30, 2030](https://www.debian.org/releases/trixie/),
+with reduced LTS architecture/package coverage. The Go 1.26 line is supported
+[until two newer major Go releases exist](https://go.dev/doc/devel/release#policy);
+update its patch pin and replace it before that boundary. The build-only Node 22
+line has [scheduled EOL April 30, 2027](https://github.com/nodejs/Release/blob/main/schedule.json).
+The pinned UI builder is Node `22.23.4` on Alpine `3.24.3`;
+[Alpine 3.24 main support ends June 1, 2028](https://alpinelinux.org/releases/),
+while community support ends at the next stable release. Track both when
+refreshing that build-only base. Rebuilding does not refresh immutable
+base pins automatically, and APT repositories are not snapshot-pinned. Retain the
+actual installed-package/SBOM evidence per architecture and release.
 
 ### Attach a volume
 
@@ -34,14 +275,14 @@ You attach a volume to your container by leveraging the `-v` option. To mount yo
 
 3.  Run the docker command as following to attach your config directory and recording directory.
 
-        docker run -p 80:80 --name mycamera \
+        docker run -p 80:8080 --name mycamera \
         -v $(pwd)/agent/config:/home/agent/data/config \
-        -v $(pwd)/agent/recordings:/home/agent/data/recordings\
-        -d --restart=alwayskerberos/agent:latest
+        -v $(pwd)/agent/recordings:/home/agent/data/recordings \
+        -d --restart=always kerberos/agent:latest
 
 ### Override with environment variables
 
-Next to attaching the configuration file, it is also possible to override the configuration with environment variables. This makes deployments easier when leveraging `docker compose` or `kubernetes` deployments much easier and scalable. Using this approach we simplify automation through `ansible` and `terraform`. You'll find [the full list of environment variables on the main README.md file](https://github.com/kerberos-io/agent#override-with-environment-variables).
+Next to attaching the configuration file, it is also possible to override the configuration with environment variables. This makes deployments when leveraging `docker compose` or `kubernetes` much easier and more scalable. Using this approach we simplify automation through `ansible` and `terraform`. You'll find [the full list of environment variables on the main README.md file](https://github.com/kerberos-io/agent#override-with-environment-variables).
 
 ### 2. Running multiple containers with Docker compose
 
@@ -52,7 +293,7 @@ You'll find [an example `docker-compose.yaml` file here](https://github.com/kerb
     kerberos-agent2:
         image: "kerberos/agent:latest"
         ports:
-        - "8082:80"
+        - "8082:8080"
         environment:
         - AGENT_NAME=agent2
         - AGENT_CAPTURE_IPCAMERA_RTSP=rtsp://x.x.x.x:554/Streaming/Channels/101

deployments/docker/assemble-rootfs.sh

@@ -0,0 +1,107 @@
+#!/bin/sh
+set -eu
+
+root=/runtime
+mkdir -p "$root/usr/bin" "$root/usr/sbin" "$root/usr/lib" "$root/etc" \
+	"$root/var/lib/dpkg" "$root/dev/pts" "$root/proc" "$root/sys" "$root/run"
+ln -s usr/bin "$root/bin"
+ln -s usr/sbin "$root/sbin"
+ln -s usr/lib "$root/lib"
+if [ -L /lib64 ]; then
+	mkdir -p "$root/usr/lib64"
+	ln -s usr/lib64 "$root/lib64"
+fi
+
+# Package dependencies include dlopen-loaded codecs/drivers and their data, which
+# ldd alone cannot discover. Debian resolves the native architecture's loader too.
+apt-cache depends --recurse --installed --no-recommends --no-suggests \
+	--no-conflicts --no-breaks --no-replaces --no-enhances \
+	ffmpeg libatomic1 libstdc++6 dash coreutils findutils grep sed tzdata ncurses-base \
+	> /tmp/runtime-dependencies
+sed -n '/^[a-z0-9][a-z0-9+.:_-]*$/p' /tmp/runtime-dependencies \
+	| grep -vx debconf | sort -u > /tmp/runtime-candidates
+dpkg-query -W -f='${Package} ${db:Status-Status}\n' > /tmp/package-status
+awk '$2 == "installed" { print $1 }' /tmp/package-status \
+	| sort -u > /tmp/installed-packages
+comm -12 /tmp/runtime-candidates /tmp/installed-packages > /tmp/runtime-packages
+
+set --
+while IFS= read -r package; do
+	set -- "$@" "$package"
+done < /tmp/runtime-packages
+dpkg-query -L "$@" > /tmp/runtime-package-paths
+sort -u /tmp/runtime-package-paths > /tmp/runtime-paths
+while IFS= read -r path; do
+	case "$path" in
+		"") continue ;;
+		/usr/share/doc/*/copyright|/usr/share/common-licenses/*) ;;
+		/usr/share/doc/*|/usr/share/man/*|/usr/share/info/*|/usr/share/locale/*|\
+		/usr/share/lintian/*|/usr/share/bug/*|/usr/share/debconf/*|\
+		/usr/share/bash-completion/*|/usr/share/fish/*|\
+		/usr/lib/systemd/*|/lib/systemd/*|/etc/init.d/*|/etc/cron.*/*) continue ;;
+	esac
+	if [ -d "$path" ] && [ ! -L "$path" ]; then
+		continue
+	fi
+	if [ ! -f "$path" ] && [ ! -L "$path" ]; then
+		printf 'Missing selected runtime file: %s\n' "$path" >&2
+		exit 1
+	fi
+	printf '%s\n' "$path"
+done < /tmp/runtime-paths > /tmp/runtime-files
+tar --create --file /tmp/runtime.tar --no-recursion --files-from /tmp/runtime-files
+tar --extract --file /tmp/runtime.tar --directory "$root"
+
+# Preserve generated trust stores, font configuration/caches and pixbuf loaders.
+cp -a --parents /etc/ssl /usr/lib/ssl /usr/share/ca-certificates /etc/fonts \
+	/var/cache/fontconfig /usr/share/mime /usr/share/common-licenses "$root"
+find /usr/lib -path '*/gdk-pixbuf-2.0/*/loaders.cache' \
+	-exec cp -a --parents {} "$root" \;
+cp -a --parents /etc/nsswitch.conf /etc/gai.conf /etc/localtime \
+	/etc/ld.so.conf /etc/ld.so.conf.d /etc/os-release /etc/debian_version \
+	/usr/lib/os-release /usr/lib/locale "$root"
+
+# Some public SONAME links (BLAS/LAPACK, for example) are generated by Debian
+# alternatives rather than owned by a package. Keep only links to selected files.
+find /usr/lib -type l > /tmp/runtime-links
+if [ -d /usr/lib64 ]; then
+	find /usr/lib64 -type l >> /tmp/runtime-links
+fi
+while IFS= read -r link; do
+	target=$(readlink -f "$link")
+	if [ -e "$root$target" ]; then
+		while [ -L "$link" ]; do
+			cp -a --parents "$link" "$root"
+			target=$(readlink "$link")
+			case "$target" in
+				/*) link=$target ;;
+				*) link=$(dirname "$link")/$target ;;
+			esac
+		done
+	fi
+done < /tmp/runtime-links
+
+getent passwd root agent nobody > "$root/etc/passwd"
+getent group root kerberosio video nogroup > "$root/etc/group"
+mkdir -p "$root/tmp" "$root/var/tmp"
+chmod 1777 "$root/tmp" "$root/var/tmp"
+install -d -m 0700 -o 999 -g 999 "$root/tmp/agent-cache"
+
+# Retain package provenance for scanners without shipping apt/dpkg executables.
+dpkg-query -s "$@" ca-certificates base-files > "$root/var/lib/dpkg/status"
+mkdir -p "$root/usr/share/doc/ca-certificates"
+cp /usr/share/doc/ca-certificates/copyright "$root/usr/share/doc/ca-certificates/"
+ldconfig -r "$root"
+chroot "$root" /usr/bin/fc-cache --force
+find "$root" -type f -perm /6000 -exec chmod a-s {} +
+
+# Execute against the assembled loader/libraries, not the assembly-stage rootfs.
+chroot --userspec=999:999 "$root" /bin/sh -ec '
+	/home/agent/main -action version
+	ffmpeg -version
+	ffprobe -version
+	test -s /etc/ssl/certs/ca-certificates.crt
+	test ! -e /usr/bin/curl
+	test ! -e /usr/bin/apt
+	test ! -e /usr/bin/dpkg
+'

deployments/docker/docker-compose-with-volumes.yaml

@@ -3,7 +3,7 @@ services:
   kerberos-agent1:
     image: "kerberos/agent:latest"
     ports:
-      - "8081:80"
+      - "8081:8080"
     environment:
       - AGENT_NAME=agent1
       # You can still override the configuration with environment variables, but might not makes sense if you are attaching a host config.
@@ -14,14 +14,14 @@ services:
   kerberos-agent2:
     image: "kerberos/agent:latest"
     ports:
-      - "8082:80"
+      - "8082:8080"
     volumes:
       - ./agent2/config:/home/agent/data/config
       - ./agent2/recordings:/home/agent/data/recordings
   kerberos-agent3:
     image: "kerberos/agent:latest"
     ports:
-      - "8083:80"
+      - "8083:8080"
     volumes:
       - ./agent3/config:/home/agent/data/config
       - ./agent3/recordings:/home/agent/data/recordings

deployments/docker/docker-compose.yaml

@@ -1,35 +1,38 @@
 version: "3.9"
+x-common-variables: &common-variables
+  # Add variables here to add them to all agents
+  AGENT_HUB_KEY: "xxxxx" # The access key linked to your account in Kerberos Hub.
+  AGENT_HUB_PRIVATE_KEY: "xxxxx" # The secret access key linked to your account in Kerberos Hub.
+  # find full list of environment variables here: https://github.com/kerberos-io/agent#override-with-environment-variables
 services:
   kerberos-agent1:
     image: "kerberos/agent:latest"
     ports:
-      - "8081:80"
+      - "8081:8080"
     environment:
-      - AGENT_NAME=agent1
-      - AGENT_CAPTURE_IPCAMERA_RTSP=rtsp://x.x.x.x:554/Streaming/Channels/101
-      - AGENT_HUB_KEY=xxx
-      - AGENT_HUB_PRIVATE_KEY=xxx
-      - AGENT_CAPTURE_CONTINUOUS=true
-      - AGENT_CAPTURE_PRERECORDING=10
-      - AGENT_CAPTURE_POSTRECORDING=10
-      - AGENT_CAPTURE_MAXLENGTH=60
-      - AGENT_CAPTURE_PIXEL_CHANGE=150
-      # find full list of environment variables here: https://github.com/kerberos-io/agent#override-with-environment-variables
+      <<: *common-variables
+      AGENT_NAME: agent1
+      AGENT_CAPTURE_IPCAMERA_RTSP: rtsp://username:password@x.x.x.x/Streaming/Channels/101 # Hikvision camera RTSP url example
+      AGENT_KEY: "1"
   kerberos-agent2:
     image: "kerberos/agent:latest"
     ports:
-      - "8082:80"
+      - "8082:8080"
     environment:
-      - AGENT_NAME=agent2
-      - AGENT_CAPTURE_IPCAMERA_RTSP=rtsp://x.x.x.x:554/Streaming/Channels/101
-      - AGENT_HUB_KEY=yyy
-      - AGENT_HUB_PRIVATE_KEY=yyy
+      <<: *common-variables
+      AGENT_NAME: agent2
+      AGENT_CAPTURE_IPCAMERA_RTSP: rtsp://username:password@x.x.x.x/channel1 # Linksys camera RTSP url example
+      AGENT_KEY: "2"
   kerberos-agent3:
     image: "kerberos/agent:latest"
     ports:
-      - "8083:80"
+      - "8083:8080"
     environment:
-      - AGENT_NAME=agent3
-      - AGENT_CAPTURE_IPCAMERA_RTSP=rtsp://x.x.x.x:554/Streaming/Channels/101
-      - AGENT_HUB_KEY=zzz
-      - AGENT_HUB_PRIVATE_KEY=zzz
+      <<: *common-variables
+      AGENT_NAME: agent3
+      AGENT_CAPTURE_IPCAMERA_RTSP: rtsp://username:password@x.x.x.x/cam/realmonitor?channel=1&subtype=1 # Dahua camera RTSP url example
+      AGENT_KEY: "3"
+networks:
+  default:
+    name: cluster-net
+    external: true

deployments/docker/test-image.sh

@@ -0,0 +1,128 @@
+#!/bin/sh
+set -eu
+
+image=${1:?Usage: sh deployments/docker/test-image.sh IMAGE}
+container=
+volume=
+temporary_volume=
+cleanup() {
+	if [ -n "$container" ]; then docker rm -f "$container" >/dev/null; fi
+	if [ -n "$volume" ]; then docker volume rm "$volume" >/dev/null; fi
+	if [ -n "$temporary_volume" ]; then docker volume rm "$temporary_volume" >/dev/null; fi
+}
+trap cleanup EXIT
+trap 'exit 1' HUP INT TERM
+
+docker run --rm --entrypoint /bin/sh "$image" -ec '
+	test "$(id -u)" = 999
+	test "$(id -g)" = 999
+	test ! -w /home/agent
+	test ! -w /home/agent/main
+	test -w /home/agent/data/config
+	test -w /home/agent/data/recordings
+	test -w /home/agent/data/tus
+	test ! -w /home/agent/www
+	test ! -w /home/agent/www/env.js
+	test -z "$(find / -xdev -type f -perm /6000 -print 2>/dev/null)"
+	! command -v setcap
+	! command -v capsh
+	! command -v apt
+	! command -v apt-get
+	! command -v dpkg
+	! command -v curl
+	test -s /var/lib/dpkg/status
+	test -r /etc/os-release
+	test -r /usr/share/terminfo/x/xterm-256color
+	test -s /etc/ssl/certs/ca-certificates.crt
+	test "$(id -Gn)" = "kerberosio"
+	test "$(stat -c %a /tmp)" = 1777
+	test -w "$XDG_CACHE_HOME"
+	test ! -e /home/agent/.env
+	test -z "$(find /home/agent/data/tus -type f -print)"
+	./main -action version
+	ffmpeg -nostdin -v error -f lavfi -i sine=frequency=1000:sample_rate=8000 \
+		-t 0.1 -c:a aac -f adts /tmp/test.aac
+	ffmpeg -nostdin -v error -i /tmp/test.aac -ar 8000 -ac 1 \
+		-c:a pcm_mulaw -f mulaw /tmp/test.pcm
+	test -s /tmp/test.pcm
+	ffprobe -v error -show_entries stream=codec_name data/test-480p.mp4
+	ffmpeg -nostdin -v error -i data/test-480p.mp4 -frames:v 1 -f null -
+	ffmpeg -nostdin -v error -i data/test-480p.mp4 -frames:v 1 \
+		-c:v libx265 -x265-params pools=none:frame-threads=1:log-level=error \
+		-f hevc /tmp/test.hevc
+	ffmpeg -nostdin -v error -i /tmp/test.hevc -frames:v 1 -f null -
+	ffmpeg -nostdin -v error -f lavfi -i color=black:s=64x64 \
+		-vf drawtext=text=scratch:fontcolor=white -frames:v 1 -f null -
+'
+
+# Exercise the same shell and PTY devices used by remote-access sessions.
+docker run --rm -t --entrypoint /bin/sh "$image" -ec '
+	test -t 0
+	test -t 1
+	test -c /dev/ptmx
+	test -d /dev/pts
+	stty size
+	printf "Shell and PTY ready\n"
+'
+docker run --rm --group-add 44 --entrypoint /bin/sh "$image" -ec '
+	test "$(id -Gn)" = "kerberosio video"
+'
+wait_healthy() {
+	attempt=0
+	while [ "$attempt" -lt 60 ]; do
+		status=$(docker inspect --format '{{.State.Health.Status}}' "$container")
+		if [ "$status" = healthy ]; then return; fi
+		if [ "$(docker inspect --format '{{.State.Running}}' "$container")" != true ]; then
+			break
+		fi
+		attempt=$((attempt + 1))
+		sleep 1
+	done
+	docker logs "$container"
+	docker inspect --format '{{json .State.Health}}' "$container"
+	echo "Agent did not become healthy" >&2
+	return 1
+}
+
+# Exercise the unprivileged default port without any capabilities.
+volume=$(docker volume create)
+container=$(docker run -d --cap-drop ALL --security-opt no-new-privileges=true \
+	--sysctl net.ipv4.ip_unprivileged_port_start=1024 \
+	--health-interval=1s --health-start-period=0s \
+	--mount "type=volume,source=$volume,target=/home/agent/data" "$image")
+wait_healthy
+docker exec "$container" sh -ec '
+	test "$AGENT_PORT" = 8080
+	./main -action healthcheck
+	test -r data/config/config.json
+	touch data/config/.permission-test data/recordings/.permission-test data/tus/.permission-test
+	rm data/config/.permission-test data/recordings/.permission-test data/tus/.permission-test
+'
+if docker exec -e AGENT_PORT=65534 "$container" ./main -action healthcheck; then
+	echo "Healthcheck incorrectly succeeded on a port with no Agent" >&2
+	exit 1
+fi
+docker stop --time 10 "$container" >/dev/null
+docker rm "$container" >/dev/null
+container=
+
+# Demo UI selection must work with immutable assets and a read-only root.
+temporary_volume=$(docker volume create)
+container=$(docker run -d --read-only --cap-drop ALL \
+	--security-opt no-new-privileges=true \
+	--sysctl net.ipv4.ip_unprivileged_port_start=1024 \
+	--health-interval=1s --health-start-period=0s \
+	--mount "type=volume,source=$volume,target=/home/agent/data" \
+	--mount "type=volume,source=$temporary_volume,target=/tmp" \
+	-e AGENT_PORT=8082 -e AGENT_MODE=demo \
+	-e http_proxy=http://127.0.0.1:9 -e HTTP_PROXY=http://127.0.0.1:9 \
+	-e no_proxy= -e NO_PROXY= "$image")
+wait_healthy
+docker exec "$container" sh -ec '
+	test -f www/env.js
+	test -f www/env.demo.js
+	test ! -w www
+	ffmpeg -nostdin -v error -f lavfi -i color=black:s=64x64 \
+		-vf drawtext=text=readonly:fontcolor=white -frames:v 1 -f null -
+'
+echo "Scratch image permissions, media, shell/PTY, volume writes, default/custom ports, and demo startup passed."

deployments/kubernetes/README.md

@@ -6,6 +6,27 @@ Kubernetes can help you to build a scalable, flexible and resilient deployment.
 
 We've provided an example deployment `deployment-agent.yml` in this directory, which show case you have to create a deployment (and under the hood a pod), to run a Kerberos Agent workload.
 
+These manifests target the forthcoming hardened image: **containerPort and
+Service targetPort are 8080**, while external Service/Ingress port 80 stays
+unchanged. Pin a published hardened release digest before production use.
+Previously published port-80 images (including `v3.14.1`) require the old
+container/target ports; upgrade the image and mapping together. Host-network
+deployments use host port 8080 without Service port translation.
+
+The examples use UID/GID `999:999`, `fsGroup: 999`, a read-only root filesystem,
+no privilege escalation, all capabilities dropped and runtime-default seccomp.
+A non-root init container copies missing packaged data to the writable volume
+without overwriting existing files and initializes the user cache. Temporary
+storage is ephemeral. The PVC example preserves the existing `config/`,
+`recordings/`, `snapshots/` and `cloud/` directories under the same PVC root,
+mounting that root at `/home/agent/data` to cover all writable data paths.
+Ensure the storage driver honors fsGroup or pre-provision UID/GID permissions.
+If deliberately passing video devices, add their actual GID with
+`supplementalGroups`; ordinary IP cameras do not need that group or devices.
+See the [image contract](../docker/README.md#image-contract), including the pending
+remote-terminal policy exception and release blockers. These examples do not
+assert a running cluster or security-policy approval.
+
 ## Create a Kerberos Agent deployment
 
 It's always a best practices to isolate and structure your workloads in Kubernetes. To achieve this we are utilising the concept of namespaces. For this example we will create a new namespace `demo`.
@@ -61,8 +82,7 @@ Depending on where and how you are hosting the Kubernetes cluster, you may need
           image: kerberos/agent:latest
           volumeMounts:
             - name: kerberos-data
-              mountPath: /home/agent/data/config
-              subPath: config
+              mountPath: /home/agent/data
         ...
 
 ## Expose with Ingress
@@ -76,6 +96,7 @@ In the first example `deployment-agent.yml` we are using a `LoadBalancer` to exp
     type: LoadBalancer
     ports:
         - port: 80
+          targetPort: 8080
     ...
 
 An alternative to `LoadBalancer` is `Ingress`. By leveraging an ingress such as `ingress-nginx` or `traefik` you setup a gateway (single point of contact), through which all communication to your apps (services) will flow.

deployments/kubernetes/deployment-agent-volume.yml

@@ -14,41 +14,56 @@ spec:
       labels:
         app: agent
     spec:
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 999
+        runAsGroup: 999
+        fsGroup: 999
+        seccompProfile:
+          type: RuntimeDefault
       volumes:
         - name: kerberos-data
           persistentVolumeClaim:
             claimName: kerberos-data
+        - name: temporary
+          emptyDir: {}
 
       initContainers:
         - name: download-config
           image: kerberos/agent:latest
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop: ["ALL"]
           volumeMounts:
             - name: kerberos-data
-              mountPath: /home/agent/data/config
-              subPath: config
-          command:
-            [
-              "cp",
-              "/home/agent/data/config.template.json",
-              "/home/agent/data/config/config.json",
-            ]
+              mountPath: /runtime-data
+            - name: temporary
+              mountPath: /runtime-tmp
+          command: ["/bin/sh", "-ec", "cp -R --update=none /home/agent/data/. /runtime-data/; install -d -m 0700 /runtime-tmp/agent-cache"]
 
       containers:
         - name: agent
           image: kerberos/agent:latest
+          livenessProbe:
+            exec:
+              command: ["/home/agent/main", "-action", "healthcheck"]
+            initialDelaySeconds: 10
+            periodSeconds: 10
+            timeoutSeconds: 10
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop: ["ALL"]
           volumeMounts:
             - name: kerberos-data
-              mountPath: /home/agent/data/config
-              subPath: config
-            - name: kerberos-data
-              mountPath: /home/agent/data/recordings
-              subPath: recordings
-            - name: kerberos-data
-              mountPath: /home/agent/data/snapshots
-              subPath: snapshots
-            - name: kerberos-data
-              mountPath: /home/agent/data/cloud
-              subPath: cloud
+              mountPath: /home/agent/data
+            - name: temporary
+              mountPath: /tmp
+            - name: temporary
+              mountPath: /var/tmp
           ports:
-            - containerPort: 80
+            - containerPort: 8080
               protocol: TCP

deployments/kubernetes/deployment-agent-with-ingress.yml

@@ -14,11 +14,55 @@ spec:
       labels:
         app: agent
     spec:
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 999
+        runAsGroup: 999
+        fsGroup: 999
+        seccompProfile:
+          type: RuntimeDefault
+      volumes:
+        - name: data
+          emptyDir: {}
+        - name: temporary
+          emptyDir: {}
+      initContainers:
+        - name: initialize-data
+          image: kerberos/agent:latest
+          command: ["/bin/sh", "-ec", "cp -R --update=none /home/agent/data/. /runtime-data/; install -d -m 0700 /runtime-tmp/agent-cache"]
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop: ["ALL"]
+          volumeMounts:
+            - name: data
+              mountPath: /runtime-data
+            - name: temporary
+              mountPath: /runtime-tmp
       containers:
         - name: agent
           image: kerberos/agent:latest
+          livenessProbe:
+            exec:
+              command: ["/home/agent/main", "-action", "healthcheck"]
+            initialDelaySeconds: 10
+            periodSeconds: 10
+            timeoutSeconds: 10
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop: ["ALL"]
+          volumeMounts:
+            - name: data
+              mountPath: /home/agent/data
+            - name: temporary
+              mountPath: /tmp
+            - name: temporary
+              mountPath: /var/tmp
           ports:
-            - containerPort: 80
+            - containerPort: 8080
               protocol: TCP
           resources:
             limits:
@@ -48,7 +92,7 @@ spec:
   #type: LoadBalancer
   ports:
     - port: 80
-      targetPort: 80
+      targetPort: 8080
   selector:
     app: agent
 ---

deployments/kubernetes/deployment-agent.yml

@@ -14,11 +14,55 @@ spec:
       labels:
         app: agent
     spec:
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 999
+        runAsGroup: 999
+        fsGroup: 999
+        seccompProfile:
+          type: RuntimeDefault
+      volumes:
+        - name: data
+          emptyDir: {}
+        - name: temporary
+          emptyDir: {}
+      initContainers:
+        - name: initialize-data
+          image: kerberos/agent:latest
+          command: ["/bin/sh", "-ec", "cp -R --update=none /home/agent/data/. /runtime-data/; install -d -m 0700 /runtime-tmp/agent-cache"]
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop: ["ALL"]
+          volumeMounts:
+            - name: data
+              mountPath: /runtime-data
+            - name: temporary
+              mountPath: /runtime-tmp
       containers:
         - name: agent
           image: kerberos/agent:latest
+          livenessProbe:
+            exec:
+              command: ["/home/agent/main", "-action", "healthcheck"]
+            initialDelaySeconds: 10
+            periodSeconds: 10
+            timeoutSeconds: 10
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop: ["ALL"]
+          volumeMounts:
+            - name: data
+              mountPath: /home/agent/data
+            - name: temporary
+              mountPath: /tmp
+            - name: temporary
+              mountPath: /var/tmp
           ports:
-            - containerPort: 80
+            - containerPort: 8080
               protocol: TCP
           resources:
             limits:
@@ -48,6 +92,6 @@ spec:
   type: LoadBalancer
   ports:
     - port: 80
-      targetPort: 80
+      targetPort: 8080
   selector:
-    app: agent
+    app: agent

deployments/terraform/README.md

@@ -4,6 +4,13 @@ If you are using Terraform as part of your DevOps stack, you might utilise it to
 
 For this example we will install Kerberos Agent using `docker` on a remote `linux` machine. Therefore we'll make sure we have the `TelkomIndonesia/linux` provider initialised.
 
+The example targets the forthcoming hardened image and maps the configured host
+port (80 by default) to **container port 8080**. Pin a published hardened release
+digest before deployment. Older releases, including `v3.14.1`, still require
+container port 80; change the image and mapping together. See the
+[image contract](../docker/README.md#image-contract) for runtime permissions,
+writable paths and release-policy limitations.
+
      terraform init
 
 Once initialised you should see similar output:

deployments/terraform/docker.tf

@@ -34,9 +34,9 @@ resource "linux_script" "install_docker" {
 
 resource "linux_script" "install_docker_kerberos_agent" {
     lifecycle_commands {
-        create = "docker pull $IMAGE:$VERSION && docker run -d -p $PORT:80 --name agent $IMAGE:$VERSION"
+        create = "docker pull $IMAGE:$VERSION && docker run -d -p $PORT:8080 --name agent $IMAGE:$VERSION"
         read = "docker inspect agent"
-        update = "docker pull $IMAGE:$VERSION && docker rm agent --force && docker run -d -p $PORT:80 --name agent $IMAGE:$VERSION"
+        update = "docker pull $IMAGE:$VERSION && docker rm agent --force && docker run -d -p $PORT:8080 --name agent $IMAGE:$VERSION"
         delete = "docker rm agent --force"
     }
     environment = {

machinery/.env

@@ -0,0 +1,38 @@
+AGENT_NAME=camera-name
+AGENT_KEY=uniq-camera-id
+AGENT_TIMEZONE=Europe/Brussels
+#AGENT_CAPTURE_CONTINUOUS=true
+#AGENT_CAPTURE_IPCAMERA_RTSP=rtsp://fake.kerberos.io/stream
+#AGENT_CAPTURE_IPCAMERA_SUB_RTSP=rtsp://fake.kerberos.io/stream
+AGENT_CAPTURE_IPCAMERA_ONVIF_XADDR=x.x.x.x
+AGENT_CAPTURE_IPCAMERA_ONVIF_USERNAME=xxx
+AGENT_CAPTURE_IPCAMERA_ONVIF_PASSWORD=xxx
+AGENT_HUB_URI=https://api.cloud.kerberos.io
+AGENT_HUB_KEY=AKIXxxx4JBEI
+AGENT_HUB_PRIVATE_KEY=DIOXxxxAlYpaxxxxXioL0txxx
+AGENT_HUB_SITE=681xxxxxxx9bcda5
+
+# By default will send to Hub (=S3), if you wish to send to Kerberos Vault, set to "kstorage"
+AGENT_CLOUD=s3
+AGENT_KERBEROSVAULT_URI=
+AGENT_KERBEROSVAULT_PROVIDER=
+AGENT_KERBEROSVAULT_DIRECTORY=
+AGENT_KERBEROSVAULT_ACCESS_KEY=
+AGENT_KERBEROSVAULT_SECRET_KEY=
+AGENT_KERBEROSVAULT_MAX_RETRIES=10
+AGENT_KERBEROSVAULT_TIMEOUT=120
+AGENT_KERBEROSVAULT_SECONDARY_URI=
+AGENT_KERBEROSVAULT_SECONDARY_PROVIDER=
+AGENT_KERBEROSVAULT_SECONDARY_DIRECTORY=
+AGENT_KERBEROSVAULT_SECONDARY_ACCESS_KEY=
+AGENT_KERBEROSVAULT_SECONDARY_SECRET_KEY=
+
+# Resumable (tus) uploads to Kerberos Vault are enabled by default.
+# Set to true to fall back to the legacy single-shot POST /storage upload.
+#AGENT_DISABLE_RESUMABLE_UPLOAD=true
+# Bytes sent per PATCH request (default 1 MiB = 1048576). 0 disables chunking
+# and sends the whole file in a single PATCH.
+AGENT_TUS_CHUNK_SIZE_BYTES=1048576
+
+# Open telemetry tracing endpoint
+OTEL_EXPORTER_OTLP_ENDPOINT=

machinery/.vscode/launch.json

@@ -1,18 +0,0 @@
-{
-    // Use IntelliSense to learn about possible attributes.
-    // Hover to view descriptions of existing attributes.
-    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
-    "version": "0.2.0",
-    "configurations": [
-        {
-            "name": "Launch Package",
-            "type": "go",
-            "request": "launch",
-            "mode": "auto",
-            "program": "main.go",
-            "args": ["-action", "run"],
-            "envFile": "${workspaceFolder}/.env",
-            "buildFlags": "--tags dynamic",
-        },
-    ]
-}

machinery/README.md

@@ -5,7 +5,6 @@
 <a target="_blank" href="https://twitter.com/kerberosio?ref_src=twsrc%5Etfw"><img src="https://img.shields.io/twitter/url.svg?label=Follow%20%40kerberosio&style=social&url=https%3A%2F%2Ftwitter.com%2Fkerberosio" alt="Twitter Widget"></a>
 <a target="_blank" href="https://join.slack.com/t/kerberosio/shared_invite/zt-1a5oj4pwm-O4qCAN9c5r2um0Ns0ge8ww"><img src="https://img.shields.io/badge/slack-@kerberosio-yellow.svg?logo=slack " alt="Kerberos.io"></a>
 
-<a target="_blank" href="https://circleci.com/gh/kerberos-io/agent"><img src="https://circleci.com/gh/kerberos-io/agent.svg?style=svg"/></a>
 <img src="https://github.com/kerberos-io/agent/workflows/Go/badge.svg"/>
 <img src="https://github.com/kerberos-io/agent/workflows/CodeQL/badge.svg"/>
 
@@ -22,4 +21,8 @@ https://brianmacdonald.github.io/Ethonate/address#0xf4a759C9436E2280Ea9cdd23d314
 
 [**Docker Hub**](https://hub.docker.com/r/kerberos/agent) | [**Documentation**](https://doc.kerberos.io) | [**Website**](https://kerberos.io)
 
-Kerberos Open source (v3) is a cutting edge video surveillance management system made available as Open Source under the MIT License. This means that all the source code is available for you or your company, and you can use, transform and distribute the source code; as long you keep a reference of the original license. Kerberos Open Source (v3) can be used for commercial usage (which was not the case for v2). Read more [about the license here](LICENSE).
+Kerberos Open source (v3) is a cutting edge video surveillance management system made available as Open Source under the MIT License. This means that all the source code is available for you or your company, and you can use, transform and distribute the source code; as long you keep a reference of the original license. Kerberos Open Source (v3) can be used for commercial usage (which was not the case for v2). Read more [about the license here](LICENSE).
+
+## Security reporting
+
+For sensitive vulnerabilities, use private disclosure channels documented in [../SECURITY.md](../SECURITY.md).

machinery/cmd/mp4analyze/main.go

@@ -0,0 +1,636 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+	"os"
+	"sort"
+
+	"github.com/Eyevinn/mp4ff/avc"
+	mp4ff "github.com/Eyevinn/mp4ff/mp4"
+)
+
+func main() {
+	fromFlag := flag.Int64("from", -1, "start of the detailed inspection window (track timescale units); default auto-detects the largest keyframe gap")
+	toFlag := flag.Int64("to", -1, "end of the detailed inspection window (track timescale units); default auto-detected")
+	flag.Parse()
+	if flag.NArg() < 1 {
+		fmt.Println("usage: mp4analyze [-from N] [-to N] <file.mp4>")
+		os.Exit(1)
+	}
+	f, err := os.Open(flag.Arg(0))
+	if err != nil {
+		panic(err)
+	}
+	defer f.Close()
+	parsed, err := mp4ff.DecodeFile(f)
+	if err != nil {
+		panic(err)
+	}
+
+	// Movie-level info
+	if parsed.Init != nil && parsed.Init.Moov != nil {
+		moov := parsed.Init.Moov
+		fmt.Printf("ftyp/moov present. timescale(mvhd)=%d duration(mvhd)=%d\n",
+			moov.Mvhd.Timescale, moov.Mvhd.Duration)
+		for _, trak := range moov.Traks {
+			ts := trak.Mdia.Mdhd.Timescale
+			fmt.Printf("  trak id=%d handler=%s mdhd.timescale=%d mdhd.duration=%d\n",
+				trak.Tkhd.TrackID, trak.Mdia.Hdlr.HandlerType, ts, trak.Mdia.Mdhd.Duration)
+		}
+	} else {
+		fmt.Println("no Init/Moov (pure fragmented stream?)")
+	}
+
+	// sidx vs actual segment layout. MSE players use sidx to map presentation
+	// time -> byte ranges; if sidx references disagree with the real segment
+	// sizes/durations (e.g. after an early/short flush) the player fetches the
+	// wrong bytes and fails to decode — a failure that "heals" on seek.
+	fmt.Println("=== sidx references vs actual segments ===")
+	var sidxRefs []mp4ff.SidxRef
+	for _, c := range parsed.Children {
+		if s, ok := c.(*mp4ff.SidxBox); ok {
+			fmt.Printf("  sidx: timescale=%d earliestPresTime=%d firstOffset=%d refCount=%d anchor(after sidx)=%d\n",
+				s.Timescale, s.EarliestPresentationTime, s.FirstOffset, len(s.SidxRefs), s.AnchorPoint)
+			sidxRefs = s.SidxRefs
+		}
+	}
+	// Actual segment sizes (styp+moof+mdat) and fragment durations.
+	type segInfo struct {
+		size uint64
+		dur  uint64
+	}
+	var actual []segInfo
+	for _, seg := range parsed.Segments {
+		var sz uint64
+		if seg.Styp != nil {
+			sz += seg.Styp.Size()
+		}
+		if seg.Sidx != nil {
+			sz += seg.Sidx.Size()
+		}
+		var dur uint64
+		for _, fr := range seg.Fragments {
+			sz += fr.Moof.Size()
+			if fr.Mdat != nil {
+				sz += fr.Mdat.Size()
+			}
+			for _, traf := range fr.Moof.Trafs {
+				if traf.Tfhd.TrackID != 1 {
+					continue
+				}
+				for _, trun := range traf.Truns {
+					for _, s := range trun.Samples {
+						dur += uint64(s.Dur)
+					}
+				}
+			}
+		}
+		actual = append(actual, segInfo{size: sz, dur: dur})
+	}
+	for i := range actual {
+		refStr := "(no sidx ref)"
+		if i < len(sidxRefs) {
+			r := sidxRefs[i]
+			mark := ""
+			if uint64(r.ReferencedSize) != actual[i].size {
+				mark += fmt.Sprintf(" SIZE MISMATCH actual=%d", actual[i].size)
+			}
+			if uint64(r.SubSegmentDuration) != actual[i].dur {
+				mark += fmt.Sprintf(" DUR MISMATCH actual=%d", actual[i].dur)
+			}
+			refStr = fmt.Sprintf("sidx.size=%d sidx.dur=%d type=%d sap=%d/%d%s",
+				r.ReferencedSize, r.SubSegmentDuration, r.ReferenceType, r.StartsWithSAP, r.SAPType, mark)
+		}
+		fmt.Printf("  seg%02d actual.size=%d actual.dur=%d | %s\n", i, actual[i].size, actual[i].dur, refStr)
+	}
+
+	fmt.Println("=== fragments ===")
+	fragIdx := 0
+	var allKeyGlobal []uint64 // global keyframe decode times (track timescale units)
+	var prevTfdtEnd = map[uint32]uint64{}
+	for si, seg := range parsed.Segments {
+		for _, fr := range seg.Fragments {
+			for _, traf := range fr.Moof.Trafs {
+				tid := traf.Tfhd.TrackID
+				tfdt := traf.Tfdt.BaseMediaDecodeTime()
+				offset := uint64(0)
+				var keys []uint64 // keyframe offset-from-tfdt
+				var durs []uint64
+				zeroDur := 0
+				nSamples := 0
+				for _, trun := range traf.Truns {
+					for _, s := range trun.Samples {
+						nSamples++
+						if (s.Flags>>24)&0x03 == 0x02 { // sample_depends_on==2 => IDR/sync
+							keys = append(keys, offset)
+							if tid == 1 {
+								allKeyGlobal = append(allKeyGlobal, tfdt+offset)
+							}
+						}
+						if s.Dur == 0 {
+							zeroDur++
+						}
+						durs = append(durs, uint64(s.Dur))
+						offset += uint64(s.Dur)
+					}
+				}
+				cont := ""
+				if pe, ok := prevTfdtEnd[tid]; ok {
+					if tfdt != pe {
+						cont = fmt.Sprintf(" <-- tfdt GAP/JUMP prev_end=%d delta=%d", pe, int64(tfdt)-int64(pe))
+					}
+				}
+				prevTfdtEnd[tid] = tfdt + offset
+				if tid == 1 {
+					// in-fragment keyframe gaps
+					var gaps []int64
+					for i := 1; i < len(keys); i++ {
+						gaps = append(gaps, int64(keys[i])-int64(keys[i-1]))
+					}
+					fmt.Printf("seg%d frag%d trk%d tfdt=%d dur=%d nSamp=%d zeroDur=%d keys=%v inFragKeyGaps=%v%s\n",
+						si, fragIdx, tid, tfdt, offset, nSamples, zeroDur, keys, gaps, cont)
+				}
+			}
+			fragIdx++
+		}
+	}
+
+	fmt.Println("=== global video keyframe decode times & gaps ===")
+	for i, k := range allKeyGlobal {
+		gap := int64(0)
+		if i > 0 {
+			gap = int64(k) - int64(allKeyGlobal[i-1])
+		}
+		seam := ""
+		if i > 1 {
+			prevGap := int64(allKeyGlobal[i-1]) - int64(allKeyGlobal[i-2])
+			if gap > 0 && prevGap > 0 && gap*2 < prevGap {
+				seam = fmt.Sprintf("  <== SEAM? gap=%d < prevGap/2=%d", gap, prevGap/2)
+			}
+		}
+		fmt.Printf("  kf#%02d dt=%d gap=%d%s\n", i, k, gap, seam)
+	}
+
+	// Choose the detailed-inspection window. By default centre it on the largest
+	// keyframe gap (the most likely artifact location); -from/-to override.
+	winLo, winHi := inspectWindow(allKeyGlobal, *fromFlag, *toFlag)
+	fmt.Printf("=== detailed inspection window: dts %d..%d ===\n", winLo, winHi)
+
+	// Full sample timeline: DTS, CTS (=DTS+cto), composition offset, NAL types,
+	// to detect PTS non-monotonicity / gaps / param-set changes at the seam.
+	fmt.Println("=== per-sample timeline (full) — checking PTS monotonicity & nal types ===")
+	var trex *mp4ff.TrexBox
+	if parsed.Init != nil && parsed.Init.Moov != nil && parsed.Init.Moov.Mvex != nil {
+		for _, t := range parsed.Init.Moov.Mvex.Trexs {
+			if t.TrackID == 1 {
+				trex = t
+			}
+		}
+	}
+	var lastCTS int64 = -1
+	var lastDTS int64 = -1
+	sampIdx := 0
+	fragIdx = 0
+	for _, seg := range parsed.Segments {
+		for _, fr := range seg.Fragments {
+			fs, err := fr.GetFullSamples(trex)
+			if err != nil {
+				fmt.Printf("  frag%d GetFullSamples err: %v\n", fragIdx, err)
+				fragIdx++
+				continue
+			}
+			for _, s := range fs {
+				dts := int64(s.DecodeTime)
+				cts := dts + int64(s.CompositionTimeOffset)
+				nals := nalTypes(s.Data)
+				anomaly := ""
+				if lastCTS >= 0 && cts < lastCTS {
+					anomaly += fmt.Sprintf(" <== CTS BACKWARDS (prev=%d)", lastCTS)
+				}
+				if lastDTS >= 0 && dts < lastDTS {
+					anomaly += fmt.Sprintf(" <== DTS BACKWARDS (prev=%d)", lastDTS)
+				}
+				// sample_is_non_sync_sample is bit 16 (0x00010000); a sync sample
+				// has it clear and sample_depends_on==2 (i.e. an I-frame).
+				isSync := s.Flags&0x00010000 == 0 && (s.Flags>>24)&0x03 == 0x02
+				// Only print inside the inspection window and any anomalies, to keep output small.
+				near := dts >= winLo && dts <= winHi
+				if near || anomaly != "" {
+					fmt.Printf("  s%04d frag%d dts=%d cts=%d cto=%d dur=%d size=%d sync=%v nal=%v%s\n",
+						sampIdx, fragIdx, dts, cts, s.CompositionTimeOffset, s.Dur, len(s.Data), isSync, nals, anomaly)
+				}
+				lastCTS = cts
+				lastDTS = dts
+				sampIdx++
+			}
+			fragIdx++
+		}
+	}
+
+	// Compare parameter sets: avcC (in moov) vs inline SPS/PPS at every IDR.
+	// A looping source that restarts may re-emit SPS/PPS that differ from the
+	// ones the player configured its decoder with from avcC — a classic cause
+	// of a freeze that "heals" when you seek past the seam.
+	fmt.Println("=== parameter set comparison (avcC vs inline IDR) ===")
+	var avccSPS, avccPPS [][]byte
+	if parsed.Init != nil && parsed.Init.Moov != nil {
+		for _, trak := range parsed.Init.Moov.Traks {
+			if trak.Mdia == nil || trak.Mdia.Minf == nil || trak.Mdia.Minf.Stbl == nil {
+				continue
+			}
+			stsd := trak.Mdia.Minf.Stbl.Stsd
+			if stsd == nil || stsd.AvcX == nil || stsd.AvcX.AvcC == nil {
+				continue
+			}
+			avccSPS = stsd.AvcX.AvcC.SPSnalus
+			avccPPS = stsd.AvcX.AvcC.PPSnalus
+		}
+	}
+	for i, s := range avccSPS {
+		fmt.Printf("  avcC SPS[%d] = %x\n", i, s)
+	}
+	for i, p := range avccPPS {
+		fmt.Printf("  avcC PPS[%d] = %x\n", i, p)
+	}
+	fragIdx = 0
+	sampIdx = 0
+	var baseSPS, basePPS []byte
+	if len(avccSPS) > 0 {
+		baseSPS = avccSPS[0]
+	}
+	if len(avccPPS) > 0 {
+		basePPS = avccPPS[0]
+	}
+	for _, seg := range parsed.Segments {
+		for _, fr := range seg.Fragments {
+			fs, err := fr.GetFullSamples(trex)
+			if err != nil {
+				fragIdx++
+				continue
+			}
+			for _, s := range fs {
+				spsList := nalsByType(s.Data, 7)
+				ppsList := nalsByType(s.Data, 8)
+				if len(spsList) > 0 || len(ppsList) > 0 {
+					dts := int64(s.DecodeTime)
+					note := ""
+					if len(spsList) > 0 {
+						if baseSPS == nil {
+							baseSPS = spsList[0]
+						} else if !bytesEqual(baseSPS, spsList[0]) {
+							note += " <== SPS CHANGED vs base/avcC"
+						}
+					}
+					if len(ppsList) > 0 {
+						if basePPS == nil {
+							basePPS = ppsList[0]
+						} else if !bytesEqual(basePPS, ppsList[0]) {
+							note += " <== PPS CHANGED vs base/avcC"
+						}
+					}
+					var spsHex, ppsHex string
+					if len(spsList) > 0 {
+						spsHex = fmt.Sprintf("%x", spsList[0])
+					}
+					if len(ppsList) > 0 {
+						ppsHex = fmt.Sprintf("%x", ppsList[0])
+					}
+					fmt.Printf("  IDR s%04d frag%d dts=%d SPS=%s PPS=%s%s\n",
+						sampIdx, fragIdx, dts, spsHex, ppsHex, note)
+				}
+				sampIdx++
+			}
+			fragIdx++
+		}
+	}
+
+	sliceHeaders(parsed, trex, winLo, winHi)
+
+	summary(parsed, trex)
+}
+
+func sliceHeaders(parsed *mp4ff.File, trex *mp4ff.TrexBox, winLo, winHi int64) {
+	// Build SPS/PPS maps from avcC.
+	spsMap := map[uint32]*avc.SPS{}
+	ppsMap := map[uint32]*avc.PPS{}
+	if parsed.Init != nil && parsed.Init.Moov != nil {
+		for _, trak := range parsed.Init.Moov.Traks {
+			if trak.Mdia == nil || trak.Mdia.Minf == nil || trak.Mdia.Minf.Stbl == nil {
+				continue
+			}
+			stsd := trak.Mdia.Minf.Stbl.Stsd
+			if stsd == nil || stsd.AvcX == nil || stsd.AvcX.AvcC == nil {
+				continue
+			}
+			for _, s := range stsd.AvcX.AvcC.SPSnalus {
+				if sps, err := avc.ParseSPSNALUnit(s, true); err == nil {
+					spsMap[uint32(sps.ParameterID)] = sps
+				}
+			}
+			for _, p := range stsd.AvcX.AvcC.PPSnalus {
+				if pps, err := avc.ParsePPSNALUnit(p, spsMap); err == nil {
+					ppsMap[pps.PicParameterSetID] = pps
+				}
+			}
+		}
+	}
+
+	fmt.Println("=== slice headers in inspection window (frame_num / poc / idr_pic_id) ===")
+	fragIdx := 0
+	sampIdx := 0
+	for _, seg := range parsed.Segments {
+		for _, fr := range seg.Fragments {
+			fs, err := fr.GetFullSamples(trex)
+			if err != nil {
+				fragIdx++
+				continue
+			}
+			for _, s := range fs {
+				dts := int64(s.DecodeTime)
+				if dts < winLo || dts > winHi {
+					sampIdx++
+					continue
+				}
+				for _, nal := range splitAVCC(s.Data) {
+					t := nal[0] & 0x1f
+					if t == 1 || t == 5 { // non-IDR or IDR slice
+						sh, err := avc.ParseSliceHeader(nal, spsMap, ppsMap)
+						if err != nil {
+							fmt.Printf("  s%04d frag%d dts=%d nalType=%d sliceHeader ERR: %v\n", sampIdx, fragIdx, dts, t, err)
+							break
+						}
+						fmt.Printf("  s%04d frag%d dts=%d nalType=%d sliceType=%v frameNum=%d idrPicId=%d pocLsb=%d\n",
+							sampIdx, fragIdx, dts, t, sh.SliceType, sh.FrameNum, sh.IDRPicID, sh.PicOrderCntLsb)
+						break
+					}
+				}
+				sampIdx++
+			}
+			fragIdx++
+		}
+	}
+}
+
+// splitAVCC splits a length-prefixed (4-byte) AVCC buffer into NAL units.
+func splitAVCC(b []byte) [][]byte {
+	var out [][]byte
+	i := 0
+	for i+4 <= len(b) {
+		n := int(uint32(b[i])<<24 | uint32(b[i+1])<<16 | uint32(b[i+2])<<8 | uint32(b[i+3]))
+		i += 4
+		if n <= 0 || i+n > len(b) {
+			break
+		}
+		out = append(out, b[i:i+n])
+		i += n
+	}
+	return out
+}
+
+func bytesEqual(a, b []byte) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}
+
+// nalTypes returns the list of H.264 NAL unit types present in an AVCC
+// (length-prefixed) sample buffer.
+func nalTypes(b []byte) []int {
+	var out []int
+	i := 0
+	for i+4 <= len(b) {
+		n := int(uint32(b[i])<<24 | uint32(b[i+1])<<16 | uint32(b[i+2])<<8 | uint32(b[i+3]))
+		i += 4
+		if n <= 0 || i+n > len(b) {
+			break
+		}
+		out = append(out, int(b[i]&0x1f))
+		i += n
+	}
+	return out
+}
+
+// nalsByType returns the raw NAL payloads (without length prefix) of the given
+// type from an AVCC (length-prefixed) sample buffer.
+func nalsByType(b []byte, want int) [][]byte {
+	var out [][]byte
+	i := 0
+	for i+4 <= len(b) {
+		n := int(uint32(b[i])<<24 | uint32(b[i+1])<<16 | uint32(b[i+2])<<8 | uint32(b[i+3]))
+		i += 4
+		if n <= 0 || i+n > len(b) {
+			break
+		}
+		if int(b[i]&0x1f) == want {
+			nal := make([]byte, n)
+			copy(nal, b[i:i+n])
+			out = append(out, nal)
+		}
+		i += n
+	}
+	return out
+}
+
+// inspectWindow returns the [lo,hi] decode-time range (track timescale units)
+// for which sample-level detail is printed. Explicit -from/-to win; otherwise
+// the window auto-centres on the largest gap between consecutive video
+// keyframes — the most likely location of a visible artifact — with a margin on
+// each side so the frames leading into and out of the gap are shown too.
+func inspectWindow(keyDecodeTimes []uint64, from, to int64) (int64, int64) {
+	if from >= 0 || to >= 0 {
+		if from < 0 {
+			from = 0
+		}
+		if to < 0 {
+			to = from + 2000
+		}
+		return from, to
+	}
+	if len(keyDecodeTimes) < 2 {
+		return 0, 1 << 62
+	}
+	worstIdx, worstGap := 1, uint64(0)
+	for i := 1; i < len(keyDecodeTimes); i++ {
+		if g := keyDecodeTimes[i] - keyDecodeTimes[i-1]; g > worstGap {
+			worstGap = g
+			worstIdx = i
+		}
+	}
+	const margin = 500
+	lo := int64(keyDecodeTimes[worstIdx-1]) - margin
+	if lo < 0 {
+		lo = 0
+	}
+	return lo, int64(keyDecodeTimes[worstIdx]) + margin
+}
+
+// summary prints a compact, generic health report so a recording can be
+// validated at a glance without reading the full per-sample dump above.
+func summary(parsed *mp4ff.File, trex *mp4ff.TrexBox) {
+	fmt.Println("=== SUMMARY (health checks) ===")
+
+	videoTracks, audioTracks := 0, 0
+	var videoTimescale uint64 = 1
+	if parsed.Init != nil && parsed.Init.Moov != nil {
+		for _, trak := range parsed.Init.Moov.Traks {
+			switch trak.Mdia.Hdlr.HandlerType {
+			case "vide":
+				videoTracks++
+				if trak.Mdia.Mdhd.Timescale != 0 {
+					videoTimescale = uint64(trak.Mdia.Mdhd.Timescale)
+				}
+			case "soun":
+				audioTracks++
+			}
+		}
+	}
+	fmt.Printf("  tracks: %d video, %d audio\n", videoTracks, audioTracks)
+	if audioTracks == 0 {
+		fmt.Println("    note: no audio track is embedded in this file")
+	}
+
+	type fragStat struct {
+		idx     int
+		tfdt    uint64
+		dur     uint64
+		nSamp   int
+		nKeys   int
+		zeroDur int
+		fps     float64
+	}
+	var stats []fragStat
+	var keyTimes []uint64
+	var fpsArr []float64
+	tfdtGaps := 0
+	var prevEnd uint64
+	havePrev := false
+	fi := 0
+	for _, seg := range parsed.Segments {
+		for _, fr := range seg.Fragments {
+			for _, traf := range fr.Moof.Trafs {
+				if traf.Tfhd.TrackID != 1 {
+					continue
+				}
+				st := fragStat{idx: fi, tfdt: traf.Tfdt.BaseMediaDecodeTime()}
+				off := uint64(0)
+				for _, trun := range traf.Truns {
+					for _, s := range trun.Samples {
+						st.nSamp++
+						if (s.Flags>>24)&0x03 == 0x02 {
+							st.nKeys++
+							keyTimes = append(keyTimes, st.tfdt+off)
+						}
+						if s.Dur == 0 {
+							st.zeroDur++
+						}
+						off += uint64(s.Dur)
+					}
+				}
+				st.dur = off
+				d := st.dur
+				if d == 0 {
+					d = 1
+				}
+				st.fps = float64(st.nSamp) * float64(videoTimescale) / float64(d)
+				fpsArr = append(fpsArr, st.fps)
+				if havePrev && st.tfdt != prevEnd {
+					tfdtGaps++
+				}
+				prevEnd = st.tfdt + st.dur
+				havePrev = true
+				stats = append(stats, st)
+			}
+			fi++
+		}
+	}
+
+	medFps := medianFloat(fpsArr)
+	fmt.Printf("  fragments: %d (video timescale=%d, median %.1f fps)\n", len(stats), videoTimescale, medFps)
+	lowFps := 0
+	totalZero := 0
+	for _, st := range stats {
+		totalZero += st.zeroDur
+		flagStr := ""
+		if medFps > 0 && st.fps < medFps*0.9 {
+			lowFps++
+			flagStr = "  <== LOW FRAME RATE — likely dropped frames"
+		}
+		fmt.Printf("    frag%02d tfdt=%-6d dur=%-5d samples=%-3d keyframes=%d zeroDur=%d fps=%.1f%s\n",
+			st.idx, st.tfdt, st.dur, st.nSamp, st.nKeys, st.zeroDur, st.fps, flagStr)
+	}
+
+	var gaps []uint64
+	for i := 1; i < len(keyTimes); i++ {
+		gaps = append(gaps, keyTimes[i]-keyTimes[i-1])
+	}
+	irregular := 0
+	if len(gaps) > 0 {
+		med := medianUint(gaps)
+		mn, mx := gaps[0], gaps[0]
+		for _, g := range gaps {
+			if g < mn {
+				mn = g
+			}
+			if g > mx {
+				mx = g
+			}
+			// Flag intervals that deviate by more than ~50% from the median GOP.
+			if med > 0 && (g*2 > med*3 || g*2 < med) {
+				irregular++
+			}
+		}
+		fmt.Printf("  keyframe gaps: min=%d median=%d max=%d  irregular=%d/%d\n", mn, med, mx, irregular, len(gaps))
+	}
+	fmt.Printf("  tfdt discontinuities: %d\n", tfdtGaps)
+	fmt.Printf("  zero-duration samples: %d\n", totalZero)
+
+	fmt.Println("  verdict:")
+	clean := true
+	if audioTracks == 0 {
+		fmt.Println("    - no audio track (expected if this recording is video-only)")
+	}
+	if lowFps > 0 {
+		clean = false
+		fmt.Printf("    - %d fragment(s) have a reduced frame rate (dropped frames) — likely source of the artifacts\n", lowFps)
+	}
+	if irregular > 0 {
+		clean = false
+		fmt.Printf("    - %d irregular keyframe interval(s)\n", irregular)
+	}
+	if tfdtGaps > 0 {
+		clean = false
+		fmt.Printf("    - %d timeline (tfdt) discontinuity(ies)\n", tfdtGaps)
+	}
+	if totalZero > 0 {
+		clean = false
+		fmt.Printf("    - %d zero-duration sample(s)\n", totalZero)
+	}
+	if clean {
+		fmt.Println("    - container structure looks healthy")
+	}
+}
+
+func medianUint(v []uint64) uint64 {
+	if len(v) == 0 {
+		return 0
+	}
+	c := append([]uint64(nil), v...)
+	sort.Slice(c, func(i, j int) bool { return c[i] < c[j] })
+	return c[len(c)/2]
+}
+
+func medianFloat(v []float64) float64 {
+	if len(v) == 0 {
+		return 0
+	}
+	c := append([]float64(nil), v...)
+	sort.Float64s(c)
+	return c[len(c)/2]
+}

machinery/data/config/config.json

@@ -1,25 +1,22 @@
+
 {
 	"type": "",
-	"key": "okkey",
-	"name": "rtsp2",
+	"key": "",
+	"name": "agent",
 	"time": "false",
 	"offline": "false",
-	"auto_clean": "100",
+	"auto_clean": "true",
 	"remove_after_upload": "true",
-	"max_directory_size": 20,
-	"timezone": "Europe/Brussels",
+	"max_directory_size": 0,
+	"timezone": "Africa/Ceuta",
 	"capture": {
 		"name": "",
 		"ipcamera": {
-			"width": 640,
-			"height": 480,
+			"rtsp": "",
+			"sub_rtsp": "",
 			"fps": "",
-			"rtsp": "rtsp://fake.kerberos.io/stream",
-			"sub_rtsp": "rtsp://kellyvd:cedricve123@192.168.1.68:554/Streaming/Channels/102?transportmode=multicast\u0026profile=Profile_1",
-			"onvif": "true",
-			"onvif_xaddr": "192.168.1.68",
-			"onvif_username": "kellyvd",
-			"onvif_password": "cedricve123"
+			"base_width": 640,
+			"base_height": 0
 		},
 		"usbcamera": {
 			"device": ""
@@ -27,27 +24,28 @@
 		"raspicamera": {
 			"device": ""
 		},
+		"continuous": "false",
 		"recording": "true",
 		"snapshots": "true",
-		"motion": "true",
 		"liveview": "true",
-		"continuous": "false",
-		"postrecording": 5,
-		"prerecording": 5,
-		"maxlengthrecording": 10,
+		"liveview_chunking": "false",
+		"motion": "true",
+		"postrecording": 20,
+		"prerecording": 10,
+		"maxlengthrecording": 30,
 		"transcodingwebrtc": "",
 		"transcodingresolution": 0,
 		"forwardwebrtc": "",
 		"fragmented": "false",
-		"fragmentedduration": 10,
+		"fragmentedduration": 8,
 		"pixelChangeThreshold": 150
 	},
 	"timetable": [
 		{
 			"start1": 0,
-			"end1": 0,
-			"start2": 0,
-			"end2": 0
+			"end1": 43199,
+			"start2": 43200,
+			"end2": 86400
 		},
 		{
 			"start1": 0,
@@ -94,118 +92,34 @@
 			"x2": 800,
 			"y2": 640
 		},
-		"polygon": [
-			{
-				"id": "1694456798869",
-				"coordinates": [
-					{
-						"x": 458.8176559163439,
-						"y": 420.6597577161105
-					},
-					{
-						"x": 541.8959724597637,
-						"y": 422.62130444776193
-					},
-					{
-						"x": 540.2578560606811,
-						"y": 446.03551153214977
-					},
-					{
-						"x": 459.51092569845395,
-						"y": 445.07041692205803
-					}
-				]
-			},
-			{
-				"id": "1694455955284",
-				"coordinates": [
-					{
-						"x": 82.63849814838939,
-						"y": 122.83665165528404
-					},
-					{
-						"x": 259.18591194149286,
-						"y": 122.83665165528404
-					},
-					{
-						"x": 259.18591194149286,
-						"y": 232.42716889666335
-					},
-					{
-						"x": 82.63849814838939,
-						"y": 232.42716889666335
-					}
-				]
-			},
-			{
-				"id": "1694455953115",
-				"coordinates": [
-					{
-						"x": 200.7130606007035,
-						"y": 171.25495957161723
-					},
-					{
-						"x": 445.73676749725524,
-						"y": 171.25495957161723
-					},
-					{
-						"x": 445.73676749725524,
-						"y": 297.5911664681689
-					},
-					{
-						"x": 200.7130606007035,
-						"y": 297.5911664681689
-					}
-				]
-			},
-			{
-				"id": "0",
-				"coordinates": [
-					{
-						"x": 351.8431271737717,
-						"y": 65.62379883848743
-					},
-					{
-						"x": 609.6534108617149,
-						"y": 65.62379883848743
-					},
-					{
-						"x": 609.6534108617149,
-						"y": 246.50145841295546
-					},
-					{
-						"x": 351.8431271737717,
-						"y": 246.50145841295546
-					}
-				]
-			}
-		]
+		"polygon": []
 	},
 	"cloud": "s3",
 	"s3": {
 		"proxyuri": "http://proxy.kerberos.io",
 		"bucket": "kerberosaccept",
-		"region": "eu-west1",
-		"username": "cedricve"
-	},
-	"kstorage": {
-		"uri": "https://api.vault.kerberos.io",
-		"access_key": "pDCQve0XL1DXwy2x",
-		"secret_access_key": "GTpus90EKrKYuplqL3g!2oiQ@s",
-		"directory": "cedricve"
+		"region": "eu-west-1"
 	},
+	"kstorage": {},
+	"kstorage_secondary": {},
 	"dropbox": {},
 	"mqtturi": "tcp://mqtt.kerberos.io:1883",
 	"mqtt_username": "",
 	"mqtt_password": "",
-	"stunuri": "stun:turn.kerberos.io:8443",
-	"turnuri": "turn:turn.kerberos.io:8443",
+	"turn_force": "false",
+	"stunuri": "stun:turn-fra1.kerberos.io:3478",
+	"turnuri": "turn:turn-fra1.kerberos.io:3478",
 	"turn_username": "username1",
 	"turn_password": "password1",
 	"heartbeaturi": "",
-	"hub_uri": "http://localhost:8081",
-	"hub_key": "AKIA5V6EGLUWXDU4JBEI",
-	"hub_private_key": "DIOXToTpAlYpa4atf7aWtxHd9xEw/Fk4XioL0tek",
+	"hub_encryption": "true",
+	"hub_uri": "https://api.cloud.kerberos.io",
+	"hub_key": "",
+	"hub_private_key": "",
 	"hub_site": "",
-	"condition_uri": ""
+	"condition_uri": "",
+	"encryption": {},
+	"signing": {},
+	"realtimeprocessing": "false",
+	"realtimeprocessing_topic": ""
 }

machinery/data/tus/1786715908_3-737_encrypted_0-0-0-0_-1_25498.mp4.primary.json

@@ -0,0 +1 @@
+{"upload_url":"https://vault.kerberos.io/api/storage/tus/19e42fbc666a38064904caf8c46d182a","vault_uri":"https://vault.kerberos.io/api/storage/tus/","size":1591581}

machinery/data/tus/1788718145_3-694_encrypted_0-0-0-0_-1_25497.mp4.primary.json

@@ -0,0 +1 @@
+{"upload_url":"https://vault.kerberos.io/api/storage/tus/bd3be0f9ecd3873d381f57cb8b4a7e96","vault_uri":"https://vault.kerberos.io/api/storage/tus/","size":2560480}

machinery/docs/docs.go

@@ -1,5 +1,4 @@
-// Package docs GENERATED BY SWAG; DO NOT EDIT
-// This file was generated by swaggo/swag
+// Package docs Code generated by swaggo/swag. DO NOT EDIT
 package docs
 
 import "github.com/swaggo/swag"
@@ -25,11 +24,43 @@ const docTemplate = `{
     "host": "{{.Host}}",
     "basePath": "{{.BasePath}}",
     "paths": {
+        "/api/camera/discover": {
+            "get": {
+                "description": "Runs an advanced Fing/WiFiman-style scan (ONVIF WS-Discovery + TCP port scan + MAC/vendor lookup) and returns the devices found on the local network.",
+                "tags": [
+                    "onvif"
+                ],
+                "summary": "Discover cameras and other devices on the local network.",
+                "operationId": "camera-discover",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Discovery timeout in milliseconds (default 2000)",
+                        "name": "timeout",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Optional subnet(s) to scan, e.g. '192.168.1.0/24' (comma-separated). Defaults to the local interfaces.",
+                        "name": "subnet",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.APIResponse"
+                        }
+                    }
+                }
+            }
+        },
         "/api/camera/onvif/capabilities": {
             "post": {
                 "description": "Will return the ONVIF capabilities for the specific camera.",
                 "tags": [
-                    "camera"
+                    "onvif"
                 ],
                 "summary": "Will return the ONVIF capabilities for the specific camera.",
                 "operationId": "camera-onvif-capabilities",
@@ -58,7 +89,7 @@ const docTemplate = `{
             "post": {
                 "description": "Will activate the desired ONVIF preset.",
                 "tags": [
-                    "camera"
+                    "onvif"
                 ],
                 "summary": "Will activate the desired ONVIF preset.",
                 "operationId": "camera-onvif-gotopreset",
@@ -83,11 +114,45 @@ const docTemplate = `{
                 }
             }
         },
+        "/api/camera/onvif/inputs": {
+            "post": {
+                "security": [
+                    {
+                        "Bearer": []
+                    }
+                ],
+                "description": "Will get the digital inputs from the ONVIF device.",
+                "tags": [
+                    "onvif"
+                ],
+                "summary": "Will get the digital inputs from the ONVIF device.",
+                "operationId": "get-digital-inputs",
+                "parameters": [
+                    {
+                        "description": "OnvifCredentials",
+                        "name": "config",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/models.OnvifCredentials"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.APIResponse"
+                        }
+                    }
+                }
+            }
+        },
         "/api/camera/onvif/login": {
             "post": {
                 "description": "Try to login into ONVIF supported camera.",
                 "tags": [
-                    "camera"
+                    "onvif"
                 ],
                 "summary": "Try to login into ONVIF supported camera.",
                 "operationId": "camera-onvif-login",
@@ -112,11 +177,86 @@ const docTemplate = `{
                 }
             }
         },
+        "/api/camera/onvif/outputs": {
+            "post": {
+                "security": [
+                    {
+                        "Bearer": []
+                    }
+                ],
+                "description": "Will get the relay outputs from the ONVIF device.",
+                "tags": [
+                    "onvif"
+                ],
+                "summary": "Will get the relay outputs from the ONVIF device.",
+                "operationId": "get-relay-outputs",
+                "parameters": [
+                    {
+                        "description": "OnvifCredentials",
+                        "name": "config",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/models.OnvifCredentials"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.APIResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/camera/onvif/outputs/{output}": {
+            "post": {
+                "security": [
+                    {
+                        "Bearer": []
+                    }
+                ],
+                "description": "Will trigger the relay output from the ONVIF device.",
+                "tags": [
+                    "onvif"
+                ],
+                "summary": "Will trigger the relay output from the ONVIF device.",
+                "operationId": "trigger-relay-output",
+                "parameters": [
+                    {
+                        "description": "OnvifCredentials",
+                        "name": "config",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/models.OnvifCredentials"
+                        }
+                    },
+                    {
+                        "type": "string",
+                        "description": "Output",
+                        "name": "output",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.APIResponse"
+                        }
+                    }
+                }
+            }
+        },
         "/api/camera/onvif/pantilt": {
             "post": {
                 "description": "Panning or/and tilting the camera using a direction (x,y).",
                 "tags": [
-                    "camera"
+                    "onvif"
                 ],
                 "summary": "Panning or/and tilting the camera.",
                 "operationId": "camera-onvif-pantilt",
@@ -145,7 +285,7 @@ const docTemplate = `{
             "post": {
                 "description": "Will return the ONVIF presets for the specific camera.",
                 "tags": [
-                    "camera"
+                    "onvif"
                 ],
                 "summary": "Will return the ONVIF presets for the specific camera.",
                 "operationId": "camera-onvif-presets",
@@ -170,11 +310,45 @@ const docTemplate = `{
                 }
             }
         },
+        "/api/camera/onvif/verify": {
+            "post": {
+                "security": [
+                    {
+                        "Bearer": []
+                    }
+                ],
+                "description": "Will verify the ONVIF connectivity.",
+                "tags": [
+                    "onvif"
+                ],
+                "summary": "Will verify the ONVIF connectivity.",
+                "operationId": "verify-onvif",
+                "parameters": [
+                    {
+                        "description": "OnvifCredentials",
+                        "name": "config",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/models.OnvifCredentials"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.APIResponse"
+                        }
+                    }
+                }
+            }
+        },
         "/api/camera/onvif/zoom": {
             "post": {
                 "description": "Zooming in or out the camera.",
                 "tags": [
-                    "camera"
+                    "onvif"
                 ],
                 "summary": "Zooming in or out the camera.",
                 "operationId": "camera-onvif-zoom",
@@ -199,6 +373,90 @@ const docTemplate = `{
                 }
             }
         },
+        "/api/camera/record": {
+            "post": {
+                "description": "Make a recording.",
+                "tags": [
+                    "camera"
+                ],
+                "summary": "Make a recording.",
+                "operationId": "camera-record",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.APIResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/camera/restart": {
+            "post": {
+                "description": "Restart the agent.",
+                "tags": [
+                    "camera"
+                ],
+                "summary": "Restart the agent.",
+                "operationId": "camera-restart",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.APIResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/camera/snapshot/base64": {
+            "get": {
+                "description": "Get a snapshot from the camera in base64.",
+                "tags": [
+                    "camera"
+                ],
+                "summary": "Get a snapshot from the camera in base64.",
+                "operationId": "snapshot-base64",
+                "responses": {
+                    "200": {
+                        "description": "OK"
+                    }
+                }
+            }
+        },
+        "/api/camera/snapshot/jpeg": {
+            "get": {
+                "description": "Get a snapshot from the camera in jpeg format.",
+                "tags": [
+                    "camera"
+                ],
+                "summary": "Get a snapshot from the camera in jpeg format.",
+                "operationId": "snapshot-jpeg",
+                "responses": {
+                    "200": {
+                        "description": "OK"
+                    }
+                }
+            }
+        },
+        "/api/camera/stop": {
+            "post": {
+                "description": "Stop the agent.",
+                "tags": [
+                    "camera"
+                ],
+                "summary": "Stop the agent.",
+                "operationId": "camera-stop",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.APIResponse"
+                        }
+                    }
+                }
+            }
+        },
         "/api/camera/verify/{streamType}": {
             "post": {
                 "description": "This method will validate a specific profile connection from an RTSP camera, and try to get the codec.",
@@ -239,6 +497,75 @@ const docTemplate = `{
                 }
             }
         },
+        "/api/config": {
+            "get": {
+                "description": "Get the current configuration.",
+                "tags": [
+                    "config"
+                ],
+                "summary": "Get the current configuration.",
+                "operationId": "config",
+                "responses": {
+                    "200": {
+                        "description": "OK"
+                    }
+                }
+            },
+            "post": {
+                "description": "Update the current configuration.",
+                "tags": [
+                    "config"
+                ],
+                "summary": "Update the current configuration.",
+                "operationId": "config",
+                "parameters": [
+                    {
+                        "description": "Configuration",
+                        "name": "config",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/models.Config"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK"
+                    }
+                }
+            }
+        },
+        "/api/dashboard": {
+            "get": {
+                "description": "Get all information showed on the dashboard.",
+                "tags": [
+                    "general"
+                ],
+                "summary": "Get all information showed on the dashboard.",
+                "operationId": "dashboard",
+                "responses": {
+                    "200": {
+                        "description": "OK"
+                    }
+                }
+            }
+        },
+        "/api/days": {
+            "get": {
+                "description": "Get all days stored in the recordings directory.",
+                "tags": [
+                    "general"
+                ],
+                "summary": "Get all days stored in the recordings directory.",
+                "operationId": "days",
+                "responses": {
+                    "200": {
+                        "description": "OK"
+                    }
+                }
+            }
+        },
         "/api/hub/verify": {
             "post": {
                 "security": [
@@ -248,7 +575,7 @@ const docTemplate = `{
                 ],
                 "description": "Will verify the hub connectivity.",
                 "tags": [
-                    "config"
+                    "persistence"
                 ],
                 "summary": "Will verify the hub connectivity.",
                 "operationId": "verify-hub",
@@ -273,6 +600,32 @@ const docTemplate = `{
                 }
             }
         },
+        "/api/latest-events": {
+            "post": {
+                "description": "Get the latest recordings (events) from the recordings directory.",
+                "tags": [
+                    "general"
+                ],
+                "summary": "Get the latest recordings (events) from the recordings directory.",
+                "operationId": "latest-events",
+                "parameters": [
+                    {
+                        "description": "Event filter",
+                        "name": "eventFilter",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/models.EventFilter"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK"
+                    }
+                }
+            }
+        },
         "/api/login": {
             "post": {
                 "description": "Get Authorization token.",
@@ -302,27 +655,27 @@ const docTemplate = `{
                 }
             }
         },
-        "/api/onvif/verify": {
+        "/api/persistence/secondary/verify": {
             "post": {
                 "security": [
                     {
                         "Bearer": []
                     }
                 ],
-                "description": "Will verify the ONVIF connectivity.",
+                "description": "Will verify the secondary persistence.",
                 "tags": [
-                    "config"
+                    "persistence"
                 ],
-                "summary": "Will verify the ONVIF connectivity.",
-                "operationId": "verify-onvif",
+                "summary": "Will verify the secondary persistence.",
+                "operationId": "verify-secondary-persistence",
                 "parameters": [
                     {
-                        "description": "Camera Config",
-                        "name": "cameraConfig",
+                        "description": "Config",
+                        "name": "config",
                         "in": "body",
                         "required": true,
                         "schema": {
-                            "$ref": "#/definitions/models.IPCamera"
+                            "$ref": "#/definitions/models.Config"
                         }
                     }
                 ],
@@ -345,7 +698,7 @@ const docTemplate = `{
                 ],
                 "description": "Will verify the persistence.",
                 "tags": [
-                    "config"
+                    "persistence"
                 ],
                 "summary": "Will verify the persistence.",
                 "operationId": "verify-persistence",
@@ -369,9 +722,151 @@ const docTemplate = `{
                     }
                 }
             }
+        },
+        "/health": {
+            "get": {
+                "description": "Confirms that the Agent HTTP process can serve requests and reports current camera stream and Hub heartbeat diagnostics. Operational dependency failures do not change the liveness HTTP status.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "health"
+                ],
+                "summary": "Check Agent health",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/http.HealthResponse"
+                        }
+                    }
+                }
+            }
         }
     },
     "definitions": {
+        "http.Health": {
+            "type": "object",
+            "properties": {
+                "cameraConnected": {
+                    "type": "boolean"
+                },
+                "description": {
+                    "type": "string"
+                },
+                "hub": {
+                    "$ref": "#/definitions/http.HubHealth"
+                },
+                "mainStream": {
+                    "$ref": "#/definitions/http.StreamHealth"
+                },
+                "subStream": {
+                    "$ref": "#/definitions/http.StreamHealth"
+                }
+            }
+        },
+        "http.HealthResponse": {
+            "type": "object",
+            "properties": {
+                "applicationStatusCode": {
+                    "type": "string"
+                },
+                "data": {
+                    "$ref": "#/definitions/http.HealthResponseData"
+                },
+                "entityStatusCode": {
+                    "type": "string"
+                },
+                "httpStatusCode": {
+                    "type": "integer"
+                },
+                "message": {
+                    "type": "string"
+                },
+                "metadata": {
+                    "$ref": "#/definitions/http.ResponseMetadata"
+                }
+            }
+        },
+        "http.HealthResponseData": {
+            "type": "object",
+            "properties": {
+                "health": {
+                    "$ref": "#/definitions/http.Health"
+                }
+            }
+        },
+        "http.HubHealth": {
+            "type": "object",
+            "properties": {
+                "configured": {
+                    "type": "boolean"
+                },
+                "connected": {
+                    "type": "boolean"
+                },
+                "lastHeartbeatAttemptAt": {
+                    "type": "integer"
+                },
+                "lastSuccessfulHeartbeatAt": {
+                    "type": "integer"
+                }
+            }
+        },
+        "http.ResponseMetadata": {
+            "type": "object",
+            "properties": {
+                "applicationName": {
+                    "type": "string"
+                },
+                "applicationVersion": {
+                    "type": "string"
+                },
+                "path": {
+                    "type": "string"
+                },
+                "timestamp": {
+                    "type": "integer"
+                },
+                "traceId": {
+                    "type": "string"
+                }
+            }
+        },
+        "http.StreamHealth": {
+            "type": "object",
+            "properties": {
+                "configured": {
+                    "type": "boolean"
+                },
+                "connected": {
+                    "type": "boolean"
+                },
+                "fps": {
+                    "type": "number"
+                },
+                "lastPacketAt": {
+                    "type": "integer"
+                },
+                "packagesProcessed": {
+                    "type": "integer"
+                },
+                "resolution": {
+                    "$ref": "#/definitions/http.StreamResolution"
+                }
+            }
+        },
+        "http.StreamResolution": {
+            "type": "object",
+            "properties": {
+                "height": {
+                    "type": "integer"
+                },
+                "width": {
+                    "type": "integer"
+                }
+            }
+        },
         "models.APIResponse": {
             "type": "object",
             "properties": {
@@ -443,12 +938,19 @@ const docTemplate = `{
                 "fragmentedduration": {
                     "type": "integer"
                 },
+                "gopsize": {
+                    "description": "GOP size in seconds, used for pre-recording",
+                    "type": "integer"
+                },
                 "ipcamera": {
                     "$ref": "#/definitions/models.IPCamera"
                 },
                 "liveview": {
                     "type": "string"
                 },
+                "liveview_chunking": {
+                    "type": "string"
+                },
                 "maxlengthrecording": {
                     "type": "integer"
                 },
@@ -458,6 +960,10 @@ const docTemplate = `{
                 "name": {
                     "type": "string"
                 },
+                "onvif_motion": {
+                    "description": "ONVIFMotion routes the camera's ONVIF motion events into the\nagent's motion-triggered recording pipeline. When \"true\" the\nagent opens an event/stream against the configured ONVIF\nendpoint and forwards Motion+Active events to HandleMotion.\nRequires Capture.IPCamera.ONVIFXAddr / ONVIFUsername /\nONVIFPassword to be set. Default empty (disabled) keeps the\nexisting pixel-diff motion detection as the only source.",
+                    "type": "string"
+                },
                 "pixelChangeThreshold": {
                     "type": "integer"
                 },
@@ -505,6 +1011,9 @@ const docTemplate = `{
                 "dropbox": {
                     "$ref": "#/definitions/models.Dropbox"
                 },
+                "encryption": {
+                    "$ref": "#/definitions/models.Encryption"
+                },
                 "friendly_name": {
                     "type": "string"
                 },
@@ -512,6 +1021,9 @@ const docTemplate = `{
                     "description": "obsolete",
                     "type": "string"
                 },
+                "hub_encryption": {
+                    "type": "string"
+                },
                 "hub_key": {
                     "type": "string"
                 },
@@ -530,9 +1042,15 @@ const docTemplate = `{
                 "kstorage": {
                     "$ref": "#/definitions/models.KStorage"
                 },
+                "kstorage_secondary": {
+                    "$ref": "#/definitions/models.KStorage"
+                },
                 "max_directory_size": {
                     "type": "integer"
                 },
+                "min_free_space": {
+                    "type": "integer"
+                },
                 "mqtt_password": {
                     "type": "string"
                 },
@@ -548,6 +1066,12 @@ const docTemplate = `{
                 "offline": {
                     "type": "string"
                 },
+                "realtimeprocessing": {
+                    "type": "string"
+                },
+                "realtimeprocessing_topic": {
+                    "type": "string"
+                },
                 "region": {
                     "$ref": "#/definitions/models.Region"
                 },
@@ -557,6 +1081,9 @@ const docTemplate = `{
                 "s3": {
                     "$ref": "#/definitions/models.S3"
                 },
+                "signing": {
+                    "$ref": "#/definitions/models.Signing"
+                },
                 "stunuri": {
                     "type": "string"
                 },
@@ -572,6 +1099,9 @@ const docTemplate = `{
                 "timezone": {
                     "type": "string"
                 },
+                "turn_force": {
+                    "type": "string"
+                },
                 "turn_password": {
                     "type": "string"
                 },
@@ -608,12 +1138,58 @@ const docTemplate = `{
                 }
             }
         },
+        "models.Encryption": {
+            "type": "object",
+            "properties": {
+                "enabled": {
+                    "type": "string"
+                },
+                "fingerprint": {
+                    "type": "string"
+                },
+                "private_key": {
+                    "type": "string"
+                },
+                "recordings": {
+                    "type": "string"
+                },
+                "symmetric_key": {
+                    "type": "string"
+                }
+            }
+        },
+        "models.EventFilter": {
+            "type": "object",
+            "properties": {
+                "number_of_elements": {
+                    "type": "integer"
+                },
+                "timestamp_offset_end": {
+                    "type": "integer"
+                },
+                "timestamp_offset_start": {
+                    "type": "integer"
+                }
+            }
+        },
         "models.IPCamera": {
             "type": "object",
             "properties": {
+                "base_height": {
+                    "type": "integer"
+                },
+                "base_width": {
+                    "type": "integer"
+                },
+                "channels": {
+                    "type": "integer"
+                },
                 "fps": {
                     "type": "string"
                 },
+                "height": {
+                    "type": "integer"
+                },
                 "onvif": {
                     "type": "string"
                 },
@@ -626,11 +1202,87 @@ const docTemplate = `{
                 "onvif_xaddr": {
                     "type": "string"
                 },
+                "pps_nalus": {
+                    "type": "array",
+                    "items": {
+                        "type": "array",
+                        "items": {
+                            "type": "integer",
+                            "format": "int32"
+                        }
+                    }
+                },
                 "rtsp": {
                     "type": "string"
                 },
+                "sample_rate": {
+                    "type": "integer"
+                },
+                "sps_nalus": {
+                    "type": "array",
+                    "items": {
+                        "type": "array",
+                        "items": {
+                            "type": "integer",
+                            "format": "int32"
+                        }
+                    }
+                },
+                "sub_fps": {
+                    "type": "string"
+                },
+                "sub_height": {
+                    "type": "integer"
+                },
+                "sub_pps_nalus": {
+                    "type": "array",
+                    "items": {
+                        "type": "array",
+                        "items": {
+                            "type": "integer",
+                            "format": "int32"
+                        }
+                    }
+                },
                 "sub_rtsp": {
                     "type": "string"
+                },
+                "sub_sps_nalus": {
+                    "description": "Sub stream parameter sets, captured separately from the main stream so the\nlive HLS muxer can build a correct init segment when a viewer switches the\nlive view to the sub (low-resolution) stream.",
+                    "type": "array",
+                    "items": {
+                        "type": "array",
+                        "items": {
+                            "type": "integer",
+                            "format": "int32"
+                        }
+                    }
+                },
+                "sub_vps_nalus": {
+                    "type": "array",
+                    "items": {
+                        "type": "array",
+                        "items": {
+                            "type": "integer",
+                            "format": "int32"
+                        }
+                    }
+                },
+                "sub_width": {
+                    "type": "integer"
+                },
+                "vps_nalus": {
+                    "type": "array",
+                    "items": {
+                        "type": "array",
+                        "items": {
+                            "type": "integer",
+                            "format": "int32"
+                        }
+                    }
+                },
+                "width": {
+                    "type": "integer"
                 }
             }
         },
@@ -644,15 +1296,24 @@ const docTemplate = `{
                     "description": "old way, remove this",
                     "type": "string"
                 },
+                "custom_headers": {
+                    "type": "string"
+                },
                 "directory": {
                     "type": "string"
                 },
+                "max_retries": {
+                    "type": "integer"
+                },
                 "provider": {
                     "type": "string"
                 },
                 "secret_access_key": {
                     "type": "string"
                 },
+                "timeout": {
+                    "type": "integer"
+                },
                 "uri": {
                     "type": "string"
                 }
@@ -790,6 +1451,17 @@ const docTemplate = `{
                 }
             }
         },
+        "models.Signing": {
+            "type": "object",
+            "properties": {
+                "enabled": {
+                    "type": "string"
+                },
+                "private_key": {
+                    "type": "string"
+                }
+            }
+        },
         "models.Timetable": {
             "type": "object",
             "properties": {
@@ -835,6 +1507,8 @@ var SwaggerInfo = &swag.Spec{
 	Description:      "This is the API for using and configure Kerberos Agent.",
 	InfoInstanceName: "swagger",
 	SwaggerTemplate:  docTemplate,
+	LeftDelim:        "{{",
+	RightDelim:       "}}",
 }
 
 func init() {

machinery/docs/swagger.json

@@ -17,11 +17,43 @@
     },
     "basePath": "/",
     "paths": {
+        "/api/camera/discover": {
+            "get": {
+                "description": "Runs an advanced Fing/WiFiman-style scan (ONVIF WS-Discovery + TCP port scan + MAC/vendor lookup) and returns the devices found on the local network.",
+                "tags": [
+                    "onvif"
+                ],
+                "summary": "Discover cameras and other devices on the local network.",
+                "operationId": "camera-discover",
+                "parameters": [
+                    {
+                        "type": "integer",
+                        "description": "Discovery timeout in milliseconds (default 2000)",
+                        "name": "timeout",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "Optional subnet(s) to scan, e.g. '192.168.1.0/24' (comma-separated). Defaults to the local interfaces.",
+                        "name": "subnet",
+                        "in": "query"
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.APIResponse"
+                        }
+                    }
+                }
+            }
+        },
         "/api/camera/onvif/capabilities": {
             "post": {
                 "description": "Will return the ONVIF capabilities for the specific camera.",
                 "tags": [
-                    "camera"
+                    "onvif"
                 ],
                 "summary": "Will return the ONVIF capabilities for the specific camera.",
                 "operationId": "camera-onvif-capabilities",
@@ -50,7 +82,7 @@
             "post": {
                 "description": "Will activate the desired ONVIF preset.",
                 "tags": [
-                    "camera"
+                    "onvif"
                 ],
                 "summary": "Will activate the desired ONVIF preset.",
                 "operationId": "camera-onvif-gotopreset",
@@ -75,11 +107,45 @@
                 }
             }
         },
+        "/api/camera/onvif/inputs": {
+            "post": {
+                "security": [
+                    {
+                        "Bearer": []
+                    }
+                ],
+                "description": "Will get the digital inputs from the ONVIF device.",
+                "tags": [
+                    "onvif"
+                ],
+                "summary": "Will get the digital inputs from the ONVIF device.",
+                "operationId": "get-digital-inputs",
+                "parameters": [
+                    {
+                        "description": "OnvifCredentials",
+                        "name": "config",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/models.OnvifCredentials"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.APIResponse"
+                        }
+                    }
+                }
+            }
+        },
         "/api/camera/onvif/login": {
             "post": {
                 "description": "Try to login into ONVIF supported camera.",
                 "tags": [
-                    "camera"
+                    "onvif"
                 ],
                 "summary": "Try to login into ONVIF supported camera.",
                 "operationId": "camera-onvif-login",
@@ -104,11 +170,86 @@
                 }
             }
         },
+        "/api/camera/onvif/outputs": {
+            "post": {
+                "security": [
+                    {
+                        "Bearer": []
+                    }
+                ],
+                "description": "Will get the relay outputs from the ONVIF device.",
+                "tags": [
+                    "onvif"
+                ],
+                "summary": "Will get the relay outputs from the ONVIF device.",
+                "operationId": "get-relay-outputs",
+                "parameters": [
+                    {
+                        "description": "OnvifCredentials",
+                        "name": "config",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/models.OnvifCredentials"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.APIResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/camera/onvif/outputs/{output}": {
+            "post": {
+                "security": [
+                    {
+                        "Bearer": []
+                    }
+                ],
+                "description": "Will trigger the relay output from the ONVIF device.",
+                "tags": [
+                    "onvif"
+                ],
+                "summary": "Will trigger the relay output from the ONVIF device.",
+                "operationId": "trigger-relay-output",
+                "parameters": [
+                    {
+                        "description": "OnvifCredentials",
+                        "name": "config",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/models.OnvifCredentials"
+                        }
+                    },
+                    {
+                        "type": "string",
+                        "description": "Output",
+                        "name": "output",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.APIResponse"
+                        }
+                    }
+                }
+            }
+        },
         "/api/camera/onvif/pantilt": {
             "post": {
                 "description": "Panning or/and tilting the camera using a direction (x,y).",
                 "tags": [
-                    "camera"
+                    "onvif"
                 ],
                 "summary": "Panning or/and tilting the camera.",
                 "operationId": "camera-onvif-pantilt",
@@ -137,7 +278,7 @@
             "post": {
                 "description": "Will return the ONVIF presets for the specific camera.",
                 "tags": [
-                    "camera"
+                    "onvif"
                 ],
                 "summary": "Will return the ONVIF presets for the specific camera.",
                 "operationId": "camera-onvif-presets",
@@ -162,11 +303,45 @@
                 }
             }
         },
+        "/api/camera/onvif/verify": {
+            "post": {
+                "security": [
+                    {
+                        "Bearer": []
+                    }
+                ],
+                "description": "Will verify the ONVIF connectivity.",
+                "tags": [
+                    "onvif"
+                ],
+                "summary": "Will verify the ONVIF connectivity.",
+                "operationId": "verify-onvif",
+                "parameters": [
+                    {
+                        "description": "OnvifCredentials",
+                        "name": "config",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/models.OnvifCredentials"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.APIResponse"
+                        }
+                    }
+                }
+            }
+        },
         "/api/camera/onvif/zoom": {
             "post": {
                 "description": "Zooming in or out the camera.",
                 "tags": [
-                    "camera"
+                    "onvif"
                 ],
                 "summary": "Zooming in or out the camera.",
                 "operationId": "camera-onvif-zoom",
@@ -191,6 +366,90 @@
                 }
             }
         },
+        "/api/camera/record": {
+            "post": {
+                "description": "Make a recording.",
+                "tags": [
+                    "camera"
+                ],
+                "summary": "Make a recording.",
+                "operationId": "camera-record",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.APIResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/camera/restart": {
+            "post": {
+                "description": "Restart the agent.",
+                "tags": [
+                    "camera"
+                ],
+                "summary": "Restart the agent.",
+                "operationId": "camera-restart",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.APIResponse"
+                        }
+                    }
+                }
+            }
+        },
+        "/api/camera/snapshot/base64": {
+            "get": {
+                "description": "Get a snapshot from the camera in base64.",
+                "tags": [
+                    "camera"
+                ],
+                "summary": "Get a snapshot from the camera in base64.",
+                "operationId": "snapshot-base64",
+                "responses": {
+                    "200": {
+                        "description": "OK"
+                    }
+                }
+            }
+        },
+        "/api/camera/snapshot/jpeg": {
+            "get": {
+                "description": "Get a snapshot from the camera in jpeg format.",
+                "tags": [
+                    "camera"
+                ],
+                "summary": "Get a snapshot from the camera in jpeg format.",
+                "operationId": "snapshot-jpeg",
+                "responses": {
+                    "200": {
+                        "description": "OK"
+                    }
+                }
+            }
+        },
+        "/api/camera/stop": {
+            "post": {
+                "description": "Stop the agent.",
+                "tags": [
+                    "camera"
+                ],
+                "summary": "Stop the agent.",
+                "operationId": "camera-stop",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.APIResponse"
+                        }
+                    }
+                }
+            }
+        },
         "/api/camera/verify/{streamType}": {
             "post": {
                 "description": "This method will validate a specific profile connection from an RTSP camera, and try to get the codec.",
@@ -231,6 +490,75 @@
                 }
             }
         },
+        "/api/config": {
+            "get": {
+                "description": "Get the current configuration.",
+                "tags": [
+                    "config"
+                ],
+                "summary": "Get the current configuration.",
+                "operationId": "config",
+                "responses": {
+                    "200": {
+                        "description": "OK"
+                    }
+                }
+            },
+            "post": {
+                "description": "Update the current configuration.",
+                "tags": [
+                    "config"
+                ],
+                "summary": "Update the current configuration.",
+                "operationId": "config",
+                "parameters": [
+                    {
+                        "description": "Configuration",
+                        "name": "config",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/models.Config"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK"
+                    }
+                }
+            }
+        },
+        "/api/dashboard": {
+            "get": {
+                "description": "Get all information showed on the dashboard.",
+                "tags": [
+                    "general"
+                ],
+                "summary": "Get all information showed on the dashboard.",
+                "operationId": "dashboard",
+                "responses": {
+                    "200": {
+                        "description": "OK"
+                    }
+                }
+            }
+        },
+        "/api/days": {
+            "get": {
+                "description": "Get all days stored in the recordings directory.",
+                "tags": [
+                    "general"
+                ],
+                "summary": "Get all days stored in the recordings directory.",
+                "operationId": "days",
+                "responses": {
+                    "200": {
+                        "description": "OK"
+                    }
+                }
+            }
+        },
         "/api/hub/verify": {
             "post": {
                 "security": [
@@ -240,7 +568,7 @@
                 ],
                 "description": "Will verify the hub connectivity.",
                 "tags": [
-                    "config"
+                    "persistence"
                 ],
                 "summary": "Will verify the hub connectivity.",
                 "operationId": "verify-hub",
@@ -265,6 +593,32 @@
                 }
             }
         },
+        "/api/latest-events": {
+            "post": {
+                "description": "Get the latest recordings (events) from the recordings directory.",
+                "tags": [
+                    "general"
+                ],
+                "summary": "Get the latest recordings (events) from the recordings directory.",
+                "operationId": "latest-events",
+                "parameters": [
+                    {
+                        "description": "Event filter",
+                        "name": "eventFilter",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/models.EventFilter"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK"
+                    }
+                }
+            }
+        },
         "/api/login": {
             "post": {
                 "description": "Get Authorization token.",
@@ -294,27 +648,27 @@
                 }
             }
         },
-        "/api/onvif/verify": {
+        "/api/persistence/secondary/verify": {
             "post": {
                 "security": [
                     {
                         "Bearer": []
                     }
                 ],
-                "description": "Will verify the ONVIF connectivity.",
+                "description": "Will verify the secondary persistence.",
                 "tags": [
-                    "config"
+                    "persistence"
                 ],
-                "summary": "Will verify the ONVIF connectivity.",
-                "operationId": "verify-onvif",
+                "summary": "Will verify the secondary persistence.",
+                "operationId": "verify-secondary-persistence",
                 "parameters": [
                     {
-                        "description": "Camera Config",
-                        "name": "cameraConfig",
+                        "description": "Config",
+                        "name": "config",
                         "in": "body",
                         "required": true,
                         "schema": {
-                            "$ref": "#/definitions/models.IPCamera"
+                            "$ref": "#/definitions/models.Config"
                         }
                     }
                 ],
@@ -337,7 +691,7 @@
                 ],
                 "description": "Will verify the persistence.",
                 "tags": [
-                    "config"
+                    "persistence"
                 ],
                 "summary": "Will verify the persistence.",
                 "operationId": "verify-persistence",
@@ -361,9 +715,151 @@
                     }
                 }
             }
+        },
+        "/health": {
+            "get": {
+                "description": "Confirms that the Agent HTTP process can serve requests and reports current camera stream and Hub heartbeat diagnostics. Operational dependency failures do not change the liveness HTTP status.",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "health"
+                ],
+                "summary": "Check Agent health",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/http.HealthResponse"
+                        }
+                    }
+                }
+            }
         }
     },
     "definitions": {
+        "http.Health": {
+            "type": "object",
+            "properties": {
+                "cameraConnected": {
+                    "type": "boolean"
+                },
+                "description": {
+                    "type": "string"
+                },
+                "hub": {
+                    "$ref": "#/definitions/http.HubHealth"
+                },
+                "mainStream": {
+                    "$ref": "#/definitions/http.StreamHealth"
+                },
+                "subStream": {
+                    "$ref": "#/definitions/http.StreamHealth"
+                }
+            }
+        },
+        "http.HealthResponse": {
+            "type": "object",
+            "properties": {
+                "applicationStatusCode": {
+                    "type": "string"
+                },
+                "data": {
+                    "$ref": "#/definitions/http.HealthResponseData"
+                },
+                "entityStatusCode": {
+                    "type": "string"
+                },
+                "httpStatusCode": {
+                    "type": "integer"
+                },
+                "message": {
+                    "type": "string"
+                },
+                "metadata": {
+                    "$ref": "#/definitions/http.ResponseMetadata"
+                }
+            }
+        },
+        "http.HealthResponseData": {
+            "type": "object",
+            "properties": {
+                "health": {
+                    "$ref": "#/definitions/http.Health"
+                }
+            }
+        },
+        "http.HubHealth": {
+            "type": "object",
+            "properties": {
+                "configured": {
+                    "type": "boolean"
+                },
+                "connected": {
+                    "type": "boolean"
+                },
+                "lastHeartbeatAttemptAt": {
+                    "type": "integer"
+                },
+                "lastSuccessfulHeartbeatAt": {
+                    "type": "integer"
+                }
+            }
+        },
+        "http.ResponseMetadata": {
+            "type": "object",
+            "properties": {
+                "applicationName": {
+                    "type": "string"
+                },
+                "applicationVersion": {
+                    "type": "string"
+                },
+                "path": {
+                    "type": "string"
+                },
+                "timestamp": {
+                    "type": "integer"
+                },
+                "traceId": {
+                    "type": "string"
+                }
+            }
+        },
+        "http.StreamHealth": {
+            "type": "object",
+            "properties": {
+                "configured": {
+                    "type": "boolean"
+                },
+                "connected": {
+                    "type": "boolean"
+                },
+                "fps": {
+                    "type": "number"
+                },
+                "lastPacketAt": {
+                    "type": "integer"
+                },
+                "packagesProcessed": {
+                    "type": "integer"
+                },
+                "resolution": {
+                    "$ref": "#/definitions/http.StreamResolution"
+                }
+            }
+        },
+        "http.StreamResolution": {
+            "type": "object",
+            "properties": {
+                "height": {
+                    "type": "integer"
+                },
+                "width": {
+                    "type": "integer"
+                }
+            }
+        },
         "models.APIResponse": {
             "type": "object",
             "properties": {
@@ -435,12 +931,19 @@
                 "fragmentedduration": {
                     "type": "integer"
                 },
+                "gopsize": {
+                    "description": "GOP size in seconds, used for pre-recording",
+                    "type": "integer"
+                },
                 "ipcamera": {
                     "$ref": "#/definitions/models.IPCamera"
                 },
                 "liveview": {
                     "type": "string"
                 },
+                "liveview_chunking": {
+                    "type": "string"
+                },
                 "maxlengthrecording": {
                     "type": "integer"
                 },
@@ -450,6 +953,10 @@
                 "name": {
                     "type": "string"
                 },
+                "onvif_motion": {
+                    "description": "ONVIFMotion routes the camera's ONVIF motion events into the\nagent's motion-triggered recording pipeline. When \"true\" the\nagent opens an event/stream against the configured ONVIF\nendpoint and forwards Motion+Active events to HandleMotion.\nRequires Capture.IPCamera.ONVIFXAddr / ONVIFUsername /\nONVIFPassword to be set. Default empty (disabled) keeps the\nexisting pixel-diff motion detection as the only source.",
+                    "type": "string"
+                },
                 "pixelChangeThreshold": {
                     "type": "integer"
                 },
@@ -497,6 +1004,9 @@
                 "dropbox": {
                     "$ref": "#/definitions/models.Dropbox"
                 },
+                "encryption": {
+                    "$ref": "#/definitions/models.Encryption"
+                },
                 "friendly_name": {
                     "type": "string"
                 },
@@ -504,6 +1014,9 @@
                     "description": "obsolete",
                     "type": "string"
                 },
+                "hub_encryption": {
+                    "type": "string"
+                },
                 "hub_key": {
                     "type": "string"
                 },
@@ -522,9 +1035,15 @@
                 "kstorage": {
                     "$ref": "#/definitions/models.KStorage"
                 },
+                "kstorage_secondary": {
+                    "$ref": "#/definitions/models.KStorage"
+                },
                 "max_directory_size": {
                     "type": "integer"
                 },
+                "min_free_space": {
+                    "type": "integer"
+                },
                 "mqtt_password": {
                     "type": "string"
                 },
@@ -540,6 +1059,12 @@
                 "offline": {
                     "type": "string"
                 },
+                "realtimeprocessing": {
+                    "type": "string"
+                },
+                "realtimeprocessing_topic": {
+                    "type": "string"
+                },
                 "region": {
                     "$ref": "#/definitions/models.Region"
                 },
@@ -549,6 +1074,9 @@
                 "s3": {
                     "$ref": "#/definitions/models.S3"
                 },
+                "signing": {
+                    "$ref": "#/definitions/models.Signing"
+                },
                 "stunuri": {
                     "type": "string"
                 },
@@ -564,6 +1092,9 @@
                 "timezone": {
                     "type": "string"
                 },
+                "turn_force": {
+                    "type": "string"
+                },
                 "turn_password": {
                     "type": "string"
                 },
@@ -600,12 +1131,58 @@
                 }
             }
         },
+        "models.Encryption": {
+            "type": "object",
+            "properties": {
+                "enabled": {
+                    "type": "string"
+                },
+                "fingerprint": {
+                    "type": "string"
+                },
+                "private_key": {
+                    "type": "string"
+                },
+                "recordings": {
+                    "type": "string"
+                },
+                "symmetric_key": {
+                    "type": "string"
+                }
+            }
+        },
+        "models.EventFilter": {
+            "type": "object",
+            "properties": {
+                "number_of_elements": {
+                    "type": "integer"
+                },
+                "timestamp_offset_end": {
+                    "type": "integer"
+                },
+                "timestamp_offset_start": {
+                    "type": "integer"
+                }
+            }
+        },
         "models.IPCamera": {
             "type": "object",
             "properties": {
+                "base_height": {
+                    "type": "integer"
+                },
+                "base_width": {
+                    "type": "integer"
+                },
+                "channels": {
+                    "type": "integer"
+                },
                 "fps": {
                     "type": "string"
                 },
+                "height": {
+                    "type": "integer"
+                },
                 "onvif": {
                     "type": "string"
                 },
@@ -618,11 +1195,87 @@
                 "onvif_xaddr": {
                     "type": "string"
                 },
+                "pps_nalus": {
+                    "type": "array",
+                    "items": {
+                        "type": "array",
+                        "items": {
+                            "type": "integer",
+                            "format": "int32"
+                        }
+                    }
+                },
                 "rtsp": {
                     "type": "string"
                 },
+                "sample_rate": {
+                    "type": "integer"
+                },
+                "sps_nalus": {
+                    "type": "array",
+                    "items": {
+                        "type": "array",
+                        "items": {
+                            "type": "integer",
+                            "format": "int32"
+                        }
+                    }
+                },
+                "sub_fps": {
+                    "type": "string"
+                },
+                "sub_height": {
+                    "type": "integer"
+                },
+                "sub_pps_nalus": {
+                    "type": "array",
+                    "items": {
+                        "type": "array",
+                        "items": {
+                            "type": "integer",
+                            "format": "int32"
+                        }
+                    }
+                },
                 "sub_rtsp": {
                     "type": "string"
+                },
+                "sub_sps_nalus": {
+                    "description": "Sub stream parameter sets, captured separately from the main stream so the\nlive HLS muxer can build a correct init segment when a viewer switches the\nlive view to the sub (low-resolution) stream.",
+                    "type": "array",
+                    "items": {
+                        "type": "array",
+                        "items": {
+                            "type": "integer",
+                            "format": "int32"
+                        }
+                    }
+                },
+                "sub_vps_nalus": {
+                    "type": "array",
+                    "items": {
+                        "type": "array",
+                        "items": {
+                            "type": "integer",
+                            "format": "int32"
+                        }
+                    }
+                },
+                "sub_width": {
+                    "type": "integer"
+                },
+                "vps_nalus": {
+                    "type": "array",
+                    "items": {
+                        "type": "array",
+                        "items": {
+                            "type": "integer",
+                            "format": "int32"
+                        }
+                    }
+                },
+                "width": {
+                    "type": "integer"
                 }
             }
         },
@@ -636,15 +1289,24 @@
                     "description": "old way, remove this",
                     "type": "string"
                 },
+                "custom_headers": {
+                    "type": "string"
+                },
                 "directory": {
                     "type": "string"
                 },
+                "max_retries": {
+                    "type": "integer"
+                },
                 "provider": {
                     "type": "string"
                 },
                 "secret_access_key": {
                     "type": "string"
                 },
+                "timeout": {
+                    "type": "integer"
+                },
                 "uri": {
                     "type": "string"
                 }
@@ -782,6 +1444,17 @@
                 }
             }
         },
+        "models.Signing": {
+            "type": "object",
+            "properties": {
+                "enabled": {
+                    "type": "string"
+                },
+                "private_key": {
+                    "type": "string"
+                }
+            }
+        },
         "models.Timetable": {
             "type": "object",
             "properties": {

machinery/docs/swagger.yaml

@@ -1,5 +1,84 @@
 basePath: /
 definitions:
+  http.Health:
+    properties:
+      cameraConnected:
+        type: boolean
+      description:
+        type: string
+      hub:
+        $ref: '#/definitions/http.HubHealth'
+      mainStream:
+        $ref: '#/definitions/http.StreamHealth'
+      subStream:
+        $ref: '#/definitions/http.StreamHealth'
+    type: object
+  http.HealthResponse:
+    properties:
+      applicationStatusCode:
+        type: string
+      data:
+        $ref: '#/definitions/http.HealthResponseData'
+      entityStatusCode:
+        type: string
+      httpStatusCode:
+        type: integer
+      message:
+        type: string
+      metadata:
+        $ref: '#/definitions/http.ResponseMetadata'
+    type: object
+  http.HealthResponseData:
+    properties:
+      health:
+        $ref: '#/definitions/http.Health'
+    type: object
+  http.HubHealth:
+    properties:
+      configured:
+        type: boolean
+      connected:
+        type: boolean
+      lastHeartbeatAttemptAt:
+        type: integer
+      lastSuccessfulHeartbeatAt:
+        type: integer
+    type: object
+  http.ResponseMetadata:
+    properties:
+      applicationName:
+        type: string
+      applicationVersion:
+        type: string
+      path:
+        type: string
+      timestamp:
+        type: integer
+      traceId:
+        type: string
+    type: object
+  http.StreamHealth:
+    properties:
+      configured:
+        type: boolean
+      connected:
+        type: boolean
+      fps:
+        type: number
+      lastPacketAt:
+        type: integer
+      packagesProcessed:
+        type: integer
+      resolution:
+        $ref: '#/definitions/http.StreamResolution'
+    type: object
+  http.StreamResolution:
+    properties:
+      height:
+        type: integer
+      width:
+        type: integer
+    type: object
   models.APIResponse:
     properties:
       can_pan_tilt:
@@ -47,16 +126,31 @@ definitions:
         type: string
       fragmentedduration:
         type: integer
+      gopsize:
+        description: GOP size in seconds, used for pre-recording
+        type: integer
       ipcamera:
         $ref: '#/definitions/models.IPCamera'
       liveview:
         type: string
+      liveview_chunking:
+        type: string
       maxlengthrecording:
         type: integer
       motion:
         type: string
       name:
         type: string
+      onvif_motion:
+        description: |-
+          ONVIFMotion routes the camera's ONVIF motion events into the
+          agent's motion-triggered recording pipeline. When "true" the
+          agent opens an event/stream against the configured ONVIF
+          endpoint and forwards Motion+Active events to HandleMotion.
+          Requires Capture.IPCamera.ONVIFXAddr / ONVIFUsername /
+          ONVIFPassword to be set. Default empty (disabled) keeps the
+          existing pixel-diff motion detection as the only source.
+        type: string
       pixelChangeThreshold:
         type: integer
       postrecording:
@@ -88,11 +182,15 @@ definitions:
         type: string
       dropbox:
         $ref: '#/definitions/models.Dropbox'
+      encryption:
+        $ref: '#/definitions/models.Encryption'
       friendly_name:
         type: string
       heartbeaturi:
         description: obsolete
         type: string
+      hub_encryption:
+        type: string
       hub_key:
         type: string
       hub_private_key:
@@ -105,8 +203,12 @@ definitions:
         type: string
       kstorage:
         $ref: '#/definitions/models.KStorage'
+      kstorage_secondary:
+        $ref: '#/definitions/models.KStorage'
       max_directory_size:
         type: integer
+      min_free_space:
+        type: integer
       mqtt_password:
         type: string
       mqtt_username:
@@ -117,12 +219,18 @@ definitions:
         type: string
       offline:
         type: string
+      realtimeprocessing:
+        type: string
+      realtimeprocessing_topic:
+        type: string
       region:
         $ref: '#/definitions/models.Region'
       remove_after_upload:
         type: string
       s3:
         $ref: '#/definitions/models.S3'
+      signing:
+        $ref: '#/definitions/models.Signing'
       stunuri:
         type: string
       time:
@@ -133,6 +241,8 @@ definitions:
         type: array
       timezone:
         type: string
+      turn_force:
+        type: string
       turn_password:
         type: string
       turn_username:
@@ -156,10 +266,40 @@ definitions:
       directory:
         type: string
     type: object
+  models.Encryption:
+    properties:
+      enabled:
+        type: string
+      fingerprint:
+        type: string
+      private_key:
+        type: string
+      recordings:
+        type: string
+      symmetric_key:
+        type: string
+    type: object
+  models.EventFilter:
+    properties:
+      number_of_elements:
+        type: integer
+      timestamp_offset_end:
+        type: integer
+      timestamp_offset_start:
+        type: integer
+    type: object
   models.IPCamera:
     properties:
+      base_height:
+        type: integer
+      base_width:
+        type: integer
+      channels:
+        type: integer
       fps:
         type: string
+      height:
+        type: integer
       onvif:
         type: string
       onvif_password:
@@ -168,10 +308,66 @@ definitions:
         type: string
       onvif_xaddr:
         type: string
+      pps_nalus:
+        items:
+          items:
+            format: int32
+            type: integer
+          type: array
+        type: array
       rtsp:
         type: string
+      sample_rate:
+        type: integer
+      sps_nalus:
+        items:
+          items:
+            format: int32
+            type: integer
+          type: array
+        type: array
+      sub_fps:
+        type: string
+      sub_height:
+        type: integer
+      sub_pps_nalus:
+        items:
+          items:
+            format: int32
+            type: integer
+          type: array
+        type: array
       sub_rtsp:
         type: string
+      sub_sps_nalus:
+        description: |-
+          Sub stream parameter sets, captured separately from the main stream so the
+          live HLS muxer can build a correct init segment when a viewer switches the
+          live view to the sub (low-resolution) stream.
+        items:
+          items:
+            format: int32
+            type: integer
+          type: array
+        type: array
+      sub_vps_nalus:
+        items:
+          items:
+            format: int32
+            type: integer
+          type: array
+        type: array
+      sub_width:
+        type: integer
+      vps_nalus:
+        items:
+          items:
+            format: int32
+            type: integer
+          type: array
+        type: array
+      width:
+        type: integer
     type: object
   models.KStorage:
     properties:
@@ -182,10 +378,14 @@ definitions:
         type: string
       directory:
         type: string
+      max_retries:
+        type: integer
       provider:
         type: string
       secret_access_key:
         type: string
+      timeout:
+        type: integer
       uri:
         type: string
     type: object
@@ -274,6 +474,13 @@ definitions:
       username:
         type: string
     type: object
+  models.Signing:
+    properties:
+      enabled:
+        type: string
+      private_key:
+        type: string
+    type: object
   models.Timetable:
     properties:
       end1:
@@ -303,6 +510,30 @@ info:
   title: Swagger Kerberos Agent API
   version: "1.0"
 paths:
+  /api/camera/discover:
+    get:
+      description: Runs an advanced Fing/WiFiman-style scan (ONVIF WS-Discovery +
+        TCP port scan + MAC/vendor lookup) and returns the devices found on the local
+        network.
+      operationId: camera-discover
+      parameters:
+      - description: Discovery timeout in milliseconds (default 2000)
+        in: query
+        name: timeout
+        type: integer
+      - description: Optional subnet(s) to scan, e.g. '192.168.1.0/24' (comma-separated).
+          Defaults to the local interfaces.
+        in: query
+        name: subnet
+        type: string
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/models.APIResponse'
+      summary: Discover cameras and other devices on the local network.
+      tags:
+      - onvif
   /api/camera/onvif/capabilities:
     post:
       description: Will return the ONVIF capabilities for the specific camera.
@@ -321,7 +552,7 @@ paths:
             $ref: '#/definitions/models.APIResponse'
       summary: Will return the ONVIF capabilities for the specific camera.
       tags:
-      - camera
+      - onvif
   /api/camera/onvif/gotopreset:
     post:
       description: Will activate the desired ONVIF preset.
@@ -340,7 +571,28 @@ paths:
             $ref: '#/definitions/models.APIResponse'
       summary: Will activate the desired ONVIF preset.
       tags:
-      - camera
+      - onvif
+  /api/camera/onvif/inputs:
+    post:
+      description: Will get the digital inputs from the ONVIF device.
+      operationId: get-digital-inputs
+      parameters:
+      - description: OnvifCredentials
+        in: body
+        name: config
+        required: true
+        schema:
+          $ref: '#/definitions/models.OnvifCredentials'
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/models.APIResponse'
+      security:
+      - Bearer: []
+      summary: Will get the digital inputs from the ONVIF device.
+      tags:
+      - onvif
   /api/camera/onvif/login:
     post:
       description: Try to login into ONVIF supported camera.
@@ -359,7 +611,54 @@ paths:
             $ref: '#/definitions/models.APIResponse'
       summary: Try to login into ONVIF supported camera.
       tags:
-      - camera
+      - onvif
+  /api/camera/onvif/outputs:
+    post:
+      description: Will get the relay outputs from the ONVIF device.
+      operationId: get-relay-outputs
+      parameters:
+      - description: OnvifCredentials
+        in: body
+        name: config
+        required: true
+        schema:
+          $ref: '#/definitions/models.OnvifCredentials'
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/models.APIResponse'
+      security:
+      - Bearer: []
+      summary: Will get the relay outputs from the ONVIF device.
+      tags:
+      - onvif
+  /api/camera/onvif/outputs/{output}:
+    post:
+      description: Will trigger the relay output from the ONVIF device.
+      operationId: trigger-relay-output
+      parameters:
+      - description: OnvifCredentials
+        in: body
+        name: config
+        required: true
+        schema:
+          $ref: '#/definitions/models.OnvifCredentials'
+      - description: Output
+        in: path
+        name: output
+        required: true
+        type: string
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/models.APIResponse'
+      security:
+      - Bearer: []
+      summary: Will trigger the relay output from the ONVIF device.
+      tags:
+      - onvif
   /api/camera/onvif/pantilt:
     post:
       description: Panning or/and tilting the camera using a direction (x,y).
@@ -378,7 +677,7 @@ paths:
             $ref: '#/definitions/models.APIResponse'
       summary: Panning or/and tilting the camera.
       tags:
-      - camera
+      - onvif
   /api/camera/onvif/presets:
     post:
       description: Will return the ONVIF presets for the specific camera.
@@ -397,7 +696,28 @@ paths:
             $ref: '#/definitions/models.APIResponse'
       summary: Will return the ONVIF presets for the specific camera.
       tags:
-      - camera
+      - onvif
+  /api/camera/onvif/verify:
+    post:
+      description: Will verify the ONVIF connectivity.
+      operationId: verify-onvif
+      parameters:
+      - description: OnvifCredentials
+        in: body
+        name: config
+        required: true
+        schema:
+          $ref: '#/definitions/models.OnvifCredentials'
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/models.APIResponse'
+      security:
+      - Bearer: []
+      summary: Will verify the ONVIF connectivity.
+      tags:
+      - onvif
   /api/camera/onvif/zoom:
     post:
       description: Zooming in or out the camera.
@@ -416,6 +736,62 @@ paths:
             $ref: '#/definitions/models.APIResponse'
       summary: Zooming in or out the camera.
       tags:
+      - onvif
+  /api/camera/record:
+    post:
+      description: Make a recording.
+      operationId: camera-record
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/models.APIResponse'
+      summary: Make a recording.
+      tags:
+      - camera
+  /api/camera/restart:
+    post:
+      description: Restart the agent.
+      operationId: camera-restart
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/models.APIResponse'
+      summary: Restart the agent.
+      tags:
+      - camera
+  /api/camera/snapshot/base64:
+    get:
+      description: Get a snapshot from the camera in base64.
+      operationId: snapshot-base64
+      responses:
+        "200":
+          description: OK
+      summary: Get a snapshot from the camera in base64.
+      tags:
+      - camera
+  /api/camera/snapshot/jpeg:
+    get:
+      description: Get a snapshot from the camera in jpeg format.
+      operationId: snapshot-jpeg
+      responses:
+        "200":
+          description: OK
+      summary: Get a snapshot from the camera in jpeg format.
+      tags:
+      - camera
+  /api/camera/stop:
+    post:
+      description: Stop the agent.
+      operationId: camera-stop
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/models.APIResponse'
+      summary: Stop the agent.
+      tags:
       - camera
   /api/camera/verify/{streamType}:
     post:
@@ -445,6 +821,52 @@ paths:
       summary: Validate a specific RTSP profile camera connection.
       tags:
       - camera
+  /api/config:
+    get:
+      description: Get the current configuration.
+      operationId: config
+      responses:
+        "200":
+          description: OK
+      summary: Get the current configuration.
+      tags:
+      - config
+    post:
+      description: Update the current configuration.
+      operationId: config
+      parameters:
+      - description: Configuration
+        in: body
+        name: config
+        required: true
+        schema:
+          $ref: '#/definitions/models.Config'
+      responses:
+        "200":
+          description: OK
+      summary: Update the current configuration.
+      tags:
+      - config
+  /api/dashboard:
+    get:
+      description: Get all information showed on the dashboard.
+      operationId: dashboard
+      responses:
+        "200":
+          description: OK
+      summary: Get all information showed on the dashboard.
+      tags:
+      - general
+  /api/days:
+    get:
+      description: Get all days stored in the recordings directory.
+      operationId: days
+      responses:
+        "200":
+          description: OK
+      summary: Get all days stored in the recordings directory.
+      tags:
+      - general
   /api/hub/verify:
     post:
       description: Will verify the hub connectivity.
@@ -465,7 +887,24 @@ paths:
       - Bearer: []
       summary: Will verify the hub connectivity.
       tags:
-      - config
+      - persistence
+  /api/latest-events:
+    post:
+      description: Get the latest recordings (events) from the recordings directory.
+      operationId: latest-events
+      parameters:
+      - description: Event filter
+        in: body
+        name: eventFilter
+        required: true
+        schema:
+          $ref: '#/definitions/models.EventFilter'
+      responses:
+        "200":
+          description: OK
+      summary: Get the latest recordings (events) from the recordings directory.
+      tags:
+      - general
   /api/login:
     post:
       description: Get Authorization token.
@@ -485,17 +924,17 @@ paths:
       summary: Get Authorization token.
       tags:
       - authentication
-  /api/onvif/verify:
+  /api/persistence/secondary/verify:
     post:
-      description: Will verify the ONVIF connectivity.
-      operationId: verify-onvif
+      description: Will verify the secondary persistence.
+      operationId: verify-secondary-persistence
       parameters:
-      - description: Camera Config
+      - description: Config
         in: body
-        name: cameraConfig
+        name: config
         required: true
         schema:
-          $ref: '#/definitions/models.IPCamera'
+          $ref: '#/definitions/models.Config'
       responses:
         "200":
           description: OK
@@ -503,9 +942,9 @@ paths:
             $ref: '#/definitions/models.APIResponse'
       security:
       - Bearer: []
-      summary: Will verify the ONVIF connectivity.
+      summary: Will verify the secondary persistence.
       tags:
-      - config
+      - persistence
   /api/persistence/verify:
     post:
       description: Will verify the persistence.
@@ -526,7 +965,22 @@ paths:
       - Bearer: []
       summary: Will verify the persistence.
       tags:
-      - config
+      - persistence
+  /health:
+    get:
+      description: Confirms that the Agent HTTP process can serve requests and reports
+        current camera stream and Hub heartbeat diagnostics. Operational dependency
+        failures do not change the liveness HTTP status.
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/http.HealthResponse'
+      summary: Check Agent health
+      tags:
+      - health
 securityDefinitions:
   Bearer:
     in: header

machinery/go.mod

@@ -1,145 +1,145 @@
 module github.com/kerberos-io/agent/machinery
 
-go 1.19
+go 1.26.10
 
-// replace github.com/kerberos-io/joy4 v1.0.57 => ../../../../github.com/kerberos-io/joy4
-// replace github.com/kerberos-io/onvif v0.0.6 => ../../../../github.com/kerberos-io/onvif
+replace google.golang.org/genproto => google.golang.org/genproto v0.0.0-20250519155744-55703ea1f237
 
 require (
+	github.com/Eyevinn/mp4ff v0.48.0
 	github.com/InVisionApp/conjungo v1.1.0
-	github.com/appleboy/gin-jwt/v2 v2.9.1
-	github.com/asticode/go-astits v1.11.0
-	github.com/bluenviron/gortsplib/v3 v3.6.1
-	github.com/bluenviron/mediacommon v0.5.0
+	github.com/appleboy/gin-jwt/v2 v2.10.3
+	github.com/bluenviron/gortsplib/v5 v5.6.3
+	github.com/bluenviron/mediacommon v1.14.0
 	github.com/cedricve/go-onvif v0.0.0-20200222191200-567e8ce298f6
-	github.com/deepch/vdk v0.0.19
+	github.com/creack/pty v1.1.24
+	github.com/dromara/carbon/v2 v2.6.8
 	github.com/dropbox/dropbox-sdk-go-unofficial/v6 v6.0.5
-	github.com/eclipse/paho.mqtt.golang v1.4.2
-	github.com/elastic/go-sysinfo v1.9.0
-	github.com/gin-contrib/cors v1.4.0
-	github.com/gin-contrib/pprof v1.4.0
-	github.com/gin-gonic/contrib v0.0.0-20221130124618-7e01895a63f2
-	github.com/gin-gonic/gin v1.8.2
-	github.com/golang-jwt/jwt/v4 v4.4.3
-	github.com/golang-module/carbon/v2 v2.2.3
-	github.com/gorilla/websocket v1.5.0
+	github.com/eclipse/paho.mqtt.golang v1.5.1
+	github.com/elastic/go-sysinfo v1.15.3
+	github.com/gin-contrib/cors v1.7.5
+	github.com/gin-contrib/pprof v1.5.3
+	github.com/gin-gonic/contrib v0.0.0-20250521004450-2b1292699c15
+	github.com/gin-gonic/gin v1.10.1
+	github.com/gofrs/uuid v4.4.0+incompatible
+	github.com/golang-jwt/jwt/v4 v4.5.2
+	github.com/gorilla/websocket v1.5.3
 	github.com/kellydunn/golang-geo v0.7.0
-	github.com/kerberos-io/joy4 v1.0.58
-	github.com/kerberos-io/onvif v0.0.7
+	github.com/kerberos-io/joy4 v1.0.64
+	github.com/kerberos-io/onvif v1.2.3
 	github.com/minio/minio-go/v6 v6.0.57
-	github.com/nsmith5/mjpeg v0.0.0-20200913181537-54b8ada0e53e
-	github.com/op/go-logging v0.0.0-20160315200505-970db520ece7
-	github.com/pion/rtp v1.7.13
-	github.com/pion/webrtc/v3 v3.1.50
-	github.com/sirupsen/logrus v1.9.0
-	github.com/swaggo/files v1.0.0
-	github.com/swaggo/gin-swagger v1.5.3
-	github.com/swaggo/swag v1.8.9
+	github.com/moq-dev/moq-go v0.5.7
+	github.com/nfnt/resize v0.0.0-20180221191011-83c6a9932646
+	github.com/pion/interceptor v0.1.47
+	github.com/pion/rtp v1.10.5
+	github.com/pion/webrtc/v4 v4.2.18
+	github.com/sirupsen/logrus v1.9.3
+	github.com/stretchr/testify v1.11.1
+	github.com/swaggo/files v1.0.1
+	github.com/swaggo/gin-swagger v1.6.0
+	github.com/swaggo/swag v1.16.4
 	github.com/tevino/abool v1.2.0
-	go.mongodb.org/mongo-driver v1.7.5
-	gopkg.in/DataDog/dd-trace-go.v1 v1.46.0
-	gopkg.in/natefinch/lumberjack.v2 v2.0.0
+	github.com/zaf/g711 v1.4.0
+	go.mongodb.org/mongo-driver v1.17.7
+	go.opentelemetry.io/otel v1.45.0
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.45.0
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.45.0
+	go.opentelemetry.io/otel/sdk v1.45.0
+	go.opentelemetry.io/otel/trace v1.45.0
+	golang.org/x/net v0.62.0
 )
 
 require (
-	github.com/DataDog/datadog-agent/pkg/obfuscate v0.0.0-20211129110424-6491aa3bf583 // indirect
-	github.com/DataDog/datadog-agent/pkg/remoteconfig/state v0.42.0-rc.1 // indirect
-	github.com/DataDog/datadog-go v4.8.2+incompatible // indirect
-	github.com/DataDog/datadog-go/v5 v5.0.2 // indirect
-	github.com/DataDog/go-tuf v0.3.0--fix-localmeta-fork // indirect
-	github.com/DataDog/gostackparse v0.5.0 // indirect
-	github.com/DataDog/sketches-go v1.2.1 // indirect
 	github.com/KyleBanks/depth v1.2.1 // indirect
-	github.com/Microsoft/go-winio v0.5.1 // indirect
 	github.com/PuerkitoBio/purell v1.1.1 // indirect
 	github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578 // indirect
-	github.com/asticode/go-astikit v0.30.0 // indirect
-	github.com/beevik/etree v1.1.0 // indirect
-	github.com/cespare/xxhash/v2 v2.1.2 // indirect
+	github.com/beevik/etree v1.2.0 // indirect
+	github.com/bluenviron/mediacommon/v2 v2.9.2 // indirect
+	github.com/bytedance/sonic v1.13.2 // indirect
+	github.com/bytedance/sonic/loader v0.2.4 // indirect
+	github.com/cenkalti/backoff/v5 v5.0.3 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/clbanning/mxj v1.8.4 // indirect
-	github.com/dgraph-io/ristretto v0.1.0 // indirect
-	github.com/dustin/go-humanize v1.0.0 // indirect
-	github.com/elastic/go-windows v1.0.0 // indirect
+	github.com/clbanning/mxj/v2 v2.7.0 // indirect
+	github.com/cloudwego/base64x v0.1.5 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/elastic/go-windows v1.0.2 // indirect
 	github.com/elgs/gostrgen v0.0.0-20161222160715-9d61ae07eeae // indirect
 	github.com/erikstmartin/go-testdb v0.0.0-20160219214506-8d10e4a1bae5 // indirect
-	github.com/gin-contrib/sse v0.1.0 // indirect
+	github.com/gabriel-vasile/mimetype v1.4.8 // indirect
+	github.com/gin-contrib/sse v1.0.0 // indirect
+	github.com/go-logr/logr v1.4.4 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/go-openapi/jsonpointer v0.19.5 // indirect
 	github.com/go-openapi/jsonreference v0.19.6 // indirect
 	github.com/go-openapi/spec v0.20.4 // indirect
 	github.com/go-openapi/swag v0.19.15 // indirect
-	github.com/go-playground/locales v0.14.0 // indirect
-	github.com/go-playground/universal-translator v0.18.0 // indirect
-	github.com/go-playground/validator/v10 v10.11.1 // indirect
-	github.com/go-stack/stack v1.8.0 // indirect
-	github.com/goccy/go-json v0.10.0 // indirect
-	github.com/gofrs/uuid v3.2.0+incompatible // indirect
-	github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b // indirect
-	github.com/golang/protobuf v1.5.3 // indirect
+	github.com/go-playground/locales v0.14.1 // indirect
+	github.com/go-playground/universal-translator v0.18.1 // indirect
+	github.com/go-playground/validator/v10 v10.26.0 // indirect
+	github.com/goccy/go-json v0.10.5 // indirect
 	github.com/golang/snappy v0.0.4 // indirect
-	github.com/google/go-cmp v0.5.9 // indirect
-	github.com/google/pprof v0.0.0-20210423192551-a2663126120b // indirect
-	github.com/google/uuid v1.3.0 // indirect
-	github.com/joeshaw/multierror v0.0.0-20140124173710-69b34d4ec901 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.29.0 // indirect
 	github.com/josharian/intern v1.0.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
-	github.com/klauspost/compress v1.15.0 // indirect
+	github.com/juju/errors v1.0.0 // indirect
+	github.com/klauspost/compress v1.18.7 // indirect
 	github.com/klauspost/cpuid v1.2.3 // indirect
+	github.com/klauspost/cpuid/v2 v2.2.10 // indirect
 	github.com/kylelemons/go-gypsy v1.0.0 // indirect
-	github.com/leodido/go-urn v1.2.1 // indirect
-	github.com/lib/pq v1.10.7 // indirect
-	github.com/mailru/easyjson v0.7.7 // indirect
-	github.com/mattn/go-isatty v0.0.16 // indirect
+	github.com/leodido/go-urn v1.4.0 // indirect
+	github.com/lib/pq v1.10.9 // indirect
+	github.com/mailru/easyjson v0.7.6 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/minio/md5-simd v1.1.0 // indirect
 	github.com/minio/sha256-simd v0.1.1 // indirect
 	github.com/mitchellh/go-homedir v1.1.0 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
-	github.com/onsi/gomega v1.27.4 // indirect
-	github.com/pelletier/go-toml/v2 v2.0.6 // indirect
-	github.com/philhofer/fwd v1.1.1 // indirect
-	github.com/pion/datachannel v1.5.5 // indirect
-	github.com/pion/dtls/v2 v2.1.5 // indirect
-	github.com/pion/ice/v2 v2.2.12 // indirect
-	github.com/pion/interceptor v0.1.11 // indirect
-	github.com/pion/logging v0.2.2 // indirect
-	github.com/pion/mdns v0.0.5 // indirect
+	github.com/montanaflynn/stats v0.7.1 // indirect
+	github.com/moq-dev/moq-go-ffi v0.3.7 // indirect
+	github.com/nxadm/tail v1.4.11 // indirect
+	github.com/pelletier/go-toml/v2 v2.2.3 // indirect
+	github.com/pion/datachannel v1.6.2 // indirect
+	github.com/pion/dtls/v3 v3.1.5 // indirect
+	github.com/pion/ice/v4 v4.4.0 // indirect
+	github.com/pion/logging v0.2.4 // indirect
+	github.com/pion/mdns/v2 v2.1.0 // indirect
 	github.com/pion/randutil v0.1.0 // indirect
-	github.com/pion/rtcp v1.2.10 // indirect
-	github.com/pion/sctp v1.8.5 // indirect
-	github.com/pion/sdp/v3 v3.0.6 // indirect
-	github.com/pion/srtp/v2 v2.0.10 // indirect
-	github.com/pion/stun v0.3.5 // indirect
-	github.com/pion/transport v0.14.1 // indirect
-	github.com/pion/turn/v2 v2.0.8 // indirect
-	github.com/pion/udp v0.1.1 // indirect
-	github.com/pkg/errors v0.9.1 // indirect
-	github.com/prometheus/procfs v0.8.0 // indirect
-	github.com/richardartoul/molecule v1.0.1-0.20221107223329-32cfee06a052 // indirect
-	github.com/secure-systems-lab/go-securesystemslib v0.4.0 // indirect
-	github.com/spaolacci/murmur3 v1.1.0 // indirect
-	github.com/tinylib/msgp v1.1.6 // indirect
-	github.com/ugorji/go/codec v1.2.7 // indirect
+	github.com/pion/rtcp v1.2.17 // indirect
+	github.com/pion/sctp v1.11.1 // indirect
+	github.com/pion/sdp/v3 v3.0.19 // indirect
+	github.com/pion/srtp/v3 v3.0.12 // indirect
+	github.com/pion/stun/v3 v3.1.6 // indirect
+	github.com/pion/transport/v4 v4.0.2 // indirect
+	github.com/pion/turn/v5 v5.0.12 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/prometheus/procfs v0.15.1 // indirect
+	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
+	github.com/ugorji/go/codec v1.2.12 // indirect
+	github.com/wlynxg/anet v0.0.5 // indirect
 	github.com/xdg-go/pbkdf2 v1.0.0 // indirect
-	github.com/xdg-go/scram v1.0.2 // indirect
-	github.com/xdg-go/stringprep v1.0.2 // indirect
-	github.com/youmark/pkcs8 v0.0.0-20181117223130-1be2e3e5546d // indirect
+	github.com/xdg-go/scram v1.1.2 // indirect
+	github.com/xdg-go/stringprep v1.0.4 // indirect
+	github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 // indirect
 	github.com/ziutek/mymysql v1.5.4 // indirect
-	go4.org/intern v0.0.0-20211027215823-ae77deb06f29 // indirect
-	go4.org/unsafe/assume-no-moving-gc v0.0.0-20220617031537-928513b29760 // indirect
-	golang.org/x/crypto v0.4.0 // indirect
-	golang.org/x/net v0.9.0 // indirect
-	golang.org/x/oauth2 v0.0.0-20201208152858-08078c50e5b5 // indirect
-	golang.org/x/sync v0.1.0 // indirect
-	golang.org/x/sys v0.7.0 // indirect
-	golang.org/x/text v0.9.0 // indirect
-	golang.org/x/time v0.0.0-20211116232009-f0f3c7e86c11 // indirect
-	golang.org/x/tools v0.7.0 // indirect
-	golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1 // indirect
-	google.golang.org/appengine v1.6.6 // indirect
-	google.golang.org/grpc v1.32.0 // indirect
-	google.golang.org/protobuf v1.28.1 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/otel/metric v1.45.0 // indirect
+	go.opentelemetry.io/proto/otlp v1.11.0 // indirect
+	golang.org/x/arch v0.16.0 // indirect
+	golang.org/x/crypto v0.58.1-0.20261009181718-2f1f834330b2 // indirect
+	golang.org/x/oauth2 v0.36.0 // indirect
+	golang.org/x/sync v0.24.0 // indirect
+	golang.org/x/sys v0.49.0 // indirect
+	golang.org/x/text v0.43.0 // indirect
+	golang.org/x/time v0.14.0 // indirect
+	golang.org/x/tools v0.51.0 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20260803160001-6ac0973c030d // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260803160001-6ac0973c030d // indirect
+	google.golang.org/grpc v1.83.2 // indirect
+	google.golang.org/protobuf v1.36.11 // indirect
 	gopkg.in/ini.v1 v1.42.0 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
 	howett.net/plist v0.0.0-20181124034731-591f970eefbb // indirect
-	inet.af/netaddr v0.0.0-20220617031823-097006376321 // indirect
 )

machinery/healthcheck.go

@@ -0,0 +1,47 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+)
+
+func checkAgentHealth(ctx context.Context, port string) error {
+	request, err := http.NewRequestWithContext(ctx, http.MethodGet, "http://127.0.0.1:"+port+"/health", nil)
+	if err != nil {
+		return fmt.Errorf("creating health request: %w", err)
+	}
+	client := &http.Client{
+		Timeout:   5 * time.Second,
+		Transport: &http.Transport{DisableKeepAlives: true},
+		CheckRedirect: func(*http.Request, []*http.Request) error {
+			return http.ErrUseLastResponse
+		},
+	}
+	defer client.CloseIdleConnections()
+	response, err := client.Do(request)
+	if err != nil {
+		return fmt.Errorf("requesting Agent health: %w", err)
+	}
+	defer response.Body.Close()
+	if response.StatusCode != http.StatusOK {
+		return fmt.Errorf("Agent health returned HTTP %d", response.StatusCode)
+	}
+	var health struct {
+		HTTPStatusCode   int    `json:"httpStatusCode"`
+		EntityStatusCode string `json:"entityStatusCode"`
+		Metadata         struct {
+			ApplicationName string `json:"applicationName"`
+		} `json:"metadata"`
+	}
+	if err := json.NewDecoder(io.LimitReader(response.Body, 64*1024)).Decode(&health); err != nil {
+		return fmt.Errorf("decoding Agent health: %w", err)
+	}
+	if health.HTTPStatusCode != http.StatusOK || health.EntityStatusCode != "healthy" || health.Metadata.ApplicationName != "agent" {
+		return fmt.Errorf("Agent health returned an unexpected response")
+	}
+	return nil
+}

machinery/healthcheck_test.go

@@ -0,0 +1,66 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+)
+
+func TestCheckAgentHealth(t *testing.T) {
+	tests := []struct {
+		name   string
+		status int
+		body   string
+		wantOK bool
+	}{
+		{"healthy", 200, `{"httpStatusCode":200,"entityStatusCode":"healthy","metadata":{"applicationName":"agent"}}`, true},
+		{"unhealthy status", 503, `{}`, false},
+		{"redirect", 302, `{}`, false},
+		{"invalid JSON", 200, `not JSON`, false},
+		{"wrong service", 200, `{"httpStatusCode":200,"entityStatusCode":"healthy","metadata":{"applicationName":"other"}}`, false},
+		{"unhealthy body", 200, `{"httpStatusCode":200,"entityStatusCode":"unhealthy","metadata":{"applicationName":"agent"}}`, false},
+	}
+	t.Setenv("HTTP_PROXY", "http://127.0.0.1:1")
+	t.Setenv("NO_PROXY", "")
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				if r.URL.Path != "/health" {
+					t.Errorf("path = %q, want /health", r.URL.Path)
+				}
+				w.Header().Set("Location", "/unexpected-redirect-target")
+				w.WriteHeader(test.status)
+				_, _ = w.Write([]byte(test.body))
+			}))
+			defer server.Close()
+			_, port, err := net.SplitHostPort(server.Listener.Addr().String())
+			if err != nil {
+				t.Fatal(err)
+			}
+			err = checkAgentHealth(context.Background(), port)
+			if (err == nil) != test.wantOK {
+				t.Fatalf("checkAgentHealth() = %v, wantOK %t", err, test.wantOK)
+			}
+		})
+	}
+}
+
+func TestCheckAgentHealthTimesOut(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		<-r.Context().Done()
+	}))
+	defer server.Close()
+	_, port, err := net.SplitHostPort(server.Listener.Addr().String())
+	if err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 25*time.Millisecond)
+	defer cancel()
+	if err := checkAgentHealth(ctx, port); !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("healthcheck error = %v, want context deadline exceeded", err)
+	}
+}

machinery/logging.go

@@ -0,0 +1,160 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+)
+
+const (
+	defaultLogLevel  = log.InfoLevel
+	defaultLogOutput = "text"
+)
+
+type localTimeFormatter struct {
+	timezone  *time.Location
+	formatter log.Formatter
+}
+
+func (f localTimeFormatter) Format(entry *log.Entry) ([]byte, error) {
+	entry.Time = entry.Time.In(f.timezone)
+	return f.formatter.Format(entry)
+}
+
+type componentHook struct{}
+
+func (componentHook) Levels() []log.Level {
+	return log.AllLevels
+}
+
+func (componentHook) Fire(entry *log.Entry) error {
+	if _, exists := entry.Data["component"]; exists {
+		return nil
+	}
+	entry.Data["component"] = componentFromCaller(entry.Caller)
+	return nil
+}
+
+func configureLogging(levelValue string, outputValue string, timezone *time.Location) {
+	configureLogger(log.StandardLogger(), levelValue, outputValue, timezone)
+}
+
+func configureLogger(logger *log.Logger, levelValue string, outputValue string, timezone *time.Location) {
+	if timezone == nil {
+		timezone = time.Local
+	}
+
+	level, levelErr := parseLogLevel(levelValue)
+	output, outputErr := parseLogOutput(outputValue)
+
+	logger.SetOutput(os.Stdout)
+	logger.SetLevel(level)
+	logger.SetReportCaller(true)
+	logger.SetFormatter(localTimeFormatter{
+		timezone:  timezone,
+		formatter: newLogFormatter(output),
+	})
+	installComponentHook(logger)
+
+	if levelErr != nil {
+		logger.WithFields(log.Fields{
+			"configured_level": levelValue,
+			"effective_level":  level.String(),
+		}).WithError(levelErr).Warn("invalid log level; using default")
+	}
+	if outputErr != nil {
+		logger.WithFields(log.Fields{
+			"configured_output": outputValue,
+			"effective_output":  output,
+		}).WithError(outputErr).Warn("invalid log output; using default")
+	}
+
+	logger.WithFields(log.Fields{
+		"event":         "logger_configured",
+		"log_level":     level.String(),
+		"output":        output,
+		"report_caller": logger.ReportCaller,
+		"timezone":      timezone.String(),
+	}).Debug("logging configured")
+}
+
+func installComponentHook(logger *log.Logger) {
+	for _, hooks := range logger.Hooks {
+		for _, hook := range hooks {
+			if _, ok := hook.(componentHook); ok {
+				return
+			}
+		}
+	}
+	logger.AddHook(componentHook{})
+}
+
+func componentFromCaller(frame *runtime.Frame) string {
+	if frame == nil {
+		return "unknown"
+	}
+
+	const sourceMarker = "/machinery/src/"
+	normalizedFile := filepath.ToSlash(frame.File)
+	if markerIndex := strings.Index(normalizedFile, sourceMarker); markerIndex >= 0 {
+		relativeFile := normalizedFile[markerIndex+len(sourceMarker):]
+		if directory := filepath.ToSlash(filepath.Dir(relativeFile)); directory != "." {
+			return directory
+		}
+	}
+	if strings.Contains(normalizedFile, "/machinery/") {
+		return "agent"
+	}
+	return "unknown"
+}
+
+func parseLogLevel(value string) (log.Level, error) {
+	normalized := strings.ToLower(strings.TrimSpace(value))
+	if normalized == "" {
+		return defaultLogLevel, nil
+	}
+	if normalized == "warning" {
+		normalized = "warn"
+	}
+
+	level, err := log.ParseLevel(normalized)
+	if err != nil {
+		return defaultLogLevel, fmt.Errorf("parse LOG_LEVEL: %w", err)
+	}
+	return level, nil
+}
+
+func parseLogOutput(value string) (string, error) {
+	normalized := strings.ToLower(strings.TrimSpace(value))
+	if normalized == "" {
+		return defaultLogOutput, nil
+	}
+	switch normalized {
+	case "json", "text":
+		return normalized, nil
+	default:
+		return defaultLogOutput, fmt.Errorf("unsupported LOG_OUTPUT %q", value)
+	}
+}
+
+func newLogFormatter(output string) log.Formatter {
+	callerPrettyfier := func(frame *runtime.Frame) (string, string) {
+		return filepath.Base(frame.Function), fmt.Sprintf("%s:%d", filepath.Base(frame.File), frame.Line)
+	}
+	if output == "json" {
+		return &log.JSONFormatter{
+			CallerPrettyfier: callerPrettyfier,
+			TimestampFormat:  time.RFC3339Nano,
+		}
+	}
+	return &log.TextFormatter{
+		CallerPrettyfier: callerPrettyfier,
+		FullTimestamp:    true,
+		TimestampFormat:  time.RFC3339Nano,
+	}
+}

machinery/logging_test.go

@@ -0,0 +1,165 @@
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+)
+
+func TestConfigureLoggingDebugIncludesStructuredContext(t *testing.T) {
+	logger := log.New()
+	var output bytes.Buffer
+	configureLogger(logger, "debug", "json", time.UTC)
+	logger.SetOutput(&output)
+	logger.WithField("event", "test_event").Debug("structured debug test")
+
+	lines := strings.Split(strings.TrimSpace(output.String()), "\n")
+	var entry map[string]interface{}
+	if err := json.Unmarshal([]byte(lines[len(lines)-1]), &entry); err != nil {
+		t.Fatalf("decode debug log: %v; output=%q", err, output.String())
+	}
+	for key, want := range map[string]interface{}{
+		"component": "agent",
+		"event":     "test_event",
+		"level":     "debug",
+		"msg":       "structured debug test",
+	} {
+		if got := entry[key]; got != want {
+			t.Fatalf("%s = %v, want %v", key, got, want)
+		}
+	}
+	if entry["file"] == nil || entry["func"] == nil {
+		t.Fatalf("debug log is missing caller metadata: %v", entry)
+	}
+}
+
+func TestConfigureLoggerInstallsComponentHookOnce(t *testing.T) {
+	logger := log.New()
+	configureLogger(logger, "info", "text", time.UTC)
+	configureLogger(logger, "debug", "json", time.UTC)
+
+	var componentHooks int
+	for _, hooks := range logger.Hooks {
+		for _, hook := range hooks {
+			if _, ok := hook.(componentHook); ok {
+				componentHooks++
+			}
+		}
+	}
+	if componentHooks != len(log.AllLevels) {
+		t.Fatalf("component hook registrations = %d, want %d", componentHooks, len(log.AllLevels))
+	}
+}
+
+func TestComponentFromCaller(t *testing.T) {
+	tests := []struct {
+		name  string
+		frame *runtime.Frame
+		want  string
+	}{
+		{
+			name:  "nested runtime package",
+			frame: &runtime.Frame{File: "/workspace/agent/machinery/src/routers/mqtt/main.go"},
+			want:  "routers/mqtt",
+		},
+		{
+			name:  "top-level runtime package",
+			frame: &runtime.Frame{File: "/workspace/agent/machinery/src/capture/main.go"},
+			want:  "capture",
+		},
+		{
+			name:  "executable",
+			frame: &runtime.Frame{File: "/workspace/agent/machinery/main.go"},
+			want:  "agent",
+		},
+		{name: "missing caller", want: "unknown"},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if got := componentFromCaller(test.frame); got != test.want {
+				t.Fatalf("componentFromCaller() = %q, want %q", got, test.want)
+			}
+		})
+	}
+}
+
+func TestComponentHookAddsAndPreservesComponent(t *testing.T) {
+	hook := componentHook{}
+
+	entry := log.NewEntry(log.New())
+	entry.Caller = &runtime.Frame{File: "/workspace/agent/machinery/src/cloud/livehls/session.go"}
+	if err := hook.Fire(entry); err != nil {
+		t.Fatalf("componentHook.Fire() error = %v", err)
+	}
+	if got := entry.Data["component"]; got != "cloud/livehls" {
+		t.Fatalf("component = %v, want cloud/livehls", got)
+	}
+
+	entry.Data["component"] = "explicit"
+	if err := hook.Fire(entry); err != nil {
+		t.Fatalf("componentHook.Fire() preserving field error = %v", err)
+	}
+	if got := entry.Data["component"]; got != "explicit" {
+		t.Fatalf("component = %v, want explicit", got)
+	}
+}
+
+func TestParseLogLevel(t *testing.T) {
+	tests := []struct {
+		name    string
+		value   string
+		want    log.Level
+		wantErr bool
+	}{
+		{name: "default", want: log.InfoLevel},
+		{name: "info", value: "INFO", want: log.InfoLevel},
+		{name: "warning alias", value: "warning", want: log.WarnLevel},
+		{name: "debug", value: "debug", want: log.DebugLevel},
+		{name: "trace", value: "trace", want: log.TraceLevel},
+		{name: "invalid", value: "verbose", want: log.InfoLevel, wantErr: true},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			got, err := parseLogLevel(test.value)
+			if (err != nil) != test.wantErr {
+				t.Fatalf("parseLogLevel(%q) error = %v, wantErr %t", test.value, err, test.wantErr)
+			}
+			if got != test.want {
+				t.Fatalf("parseLogLevel(%q) = %s, want %s", test.value, got, test.want)
+			}
+		})
+	}
+}
+
+func TestParseLogOutput(t *testing.T) {
+	tests := []struct {
+		name    string
+		value   string
+		want    string
+		wantErr bool
+	}{
+		{name: "default", want: "text"},
+		{name: "text", value: "TEXT", want: "text"},
+		{name: "json", value: "json", want: "json"},
+		{name: "invalid", value: "console", want: "text", wantErr: true},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			got, err := parseLogOutput(test.value)
+			if (err != nil) != test.wantErr {
+				t.Fatalf("parseLogOutput(%q) error = %v, wantErr %t", test.value, err, test.wantErr)
+			}
+			if got != test.want {
+				t.Fatalf("parseLogOutput(%q) = %q, want %q", test.value, got, test.want)
+			}
+		})
+	}
+}

machinery/main.go

@@ -3,53 +3,88 @@ package main
 import (
 	"context"
 	"flag"
+	"fmt"
 	"os"
+	"strconv"
+	"strings"
 	"time"
 
+	"github.com/kerberos-io/agent/machinery/src/capture"
 	"github.com/kerberos-io/agent/machinery/src/components"
-	"github.com/kerberos-io/agent/machinery/src/log"
 	"github.com/kerberos-io/agent/machinery/src/models"
+	"github.com/kerberos-io/agent/machinery/src/onvif"
+	log "github.com/sirupsen/logrus"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/exporters/otlp/otlptrace"
+	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
+	"go.opentelemetry.io/otel/sdk/resource"
+	"go.opentelemetry.io/otel/sdk/trace"
+	semconv "go.opentelemetry.io/otel/semconv/v1.4.0"
 
 	configService "github.com/kerberos-io/agent/machinery/src/config"
 	"github.com/kerberos-io/agent/machinery/src/routers"
 	"github.com/kerberos-io/agent/machinery/src/utils"
-	"gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer"
-	"gopkg.in/DataDog/dd-trace-go.v1/profiler"
 )
 
-var VERSION = "3.0.0"
+var VERSION = utils.VERSION
+
+func resolveServerPort(flagValue, environmentValue string) (string, error) {
+	value := strings.TrimSpace(environmentValue)
+	if value == "" {
+		value = strings.TrimSpace(flagValue)
+	}
+	if value == "" {
+		value = "80"
+	}
+
+	port, err := strconv.Atoi(value)
+	if err != nil || port < 1 || port > 65535 {
+		return "", fmt.Errorf("port must be an integer between 1 and 65535, got %q", value)
+	}
+	return strconv.Itoa(port), nil
+}
+
+func startTracing(agentKey string, otelEndpoint string) (*trace.TracerProvider, error) {
+	serviceName := "agent-" + agentKey
+	headers := map[string]string{
+		"content-type": "application/json",
+	}
+
+	exporter, err := otlptrace.New(
+		context.Background(),
+		otlptracehttp.NewClient(
+			otlptracehttp.WithEndpoint(otelEndpoint),
+			otlptracehttp.WithHeaders(headers),
+			otlptracehttp.WithInsecure(),
+		),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("creating new exporter: %w", err)
+	}
+
+	tracerprovider := trace.NewTracerProvider(
+		trace.WithBatcher(
+			exporter,
+			trace.WithMaxExportBatchSize(trace.DefaultMaxExportBatchSize),
+			trace.WithBatchTimeout(trace.DefaultScheduleDelay*time.Millisecond),
+			trace.WithMaxExportBatchSize(trace.DefaultMaxExportBatchSize),
+		),
+		trace.WithResource(
+			resource.NewWithAttributes(
+				semconv.SchemaURL,
+				semconv.ServiceNameKey.String(serviceName),
+				attribute.String("environment", "develop"),
+			),
+		),
+	)
+
+	otel.SetTracerProvider(tracerprovider)
+
+	return tracerprovider, nil
+}
 
 func main() {
-	// You might be interested in debugging the agent.
-	if os.Getenv("DATADOG_AGENT_ENABLED") == "true" {
-		if os.Getenv("DATADOG_AGENT_K8S_ENABLED") == "true" {
-			tracer.Start()
-			defer tracer.Stop()
-		} else {
-			service := os.Getenv("DATADOG_AGENT_SERVICE")
-			environment := os.Getenv("DATADOG_AGENT_ENVIRONMENT")
-			log.Log.Info("Starting Datadog Agent with service: " + service + " and environment: " + environment)
-			rules := []tracer.SamplingRule{tracer.RateRule(1)}
-			tracer.Start(
-				tracer.WithSamplingRules(rules),
-				tracer.WithService(service),
-				tracer.WithEnv(environment),
-			)
-			defer tracer.Stop()
-			err := profiler.Start(
-				profiler.WithService(service),
-				profiler.WithEnv(environment),
-				profiler.WithProfileTypes(
-					profiler.CPUProfile,
-					profiler.HeapProfile,
-				),
-			)
-			if err != nil {
-				log.Log.Fatal(err.Error())
-			}
-			defer profiler.Stop()
-		}
-	}
 
 	// Start the show ;)
 	// We'll parse the flags (named variables), and start the agent.
@@ -59,28 +94,107 @@ func main() {
 	var name string
 	var port string
 	var timeout string
+	var subnet string
 
-	flag.StringVar(&action, "action", "version", "Tell us what you want do 'run' or 'version'")
+	flag.StringVar(&action, "action", "version", "Action: run, version, healthcheck, discover, or decrypt")
 	flag.StringVar(&configDirectory, "config", ".", "Where is the configuration stored")
 	flag.StringVar(&name, "name", "agent", "Provide a name for the agent")
 	flag.StringVar(&port, "port", "80", "On which port should the agent run")
 	flag.StringVar(&timeout, "timeout", "2000", "Number of milliseconds to wait for the ONVIF discovery to complete")
+	flag.StringVar(&subnet, "subnet", "", "Optional subnet(s) to scan for discovery, e.g. '192.168.1.0/24' (comma-separated). Defaults to the local interfaces.")
 	flag.Parse()
 
+	// Specify the level of loggin: "info", "warning", "debug", "error" or "fatal."
+	logLevel := os.Getenv("LOG_LEVEL")
+	if logLevel == "" {
+		logLevel = "info"
+	}
+	// Specify the output formatter of the log: "text" or "json".
+	logOutput := os.Getenv("LOG_OUTPUT")
+	if logOutput == "" {
+		logOutput = "text"
+	}
+	// Specify the timezone of the log: "UTC" or "Local".
 	timezone, _ := time.LoadLocation("CET")
-	log.Log.Init(configDirectory, timezone)
+	configureLogging(logLevel, logOutput, timezone)
+	if action == "run" || action == "healthcheck" {
+		resolvedPort, err := resolveServerPort(port, os.Getenv("AGENT_PORT"))
+		if err != nil {
+			log.WithError(err).WithFields(log.Fields{
+				"component": "http",
+				"event":     "server_port_invalid",
+			}).Fatal("Invalid HTTP server port")
+			return
+		}
+		port = resolvedPort
+	}
+	log.WithFields(log.Fields{
+		"action":           action,
+		"component":        "agent",
+		"config_directory": configDirectory,
+		"event":            "command_parsed",
+		"port":             port,
+		"version":          VERSION,
+	}).Debug("Agent command parsed")
 
 	switch action {
 
+	case "healthcheck":
+		if err := checkAgentHealth(context.Background(), port); err != nil {
+			log.WithError(err).WithFields(log.Fields{
+				"component": "healthcheck",
+				"event":     "healthcheck_failed",
+			}).Fatal("Agent healthcheck failed")
+		}
 	case "version":
-		log.Log.Info("You are currrently running Kerberos Agent " + VERSION)
-
+		{
+			log.WithFields(log.Fields{
+				"component": "agent",
+				"event":     "version",
+				"version":   VERSION,
+			}).Info("Kerberos Agent version")
+		}
 	case "discover":
-		log.Log.Info(timeout)
+		{
+			// Convert duration to int
+			timeout, err := time.ParseDuration(timeout + "ms")
+			if err != nil {
+				log.WithError(err).WithField("component", "onvif").
+					Fatal("invalid ONVIF discovery timeout")
+				return
+			}
+			var subnets []string
+			for _, part := range strings.Split(subnet, ",") {
+				if trimmed := strings.TrimSpace(part); trimmed != "" {
+					subnets = append(subnets, trimmed)
+				}
+			}
+			onvif.Discover(timeout, subnets...)
+		}
+	case "decrypt":
+		{
+			log.WithFields(log.Fields{
+				"component": "encryption",
+				"event":     "decrypt_started",
+				"path":      flag.Arg(0),
+			}).Info("Decrypting recording")
+			symmetricKey := []byte(flag.Arg(1))
+
+			if len(symmetricKey) == 0 {
+				log.Fatal("main.Main(): symmetric key should not be empty")
+				return
+			}
+			if len(symmetricKey) != 32 {
+				log.Fatal("main.Main(): symmetric key should be 32 bytes")
+				return
+			}
+
+			utils.Decrypt(flag.Arg(0), symmetricKey)
+		}
 
 	case "run":
 		{
-			// Print Kerberos.io ASCII art
+			// Print Agent ASCII art
 			utils.PrintASCIIArt()
 
 			// Print the environment variables which include "AGENT_" as prefix.
@@ -93,12 +207,38 @@ func main() {
 			configuration.Name = name
 			configuration.Port = port
 
-			// Open this configuration either from Kerberos Agent or Kerberos Factory.
+			// Open this configuration either from Agent or Factory.
 			configService.OpenConfig(configDirectory, &configuration)
 
 			// We will override the configuration with the environment variables
 			configService.OverrideWithEnvironmentVariables(&configuration)
 
+			// Start OpenTelemetry tracing
+			if otelEndpoint := os.Getenv("OTEL_EXPORTER_OTLP_ENDPOINT"); otelEndpoint == "" {
+				log.WithFields(log.Fields{
+					"component": "tracing",
+					"event":     "tracing_disabled",
+				}).Debug("OpenTelemetry tracing disabled")
+			} else {
+				log.WithFields(log.Fields{
+					"component": "tracing",
+					"event":     "tracing_starting",
+				}).Info("Starting OpenTelemetry tracing")
+				agentKey := configuration.Config.Key
+				traceProvider, err := startTracing(agentKey, otelEndpoint)
+				if err != nil {
+					log.WithError(err).WithField("component", "tracing").
+						Error("Failed to start OpenTelemetry tracing")
+				} else {
+					defer func() {
+						if err := traceProvider.Shutdown(context.Background()); err != nil {
+							log.WithError(err).WithField("component", "tracing").
+								Error("Failed to shut down OpenTelemetry tracing")
+						}
+					}()
+				}
+			}
+
 			// Printing final configuration
 			utils.PrintConfiguration(&configuration)
 
@@ -107,8 +247,13 @@ func main() {
 			utils.CheckDataDirectoryPermissions(configDirectory)
 
 			// Set timezone
-			timezone, _ := time.LoadLocation(configuration.Config.Timezone)
-			log.Log.Init(configDirectory, timezone)
+			timezone, err := time.LoadLocation(configuration.Config.Timezone)
+			if err != nil {
+				log.WithError(err).WithField("timezone", configuration.Config.Timezone).
+					Warn("invalid Agent timezone; using the host timezone for logs")
+				timezone = time.Local
+			}
+			configureLogging(logLevel, logOutput, timezone)
 
 			// Check if we have a device Key or not, if not
 			// we will generate one.
@@ -117,28 +262,45 @@ func main() {
 				configuration.Config.Key = key
 				err := configService.StoreConfig(configDirectory, configuration.Config)
 				if err == nil {
-					log.Log.Info("Main: updated unique key for agent to: " + key)
+					log.WithFields(log.Fields{
+						"component": "configuration",
+						"event":     "agent_key_generated",
+					}).Info("Generated and stored a unique Agent key")
 				} else {
-					log.Log.Info("Main: something went wrong while trying to store key: " + key)
+					log.WithError(err).WithFields(log.Fields{
+						"component": "configuration",
+						"event":     "agent_key_store_failed",
+					}).Error("Failed to store the generated Agent key")
 				}
 			}
 
 			// Create a cancelable context, which will be used to cancel and restart.
 			// This is used to restart the agent when the configuration is updated.
 			ctx, cancel := context.WithCancel(context.Background())
+			defer cancel()
+
+			// We create a capture object, this will contain all the streaming clients.
+			// And allow us to extract media from within difference places in the agent.
+			capture := capture.Capture{}
 
 			// Bootstrapping the agent
 			communication := models.Communication{
-				Context:         &ctx,
-				CancelContext:   &cancel,
 				HandleBootstrap: make(chan string, 1),
 			}
-			go components.Bootstrap(configDirectory, &configuration, &communication)
+
+			log.WithFields(log.Fields{
+				"component": "agent",
+				"event":     "runtime_starting",
+				"port":      configuration.Port,
+			}).Info("Starting Agent runtime")
+			go components.Bootstrap(ctx, configDirectory, &configuration, &communication, &capture)
 
 			// Start the REST API.
-			routers.StartWebserver(configDirectory, &configuration, &communication)
+			routers.StartWebserver(configDirectory, &configuration, &communication, &capture)
 		}
 	default:
-		log.Log.Error("Main: Sorry I don't understand :(")
+		{
+			log.Error("main.Main(): Sorry I don't understand :(")
+		}
 	}
 }

machinery/main_test.go

@@ -0,0 +1,33 @@
+package main
+
+import "testing"
+
+func TestResolveServerPort(t *testing.T) {
+	tests := []struct {
+		name      string
+		flagValue string
+		envValue  string
+		want      string
+		wantError bool
+	}{
+		{name: "flag default", flagValue: "80", want: "80"},
+		{name: "environment overrides flag", flagValue: "80", envValue: "8082", want: "8082"},
+		{name: "trims environment", flagValue: "80", envValue: " 9090 ", want: "9090"},
+		{name: "empty values use default", want: "80"},
+		{name: "invalid text", flagValue: "80", envValue: "http", wantError: true},
+		{name: "zero", flagValue: "80", envValue: "0", wantError: true},
+		{name: "above maximum", flagValue: "80", envValue: "65536", wantError: true},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			got, err := resolveServerPort(test.flagValue, test.envValue)
+			if (err != nil) != test.wantError {
+				t.Fatalf("resolveServerPort(%q, %q) error = %v, wantError %t", test.flagValue, test.envValue, err, test.wantError)
+			}
+			if got != test.want {
+				t.Fatalf("resolveServerPort(%q, %q) = %q, want %q", test.flagValue, test.envValue, got, test.want)
+			}
+		})
+	}
+}

machinery/src/api/onvif.go

@@ -1 +0,0 @@
-package api

machinery/src/capture/IPCamera.go

@@ -1,150 +0,0 @@
-package capture
-
-import (
-	"context"
-	"strconv"
-	"sync"
-	"time"
-
-	"github.com/kerberos-io/agent/machinery/src/log"
-	"github.com/kerberos-io/agent/machinery/src/models"
-	"github.com/kerberos-io/joy4/av/pubsub"
-
-	"github.com/kerberos-io/joy4/av"
-	"github.com/kerberos-io/joy4/av/avutil"
-	"github.com/kerberos-io/joy4/cgo/ffmpeg"
-	"github.com/kerberos-io/joy4/format"
-)
-
-func OpenRTSP(ctx context.Context, url string) (av.DemuxCloser, []av.CodecData, error) {
-	format.RegisterAll()
-	infile, err := avutil.Open(ctx, url)
-	if err == nil {
-		streams, errstreams := infile.Streams()
-		return infile, streams, errstreams
-	}
-	return nil, []av.CodecData{}, err
-}
-
-func GetVideoStream(streams []av.CodecData) (av.CodecData, error) {
-	var videoStream av.CodecData
-	for _, stream := range streams {
-		if stream.Type().IsAudio() {
-			//astream := stream.(av.AudioCodecData)
-		} else if stream.Type().IsVideo() {
-			videoStream = stream
-		}
-	}
-	return videoStream, nil
-}
-
-func GetVideoDecoder(decoder *ffmpeg.VideoDecoder, streams []av.CodecData) {
-	// Load video codec
-	var vstream av.VideoCodecData
-	for _, stream := range streams {
-		if stream.Type().IsAudio() {
-			//astream := stream.(av.AudioCodecData)
-		} else if stream.Type().IsVideo() {
-			vstream = stream.(av.VideoCodecData)
-		}
-	}
-	err := ffmpeg.NewVideoDecoder(decoder, vstream)
-	if err != nil {
-		log.Log.Error("GetVideoDecoder: " + err.Error())
-	}
-}
-
-func DecodeImage(frame *ffmpeg.VideoFrame, pkt av.Packet, decoder *ffmpeg.VideoDecoder, decoderMutex *sync.Mutex) (*ffmpeg.VideoFrame, error) {
-	decoderMutex.Lock()
-	img, err := decoder.Decode(frame, pkt.Data)
-	decoderMutex.Unlock()
-	return img, err
-}
-
-func HandleStream(infile av.DemuxCloser, queue *pubsub.Queue, communication *models.Communication) { //, wg *sync.WaitGroup) {
-
-	log.Log.Debug("HandleStream: started")
-	var err error
-loop:
-	for {
-		// This will check if we need to stop the thread,
-		// because of a reconfiguration.
-		select {
-		case <-communication.HandleStream:
-			break loop
-		default:
-		}
-
-		var pkt av.Packet
-		if pkt, err = infile.ReadPacket(); err != nil { // sometimes this throws an end of file..
-			log.Log.Error("HandleStream: " + err.Error())
-			time.Sleep(1 * time.Second)
-		}
-
-		// Could be that a decode is throwing errors.
-		if len(pkt.Data) > 0 {
-
-			queue.WritePacket(pkt)
-
-			// This will check if we need to stop the thread,
-			// because of a reconfiguration.
-			select {
-			case <-communication.HandleStream:
-				break loop
-			default:
-			}
-
-			if pkt.IsKeyFrame {
-
-				// Increment packets, so we know the device
-				// is not blocking.
-				r := communication.PackageCounter.Load().(int64)
-				log.Log.Info("HandleStream: packet size " + strconv.Itoa(len(pkt.Data)))
-				communication.PackageCounter.Store((r + 1) % 1000)
-				communication.LastPacketTimer.Store(time.Now().Unix())
-			}
-		}
-	}
-
-	queue.Close()
-	log.Log.Debug("HandleStream: finished")
-}
-
-func HandleSubStream(infile av.DemuxCloser, queue *pubsub.Queue, communication *models.Communication) { //, wg *sync.WaitGroup) {
-
-	log.Log.Debug("HandleSubStream: started")
-	var err error
-loop:
-	for {
-		// This will check if we need to stop the thread,
-		// because of a reconfiguration.
-		select {
-		case <-communication.HandleSubStream:
-			break loop
-		default:
-		}
-
-		var pkt av.Packet
-		if pkt, err = infile.ReadPacket(); err != nil { // sometimes this throws an end of file..
-			log.Log.Error("HandleSubStream: " + err.Error())
-			time.Sleep(1 * time.Second)
-		}
-
-		// Could be that a decode is throwing errors.
-		if len(pkt.Data) > 0 {
-
-			queue.WritePacket(pkt)
-
-			// This will check if we need to stop the thread,
-			// because of a reconfiguration.
-			select {
-			case <-communication.HandleSubStream:
-				break loop
-			default:
-			}
-		}
-	}
-
-	queue.Close()
-	log.Log.Debug("HandleSubStream: finished")
-}

machinery/src/capture/cleanup_test.go

@@ -0,0 +1,285 @@
+package capture
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+	"time"
+
+	"github.com/kerberos-io/agent/machinery/src/models"
+)
+
+func TestPickRecordingToCleanupAcrossDatedDirectories(t *testing.T) {
+	for _, legacyMarker := range []bool{false, true} {
+		t.Run(map[bool]string{false: "metadata", true: "legacy"}[legacyMarker], func(t *testing.T) {
+			recordingsDir, cloudDir := newCleanupDirs(t)
+			pendingName := "2026/01/01/oldest_pending.mp4"
+			safeName := "2026/01/02/uploaded.mp4"
+			writeRecording(t, recordingsDir, pendingName, 30)
+			if legacyMarker {
+				if err := os.WriteFile(filepath.Join(cloudDir, filepath.Base(pendingName)), nil, 0o644); err != nil {
+					t.Fatal(err)
+				}
+			} else {
+				markPending(t, cloudDir, pendingName)
+			}
+			writeRecording(t, recordingsDir, safeName, 20)
+			writeRecording(t, recordingsDir, "flat_uploaded.mp4", 10)
+			name, pending, err := pickRecordingToCleanup(recordingsDir, cloudDir)
+			if err != nil || pending || name != safeName {
+				t.Fatalf("cleanup = (%q, %v, %v), want (%q, false, nil)", name, pending, err, safeName)
+			}
+		})
+	}
+}
+
+func TestCleanupDatedPendingRecordingRemovesFlatMarker(t *testing.T) {
+	recordingsDir, cloudDir := newCleanupDirs(t)
+	name := "2026/01/01/pending.mp4"
+	if err := os.MkdirAll(filepath.Dir(filepath.Join(recordingsDir, name)), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	writeSizedRecording(t, recordingsDir, name, 2*1000*1000)
+	markPending(t, cloudDir, name)
+	config := &models.Configuration{Config: models.Config{AutoClean: "true", MaxDirectorySize: 1}}
+	CleanupRecordingDirectory(filepath.Dir(filepath.Dir(recordingsDir)), config)
+	for _, filePath := range []string{
+		filepath.Join(recordingsDir, name),
+		filepath.Join(cloudDir, models.RecordingUploadMetadataFileName(name)),
+	} {
+		if _, err := os.Stat(filePath); !os.IsNotExist(err) {
+			t.Fatalf("expected %s to be removed, got %v", filePath, err)
+		}
+	}
+}
+
+// writeRecording creates a file under recordingsDir and sets its modtime so the
+// tests can control the "oldest" ordering deterministically.
+func writeRecording(t *testing.T, recordingsDir, name string, ageMinutes int) {
+	t.Helper()
+	full := filepath.Join(recordingsDir, name)
+	if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+		t.Fatalf("mkdir recording directory: %v", err)
+	}
+	if err := os.WriteFile(full, []byte("data"), 0o644); err != nil {
+		t.Fatalf("write recording %s: %v", name, err)
+	}
+	mod := time.Now().Add(-time.Duration(ageMinutes) * time.Minute)
+	if err := os.Chtimes(full, mod, mod); err != nil {
+		t.Fatalf("chtimes %s: %v", name, err)
+	}
+}
+
+// markPending creates the upload marker in cloudDir for the given recording,
+// marking it as still queued for upload.
+func markPending(t *testing.T, cloudDir, name string) {
+	t.Helper()
+	markerName := models.RecordingUploadMetadataFileName(name)
+	if err := os.WriteFile(filepath.Join(cloudDir, markerName), nil, 0o644); err != nil {
+		t.Fatalf("write marker %s: %v", name, err)
+	}
+}
+
+func newCleanupDirs(t *testing.T) (string, string) {
+	t.Helper()
+	base := t.TempDir()
+	recordingsDir := filepath.Join(base, "data", "recordings")
+	cloudDir := filepath.Join(base, "data", "cloud")
+	if err := os.MkdirAll(recordingsDir, 0o755); err != nil {
+		t.Fatalf("mkdir recordings: %v", err)
+	}
+	if err := os.MkdirAll(cloudDir, 0o755); err != nil {
+		t.Fatalf("mkdir cloud: %v", err)
+	}
+	return recordingsDir, cloudDir
+}
+
+// The core regression: when the oldest recording is still pending upload but a
+// newer one has already been uploaded, cleanup must delete the uploaded (safe)
+// one and leave the pending recording on disk so it can still be uploaded.
+func TestPickRecordingToCleanup_PrefersUploaded(t *testing.T) {
+	recordingsDir, cloudDir := newCleanupDirs(t)
+
+	// oldest is still pending upload (marker present).
+	writeRecording(t, recordingsDir, "oldest_pending.mp4", 30)
+	markPending(t, cloudDir, "oldest_pending.mp4")
+	// newer one has already been uploaded (no marker).
+	writeRecording(t, recordingsDir, "newer_uploaded.mp4", 10)
+
+	name, pending, err := pickRecordingToCleanup(recordingsDir, cloudDir)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if pending {
+		t.Fatalf("expected a safe (already-uploaded) deletion, got pending=true")
+	}
+	if name != "newer_uploaded.mp4" {
+		t.Fatalf("cleanup picked %q, want the uploaded recording newer_uploaded.mp4", name)
+	}
+}
+
+func TestPickRecordingToCleanup_RecognizesLegacyMarkerName(t *testing.T) {
+	recordingsDir, cloudDir := newCleanupDirs(t)
+
+	writeRecording(t, recordingsDir, "legacy_pending.mp4", 30)
+	if err := os.WriteFile(filepath.Join(cloudDir, "legacy_pending.mp4"), nil, 0o644); err != nil {
+		t.Fatalf("write legacy marker: %v", err)
+	}
+	writeRecording(t, recordingsDir, "uploaded.mp4", 10)
+
+	name, pending, err := pickRecordingToCleanup(recordingsDir, cloudDir)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if pending || name != "uploaded.mp4" {
+		t.Fatalf("cleanup picked name=%q pending=%v, want uploaded.mp4 pending=false", name, pending)
+	}
+}
+
+// Among several already-uploaded recordings, the oldest uploaded one is chosen.
+func TestPickRecordingToCleanup_OldestUploadedFirst(t *testing.T) {
+	recordingsDir, cloudDir := newCleanupDirs(t)
+
+	writeRecording(t, recordingsDir, "old_uploaded.mp4", 40)
+	writeRecording(t, recordingsDir, "mid_uploaded.mp4", 20)
+	// pending one must be ignored even though it is not the oldest.
+	writeRecording(t, recordingsDir, "pending.mp4", 30)
+	markPending(t, cloudDir, "pending.mp4")
+
+	name, pending, err := pickRecordingToCleanup(recordingsDir, cloudDir)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if pending {
+		t.Fatalf("expected pending=false, got true")
+	}
+	if name != "old_uploaded.mp4" {
+		t.Fatalf("cleanup picked %q, want old_uploaded.mp4", name)
+	}
+}
+
+// Last resort: when every recording is still pending upload, cleanup returns the
+// oldest one with pending=true so the caller can drop it (and its marker) to keep
+// the disk bounded.
+func TestPickRecordingToCleanup_AllPendingFallsBackToOldest(t *testing.T) {
+	recordingsDir, cloudDir := newCleanupDirs(t)
+
+	writeRecording(t, recordingsDir, "a_old.mp4", 50)
+	markPending(t, cloudDir, "a_old.mp4")
+	writeRecording(t, recordingsDir, "b_new.mp4", 5)
+	markPending(t, cloudDir, "b_new.mp4")
+
+	name, pending, err := pickRecordingToCleanup(recordingsDir, cloudDir)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !pending {
+		t.Fatalf("expected pending=true when every recording is queued for upload")
+	}
+	if name != "a_old.mp4" {
+		t.Fatalf("cleanup picked %q, want the oldest pending a_old.mp4", name)
+	}
+}
+
+// An empty recordings directory yields os.ErrNotExist so the caller does nothing.
+func TestPickRecordingToCleanup_Empty(t *testing.T) {
+	recordingsDir, cloudDir := newCleanupDirs(t)
+
+	if _, _, err := pickRecordingToCleanup(recordingsDir, cloudDir); err != os.ErrNotExist {
+		t.Fatalf("expected os.ErrNotExist for an empty directory, got %v", err)
+	}
+}
+
+// writeSizedRecording writes a recording of an exact byte size so tests can
+// exercise the megabyte-based directory-cap threshold.
+func writeSizedRecording(t *testing.T, dir, name string, size int) {
+	t.Helper()
+	if err := os.WriteFile(filepath.Join(dir, name), make([]byte, size), 0o644); err != nil {
+		t.Fatalf("write sized recording %s: %v", name, err)
+	}
+}
+
+// When AGENT_AUTO_CLEAN_MAX_SIZE (MaxDirectorySize) is set, cleanup triggers once
+// the recordings directory grows past that many megabytes.
+func TestRecordingsNeedCleanup_FixedCap(t *testing.T) {
+	recordingsDir, _ := newCleanupDirs(t)
+	// ~2 MB of recordings on disk.
+	writeSizedRecording(t, recordingsDir, "big.mp4", 2*1000*1000)
+
+	over := &models.Configuration{Config: models.Config{MaxDirectorySize: 1}}
+	need, err := recordingsNeedCleanup(recordingsDir, over)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !need {
+		t.Fatalf("expected cleanup when 2MB of recordings exceed the 1MB cap")
+	}
+
+	under := &models.Configuration{Config: models.Config{MaxDirectorySize: 100}}
+	need, err = recordingsNeedCleanup(recordingsDir, under)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if need {
+		t.Fatalf("expected no cleanup when 2MB of recordings stay under the 100MB cap")
+	}
+}
+
+// With no fixed cap (the default), cleanup is driven by the free space left on
+// the recordings filesystem versus the reserve.
+func TestRecordingsNeedCleanup_DefaultDiskReserve(t *testing.T) {
+	if runtime.GOOS != "linux" {
+		t.Skip("disk usage stats are only implemented on linux")
+	}
+	recordingsDir, _ := newCleanupDirs(t)
+
+	totalMB, availableMB, err := diskUsageMB(recordingsDir)
+	if err != nil {
+		t.Fatalf("diskUsageMB: %v", err)
+	}
+	if totalMB <= 0 || availableMB <= 0 {
+		t.Skipf("unexpected disk stats total=%dMB available=%dMB", totalMB, availableMB)
+	}
+
+	// A reserve larger than the whole disk means free space is always below it.
+	over := &models.Configuration{Config: models.Config{MinFreeSpace: totalMB + availableMB}}
+	need, err := recordingsNeedCleanup(recordingsDir, over)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !need {
+		t.Fatalf("expected cleanup when free space (%dMB) is below the reserve", availableMB)
+	}
+
+	// A 1 MB reserve leaves plenty of free space, so nothing should be cleaned.
+	under := &models.Configuration{Config: models.Config{MinFreeSpace: 1}}
+	need, err = recordingsNeedCleanup(recordingsDir, under)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if need {
+		t.Fatalf("expected no cleanup when free space (%dMB) exceeds the 1MB reserve", availableMB)
+	}
+}
+
+// The default 5% reserve must never truncate to 0MB on small disks, otherwise
+// cleanup would only trigger once the disk is completely full.
+func TestDefaultReserveMB(t *testing.T) {
+	cases := []struct {
+		totalMB int64
+		want    int64
+	}{
+		{totalMB: 0, want: 1},   // no/unknown disk size still reserves 1MB
+		{totalMB: 10, want: 1},  // 5% = 0MB -> floored to 1MB
+		{totalMB: 19, want: 1},  // 5% = 0MB -> floored to 1MB
+		{totalMB: 20, want: 1},  // 5% = exactly 1MB
+		{totalMB: 100, want: 5}, // 5% = 5MB
+		{totalMB: 1000, want: 50},
+	}
+	for _, c := range cases {
+		if got := defaultReserveMB(c.totalMB); got != c.want {
+			t.Errorf("defaultReserveMB(%d) = %d, want %d", c.totalMB, got, c.want)
+		}
+	}
+}

machinery/src/capture/disk_linux.go

@@ -0,0 +1,23 @@
+//go:build linux
+
+package capture
+
+import "syscall"
+
+// diskUsageMB returns the total capacity and the currently available space (both
+// in megabytes, decimal) of the filesystem that contains path. Auto-clean uses
+// it to default its cleanup threshold to the real disk capacity instead of a
+// fixed size, so recordings can grow to fill the disk while keeping a reserve
+// free. Linux is the agent's deployment target (amd64/arm64 containers).
+func diskUsageMB(path string) (totalMB int64, availableMB int64, err error) {
+	var stat syscall.Statfs_t
+	if err = syscall.Statfs(path, &stat); err != nil {
+		return 0, 0, err
+	}
+	blockSize := int64(stat.Bsize)
+	totalMB = int64(stat.Blocks) * blockSize / 1000 / 1000
+	// Bavail is the free space available to unprivileged users, which is the
+	// space we can actually keep writing recordings into.
+	availableMB = int64(stat.Bavail) * blockSize / 1000 / 1000
+	return totalMB, availableMB, nil
+}

machinery/src/capture/disk_other.go

@@ -0,0 +1,13 @@
+//go:build !linux
+
+package capture
+
+import "errors"
+
+// diskUsageMB is only implemented on Linux (the agent's deployment target). On
+// other platforms (e.g. local macOS/Windows dev builds) auto-clean falls back to
+// its historical fixed-size directory cap, so this reports the capability as
+// unavailable.
+func diskUsageMB(path string) (totalMB int64, availableMB int64, err error) {
+	return 0, 0, errors.New("disk usage stats are not supported on this platform")
+}

machinery/src/capture/gortsplib_test.go

@@ -0,0 +1,249 @@
+package capture
+
+import (
+	"bytes"
+	"context"
+	"encoding/pem"
+	"errors"
+	"math"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/bluenviron/mediacommon/pkg/codecs/h264"
+)
+
+func TestPreRecordingGOPCount(t *testing.T) {
+	maxInt := int64(^uint(0) >> 1)
+	tests := []struct {
+		name         string
+		preRecording int64
+		gopDuration  float64
+		want         int
+		wantOK       bool
+	}{
+		{name: "normal duration", preRecording: 10, gopDuration: 2.9, want: 6, wantOK: true},
+		{name: "duration longer than buffer", preRecording: 1, gopDuration: 2, want: 1, wantOK: true},
+		{name: "largest representable result", preRecording: maxInt - 1, gopDuration: 1, want: int(maxInt), wantOK: true},
+		{name: "result exceeds int", preRecording: maxInt, gopDuration: 1, wantOK: false},
+		{name: "non-positive pre-recording", preRecording: 0, gopDuration: 1, wantOK: false},
+		{name: "sub-second GOP", preRecording: 10, gopDuration: 0.9, wantOK: false},
+		{name: "NaN GOP", preRecording: 10, gopDuration: math.NaN(), wantOK: false},
+		{name: "infinite GOP", preRecording: 10, gopDuration: math.Inf(1), wantOK: false},
+		{name: "GOP exceeds int64", preRecording: 10, gopDuration: float64(math.MaxInt64), wantOK: false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, ok := preRecordingGOPCount(tt.preRecording, tt.gopDuration)
+			if ok != tt.wantOK || got != tt.want {
+				t.Fatalf("preRecordingGOPCount(%d, %v) = (%d, %t), want (%d, %t)",
+					tt.preRecording, tt.gopDuration, got, ok, tt.want, tt.wantOK)
+			}
+		})
+	}
+}
+
+func TestGolibrtspCloseBeforeClientStart(t *testing.T) {
+	client := &Golibrtsp{}
+
+	if err := client.Close(context.Background()); err != nil {
+		t.Fatalf("Close() error = %v", err)
+	}
+}
+
+func TestSanitizeRTSPErrorRemovesCredentialsAndQuery(t *testing.T) {
+	rawURL := "rtsp://camera-user:camera-password@10.0.20.15/live?access_token=secret"
+	got := sanitizeRTSPError(errors.New("describe "+rawURL+": bad status code"), rawURL)
+
+	for _, secret := range []string{"camera-user", "camera-password", "access_token", "secret"} {
+		if strings.Contains(got.Error(), secret) {
+			t.Fatalf("sanitizeRTSPError() exposed %q in %q", secret, got)
+		}
+	}
+	if !strings.Contains(got.Error(), "rtsp://10.0.20.15/live") {
+		t.Fatalf("sanitizeRTSPError() removed useful host/path context: %q", got)
+	}
+}
+
+func TestRTSPSTLSConfig(t *testing.T) {
+	t.Run("verifies certificates by default", func(t *testing.T) {
+		t.Setenv(rtspsCAFileEnv, "")
+		t.Setenv(rtspsInsecureEnv, "")
+
+		got, err := rtspsTLSConfig()
+		if err != nil {
+			t.Fatalf("rtspsTLSConfig() error = %v", err)
+		}
+		if got != nil {
+			t.Fatalf("rtspsTLSConfig() = %#v, want nil", got)
+		}
+	})
+
+	t.Run("allows explicit insecure mode", func(t *testing.T) {
+		t.Setenv(rtspsCAFileEnv, "/missing/ignored-in-insecure-mode.pem")
+		t.Setenv(rtspsInsecureEnv, "true")
+
+		got, err := rtspsTLSConfig()
+		if err != nil {
+			t.Fatalf("rtspsTLSConfig() error = %v", err)
+		}
+		if got == nil || !got.InsecureSkipVerify {
+			t.Fatalf("rtspsTLSConfig() = %#v, want InsecureSkipVerify enabled", got)
+		}
+	})
+
+	t.Run("adds a camera CA to system roots", func(t *testing.T) {
+		t.Setenv(rtspsInsecureEnv, "")
+		server := httptest.NewTLSServer(nil)
+		defer server.Close()
+
+		certificate := server.Certificate()
+		caFile := filepath.Join(t.TempDir(), "camera-ca.pem")
+		caPEM := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: certificate.Raw})
+		if err := os.WriteFile(caFile, caPEM, 0o600); err != nil {
+			t.Fatal(err)
+		}
+		t.Setenv(rtspsCAFileEnv, caFile)
+
+		got, err := rtspsTLSConfig()
+		if err != nil {
+			t.Fatalf("rtspsTLSConfig() error = %v", err)
+		}
+		if got == nil || got.RootCAs == nil {
+			t.Fatalf("rtspsTLSConfig() = %#v, want custom RootCAs", got)
+		}
+		for _, subject := range got.RootCAs.Subjects() {
+			if bytes.Equal(subject, certificate.RawSubject) {
+				return
+			}
+		}
+		t.Fatal("camera CA was not added to RootCAs")
+	})
+
+	t.Run("rejects an invalid camera CA file", func(t *testing.T) {
+		t.Setenv(rtspsInsecureEnv, "")
+		caFile := filepath.Join(t.TempDir(), "camera-ca.pem")
+		if err := os.WriteFile(caFile, []byte("not a certificate"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		t.Setenv(rtspsCAFileEnv, caFile)
+
+		if _, err := rtspsTLSConfig(); err == nil {
+			t.Fatal("rtspsTLSConfig() error = nil, want invalid CA error")
+		}
+	})
+}
+
+func TestVideoReferenceStateDropsDependentFramesUntilRandomAccess(t *testing.T) {
+	state := &videoReferenceState{}
+
+	accepted, recovered := state.accept(false)
+	if accepted || recovered != 0 || state.droppedAccessUnits != 1 {
+		t.Fatalf("initial dependent frame = (accepted=%t, recovered=%d, dropped=%d), want (false, 0, 1)",
+			accepted, recovered, state.droppedAccessUnits)
+	}
+
+	accepted, recovered = state.accept(true)
+	if !accepted || recovered != 1 || !state.valid {
+		t.Fatalf("random-access recovery = (accepted=%t, recovered=%d, valid=%t), want (true, 1, true)",
+			accepted, recovered, state.valid)
+	}
+
+	if expected, gap := state.observeSequence(100); gap || expected != 100 {
+		t.Fatalf("first sequence observation = (expected=%d, gap=%t), want (100, false)", expected, gap)
+	}
+	if expected, gap := state.observeSequence(102); !gap || expected != 101 || state.valid {
+		t.Fatalf("sequence gap = (expected=%d, gap=%t, valid=%t), want (101, true, false)",
+			expected, gap, state.valid)
+	}
+
+	accepted, recovered = state.accept(false)
+	if accepted || recovered != 0 || state.droppedAccessUnits != 1 {
+		t.Fatalf("post-loss dependent frame = (accepted=%t, recovered=%d, dropped=%d), want (false, 0, 1)",
+			accepted, recovered, state.droppedAccessUnits)
+	}
+
+	accepted, recovered = state.accept(true)
+	if !accepted || recovered != 1 || !state.valid {
+		t.Fatalf("post-loss recovery = (accepted=%t, recovered=%d, valid=%t), want (true, 1, true)",
+			accepted, recovered, state.valid)
+	}
+}
+
+func TestVideoReferenceStateAcceptsSequenceWraparound(t *testing.T) {
+	state := &videoReferenceState{valid: true}
+
+	if _, gap := state.observeSequence(^uint16(0)); gap {
+		t.Fatal("first sequence observation reported a gap")
+	}
+	if expected, gap := state.observeSequence(0); gap || expected != 0 || !state.valid {
+		t.Fatalf("sequence wraparound = (expected=%d, gap=%t, valid=%t), want (0, false, true)",
+			expected, gap, state.valid)
+	}
+}
+
+func TestH264FrameNumTrackerDetectsMissingIDR(t *testing.T) {
+	tracker := &h264FrameNumTracker{}
+	tracker.setSPS(&h264.SPS{
+		Log2MaxFrameNumMinus4: 1,
+		FrameMbsOnlyFlag:      true,
+	})
+
+	if _, _, gap, ok := tracker.observe([][]byte{testH264Slice(h264.NALUTypeIDR, 0)}); !ok || gap {
+		t.Fatalf("initial IDR observation = (ok=%t, gap=%t), want (true, false)", ok, gap)
+	}
+	for frameNum := uint32(1); frameNum <= 24; frameNum++ {
+		if expected, received, gap, ok := tracker.observe([][]byte{testH264Slice(h264.NALUTypeNonIDR, frameNum)}); !ok || gap {
+			t.Fatalf("frame_num %d observation = (expected=%d, received=%d, ok=%t, gap=%t), want no gap",
+				frameNum, expected, received, ok, gap)
+		}
+	}
+
+	expected, received, gap, ok := tracker.observe([][]byte{testH264Slice(h264.NALUTypeNonIDR, 1)})
+	if !ok || !gap || expected != 25 || received != 1 {
+		t.Fatalf("missing IDR transition = (expected=%d, received=%d, ok=%t, gap=%t), want (25, 1, true, true)",
+			expected, received, ok, gap)
+	}
+}
+
+func TestH264FrameNumTrackerResetsAtIDR(t *testing.T) {
+	tracker := &h264FrameNumTracker{}
+	tracker.setSPS(&h264.SPS{
+		Log2MaxFrameNumMinus4: 1,
+		FrameMbsOnlyFlag:      true,
+	})
+
+	tracker.observe([][]byte{testH264Slice(h264.NALUTypeIDR, 0)})
+	tracker.observe([][]byte{testH264Slice(h264.NALUTypeNonIDR, 1)})
+	if expected, received, gap, ok := tracker.observe([][]byte{testH264Slice(h264.NALUTypeIDR, 0)}); !ok || gap {
+		t.Fatalf("IDR reset = (expected=%d, received=%d, ok=%t, gap=%t), want no gap",
+			expected, received, ok, gap)
+	}
+	if expected, received, gap, ok := tracker.observe([][]byte{testH264Slice(h264.NALUTypeNonIDR, 1)}); !ok || gap || expected != 1 || received != 1 {
+		t.Fatalf("post-IDR frame = (expected=%d, received=%d, ok=%t, gap=%t), want (1, 1, true, false)",
+			expected, received, ok, gap)
+	}
+}
+
+func TestH264FrameNumTrackerHonorsPermittedGaps(t *testing.T) {
+	tracker := &h264FrameNumTracker{}
+	tracker.setSPS(&h264.SPS{
+		Log2MaxFrameNumMinus4:          1,
+		FrameMbsOnlyFlag:               true,
+		GapsInFrameNumValueAllowedFlag: true,
+	})
+
+	tracker.observe([][]byte{testH264Slice(h264.NALUTypeIDR, 0)})
+	expected, received, gap, ok := tracker.observe([][]byte{testH264Slice(h264.NALUTypeNonIDR, 2)})
+	if !ok || gap || expected != 1 || received != 2 {
+		t.Fatalf("permitted frame_num gap = (expected=%d, received=%d, ok=%t, gap=%t), want (1, 2, true, false)",
+			expected, received, ok, gap)
+	}
+}
+
+func testH264Slice(naluType h264.NALUType, frameNum uint32) []byte {
+	return []byte{0x60 | byte(naluType), 0xE0 | byte(frameNum&0x1F)}
+}

machinery/src/capture/main_test.go

@@ -0,0 +1,90 @@
+package capture
+
+import (
+	"encoding/json"
+	"math"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/kerberos-io/agent/machinery/src/models"
+	"github.com/kerberos-io/agent/machinery/src/video"
+)
+
+func TestPTSToDuration(t *testing.T) {
+	tests := []struct {
+		name      string
+		pts       int64
+		clockRate int
+		want      time.Duration
+	}{
+		{name: "one video second", pts: 90_000, clockRate: 90_000, want: time.Second},
+		{name: "one audio frame", pts: 1_024, clockRate: 8_000, want: 128 * time.Millisecond},
+		{name: "fractional millisecond", pts: 45_045, clockRate: 90_000, want: 500*time.Millisecond + 500*time.Microsecond},
+		{name: "negative timestamp", pts: -45_045, clockRate: 90_000, want: -500*time.Millisecond - 500*time.Microsecond},
+		{name: "large timestamp", pts: 90_000 * 60 * 60 * 24, clockRate: 90_000, want: 24 * time.Hour},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if got := ptsToDuration(test.pts, test.clockRate); got != test.want {
+				t.Fatalf("ptsToDuration(%d, %d) = %s, want %s", test.pts, test.clockRate, got, test.want)
+			}
+		})
+	}
+}
+
+func TestQueueRecordingForUploadStoresFinalizedMetadata(t *testing.T) {
+	configDirectory := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(configDirectory, "data", "cloud"), 0o755); err != nil {
+		t.Fatalf("mkdir cloud queue: %v", err)
+	}
+
+	mp4Video := &video.MP4{VideoTotalDuration: 20452, SampleCount: 613}
+	config := models.Config{Key: "device-key", Name: "camera-name"}
+	metadata := recordingUploadMetadata("1785934709414-device-key.mp4", config, 1785934709414, mp4Video, true, "1-2-3-4", 57)
+	queueRecordingForUpload(configDirectory, metadata)
+
+	got, err := os.ReadFile(filepath.Join(configDirectory, "data", "cloud", "1785934709414-device-key.metadata"))
+	if err != nil {
+		t.Fatalf("read upload marker: %v", err)
+	}
+	var stored models.RecordingUploadMetadata
+	if err := json.Unmarshal(got, &stored); err != nil {
+		t.Fatalf("decode upload marker: %v", err)
+	}
+	expectedFPS := mp4Video.AverageFPS()
+	if stored.FileName != "1785934709414-device-key.mp4" || stored.DeviceKey != "device-key" || stored.Timestamp != 1785934709414 || stored.Duration != 20452 || math.Abs(stored.FPS-expectedFPS) > 1e-9 || !stored.Encrypted ||
+		stored.DeviceName != "camera-name" || stored.RegionCoordinates != "1-2-3-4" || stored.NumberOfChanges != "57" {
+		t.Fatalf("upload marker = %+v", stored)
+	}
+	if stored.FPS == math.Floor(stored.FPS) {
+		t.Fatalf("upload marker FPS = %v, want fractional precision", stored.FPS)
+	}
+}
+
+func TestQueueRecordingForUploadKeepsUnknownFPSCompatible(t *testing.T) {
+	for _, fps := range []float64{0, 0.99, -1, math.NaN(), math.Inf(1), 241} {
+		t.Run("invalid FPS", func(t *testing.T) {
+			configDirectory := t.TempDir()
+			if err := os.MkdirAll(filepath.Join(configDirectory, "data", "cloud"), 0o755); err != nil {
+				t.Fatalf("mkdir cloud queue: %v", err)
+			}
+
+			metadata := models.RecordingUploadMetadata{FileName: "recording.mp4"}
+			if fps >= 1 && fps <= 240 && !math.IsNaN(fps) && !math.IsInf(fps, 0) {
+				metadata.FPS = fps
+			}
+			queueRecordingForUpload(configDirectory, metadata)
+
+			got, err := os.ReadFile(filepath.Join(configDirectory, "data", "cloud", "recording.metadata"))
+			if err != nil {
+				t.Fatalf("read upload marker: %v", err)
+			}
+			if string(got) != `{"filename":"recording.mp4","device_key":"","timestamp":0,"duration":0}` {
+				t.Fatalf("upload marker = %q, want metadata without FPS", got)
+			}
+		})
+	}
+}

machinery/src/capture/rtsp_client.go

@@ -0,0 +1,109 @@
+package capture
+
+import (
+	"context"
+	"image"
+	"sync"
+
+	"github.com/kerberos-io/agent/machinery/src/models"
+	"github.com/kerberos-io/agent/machinery/src/packets"
+)
+
+type Capture struct {
+	clientsMu             sync.RWMutex
+	rtspClient            *Golibrtsp
+	rtspSubClient         *Golibrtsp
+	rtspBackChannelClient *Golibrtsp
+}
+
+func (c *Capture) SetMainClient(rtspUrl string) *Golibrtsp {
+	client := &Golibrtsp{
+		Url: rtspUrl,
+	}
+	c.clientsMu.Lock()
+	c.rtspClient = client
+	c.clientsMu.Unlock()
+	return client
+}
+
+func (c *Capture) SetSubClient(rtspUrl string) *Golibrtsp {
+	client := &Golibrtsp{
+		Url: rtspUrl,
+	}
+	c.clientsMu.Lock()
+	c.rtspSubClient = client
+	c.clientsMu.Unlock()
+	return client
+}
+
+func (c *Capture) SetBackChannelClient(rtspUrl string) *Golibrtsp {
+	client := &Golibrtsp{
+		Url: rtspUrl,
+	}
+	c.clientsMu.Lock()
+	c.rtspBackChannelClient = client
+	c.clientsMu.Unlock()
+	return client
+}
+
+func (c *Capture) MainClient() *Golibrtsp {
+	c.clientsMu.RLock()
+	defer c.clientsMu.RUnlock()
+	return c.rtspClient
+}
+
+func (c *Capture) SubClient() *Golibrtsp {
+	c.clientsMu.RLock()
+	defer c.clientsMu.RUnlock()
+	return c.rtspSubClient
+}
+
+func (c *Capture) ClearClients(main, sub, backchannel *Golibrtsp) {
+	c.clientsMu.Lock()
+	defer c.clientsMu.Unlock()
+	if c.rtspClient == main {
+		c.rtspClient = nil
+	}
+	if c.rtspSubClient == sub {
+		c.rtspSubClient = nil
+	}
+	if c.rtspBackChannelClient == backchannel {
+		c.rtspBackChannelClient = nil
+	}
+}
+
+// RTSPClient is a interface that abstracts the RTSP client implementation.
+type RTSPClient interface {
+	// Connect to the RTSP server.
+	Connect(ctx context.Context, otelContext context.Context) error
+
+	// Connect to a backchannel RTSP server.
+	ConnectBackChannel(ctx context.Context, otelContext context.Context) error
+
+	// Start the RTSP client, and start reading packets.
+	Start(ctx context.Context, streamType string, queue *packets.Queue, configuration *models.Configuration, communication *models.Communication) error
+
+	// Start the RTSP client, and start reading packets.
+	StartBackChannel(ctx context.Context, otelContext context.Context) error
+
+	// Decode a packet into a image.
+	DecodePacket(pkt packets.Packet) (image.YCbCr, error)
+
+	// Decode a packet into a image.
+	DecodePacketRaw(pkt packets.Packet) (image.Gray, error)
+
+	// Write a packet to the RTSP server.
+	WritePacket(pkt packets.Packet) error
+
+	// Close the connection to the RTSP server.
+	Close(ctx context.Context) error
+
+	// Get a list of streams from the RTSP server.
+	GetStreams() ([]packets.Stream, error)
+
+	// Get a list of video streams from the RTSP server.
+	GetVideoStreams() ([]packets.Stream, error)
+
+	// Get a list of audio streams from the RTSP server.
+	GetAudioStreams() ([]packets.Stream, error)
+}

machinery/src/capture/rtsp_client_test.go

@@ -0,0 +1,62 @@
+package capture
+
+import (
+	"strconv"
+	"sync"
+	"testing"
+)
+
+func TestCaptureClientAccessCanRaceReplacement(t *testing.T) {
+	captureDevice := &Capture{}
+	captureDevice.SetMainClient("rtsp://main/0")
+	captureDevice.SetSubClient("rtsp://sub/0")
+
+	var workers sync.WaitGroup
+	workers.Add(2)
+	go func() {
+		defer workers.Done()
+		for replacement := 1; replacement <= 1000; replacement++ {
+			suffix := strconv.Itoa(replacement)
+			captureDevice.SetMainClient("rtsp://main/" + suffix)
+			captureDevice.SetSubClient("rtsp://sub/" + suffix)
+		}
+	}()
+	go func() {
+		defer workers.Done()
+		for snapshot := 0; snapshot < 1000; snapshot++ {
+			if captureDevice.MainClient() == nil {
+				t.Error("MainClient() returned nil")
+				return
+			}
+			if captureDevice.SubClient() == nil {
+				t.Error("SubClient() returned nil")
+				return
+			}
+		}
+	}()
+	workers.Wait()
+}
+
+func TestCaptureClearClientsOnlyClearsMatchingRun(t *testing.T) {
+	captureDevice := &Capture{}
+	oldMain := captureDevice.SetMainClient("rtsp://main/old")
+	oldSub := captureDevice.SetSubClient("rtsp://sub/old")
+	oldBackchannel := captureDevice.SetBackChannelClient("rtsp://back/old")
+
+	newMain := captureDevice.SetMainClient("rtsp://main/new")
+	newSub := captureDevice.SetSubClient("rtsp://sub/new")
+	newBackchannel := captureDevice.SetBackChannelClient("rtsp://back/new")
+
+	captureDevice.ClearClients(oldMain, oldSub, oldBackchannel)
+	if captureDevice.MainClient() != newMain {
+		t.Fatal("stale cleanup cleared the new main client")
+	}
+	if captureDevice.SubClient() != newSub {
+		t.Fatal("stale cleanup cleared the new sub client")
+	}
+
+	captureDevice.ClearClients(newMain, newSub, newBackchannel)
+	if captureDevice.MainClient() != nil || captureDevice.SubClient() != nil {
+		t.Fatal("matching cleanup did not clear current clients")
+	}
+}

machinery/src/capture/snapshot_test.go

@@ -0,0 +1,68 @@
+package capture
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/kerberos-io/agent/machinery/src/models"
+	"github.com/kerberos-io/agent/machinery/src/packets"
+)
+
+func TestSnapshotReturnsAfterQueueClosure(t *testing.T) {
+	for _, stream := range []string{"main", "sub"} {
+		for _, format := range []string{"jpeg", "base64"} {
+			for _, alreadyClosed := range []bool{true, false} {
+				name := stream + "/" + format + "/closed_during_read"
+				if alreadyClosed {
+					name = stream + "/" + format + "/already_closed"
+				}
+				t.Run(name, func(t *testing.T) {
+					communication := &models.Communication{}
+					run := models.NewAgentRun(context.Background(), communication, false)
+					queue := packets.NewQueue()
+					captureDevice := &Capture{}
+					if stream == "main" {
+						captureDevice.SetMainClient("rtsp://unused.invalid/main")
+						run.SetMainQueue(queue)
+					} else {
+						captureDevice.SetSubClient("rtsp://unused.invalid/sub")
+						run.SetSubQueue(queue)
+					}
+					if err := run.Activate(); err != nil {
+						t.Fatal(err)
+					}
+					defer queue.Close()
+					if alreadyClosed {
+						queue.Close()
+					}
+					done := make(chan bool, 1)
+					go func() {
+						if format == "jpeg" {
+							image := JpegImage(captureDevice, communication)
+							done <- image.Rect.Empty()
+						} else {
+							done <- Base64Image(captureDevice, communication, &models.Configuration{}) == ""
+						}
+					}()
+					if !alreadyClosed {
+						select {
+						case <-done:
+							t.Fatal("snapshot returned before a frame or queue closure")
+						case <-time.After(10 * time.Millisecond):
+						}
+						queue.Close()
+					}
+					select {
+					case empty := <-done:
+						if !empty {
+							t.Fatal("closed empty queue produced a snapshot")
+						}
+					case <-time.After(time.Second):
+						t.Fatal("snapshot did not return after its packet queue closed")
+					}
+				})
+			}
+		}
+	}
+}

machinery/src/cloud/Cloud.go

@@ -1,859 +0,0 @@
-package cloud
-
-import (
-	"bytes"
-	"crypto/tls"
-	"encoding/base64"
-	"encoding/json"
-	"fmt"
-	"io/ioutil"
-	"os"
-	"strings"
-	"sync"
-
-	"github.com/elastic/go-sysinfo"
-	"github.com/gin-gonic/gin"
-	"github.com/golang-module/carbon/v2"
-	"github.com/kerberos-io/joy4/av/pubsub"
-
-	mqtt "github.com/eclipse/paho.mqtt.golang"
-	av "github.com/kerberos-io/joy4/av"
-	"github.com/kerberos-io/joy4/cgo/ffmpeg"
-
-	"net/http"
-	"strconv"
-	"time"
-
-	"github.com/kerberos-io/agent/machinery/src/computervision"
-	"github.com/kerberos-io/agent/machinery/src/log"
-	"github.com/kerberos-io/agent/machinery/src/models"
-	"github.com/kerberos-io/agent/machinery/src/onvif"
-	"github.com/kerberos-io/agent/machinery/src/utils"
-	"github.com/kerberos-io/agent/machinery/src/webrtc"
-)
-
-func PendingUpload(configDirectory string) {
-	ff, err := utils.ReadDirectory(configDirectory + "/data/cloud/")
-	if err == nil {
-		for _, f := range ff {
-			log.Log.Info(f.Name())
-		}
-	}
-}
-
-func HandleUpload(configDirectory string, configuration *models.Configuration, communication *models.Communication) {
-
-	log.Log.Debug("HandleUpload: started")
-
-	config := configuration.Config
-	watchDirectory := configDirectory + "/data/cloud/"
-
-	if config.Offline == "true" {
-		log.Log.Debug("HandleUpload: stopping as Offline is enabled.")
-	} else {
-
-		// Half a second delay between two uploads
-		delay := 500 * time.Millisecond
-
-	loop:
-		for {
-			// This will check if we need to stop the thread,
-			// because of a reconfiguration.
-			select {
-			case <-communication.HandleUpload:
-				break loop
-			case <-time.After(2 * time.Second):
-			}
-
-			ff, err := utils.ReadDirectory(watchDirectory)
-			if err != nil {
-				log.Log.Error("HandleUpload: " + err.Error())
-			} else {
-				for _, f := range ff {
-
-					// This will check if we need to stop the thread,
-					// because of a reconfiguration.
-					select {
-					case <-communication.HandleUpload:
-						break loop
-					default:
-					}
-
-					fileName := f.Name()
-					uploaded := false
-					configured := false
-					err = nil
-					if config.Cloud == "s3" || config.Cloud == "kerberoshub" {
-						uploaded, configured, err = UploadKerberosHub(configuration, fileName)
-					} else if config.Cloud == "kstorage" || config.Cloud == "kerberosvault" {
-						uploaded, configured, err = UploadKerberosVault(configuration, fileName)
-					} else if config.Cloud == "dropbox" {
-						uploaded, configured, err = UploadDropbox(configuration, fileName)
-					} else if config.Cloud == "gdrive" {
-						// Todo: implement gdrive upload
-					} else if config.Cloud == "onedrive" {
-						// Todo: implement onedrive upload
-					} else if config.Cloud == "minio" {
-						// Todo: implement minio upload
-					} else if config.Cloud == "webdav" {
-						// Todo: implement webdav upload
-					} else if config.Cloud == "ftp" {
-						// Todo: implement ftp upload
-					} else if config.Cloud == "sftp" {
-						// Todo: implement sftp upload
-					} else if config.Cloud == "aws" {
-						// Todo: need to be updated, was previously used for hub.
-						uploaded, configured, err = UploadS3(configuration, fileName)
-					} else if config.Cloud == "azure" {
-						// Todo: implement azure upload
-					} else if config.Cloud == "google" {
-						// Todo: implement google upload
-					}
-					// And so on... (have a look here -> https://github.com/kerberos-io/agent/issues/95)
-
-					// Check if the file is uploaded, if so, remove it.
-					if uploaded {
-						delay = 500 * time.Millisecond // reset
-						err := os.Remove(watchDirectory + fileName)
-						if err != nil {
-							log.Log.Error("HandleUpload: " + err.Error())
-						}
-
-						// Check if we need to remove the original recording
-						// removeAfterUpload is set to false by default
-						if config.RemoveAfterUpload != "false" {
-							err := os.Remove(configDirectory + "/data/recordings/" + fileName)
-							if err != nil {
-								log.Log.Error("HandleUpload: " + err.Error())
-							}
-						}
-					} else if !configured {
-						err := os.Remove(watchDirectory + fileName)
-						if err != nil {
-							log.Log.Error("HandleUpload: " + err.Error())
-						}
-					} else {
-						delay = 20 * time.Second // slow down
-						if err != nil {
-							log.Log.Error("HandleUpload: " + err.Error())
-						}
-					}
-
-					time.Sleep(delay)
-				}
-			}
-		}
-	}
-
-	log.Log.Debug("HandleUpload: finished")
-}
-
-func GetSystemInfo() (models.System, error) {
-	var usedMem uint64 = 0
-	var totalMem uint64 = 0
-	var freeMem uint64 = 0
-
-	var processUsedMem uint64 = 0
-
-	architecture := ""
-	cpuId := ""
-	KernelVersion := ""
-	agentVersion := ""
-	var MACs []string
-	var IPs []string
-	hostname := ""
-	bootTime := time.Time{}
-
-	// Read agent version
-	version, err := os.Open("./version")
-	defer version.Close()
-	agentVersion = "unknown"
-	if err == nil {
-		agentVersionBytes, err := ioutil.ReadAll(version)
-		agentVersion = string(agentVersionBytes)
-		if err != nil {
-			log.Log.Error(err.Error())
-		}
-	}
-
-	host, err := sysinfo.Host()
-	if err == nil {
-		cpuId = host.Info().UniqueID
-		architecture = host.Info().Architecture
-		KernelVersion = host.Info().KernelVersion
-		MACs = host.Info().MACs
-		IPs = host.Info().IPs
-		hostname = host.Info().Hostname
-		bootTime = host.Info().BootTime
-		memory, err := host.Memory()
-		if err == nil {
-			usedMem = memory.Used
-			totalMem = memory.Total
-			freeMem = memory.Free
-		}
-	}
-
-	process, err := sysinfo.Self()
-	if err == nil {
-		memInfo, err := process.Memory()
-		if err == nil {
-			processUsedMem = memInfo.Resident
-		}
-	}
-
-	system := models.System{
-		Hostname:          hostname,
-		CPUId:             cpuId,
-		KernelVersion:     KernelVersion,
-		Version:           agentVersion,
-		MACs:              MACs,
-		IPs:               IPs,
-		BootTime:          uint64(bootTime.Unix()),
-		Architecture:      architecture,
-		UsedMemory:        usedMem,
-		TotalMemory:       totalMem,
-		FreeMemory:        freeMem,
-		ProcessUsedMemory: processUsedMem,
-	}
-
-	return system, nil
-}
-
-func HandleHeartBeat(configuration *models.Configuration, communication *models.Communication, uptimeStart time.Time) {
-	log.Log.Debug("HandleHeartBeat: started")
-
-loop:
-	for {
-
-		config := configuration.Config
-
-		if config.Offline == "true" {
-			log.Log.Debug("HandleHeartBeat: stopping as Offline is enabled.")
-		} else {
-
-			url := config.HeartbeatURI
-			key := ""
-			username := ""
-			vaultURI := ""
-
-			username = config.S3.Username
-			if config.Cloud == "s3" && config.S3 != nil && config.S3.Publickey != "" {
-				username = config.S3.Username
-				key = config.S3.Publickey
-			} else if config.Cloud == "kstorage" && config.KStorage != nil && config.KStorage.CloudKey != "" {
-				key = config.KStorage.CloudKey
-				username = config.KStorage.Directory
-			}
-
-			// This is the new way ;)
-			if config.HubURI != "" {
-				url = config.HubURI + "/devices/heartbeat"
-			}
-			if config.HubKey != "" {
-				key = config.HubKey
-			}
-
-			if key != "" {
-				// Check if we have a friendly name or not.
-				name := config.Name
-				if config.FriendlyName != "" {
-					name = config.FriendlyName
-				}
-
-				// Get some system information
-				// like the uptime, hostname, memory usage, etc.
-				system, _ := GetSystemInfo()
-
-				// We will formated the uptime to a human readable format
-				// this will be used on Kerberos Hub: Uptime -> 1 day and 2 hours.
-				uptimeFormatted := uptimeStart.Format("2006-01-02 15:04:05")
-				uptimeString := carbon.Parse(uptimeFormatted).DiffForHumans()
-				uptimeString = strings.ReplaceAll(uptimeString, "ago", "")
-
-				// Do the same for boottime
-				bootTimeFormatted := time.Unix(int64(system.BootTime), 0).Format("2006-01-02 15:04:05")
-				boottimeString := carbon.Parse(bootTimeFormatted).DiffForHumans()
-				boottimeString = strings.ReplaceAll(boottimeString, "ago", "")
-
-				// We'll check which mode is enabled for the camera.
-				onvifEnabled := "false"
-				onvifZoom := "false"
-				onvifPanTilt := "false"
-				onvifPresets := "false"
-				var onvifPresetsList []byte
-				if config.Capture.IPCamera.ONVIFXAddr != "" {
-					cameraConfiguration := configuration.Config.Capture.IPCamera
-					device, err := onvif.ConnectToOnvifDevice(&cameraConfiguration)
-					if err == nil {
-						configurations, err := onvif.GetPTZConfigurationsFromDevice(device)
-						if err == nil {
-							onvifEnabled = "true"
-							_, canZoom, canPanTilt := onvif.GetPTZFunctionsFromDevice(configurations)
-							if canZoom {
-								onvifZoom = "true"
-							}
-							if canPanTilt {
-								onvifPanTilt = "true"
-							}
-							// Try to read out presets
-							presets, err := onvif.GetPresetsFromDevice(device)
-							if err == nil && len(presets) > 0 {
-								onvifPresets = "true"
-								onvifPresetsList, err = json.Marshal(presets)
-								if err != nil {
-									log.Log.Error("HandleHeartBeat: error while marshalling presets: " + err.Error())
-									onvifPresetsList = []byte("[]")
-								}
-							} else {
-								if err != nil {
-									log.Log.Error("HandleHeartBeat: error while getting presets: " + err.Error())
-								} else {
-									log.Log.Debug("HandleHeartBeat: no presets found.")
-								}
-								onvifPresetsList = []byte("[]")
-							}
-						} else {
-							log.Log.Error("HandleHeartBeat: error while getting PTZ configurations: " + err.Error())
-							onvifPresetsList = []byte("[]")
-						}
-					} else {
-						log.Log.Error("HandleHeartBeat: error while connecting to ONVIF device: " + err.Error())
-						onvifPresetsList = []byte("[]")
-					}
-				} else {
-					log.Log.Debug("HandleHeartBeat: ONVIF is not enabled.")
-					onvifPresetsList = []byte("[]")
-				}
-
-				// Check if the agent is running inside a cluster (Kerberos Factory) or as
-				// an open source agent
-				isEnterprise := false
-				if os.Getenv("DEPLOYMENT") == "factory" || os.Getenv("MACHINERY_ENVIRONMENT") == "kubernetes" {
-					isEnterprise = true
-				}
-
-				// Congert to string
-				macs, _ := json.Marshal(system.MACs)
-				ips, _ := json.Marshal(system.IPs)
-				cameraConnected := "true"
-				if communication.CameraConnected == false {
-					cameraConnected = "false"
-				}
-
-				var object = fmt.Sprintf(`{
-						"key" : "%s",
-						"version" : "3.0.0",
-						"release" : "%s",
-						"cpuid" : "%s",
-						"clouduser" : "%s",
-						"cloudpublickey" : "%s",
-						"cameraname" : "%s",
-						"enterprise" : %t,
-						"hostname" : "%s",
-						"architecture" : "%s",
-						"totalMemory" : "%d",
-						"usedMemory" : "%d",
-						"freeMemory" : "%d",
-						"processMemory" : "%d",
-						"mac_list" : %s,
-						"ip_list" : %s,
-						"board" : "",
-						"disk1size" : "%s",
-						"disk3size" : "%s",
-						"diskvdasize" :  "%s",
-						"uptime" : "%s",
-						"boot_time" : "%s",
-						"siteID" : "%s",
-						"onvif" : "%s",
-						"onvif_zoom" : "%s",
-						"onvif_pantilt" : "%s",
-						"onvif_presets": "%s",
-						"onvif_presets_list": %s,
-						"cameraConnected": "%s",
-						"numberoffiles" : "33",
-						"timestamp" : 1564747908,
-						"cameratype" : "IPCamera",
-						"docker" : true,
-						"kios" : false,
-						"raspberrypi" : false
-					}`, config.Key, system.Version, system.CPUId, username, key, name, isEnterprise, system.Hostname, system.Architecture, system.TotalMemory, system.UsedMemory, system.FreeMemory, system.ProcessUsedMemory, macs, ips, "0", "0", "0", uptimeString, boottimeString, config.HubSite, onvifEnabled, onvifZoom, onvifPanTilt, onvifPresets, onvifPresetsList, cameraConnected)
-
-				var jsonStr = []byte(object)
-				buffy := bytes.NewBuffer(jsonStr)
-				req, _ := http.NewRequest("POST", url, buffy)
-				req.Header.Set("Content-Type", "application/json")
-
-				var client *http.Client
-				if os.Getenv("AGENT_TLS_INSECURE") == "true" {
-					tr := &http.Transport{
-						TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
-					}
-					client = &http.Client{Transport: tr}
-				} else {
-					client = &http.Client{}
-				}
-
-				resp, err := client.Do(req)
-				if resp != nil {
-					resp.Body.Close()
-				}
-				if err == nil && resp.StatusCode == 200 {
-					communication.CloudTimestamp.Store(time.Now().Unix())
-					log.Log.Info("HandleHeartBeat: (200) Heartbeat received by Kerberos Hub.")
-				} else {
-					if communication.CloudTimestamp != nil && communication.CloudTimestamp.Load() != nil {
-						communication.CloudTimestamp.Store(int64(0))
-					}
-					log.Log.Error("HandleHeartBeat: (400) Something went wrong while sending to Kerberos Hub.")
-				}
-
-				// If we have a Kerberos Vault connected, we will also send some analytics
-				// to that service.
-				vaultURI = config.KStorage.URI
-				if vaultURI != "" {
-					buffy = bytes.NewBuffer(jsonStr)
-					req, _ = http.NewRequest("POST", vaultURI+"/devices/heartbeat", buffy)
-					req.Header.Set("Content-Type", "application/json")
-					resp, err = client.Do(req)
-					if resp != nil {
-						resp.Body.Close()
-					}
-					if err == nil && resp.StatusCode == 200 {
-						log.Log.Info("HandleHeartBeat: (200) Heartbeat received by Kerberos Vault.")
-					} else {
-						log.Log.Error("HandleHeartBeat: (400) Something went wrong while sending to Kerberos Vault.")
-					}
-				}
-			} else {
-				log.Log.Error("HandleHeartBeat: Disabled as we do not have a public key defined.")
-			}
-		}
-
-		// This will check if we need to stop the thread,
-		// because of a reconfiguration.
-		select {
-		case <-communication.HandleHeartBeat:
-			break loop
-		case <-time.After(15 * time.Second):
-		}
-	}
-
-	log.Log.Debug("HandleHeartBeat: finished")
-}
-
-func HandleLiveStreamSD(livestreamCursor *pubsub.QueueCursor, configuration *models.Configuration, communication *models.Communication, mqttClient mqtt.Client, decoder *ffmpeg.VideoDecoder, decoderMutex *sync.Mutex) {
-
-	log.Log.Debug("HandleLiveStreamSD: started")
-
-	config := configuration.Config
-
-	// If offline made is enabled, we will stop the thread.
-	if config.Offline == "true" {
-		log.Log.Debug("HandleLiveStreamSD: stopping as Offline is enabled.")
-	} else {
-
-		// Check if we need to enable the live stream
-		if config.Capture.Liveview != "false" {
-
-			// Allocate frame
-			frame := ffmpeg.AllocVideoFrame()
-
-			key := ""
-			if config.Cloud == "s3" && config.S3 != nil && config.S3.Publickey != "" {
-				key = config.S3.Publickey
-			} else if config.Cloud == "kstorage" && config.KStorage != nil && config.KStorage.CloudKey != "" {
-				key = config.KStorage.CloudKey
-			}
-			// This is the new way ;)
-			if config.HubKey != "" {
-				key = config.HubKey
-			}
-
-			topic := "kerberos/" + key + "/device/" + config.Key + "/live"
-
-			lastLivestreamRequest := int64(0)
-
-			var cursorError error
-			var pkt av.Packet
-
-			for cursorError == nil {
-				pkt, cursorError = livestreamCursor.ReadPacket()
-				if len(pkt.Data) == 0 || !pkt.IsKeyFrame {
-					continue
-				}
-				now := time.Now().Unix()
-				select {
-				case <-communication.HandleLiveSD:
-					lastLivestreamRequest = now
-				default:
-				}
-				if now-lastLivestreamRequest > 3 {
-					continue
-				}
-				log.Log.Info("HandleLiveStreamSD: Sending base64 encoded images to MQTT.")
-				sendImage(frame, topic, mqttClient, pkt, decoder, decoderMutex)
-			}
-
-			// Cleanup the frame.
-			frame.Free()
-
-		} else {
-			log.Log.Debug("HandleLiveStreamSD: stopping as Liveview is disabled.")
-		}
-	}
-
-	log.Log.Debug("HandleLiveStreamSD: finished")
-}
-
-func sendImage(frame *ffmpeg.VideoFrame, topic string, mqttClient mqtt.Client, pkt av.Packet, decoder *ffmpeg.VideoDecoder, decoderMutex *sync.Mutex) {
-	_, err := computervision.GetRawImage(frame, pkt, decoder, decoderMutex)
-	if err == nil {
-		bytes, _ := computervision.ImageToBytes(&frame.Image)
-		encoded := base64.StdEncoding.EncodeToString(bytes)
-		mqttClient.Publish(topic, 0, false, encoded)
-	}
-}
-
-func HandleLiveStreamHD(livestreamCursor *pubsub.QueueCursor, configuration *models.Configuration, communication *models.Communication, mqttClient mqtt.Client, codecs []av.CodecData, decoder *ffmpeg.VideoDecoder, decoderMutex *sync.Mutex) {
-
-	config := configuration.Config
-
-	if config.Offline == "true" {
-		log.Log.Debug("HandleLiveStreamHD: stopping as Offline is enabled.")
-	} else {
-
-		// Check if we need to enable the live stream
-		if config.Capture.Liveview != "false" {
-
-			// Should create a track here.
-			videoTrack := webrtc.NewVideoTrack(codecs)
-			audioTrack := webrtc.NewAudioTrack(codecs)
-			go webrtc.WriteToTrack(livestreamCursor, configuration, communication, mqttClient, videoTrack, audioTrack, codecs, decoder, decoderMutex)
-
-			if config.Capture.ForwardWebRTC == "true" {
-				// We get a request with an offer, but we'll forward it.
-				for m := range communication.HandleLiveHDHandshake {
-					// Forward SDP
-					m.CloudKey = config.Key
-					request, err := json.Marshal(m)
-					if err == nil {
-						mqttClient.Publish("kerberos/webrtc/request", 2, false, request)
-					}
-				}
-			} else {
-				log.Log.Info("HandleLiveStreamHD: Waiting for peer connections.")
-				for handshake := range communication.HandleLiveHDHandshake {
-					log.Log.Info("HandleLiveStreamHD: setting up a peer connection.")
-					key := config.Key + "/" + handshake.Cuuid
-					webrtc.CandidatesMutex.Lock()
-					_, ok := webrtc.CandidateArrays[key]
-					if !ok {
-						webrtc.CandidateArrays[key] = make(chan string, 30)
-					}
-					webrtc.CandidatesMutex.Unlock()
-					webrtc.InitializeWebRTCConnection(configuration, communication, mqttClient, videoTrack, audioTrack, handshake, webrtc.CandidateArrays[key])
-
-				}
-			}
-
-		} else {
-			log.Log.Debug("HandleLiveStreamHD: stopping as Liveview is disabled.")
-		}
-	}
-}
-
-// VerifyHub godoc
-// @Router /api/hub/verify [post]
-// @ID verify-hub
-// @Security Bearer
-// @securityDefinitions.apikey Bearer
-// @in header
-// @name Authorization
-// @Tags config
-// @Param config body models.Config true "Config"
-// @Summary Will verify the hub connectivity.
-// @Description Will verify the hub connectivity.
-// @Success 200 {object} models.APIResponse
-func VerifyHub(c *gin.Context) {
-
-	var config models.Config
-	err := c.BindJSON(&config)
-
-	if err == nil {
-		hubURI := config.HubURI
-		publicKey := config.HubKey
-		privateKey := config.HubPrivateKey
-
-		req, err := http.NewRequest("POST", hubURI+"/subscription/verify", nil)
-		if err == nil {
-			req.Header.Set("X-Kerberos-Hub-PublicKey", publicKey)
-			req.Header.Set("X-Kerberos-Hub-PrivateKey", privateKey)
-			var client *http.Client
-			if os.Getenv("AGENT_TLS_INSECURE") == "true" {
-				tr := &http.Transport{
-					TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
-				}
-				client = &http.Client{Transport: tr}
-			} else {
-				client = &http.Client{}
-			}
-
-			resp, err := client.Do(req)
-			if err == nil {
-				body, err := ioutil.ReadAll(resp.Body)
-				defer resp.Body.Close()
-				if err == nil {
-					if resp.StatusCode == 200 {
-						c.JSON(200, body)
-					} else {
-						c.JSON(400, models.APIResponse{
-							Data: "Something went wrong while reaching the Kerberos Hub API: " + string(body),
-						})
-					}
-				} else {
-					c.JSON(400, models.APIResponse{
-						Data: "Something went wrong while ready the response body: " + err.Error(),
-					})
-				}
-			} else {
-				c.JSON(400, models.APIResponse{
-					Data: "Something went wrong while reaching to the Kerberos Hub API: " + hubURI,
-				})
-			}
-		} else {
-			c.JSON(400, models.APIResponse{
-				Data: "Something went wrong while creating the HTTP request: " + err.Error(),
-			})
-		}
-	} else {
-		c.JSON(400, models.APIResponse{
-			Data: "Something went wrong while receiving the config " + err.Error(),
-		})
-	}
-}
-
-// VerifyPersistence godoc
-// @Router /api/persistence/verify [post]
-// @ID verify-persistence
-// @Security Bearer
-// @securityDefinitions.apikey Bearer
-// @in header
-// @name Authorization
-// @Tags config
-// @Param config body models.Config true "Config"
-// @Summary Will verify the persistence.
-// @Description Will verify the persistence.
-// @Success 200 {object} models.APIResponse
-func VerifyPersistence(c *gin.Context, configDirectory string) {
-
-	var config models.Config
-	err := c.BindJSON(&config)
-	if err != nil || config.Cloud != "" {
-
-		if config.Cloud == "dropbox" {
-			VerifyDropbox(config, c)
-		} else if config.Cloud == "s3" || config.Cloud == "kerberoshub" {
-
-			if config.HubURI == "" ||
-				config.HubKey == "" ||
-				config.HubPrivateKey == "" ||
-				config.S3.Region == "" {
-				msg := "VerifyPersistence: Kerberos Hub not properly configured."
-				log.Log.Info(msg)
-				c.JSON(400, models.APIResponse{
-					Data: msg,
-				})
-			} else {
-
-				// Open test-480p.mp4
-				file, err := os.Open(configDirectory + "/data/test-480p.mp4")
-				if err != nil {
-					msg := "VerifyPersistence: error reading test-480p.mp4: " + err.Error()
-					log.Log.Error(msg)
-					c.JSON(400, models.APIResponse{
-						Data: msg,
-					})
-				}
-				defer file.Close()
-
-				req, err := http.NewRequest("POST", config.HubURI+"/storage/upload", file)
-				if err != nil {
-					msg := "VerifyPersistence: error reading Kerberos Hub HEAD request, " + config.HubURI + "/storage: " + err.Error()
-					log.Log.Error(msg)
-					c.JSON(400, models.APIResponse{
-						Data: msg,
-					})
-				}
-
-				timestamp := time.Now().Unix()
-				fileName := strconv.FormatInt(timestamp, 10) +
-					"_6-967003_" + config.Name + "_200-200-400-400_24_769.mp4"
-				req.Header.Set("X-Kerberos-Storage-FileName", fileName)
-				req.Header.Set("X-Kerberos-Storage-Capture", "IPCamera")
-				req.Header.Set("X-Kerberos-Storage-Device", config.Key)
-				req.Header.Set("X-Kerberos-Hub-PublicKey", config.HubKey)
-				req.Header.Set("X-Kerberos-Hub-PrivateKey", config.HubPrivateKey)
-				req.Header.Set("X-Kerberos-Hub-Region", config.S3.Region)
-
-				var client *http.Client
-				if os.Getenv("AGENT_TLS_INSECURE") == "true" {
-					tr := &http.Transport{
-						TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
-					}
-					client = &http.Client{Transport: tr}
-				} else {
-					client = &http.Client{}
-				}
-
-				resp, err := client.Do(req)
-				if resp != nil {
-					defer resp.Body.Close()
-				}
-
-				if err == nil && resp != nil {
-					if resp.StatusCode == 200 {
-						msg := "VerifyPersistence: Upload allowed using the credentials provided (" + config.HubKey + ", " + config.HubPrivateKey + ")"
-						log.Log.Info(msg)
-						c.JSON(200, models.APIResponse{
-							Data: msg,
-						})
-					} else {
-						msg := "VerifyPersistence: Upload NOT allowed using the credentials provided (" + config.HubKey + ", " + config.HubPrivateKey + ")"
-						log.Log.Info(msg)
-						c.JSON(400, models.APIResponse{
-							Data: msg,
-						})
-					}
-				} else {
-					msg := "VerifyPersistence: Error creating Kerberos Hub request"
-					log.Log.Info(msg)
-					c.JSON(400, models.APIResponse{
-						Data: msg,
-					})
-				}
-			}
-
-		} else if config.Cloud == "kstorage" || config.Cloud == "kerberosvault" {
-
-			uri := config.KStorage.URI
-			accessKey := config.KStorage.AccessKey
-			secretAccessKey := config.KStorage.SecretAccessKey
-			directory := config.KStorage.Directory
-			provider := config.KStorage.Provider
-
-			if err == nil && uri != "" && accessKey != "" && secretAccessKey != "" {
-
-				var client *http.Client
-				if os.Getenv("AGENT_TLS_INSECURE") == "true" {
-					tr := &http.Transport{
-						TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
-					}
-					client = &http.Client{Transport: tr}
-				} else {
-					client = &http.Client{}
-				}
-
-				req, err := http.NewRequest("POST", uri+"/ping", nil)
-				req.Header.Add("X-Kerberos-Storage-AccessKey", accessKey)
-				req.Header.Add("X-Kerberos-Storage-SecretAccessKey", secretAccessKey)
-				resp, err := client.Do(req)
-
-				if err == nil {
-					body, err := ioutil.ReadAll(resp.Body)
-					defer resp.Body.Close()
-					if err == nil && resp.StatusCode == http.StatusOK {
-
-						if provider != "" || directory != "" {
-
-							// Generate a random name.
-							timestamp := time.Now().Unix()
-							fileName := strconv.FormatInt(timestamp, 10) +
-								"_6-967003_" + config.Name + "_200-200-400-400_24_769.mp4"
-
-							// Open test-480p.mp4
-							file, err := os.Open(configDirectory + "/test-480p.mp4")
-							if err != nil {
-								msg := "VerifyPersistence: error reading test-480p.mp4: " + err.Error()
-								log.Log.Error(msg)
-								c.JSON(400, models.APIResponse{
-									Data: msg,
-								})
-							}
-							defer file.Close()
-
-							req, err := http.NewRequest("POST", uri+"/storage", file)
-							if err == nil {
-
-								req.Header.Set("Content-Type", "video/mp4")
-								req.Header.Set("X-Kerberos-Storage-CloudKey", config.HubKey)
-								req.Header.Set("X-Kerberos-Storage-AccessKey", accessKey)
-								req.Header.Set("X-Kerberos-Storage-SecretAccessKey", secretAccessKey)
-								req.Header.Set("X-Kerberos-Storage-Provider", provider)
-								req.Header.Set("X-Kerberos-Storage-FileName", fileName)
-								req.Header.Set("X-Kerberos-Storage-Device", config.Key)
-								req.Header.Set("X-Kerberos-Storage-Capture", "IPCamera")
-								req.Header.Set("X-Kerberos-Storage-Directory", directory)
-
-								var client *http.Client
-								if os.Getenv("AGENT_TLS_INSECURE") == "true" {
-									tr := &http.Transport{
-										TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
-									}
-									client = &http.Client{Transport: tr}
-								} else {
-									client = &http.Client{}
-								}
-
-								resp, err := client.Do(req)
-
-								if err == nil {
-									if resp != nil {
-										body, err := ioutil.ReadAll(resp.Body)
-										defer resp.Body.Close()
-										if err == nil {
-											if resp.StatusCode == 200 {
-												c.JSON(200, body)
-											} else {
-												c.JSON(400, models.APIResponse{
-													Data: "VerifyPersistence: Something went wrong while verifying your persistence settings. Make sure your provider is the same as the storage provider in your Kerberos Vault, and the relevant storage provider is configured properly.",
-												})
-											}
-										}
-									}
-								} else {
-									c.JSON(400, models.APIResponse{
-										Data: "VerifyPersistence: Upload of fake recording failed: " + err.Error(),
-									})
-								}
-							} else {
-								c.JSON(400, models.APIResponse{
-									Data: "VerifyPersistence: Something went wrong while creating /storage POST request." + err.Error(),
-								})
-							}
-						} else {
-							c.JSON(400, models.APIResponse{
-								Data: "VerifyPersistence: Provider and/or directory is missing from the request.",
-							})
-						}
-					} else {
-						c.JSON(400, models.APIResponse{
-							Data: "VerifyPersistence: Something went wrong while verifying storage credentials: " + string(body),
-						})
-					}
-				} else {
-					c.JSON(400, models.APIResponse{
-						Data: "VerifyPersistence: Something went wrong while verifying storage credentials:" + err.Error(),
-					})
-				}
-			} else {
-				c.JSON(400, models.APIResponse{
-					Data: "VerifyPersistence: please fill-in the required Kerberos Vault credentials.",
-				})
-			}
-		}
-	} else {
-		c.JSON(400, models.APIResponse{
-			Data: "VerifyPersistence: No persistence was specified, so do not know what to verify:" + err.Error(),
-		})
-	}
-}

machinery/src/cloud/KerberosHub.go

@@ -1,131 +0,0 @@
-package cloud
-
-import (
-	"crypto/tls"
-	"errors"
-	"io/ioutil"
-	"net/http"
-	"os"
-
-	"github.com/kerberos-io/agent/machinery/src/log"
-	"github.com/kerberos-io/agent/machinery/src/models"
-)
-
-func UploadKerberosHub(configuration *models.Configuration, fileName string) (bool, bool, error) {
-	config := configuration.Config
-
-	if config.HubURI == "" ||
-		config.HubKey == "" ||
-		config.HubPrivateKey == "" ||
-		config.S3.Region == "" {
-		err := "UploadKerberosHub: Kerberos Hub not properly configured."
-		log.Log.Info(err)
-		return false, false, errors.New(err)
-	}
-
-	// timestamp_microseconds_instanceName_regionCoordinates_numberOfChanges_token
-	// 1564859471_6-474162_oprit_577-283-727-375_1153_27.mp4
-	// - Timestamp
-	// - Size + - + microseconds
-	// - device
-	// - Region
-	// - Number of changes
-	// - Token
-
-	log.Log.Info("UploadKerberosHub: Uploading to Kerberos Hub (" + config.HubURI + ")")
-	log.Log.Info("UploadKerberosHub: Upload started for " + fileName)
-	fullname := "data/recordings/" + fileName
-
-	// Check if we still have the file otherwise we abort the request.
-	file, err := os.OpenFile(fullname, os.O_RDWR, 0755)
-	if file != nil {
-		defer file.Close()
-	}
-	if err != nil {
-		err := "UploadKerberosHub: Upload Failed, file doesn't exists anymore."
-		log.Log.Info(err)
-		return false, false, errors.New(err)
-	}
-
-	// Check if we are allowed to upload to the hub with these credentials.
-	// There might be different reasons like (muted, read-only..)
-	req, err := http.NewRequest("HEAD", config.HubURI+"/storage/upload", nil)
-	if err != nil {
-		errorMessage := "UploadKerberosHub: error reading HEAD request, " + config.HubURI + "/storage: " + err.Error()
-		log.Log.Error(errorMessage)
-		return false, true, errors.New(errorMessage)
-	}
-
-	req.Header.Set("X-Kerberos-Storage-FileName", fileName)
-	req.Header.Set("X-Kerberos-Storage-Capture", "IPCamera")
-	req.Header.Set("X-Kerberos-Storage-Device", config.Key)
-	req.Header.Set("X-Kerberos-Hub-PublicKey", config.HubKey)
-	req.Header.Set("X-Kerberos-Hub-PrivateKey", config.HubPrivateKey)
-	req.Header.Set("X-Kerberos-Hub-Region", config.S3.Region)
-
-	var client *http.Client
-	if os.Getenv("AGENT_TLS_INSECURE") == "true" {
-		tr := &http.Transport{
-			TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
-		}
-		client = &http.Client{Transport: tr}
-	} else {
-		client = &http.Client{}
-	}
-
-	resp, err := client.Do(req)
-	if resp != nil {
-		defer resp.Body.Close()
-	}
-
-	if err == nil {
-		if resp != nil {
-			if err == nil {
-				if resp.StatusCode == 200 {
-					log.Log.Info("UploadKerberosHub: Upload allowed using the credentials provided (" + config.HubKey + ", " + config.HubPrivateKey + ")")
-				} else {
-					log.Log.Info("UploadKerberosHub: Upload NOT allowed using the credentials provided (" + config.HubKey + ", " + config.HubPrivateKey + ")")
-					return false, true, nil
-				}
-			}
-		}
-	}
-
-	// Now we know we are allowed to upload to the hub, we can start uploading.
-	req, err = http.NewRequest("POST", config.HubURI+"/storage/upload", file)
-	if err != nil {
-		errorMessage := "UploadKerberosHub: error reading POST request, " + config.KStorage.URI + "/storage/upload: " + err.Error()
-		log.Log.Error(errorMessage)
-		return false, true, errors.New(errorMessage)
-	}
-	req.Header.Set("Content-Type", "video/mp4")
-	req.Header.Set("X-Kerberos-Storage-FileName", fileName)
-	req.Header.Set("X-Kerberos-Storage-Capture", "IPCamera")
-	req.Header.Set("X-Kerberos-Storage-Device", config.Key)
-	req.Header.Set("X-Kerberos-Hub-PublicKey", config.HubKey)
-	req.Header.Set("X-Kerberos-Hub-PrivateKey", config.HubPrivateKey)
-	req.Header.Set("X-Kerberos-Hub-Region", config.S3.Region)
-	resp, err = client.Do(req)
-	if resp != nil {
-		defer resp.Body.Close()
-	}
-
-	if err == nil {
-		if resp != nil {
-			body, err := ioutil.ReadAll(resp.Body)
-			if err == nil {
-				if resp.StatusCode == 200 {
-					log.Log.Info("UploadKerberosHub: Upload Finished, " + resp.Status + ".")
-					return true, true, nil
-				} else {
-					log.Log.Info("UploadKerberosHub: Upload Failed, " + resp.Status + ", " + string(body))
-					return false, true, nil
-				}
-			}
-		}
-	}
-
-	errorMessage := "UploadKerberosHub: Upload Failed, " + err.Error()
-	log.Log.Info(errorMessage)
-	return false, true, errors.New(errorMessage)
-}

machinery/src/cloud/KerberosVault.go

@@ -1,105 +0,0 @@
-package cloud
-
-import (
-	"crypto/tls"
-	"errors"
-	"io/ioutil"
-	"net/http"
-	"os"
-
-	"github.com/kerberos-io/agent/machinery/src/log"
-	"github.com/kerberos-io/agent/machinery/src/models"
-)
-
-func UploadKerberosVault(configuration *models.Configuration, fileName string) (bool, bool, error) {
-
-	config := configuration.Config
-
-	if config.KStorage.AccessKey == "" ||
-		config.KStorage.SecretAccessKey == "" ||
-		config.KStorage.Directory == "" ||
-		config.KStorage.URI == "" {
-		err := "UploadKerberosVault: Kerberos Vault not properly configured."
-		log.Log.Info(err)
-		return false, false, errors.New(err)
-	}
-
-	// timestamp_microseconds_instanceName_regionCoordinates_numberOfChanges_token
-	// 1564859471_6-474162_oprit_577-283-727-375_1153_27.mp4
-	// - Timestamp
-	// - Size + - + microseconds
-	// - device
-	// - Region
-	// - Number of changes
-	// - Token
-	// KerberosCloud, this means storage is disabled and proxy enabled.
-	log.Log.Info("UploadKerberosVault: Uploading to Kerberos Vault (" + config.KStorage.URI + ")")
-	log.Log.Info("UploadKerberosVault: Upload started for " + fileName)
-	fullname := "data/recordings/" + fileName
-
-	file, err := os.OpenFile(fullname, os.O_RDWR, 0755)
-	if file != nil {
-		defer file.Close()
-	}
-	if err != nil {
-		err := "UploadKerberosVault: Upload Failed, file doesn't exists anymore."
-		log.Log.Info(err)
-		return false, false, errors.New(err)
-	}
-
-	publicKey := config.KStorage.CloudKey
-	// This is the new way ;)
-	if config.HubKey != "" {
-		publicKey = config.HubKey
-	}
-
-	req, err := http.NewRequest("POST", config.KStorage.URI+"/storage", file)
-	if err != nil {
-		errorMessage := "UploadKerberosVault: error reading request, " + config.KStorage.URI + "/storage: " + err.Error()
-		log.Log.Error(errorMessage)
-		return false, true, errors.New(errorMessage)
-	}
-	req.Header.Set("Content-Type", "video/mp4")
-	req.Header.Set("X-Kerberos-Storage-CloudKey", publicKey)
-	req.Header.Set("X-Kerberos-Storage-AccessKey", config.KStorage.AccessKey)
-	req.Header.Set("X-Kerberos-Storage-SecretAccessKey", config.KStorage.SecretAccessKey)
-	req.Header.Set("X-Kerberos-Storage-Provider", config.KStorage.Provider)
-	req.Header.Set("X-Kerberos-Storage-FileName", fileName)
-	req.Header.Set("X-Kerberos-Storage-Device", config.Key)
-	req.Header.Set("X-Kerberos-Storage-Capture", "IPCamera")
-	req.Header.Set("X-Kerberos-Storage-Directory", config.KStorage.Directory)
-
-	var client *http.Client
-	if os.Getenv("AGENT_TLS_INSECURE") == "true" {
-		tr := &http.Transport{
-			TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
-		}
-		client = &http.Client{Transport: tr}
-	} else {
-		client = &http.Client{}
-	}
-
-	resp, err := client.Do(req)
-	if resp != nil {
-		defer resp.Body.Close()
-	}
-
-	if err == nil {
-		if resp != nil {
-			body, err := ioutil.ReadAll(resp.Body)
-			if err == nil {
-				if resp.StatusCode == 200 {
-					log.Log.Info("UploadKerberosVault: Upload Finished, " + resp.Status + ", " + string(body))
-					return true, true, nil
-				} else {
-					log.Log.Info("UploadKerberosVault: Upload Failed, " + resp.Status + ", " + string(body))
-					return false, true, nil
-				}
-			}
-		}
-	}
-
-	errorMessage := "UploadKerberosVault: Upload Failed, " + err.Error()
-	log.Log.Info(errorMessage)
-	return false, true, errors.New(errorMessage)
-}

machinery/src/cloud/S3.go

@@ -1,137 +0,0 @@
-package cloud
-
-import (
-	"crypto/tls"
-	"errors"
-	"net/http"
-	"net/url"
-	"os"
-	"strconv"
-	"strings"
-
-	"github.com/kerberos-io/agent/machinery/src/log"
-	"github.com/kerberos-io/agent/machinery/src/models"
-	"github.com/minio/minio-go/v6"
-)
-
-func UploadS3(configuration *models.Configuration, fileName string) (bool, bool, error) {
-
-	config := configuration.Config
-
-	// timestamp_microseconds_instanceName_regionCoordinates_numberOfChanges_token
-	// 1564859471_6-474162_oprit_577-283-727-375_1153_27.mp4
-	// - Timestamp
-	// - Size + - + microseconds
-	// - device
-	// - Region
-	// - Number of changes
-	// - Token
-
-	if config.S3 == nil {
-		errorMessage := "UploadS3: Uploading Failed, as no settings found"
-		log.Log.Error(errorMessage)
-		return false, false, errors.New(errorMessage)
-	}
-
-	// Legacy support, should get rid of it!
-	aws_access_key_id := config.S3.Publickey
-	aws_secret_access_key := config.S3.Secretkey
-	aws_region := config.S3.Region
-
-	// This is the new way ;)
-	if config.HubKey != "" {
-		aws_access_key_id = config.HubKey
-	}
-	if config.HubPrivateKey != "" {
-		aws_secret_access_key = config.HubPrivateKey
-	}
-
-	// Check if we have some credentials otherwise we abort the request.
-	if aws_access_key_id == "" || aws_secret_access_key == "" {
-		errorMessage := "UploadS3: Uploading Failed, as no credentials found"
-		log.Log.Error(errorMessage)
-		return false, false, errors.New(errorMessage)
-	}
-
-	s3Client, err := minio.NewWithRegion("s3.amazonaws.com", aws_access_key_id, aws_secret_access_key, true, aws_region)
-	if err != nil {
-		errorMessage := "UploadS3: " + err.Error()
-		log.Log.Error(errorMessage)
-		return false, true, errors.New(errorMessage)
-	}
-
-	// Check if we need to use the proxy.
-	if config.S3.ProxyURI != "" {
-		var transport http.RoundTripper = &http.Transport{
-			Proxy: func(*http.Request) (*url.URL, error) {
-				return url.Parse(config.S3.ProxyURI)
-			},
-			TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
-		}
-		s3Client.SetCustomTransport(transport)
-	}
-
-	fileParts := strings.Split(fileName, "_")
-	if len(fileParts) == 1 {
-		errorMessage := "UploadS3: " + fileName + " is not a valid name."
-		log.Log.Error(errorMessage)
-		return false, true, errors.New(errorMessage)
-	}
-
-	deviceKey := config.Key
-	startRecording, _ := strconv.ParseInt(fileParts[0], 10, 64)
-	devicename := fileParts[2]
-	coordinates := fileParts[3]
-	//numberOfChanges := fileParts[4]
-	token, _ := strconv.Atoi(fileParts[5])
-
-	log.Log.Info("UploadS3: Upload started for " + fileName)
-	fullname := "data/recordings/" + fileName
-
-	file, err := os.OpenFile(fullname, os.O_RDWR, 0755)
-	if file != nil {
-		defer file.Close()
-	}
-
-	if err != nil {
-		errorMessage := "UploadS3: " + err.Error()
-		log.Log.Error(errorMessage)
-		return false, true, errors.New(errorMessage)
-	}
-
-	fileInfo, err := file.Stat()
-	if err != nil {
-		errorMessage := "UploadS3: " + err.Error()
-		log.Log.Error(errorMessage)
-		return false, true, errors.New(errorMessage)
-	}
-
-	n, err := s3Client.PutObject(config.S3.Bucket,
-		config.S3.Username+"/"+fileName,
-		file,
-		fileInfo.Size(),
-		minio.PutObjectOptions{
-			ContentType:  "video/mp4",
-			StorageClass: "ONEZONE_IA",
-			UserMetadata: map[string]string{
-				"event-timestamp":         strconv.FormatInt(startRecording, 10),
-				"event-microseconds":      deviceKey,
-				"event-instancename":      devicename,
-				"event-regioncoordinates": coordinates,
-				"event-numberofchanges":   deviceKey,
-				"event-token":             strconv.Itoa(token),
-				"productid":               deviceKey,
-				"publickey":               aws_access_key_id,
-				"uploadtime":              "now",
-			},
-		})
-
-	if err != nil {
-		errorMessage := "UploadS3: Uploading Failed, " + err.Error()
-		log.Log.Error(errorMessage)
-		return false, true, errors.New(errorMessage)
-	} else {
-		log.Log.Info("UploadS3: Upload Finished, file has been uploaded to bucket: " + strconv.FormatInt(n, 10))
-		return true, true, nil
-	}
-}

machinery/src/cloud/cloud_test.go

@@ -0,0 +1,849 @@
+package cloud
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/kerberos-io/agent/machinery/src/models"
+	agentonvif "github.com/kerberos-io/agent/machinery/src/onvif"
+	goonvif "github.com/kerberos-io/onvif"
+	goonvifdevice "github.com/kerberos-io/onvif/device"
+	goonvifptz "github.com/kerberos-io/onvif/ptz"
+	goonvifxsd "github.com/kerberos-io/onvif/xsd/onvif"
+)
+
+func TestVerifyPersistenceKerberosHubUsesAuthorizationHead(t *testing.T) {
+	var requestMethod string
+	var requestBody []byte
+	var requestHeaders http.Header
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requestMethod = r.Method
+		requestHeaders = r.Header.Clone()
+		requestBody, _ = io.ReadAll(r.Body)
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer server.Close()
+
+	config := models.Config{
+		Cloud:         "kerberoshub",
+		Key:           "camera-1",
+		Name:          "front-door",
+		HubURI:        server.URL,
+		HubKey:        "project-public",
+		HubPrivateKey: "project-private",
+		S3:            &models.S3{Region: "eu"},
+	}
+	payload, err := json.Marshal(config)
+	if err != nil {
+		t.Fatalf("json.Marshal() error = %v", err)
+	}
+
+	gin.SetMode(gin.TestMode)
+	recorder := httptest.NewRecorder()
+	ctx, _ := gin.CreateTestContext(recorder)
+	ctx.Request = httptest.NewRequest(http.MethodPost, "/api/persistence/verify", bytes.NewReader(payload))
+	ctx.Request.Header.Set("Content-Type", "application/json")
+
+	VerifyPersistence(ctx, t.TempDir(), server.URL)
+
+	if recorder.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", recorder.Code, recorder.Body.String())
+	}
+	if requestMethod != http.MethodHead {
+		t.Fatalf("Hub request method = %q, want HEAD", requestMethod)
+	}
+	if len(requestBody) != 0 {
+		t.Fatalf("Hub request body has %d bytes, want none", len(requestBody))
+	}
+	for header, want := range map[string]string{
+		"X-Kerberos-Storage-Device":  "camera-1",
+		"X-Kerberos-Hub-PublicKey":   "project-public",
+		"X-Kerberos-Hub-PrivateKey":  "project-private",
+		"X-Kerberos-Hub-Region":      "eu",
+		"X-Kerberos-Storage-Capture": "IPCamera",
+	} {
+		if got := requestHeaders.Get(header); got != want {
+			t.Errorf("%s = %q, want %q", header, got, want)
+		}
+	}
+}
+
+func TestVerifyPersistenceKerberosHubRejectsCrossHostRedirect(t *testing.T) {
+	var redirectedHeaders http.Header
+	target := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		redirectedHeaders = r.Header.Clone()
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer target.Close()
+
+	var originalHeaders http.Header
+	hub := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		originalHeaders = r.Header.Clone()
+		http.Redirect(w, r, target.URL+"/storage/upload", http.StatusTemporaryRedirect)
+	}))
+	defer hub.Close()
+
+	config := models.Config{
+		Cloud:         "kerberoshub",
+		Key:           "camera-1",
+		Name:          "front-door",
+		HubURI:        hub.URL,
+		HubKey:        "project-public",
+		HubPrivateKey: "project-private",
+		S3:            &models.S3{Region: "eu"},
+	}
+	payload, err := json.Marshal(config)
+	if err != nil {
+		t.Fatalf("json.Marshal() error = %v", err)
+	}
+
+	gin.SetMode(gin.TestMode)
+	recorder := httptest.NewRecorder()
+	ctx, _ := gin.CreateTestContext(recorder)
+	ctx.Request = httptest.NewRequest(http.MethodPost, "/api/persistence/verify", bytes.NewReader(payload))
+	ctx.Request.Header.Set("Content-Type", "application/json")
+
+	VerifyPersistence(ctx, t.TempDir(), hub.URL)
+
+	if recorder.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d; body = %s", recorder.Code, http.StatusBadRequest, recorder.Body.String())
+	}
+	for _, header := range []string{"X-Kerberos-Hub-PublicKey", "X-Kerberos-Hub-PrivateKey"} {
+		if originalHeaders.Get(header) == "" {
+			t.Errorf("%s was not sent to the configured Hub", header)
+		}
+		if redirectedHeaders != nil {
+			t.Errorf("redirect target received a request with %s=%q", header, redirectedHeaders.Get(header))
+		}
+	}
+}
+
+func TestVerifyPersistenceKerberosHubRejectsUnsavedURI(t *testing.T) {
+	requestCount := 0
+	untrusted := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		requestCount++
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer untrusted.Close()
+
+	config := models.Config{
+		Cloud:         "kerberoshub",
+		Key:           "camera-1",
+		Name:          "front-door",
+		HubURI:        untrusted.URL,
+		HubKey:        "project-public",
+		HubPrivateKey: "project-private",
+		S3:            &models.S3{Region: "eu"},
+	}
+	payload, err := json.Marshal(config)
+	if err != nil {
+		t.Fatalf("json.Marshal() error = %v", err)
+	}
+
+	gin.SetMode(gin.TestMode)
+	recorder := httptest.NewRecorder()
+	ctx, _ := gin.CreateTestContext(recorder)
+	ctx.Request = httptest.NewRequest(http.MethodPost, "/api/persistence/verify", bytes.NewReader(payload))
+	ctx.Request.Header.Set("Content-Type", "application/json")
+
+	VerifyPersistence(ctx, t.TempDir(), "https://saved-hub.example.com")
+
+	if recorder.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d; body = %s", recorder.Code, http.StatusBadRequest, recorder.Body.String())
+	}
+	if requestCount != 0 {
+		t.Fatalf("untrusted Hub received %d requests, want none", requestCount)
+	}
+}
+
+func TestVerifyHubRejectsUnsavedURI(t *testing.T) {
+	requestCount := 0
+	untrusted := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		requestCount++
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer untrusted.Close()
+
+	config := models.Config{
+		HubURI:        untrusted.URL,
+		HubKey:        "project-public",
+		HubPrivateKey: "project-private",
+	}
+	payload, err := json.Marshal(config)
+	if err != nil {
+		t.Fatalf("json.Marshal() error = %v", err)
+	}
+
+	gin.SetMode(gin.TestMode)
+	recorder := httptest.NewRecorder()
+	ctx, _ := gin.CreateTestContext(recorder)
+	ctx.Request = httptest.NewRequest(http.MethodPost, "/api/hub/verify", bytes.NewReader(payload))
+	ctx.Request.Header.Set("Content-Type", "application/json")
+
+	VerifyHub(ctx, "https://saved-hub.example.com")
+
+	if recorder.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d; body = %s", recorder.Code, http.StatusBadRequest, recorder.Body.String())
+	}
+	if requestCount != 0 {
+		t.Fatalf("untrusted Hub received %d requests, want none", requestCount)
+	}
+}
+
+func TestHubPersistenceVerificationErrorExplainsStatus(t *testing.T) {
+	for _, test := range []struct {
+		status int
+		want   string
+	}{
+		{status: http.StatusBadRequest, want: "credentials or device/project assignment"},
+		{status: http.StatusUnauthorized, want: "no active subscription"},
+		{status: http.StatusForbidden, want: "device is muted"},
+		{status: http.StatusBadGateway, want: "HTTP 502"},
+	} {
+		t.Run(http.StatusText(test.status), func(t *testing.T) {
+			if got := hubPersistenceVerificationError(test.status); !strings.Contains(got, test.want) {
+				t.Fatalf("hubPersistenceVerificationError(%d) = %q, want it to contain %q", test.status, got, test.want)
+			}
+		})
+	}
+}
+
+func TestHeartbeatFailureLogOmitsHubResponseBody(t *testing.T) {
+	response := &http.Response{
+		StatusCode: http.StatusBadRequest,
+		Status:     "400 Bad Request",
+		Body:       io.NopCloser(strings.NewReader(`{"error":"invalid heartbeat"}`)),
+	}
+
+	responseBody, truncated, err := readHeartbeatResponseBody(response)
+	if err != nil {
+		t.Fatalf("readHeartbeatResponseBody() error = %v", err)
+	}
+	fields := heartbeatFailureLogFields(response, responseBody, truncated, 125*time.Millisecond)
+
+	for key, want := range map[string]interface{}{
+		"duration_ms":             int64(125),
+		"response_body_bytes":     len(responseBody),
+		"response_body_truncated": false,
+		"status_code":             http.StatusBadRequest,
+	} {
+		if got := fields[key]; got != want {
+			t.Errorf("%s = %v, want %v", key, got, want)
+		}
+	}
+	for key, value := range fields {
+		if strings.Contains(key, "response_body") && key != "response_body_bytes" && key != "response_body_truncated" {
+			t.Fatalf("unexpected response body field %q=%v", key, value)
+		}
+		if strings.Contains(fmt.Sprint(value), "invalid heartbeat") {
+			t.Fatalf("heartbeat log fields exposed response body in %q=%v", key, value)
+		}
+	}
+}
+
+func TestReadHeartbeatResponseBodyTruncatesLargeBody(t *testing.T) {
+	response := &http.Response{
+		Body: io.NopCloser(strings.NewReader(strings.Repeat("x", heartbeatResponseBodyLogLimit+1))),
+	}
+
+	body, truncated, err := readHeartbeatResponseBody(response)
+	if err != nil {
+		t.Fatalf("readHeartbeatResponseBody() error = %v", err)
+	}
+	if !truncated {
+		t.Fatal("readHeartbeatResponseBody() truncated = false, want true")
+	}
+	if len(body) != heartbeatResponseBodyLogLimit {
+		t.Fatalf("len(body) = %d, want %d", len(body), heartbeatResponseBodyLogLimit)
+	}
+}
+
+func TestHeartbeatONVIFPayloadCachesStaticAndReusesLoopSubscription(t *testing.T) {
+	restoreHeartbeatONVIFStubs(t)
+
+	device := newTestONVIFDevice()
+	camera := models.IPCamera{
+		ONVIFXAddr:    "http://camera/onvif",
+		ONVIFUsername: "operator",
+		ONVIFPassword: "secret",
+	}
+	initialEvents := []agentonvif.ONVIFEvents{{Key: "input-1", Type: "input", Value: "true", Timestamp: 1}}
+	loopEvents := []agentonvif.ONVIFEvents{{Key: "output-1", Type: "output", Value: "false", Timestamp: 2}}
+	wantPresets := mustJSONMarshal(t, []models.OnvifActionPreset{{Name: "Lobby", Token: "1"}})
+	wantInitialEvents := mustJSONMarshal(t, initialEvents)
+	wantLoopEvents := mustJSONMarshal(t, loopEvents)
+
+	var connectCalls, ptzConfigCalls, ptzFunctionCalls, presetCalls, createCalls, eventCalls, unsubscribeCalls int
+
+	heartbeatConnectToONVIFDevice = func(*models.IPCamera) (*goonvif.Device, goonvifdevice.GetCapabilitiesResponse, error) {
+		connectCalls++
+		return device, goonvifdevice.GetCapabilitiesResponse{}, nil
+	}
+	heartbeatGetPTZConfigurationsFromDevice = func(*goonvif.Device) (goonvifptz.GetConfigurationsResponse, error) {
+		ptzConfigCalls++
+		return goonvifptz.GetConfigurationsResponse{}, nil
+	}
+	heartbeatGetPTZFunctionsFromDevice = func(goonvifptz.GetConfigurationsResponse) ([]string, bool, bool) {
+		ptzFunctionCalls++
+		return nil, true, true
+	}
+	heartbeatGetPresetsFromDevice = func(*goonvif.Device, int) ([]models.OnvifActionPreset, error) {
+		presetCalls++
+		return []models.OnvifActionPreset{{Name: "Lobby", Token: "1"}}, nil
+	}
+	heartbeatCreatePullPointSubscription = func(*goonvif.Device) (string, error) {
+		createCalls++
+		switch createCalls {
+		case 1:
+			return "initial-1", nil
+		case 2:
+			return "loop", nil
+		case 3:
+			return "initial-2", nil
+		default:
+			t.Fatalf("unexpected create pull point call %d", createCalls)
+			return "", nil
+		}
+	}
+	heartbeatGetEventMessages = func(_ *goonvif.Device, pullPointAddress string) ([]agentonvif.ONVIFEvents, error) {
+		eventCalls++
+		switch pullPointAddress {
+		case "initial-1", "initial-2":
+			return initialEvents, nil
+		case "loop":
+			return loopEvents, nil
+		default:
+			t.Fatalf("unexpected pull point address %q", pullPointAddress)
+			return nil, nil
+		}
+	}
+	heartbeatUnsubscribePullPoint = func(_ *goonvif.Device, pullPointAddress string) error {
+		unsubscribeCalls++
+		if pullPointAddress != "initial-1" && pullPointAddress != "initial-2" {
+			t.Fatalf("unexpected unsubscribe pull point %q", pullPointAddress)
+		}
+		return nil
+	}
+
+	state := newHeartbeatONVIFState()
+
+	payload := getHeartbeatONVIFPayload(camera, state)
+	if payload.enabled != "true" || payload.zoom != "true" || payload.panTilt != "true" || payload.presets != "true" {
+		t.Fatalf("unexpected static payload: %+v", payload)
+	}
+	if string(payload.presetsList) != string(wantPresets) {
+		t.Fatalf("payload.presetsList = %s, want %s", payload.presetsList, wantPresets)
+	}
+	if string(payload.eventsList) != string(wantInitialEvents) {
+		t.Fatalf("payload.eventsList = %s, want %s", payload.eventsList, wantInitialEvents)
+	}
+	if connectCalls != 1 || ptzConfigCalls != 1 || ptzFunctionCalls != 1 || presetCalls != 1 {
+		t.Fatalf("unexpected static call counts after first cycle: connect=%d ptzConfig=%d ptzFunctions=%d presets=%d", connectCalls, ptzConfigCalls, ptzFunctionCalls, presetCalls)
+	}
+	if createCalls != 2 || eventCalls != 1 || unsubscribeCalls != 1 {
+		t.Fatalf("unexpected event call counts after first cycle: create=%d events=%d unsubscribe=%d", createCalls, eventCalls, unsubscribeCalls)
+	}
+
+	payload = getHeartbeatONVIFPayload(camera, state)
+	if string(payload.eventsList) != string(wantLoopEvents) {
+		t.Fatalf("second payload.eventsList = %s, want %s", payload.eventsList, wantLoopEvents)
+	}
+	if connectCalls != 1 {
+		t.Fatalf("connectCalls = %d, want 1", connectCalls)
+	}
+	if ptzConfigCalls != 1 || ptzFunctionCalls != 1 || presetCalls != 1 {
+		t.Fatalf("static calls were not cached: ptzConfig=%d ptzFunctions=%d presets=%d", ptzConfigCalls, ptzFunctionCalls, presetCalls)
+	}
+	if createCalls != 3 || eventCalls != 3 || unsubscribeCalls != 2 {
+		t.Fatalf("temporary state subscription was not refreshed or loop subscription was not reused: create=%d events=%d unsubscribe=%d", createCalls, eventCalls, unsubscribeCalls)
+	}
+}
+
+func TestHeartbeatONVIFPayloadRefreshesAfterCameraConfigChange(t *testing.T) {
+	restoreHeartbeatONVIFStubs(t)
+
+	deviceA := newTestONVIFDevice()
+	deviceB := newTestONVIFDevice()
+	cameraA := models.IPCamera{ONVIFXAddr: "http://camera-a/onvif", ONVIFUsername: "user", ONVIFPassword: "secret-a"}
+	cameraB := models.IPCamera{ONVIFXAddr: "http://camera-b/onvif", ONVIFUsername: "user", ONVIFPassword: "secret-b"}
+	var connectCalls, ptzConfigCalls, presetCalls, createCalls int
+	var unsubscribed []string
+
+	heartbeatConnectToONVIFDevice = func(camera *models.IPCamera) (*goonvif.Device, goonvifdevice.GetCapabilitiesResponse, error) {
+		connectCalls++
+		switch camera.ONVIFXAddr {
+		case cameraA.ONVIFXAddr:
+			return deviceA, goonvifdevice.GetCapabilitiesResponse{}, nil
+		case cameraB.ONVIFXAddr:
+			return deviceB, goonvifdevice.GetCapabilitiesResponse{}, nil
+		default:
+			t.Fatalf("unexpected camera address %q", camera.ONVIFXAddr)
+			return nil, goonvifdevice.GetCapabilitiesResponse{}, nil
+		}
+	}
+	heartbeatGetPTZConfigurationsFromDevice = func(*goonvif.Device) (goonvifptz.GetConfigurationsResponse, error) {
+		ptzConfigCalls++
+		return goonvifptz.GetConfigurationsResponse{}, nil
+	}
+	heartbeatGetPTZFunctionsFromDevice = func(goonvifptz.GetConfigurationsResponse) ([]string, bool, bool) {
+		return nil, false, true
+	}
+	heartbeatGetPresetsFromDevice = func(*goonvif.Device, int) ([]models.OnvifActionPreset, error) {
+		presetCalls++
+		return nil, nil
+	}
+	heartbeatCreatePullPointSubscription = func(*goonvif.Device) (string, error) {
+		createCalls++
+		switch createCalls {
+		case 1:
+			return "initial-a", nil
+		case 2:
+			return "loop-a", nil
+		case 3:
+			return "initial-b", nil
+		case 4:
+			return "loop-b", nil
+		default:
+			t.Fatalf("unexpected create pull point call %d", createCalls)
+			return "", nil
+		}
+	}
+	heartbeatGetEventMessages = func(_ *goonvif.Device, pullPointAddress string) ([]agentonvif.ONVIFEvents, error) {
+		switch pullPointAddress {
+		case "initial-a":
+			return []agentonvif.ONVIFEvents{{Key: "a", Type: "input", Value: "true", Timestamp: 1}}, nil
+		case "initial-b":
+			return []agentonvif.ONVIFEvents{{Key: "b", Type: "input", Value: "false", Timestamp: 2}}, nil
+		default:
+			t.Fatalf("unexpected pull point address %q", pullPointAddress)
+			return nil, nil
+		}
+	}
+	heartbeatUnsubscribePullPoint = func(_ *goonvif.Device, pullPointAddress string) error {
+		unsubscribed = append(unsubscribed, pullPointAddress)
+		return nil
+	}
+
+	state := newHeartbeatONVIFState()
+	_ = getHeartbeatONVIFPayload(cameraA, state)
+	payload := getHeartbeatONVIFPayload(cameraB, state)
+
+	if connectCalls != 2 {
+		t.Fatalf("connectCalls = %d, want 2", connectCalls)
+	}
+	if ptzConfigCalls != 2 || presetCalls != 2 {
+		t.Fatalf("camera config change did not refresh static state: ptzConfig=%d presets=%d", ptzConfigCalls, presetCalls)
+	}
+	if createCalls != 4 {
+		t.Fatalf("camera config change did not recreate subscriptions: create=%d", createCalls)
+	}
+	if countString(unsubscribed, "loop-a") != 1 {
+		t.Fatalf("unsubscribed loop-a %d times, want 1; unsubscribed=%v", countString(unsubscribed, "loop-a"), unsubscribed)
+	}
+	wantEvents := mustJSONMarshal(t, []agentonvif.ONVIFEvents{{Key: "b", Type: "input", Value: "false", Timestamp: 2}})
+	if string(payload.eventsList) != string(wantEvents) {
+		t.Fatalf("payload.eventsList = %s, want %s", payload.eventsList, wantEvents)
+	}
+}
+
+func TestHeartbeatONVIFPayloadRetriesStaticFetchFailuresWithoutReconnect(t *testing.T) {
+	restoreHeartbeatONVIFStubs(t)
+
+	device := newTestONVIFDevice()
+	camera := models.IPCamera{
+		ONVIFXAddr:    "http://camera/onvif",
+		ONVIFUsername: "operator",
+		ONVIFPassword: "secret",
+	}
+	var connectCalls, ptzConfigCalls, presetCalls, createCalls, eventCalls int
+
+	heartbeatConnectToONVIFDevice = func(*models.IPCamera) (*goonvif.Device, goonvifdevice.GetCapabilitiesResponse, error) {
+		connectCalls++
+		return device, goonvifdevice.GetCapabilitiesResponse{}, nil
+	}
+	heartbeatGetPTZConfigurationsFromDevice = func(*goonvif.Device) (goonvifptz.GetConfigurationsResponse, error) {
+		ptzConfigCalls++
+		return goonvifptz.GetConfigurationsResponse{}, nil
+	}
+	heartbeatGetPTZFunctionsFromDevice = func(goonvifptz.GetConfigurationsResponse) ([]string, bool, bool) {
+		return nil, true, true
+	}
+	heartbeatGetPresetsFromDevice = func(*goonvif.Device, int) ([]models.OnvifActionPreset, error) {
+		presetCalls++
+		if presetCalls == 1 {
+			return nil, errors.New("temporary preset failure")
+		}
+		return []models.OnvifActionPreset{{Name: "Lobby", Token: "1"}}, nil
+	}
+	heartbeatCreatePullPointSubscription = func(*goonvif.Device) (string, error) {
+		createCalls++
+		switch createCalls {
+		case 1:
+			return "initial-1", nil
+		case 2:
+			return "loop", nil
+		case 3:
+			return "initial-2", nil
+		default:
+			t.Fatalf("unexpected create pull point call %d", createCalls)
+			return "", nil
+		}
+	}
+	heartbeatGetEventMessages = func(_ *goonvif.Device, pullPointAddress string) ([]agentonvif.ONVIFEvents, error) {
+		eventCalls++
+		switch pullPointAddress {
+		case "initial-1", "initial-2":
+			return []agentonvif.ONVIFEvents{{Key: "one", Type: "input", Value: "true", Timestamp: 1}}, nil
+		case "loop":
+			return []agentonvif.ONVIFEvents{{Key: "two", Type: "output", Value: "false", Timestamp: 2}}, nil
+		default:
+			t.Fatalf("unexpected pull point address %q", pullPointAddress)
+			return nil, nil
+		}
+	}
+	heartbeatUnsubscribePullPoint = func(*goonvif.Device, string) error { return nil }
+
+	state := newHeartbeatONVIFState()
+	payload := getHeartbeatONVIFPayload(camera, state)
+	if payload.presets != "false" {
+		t.Fatalf("payload.presets = %q, want false on transient preset failure", payload.presets)
+	}
+	payload = getHeartbeatONVIFPayload(camera, state)
+	if payload.presets != "true" {
+		t.Fatalf("payload.presets = %q, want true after retry", payload.presets)
+	}
+	if connectCalls != 1 {
+		t.Fatalf("connectCalls = %d, want 1", connectCalls)
+	}
+	if ptzConfigCalls != 2 || presetCalls != 2 {
+		t.Fatalf("static failures were not retried on heartbeat cadence: ptzConfig=%d presets=%d", ptzConfigCalls, presetCalls)
+	}
+	if createCalls != 3 || eventCalls != 3 {
+		t.Fatalf("unexpected event behavior during retry: create=%d events=%d", createCalls, eventCalls)
+	}
+}
+
+func TestHeartbeatONVIFStateReleasesSubscriptionWhenDisabled(t *testing.T) {
+	restoreHeartbeatONVIFStubs(t)
+
+	device := newTestONVIFDevice()
+	state := newHeartbeatONVIFState()
+	state.cameraConfiguration = models.IPCamera{ONVIFXAddr: "http://camera/onvif"}
+	state.cameraKey = heartbeatONVIFCameraKey(state.cameraConfiguration)
+	state.device = device
+	state.loopPullPoint = "loop"
+
+	var unsubscribed []string
+	heartbeatUnsubscribePullPoint = func(gotDevice *goonvif.Device, pullPointAddress string) error {
+		if gotDevice != device {
+			t.Fatal("unsubscribe used a different ONVIF device")
+		}
+		unsubscribed = append(unsubscribed, pullPointAddress)
+		return nil
+	}
+
+	state.prepare(models.IPCamera{})
+
+	if len(unsubscribed) != 1 || unsubscribed[0] != "loop" {
+		t.Fatalf("unsubscribed = %v, want [loop]", unsubscribed)
+	}
+	if state.device != nil || state.loopPullPoint != "" {
+		t.Fatalf("disabled state retained device or pull point: %+v", state)
+	}
+}
+
+func TestHeartbeatONVIFPayloadDoesNotCreateSubscriptionsWhenConnectFails(t *testing.T) {
+	restoreHeartbeatONVIFStubs(t)
+
+	var createCalls int
+
+	heartbeatConnectToONVIFDevice = func(*models.IPCamera) (*goonvif.Device, goonvifdevice.GetCapabilitiesResponse, error) {
+		return nil, goonvifdevice.GetCapabilitiesResponse{}, errors.New("connect failed")
+	}
+	heartbeatCreatePullPointSubscription = func(*goonvif.Device) (string, error) {
+		createCalls++
+		return "unexpected", nil
+	}
+
+	payload := getHeartbeatONVIFPayload(models.IPCamera{
+		ONVIFXAddr:    "http://camera/onvif",
+		ONVIFUsername: "operator",
+		ONVIFPassword: "secret",
+	}, newHeartbeatONVIFState())
+
+	if createCalls != 0 {
+		t.Fatalf("createCalls = %d, want 0", createCalls)
+	}
+	assertDefaultHeartbeatONVIFPayload(t, payload)
+}
+
+func TestHeartbeatONVIFPayloadReconnectFailureInvalidatesCache(t *testing.T) {
+	restoreHeartbeatONVIFStubs(t)
+
+	device1 := newTestONVIFDevice()
+	device2 := newTestONVIFDevice()
+	camera := models.IPCamera{
+		ONVIFXAddr:    "http://camera/onvif",
+		ONVIFUsername: "operator",
+		ONVIFPassword: "secret",
+	}
+	var connectCalls, ptzConfigCalls, presetCalls, createCalls int
+	var unsubscribed []string
+
+	heartbeatConnectToONVIFDevice = func(*models.IPCamera) (*goonvif.Device, goonvifdevice.GetCapabilitiesResponse, error) {
+		connectCalls++
+		switch connectCalls {
+		case 1:
+			return device1, goonvifdevice.GetCapabilitiesResponse{}, nil
+		case 2:
+			return device2, goonvifdevice.GetCapabilitiesResponse{}, nil
+		default:
+			t.Fatalf("unexpected connect call %d", connectCalls)
+			return nil, goonvifdevice.GetCapabilitiesResponse{}, nil
+		}
+	}
+	heartbeatGetPTZConfigurationsFromDevice = func(*goonvif.Device) (goonvifptz.GetConfigurationsResponse, error) {
+		ptzConfigCalls++
+		return goonvifptz.GetConfigurationsResponse{}, nil
+	}
+	heartbeatGetPTZFunctionsFromDevice = func(goonvifptz.GetConfigurationsResponse) ([]string, bool, bool) {
+		return nil, true, false
+	}
+	heartbeatGetPresetsFromDevice = func(*goonvif.Device, int) ([]models.OnvifActionPreset, error) {
+		presetCalls++
+		return []models.OnvifActionPreset{{Name: "Preset", Token: "1"}}, nil
+	}
+	heartbeatCreatePullPointSubscription = func(*goonvif.Device) (string, error) {
+		createCalls++
+		switch createCalls {
+		case 1:
+			return "initial-1", nil
+		case 2:
+			return "loop-1", nil
+		case 3:
+			return "initial-2", nil
+		case 4:
+			return "initial-3", nil
+		case 5:
+			return "loop-3", nil
+		default:
+			t.Fatalf("unexpected create pull point call %d", createCalls)
+			return "", nil
+		}
+	}
+	heartbeatGetEventMessages = func(_ *goonvif.Device, pullPointAddress string) ([]agentonvif.ONVIFEvents, error) {
+		switch pullPointAddress {
+		case "initial-1":
+			return []agentonvif.ONVIFEvents{{Key: "before", Type: "input", Value: "true", Timestamp: 1}}, nil
+		case "initial-2":
+			return []agentonvif.ONVIFEvents{{Key: "during", Type: "input", Value: "true", Timestamp: 2}}, nil
+		case "loop-1":
+			return nil, errors.New("pull failed")
+		case "initial-3":
+			return []agentonvif.ONVIFEvents{{Key: "after", Type: "input", Value: "false", Timestamp: 2}}, nil
+		default:
+			t.Fatalf("unexpected pull point address %q", pullPointAddress)
+			return nil, nil
+		}
+	}
+	heartbeatUnsubscribePullPoint = func(_ *goonvif.Device, pullPointAddress string) error {
+		unsubscribed = append(unsubscribed, pullPointAddress)
+		return nil
+	}
+
+	state := newHeartbeatONVIFState()
+	_ = getHeartbeatONVIFPayload(camera, state)
+	payload := getHeartbeatONVIFPayload(camera, state)
+	wantEventsDuringFailure := mustJSONMarshal(t, []agentonvif.ONVIFEvents{{Key: "during", Type: "input", Value: "true", Timestamp: 2}})
+	if string(payload.eventsList) != string(wantEventsDuringFailure) {
+		t.Fatalf("payload.eventsList after operation failure = %s, want %s", payload.eventsList, wantEventsDuringFailure)
+	}
+	payload = getHeartbeatONVIFPayload(camera, state)
+
+	if ptzConfigCalls != 2 || presetCalls != 2 {
+		t.Fatalf("reconnect did not refresh static state: ptzConfig=%d presets=%d", ptzConfigCalls, presetCalls)
+	}
+	if connectCalls != 2 {
+		t.Fatalf("connectCalls = %d, want 2 after reconnect", connectCalls)
+	}
+	if createCalls != 5 {
+		t.Fatalf("reconnect did not recreate subscriptions: create=%d", createCalls)
+	}
+	if countString(unsubscribed, "loop-1") != 1 {
+		t.Fatalf("operation failure cleanup mismatch, unsubscribed=%v", unsubscribed)
+	}
+	wantEvents := mustJSONMarshal(t, []agentonvif.ONVIFEvents{{Key: "after", Type: "input", Value: "false", Timestamp: 2}})
+	if string(payload.eventsList) != string(wantEvents) {
+		t.Fatalf("payload.eventsList = %s, want %s", payload.eventsList, wantEvents)
+	}
+}
+
+func TestHeartbeatONVIFPayloadKeepsCachedConnectionWhenInitialStateFetchFails(t *testing.T) {
+	restoreHeartbeatONVIFStubs(t)
+
+	device := newTestONVIFDevice()
+	camera := models.IPCamera{
+		ONVIFXAddr:    "http://camera/onvif",
+		ONVIFUsername: "operator",
+		ONVIFPassword: "secret",
+	}
+	loopEvents := []agentonvif.ONVIFEvents{{Key: "input-1", Type: "input", Value: "true", Timestamp: 1}}
+
+	state := newHeartbeatONVIFState()
+	state.cameraConfiguration = camera
+	state.cameraKey = heartbeatONVIFCameraKey(camera)
+	state.device = device
+	state.loopPullPoint = "loop"
+	state.staticLoaded = true
+	state.staticPayload.enabled = "true"
+
+	heartbeatCreatePullPointSubscription = func(*goonvif.Device) (string, error) {
+		return "", errors.New("temporary initial-state failure")
+	}
+	heartbeatGetEventMessages = func(_ *goonvif.Device, pullPointAddress string) ([]agentonvif.ONVIFEvents, error) {
+		if pullPointAddress != "loop" {
+			t.Fatalf("unexpected pull point address %q", pullPointAddress)
+		}
+		return loopEvents, nil
+	}
+
+	payload := getHeartbeatONVIFPayload(camera, state)
+
+	wantEvents := mustJSONMarshal(t, loopEvents)
+	if string(payload.eventsList) != string(wantEvents) {
+		t.Fatalf("payload.eventsList = %s, want %s", payload.eventsList, wantEvents)
+	}
+	if state.device != device || state.loopPullPoint != "loop" || !state.staticLoaded {
+		t.Fatalf("temporary failure invalidated healthy cached state: %+v", state)
+	}
+}
+
+func restoreHeartbeatONVIFStubs(t *testing.T) {
+	t.Helper()
+
+	originalConnect := heartbeatConnectToONVIFDevice
+	originalCreate := heartbeatCreatePullPointSubscription
+	originalDigitalInputs := heartbeatGetDigitalInputs
+	originalEvents := heartbeatGetEventMessages
+	originalPresets := heartbeatGetPresetsFromDevice
+	originalPTZConfigurations := heartbeatGetPTZConfigurationsFromDevice
+	originalPTZFunctions := heartbeatGetPTZFunctionsFromDevice
+	originalRelayOutputs := heartbeatGetRelayOutputs
+	originalUnsubscribe := heartbeatUnsubscribePullPoint
+
+	t.Cleanup(func() {
+		heartbeatConnectToONVIFDevice = originalConnect
+		heartbeatCreatePullPointSubscription = originalCreate
+		heartbeatGetDigitalInputs = originalDigitalInputs
+		heartbeatGetEventMessages = originalEvents
+		heartbeatGetPresetsFromDevice = originalPresets
+		heartbeatGetPTZConfigurationsFromDevice = originalPTZConfigurations
+		heartbeatGetPTZFunctionsFromDevice = originalPTZFunctions
+		heartbeatGetRelayOutputs = originalRelayOutputs
+		heartbeatUnsubscribePullPoint = originalUnsubscribe
+	})
+}
+
+func mustJSONMarshal(t *testing.T, v interface{}) []byte {
+	t.Helper()
+
+	b, err := json.Marshal(v)
+	if err != nil {
+		t.Fatalf("json.Marshal() error = %v", err)
+	}
+	return b
+}
+
+func assertDefaultHeartbeatONVIFPayload(t *testing.T, payload heartbeatONVIFPayload) {
+	t.Helper()
+
+	defaultPayload := defaultHeartbeatONVIFPayload()
+	if payload.enabled != defaultPayload.enabled ||
+		payload.zoom != defaultPayload.zoom ||
+		payload.panTilt != defaultPayload.panTilt ||
+		payload.presets != defaultPayload.presets ||
+		string(payload.presetsList) != string(defaultPayload.presetsList) ||
+		string(payload.eventsList) != string(defaultPayload.eventsList) {
+		t.Fatalf("payload = %+v, want default payload", payload)
+	}
+}
+
+func newTestONVIFDevice() *goonvif.Device {
+	return &goonvif.Device{}
+}
+
+func countString(values []string, want string) int {
+	count := 0
+	for _, value := range values {
+		if value == want {
+			count++
+		}
+	}
+	return count
+}
+
+// Some devices accept the subscription but reject the pulls, or never publish
+// the initial I/O state. The relay outputs and digital inputs must then be
+// queried directly instead of reporting no I/O at all.
+func TestHeartbeatONVIFPayloadFallsBackToDirectIOWhenSubscriptionsReturnNoEvents(t *testing.T) {
+	restoreHeartbeatONVIFStubs(t)
+
+	device := newTestONVIFDevice()
+	camera := models.IPCamera{
+		ONVIFXAddr:    "http://camera/onvif",
+		ONVIFUsername: "operator",
+		ONVIFPassword: "secret",
+	}
+
+	state := newHeartbeatONVIFState()
+	state.cameraConfiguration = camera
+	state.cameraKey = heartbeatONVIFCameraKey(camera)
+	state.device = device
+	state.staticLoaded = true
+	state.staticPayload.enabled = "true"
+
+	heartbeatCreatePullPointSubscription = func(*goonvif.Device) (string, error) {
+		return "pull-point", nil
+	}
+	heartbeatGetEventMessages = func(*goonvif.Device, string) ([]agentonvif.ONVIFEvents, error) {
+		return nil, errors.New("pull rejected")
+	}
+	heartbeatUnsubscribePullPoint = func(*goonvif.Device, string) error {
+		return nil
+	}
+	var relayCalls, inputCalls int
+	heartbeatGetRelayOutputs = func(*goonvif.Device) (goonvifdevice.GetRelayOutputsResponse, error) {
+		relayCalls++
+		return goonvifdevice.GetRelayOutputsResponse{RelayOutputs: []goonvifxsd.RelayOutput{{DeviceEntity: goonvifxsd.DeviceEntity{Token: "relay0"}}}}, nil
+	}
+	heartbeatGetDigitalInputs = func(*goonvif.Device) (goonvifdevice.GetDigitalInputsResponse, error) {
+		inputCalls++
+		return goonvifdevice.GetDigitalInputsResponse{DigitalInputs: []goonvifxsd.DigitalInput{{Token: "di0"}}}, nil
+	}
+
+	payload := getHeartbeatONVIFPayload(camera, state)
+
+	if relayCalls != 1 || inputCalls != 1 {
+		t.Fatalf("direct I/O queries: relay=%d inputs=%d, want 1 each", relayCalls, inputCalls)
+	}
+	var events []agentonvif.ONVIFEvents
+	if err := json.Unmarshal(payload.eventsList, &events); err != nil {
+		t.Fatalf("payload.eventsList is not valid JSON: %v", err)
+	}
+	got := map[string]string{}
+	for _, event := range events {
+		got[event.Key] = event.Type
+	}
+	if got["relay0"] != "output" || got["di0"] != "input" || len(got) != 2 {
+		t.Fatalf("payload.eventsList = %s, want relay0 output and di0 input", payload.eventsList)
+	}
+}

machinery/src/cloud/custom_headers.go

@@ -0,0 +1,195 @@
+package cloud
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"sort"
+	"strings"
+)
+
+const (
+	customHeadersManifestHeader = "X-Kerberos-Storage-Custom-Headers"
+	maxCustomHeaders            = 32
+	maxCustomHeaderNameLength   = 128
+	maxCustomHeaderValueLength  = 4096
+)
+
+var disallowedCustomHeaders = map[string]struct{}{
+	"authorization":       {},
+	"connection":          {},
+	"content-length":      {},
+	"content-type":        {},
+	"cookie":              {},
+	"expect":              {},
+	"host":                {},
+	"keep-alive":          {},
+	"proxy-authorization": {},
+	"proxy-connection":    {},
+	"te":                  {},
+	"trailer":             {},
+	"trace-id":            {},
+	"transfer-encoding":   {},
+	"tus-resumable":       {},
+	"upgrade":             {},
+}
+
+func parseCustomVaultHeaders(value string) (map[string]string, error) {
+	if strings.TrimSpace(value) == "" {
+		return nil, nil
+	}
+
+	// Decode into pointers so JSON null values can be told apart from strings.
+	var rawHeaders map[string]*string
+	if err := json.Unmarshal([]byte(value), &rawHeaders); err != nil {
+		return nil, fmt.Errorf("custom Vault headers must be a JSON object of string values: %w", err)
+	}
+	if rawHeaders == nil {
+		return nil, errors.New("custom Vault headers must be a JSON object of string values")
+	}
+	if len(rawHeaders) > maxCustomHeaders {
+		return nil, fmt.Errorf("custom Vault headers exceed the limit of %d", maxCustomHeaders)
+	}
+	headers := make(map[string]string, len(rawHeaders))
+	seen := make(map[string]struct{}, len(rawHeaders))
+	for name, rawValue := range rawHeaders {
+		if rawValue == nil {
+			return nil, fmt.Errorf("custom Vault header %q must be a string, not null", name)
+		}
+		value := *rawValue
+		headers[name] = value
+		if err := validateCustomVaultHeader(name, value); err != nil {
+			return nil, err
+		}
+		lowerName := strings.ToLower(name)
+		if _, duplicate := seen[lowerName]; duplicate {
+			return nil, fmt.Errorf("custom Vault header %q is duplicated with different casing", name)
+		}
+		seen[lowerName] = struct{}{}
+	}
+	return headers, nil
+}
+
+func validateCustomVaultHeader(name, value string) error {
+	if name == "" || len(name) > maxCustomHeaderNameLength || !isHTTPToken(name) {
+		return fmt.Errorf("invalid custom Vault header name %q", name)
+	}
+	lowerName := strings.ToLower(name)
+	if strings.HasPrefix(lowerName, "x-kerberos-") {
+		return fmt.Errorf("custom Vault header %q uses the reserved X-Kerberos namespace", name)
+	}
+	if strings.HasPrefix(lowerName, "upload-") {
+		return fmt.Errorf("custom Vault header %q uses the reserved tus Upload namespace", name)
+	}
+	if _, disallowed := disallowedCustomHeaders[lowerName]; disallowed {
+		return fmt.Errorf("custom Vault header %q is reserved", name)
+	}
+	if len(value) > maxCustomHeaderValueLength {
+		return fmt.Errorf("custom Vault header %q exceeds the %d byte value limit", name, maxCustomHeaderValueLength)
+	}
+	for _, character := range value {
+		if character < 0x20 || character == 0x7f {
+			return fmt.Errorf("custom Vault header %q contains an invalid value", name)
+		}
+	}
+	return nil
+}
+
+func isHTTPToken(value string) bool {
+	if value == "" {
+		return false
+	}
+	for _, character := range value {
+		if (character >= 'a' && character <= 'z') ||
+			(character >= 'A' && character <= 'Z') ||
+			(character >= '0' && character <= '9') ||
+			strings.ContainsRune("!#$%&'*+-.^_`|~", character) {
+			continue
+		}
+		return false
+	}
+	return true
+}
+
+func setCustomVaultHeaders(headers http.Header, customHeaders map[string]string) error {
+	if len(customHeaders) == 0 {
+		return nil
+	}
+
+	names := make([]string, 0, len(customHeaders))
+	for name, value := range customHeaders {
+		if err := validateCustomVaultHeader(name, value); err != nil {
+			return err
+		}
+		names = append(names, name)
+		// Assign directly so the configured name is not canonicalised by Set.
+		headers[name] = []string{value}
+	}
+	sort.Strings(names)
+	manifest, err := json.Marshal(names)
+	if err != nil {
+		return err
+	}
+	headers.Set(customHeadersManifestHeader, base64.RawURLEncoding.EncodeToString(manifest))
+	return nil
+}
+
+const maxVaultRedirects = 10
+
+// stripVaultHeadersOnCrossHostRedirect removes Vault credentials and the
+// customer-supplied metadata (custom headers, their manifest and the tus
+// Upload-Metadata that embeds them) before following a redirect to another host.
+func stripVaultHeadersOnCrossHostRedirect(req *http.Request, via []*http.Request) error {
+	if len(via) >= maxVaultRedirects {
+		return fmt.Errorf("stopped after %d redirects", maxVaultRedirects)
+	}
+	if len(via) == 0 || req.URL.Host == via[0].URL.Host {
+		return nil
+	}
+
+	customNames := customVaultHeaderNamesFromManifest(req.Header)
+	for name := range req.Header {
+		canonicalName := http.CanonicalHeaderKey(name)
+		_, custom := customNames[strings.ToLower(name)]
+		if custom || strings.HasPrefix(canonicalName, "X-Kerberos-") || canonicalName == "Upload-Metadata" {
+			delete(req.Header, name)
+		}
+	}
+	return nil
+}
+
+func customVaultHeaderNamesFromManifest(headers http.Header) map[string]struct{} {
+	encoded := headers.Get(customHeadersManifestHeader)
+	if encoded == "" {
+		return nil
+	}
+	manifest, err := base64.RawURLEncoding.DecodeString(encoded)
+	if err != nil {
+		return nil
+	}
+	var names []string
+	if err := json.Unmarshal(manifest, &names); err != nil {
+		return nil
+	}
+	lowerNames := make(map[string]struct{}, len(names))
+	for _, name := range names {
+		lowerNames[strings.ToLower(name)] = struct{}{}
+	}
+	return lowerNames
+}
+
+func encodeCustomVaultHeaders(customHeaders map[string]string) (string, error) {
+	if len(customHeaders) == 0 {
+		return "", nil
+	}
+	encoded, err := json.Marshal(customHeaders)
+	if err != nil {
+		return "", err
+	}
+	if len(encoded) == 0 {
+		return "", errors.New("custom Vault headers could not be encoded")
+	}
+	return string(encoded), nil
+}

machinery/src/cloud/custom_headers_test.go

@@ -0,0 +1,100 @@
+package cloud
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"net/http"
+	"reflect"
+	"testing"
+)
+
+func TestCustomVaultHeadersAreValidatedAndAdded(t *testing.T) {
+	customHeaders, err := parseCustomVaultHeaders(`{"site_id":"site-1","line_id":"line-2"}`)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	headers := http.Header{}
+	if err := setCustomVaultHeaders(headers, customHeaders); err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(headers["site_id"], []string{"site-1"}) || !reflect.DeepEqual(headers["line_id"], []string{"line-2"}) {
+		t.Fatalf("custom header names were not preserved: %#v", headers)
+	}
+	if _, canonicalised := headers["Site_id"]; canonicalised {
+		t.Fatalf("custom header name was canonicalised: %#v", headers)
+	}
+
+	encodedManifest, err := base64.RawURLEncoding.DecodeString(headers.Get(customHeadersManifestHeader))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var names []string
+	if err := json.Unmarshal(encodedManifest, &names); err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(names, []string{"line_id", "site_id"}) {
+		t.Fatalf("manifest = %#v", names)
+	}
+}
+
+func TestCustomVaultHeadersRejectReservedAndInvalidValues(t *testing.T) {
+	for _, value := range []string{
+		`{"X-Kerberos-Storage-AccessKey":"secret"}`,
+		`{"Authorization":"secret"}`,
+		`{"site_id":"one\nInjected: value"}`,
+		`{"bad header":"value"}`,
+		`{"site_id":1}`,
+		`{"Content-Type":"text/plain"}`,
+		`{"site_id":"one","SITE_ID":"two"}`,
+		`{"site_id":null}`,
+		`{"site_id":"one\ttwo"}`,
+		`{"Upload-Checksum":"sha1 abc"}`,
+		`{"upload-concat":"final;/files/a"}`,
+		`{"Upload-Defer-Length":"1"}`,
+		`null`,
+	} {
+		if _, err := parseCustomVaultHeaders(value); err == nil {
+			t.Fatalf("parseCustomVaultHeaders(%q) succeeded", value)
+		}
+	}
+}
+
+func TestVaultRedirectStripsCustomHeadersOnHostChange(t *testing.T) {
+	newRedirect := func(t *testing.T, host string) (*http.Request, []*http.Request) {
+		t.Helper()
+		original, err := http.NewRequest(http.MethodPost, "https://vault.example.com/api/storage", nil)
+		if err != nil {
+			t.Fatal(err)
+		}
+		redirected, err := http.NewRequest(http.MethodPost, "https://"+host+"/api/storage", nil)
+		if err != nil {
+			t.Fatal(err)
+		}
+		redirected.Header.Set("X-Kerberos-Storage-AccessKey", "secret")
+		redirected.Header.Set("Upload-Metadata", "custom_headers abc")
+		redirected.Header.Set("Tus-Resumable", "1.0.0")
+		if err := setCustomVaultHeaders(redirected.Header, map[string]string{"site_id": "site-1", "Line-Id": "line-2"}); err != nil {
+			t.Fatal(err)
+		}
+		return redirected, []*http.Request{original}
+	}
+
+	crossHost, via := newRedirect(t, "other.example.com")
+	if err := stripVaultHeadersOnCrossHostRedirect(crossHost, via); err != nil {
+		t.Fatal(err)
+	}
+	if len(crossHost.Header) != 1 || crossHost.Header.Get("Tus-Resumable") != "1.0.0" {
+		t.Fatalf("cross-host redirect headers = %#v", crossHost.Header)
+	}
+
+	sameHost, via := newRedirect(t, "vault.example.com")
+	if err := stripVaultHeadersOnCrossHostRedirect(sameHost, via); err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(sameHost.Header["site_id"], []string{"site-1"}) ||
+		sameHost.Header.Get("X-Kerberos-Storage-AccessKey") != "secret" ||
+		sameHost.Header.Get(customHeadersManifestHeader) == "" {
+		t.Fatalf("same-host redirect headers = %#v", sameHost.Header)
+	}
+}

machinery/src/cloud/dropbox.go

@@ -5,14 +5,14 @@ package cloud
 import (
 	"bytes"
 	"errors"
-	"os"
 
 	"github.com/dropbox/dropbox-sdk-go-unofficial/v6/dropbox"
 	"github.com/dropbox/dropbox-sdk-go-unofficial/v6/dropbox/files"
 	"github.com/dropbox/dropbox-sdk-go-unofficial/v6/dropbox/users"
 	"github.com/gin-gonic/gin"
-	"github.com/kerberos-io/agent/machinery/src/log"
 	"github.com/kerberos-io/agent/machinery/src/models"
+	"github.com/kerberos-io/agent/machinery/src/utils"
+	log "github.com/sirupsen/logrus"
 )
 
 // UploadDropbox uploads the file to your Dropbox account using the access token and directory.
@@ -30,23 +30,25 @@ func UploadDropbox(configuration *models.Configuration, fileName string) (bool,
 
 	if token == "" {
 		err := "UploadDropbox: Dropbox not properly configured"
-		log.Log.Info(err)
+		log.Info(err)
 		return false, true, errors.New(err)
 	}
 
 	// Upload to Dropbox
-	log.Log.Info("UploadDropbox: Uploading to Dropbox")
-	log.Log.Info("UploadDropbox: Upload started for " + fileName)
-	fullname := "data/recordings/" + fileName
-
+	log.Info("UploadDropbox: Uploading to Dropbox")
+	log.Info("UploadDropbox: Upload started for " + fileName)
 	dConfig := dropbox.Config{
 		Token:    token,
 		LogLevel: dropbox.LogInfo, // if needed, set the desired logging level. Default is off
 	}
 
-	file, err := os.OpenFile(fullname, os.O_RDWR, 0755)
+	file, err := utils.OpenRecording("data/recordings", fileName)
 	if file != nil {
-		defer file.Close()
+		defer func() {
+			if cerr := file.Close(); cerr != nil {
+				log.Error("UploadDropbox: Error closing file: " + cerr.Error())
+			}
+		}()
 	}
 
 	if err == nil {
@@ -64,15 +66,15 @@ func UploadDropbox(configuration *models.Configuration, fileName string) (bool,
 		}, file)
 
 		if err != nil {
-			log.Log.Error("UploadDropbox: Error uploading file: " + err.Error())
+			log.Error("UploadDropbox: Error uploading file: " + err.Error())
 			return false, false, err
 		}
 
-		log.Log.Info("UploadDropbox: File uploaded successfully, " + res.Name)
+		log.Info("UploadDropbox: File uploaded successfully, " + res.Name)
 		return true, true, nil
 	}
 
-	log.Log.Error("UploadDropbox: Error opening file: " + err.Error())
+	log.Error("UploadDropbox: Error opening file: " + err.Error())
 	return false, true, err
 }
 

machinery/src/cloud/kerberos_hub.go

@@ -0,0 +1,218 @@
+package cloud
+
+import (
+	"crypto/tls"
+	"errors"
+	"fmt"
+	"io/ioutil"
+	"net/http"
+	"os"
+
+	"github.com/kerberos-io/agent/machinery/src/models"
+	"github.com/kerberos-io/agent/machinery/src/utils"
+	log "github.com/sirupsen/logrus"
+)
+
+func UploadKerberosHub(configuration *models.Configuration, fileName string) (bool, bool, error) {
+	config := configuration.Config
+
+	if config.HubURI == "" ||
+		config.HubKey == "" ||
+		config.HubPrivateKey == "" ||
+		config.S3.Region == "" {
+		err := "UploadKerberosHub: Kerberos Hub not properly configured."
+		log.Info(err)
+		return false, false, errors.New(err)
+	}
+
+	// timestamp_microseconds_instanceName_regionCoordinates_numberOfChanges_token
+	// 1564859471_6-474162_oprit_577-283-727-375_1153_27.mp4
+	// - Timestamp
+	// - Size + - + microseconds
+	// - device
+	// - Region
+	// - Number of changes
+	// - Token
+
+	log.WithFields(log.Fields{
+		"component": "kerberos_hub",
+		"event":     "upload_started",
+	}).Info("Uploading recording to Kerberos Hub")
+
+	// Prefer the resumable (tus) upload when enabled (the default). Kerberos Hub
+	// authenticates the agent with its Hub public/private key and proxies the
+	// resumable upload to the Kerberos Vault. When Hub does not expose a tus
+	// endpoint (older deployments) we transparently fall back to the legacy
+	// single-POST upload below.
+	if resumableUploadsEnabled() {
+		uploaded, _, supported, body, rerr := uploadHubResumable(&config, fileName, "UploadKerberosHub", "hub")
+		if supported {
+			if uploaded {
+				log.WithFields(log.Fields{
+					"component":      "kerberos_hub",
+					"event":          "upload_completed",
+					"response_bytes": len(body),
+					"transport":      "tus",
+				}).Info("Hub upload completed")
+				return true, true, nil
+			}
+			if rerr != nil {
+				log.WithError(rerr).WithFields(log.Fields{
+					"component": "kerberos_hub",
+					"event":     "upload_failed",
+					"transport": "tus",
+				}).Error("Hub upload failed")
+			} else {
+				log.WithFields(log.Fields{
+					"component":      "kerberos_hub",
+					"event":          "upload_incomplete",
+					"response_bytes": len(body),
+					"transport":      "tus",
+				}).Warn("Hub upload incomplete")
+			}
+			return false, true, rerr
+		}
+		log.WithFields(log.Fields{
+			"component": "kerberos_hub",
+			"event":     "upload_transport_fallback",
+			"transport": "http",
+		}).Info("Resumable Hub upload unavailable; using legacy upload")
+	}
+
+	// Check if we still have the file otherwise we abort the request.
+	file, err := utils.OpenRecording("data/recordings", fileName)
+	if file != nil {
+		defer file.Close()
+	}
+	if err != nil {
+		err := "UploadKerberosHub: Upload Failed, file doesn't exists anymore."
+		log.Info(err)
+		return false, false, errors.New(err)
+	}
+
+	// Check if we are allowed to upload to the hub with these credentials.
+	// There might be different reasons like (muted, read-only..)
+	req, err := http.NewRequest("HEAD", config.HubURI+"/storage/upload", nil)
+	if err != nil {
+		log.WithError(err).WithFields(log.Fields{
+			"component": "kerberos_hub",
+			"event":     "authorization_request_creation_failed",
+		}).Error("Failed to create Hub upload authorization request")
+		return false, true, fmt.Errorf("create Hub upload authorization request: %w", err)
+	}
+
+	req.Header.Set("X-Kerberos-Storage-FileName", fileName)
+	req.Header.Set("X-Kerberos-Storage-Capture", "IPCamera")
+	req.Header.Set("X-Kerberos-Storage-Device", config.Key)
+	req.Header.Set("X-Kerberos-Hub-PublicKey", config.HubKey)
+	req.Header.Set("X-Kerberos-Hub-PrivateKey", config.HubPrivateKey)
+	req.Header.Set("X-Kerberos-Hub-Region", config.S3.Region)
+	setQueuedRecordingMetadataHeaders(req.Header, fileName)
+
+	var client *http.Client
+	if os.Getenv("AGENT_TLS_INSECURE") == "true" {
+		tr := &http.Transport{
+			TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
+		}
+		client = &http.Client{Transport: tr, CheckRedirect: stripHubCredentialsOnCrossHostRedirect}
+	} else {
+		client = &http.Client{CheckRedirect: stripHubCredentialsOnCrossHostRedirect}
+	}
+
+	resp, err := client.Do(req)
+	if resp != nil {
+		defer resp.Body.Close()
+	}
+
+	if err == nil && resp != nil {
+		if resp.StatusCode == 200 {
+			log.WithFields(log.Fields{
+				"component":   "kerberos_hub",
+				"event":       "upload_authorized",
+				"status_code": resp.StatusCode,
+			}).Debug("Hub upload authorized")
+		} else {
+			log.WithFields(log.Fields{
+				"component":   "kerberos_hub",
+				"event":       "upload_rejected",
+				"status_code": resp.StatusCode,
+			}).Warn("Hub upload rejected")
+			return false, true, nil
+		}
+	}
+
+	// Now we know we are allowed to upload to the hub, we can start uploading.
+	req, err = http.NewRequest("POST", config.HubURI+"/storage/upload", file)
+	if err != nil {
+		log.WithError(err).WithFields(log.Fields{
+			"component": "kerberos_hub",
+			"event":     "upload_request_creation_failed",
+		}).Error("Failed to create Hub upload request")
+		return false, true, fmt.Errorf("create Hub upload request: %w", err)
+	}
+	req.Header.Set("Content-Type", "video/mp4")
+	req.Header.Set("X-Kerberos-Storage-FileName", fileName)
+	req.Header.Set("X-Kerberos-Storage-Capture", "IPCamera")
+	req.Header.Set("X-Kerberos-Storage-Device", config.Key)
+	req.Header.Set("X-Kerberos-Hub-PublicKey", config.HubKey)
+	req.Header.Set("X-Kerberos-Hub-PrivateKey", config.HubPrivateKey)
+	req.Header.Set("X-Kerberos-Hub-Region", config.S3.Region)
+	setQueuedRecordingMetadataHeaders(req.Header, fileName)
+	resp, err = client.Do(req)
+	if resp != nil {
+		defer resp.Body.Close()
+	}
+
+	if err == nil {
+		if resp != nil {
+			body, err := ioutil.ReadAll(resp.Body)
+			if err == nil {
+				if resp.StatusCode == 200 {
+					log.WithFields(log.Fields{
+						"component":   "kerberos_hub",
+						"event":       "upload_completed",
+						"status_code": resp.StatusCode,
+						"transport":   "http",
+					}).Info("Hub upload completed")
+					return true, true, nil
+				} else {
+					log.WithFields(log.Fields{
+						"component":      "kerberos_hub",
+						"event":          "upload_rejected",
+						"response_bytes": len(body),
+						"status_code":    resp.StatusCode,
+						"transport":      "http",
+					}).Warn("Hub upload rejected")
+					return false, true, nil
+				}
+			}
+		}
+	}
+
+	if err == nil {
+		err = errors.New("Hub upload failed without a response")
+	}
+	log.WithError(err).WithFields(log.Fields{
+		"component": "kerberos_hub",
+		"event":     "upload_failed",
+		"transport": "http",
+	}).Error("Hub upload failed")
+	return false, true, fmt.Errorf("Hub upload failed: %w", err)
+}
+
+// stripHubCredentialsOnCrossHostRedirect removes the custom Kerberos Hub
+// credential headers on a redirect that crosses to a different host. net/http
+// already strips the standard sensitive headers (Authorization, Cookie,
+// WWW-Authenticate) on a cross-host redirect, but it does NOT strip
+// custom-named headers, so without this the Hub private/public keys would be
+// forwarded to any host the configured HubURI redirects to.
+func stripHubCredentialsOnCrossHostRedirect(req *http.Request, via []*http.Request) error {
+	if len(via) == 0 {
+		return nil
+	}
+	if req.URL.Host != via[0].URL.Host {
+		req.Header.Del("X-Kerberos-Hub-PrivateKey")
+		req.Header.Del("X-Kerberos-Hub-PublicKey")
+	}
+	return nil
+}

machinery/src/cloud/kerberos_vault.go

@@ -0,0 +1,316 @@
+package cloud
+
+import (
+	"crypto/tls"
+	"errors"
+	"io"
+	"net/http"
+	"os"
+	"strconv"
+	"time"
+
+	"github.com/kerberos-io/agent/machinery/src/models"
+	"github.com/kerberos-io/agent/machinery/src/utils"
+	log "github.com/sirupsen/logrus"
+)
+
+// We will count the number of retries we have done.
+// If we have done more than "kstorageRetryPolicy" retries, we will stop, and start sending to the secondary storage.
+var kstorageRetryCount = 0
+var kstorageRetryTimeout = time.Now().Unix()
+
+func UploadKerberosVault(configuration *models.Configuration, fileName string) (bool, bool, error) {
+
+	config := configuration.Config
+
+	if config.KStorage.AccessKey == "" ||
+		config.KStorage.SecretAccessKey == "" ||
+		config.KStorage.Directory == "" ||
+		config.KStorage.URI == "" {
+		err := "UploadKerberosVault: Kerberos Vault not properly configured"
+		log.Info(err)
+		return false, false, errors.New(err)
+	}
+
+	// If the recording no longer exists on disk there is nothing to upload.
+	// This can happen when the file was already removed (e.g. cleanup, or an
+	// earlier successful upload). Skip it so the watcher drops the marker
+	// instead of retrying indefinitely.
+	filePath, err := utils.ResolveRecordingPath("data/recordings", fileName)
+	if err != nil {
+		if os.IsNotExist(err) {
+			log.Info("UploadKerberosVault: skipping " + fileName + ", file doesn't exist anymore")
+			return false, false, nil
+		}
+		log.WithError(err).Error("UploadKerberosVault: could not resolve recording path")
+		return false, true, err
+	}
+	info, err := os.Stat(filePath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			log.Info("UploadKerberosVault: skipping " + fileName + ", file doesn't exist anymore")
+			return false, false, nil
+		}
+		log.WithError(err).Error("UploadKerberosVault: could not stat recording")
+		return false, true, err
+	}
+	if info.Size() == 0 {
+		log.Warn("UploadKerberosVault: skipping " + fileName + ", recording is empty")
+		return false, false, nil
+	}
+
+	// timestamp_microseconds_instanceName_regionCoordinates_numberOfChanges_token
+	// 1564859471_6-474162_oprit_577-283-727-375_1153_27.mp4
+	// - Timestamp
+	// - Size + - + microseconds
+	// - device
+	// - Region
+	// - Number of changes
+	// - Token
+	// KerberosCloud, this means storage is disabled and proxy enabled.
+	log.WithFields(log.Fields{
+		"component": "kerberos_vault",
+		"event":     "upload_started",
+		"storage":   "primary",
+	}).Info("Vault upload started")
+
+	publicKey := config.KStorage.CloudKey
+	if config.HubKey != "" {
+		publicKey = config.HubKey
+	}
+
+	// We need to check if we are in a retry timeout.
+	if kstorageRetryTimeout <= time.Now().Unix() {
+		uploaded, responded, body, err := sendToVault(*config.KStorage, publicKey, config.Key, fileName, "UploadKerberosVault", "primary")
+		if uploaded {
+			kstorageRetryCount = 0
+			log.WithFields(log.Fields{
+				"component": "kerberos_vault",
+				"event":     "upload_completed",
+				"storage":   "primary",
+			}).Info("Vault upload completed")
+			return true, true, nil
+		}
+
+		if err != nil {
+			log.WithError(err).WithFields(log.Fields{
+				"component": "kerberos_vault",
+				"event":     "upload_failed",
+				"storage":   "primary",
+			}).Error("Vault upload failed")
+		} else {
+			log.WithFields(log.Fields{
+				"component":      "kerberos_vault",
+				"event":          "upload_rejected",
+				"response_bytes": len(body),
+				"storage":        "primary",
+			}).Warn("Vault upload rejected")
+		}
+
+		// We only advance the retry policy when the vault gave a definitive
+		// response (mirroring the original behaviour where transient network
+		// errors did not consume retries). When the retry count reaches the
+		// configured maximum we back off for the configured timeout.
+		if responded {
+			if kstorageRetryCount < config.KStorage.MaxRetries {
+				kstorageRetryCount = (kstorageRetryCount + 1)
+			}
+			if kstorageRetryCount == config.KStorage.MaxRetries {
+				kstorageRetryTimeout = time.Now().Add(time.Duration(config.KStorage.Timeout) * time.Second).Unix()
+			}
+		}
+	}
+
+	// We might need to check if we can upload to our secondary storage.
+	if config.KStorageSecondary.AccessKey == "" ||
+		config.KStorageSecondary.SecretAccessKey == "" ||
+		config.KStorageSecondary.Directory == "" ||
+		config.KStorageSecondary.URI == "" {
+		log.Info("UploadKerberosVault (Secondary): Secondary Kerberos Vault not properly configured.")
+	} else {
+
+		if kstorageRetryCount < config.KStorage.MaxRetries {
+			log.Info("UploadKerberosVault (Secondary): Do not upload to secondary storage, we are still in retry policy.")
+			return false, true, nil
+		}
+
+		log.WithFields(log.Fields{
+			"component": "kerberos_vault",
+			"event":     "upload_started",
+			"storage":   "secondary",
+		}).Info("Vault upload started")
+
+		uploaded, _, body, err := sendToVault(*config.KStorageSecondary, publicKey, config.Key, fileName, "UploadKerberosVault (Secondary)", "secondary")
+		if uploaded {
+			log.WithFields(log.Fields{
+				"component": "kerberos_vault",
+				"event":     "upload_completed",
+				"storage":   "secondary",
+			}).Info("Vault upload completed")
+			return true, true, nil
+		}
+
+		if err != nil {
+			log.WithError(err).WithFields(log.Fields{
+				"component": "kerberos_vault",
+				"event":     "upload_failed",
+				"storage":   "secondary",
+			}).Error("Vault upload failed")
+		} else {
+			log.WithFields(log.Fields{
+				"component":      "kerberos_vault",
+				"event":          "upload_rejected",
+				"response_bytes": len(body),
+				"storage":        "secondary",
+			}).Warn("Vault upload rejected")
+		}
+	}
+
+	return false, true, nil
+}
+
+// sendToVault uploads a single recording to one Kerberos Vault. When resumable
+// uploads are enabled (the default) it attempts the tus protocol first and, if
+// the vault does not expose a tus endpoint (older deployments), transparently
+// falls back to the legacy single-shot POST.
+//
+// It returns whether the upload succeeded, whether the vault gave a definitive
+// HTTP response (so the caller can advance its retry policy), a short message
+// for logging, and a transport error if any.
+func sendToVault(vault models.KStorage, publicKey, deviceKey, fileName, label, slot string) (bool, bool, string, error) {
+	if resumableUploadsEnabled() {
+		uploaded, responded, supported, body, err := uploadVaultResumable(vault, publicKey, deviceKey, fileName, label, slot)
+		if supported {
+			return uploaded, responded, body, err
+		}
+		log.Info(label + ": resumable (tus) endpoint not available, falling back to legacy upload")
+	}
+	return uploadVaultLegacy(vault, publicKey, deviceKey, fileName, label)
+}
+
+// uploadVaultLegacy performs the original single-request upload: the whole file
+// is sent as the body of a POST to {URI}/storage. Kept for backwards
+// compatibility with vault deployments that do not support resumable uploads.
+func uploadVaultLegacy(vault models.KStorage, publicKey, deviceKey, fileName, label string) (bool, bool, string, error) {
+	customHeaders, err := parseCustomVaultHeaders(vault.CustomHeaders)
+	if err != nil {
+		return false, false, "", err
+	}
+	file, err := utils.OpenRecording("data/recordings", fileName)
+	if file != nil {
+		defer file.Close()
+	}
+	if err != nil {
+		msg := label + ": Upload Failed, file doesn't exists anymore"
+		log.Info(msg)
+		return false, false, "", errors.New(msg)
+	}
+
+	uri := vault.URI
+	for len(uri) > 0 && uri[len(uri)-1] == '/' {
+		uri = uri[:len(uri)-1]
+	}
+
+	req, err := http.NewRequest("POST", uri+"/storage", file)
+	if err != nil {
+		errorMessage := label + ": error reading request, " + uri + "/storage: " + err.Error()
+		log.Error(errorMessage)
+		return false, false, "", errors.New(errorMessage)
+	}
+	req.Header.Set("Content-Type", "video/mp4")
+	setVaultHeaders(req.Header, vault, publicKey, deviceKey, fileName)
+	if err := setCustomVaultHeaders(req.Header, customHeaders); err != nil {
+		return false, false, "", err
+	}
+	setQueuedRecordingMetadataHeaders(req.Header, fileName)
+
+	client := newVaultHTTPClient(0)
+	resp, err := client.Do(req)
+	if resp != nil {
+		defer resp.Body.Close()
+	}
+	if err != nil {
+		return false, false, "", err
+	}
+
+	body, rerr := io.ReadAll(resp.Body)
+	if rerr != nil {
+		return false, false, "", rerr
+	}
+
+	if resp.StatusCode == 200 {
+		return true, true, resp.Status + ", " + string(body), nil
+	}
+	return false, true, resp.Status + ", " + string(body), nil
+}
+
+// setVaultHeaders sets the standard Kerberos Vault headers used by the legacy
+// single-POST upload.
+func setVaultHeaders(h http.Header, vault models.KStorage, publicKey, deviceKey, fileName string) {
+	h.Set("X-Kerberos-Storage-CloudKey", publicKey)
+	h.Set("X-Kerberos-Storage-AccessKey", vault.AccessKey)
+	h.Set("X-Kerberos-Storage-SecretAccessKey", vault.SecretAccessKey)
+	h.Set("X-Kerberos-Storage-Provider", vault.Provider)
+	h.Set("X-Kerberos-Storage-FileName", fileName)
+	h.Set("X-Kerberos-Storage-Device", deviceKey)
+	h.Set("X-Kerberos-Storage-Capture", "IPCamera")
+	h.Set("X-Kerberos-Storage-Directory", vault.Directory)
+}
+
+// newVaultHTTPClient builds an HTTP client honouring the AGENT_TLS_INSECURE
+// escape hatch. A timeout of 0 disables the *overall* client timeout, which is
+// required for streaming large upload bodies without capping the total transfer
+// time. Transport-level timeouts are still applied so that a lost network
+// connection (for example the internet being disconnected) fails reasonably
+// fast and the upload is retried, instead of the request hanging until the OS
+// TCP timeout (which can be many minutes) and blocking the whole upload loop.
+func newVaultHTTPClient(timeout time.Duration) *http.Client {
+	// Start from a clone of the default transport so we keep its sane dial and
+	// TLS-handshake timeouts, connection pooling and HTTP/2 support even when the
+	// AGENT_TLS_INSECURE escape hatch is enabled (a bare http.Transport would have
+	// no dial/handshake timeouts at all).
+	transport := http.DefaultTransport.(*http.Transport).Clone()
+
+	// ResponseHeaderTimeout bounds how long we wait for the vault's response
+	// headers *after* the request body has been fully written. It does not limit
+	// the time spent streaming the (potentially large) upload body, so big
+	// recordings still upload fine, but a vault/network that disappears while we
+	// wait for the acknowledgement is detected and the upload is retried instead
+	// of hanging indefinitely.
+	transport.ResponseHeaderTimeout = vaultResponseHeaderTimeout()
+
+	if os.Getenv("AGENT_TLS_INSECURE") == "true" {
+		if transport.TLSClientConfig == nil {
+			transport.TLSClientConfig = &tls.Config{}
+		}
+		transport.TLSClientConfig.InsecureSkipVerify = true
+	}
+
+	client := &http.Client{Transport: transport, CheckRedirect: stripVaultHeadersOnCrossHostRedirect}
+	if timeout > 0 {
+		client.Timeout = timeout
+	}
+	return client
+}
+
+// vaultResponseHeaderTimeout returns the maximum time to wait for a vault's
+// response headers after the request body has been written. It defaults to 5
+// minutes — generous enough for the vault to persist/finalize a chunk or a full
+// recording to its storage provider — and can be tuned with the
+// AGENT_VAULT_RESPONSE_HEADER_TIMEOUT_SECONDS environment variable. A value of 0
+// (or a negative/invalid value) disables the timeout.
+func vaultResponseHeaderTimeout() time.Duration {
+	const def = 5 * time.Minute
+	v := os.Getenv("AGENT_VAULT_RESPONSE_HEADER_TIMEOUT_SECONDS")
+	if v == "" {
+		return def
+	}
+	n, err := strconv.Atoi(v)
+	if err != nil {
+		return def
+	}
+	if n <= 0 {
+		return 0
+	}
+	return time.Duration(n) * time.Second
+}

machinery/src/cloud/livehls.go

@@ -0,0 +1,403 @@
+package cloud
+
+import (
+	"os"
+	"time"
+
+	mqtt "github.com/eclipse/paho.mqtt.golang"
+
+	"github.com/kerberos-io/agent/machinery/src/cloud/livehls"
+	"github.com/kerberos-io/agent/machinery/src/models"
+	"github.com/kerberos-io/agent/machinery/src/packets"
+	log "github.com/sirupsen/logrus"
+)
+
+// hlsViewerTimeoutSeconds is how long the agent keeps shipping live HLS segments
+// after the last viewer keepalive. It is a few seconds longer than the segment
+// duration so a viewer whose keepalive is briefly delayed does not cause the
+// session to flap. When it lapses the session is torn down to stop wasting
+// upload bandwidth when nobody is watching.
+const hlsViewerTimeoutSeconds = 8
+
+// hlsReadyReannounceSeconds throttles how often the agent re-announces an
+// already-ready session over MQTT in response to viewer keepalives. The initial
+// "receive-hls-ready" is a one-shot fired when the first segment lands; a viewer
+// that connects or hard-refreshes after that (while the session is still alive)
+// missed it, so we re-announce on subsequent keepalives. Viewers dedupe by
+// session id, so a re-announce for a session they already play is a no-op. ~2s
+// gets a refreshed viewer playing well within its connection timeout without
+// spamming the control plane.
+const hlsReadyReannounceSeconds = 2
+
+// HandleLiveStreamHLS drives the live HLS producer. It mirrors HandleLiveStreamSD:
+// it reads the camera's packet stream from a Latest() cursor, and while a viewer
+// is active (kept alive via communication.HandleLiveHLS) it muxes the packets
+// into CMAF segments and ships them to hub-api, which stores each segment in an
+// ephemeral, short-TTL live window and serves the rolling playlist to viewers.
+//
+// A session is created lazily on the first keyframe seen while a viewer is active
+// and torn down once viewers go away, so an idle camera produces no live traffic.
+//
+// By default (AGENT_LIVE_HLS_PREWARM unset or != "false") the agent instead keeps
+// one long-lived session muxing continuously into a small in-memory ring buffer
+// while idle (uploading nothing) and, the moment a viewer arrives, flushes the
+// already-encoded init + most-recent segment(s) and starts uploading live. This
+// trades a little idle CPU for a near-instant "requesting stream", so viewers no
+// longer wait a full GOP for the first segment to be cut. Set
+// AGENT_LIVE_HLS_PREWARM=false to fall back to the lazy on-demand path above.
+func HandleLiveStreamHLS(
+	configuration *models.Configuration,
+	communication *models.Communication,
+	mqttClient mqtt.Client,
+	subStreamEnabled bool,
+	mainQueue *packets.Queue,
+	subQueue *packets.Queue,
+) {
+
+	log.Debug("cloud.HandleLiveStreamHLS(): started")
+
+	config := configuration.Config
+
+	if config.Offline == "true" {
+		log.Debug("cloud.HandleLiveStreamHLS(): stopping as Offline is enabled.")
+		return
+	}
+	if config.Capture.Liveview == "false" {
+		log.Debug("cloud.HandleLiveStreamHLS(): stopping as Liveview is disabled.")
+		return
+	}
+	if config.HubURI == "" || config.HubKey == "" {
+		log.Debug("cloud.HandleLiveStreamHLS(): stopping as the Hub is not configured (HubURI/HubKey).")
+		return
+	}
+
+	hubKey := config.HubKey
+	deviceId := config.Key
+
+	region := ""
+	if config.S3 != nil {
+		region = config.S3.Region
+	}
+
+	publisher := livehls.NewPublisher(livehls.PublisherConfig{
+		HubURI:        config.HubURI,
+		HubKey:        config.HubKey,
+		HubPrivateKey: config.HubPrivateKey,
+		Region:        region,
+		DeviceKey:     deviceId,
+	})
+
+	// The live session can be served from the main (high-resolution) or sub
+	// (low-resolution) stream and switched on demand. requestedQuality tracks the
+	// latest tier asked for over the keepalive; source holds the cursor plus the
+	// encoded parameter sets/dimensions for the stream currently being muxed.
+	// Encoded dimensions are only needed for the avcC fallback path (an SPS that
+	// mp4ff's strict parser rejects).
+	requestedQuality := models.StreamQualityAuto
+	useSub := models.SelectSubStreamForQuality(config, requestedQuality, subStreamEnabled)
+	source := buildHLSSource(config, mainQueue, subQueue, useSub)
+	log.Info("cloud.HandleLiveStreamHLS(): serving live HLS from the " + source.label + " stream")
+
+	// prewarm keeps a single long-lived session muxing into an in-memory ring
+	// buffer while idle and flushes it the instant a viewer arrives, eliminating
+	// the per-request GOP wait. Enabled by default; set AGENT_LIVE_HLS_PREWARM=false
+	// to fall back to the lazy on-demand path.
+	prewarm := os.Getenv("AGENT_LIVE_HLS_PREWARM") != "false"
+	if prewarm {
+		log.Info("cloud.HandleLiveStreamHLS(): live HLS prewarm ENABLED (set AGENT_LIVE_HLS_PREWARM=false to disable)")
+	} else {
+		log.Info("cloud.HandleLiveStreamHLS(): live HLS prewarm DISABLED (AGENT_LIVE_HLS_PREWARM=false)")
+	}
+
+	// lowLatency enables LL-HLS: each segment is sliced into CMAF parts shipped the
+	// instant they close and advertised via #EXT-X-PART, taking glass-to-glass HLS
+	// latency from ~4-6s down to ~1-2s. Enabled by default; set
+	// AGENT_LIVE_HLS_LOW_LATENCY=false to fall back to whole-segment HLS.
+	partTargetMs := uint64(0)
+	if os.Getenv("AGENT_LIVE_HLS_LOW_LATENCY") != "false" {
+		partTargetMs = livehls.DefaultPartTargetMs
+		log.Info("cloud.HandleLiveStreamHLS(): live HLS low-latency (LL-HLS) ENABLED (set AGENT_LIVE_HLS_LOW_LATENCY=false to disable)")
+	} else {
+		log.Info("cloud.HandleLiveStreamHLS(): live HLS low-latency (LL-HLS) DISABLED (AGENT_LIVE_HLS_LOW_LATENCY=false)")
+	}
+
+	var session *livehls.Session
+	lastViewerRequest := int64(0)
+	lastReadyAnnounce := int64(0)
+
+	var cursorError error
+	var pkt packets.Packet
+
+	for cursorError == nil {
+		pkt, cursorError = source.cursor.ReadPacket()
+		if cursorError != nil {
+			break
+		}
+
+		now := time.Now().Unix()
+		select {
+		case q := <-communication.HandleLiveHLS:
+			lastViewerRequest = now
+			if q != "" {
+				requestedQuality = q
+			}
+			// A keepalive may come from a viewer that just connected or hard-
+			// refreshed and therefore missed the one-shot readiness announcement
+			// fired when this session's first segment landed. Re-announce (throttled)
+			// so late/refreshed viewers learn the active session id; the frontend
+			// dedupes by session id, so this is a no-op for viewers already playing.
+			// UploadsActive() is always true for the on-demand path; for prewarm it
+			// suppresses a stale re-announce while idle (the flush-on-arrival path
+			// below announces once the buffer has actually been shipped).
+			if session != nil && session.IsReady() && session.UploadsActive() && now-lastReadyAnnounce >= hlsReadyReannounceSeconds {
+				publishHLSReady(configuration, mqttClient, hubKey, deviceId, session.SessionID())
+				lastReadyAnnounce = now
+			}
+		default:
+		}
+
+		// Switch the source stream when the requested quality now maps to the other
+		// stream. Tearing the current session down makes the producer rebuild the
+		// init segment and announce a fresh session id from the new stream, which the
+		// viewer re-attaches to.
+		if wantSub := models.SelectSubStreamForQuality(config, requestedQuality, subStreamEnabled); wantSub != useSub {
+			useSub = wantSub
+			if session != nil {
+				_ = session.Close()
+				session = nil
+			}
+			source = buildHLSSource(config, mainQueue, subQueue, useSub)
+			lastReadyAnnounce = 0
+			log.Info("cloud.HandleLiveStreamHLS(): switched live HLS to the " + source.label + " stream (quality=" + requestedQuality + ")")
+			continue
+		}
+
+		viewerActive := now-lastViewerRequest <= hlsViewerTimeoutSeconds
+
+		if prewarm {
+			// Keep one long-lived session muxing into the ring buffer. Create it on
+			// the first keyframe (so the buffer opens on a random-access point) and
+			// never tear it down for idleness; uploads, not muxing, are what we gate
+			// on viewer presence.
+			if session == nil {
+				if len(pkt.Data) == 0 || !pkt.IsVideo || !pkt.IsKeyFrame {
+					continue
+				}
+				session = livehls.NewSession(publisher, livehls.SessionOptions{
+					Codec:          pkt.Codec,
+					SPSNALUs:       source.sps,
+					PPSNALUs:       source.pps,
+					VPSNALUs:       source.vps,
+					Width:          source.width,
+					Height:         source.height,
+					PartTargetMs:   partTargetMs,
+					StartBuffering: true,
+				})
+				session.SetOnReady(func(sessionID string) {
+					log.WithFields(log.Fields{
+						"component":  "cloud/livehls",
+						"event":      "session_ready",
+						"session_id": sessionID,
+					}).Info("Live HLS session ready")
+					publishHLSReady(configuration, mqttClient, hubKey, deviceId, sessionID)
+					lastReadyAnnounce = time.Now().Unix()
+				})
+				session.SetOnFailure(func(sessionID, reason string) {
+					publishHLSFailure(configuration, mqttClient, hubKey, deviceId, sessionID, reason)
+				})
+				log.WithFields(log.Fields{
+					"component":  "cloud/livehls",
+					"event":      "session_prewarming",
+					"session_id": session.SessionID(),
+				}).Info("Prewarming live HLS session")
+			}
+
+			if viewerActive {
+				// Activating flushes the cached init + buffered segment(s). onReady
+				// announces the first-ever readiness; on a later re-activation it has
+				// already fired, so announce here (throttled, so the first activation
+				// does not double up) once the buffer has actually been shipped.
+				if session.SetUploadsActive(true) && session.IsReady() && now-lastReadyAnnounce >= hlsReadyReannounceSeconds {
+					publishHLSReady(configuration, mqttClient, hubKey, deviceId, session.SessionID())
+					lastReadyAnnounce = now
+				}
+			} else {
+				// No viewer: keep muxing into the buffer but stop uploading.
+				session.SetUploadsActive(false)
+			}
+
+			if len(pkt.Data) > 0 && pkt.IsVideo {
+				if err := session.WritePacket(pkt); err != nil {
+					log.Error("cloud.HandleLiveStreamHLS(): " + err.Error())
+				}
+			}
+			continue
+		}
+
+		if !viewerActive {
+			// No viewer: stop and discard the session so we stop shipping segments.
+			if session != nil {
+				_ = session.Close()
+				log.WithFields(log.Fields{
+					"component":  "cloud/livehls",
+					"event":      "session_stopped",
+					"reason":     "no_active_viewers",
+					"session_id": session.SessionID(),
+				}).Info("Live HLS session stopped")
+				session = nil
+			}
+			continue
+		}
+
+		if len(pkt.Data) == 0 || !pkt.IsVideo {
+			continue
+		}
+
+		// Start a session lazily, but only on a keyframe so the first segment opens
+		// on a random-access point.
+		if session == nil {
+			if !pkt.IsKeyFrame {
+				continue
+			}
+			session = livehls.NewSession(publisher, livehls.SessionOptions{
+				Codec:        pkt.Codec,
+				SPSNALUs:     source.sps,
+				PPSNALUs:     source.pps,
+				VPSNALUs:     source.vps,
+				Width:        source.width,
+				Height:       source.height,
+				PartTargetMs: partTargetMs,
+			})
+			session.SetOnReady(func(sessionID string) {
+				log.WithFields(log.Fields{
+					"component":  "cloud/livehls",
+					"event":      "session_ready",
+					"session_id": sessionID,
+				}).Info("Live HLS session ready")
+				publishHLSReady(configuration, mqttClient, hubKey, deviceId, sessionID)
+				lastReadyAnnounce = time.Now().Unix()
+			})
+			session.SetOnFailure(func(sessionID, reason string) {
+				publishHLSFailure(configuration, mqttClient, hubKey, deviceId, sessionID, reason)
+			})
+			log.WithFields(log.Fields{
+				"component":  "cloud/livehls",
+				"event":      "session_started",
+				"session_id": session.SessionID(),
+			}).Info("Live HLS session started")
+		}
+
+		if err := session.WritePacket(pkt); err != nil {
+			log.Error("cloud.HandleLiveStreamHLS(): " + err.Error())
+		}
+	}
+
+	if session != nil {
+		_ = session.Close()
+	}
+	log.Debug("cloud.HandleLiveStreamHLS(): finished")
+}
+
+// publishHLSReady announces, over MQTT, that a live HLS session is available so
+// viewers can load the rolling playlist hub-api serves for {device}/{session}.
+func publishHLSReady(configuration *models.Configuration, mqttClient mqtt.Client, hubKey, deviceId, sessionID string) {
+	valueMap := map[string]interface{}{
+		"session": sessionID,
+		"device":  deviceId,
+	}
+	message := models.Message{
+		Payload: models.Payload{
+			Action:   "receive-hls-ready",
+			DeviceId: deviceId,
+			Value:    valueMap,
+		},
+	}
+	payload, err := models.PackageMQTTMessage(configuration, message)
+	if err == nil {
+		mqttClient.Publish("kerberos/hub/"+hubKey, 0, false, payload)
+		log.WithFields(log.Fields{
+			"component":  "cloud/livehls",
+			"event":      "session_announced",
+			"session_id": sessionID,
+		}).Info("Live HLS session announced")
+	} else {
+		log.WithError(err).WithFields(log.Fields{
+			"component":  "cloud/livehls",
+			"event":      "session_announcement_failed",
+			"session_id": sessionID,
+		}).Error("Failed to package live HLS session announcement")
+	}
+}
+
+func publishHLSFailure(configuration *models.Configuration, mqttClient mqtt.Client, hubKey, deviceId, sessionID, reason string) {
+	valueMap := map[string]interface{}{
+		"session": sessionID,
+		"device":  deviceId,
+		"reason":  reason,
+	}
+	message := models.Message{
+		Payload: models.Payload{
+			Action:   "receive-hls-error",
+			DeviceId: deviceId,
+			Value:    valueMap,
+		},
+	}
+	payload, err := models.PackageMQTTMessage(configuration, message)
+	if err == nil {
+		mqttClient.Publish("kerberos/hub/"+hubKey, 0, false, payload)
+		log.WithFields(log.Fields{
+			"component":  "cloud/livehls",
+			"event":      "session_failure_announced",
+			"reason":     reason,
+			"session_id": sessionID,
+		}).Warn("Live HLS session failure announced")
+	} else {
+		log.WithError(err).WithFields(log.Fields{
+			"component":  "cloud/livehls",
+			"event":      "session_failure_announcement_failed",
+			"session_id": sessionID,
+		}).Error("Failed to package live HLS session failure")
+	}
+}
+
+// hlsStreamSource bundles everything the live HLS producer needs to mux one of
+// the camera's streams: the packet cursor it reads from plus the encoded
+// parameter sets and dimensions used to build that stream's init segment.
+type hlsStreamSource struct {
+	cursor *packets.QueueCursor
+	sps    [][]byte
+	pps    [][]byte
+	vps    [][]byte
+	width  uint16
+	height uint16
+	label  string
+}
+
+// buildHLSSource resolves the packet cursor and encoded parameter sets/dimensions
+// for the selected stream. useSub picks the sub (low-resolution) stream when one
+// is available; otherwise the main (high-resolution) stream is used. A fresh
+// Latest() cursor is created so muxing resumes from the live edge of the chosen
+// stream after a switch.
+func buildHLSSource(config models.Config, mainQueue, subQueue *packets.Queue, useSub bool) hlsStreamSource {
+	cam := config.Capture.IPCamera
+	if useSub && subQueue != nil {
+		return hlsStreamSource{
+			cursor: subQueue.Latest(),
+			sps:    cam.SubSPSNALUs,
+			pps:    cam.SubPPSNALUs,
+			vps:    cam.SubVPSNALUs,
+			width:  uint16(cam.SubWidth),
+			height: uint16(cam.SubHeight),
+			label:  "sub",
+		}
+	}
+	return hlsStreamSource{
+		cursor: mainQueue.Latest(),
+		sps:    cam.SPSNALUs,
+		pps:    cam.PPSNALUs,
+		vps:    cam.VPSNALUs,
+		width:  uint16(cam.Width),
+		height: uint16(cam.Height),
+		label:  "main",
+	}
+}

machinery/src/cloud/livehls/publisher.go

@@ -0,0 +1,244 @@
+// Package livehls implements the agent-side producer for live HLS streaming.
+//
+// It complements the recording pipeline: where recordings are muxed into one
+// fragmented MP4 and uploaded resumably (TUS) when complete, live HLS ships a
+// continuous series of small, independently-decodable CMAF segments to hub-api
+// the instant each is produced, so a browser can play a near-live HLS stream
+// without WebRTC/TURN (outbound HTTPS only).
+//
+// The wire contract (agent -> hub-api) intentionally mirrors the existing
+// header-based storage convention (X-Kerberos-Storage-Device / -FileName, plus
+// the Hub public/private key auth headers). hub-api authenticates the agent and
+// stores each segment in an ephemeral, short-TTL live window keyed by
+// {device}/{session}, which it serves straight back to the browser. The live
+// window is deliberately kept out of the vault and the recordings collection;
+// durable archival/DVR is a separate, later concern.
+//
+// Unlike recordings, live segments are NOT uploaded resumably: a 1-2s segment
+// that fails to upload is stale by the time a retry would land, so the publisher
+// is fire-and-forget and drops on failure (logged) rather than blocking the live
+// pipeline behind a retry/handshake.
+package livehls
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/kerberos-io/agent/machinery/src/video"
+	log "github.com/sirupsen/logrus"
+)
+
+const (
+	// liveIngestPath is the hub-api endpoint that accepts a single live segment
+	// (or the init segment) and stores it in the ephemeral live window. hub-api
+	// distinguishes init vs media segment and the object name via the
+	// X-Kerberos-Live-* headers below, keeping a single route (mirrors the
+	// existing /storage/upload convention).
+	liveIngestPath = "/storage/live"
+
+	// Object names within a session. The init segment (ftyp+moov) is uploaded
+	// once per session; media segments are seg-<sequence>.m4s.
+	initObjectName = "init.mp4"
+
+	contentTypeInit    = "video/mp4"
+	contentTypeSegment = "video/iso.segment"
+
+	// Header names for the live ingest contract.
+	headerHubPublicKey  = "X-Kerberos-Hub-PublicKey"
+	headerHubPrivateKey = "X-Kerberos-Hub-PrivateKey"
+	headerHubRegion     = "X-Kerberos-Hub-Region"
+	headerStorageDevice = "X-Kerberos-Storage-Device"
+	headerLiveSession   = "X-Kerberos-Live-Session"
+	headerLiveName      = "X-Kerberos-Live-Name"
+	headerLiveSequence  = "X-Kerberos-Live-Sequence"
+	headerLiveDuration  = "X-Kerberos-Live-Duration"
+	// Low-latency (LL-HLS) part headers. A part belongs to media segment
+	// X-Kerberos-Live-Sequence and is the X-Kerberos-Live-Part-th chunk within it;
+	// X-Kerberos-Live-Part-Independent flags a part that starts on a keyframe.
+	headerLivePart            = "X-Kerberos-Live-Part"
+	headerLivePartIndependent = "X-Kerberos-Live-Part-Independent"
+
+	// defaultPublishTimeout bounds a single segment upload. A live segment that
+	// cannot be delivered within roughly its own duration is stale, so the upload
+	// is abandoned (dropped) rather than allowed to back up the pipeline.
+	defaultPublishTimeout = 4 * time.Second
+	maxErrorResponseBytes = 4 << 10
+)
+
+// PublisherConfig carries the hub endpoint and credentials needed to ship live
+// segments. It is populated from the agent's models.Config (HubURI/HubKey/...).
+type PublisherConfig struct {
+	HubURI        string // base hub-api URL, e.g. https://api.hub.example.com
+	HubKey        string // Hub public key (X-Kerberos-Hub-PublicKey)
+	HubPrivateKey string // Hub private key (X-Kerberos-Hub-PrivateKey)
+	Region        string // storage region (X-Kerberos-Hub-Region), may be empty
+	DeviceKey     string // device/camera key (X-Kerberos-Storage-Device)
+
+	// Timeout optionally overrides defaultPublishTimeout (used by tests).
+	Timeout time.Duration
+	// HTTPClient optionally injects a client (used by tests). When nil a
+	// redirect-credential-stripping client is created.
+	HTTPClient *http.Client
+}
+
+// Publisher ships init and media segments to hub-api over plain HTTP POST.
+//
+// It is safe for sequential use from a single live-stream goroutine. Methods are
+// fire-and-forget: they return an error for the caller to log, but the caller is
+// expected to continue (drop-on-fail) rather than retry.
+type Publisher struct {
+	cfg    PublisherConfig
+	client *http.Client
+}
+
+// NewPublisher builds a Publisher. The HTTP client strips the Hub credential
+// headers on a cross-host redirect (net/http does this for standard auth headers
+// but not custom-named ones), matching the recording upload client.
+func NewPublisher(cfg PublisherConfig) *Publisher {
+	client := cfg.HTTPClient
+	if client == nil {
+		timeout := cfg.Timeout
+		if timeout <= 0 {
+			timeout = defaultPublishTimeout
+		}
+		client = &http.Client{
+			Timeout:       timeout,
+			CheckRedirect: stripHubCredentialsOnCrossHostRedirect,
+		}
+	}
+	return &Publisher{cfg: cfg, client: client}
+}
+
+// PublishInit uploads the session's init segment (ftyp+moov). It must be called
+// (and succeed) before the player can use any media segment, so the caller
+// should treat a failure here as "session not yet established" and retry on the
+// next init opportunity rather than shipping media segments blindly.
+func (p *Publisher) PublishInit(ctx context.Context, sessionID string, data []byte) error {
+	return p.post(ctx, postParams{
+		sessionID:   sessionID,
+		name:        initObjectName,
+		contentType: contentTypeInit,
+		body:        data,
+	})
+}
+
+// PublishSegment uploads one media segment (styp+moof+mdat). The segment's
+// sequence number and duration travel in headers so hub-api can update the
+// rolling playlist window without parsing the box structure.
+func (p *Publisher) PublishSegment(ctx context.Context, sessionID string, seg video.LiveSegment) error {
+	return p.post(ctx, postParams{
+		sessionID:   sessionID,
+		name:        fmt.Sprintf("seg-%d.m4s", seg.SequenceNumber),
+		sequence:    seg.SequenceNumber,
+		durationMs:  seg.DurationMs,
+		hasSegment:  true,
+		contentType: contentTypeSegment,
+		body:        seg.Data,
+	})
+}
+
+// PublishPart uploads one CMAF partial segment (LL-HLS). The part is named
+// seg-<segment>.<part>.m4s and carries its segment sequence, part index,
+// independence flag and duration in headers so hub-api can advertise it via
+// #EXT-X-PART and reconstruct the full segment by concatenating its parts.
+func (p *Publisher) PublishPart(ctx context.Context, sessionID string, part video.LivePart) error {
+	return p.post(ctx, postParams{
+		sessionID:   sessionID,
+		name:        fmt.Sprintf("seg-%d.%d.m4s", part.SegmentSeq, part.PartIndex),
+		sequence:    part.SegmentSeq,
+		durationMs:  part.DurationMs,
+		partIndex:   part.PartIndex,
+		independent: part.Independent,
+		hasPart:     true,
+		contentType: contentTypeSegment,
+		body:        part.Data,
+	})
+}
+
+type postParams struct {
+	sessionID   string
+	name        string
+	sequence    uint32
+	durationMs  uint64
+	hasSegment  bool
+	partIndex   uint32
+	independent bool
+	hasPart     bool
+	contentType string
+	body        []byte
+}
+
+// post performs a single fire-and-forget upload to the live ingest endpoint.
+func (p *Publisher) post(ctx context.Context, params postParams) error {
+	if p.cfg.HubURI == "" {
+		return fmt.Errorf("livehls: HubURI not configured")
+	}
+	if params.sessionID == "" {
+		return fmt.Errorf("livehls: empty session id")
+	}
+
+	url := strings.TrimRight(p.cfg.HubURI, "/") + liveIngestPath
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(params.body))
+	if err != nil {
+		return fmt.Errorf("livehls: build request: %w", err)
+	}
+
+	req.Header.Set("Content-Type", params.contentType)
+	req.Header.Set(headerStorageDevice, p.cfg.DeviceKey)
+	req.Header.Set(headerLiveSession, params.sessionID)
+	req.Header.Set(headerLiveName, params.name)
+	if params.hasSegment || params.hasPart {
+		req.Header.Set(headerLiveSequence, strconv.FormatUint(uint64(params.sequence), 10))
+		req.Header.Set(headerLiveDuration, strconv.FormatUint(params.durationMs, 10))
+	}
+	if params.hasPart {
+		req.Header.Set(headerLivePart, strconv.FormatUint(uint64(params.partIndex), 10))
+		independent := "0"
+		if params.independent {
+			independent = "1"
+		}
+		req.Header.Set(headerLivePartIndependent, independent)
+	}
+	req.Header.Set(headerHubPublicKey, p.cfg.HubKey)
+	req.Header.Set(headerHubPrivateKey, p.cfg.HubPrivateKey)
+	req.Header.Set(headerHubRegion, p.cfg.Region)
+
+	resp, err := p.client.Do(req)
+	if err != nil {
+		return fmt.Errorf("livehls: upload %s: %w", params.name, err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, maxErrorResponseBytes))
+		return fmt.Errorf("livehls: upload %s rejected with status %d (%d response bytes)", params.name, resp.StatusCode, len(body))
+	}
+	log.WithFields(log.Fields{
+		"component":  "cloud/livehls",
+		"event":      "object_uploaded",
+		"object":     params.name,
+		"session_id": params.sessionID,
+	}).Trace("Live HLS object uploaded")
+	return nil
+}
+
+// stripHubCredentialsOnCrossHostRedirect removes the Hub credential headers when
+// a redirect crosses to a different host. net/http strips standard sensitive
+// headers on a cross-host redirect but not custom-named ones, so without this the
+// Hub keys could leak to a redirect target.
+func stripHubCredentialsOnCrossHostRedirect(req *http.Request, via []*http.Request) error {
+	if len(via) == 0 {
+		return nil
+	}
+	if req.URL.Host != via[0].URL.Host {
+		req.Header.Del(headerHubPrivateKey)
+		req.Header.Del(headerHubPublicKey)
+	}
+	return nil
+}

machinery/src/cloud/livehls/publisher_test.go

@@ -0,0 +1,332 @@
+package livehls
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/kerberos-io/agent/machinery/src/packets"
+	"github.com/kerberos-io/agent/machinery/src/video"
+)
+
+// captured records one received upload for assertions.
+type captured struct {
+	path        string
+	method      string
+	contentType string
+	device      string
+	session     string
+	name        string
+	sequence    string
+	duration    string
+	hubPublic   string
+	hubPrivate  string
+	region      string
+	body        []byte
+}
+
+// newCapturingServer returns an httptest server that records every upload and
+// replies with the given status code.
+func newCapturingServer(t *testing.T, status int) (*httptest.Server, *[]captured, *sync.Mutex) {
+	t.Helper()
+	var mu sync.Mutex
+	var got []captured
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, _ := io.ReadAll(r.Body)
+		mu.Lock()
+		got = append(got, captured{
+			path:        r.URL.Path,
+			method:      r.Method,
+			contentType: r.Header.Get("Content-Type"),
+			device:      r.Header.Get(headerStorageDevice),
+			session:     r.Header.Get(headerLiveSession),
+			name:        r.Header.Get(headerLiveName),
+			sequence:    r.Header.Get(headerLiveSequence),
+			duration:    r.Header.Get(headerLiveDuration),
+			hubPublic:   r.Header.Get(headerHubPublicKey),
+			hubPrivate:  r.Header.Get(headerHubPrivateKey),
+			region:      r.Header.Get(headerHubRegion),
+			body:        body,
+		})
+		mu.Unlock()
+		w.WriteHeader(status)
+	}))
+	t.Cleanup(srv.Close)
+	return srv, &got, &mu
+}
+
+func testPublisher(hubURI string) *Publisher {
+	return NewPublisher(PublisherConfig{
+		HubURI:        hubURI,
+		HubKey:        "pub-key",
+		HubPrivateKey: "priv-key",
+		Region:        "eu-west",
+		DeviceKey:     "cam-1",
+		Timeout:       2 * time.Second,
+	})
+}
+
+func TestPublisherPublishInitSendsContractHeaders(t *testing.T) {
+	srv, got, mu := newCapturingServer(t, http.StatusOK)
+	p := testPublisher(srv.URL)
+
+	if err := p.PublishInit(context.Background(), "sess-1", []byte("INITBYTES")); err != nil {
+		t.Fatalf("PublishInit: %v", err)
+	}
+
+	mu.Lock()
+	defer mu.Unlock()
+	if len(*got) != 1 {
+		t.Fatalf("server received %d requests, want 1", len(*got))
+	}
+	c := (*got)[0]
+	if c.method != http.MethodPost {
+		t.Errorf("method=%s, want POST", c.method)
+	}
+	if c.path != liveIngestPath {
+		t.Errorf("path=%s, want %s", c.path, liveIngestPath)
+	}
+	if c.contentType != contentTypeInit {
+		t.Errorf("content-type=%s, want %s", c.contentType, contentTypeInit)
+	}
+	if c.device != "cam-1" {
+		t.Errorf("device=%s, want cam-1", c.device)
+	}
+	if c.session != "sess-1" {
+		t.Errorf("session=%s, want sess-1", c.session)
+	}
+	if c.name != initObjectName {
+		t.Errorf("name=%s, want %s", c.name, initObjectName)
+	}
+	if c.hubPublic != "pub-key" || c.hubPrivate != "priv-key" || c.region != "eu-west" {
+		t.Errorf("auth headers wrong: pub=%q priv=%q region=%q", c.hubPublic, c.hubPrivate, c.region)
+	}
+	if string(c.body) != "INITBYTES" {
+		t.Errorf("body=%q, want INITBYTES", string(c.body))
+	}
+	// init must NOT carry segment-only headers.
+	if c.sequence != "" || c.duration != "" {
+		t.Errorf("init should not send sequence/duration, got seq=%q dur=%q", c.sequence, c.duration)
+	}
+}
+
+func TestPublisherPublishSegmentSendsSequenceAndDuration(t *testing.T) {
+	srv, got, mu := newCapturingServer(t, http.StatusOK)
+	p := testPublisher(srv.URL)
+
+	seg := video.LiveSegment{SequenceNumber: 7, DurationMs: 1960, Data: []byte("SEGMENT")}
+	if err := p.PublishSegment(context.Background(), "sess-9", seg); err != nil {
+		t.Fatalf("PublishSegment: %v", err)
+	}
+
+	mu.Lock()
+	defer mu.Unlock()
+	c := (*got)[0]
+	if c.contentType != contentTypeSegment {
+		t.Errorf("content-type=%s, want %s", c.contentType, contentTypeSegment)
+	}
+	if c.name != "seg-7.m4s" {
+		t.Errorf("name=%s, want seg-7.m4s", c.name)
+	}
+	if c.sequence != "7" {
+		t.Errorf("sequence=%s, want 7", c.sequence)
+	}
+	if c.duration != "1960" {
+		t.Errorf("duration=%s, want 1960", c.duration)
+	}
+	if string(c.body) != "SEGMENT" {
+		t.Errorf("body=%q, want SEGMENT", string(c.body))
+	}
+}
+
+func TestPublisherReturnsErrorOnNon2xx(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusBadRequest)
+		_, _ = w.Write([]byte(`{"error":true,"data":"No user found with this public and private key."}`))
+	}))
+	t.Cleanup(srv.Close)
+	p := testPublisher(srv.URL)
+
+	err := p.PublishSegment(context.Background(), "s", video.LiveSegment{SequenceNumber: 1, Data: []byte("x")})
+	if err == nil {
+		t.Fatal("expected an error on 400 response")
+	}
+	if !strings.Contains(err.Error(), "status 400") || !strings.Contains(err.Error(), "71 response bytes") {
+		t.Fatalf("error = %q, want status code and response size", err)
+	}
+	if strings.Contains(err.Error(), "No user found with this public and private key") {
+		t.Fatalf("error exposed Hub response body: %q", err)
+	}
+}
+
+func TestPublisherErrorsWithoutHubURI(t *testing.T) {
+	p := NewPublisher(PublisherConfig{DeviceKey: "cam"})
+	if err := p.PublishInit(context.Background(), "s", []byte("x")); err == nil {
+		t.Fatal("expected error when HubURI is empty")
+	}
+}
+
+// makeAnnexBVideoPacket builds a synthetic capture packet carrying one Annex B
+// H.264 access unit at the given decode time (ms).
+func makeAnnexBVideoPacket(isKey bool, timeMs int64) packets.Packet {
+	nalType := byte(0x01)
+	if isKey {
+		nalType = 0x65
+	}
+	data := []byte{0x00, 0x00, 0x00, 0x01, nalType}
+	for i := 0; i < 80; i++ {
+		data = append(data, byte(i))
+	}
+	return packets.Packet{
+		IsVideo:    true,
+		IsKeyFrame: isKey,
+		Codec:      "H264",
+		Data:       data,
+		TimeLegacy: time.Duration(timeMs) * time.Millisecond,
+	}
+}
+
+func TestSessionShipsInitThenSegmentsAndFiresReady(t *testing.T) {
+	srv, got, mu := newCapturingServer(t, http.StatusOK)
+	p := testPublisher(srv.URL)
+
+	sess := NewSession(p, SessionOptions{
+		Codec:           "H264",
+		SPSNALUs:        [][]byte{liveTestSPSForSession()},
+		PPSNALUs:        [][]byte{{0x68, 0xce, 0x38, 0x80}},
+		Width:           640,
+		Height:          480,
+		TargetSegmentMs: 2000,
+	})
+
+	var readyCalls int
+	var readySession string
+	sess.SetOnReady(func(id string) {
+		readyCalls++
+		readySession = id
+	})
+
+	// 4 GOPs of 25 frames @ 40ms = 1s GOPs => with 2s target, 2 segments emitted
+	// during streaming and a final one on Close.
+	const gopFrames, gops = 25, 4
+	for i := 0; i < gopFrames*gops; i++ {
+		isKey := i%gopFrames == 0
+		pkt := makeAnnexBVideoPacket(isKey, int64(i*40))
+		if err := sess.WritePacket(pkt); err != nil {
+			t.Fatalf("WritePacket(%d): %v", i, err)
+		}
+	}
+	// A non-video packet must be ignored.
+	if err := sess.WritePacket(packets.Packet{IsAudio: true, Data: []byte{1, 2, 3}}); err != nil {
+		t.Fatalf("WritePacket(audio): %v", err)
+	}
+	if err := sess.Close(); err != nil {
+		t.Fatalf("Close: %v", err)
+	}
+
+	mu.Lock()
+	defer mu.Unlock()
+
+	var initCount, segCount int
+	for _, c := range *got {
+		if c.name == initObjectName {
+			initCount++
+			if string(c.body[4:8]) != "ftyp" {
+				t.Errorf("init body is not an ftyp box: % x", c.body[:12])
+			}
+		} else {
+			segCount++
+			if c.session != sess.SessionID() {
+				t.Errorf("segment session=%s, want %s", c.session, sess.SessionID())
+			}
+		}
+	}
+	if initCount != 1 {
+		t.Errorf("init uploaded %d times, want exactly 1", initCount)
+	}
+	if segCount < 2 {
+		t.Errorf("got %d segment uploads, want >= 2", segCount)
+	}
+	if readyCalls != 1 {
+		t.Errorf("OnReady fired %d times, want exactly 1", readyCalls)
+	}
+	if readySession != sess.SessionID() {
+		t.Errorf("OnReady session=%s, want %s", readySession, sess.SessionID())
+	}
+}
+
+func TestSessionRetriesInitWhenFirstAttemptFails(t *testing.T) {
+	// Server fails the first N requests, then succeeds. This proves init is
+	// re-attempted (not dropped) so the session can still establish.
+	var mu sync.Mutex
+	var inits, segs int
+	failFirst := 1
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		mu.Lock()
+		defer mu.Unlock()
+		name := r.Header.Get(headerLiveName)
+		if name == initObjectName {
+			inits++
+			if inits <= failFirst {
+				w.WriteHeader(http.StatusBadGateway)
+				return
+			}
+		} else {
+			segs++
+		}
+		w.WriteHeader(http.StatusOK)
+	}))
+	t.Cleanup(srv.Close)
+
+	sess := NewSession(testPublisher(srv.URL), SessionOptions{
+		Codec:    "H264",
+		SPSNALUs: [][]byte{liveTestSPSForSession()},
+		PPSNALUs: [][]byte{{0x68, 0xce, 0x38, 0x80}},
+		Width:    640,
+		Height:   480,
+	})
+
+	var ready int
+	var failures int
+	var failureReason string
+	sess.SetOnReady(func(string) { ready++ })
+	sess.SetOnFailure(func(_ string, reason string) {
+		failures++
+		failureReason = reason
+	})
+
+	for i := 0; i < 60; i++ {
+		isKey := i%25 == 0
+		if err := sess.WritePacket(makeAnnexBVideoPacket(isKey, int64(i*40))); err != nil {
+			t.Fatalf("WritePacket(%d): %v", i, err)
+		}
+	}
+	if err := sess.Close(); err != nil {
+		t.Fatalf("Close: %v", err)
+	}
+
+	mu.Lock()
+	defer mu.Unlock()
+	if inits < 2 {
+		t.Errorf("init attempted %d times, want >= 2 (first failed then retried)", inits)
+	}
+	if segs < 1 {
+		t.Errorf("no segments delivered after init recovered (segs=%d)", segs)
+	}
+	if ready != 1 {
+		t.Errorf("OnReady fired %d times, want 1", ready)
+	}
+	if failures != 1 || failureReason != "init-upload-failed" {
+		t.Errorf("OnFailure = %d/%q, want 1/init-upload-failed", failures, failureReason)
+	}
+}
+
+// liveTestSPSForSession is the known-good baseline SPS reused across tests.
+func liveTestSPSForSession() []byte {
+	return []byte{0x67, 0x42, 0xc0, 0x1e, 0xd9, 0x00, 0xa0, 0x47, 0xfe, 0xc8}
+}

machinery/src/cloud/livehls/session.go

@@ -0,0 +1,533 @@
+package livehls
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"fmt"
+	"sync"
+	"time"
+
+	"github.com/kerberos-io/agent/machinery/src/packets"
+	"github.com/kerberos-io/agent/machinery/src/video"
+	log "github.com/sirupsen/logrus"
+)
+
+// DefaultTargetSegmentMs is the nominal live segment length. ~2s keeps standard
+// HLS latency reasonable (a player typically buffers ~3 segments) while staying
+// large enough that per-segment HTTP overhead is negligible.
+const DefaultTargetSegmentMs = 2000
+
+// DefaultPartTargetMs is the nominal LL-HLS part length used when low latency is
+// enabled. ~300ms parts yield ~6-7 parts per 2s segment; with the playlist's
+// PART-HOLD-BACK at ~3x the part target this lands glass-to-glass latency around
+// 1-2s (versus ~4-6s for whole-segment HLS).
+const DefaultPartTargetMs = 300
+
+// Session ties a video.LiveSegmenter to a Publisher: it converts capture packets
+// into CMAF segments and ships each one to hub-api. Exactly one init segment is
+// delivered per session (re-attempted until it lands), after which media
+// segments are published and the OnReady signal fires once so the control plane
+// (MQTT) can tell viewers the live playlist exists.
+//
+// A Session is driven from a single goroutine (the live-stream loop); its methods
+// are not safe for concurrent use except SessionID, which is immutable.
+type Session struct {
+	id        string
+	publisher *Publisher
+	segmenter *video.LiveSegmenter
+
+	// newContext produces the per-upload context (timeout). Overridable in tests.
+	newContext func() (context.Context, context.CancelFunc)
+
+	mu            sync.Mutex
+	initBytes     []byte
+	initPublished bool
+	// lastInitAt is when the init segment was last (re)uploaded. The init is
+	// re-sent periodically so its short TTL in the hub live window never lapses
+	// mid-session; see refreshInitIfStale.
+	lastInitAt   time.Time
+	readyFired   bool
+	onReady      func(sessionID string)
+	failureFired bool
+	onFailure    func(sessionID, reason string)
+
+	// uploadsActive gates whether the init and completed segments are shipped to
+	// hub-api. It is true for the default on-demand path. The prewarm path starts
+	// it false so the session keeps muxing into bufferedSegments without producing
+	// any live traffic until a viewer actually arrives; see SetUploadsActive.
+	uploadsActive bool
+	// bufferedSegments is the in-memory ring buffer (the most recent
+	// prewarmMaxBufferedSegments segments) kept while uploadsActive is false, so a
+	// viewer that arrives can be served an already-encoded segment immediately
+	// instead of waiting a full GOP for the next one to be cut.
+	bufferedSegments []video.LiveSegment
+	// bufferedParts is the LL-HLS counterpart of bufferedSegments: while idle it
+	// retains the parts of the most recent (prewarmMaxBufferedSegments+1) segments,
+	// pruned a WHOLE segment at a time so a flushed segment is never partial.
+	bufferedParts []video.LivePart
+}
+
+// SessionOptions configures a live HLS session.
+type SessionOptions struct {
+	Codec           string   // "H264" or "H265"
+	SPSNALUs        [][]byte // parameter sets (raw or Annex B)
+	PPSNALUs        [][]byte //
+	VPSNALUs        [][]byte // H.265 only
+	Width           uint16   // encoded width (for the avcC fallback path)
+	Height          uint16   // encoded height
+	TargetSegmentMs uint64   // 0 => DefaultTargetSegmentMs
+	// PartTargetMs, when > 0, enables LL-HLS: each segment is additionally sliced
+	// into ~PartTargetMs CMAF parts that are published (and advertised via
+	// #EXT-X-PART) the instant they close, for ~1-2s glass-to-glass latency. 0
+	// keeps the classic whole-segment path.
+	PartTargetMs uint64
+	// StartBuffering starts the session in prewarm (buffer-only) mode: it muxes
+	// segments into an in-memory ring buffer but uploads nothing until
+	// SetUploadsActive(true) is called. Default false => uploads are live
+	// immediately (the on-demand path's behaviour).
+	StartBuffering bool
+}
+
+// NewSession builds a session with a fresh random id and wires the segmenter's
+// init/segment callbacks to the publisher.
+func NewSession(publisher *Publisher, opts SessionOptions) *Session {
+	target := opts.TargetSegmentMs
+	if target == 0 {
+		target = DefaultTargetSegmentMs
+	}
+	seg := video.NewLiveSegmenter(opts.Codec, opts.SPSNALUs, opts.PPSNALUs, opts.VPSNALUs, target)
+	seg.SetDimensions(opts.Width, opts.Height)
+	if opts.PartTargetMs > 0 {
+		seg.EnableLowLatency(opts.PartTargetMs)
+	}
+
+	s := &Session{
+		id:        newSessionID(),
+		publisher: publisher,
+		segmenter: seg,
+		// Uploads are live by default; the prewarm path opts into buffer-only mode.
+		uploadsActive: !opts.StartBuffering,
+		newContext: func() (context.Context, context.CancelFunc) {
+			return context.WithTimeout(context.Background(), defaultPublishTimeout)
+		},
+	}
+
+	// The segmenter emits the init segment exactly once; capture it and try to
+	// ship it. Failures here are non-fatal - publishInitIfNeeded re-attempts
+	// before the next media segment so a transient hub hiccup at startup does not
+	// permanently break the session.
+	seg.OnInit = func(initBytes []byte) error {
+		s.mu.Lock()
+		s.initBytes = append([]byte(nil), initBytes...)
+		active := s.uploadsActive
+		s.mu.Unlock()
+		// While prewarming we cache the init in memory but ship nothing; it is
+		// uploaded on the first SetUploadsActive(true) flush.
+		if active {
+			s.publishInitIfNeeded()
+		}
+		return nil
+	}
+
+	// Each completed media segment is shipped. We only publish a segment once the
+	// init segment has landed (a media segment is useless without it), and we fire
+	// OnReady after the first successfully shipped segment.
+	seg.OnSegment = func(segment video.LiveSegment) error {
+		s.mu.Lock()
+		active := s.uploadsActive
+		s.mu.Unlock()
+		if !active {
+			// Prewarm: retain the most recent segments in memory but upload nothing
+			// until a viewer arrives (SetUploadsActive flushes them).
+			s.bufferSegment(segment)
+			return nil
+		}
+		if !s.publishInitIfNeeded() {
+			log.WithFields(log.Fields{
+				"component":        "cloud/livehls",
+				"event":            "segment_dropped",
+				"reason":           "init_unavailable",
+				"segment_sequence": segment.SequenceNumber,
+				"session_id":       s.id,
+			}).Warn("Dropping live HLS segment")
+			return nil
+		}
+		ctx, cancel := s.newContext()
+		defer cancel()
+		if err := s.publisher.PublishSegment(ctx, s.id, segment); err != nil {
+			log.WithError(err).WithFields(log.Fields{
+				"component":        "cloud/livehls",
+				"event":            "segment_upload_failed",
+				"segment_sequence": segment.SequenceNumber,
+				"session_id":       s.id,
+			}).Warn("Failed to upload live HLS segment")
+			s.fireFailureOnce("segment-upload-failed")
+			return nil
+		}
+		s.fireReadyOnce()
+		// Keep the (write-once) init segment from ageing out of the live window
+		// while the session is still producing media.
+		s.refreshInitIfStale()
+		return nil
+	}
+
+	// In LL-HLS mode the segmenter emits parts (not whole segments); ship each one
+	// the instant it closes. Mirrors OnSegment: buffer while prewarming, otherwise
+	// publish after the init has landed and fire OnReady on the first part.
+	if opts.PartTargetMs > 0 {
+		seg.OnPart = func(part video.LivePart) error {
+			s.mu.Lock()
+			active := s.uploadsActive
+			s.mu.Unlock()
+			if !active {
+				s.bufferPart(part)
+				return nil
+			}
+			if !s.publishInitIfNeeded() {
+				log.WithFields(log.Fields{
+					"component":        "cloud/livehls",
+					"event":            "part_dropped",
+					"part_index":       part.PartIndex,
+					"reason":           "init_unavailable",
+					"segment_sequence": part.SegmentSeq,
+					"session_id":       s.id,
+				}).Warn("Dropping live HLS part")
+				return nil
+			}
+			ctx, cancel := s.newContext()
+			defer cancel()
+			if err := s.publisher.PublishPart(ctx, s.id, part); err != nil {
+				log.WithError(err).WithFields(log.Fields{
+					"component":        "cloud/livehls",
+					"event":            "part_upload_failed",
+					"part_index":       part.PartIndex,
+					"segment_sequence": part.SegmentSeq,
+					"session_id":       s.id,
+				}).Warn("Failed to upload live HLS part")
+				s.fireFailureOnce("part-upload-failed")
+				return nil
+			}
+			s.fireReadyOnce()
+			s.refreshInitIfStale()
+			return nil
+		}
+	}
+
+	return s
+}
+
+// SessionID returns the immutable session identifier used in object keys and the
+// MQTT ready signal.
+func (s *Session) SessionID() string { return s.id }
+
+// IsReady reports whether the session has delivered its init segment and at
+// least one media segment, i.e. the playlist hub-api serves is now playable. It
+// lets the live-stream loop re-announce "receive-hls-ready" to viewers that join
+// or hard-refresh after the initial one-shot signal (which they would otherwise
+// never receive, leaving the stream blank until the session is recreated).
+func (s *Session) IsReady() bool {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.readyFired
+}
+
+// SetOnReady registers a callback fired exactly once, after the first media
+// segment has been successfully delivered. Used to publish the MQTT
+// "receive-hls-ready" signal so viewers can load the playlist.
+func (s *Session) SetOnReady(fn func(sessionID string)) {
+	s.mu.Lock()
+	s.onReady = fn
+	s.mu.Unlock()
+}
+
+// SetOnFailure registers a one-shot callback for startup upload failures. The
+// reason is a fixed code rather than an HTTP response body, so credentials or
+// server details cannot leak through MQTT diagnostics.
+func (s *Session) SetOnFailure(fn func(sessionID, reason string)) {
+	s.mu.Lock()
+	s.onFailure = fn
+	s.mu.Unlock()
+}
+
+// prewarmMaxBufferedSegments is how many of the most recent completed segments
+// the prewarm path keeps in memory while idle and flushes to a viewer on arrival.
+// One segment keeps startup instant (the viewer immediately gets a playable
+// segment) while starting as close to the live edge as possible, so the HLS view
+// tracks the WebRTC/live edge instead of opening several seconds behind; hls.js
+// then converges to the edge via maxLiveSyncPlaybackRate. Raising it trades
+// latency-from-live for a little more startup cushion.
+const prewarmMaxBufferedSegments = 1
+
+// SetUploadsActive toggles whether the session ships its init and segments to
+// hub-api, and reports whether this call flipped it from inactive to active.
+//
+// While uploads are inactive the session keeps muxing capture packets into an
+// in-memory ring buffer (the cached init plus the most recent
+// prewarmMaxBufferedSegments segments) but uploads nothing, so an idle camera
+// produces no live traffic. Switching from inactive to active immediately
+// flushes the cached init and buffered segments so a viewer can start almost
+// instantly instead of waiting a full GOP for the next segment to be cut.
+// Switching from active to inactive resets the init-published flag so the next
+// activation re-uploads the init (it may have aged out of the hub's short-TTL
+// live window while idle). All other transitions are no-ops. Driven from the
+// live-stream goroutine; not safe for concurrent use.
+func (s *Session) SetUploadsActive(active bool) bool {
+	s.mu.Lock()
+	if s.uploadsActive == active {
+		s.mu.Unlock()
+		return false
+	}
+	s.uploadsActive = active
+	if !active {
+		// Going idle: force the next activation to re-deliver the init segment,
+		// which may have expired from the hub live window while nobody was watching.
+		s.initPublished = false
+		s.mu.Unlock()
+		return false
+	}
+	// Inactive -> active: take the cached buffered segments/parts and flush them
+	// outside the lock (the publish calls take their own time and re-acquire the
+	// mutex).
+	buffered := s.bufferedSegments
+	bufferedParts := s.bufferedParts
+	s.bufferedSegments = nil
+	s.bufferedParts = nil
+	s.mu.Unlock()
+
+	// Deliver the init first; media segments are useless without it.
+	for i := range buffered {
+		if !s.publishInitIfNeeded() {
+			break
+		}
+		ctx, cancel := s.newContext()
+		if err := s.publisher.PublishSegment(ctx, s.id, buffered[i]); err != nil {
+			log.WithError(err).WithFields(log.Fields{
+				"component":        "cloud/livehls",
+				"event":            "prewarm_segment_upload_failed",
+				"segment_sequence": buffered[i].SequenceNumber,
+				"session_id":       s.id,
+			}).Warn("Failed to upload buffered live HLS segment")
+			s.fireFailureOnce("segment-upload-failed")
+			cancel()
+			continue
+		}
+		cancel()
+		s.fireReadyOnce()
+		s.refreshInitIfStale()
+	}
+	// LL-HLS: flush the buffered parts in order (oldest first) so the viewer gets a
+	// playable, near-live window immediately.
+	for i := range bufferedParts {
+		if !s.publishInitIfNeeded() {
+			break
+		}
+		ctx, cancel := s.newContext()
+		if err := s.publisher.PublishPart(ctx, s.id, bufferedParts[i]); err != nil {
+			log.WithError(err).WithFields(log.Fields{
+				"component":        "cloud/livehls",
+				"event":            "prewarm_part_upload_failed",
+				"part_index":       bufferedParts[i].PartIndex,
+				"segment_sequence": bufferedParts[i].SegmentSeq,
+				"session_id":       s.id,
+			}).Warn("Failed to upload buffered live HLS part")
+			s.fireFailureOnce("part-upload-failed")
+			cancel()
+			continue
+		}
+		cancel()
+		s.fireReadyOnce()
+		s.refreshInitIfStale()
+	}
+	return true
+}
+
+// UploadsActive reports whether the session is currently shipping segments (as
+// opposed to buffering them while prewarming). Always true for the on-demand
+// path.
+func (s *Session) UploadsActive() bool {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.uploadsActive
+}
+
+// bufferSegment appends a completed segment to the in-memory prewarm ring buffer,
+// discarding the oldest so at most prewarmMaxBufferedSegments are retained.
+func (s *Session) bufferSegment(seg video.LiveSegment) {
+	s.mu.Lock()
+	s.bufferedSegments = append(s.bufferedSegments, seg)
+	if overflow := len(s.bufferedSegments) - prewarmMaxBufferedSegments; overflow > 0 {
+		// Drop the oldest segment(s) and shrink the backing array so retained bytes
+		// stay bounded.
+		s.bufferedSegments = append([]video.LiveSegment(nil), s.bufferedSegments[overflow:]...)
+	}
+	s.mu.Unlock()
+}
+
+// bufferPart appends a part to the LL-HLS prewarm ring buffer, pruning whole
+// older segments (never individual parts) so the retained window always consists
+// of complete segments plus the in-progress one. Pruning on a part-0 boundary
+// keeps at most prewarmMaxBufferedSegments fully-buffered segments behind the
+// current one, which guarantees a flushed segment can be reconstructed in full.
+func (s *Session) bufferPart(part video.LivePart) {
+	s.mu.Lock()
+	s.bufferedParts = append(s.bufferedParts, part)
+	if part.PartIndex == 0 && part.SegmentSeq > uint32(prewarmMaxBufferedSegments) {
+		minSeg := part.SegmentSeq - uint32(prewarmMaxBufferedSegments)
+		kept := make([]video.LivePart, 0, len(s.bufferedParts))
+		for _, p := range s.bufferedParts {
+			if p.SegmentSeq >= minSeg {
+				kept = append(kept, p)
+			}
+		}
+		s.bufferedParts = kept
+	}
+	s.mu.Unlock()
+}
+
+// WritePacket feeds one capture packet into the segmenter. Non-video packets are
+// ignored (the spike is video-only). The decode timestamp is derived exactly as
+// the recording muxer does: DTS = PTS - compositionOffset, with the composition
+// offset forwarded for correct B-frame presentation order.
+func (s *Session) WritePacket(pkt packets.Packet) error {
+	if !pkt.IsVideo {
+		return nil
+	}
+	pts := uint64(pkt.TimeLegacy.Milliseconds())
+	compositionOffset := pkt.CompositionTime
+	dts := pts
+	if compositionOffset > 0 && uint64(compositionOffset) <= pts {
+		dts = pts - uint64(compositionOffset)
+	} else if compositionOffset < 0 || uint64(compositionOffset) > pts {
+		// Guard against invalid offsets to avoid producing a CTS (DTS+CTO) jump.
+		compositionOffset = 0
+	}
+	return s.segmenter.WriteSample(pkt.IsKeyFrame, pkt.Data, dts, int32(compositionOffset))
+}
+
+// Close flushes any buffered sample and ships the final segment.
+func (s *Session) Close() error {
+	return s.segmenter.Close()
+}
+
+// publishInitIfNeeded ensures the init segment has been delivered, attempting an
+// upload if it has not. Returns true once init is known to be published.
+func (s *Session) publishInitIfNeeded() bool {
+	s.mu.Lock()
+	if s.initPublished {
+		s.mu.Unlock()
+		return true
+	}
+	initBytes := s.initBytes
+	s.mu.Unlock()
+
+	if len(initBytes) == 0 {
+		return false
+	}
+
+	ctx, cancel := s.newContext()
+	defer cancel()
+	if err := s.publisher.PublishInit(ctx, s.id, initBytes); err != nil {
+		log.WithError(err).WithFields(log.Fields{
+			"component":  "cloud/livehls",
+			"event":      "init_upload_failed",
+			"session_id": s.id,
+		}).Warn("Failed to upload live HLS init segment; retrying")
+		s.fireFailureOnce("init-upload-failed")
+		return false
+	}
+
+	s.mu.Lock()
+	s.initPublished = true
+	s.lastInitAt = time.Now()
+	s.mu.Unlock()
+	log.WithFields(log.Fields{
+		"component":  "cloud/livehls",
+		"event":      "init_uploaded",
+		"session_id": s.id,
+	}).Info("Live HLS init segment uploaded")
+	return true
+}
+
+// initRefreshInterval is how often the init segment is re-uploaded so its TTL in
+// the hub-api live window never lapses mid-session. The init segment is otherwise
+// written only once per session; because the live window expires objects after a
+// short TTL (LiveSegmentTTLSeconds, 45s on the hub) the init would age out after
+// ~1 minute and the playlist's #EXT-X-MAP would start 404ing, stalling playback.
+// Re-uploading well inside that TTL keeps the init alive for the life of the
+// session while still letting it expire naturally once the session ends.
+const initRefreshInterval = 15 * time.Second
+
+// refreshInitIfStale re-uploads the init segment if it has not been refreshed
+// within initRefreshInterval, keeping its created_at (and thus its TTL) current
+// for as long as the session is producing segments. It is a no-op until the init
+// has first been published. Failures are non-fatal: the next segment retries.
+func (s *Session) refreshInitIfStale() {
+	s.mu.Lock()
+	if !s.initPublished || time.Since(s.lastInitAt) < initRefreshInterval {
+		s.mu.Unlock()
+		return
+	}
+	initBytes := s.initBytes
+	s.mu.Unlock()
+
+	if len(initBytes) == 0 {
+		return
+	}
+
+	ctx, cancel := s.newContext()
+	defer cancel()
+	if err := s.publisher.PublishInit(ctx, s.id, initBytes); err != nil {
+		log.WithError(err).WithFields(log.Fields{
+			"component":  "cloud/livehls",
+			"event":      "init_refresh_failed",
+			"session_id": s.id,
+		}).Warn("Failed to refresh live HLS init segment; retrying")
+		return
+	}
+
+	s.mu.Lock()
+	s.lastInitAt = time.Now()
+	s.mu.Unlock()
+	log.WithFields(log.Fields{
+		"component":  "cloud/livehls",
+		"event":      "init_refreshed",
+		"session_id": s.id,
+	}).Debug("Live HLS init segment refreshed")
+}
+
+// fireReadyOnce invokes the OnReady callback the first time it is called.
+func (s *Session) fireReadyOnce() {
+	s.mu.Lock()
+	if s.readyFired || s.onReady == nil {
+		s.mu.Unlock()
+		return
+	}
+	s.readyFired = true
+	fn := s.onReady
+	s.mu.Unlock()
+	fn(s.id)
+}
+
+func (s *Session) fireFailureOnce(reason string) {
+	s.mu.Lock()
+	if s.failureFired || s.readyFired || s.onFailure == nil {
+		s.mu.Unlock()
+		return
+	}
+	s.failureFired = true
+	fn := s.onFailure
+	s.mu.Unlock()
+	fn(s.id, reason)
+}
+
+// newSessionID returns a short, unique, URL-safe session identifier of the form
+// <unix-seconds>-<random-hex>.
+func newSessionID() string {
+	b := make([]byte, 4)
+	if _, err := rand.Read(b); err != nil {
+		// rand.Read essentially never fails; fall back to a time-only id.
+		return fmt.Sprintf("%d", time.Now().UnixNano())
+	}
+	return fmt.Sprintf("%d-%s", time.Now().Unix(), hex.EncodeToString(b))
+}

machinery/src/cloud/livemoq/annexb.go

@@ -0,0 +1,103 @@
+package livemoq
+
+import (
+	"bytes"
+	"strings"
+
+	"github.com/bluenviron/mediacommon/pkg/codecs/h264"
+	"github.com/kerberos-io/agent/machinery/src/models"
+)
+
+var annexBStartCode = []byte{0x00, 0x00, 0x00, 0x01}
+
+// H264NormalizationStats reports malformed duplication removed from an access unit.
+type H264NormalizationStats struct {
+	DuplicateIDRNALUs int
+}
+
+// EnsureAnnexB restores the start code stripped by the Agent capture queue.
+func EnsureAnnexB(payload []byte) []byte {
+	if hasAnnexBStartCode(payload) {
+		return payload
+	}
+
+	framed := make([]byte, 0, len(annexBStartCode)+len(payload))
+	framed = append(framed, annexBStartCode...)
+	return append(framed, payload...)
+}
+
+// NormalizeH264AccessUnit removes delimiters and exact duplicate parameter-set
+// or IDR NALUs that can confuse older MoQ splitters and decoders.
+func NormalizeH264AccessUnit(payload []byte) ([]byte, error) {
+	normalized, _, err := NormalizeH264AccessUnitWithStats(payload)
+	return normalized, err
+}
+
+// NormalizeH264AccessUnitWithStats also reports exact duplicate IDR NALUs.
+func NormalizeH264AccessUnitWithStats(payload []byte) ([]byte, H264NormalizationStats, error) {
+	nalus, err := h264.AnnexBUnmarshal(EnsureAnnexB(payload))
+	if err != nil {
+		return nil, H264NormalizationStats{}, err
+	}
+
+	stats := H264NormalizationStats{}
+	normalized := make([][]byte, 0, len(nalus))
+	for _, nalu := range nalus {
+		if len(nalu) == 0 || nalu[0]&0x1f == 9 {
+			continue
+		}
+		naluType := nalu[0] & 0x1f
+		if naluType == 7 || naluType == 8 || naluType == 5 {
+			duplicate := false
+			for _, existing := range normalized {
+				if bytes.Equal(existing, nalu) {
+					duplicate = true
+					break
+				}
+			}
+			if duplicate {
+				if naluType == 5 {
+					stats.DuplicateIDRNALUs++
+				}
+				continue
+			}
+		}
+		normalized = append(normalized, nalu)
+	}
+
+	result, err := h264.AnnexBMarshal(normalized)
+	return result, stats, err
+}
+
+// BroadcastPath returns the relay path a quality tier is published on. Every
+// tier gets its own broadcast so a viewer switches between the camera's main and
+// sub stream by resubscribing to another path, without any control channel back
+// to the Agent. The high tier keeps the historical ".../live.hang" path so
+// existing viewers keep working; the low tier lives next to it on
+// ".../live-low.hang".
+func BroadcastPath(prefix string, deviceKey string, quality string) string {
+	prefix = strings.Trim(prefix, "/")
+	if prefix == "" {
+		prefix = "devices"
+	}
+	name := "live.hang"
+	if quality == models.StreamQualityLow {
+		name = "live-low.hang"
+	}
+	return prefix + "/" + strings.Trim(deviceKey, "/") + "/" + name
+}
+
+// TimestampUs converts the capture presentation timestamp from milliseconds.
+// CompositionTime must not be added: it is already represented in the PTS and
+// is only used by muxers to derive DTS for streams containing B-frames.
+func TimestampUs(presentationTimeMs int64) uint64 {
+	if presentationTimeMs < 0 {
+		return 0
+	}
+	return uint64(presentationTimeMs) * 1000
+}
+
+func hasAnnexBStartCode(payload []byte) bool {
+	return len(payload) >= 4 && payload[0] == 0 && payload[1] == 0 &&
+		((payload[2] == 0 && payload[3] == 1) || payload[2] == 1)
+}

machinery/src/cloud/livemoq/annexb_test.go

@@ -0,0 +1,116 @@
+package livemoq
+
+import (
+	"bytes"
+	"testing"
+
+	"github.com/kerberos-io/agent/machinery/src/models"
+)
+
+func TestEnsureAnnexB(t *testing.T) {
+	tests := []struct {
+		name    string
+		payload []byte
+		want    []byte
+	}{
+		{
+			name:    "missing start code",
+			payload: []byte{0x41, 0x01},
+			want:    []byte{0x00, 0x00, 0x00, 0x01, 0x41, 0x01},
+		},
+		{
+			name:    "four byte start code",
+			payload: []byte{0x00, 0x00, 0x00, 0x01, 0x65},
+			want:    []byte{0x00, 0x00, 0x00, 0x01, 0x65},
+		},
+		{
+			name:    "three byte start code",
+			payload: []byte{0x00, 0x00, 0x01, 0x41},
+			want:    []byte{0x00, 0x00, 0x01, 0x41},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if got := EnsureAnnexB(test.payload); !bytes.Equal(got, test.want) {
+				t.Fatalf("EnsureAnnexB() = %x, want %x", got, test.want)
+			}
+		})
+	}
+}
+
+func TestNormalizeH264AccessUnit(t *testing.T) {
+	startCode := []byte{0x00, 0x00, 0x00, 0x01}
+	sps := []byte{0x67, 0x42, 0x00, 0x1f}
+	pps := []byte{0x68, 0xce, 0x06, 0xe2}
+	aud := []byte{0x09, 0xf0}
+	idr := []byte{0x65, 0x88, 0x84}
+
+	payload := make([]byte, 0)
+	for _, nalu := range [][]byte{sps, pps, aud, sps, pps, idr} {
+		payload = append(payload, startCode...)
+		payload = append(payload, nalu...)
+	}
+
+	got, err := NormalizeH264AccessUnit(payload)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := make([]byte, 0)
+	for _, nalu := range [][]byte{sps, pps, idr} {
+		want = append(want, startCode...)
+		want = append(want, nalu...)
+	}
+	if !bytes.Equal(got, want) {
+		t.Fatalf("NormalizeH264AccessUnit() = %x, want %x", got, want)
+	}
+}
+
+func TestNormalizeH264AccessUnitRemovesOnlyExactDuplicateIDRSlices(t *testing.T) {
+	startCode := []byte{0x00, 0x00, 0x00, 0x01}
+	idrSlice1 := []byte{0x65, 0x88, 0x84}
+	idrSlice2 := []byte{0x65, 0x44, 0x22}
+
+	payload := make([]byte, 0)
+	for _, nalu := range [][]byte{idrSlice1, idrSlice1, idrSlice2} {
+		payload = append(payload, startCode...)
+		payload = append(payload, nalu...)
+	}
+
+	got, stats, err := NormalizeH264AccessUnitWithStats(payload)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := make([]byte, 0)
+	for _, nalu := range [][]byte{idrSlice1, idrSlice2} {
+		want = append(want, startCode...)
+		want = append(want, nalu...)
+	}
+	if !bytes.Equal(got, want) {
+		t.Fatalf("NormalizeH264AccessUnitWithStats() = %x, want %x", got, want)
+	}
+	if stats.DuplicateIDRNALUs != 1 {
+		t.Fatalf("DuplicateIDRNALUs = %d, want 1", stats.DuplicateIDRNALUs)
+	}
+}
+
+func TestBroadcastPath(t *testing.T) {
+	if got := BroadcastPath("/devices/", "/camera-1/", models.StreamQualityHigh); got != "devices/camera-1/live.hang" {
+		t.Fatalf("BroadcastPath() high = %q", got)
+	}
+	if got := BroadcastPath("", "camera-1", models.StreamQualityHigh); got != "devices/camera-1/live.hang" {
+		t.Fatalf("BroadcastPath() default = %q", got)
+	}
+	if got := BroadcastPath("", "camera-1", models.StreamQualityLow); got != "devices/camera-1/live-low.hang" {
+		t.Fatalf("BroadcastPath() low = %q", got)
+	}
+}
+
+func TestTimestampUs(t *testing.T) {
+	if got := TimestampUs(1234); got != 1_234_000 {
+		t.Fatalf("TimestampUs() = %d, want 1234000", got)
+	}
+	if got := TimestampUs(-1); got != 0 {
+		t.Fatalf("TimestampUs() negative = %d, want 0", got)
+	}
+}

machinery/src/cloud/livemoq/dedup.go

@@ -0,0 +1,41 @@
+package livemoq
+
+import (
+	"crypto/sha256"
+	"time"
+)
+
+type KeyframeDeduplicator struct {
+	hasPrevious  bool
+	timestampMs  int64
+	capturedAtMs int64
+	observedAt   time.Time
+	digest       [sha256.Size]byte
+}
+
+func (d *KeyframeDeduplicator) Reset() {
+	*d = KeyframeDeduplicator{}
+}
+
+// IsDuplicate reports exact repeated keyframe access units observed close
+// together. Distinct IDR slices within one access unit remain untouched.
+func (d *KeyframeDeduplicator) IsDuplicate(timestampMs int64, capturedAtMs int64, payload []byte, observedAt time.Time, window time.Duration) bool {
+	digest := sha256.Sum256(payload)
+	duplicate := d.hasPrevious && d.timestampMs == timestampMs && d.digest == digest
+	if duplicate {
+		if capturedAtMs > 0 && d.capturedAtMs > 0 {
+			gap := time.Duration(capturedAtMs-d.capturedAtMs) * time.Millisecond
+			duplicate = gap >= 0 && gap <= window
+		} else {
+			gap := observedAt.Sub(d.observedAt)
+			duplicate = gap >= 0 && gap <= window
+		}
+	}
+
+	d.hasPrevious = true
+	d.timestampMs = timestampMs
+	d.capturedAtMs = capturedAtMs
+	d.observedAt = observedAt
+	d.digest = digest
+	return duplicate
+}

machinery/src/cloud/livemoq/dedup_test.go

@@ -0,0 +1,60 @@
+package livemoq
+
+import (
+	"testing"
+	"time"
+)
+
+func TestKeyframeDeduplicator(t *testing.T) {
+	now := time.UnixMilli(10_000)
+	window := 500 * time.Millisecond
+	payload := []byte{0x00, 0x00, 0x00, 0x01, 0x65, 0x88}
+	deduplicator := KeyframeDeduplicator{}
+
+	if deduplicator.IsDuplicate(1_000, 10_000, payload, now, window) {
+		t.Fatal("first keyframe reported as duplicate")
+	}
+	if !deduplicator.IsDuplicate(1_000, 10_020, payload, now.Add(20*time.Millisecond), window) {
+		t.Fatal("exact repeated keyframe was not reported as duplicate")
+	}
+	if deduplicator.IsDuplicate(2_000, 11_000, payload, now.Add(time.Second), window) {
+		t.Fatal("same payload with a new timestamp reported as duplicate")
+	}
+	if deduplicator.IsDuplicate(2_000, 11_020, append(payload, 0x01), now.Add(1020*time.Millisecond), window) {
+		t.Fatal("different payload with the same timestamp reported as duplicate")
+	}
+}
+
+func TestKeyframeDeduplicatorAllowsTimestampReuseOutsideWindow(t *testing.T) {
+	now := time.UnixMilli(10_000)
+	payload := []byte{0x00, 0x00, 0x00, 0x01, 0x65, 0x88}
+	deduplicator := KeyframeDeduplicator{}
+
+	deduplicator.IsDuplicate(1_000, 10_000, payload, now, 500*time.Millisecond)
+	if deduplicator.IsDuplicate(1_000, 20_000, payload, now.Add(10*time.Second), 500*time.Millisecond) {
+		t.Fatal("later keyframe after timestamp reset reported as duplicate")
+	}
+}
+
+func TestKeyframeDeduplicatorFallsBackToObservationTime(t *testing.T) {
+	now := time.UnixMilli(10_000)
+	payload := []byte{0x65, 0x88}
+	deduplicator := KeyframeDeduplicator{}
+
+	deduplicator.IsDuplicate(1_000, 0, payload, now, 500*time.Millisecond)
+	if !deduplicator.IsDuplicate(1_000, 0, payload, now.Add(20*time.Millisecond), 500*time.Millisecond) {
+		t.Fatal("duplicate without capture time was not reported")
+	}
+}
+
+func TestKeyframeDeduplicatorReset(t *testing.T) {
+	now := time.UnixMilli(10_000)
+	payload := []byte{0x65, 0x88}
+	deduplicator := KeyframeDeduplicator{}
+
+	deduplicator.IsDuplicate(1_000, 10_000, payload, now, 500*time.Millisecond)
+	deduplicator.Reset()
+	if deduplicator.IsDuplicate(1_000, 10_020, payload, now.Add(20*time.Millisecond), 500*time.Millisecond) {
+		t.Fatal("first keyframe after reset reported as duplicate")
+	}
+}

machinery/src/cloud/livemoq/recovery.go

@@ -0,0 +1,101 @@
+package livemoq
+
+import (
+	"sync/atomic"
+	"time"
+)
+
+type FrameGateEvent uint8
+
+const (
+	FrameGateEventNone FrameGateEvent = iota
+	FrameGateEventStarted
+	FrameGateEventLagging
+	FrameGateEventRecovered
+)
+
+// FrameGate keeps publication on a decodable, recent GOP.
+type FrameGate struct {
+	started    bool
+	recovering bool
+}
+
+// AudienceGate publishes every frame while watched and only keyframes while
+// idle. The idle keyframes keep the relay's latest cached group current without
+// paying the bandwidth cost of a full stream when nobody is watching.
+type AudienceGate struct {
+	idle bool
+}
+
+func (g *AudienceGate) Allow(hasSubscribers bool, isKeyFrame bool) (allowed bool, enteredIdle bool) {
+	if hasSubscribers {
+		g.idle = false
+		return true, false
+	}
+
+	enteredIdle = !g.idle
+	g.idle = true
+	return isKeyFrame, enteredIdle
+}
+
+// WriteWatchdog tracks the single synchronous frame write performed by a MoQ
+// publisher so another goroutine can interrupt a wedged native call.
+type WriteWatchdog struct {
+	startedAt atomic.Int64
+}
+
+func (w *WriteWatchdog) Begin(now time.Time) {
+	w.startedAt.Store(now.UnixNano())
+}
+
+func (w *WriteWatchdog) End() {
+	w.startedAt.Store(0)
+}
+
+func (w *WriteWatchdog) Elapsed(now time.Time) (time.Duration, bool) {
+	startedAt := w.startedAt.Load()
+	if startedAt == 0 {
+		return 0, false
+	}
+	elapsed := now.Sub(time.Unix(0, startedAt))
+	if elapsed < 0 {
+		elapsed = 0
+	}
+	return elapsed, true
+}
+
+// Reset closes the gate so publication resumes on the next keyframe. Entering
+// idle mode uses it to start the relay-cache refresh on a complete GOP.
+func (g *FrameGate) Reset() {
+	g.started = false
+	g.recovering = false
+}
+
+// Allow rejects stale frames and waits for a fresh keyframe before reopening.
+func (g *FrameGate) Allow(isKeyFrame bool, capturedAtMs int64, now time.Time, maxAge time.Duration) (bool, FrameGateEvent) {
+	if capturedAtMs > 0 && now.Sub(time.UnixMilli(capturedAtMs)) > maxAge {
+		event := FrameGateEventNone
+		if g.started {
+			if !g.recovering {
+				event = FrameGateEventLagging
+			}
+			g.started = false
+			g.recovering = true
+		}
+		return false, event
+	}
+
+	if !g.started {
+		if !isKeyFrame {
+			return false, FrameGateEventNone
+		}
+		g.started = true
+		if g.recovering {
+			g.recovering = false
+			return true, FrameGateEventRecovered
+		}
+		return true, FrameGateEventStarted
+	}
+
+	return true, FrameGateEventNone
+}

machinery/src/cloud/livemoq/recovery_test.go

@@ -0,0 +1,91 @@
+package livemoq
+
+import (
+	"testing"
+	"time"
+)
+
+func TestFrameGateRecoversAtFreshKeyframe(t *testing.T) {
+	now := time.UnixMilli(10_000)
+	maxAge := 1500 * time.Millisecond
+	gate := FrameGate{}
+
+	tests := []struct {
+		name         string
+		isKeyFrame   bool
+		capturedAtMs int64
+		wantAllowed  bool
+		wantEvent    FrameGateEvent
+	}{
+		{name: "waits for initial keyframe", capturedAtMs: 10_000},
+		{name: "starts at initial keyframe", isKeyFrame: true, capturedAtMs: 10_000, wantAllowed: true, wantEvent: FrameGateEventStarted},
+		{name: "publishes fresh delta", capturedAtMs: 10_020, wantAllowed: true},
+		{name: "detects stale packet", capturedAtMs: 8_000, wantEvent: FrameGateEventLagging},
+		{name: "rejects fresh delta while recovering", capturedAtMs: 10_040},
+		{name: "rejects stale keyframe without duplicate event", isKeyFrame: true, capturedAtMs: 8_000},
+		{name: "recovers at fresh keyframe", isKeyFrame: true, capturedAtMs: 10_060, wantAllowed: true, wantEvent: FrameGateEventRecovered},
+		{name: "publishes delta after recovery", capturedAtMs: 10_080, wantAllowed: true},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			allowed, event := gate.Allow(test.isKeyFrame, test.capturedAtMs, now, maxAge)
+			if allowed != test.wantAllowed {
+				t.Fatalf("Allow() allowed = %t, want %t", allowed, test.wantAllowed)
+			}
+			if event != test.wantEvent {
+				t.Fatalf("Allow() event = %d, want %d", event, test.wantEvent)
+			}
+		})
+	}
+}
+
+func TestFrameGateAllowsMissingCaptureTime(t *testing.T) {
+	gate := FrameGate{}
+	allowed, event := gate.Allow(true, 0, time.Now(), time.Second)
+	if !allowed || event != FrameGateEventStarted {
+		t.Fatalf("Allow() = (%t, %d), want (true, %d)", allowed, event, FrameGateEventStarted)
+	}
+}
+
+func TestAudienceGateRefreshesOnlyKeyframesWhileIdle(t *testing.T) {
+	gate := AudienceGate{}
+
+	if allowed, enteredIdle := gate.Allow(true, false); !allowed || enteredIdle {
+		t.Fatalf("active delta = (%t, %t), want (true, false)", allowed, enteredIdle)
+	}
+	if allowed, enteredIdle := gate.Allow(false, false); allowed || !enteredIdle {
+		t.Fatalf("first idle delta = (%t, %t), want (false, true)", allowed, enteredIdle)
+	}
+	if allowed, enteredIdle := gate.Allow(false, true); !allowed || enteredIdle {
+		t.Fatalf("idle keyframe = (%t, %t), want (true, false)", allowed, enteredIdle)
+	}
+	if allowed, enteredIdle := gate.Allow(false, false); allowed || enteredIdle {
+		t.Fatalf("later idle delta = (%t, %t), want (false, false)", allowed, enteredIdle)
+	}
+	if allowed, enteredIdle := gate.Allow(true, false); !allowed || enteredIdle {
+		t.Fatalf("resumed delta = (%t, %t), want (true, false)", allowed, enteredIdle)
+	}
+	if allowed, enteredIdle := gate.Allow(false, true); !allowed || !enteredIdle {
+		t.Fatalf("next idle keyframe = (%t, %t), want (true, true)", allowed, enteredIdle)
+	}
+}
+
+func TestWriteWatchdogTracksActiveWrite(t *testing.T) {
+	now := time.Unix(10, 0)
+	watchdog := WriteWatchdog{}
+
+	if elapsed, active := watchdog.Elapsed(now); active || elapsed != 0 {
+		t.Fatalf("Elapsed() before Begin() = (%s, %t), want (0, false)", elapsed, active)
+	}
+
+	watchdog.Begin(now)
+	if elapsed, active := watchdog.Elapsed(now.Add(5 * time.Second)); !active || elapsed != 5*time.Second {
+		t.Fatalf("Elapsed() during write = (%s, %t), want (5s, true)", elapsed, active)
+	}
+
+	watchdog.End()
+	if elapsed, active := watchdog.Elapsed(now.Add(6 * time.Second)); active || elapsed != 0 {
+		t.Fatalf("Elapsed() after End() = (%s, %t), want (0, false)", elapsed, active)
+	}
+}

machinery/src/cloud/livemoq_disabled.go

@@ -0,0 +1,21 @@
+//go:build !moq
+
+package cloud
+
+import (
+	"context"
+
+	"github.com/kerberos-io/agent/machinery/src/models"
+	"github.com/kerberos-io/agent/machinery/src/packets"
+)
+
+// StartLiveStreamMoQ is disabled in the standard Agent build.
+func StartLiveStreamMoQ(
+	_ context.Context,
+	_ *models.Configuration,
+	_ *models.Communication,
+	_ bool,
+	_ *packets.Queue,
+	_ *packets.Queue,
+) {
+}