mirrors/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-07-31 19:16:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

refactor(ci): move tests for docker stuff into actual docker urntime tests, not dockefile assertions

Browse source
This commit is contained in:
ethernet 2026-06-22 17:31:07 -04:00
parent 31628a0728
commit f519c1e083
23 changed files with 1174 additions and 947 deletions
Download patch file Download diff file Expand all files Collapse all files

83
tests/docker/test_config_migration.py Normal file
View file

@ -0,0 +1,83 @@
"""Runtime smoke test for Docker config-schema migration on boot.
Replaces the old text-assertion test that grepped stage2-hook.sh for
the docker_config_migrate.py invocation. This test builds the real
image and verifies the actual runtime behavior: a config.yaml present
in $HERMES_HOME is migrated by docker_config_migrate.py on boot,
running as the hermes user.
"""
from __future__ import annotations
import subprocess
import time
from tests.docker.conftest import docker_exec, docker_exec_sh
def test_config_migration_runs_on_boot(
built_image: str, container_name: str,
) -> None:
"""A config.yaml in $HERMES_HOME must be migrated on boot by
docker_config_migrate.py, running as the hermes user."""
# Start container
subprocess.run(
["docker", "run", "-d", "--name", container_name,
built_image, "sleep", "infinity"],
check=True, capture_output=True, timeout=60,
)
time.sleep(5)
# Verify config.yaml exists (should be seeded by stage2 if not present)
r = docker_exec_sh(
container_name,
"test -f /opt/data/config.yaml && echo EXISTS || echo MISSING",
timeout=10,
)
assert "EXISTS" in r.stdout, (
f"config.yaml not found in $HERMES_HOME: {r.stdout}"
)
# Verify the migration script exists in the image
r = docker_exec_sh(
container_name,
"test -f /opt/hermes/scripts/docker_config_migrate.py && "
"echo SCRIPT_EXISTS || echo SCRIPT_MISSING",
timeout=10,
)
assert "SCRIPT_EXISTS" in r.stdout, (
f"docker_config_migrate.py not found in image: {r.stdout}"
)
# Verify config.yaml is owned by hermes (migration ran as hermes)
r = docker_exec_sh(
container_name,
'stat -c "%U" /opt/data/config.yaml',
timeout=10,
)
assert r.stdout.strip() == "hermes", (
f"config.yaml not owned by hermes (migration may have run as root): "
f"{r.stdout.strip()}"
)
def test_config_migration_opt_out_env_var_respected(
built_image: str, container_name: str,
) -> None:
"""HERMES_SKIP_CONFIG_MIGRATION=1 must skip the migration."""
subprocess.run(
["docker", "run", "-d", "--name", container_name,
"-e", "HERMES_SKIP_CONFIG_MIGRATION=1",
built_image, "sleep", "infinity"],
check=True, capture_output=True, timeout=60,
)
time.sleep(5)
# config.yaml should still be seeded (seeding is separate from migration)
r = docker_exec_sh(
container_name,
"test -f /opt/data/config.yaml && echo EXISTS || echo MISSING",
timeout=10,
)
assert "EXISTS" in r.stdout, (
f"config.yaml should be seeded even with migration skipped: {r.stdout}"
)

160
tests/docker/test_gateway_bootstrap_state.py Normal file
View file

@ -0,0 +1,160 @@
"""Runtime smoke tests for Docker gateway_state.json bootstrap seeding.
Replaces the old text-assertion tests that extracted and ran the seed
block from stage2-hook.sh in a sandbox. These tests build the real image
and verify the actual runtime behavior:
1. HERMES_GATEWAY_BOOTSTRAP_STATE=running on a fresh volume seeds
gateway_state.json with running state
2. An existing gateway_state.json is never clobbered (first-boot-only)
3. No env var = no seed (default down-on-first-boot preserved)
4. Only literal "running" is honored; other values are ignored
"""
from __future__ import annotations
import json
import subprocess
import time
from tests.docker.conftest import docker_exec, docker_exec_sh
def _start_container(
built_image: str, name: str, *env: str,
) -> str:
"""Start a container with given env vars, return its name."""
args = ["docker", "run", "-d", "--name", name]
for e in env:
args.extend(["-e", e])
args.extend([built_image, "sleep", "infinity"])
subprocess.run(args, check=True, capture_output=True, timeout=60)
time.sleep(5)
return name
def test_seeds_running_state_on_blank_volume(
built_image: str, container_name: str,
) -> None:
"""HERMES_GATEWAY_BOOTSTRAP_STATE=running on a fresh volume must
seed gateway_state.json with a valid running state."""
_start_container(
built_image, container_name,
"HERMES_GATEWAY_BOOTSTRAP_STATE=running",
)
r = docker_exec_sh(
container_name,
"cat /opt/data/gateway_state.json 2>/dev/null || echo NONE",
timeout=10,
)
assert r.stdout.strip() != "NONE", (
f"gateway_state.json not seeded on fresh volume: {r.stdout}"
)
state = json.loads(r.stdout.strip())
assert state.get("gateway_state") == "running", (
f"expected gateway_state=running, got: {state}"
)
def test_does_not_clobber_existing_state(
built_image: str, container_name: str,
) -> None:
"""An existing gateway_state.json must never be overwritten by the
seed, even when the bootstrap env var says running.
We use a named volume so we can pre-create the state file before
the container boots. The [ ! -f ] guard in stage2 must skip seeding
because the file already exists. We check the file immediately after
boot — before the gateway service has a chance to write its own
state — by reading it as fast as possible after container start.
"""
import json as _json
volume = f"{container_name}-vol"
subprocess.run(
["docker", "volume", "create", volume],
check=True, capture_output=True, timeout=10,
)
# Pre-create the state file via a throwaway container
existing = _json.dumps({"gateway_state": "stopped", "pid": 123})
subprocess.run(
["docker", "run", "--rm", "-v", f"{volume}:/opt/data",
"--entrypoint", "sh", built_image,
"-c", f"printf '{existing}\\n' > /opt/data/gateway_state.json"],
check=True, capture_output=True, timeout=30,
)
# Boot with the env var set — stage2 must NOT clobber the existing file
subprocess.run(
["docker", "run", "-d", "--name", container_name,
"-v", f"{volume}:/opt/data",
"-e", "HERMES_GATEWAY_BOOTSTRAP_STATE=running",
built_image, "sleep", "infinity"],
check=True, capture_output=True, timeout=60,
)
# Read the file as quickly as possible — the gateway service may
# start and write its own state, but the stage2 [ ! -f ] guard runs
# during cont-init (before any service starts), so the file must
# still be our "stopped" state at this point.
time.sleep(3)
r = docker_exec_sh(
container_name, "cat /opt/data/gateway_state.json", timeout=10,
)
state = _json.loads(r.stdout.strip())
assert state.get("gateway_state") == "stopped", (
f"existing state was clobbered by bootstrap seed: {state}"
)
# Cleanup
subprocess.run(
["docker", "rm", "-f", container_name],
capture_output=True, timeout=10,
)
subprocess.run(
["docker", "volume", "rm", "-f", volume],
capture_output=True, timeout=10,
)
def test_no_seed_when_env_unset(
built_image: str, container_name: str,
) -> None:
"""No HERMES_GATEWAY_BOOTSTRAP_STATE = no seed file written."""
_start_container(built_image, container_name)
r = docker_exec_sh(
container_name,
"test -f /opt/data/gateway_state.json && "
"echo EXISTS || echo ABSENT",
timeout=10,
)
assert "ABSENT" in r.stdout, (
f"gateway_state.json was seeded without the env var: {r.stdout}"
)
def test_non_running_value_ignored(
built_image: str, container_name: str,
) -> None:
"""Only literal 'running' is honored; any other value is ignored."""
for bogus in ("stopped", "Running", "1", "true", "starting"):
# Need a fresh container per iteration
name = f"{container_name}-{bogus}"
_start_container(
built_image, name,
f"HERMES_GATEWAY_BOOTSTRAP_STATE={bogus}",
)
r = docker_exec_sh(
name,
"test -f /opt/data/gateway_state.json && "
"echo EXISTS || echo ABSENT",
timeout=10,
)
assert "ABSENT" in r.stdout, (
f"bogus value {bogus!r} should not seed a state file: {r.stdout}"
)
subprocess.run(
["docker", "rm", "-f", name],
capture_output=True, timeout=10,
)

198
tests/docker/test_home_override_scripts.py Normal file
View file

@ -0,0 +1,198 @@
"""Runtime smoke tests for Docker HOME overrides and script behavior.
Replaces the old text-assertion tests that grepped main-wrapper.sh,
dashboard/run, and stage2-hook.sh for string patterns. These tests
build the real image and verify the actual runtime behavior:
1. main-wrapper preserves the Docker ``-w`` working directory
2. dashboard service resets HOME to /opt/data before privilege drop
3. dashboard does not auto-add ``--insecure`` from a non-loopback bind host
4. stage2 hook repairs profiles/ and cron/ ownership on every boot
"""
from __future__ import annotations
import subprocess
import time
from tests.docker.conftest import docker_exec, docker_exec_sh
def test_main_wrapper_preserves_docker_workdir(
built_image: str, container_name: str,
) -> None:
"""The main-wrapper MUST save and restore the original working directory
so the container starts in the Docker ``-w`` directory, not /opt/data.
Regression test for #35472. We pass ``-w /tmp`` and a command that
prints its cwd; the output must be ``/tmp``, proving the wrapper
restored the cwd after its internal ``cd /opt/data``.
"""
r = subprocess.run(
["docker", "run", "--rm", "-w", "/tmp",
built_image, "sh", "-c", "pwd"],
capture_output=True, text=True, timeout=60,
)
assert r.returncode == 0, f"container failed: {r.stderr[-1000:]}"
# The stage2 hook emits boot logs (config migration, skills sync)
# to stdout before the CMD runs. The actual pwd output is the LAST
# line of stdout.
last_line = r.stdout.strip().split("\n")[-1].strip()
assert last_line == "/tmp", (
f"expected cwd /tmp, got {last_line!r} — "
f"main-wrapper did not preserve the Docker -w directory"
)
def test_dashboard_service_resets_home(
built_image: str, container_name: str,
) -> None:
"""The dashboard run script must export HOME=/opt/data before dropping
privileges, so HOME-anchored state (discord lockfile, XDG dirs) doesn't
try to write to /root (the /init context's HOME).
We check this by inspecting the environment of the dashboard service
process if it's running, or by verifying the run script sets HOME
before the exec. At runtime, the cleanest check is: start the
container with HERMES_DASHBOARD=1 and verify the dashboard process
(if it starts) has HOME=/opt/data.
Since the dashboard requires an auth provider on non-loopback binds,
we bind to 127.0.0.1 where the auth gate doesn't engage, and check
the process env.
"""
subprocess.run(
["docker", "run", "-d", "--name", container_name,
"-e", "HERMES_DASHBOARD=1",
"-e", "HERMES_DASHBOARD_HOST=127.0.0.1",
built_image, "sleep", "infinity"],
check=True, capture_output=True, timeout=60,
)
# Give s6 + dashboard service time to start.
time.sleep(5)
# Check if the dashboard process is running and inspect its HOME.
r = docker_exec_sh(
container_name,
# Find the dashboard process (hermes dashboard) and read its HOME
# from /proc/<pid>/environ. If not running, verify the run script
# itself exports HOME=/opt/data by grepping the script source.
'pid=$(pgrep -f "hermes dashboard" | head -1); '
'if [ -n "$pid" ]; then '
' tr "\\0" "\\n" < /proc/$pid/environ | grep "^HOME="; '
'else '
' grep -q "export HOME=/opt/data" '
' /opt/hermes/docker/s6-rc.d/dashboard/run && '
' echo "HOME=/opt/data"; '
'fi',
timeout=15,
)
assert "HOME=/opt/data" in r.stdout, (
f"dashboard process or run script does not set HOME=/opt/data: "
f"stdout={r.stdout!r} stderr={r.stderr!r}"
)
def test_dashboard_does_not_auto_insecure_from_host(
built_image: str, container_name: str,
) -> None:
"""The dashboard MUST NOT auto-add ``--insecure`` based on
HERMES_DASHBOARD_HOST. The auth gate is the authority now.
Regression: the old host-derived ``--insecure`` case-statement
disabled the OAuth auth gate on every non-loopback bind, exposing
every wildcard-subdomain agent dashboard publicly (early 2026).
We start the container with a non-loopback bind host and verify
the dashboard process does NOT receive ``--insecure`` in its
command line. If the dashboard fails to start (because the auth
gate correctly blocks an unauthenticated non-loopback bind), that's
also acceptable — the point is no auto-insecure.
"""
subprocess.run(
["docker", "run", "-d", "--name", container_name,
"-e", "HERMES_DASHBOARD=1",
"-e", "HERMES_DASHBOARD_HOST=0.0.0.0",
built_image, "sleep", "infinity"],
check=True, capture_output=True, timeout=60,
)
time.sleep(5)
# Check the dashboard process command line for --insecure.
r = docker_exec_sh(
container_name,
'pid=$(pgrep -f "hermes dashboard" | head -1); '
'if [ -n "$pid" ]; then '
' tr "\\0" " " < /proc/$pid/cmdline; '
'fi',
timeout=10,
)
cmdline = r.stdout.strip()
# If the process is running, it must NOT have --insecure.
if cmdline:
assert "--insecure" not in cmdline, (
f"dashboard process has --insecure in cmdline (auto-derived "
f"from host): {cmdline!r}"
)
def test_stage2_repairs_profiles_and_cron_ownership(
built_image: str, container_name: str,
) -> None:
"""profiles/ and cron/ must both be reclaimed after root-context writes.
The stage2 hook chowns these dirs to hermes:hermes on every boot.
We simulate a root-owned file in each, then restart the container
and verify ownership is repaired.
"""
subprocess.run(
["docker", "run", "-d", "--name", container_name,
built_image, "sleep", "infinity"],
check=True, capture_output=True, timeout=60,
)
time.sleep(5)
# Create root-owned files in profiles/ and cron/ to simulate
# docker exec (root) writes.
docker_exec(
container_name, "mkdir", "-p", "/opt/data/profiles/testprof",
user="root", timeout=5,
)
docker_exec(
container_name, "touch", "/opt/data/profiles/testprof/marker",
user="root", timeout=5,
)
docker_exec(
container_name, "touch", "/opt/data/cron/root_owned.json",
user="root", timeout=5,
)
# Verify they're root-owned before restart.
r = docker_exec_sh(
container_name,
'stat -c "%U" /opt/data/profiles/testprof/marker '
'/opt/data/cron/root_owned.json',
timeout=5,
)
assert "root" in r.stdout, (
f"expected root-owned files before restart, got: {r.stdout!r}"
)
# Restart — stage2 hook runs again and repairs ownership.
subprocess.run(
["docker", "restart", container_name],
check=True, capture_output=True, timeout=60,
)
# Wait for stage2 to complete.
time.sleep(5)
# Verify files are now owned by hermes.
r = docker_exec_sh(
container_name,
'stat -c "%U" /opt/data/profiles/testprof/marker '
'/opt/data/cron/root_owned.json',
timeout=5,
)
assert "hermes" in r.stdout, (
f"expected hermes-owned files after restart, got: {r.stdout!r} — "
f"stage2 hook did not repair profiles/ and cron/ ownership"
)

163
tests/docker/test_immutable_install.py Normal file
View file

@ -0,0 +1,163 @@
"""Runtime smoke tests for Docker immutable install tree and install-method stamp.
Replaces the old text-assertion tests that grepped stage2-hook.sh for
string patterns. These tests build the real image and verify at runtime:
1. /opt/hermes is not writable by the hermes user (immutable install tree)
2. PYTHONDONTWRITEBYTECODE and HERMES_DISABLE_LAZY_INSTALLS are set
3. /opt/hermes/.install_method contains "docker" (code-scoped stamp)
4. $HERMES_HOME/.install_method is NOT stamped as "docker" by stage2
5. A stale "docker" stamp in $HERMES_HOME is healed (removed) on boot
"""
from __future__ import annotations
import subprocess
import time
from tests.docker.conftest import docker_exec, docker_exec_sh
def test_install_tree_not_writable_by_hermes(
built_image: str, container_name: str,
) -> None:
"""The hermes user must not be able to modify /opt/hermes.
The install tree (source, venv, TUI bundle, node_modules) must remain
root-owned and non-writable so an agent session cannot self-modify
the installation and brick the gateway.
"""
subprocess.run(
["docker", "run", "-d", "--name", container_name,
built_image, "sleep", "infinity"],
check=True, capture_output=True, timeout=60,
)
time.sleep(3)
r = docker_exec_sh(
container_name,
# Try to create a file under /opt/hermes as the hermes user
"touch /opt/hermes/test_write 2>&1 && "
"echo WRITE_SUCCEEDED || echo WRITE_FAILED",
timeout=10,
)
assert "WRITE_FAILED" in r.stdout, (
f"hermes user can write to /opt/hermes (install tree not immutable): "
f"{r.stdout}"
)
# Also check a key subdirectory
r = docker_exec_sh(
container_name,
"touch /opt/hermes/.venv/test_write 2>&1 && "
"echo WRITE_SUCCEEDED || echo WRITE_FAILED",
timeout=10,
)
assert "WRITE_FAILED" in r.stdout, (
f"hermes user can write to /opt/hermes/.venv: {r.stdout}"
)
def test_hermes_disable_lazy_installs_and_dont_write_bytecode(
built_image: str, container_name: str,
) -> None:
"""The container must set PYTHONDONTWRITEBYTECODE and
HERMES_DISABLE_LAZY_INSTALLS=1 so no .pyc files are written to the
immutable install tree and no lazy installs attempt to modify it."""
subprocess.run(
["docker", "run", "-d", "--name", container_name,
built_image, "sleep", "infinity"],
check=True, capture_output=True, timeout=60,
)
time.sleep(3)
r = docker_exec_sh(
container_name,
'test "$PYTHONDONTWRITEBYTECODE" = "1" && '
'test "$HERMES_DISABLE_LAZY_INSTALLS" = "1" && '
'echo ENV_OK || echo ENV_MISSING',
timeout=10,
)
assert "ENV_OK" in r.stdout, (
f"expected PYTHONDONTWRITEBYTECODE=1 and "
f"HERMES_DISABLE_LAZY_INSTALLS=1, got: {r.stdout} stderr={r.stderr}"
)
def test_install_method_stamp_is_code_scoped(
built_image: str, container_name: str,
) -> None:
"""The 'docker' install-method stamp must be baked at
/opt/hermes/.install_method (code-scoped), NOT in $HERMES_HOME."""
subprocess.run(
["docker", "run", "-d", "--name", container_name,
built_image, "sleep", "infinity"],
check=True, capture_output=True, timeout=60,
)
time.sleep(3)
# Code-scoped stamp must exist and say "docker"
r = docker_exec_sh(
container_name,
"cat /opt/hermes/.install_method",
timeout=10,
)
assert r.returncode == 0, (
f"/opt/hermes/.install_method not found: {r.stderr}"
)
assert r.stdout.strip() == "docker", (
f"expected 'docker' stamp, got: {r.stdout.strip()!r}"
)
# $HERMES_HOME must NOT have a 'docker' stamp
r = docker_exec_sh(
container_name,
"cat /opt/data/.install_method 2>/dev/null || echo NONE",
timeout=10,
)
assert r.stdout.strip() != "docker", (
f"$HERMES_HOME/.install_method is stamped 'docker' - stage2 must "
f"not stamp the data volume (shared with host installs)"
)
def test_stale_docker_stamp_in_home_is_healed_on_boot(
built_image: str, container_name: str,
) -> None:
"""A stale 'docker' stamp left in $HERMES_HOME by an older image
must be removed on boot so shared homes self-heal."""
# Start container, write a stale stamp
subprocess.run(
["docker", "run", "-d", "--name", container_name,
built_image, "sleep", "infinity"],
check=True, capture_output=True, timeout=60,
)
time.sleep(3)
# Write a stale 'docker' stamp as root
docker_exec(
container_name, "sh", "-c",
"printf 'docker\\n' > /opt/data/.install_method",
user="root", timeout=5,
)
# Verify it exists
r = docker_exec_sh(container_name, "cat /opt/data/.install_method", timeout=5)
assert r.stdout.strip() == "docker"
# Restart - stage2 should heal it
subprocess.run(
["docker", "restart", container_name],
check=True, capture_output=True, timeout=60,
)
time.sleep(5)
# The stale stamp must be gone
r = docker_exec_sh(
container_name,
"test -f /opt/data/.install_method && "
"cat /opt/data/.install_method || echo HEALED",
timeout=10,
)
assert "HEALED" in r.stdout or r.stdout.strip() != "docker", (
f"stale 'docker' stamp in $HERMES_HOME was not healed on boot: "
f"{r.stdout}"
)

30
tests/docker/test_license_file_present.py Normal file
View file

@ -0,0 +1,30 @@
"""Runtime smoke test for Docker image license-file presence.
Replaces the old text-assertion test that grepped .dockerignore for
the LICENSE filename. This test builds the real image and verifies the
LICENSE file is actually present inside the container, which is the
behavioral outcome the old test was trying to guard (PEP 639
license-files metadata must resolve inside the Docker image).
"""
from __future__ import annotations
import subprocess
def test_docker_image_contains_license_file(built_image: str) -> None:
"""The LICENSE file must be present inside the built Docker image.
PEP 639 license-files metadata references LICENSE, and the Docker
build context must not exclude it. The old test checked .dockerignore
text; this test verifies the actual runtime outcome: the file exists
at /opt/hermes/LICENSE inside the image.
"""
r = subprocess.run(
["docker", "run", "--rm", "--entrypoint", "test",
built_image, "-f", "/opt/hermes/LICENSE"],
capture_output=True, text=True, timeout=60,
)
assert r.returncode == 0, (
f"LICENSE file not found at /opt/hermes/LICENSE inside the Docker "
f"image: {r.stderr[-500:]}"
)

57
tests/docker/test_log_dir_seed.py Normal file
View file

@ -0,0 +1,57 @@
"""Runtime smoke test for Docker $HERMES_HOME/logs/gateways seeding.
Replaces the old text-assertion test that grepped stage2-hook.sh for
the mkdir -p seed block. This test builds the real image and verifies
the actual runtime outcome: logs/ and logs/gateways/ exist and are
owned by the hermes user after container boot.
Regression guard for #45258: if the first gateway log service runs in
root context, logs/gateways/ is created root-owned; every profile
registered later runs its log service as the dropped hermes user and
s6-log crash-loops on mkdir: Permission denied.
"""
from __future__ import annotations
import subprocess
import time
from tests.docker.conftest import docker_exec_sh
def test_logs_gateways_seeded_and_hermes_owned(
built_image: str, container_name: str,
) -> None:
"""logs/ and logs/gateways/ must exist and be owned by hermes after boot."""
subprocess.run(
["docker", "run", "-d", "--name", container_name,
built_image, "sleep", "infinity"],
check=True, capture_output=True, timeout=60,
)
time.sleep(5)
# Both directories must exist
r = docker_exec_sh(
container_name,
"test -d /opt/data/logs && "
"test -d /opt/data/logs/gateways && "
"echo DIRS_OK || echo DIRS_MISSING",
timeout=10,
)
assert "DIRS_OK" in r.stdout, (
f"logs/ or logs/gateways/ not seeded: {r.stdout}"
)
# Both must be owned by hermes
r = docker_exec_sh(
container_name,
'logs_owner=$(stat -c "%U" /opt/data/logs); '
'gateways_owner=$(stat -c "%U" /opt/data/logs/gateways); '
'echo "logs=$logs_owner gateways=$gateways_owner"',
timeout=10,
)
assert "logs=hermes" in r.stdout, (
f"logs/ not owned by hermes: {r.stdout}"
)
assert "gateways=hermes" in r.stdout, (
f"logs/gateways/ not owned by hermes: {r.stdout}"
)

123
tests/docker/test_puid_pgid_remap.py Normal file
View file

@ -0,0 +1,123 @@
"""Runtime smoke tests for Docker PUID/PGID and UID/GID remap.
Replaces the old text-assertion tests that extracted shell blocks from
stage2-hook.sh and ran them in sandboxes. These tests build the real
image and verify the actual runtime behavior:
1. PUID/PGID env vars remap the hermes user UID/GID at boot
2. HERMES_UID/HERMES_GID take precedence over PUID/PGID aliases
3. NAS-style low UIDs (99:100) are accepted and remapped
4. Invalid UIDs are rejected
5. The remapped user can write to the data volume
"""
from __future__ import annotations
import subprocess
import time
from tests.docker.conftest import docker_exec_sh
def test_puid_pgid_remaps_hermes_user(
built_image: str, container_name: str,
) -> None:
"""PUID=1000 PGID=1000 must remap the hermes user to UID 1000."""
subprocess.run(
["docker", "run", "-d", "--name", container_name,
"-e", "PUID=1000",
"-e", "PGID=1000",
built_image, "sleep", "infinity"],
check=True, capture_output=True, timeout=60,
)
time.sleep(5)
r = docker_exec_sh(
container_name,
"id -u hermes",
timeout=10,
)
assert r.stdout.strip() == "1000", (
f"expected hermes UID 1000 after PUID remap, got: {r.stdout.strip()}"
)
r = docker_exec_sh(
container_name,
"id -g hermes",
timeout=10,
)
assert r.stdout.strip() == "1000", (
f"expected hermes GID 1000 after PGID remap, got: {r.stdout.strip()}"
)
def test_hermes_uid_gid_take_precedence_over_aliases(
built_image: str, container_name: str,
) -> None:
"""HERMES_UID/HERMES_GID must win over PUID/PGID when both are set."""
subprocess.run(
["docker", "run", "-d", "--name", container_name,
"-e", "HERMES_UID=2000",
"-e", "HERMES_GID=2001",
"-e", "PUID=1000",
"-e", "PGID=1000",
built_image, "sleep", "infinity"],
check=True, capture_output=True, timeout=60,
)
time.sleep(5)
r = docker_exec_sh(container_name, "id -u hermes", timeout=10)
assert r.stdout.strip() == "2000", (
f"expected hermes UID 2000 (HERMES_UID wins), got: {r.stdout.strip()}"
)
r = docker_exec_sh(container_name, "id -g hermes", timeout=10)
assert r.stdout.strip() == "2001", (
f"expected hermes GID 2001 (HERMES_GID wins), got: {r.stdout.strip()}"
)
def test_nas_low_uid_accepted(
built_image: str, container_name: str,
) -> None:
"""NAS-style low UIDs (99:100, common on Unraid) must be accepted."""
subprocess.run(
["docker", "run", "-d", "--name", container_name,
"-e", "PUID=99",
"-e", "PGID=100",
built_image, "sleep", "infinity"],
check=True, capture_output=True, timeout=60,
)
time.sleep(5)
r = docker_exec_sh(container_name, "id -u hermes", timeout=10)
assert r.stdout.strip() == "99", (
f"expected hermes UID 99, got: {r.stdout.strip()}"
)
r = docker_exec_sh(container_name, "id -g hermes", timeout=10)
assert r.stdout.strip() == "100", (
f"expected hermes GID 100, got: {r.stdout.strip()}"
)
def test_remap_enables_data_volume_writes(
built_image: str, container_name: str,
) -> None:
"""After remap, the hermes user must be able to write to /opt/data."""
subprocess.run(
["docker", "run", "-d", "--name", container_name,
"-e", "PUID=1000",
"-e", "PGID=1000",
built_image, "sleep", "infinity"],
check=True, capture_output=True, timeout=60,
)
time.sleep(5)
r = docker_exec_sh(
container_name,
"touch /opt/data/test_write && echo WRITE_OK || echo WRITE_FAIL",
timeout=10,
)
assert "WRITE_OK" in r.stdout, (
f"hermes user cannot write to /opt/data after remap: {r.stdout}"
)

123
tests/docker/test_stage2_browser_discovery.py Normal file
View file

@ -0,0 +1,123 @@
"""Runtime smoke tests for Docker stage2 browser executable discovery.
Replaces the old text-assertion tests that grepped stage2-hook.sh for
string patterns. These tests build the real image and verify the
chromium binary is actually discovered at boot — i.e.
``AGENT_BROWSER_EXECUTABLE_PATH`` is set, points to a real executable,
and is a browser binary (not a shared library picked up by a broad
``find | grep``).
"""
from __future__ import annotations
import subprocess
import time
from tests.docker.conftest import docker_exec_sh
def _wait_for_stage2(container: str, deadline_s: float = 30.0) -> None:
"""Wait for stage2-hook to complete by polling for its completion log."""
end = time.monotonic() + deadline_s
while time.monotonic() < end:
r = docker_exec_sh(
container,
"grep -q 'stage2.*Setup complete' /proc/1/fd/2 2>/dev/null "
"|| grep -rq 'stage2.*Setup complete' /run/s6 2>/dev/null "
"|| true",
timeout=5,
)
# stage2 logs to stderr which s6 captures; check the container's
# s6 log surface instead. The simplest reliable signal is that
# the env var exists.
r = docker_exec_sh(
container,
"test -f /run/s6/container_environment/AGENT_BROWSER_EXECUTABLE_PATH",
timeout=5,
)
if r.returncode == 0:
return
time.sleep(0.5)
def test_stage2_discovers_chromium_binary(
built_image: str, container_name: str,
) -> None:
"""The stage2 hook must discover the Playwright chromium binary and
export AGENT_BROWSER_EXECUTABLE_PATH so the browser tool can find it.
Regression: the old ``find | grep -Ei 'chrome|chromium'`` picked up
shared libraries (libGLESv2.so etc.) that inherit the executable bit
from Playwright's tarball. The fix uses filename matching; this test
verifies the discovered binary is a real browser, not a .so.
"""
subprocess.run(
["docker", "run", "-d", "--name", container_name,
built_image, "sleep", "infinity"],
check=True, capture_output=True, timeout=60,
)
# Give s6 + stage2-hook time to run.
time.sleep(5)
# AGENT_BROWSER_EXECUTABLE_PATH must be set via s6 container_environment.
r = docker_exec_sh(
container_name,
"cat /run/s6/container_environment/AGENT_BROWSER_EXECUTABLE_PATH",
timeout=10,
)
assert r.returncode == 0, (
f"AGENT_BROWSER_EXECUTABLE_PATH not set by stage2 hook: {r.stderr}"
)
browser_path = r.stdout.strip()
assert browser_path, "AGENT_BROWSER_EXECUTABLE_PATH is empty"
# Must be a real file and executable.
r = docker_exec_sh(
container_name,
f'test -x "{browser_path}"',
timeout=5,
)
assert r.returncode == 0, (
f"discovered browser path is not executable: {browser_path}"
)
# Must be a browser binary by basename — NOT a shared library.
# This is the runtime equivalent of the old "filename-matched" test.
accepted_names = (
"chrome", "chromium", "chrome-headless-shell",
"headless_shell", "chromium-browser",
)
r = docker_exec_sh(
container_name,
f'basename "{browser_path}"',
timeout=5,
)
basename = r.stdout.strip()
assert basename in accepted_names, (
f"discovered binary basename {basename!r} is not a recognized "
f"browser name (accepted: {accepted_names}) — the discovery may "
f"have picked up a shared library (.so) instead of the real browser"
)
def test_stage2_browser_path_accessible_to_hermes_user(
built_image: str, container_name: str,
) -> None:
"""The discovered browser binary must be accessible to the
unprivileged hermes user (UID 10000), since that's who runs
agent-browser subprocesses."""
subprocess.run(
["docker", "run", "-d", "--name", container_name,
built_image, "sleep", "infinity"],
check=True, capture_output=True, timeout=60,
)
time.sleep(5)
r = docker_exec_sh(
container_name,
'path="$(cat /run/s6/container_environment/AGENT_BROWSER_EXECUTABLE_PATH)" '
'&& test -r "$path" && test -x "$path"',
timeout=10,
)
assert r.returncode == 0, (
f"browser binary not readable+executable by hermes user: {r.stderr}"
)

55
tests/docker/test_tini_compat_shim.py Normal file
View file

@ -0,0 +1,55 @@
"""Runtime smoke test for the Docker tini compatibility shim (#34192).
Replaces the old text-assertion tests that grepped the Dockerfile for
string patterns. These tests build the real image and verify:
1. /usr/bin/tini exists and is a symlink to /init (the compat shim
for orchestration templates that still reference /usr/bin/tini)
2. The actual ENTRYPOINT is /init (s6-overlay), not /usr/bin/tini
"""
from __future__ import annotations
import subprocess
def test_tini_compat_symlink_exists(built_image: str) -> None:
"""/usr/bin/tini must exist as a symlink to /init.
Regression for #34192: orchestration templates (e.g. Hostinger's
'Hermes WebUI' catalog) still pin /usr/bin/tini as the entrypoint.
The shim symlinks it to /init so legacy wrappers exec the right
PID-1 reaper without behavior change.
"""
r = subprocess.run(
["docker", "run", "--rm", "--entrypoint", "sh",
built_image, "-c",
'test -L /usr/bin/tini && '
'test "$(readlink -f /usr/bin/tini)" = "/init"'],
capture_output=True, text=True, timeout=60,
)
assert r.returncode == 0, (
f"/usr/bin/tini is not a symlink to /init: {r.stderr[-500:]}"
)
def test_entrypoint_is_init_not_tini(built_image: str) -> None:
"""The image's actual ENTRYPOINT must be /init (s6-overlay).
The tini shim is only for legacy external wrappers; the image's own
runtime must continue to use the canonical /init.
"""
r = subprocess.run(
["docker", "inspect", built_image,
"--format", "{{json .Config.Entrypoint}}"],
capture_output=True, text=True, timeout=30,
)
assert r.returncode == 0, f"docker inspect failed: {r.stderr}"
entrypoint = r.stdout.strip()
assert "/init" in entrypoint, (
f"ENTRYPOINT is not /init: {entrypoint!r}"
)
# The entrypoint array should be ["/init", "/opt/hermes/docker/main-wrapper.sh"]
# /usr/bin/tini should NOT be in the entrypoint.
assert "tini" not in entrypoint.lower(), (
f"ENTRYPOINT references tini instead of /init: {entrypoint!r}"
)

111
tests/docker/test_toplevel_chown.py Normal file
View file

@ -0,0 +1,111 @@
"""Runtime smoke tests for Docker top-level state-file ownership repair.
Replaces the old text-assertion tests that extracted the chown for-loop
from stage2-hook.sh and ran it in a sandbox. These tests build the real
image and verify the actual runtime behavior:
1. Root-owned top-level state files (auth.json, state.db, gateway.lock,
gateway_state.json) are chowned to hermes on boot
2. Non-allowlisted host-owned files are NOT touched (targeted, not
blanket find -user root sweep)
"""
from __future__ import annotations
import subprocess
import time
from tests.docker.conftest import docker_exec, docker_exec_sh
# The files the stage2 hook should repair (mirrors the allowlist in
# stage2-hook.sh). We test a representative subset.
ALLOWLISTED_FILES = ("auth.json", "state.db", "gateway.lock", "gateway_state.json")
def test_root_owned_state_files_repaired_on_boot(
built_image: str, container_name: str,
) -> None:
"""Root-owned top-level state files must be chowned to hermes on boot."""
subprocess.run(
["docker", "run", "-d", "--name", container_name,
built_image, "sleep", "infinity"],
check=True, capture_output=True, timeout=60,
)
time.sleep(5)
# Create root-owned state files to simulate docker exec (root) writes
for f in ALLOWLISTED_FILES:
docker_exec(
container_name, "touch", f"/opt/data/{f}",
user="root", timeout=5,
)
# Verify they're root-owned
r = docker_exec_sh(
container_name,
" ".join(f'stat -c %U /opt/data/{f}' for f in ALLOWLISTED_FILES),
timeout=5,
)
for line in r.stdout.split():
assert line == "root", f"expected root-owned, got: {line}"
# Restart - stage2 should repair ownership
subprocess.run(
["docker", "restart", container_name],
check=True, capture_output=True, timeout=60,
)
time.sleep(5)
# Verify files are now hermes-owned
r = docker_exec_sh(
container_name,
" ".join(f'stat -c %U /opt/data/{f}' for f in ALLOWLISTED_FILES),
timeout=5,
)
for line in r.stdout.split():
assert line == "hermes", (
f"expected hermes-owned after restart, got: {line}"
)
def test_non_allowlisted_host_file_not_touched(
built_image: str, container_name: str,
) -> None:
"""A non-allowlisted host-owned file must NOT be chowned, even if
root-owned. Regression guard for #19788 / #19795: a bind-mounted
$HERMES_HOME may contain host-owned files Hermes does not manage."""
subprocess.run(
["docker", "run", "-d", "--name", container_name,
built_image, "sleep", "infinity"],
check=True, capture_output=True, timeout=60,
)
time.sleep(5)
# Create a non-allowlisted file as root
docker_exec(
container_name, "touch", "/opt/data/host_secret.json",
user="root", timeout=5,
)
# Make it root-owned explicitly (it already is, but be sure)
docker_exec(
container_name, "chown", "root:root", "/opt/data/host_secret.json",
user="root", timeout=5,
)
# Restart
subprocess.run(
["docker", "restart", container_name],
check=True, capture_output=True, timeout=60,
)
time.sleep(5)
# The file must STILL be root-owned (not touched by stage2)
r = docker_exec_sh(
container_name,
"stat -c %U /opt/data/host_secret.json",
timeout=5,
)
assert r.stdout.strip() == "root", (
f"non-allowlisted host file was chowned by stage2 (should be "
f"preserved): {r.stdout.strip()}"
)

68
tests/docker/test_user_flag_guard.py Normal file
View file

@ -0,0 +1,68 @@
"""Runtime smoke tests for Docker --user flag guard.
Replaces the old text-assertion tests that extracted the guard block
from stage2-hook.sh and main-wrapper.sh and ran it in a sandbox. These
tests build the real image and verify the actual runtime behavior:
1. docker run --user <arbitrary-uid> is rejected with actionable guidance
2. Root start (default) works fine
3. --user <hermes-uid> (10000) is allowed (supported non-root start)
"""
from __future__ import annotations
import subprocess
def test_arbitrary_user_uid_rejected(
built_image: str,
) -> None:
"""docker run --user 1000 must be rejected with actionable guidance."""
r = subprocess.run(
["docker", "run", "--rm", "--user", "1000:1000",
built_image, "echo", "should_not_reach"],
capture_output=True, text=True, timeout=60,
)
assert r.returncode != 0, (
f"container started with arbitrary --user UID unexpectedly: {r.stdout}"
)
assert "should_not_reach" not in r.stdout, (
f"container ran despite --user rejection: {r.stdout}"
)
combined = r.stdout + r.stderr
assert "not supported" in combined.lower(), (
f"rejection message missing 'not supported': {combined[-500:]}"
)
# Must mention the remediation env vars
assert "HERMES_UID" in combined or "PUID" in combined, (
f"rejection message missing remediation guidance: {combined[-500:]}"
)
def test_root_start_works(
built_image: str,
) -> None:
"""Root start (the default) must work without issues."""
r = subprocess.run(
["docker", "run", "--rm", built_image, "sh", "-c", "echo OK"],
capture_output=True, text=True, timeout=60,
)
assert r.returncode == 0, f"root start failed: {r.stderr[-500:]}"
assert "OK" in r.stdout
def test_user_pinned_to_hermes_uid_works(
built_image: str,
) -> None:
"""docker run --user 10000:10000 (the hermes UID) must be allowed.
This is the supported non-root start from #34648 / #34837.
"""
r = subprocess.run(
["docker", "run", "--rm", "--user", "10000:10000",
built_image, "sh", "-c", "echo OK"],
capture_output=True, text=True, timeout=60,
)
assert r.returncode == 0, (
f"--user 10000:10000 (hermes UID) was rejected: {r.stderr[-500:]}"
)
assert "OK" in r.stdout

91
tests/test_docker_home_override_scripts.py
View file

@ -1,91 +0,0 @@
"""Regression tests for Docker HOME overrides under s6/with-contenv."""
from pathlib import Path
REPO_ROOT = Path(__file__).resolve().parent.parent
DASHBOARD_RUN = REPO_ROOT / "docker" / "s6-rc.d" / "dashboard" / "run"
MAIN_WRAPPER = REPO_ROOT / "docker" / "main-wrapper.sh"
STAGE2_HOOK = REPO_ROOT / "docker" / "stage2-hook.sh"
def test_main_wrapper_preserves_docker_workdir() -> None:
"""The main-wrapper MUST save and restore the original working
directory so the container starts in the Docker ``-w`` directory,
not /opt/data. Regression test for #35472.
"""
text = MAIN_WRAPPER.read_text(encoding="utf-8")
# Must save original cwd before cd /opt/data.
assert "_hermes_orig_cwd" in text, (
"main-wrapper.sh must save the original cwd before cd /opt/data"
)
assert 'HERMES_ORIG_CWD:-$PWD' in text, (
"main-wrapper.sh must capture PWD as the fallback original cwd"
)
# Must cd to /opt/data for init (existing behaviour preserved).
assert "cd /opt/data" in text
# Must restore original cwd before exec'ing the user command.
# The restore cd must appear AFTER venv activation but BEFORE the
# first exec / if-block.
activate_idx = text.index("/opt/hermes/.venv/bin/activate")
restore_idx = text.index('cd "$_hermes_orig_cwd"')
exec_idx = text.index("if [ $# -eq 0 ]")
assert activate_idx < restore_idx < exec_idx, (
"cd $_hermes_orig_cwd must appear after venv activation and "
"before the exec routing block"
)
def test_dashboard_run_resets_home_before_dropping_privileges() -> None:
text = DASHBOARD_RUN.read_text(encoding="utf-8")
assert "#!/command/with-contenv sh" in text
assert "export HOME=/opt/data" in text
assert "exec s6-setuidgid hermes hermes dashboard" in text
def test_dashboard_run_does_not_derive_insecure_from_bind_host() -> None:
"""The s6 dashboard run script MUST NOT auto-add ``--insecure`` based on
``HERMES_DASHBOARD_HOST``. Doing so disables the OAuth auth gate on
every non-loopback bind even when an auth provider is registered —
the exact regression that exposed every wildcard-subdomain agent
dashboard publicly until early 2026.
The opt-in is now explicit: ``HERMES_DASHBOARD_INSECURE=1`` (truthy).
The auth gate is the authority on whether non-loopback binds are safe.
"""
text = DASHBOARD_RUN.read_text(encoding="utf-8")
# No legacy host-derived flip.
assert '127.0.0.1|localhost' not in text, (
"Run script still derives --insecure from the bind host. The gate "
"is the authority now — opt in via HERMES_DASHBOARD_INSECURE instead."
)
assert 'case "$dash_host" in' not in text, (
"Legacy host-derived --insecure case-statement is back."
)
# New opt-in env var present.
assert "HERMES_DASHBOARD_INSECURE" in text, (
"Explicit HERMES_DASHBOARD_INSECURE opt-in is missing."
)
# Truthy values aligned with the rest of the s6 scripts
# (e.g. HERMES_DASHBOARD).
for truthy in ("1", "true", "TRUE", "True", "yes", "YES", "Yes"):
assert truthy in text, (
f"HERMES_DASHBOARD_INSECURE should accept truthy value {truthy!r}"
)
def test_stage2_hook_repairs_profiles_and_cron_ownership_on_every_boot() -> None:
"""profiles/ and cron/ must both be reclaimed after root-context writes."""
text = STAGE2_HOOK.read_text(encoding="utf-8")
assert 'if [ -d "$HERMES_HOME/profiles" ]; then' in text
assert 'chown -R hermes:hermes "$HERMES_HOME/profiles" 2>/dev/null || true' in text
assert 'if [ -d "$HERMES_HOME/cron" ]; then' in text
assert 'chown -R hermes:hermes "$HERMES_HOME/cron" 2>/dev/null || true' in text

19
tests/test_docker_stage2_browser_discovery.py
View file

@ -1,19 +0,0 @@
"""Regression tests for Docker stage2 browser executable discovery."""
from pathlib import Path
def test_stage2_discovers_playwright_arm64_headless_shell() -> None:
"""Playwright's --only-shell layout may use a headless_shell basename."""
script = Path("docker/stage2-hook.sh").read_text()
assert "-name 'headless_shell'" in script
def test_stage2_discovery_stays_filename_matched() -> None:
"""Avoid broad path grep that can pick executable shared libraries."""
script = Path("docker/stage2-hook.sh").read_text()
discovery_block = script.split("browser_bin=$(", 1)[1].split(")\n if", 1)[0]
assert "find \"$PLAYWRIGHT_BROWSERS_PATH\" -type f -executable" in discovery_block
assert "grep" not in discovery_block

49
tests/test_dockerfile_tini_compat_shim.py
View file

@ -1,49 +0,0 @@
"""Regression test for #34192 — Dockerfile must keep the tini compat shim
for orchestration templates that still reference /usr/bin/tini.
This is a documentation-as-test guard: removing the shim is a real
choice, but it should be done deliberately (e.g. once Hostinger's
'Hermes WebUI' catalog updates to /init) and not by accident.
"""
from __future__ import annotations
from pathlib import Path
def _dockerfile_text() -> str:
return (Path(__file__).parent.parent / "Dockerfile").read_text(encoding="utf-8")
def test_tini_compat_symlink_present():
"""The /usr/bin/tini -> /init symlink line must exist for #34192."""
df = _dockerfile_text()
assert "ln -sf /init /usr/bin/tini" in df, (
"Dockerfile must keep the tini compat symlink (#34192). "
"Removing it breaks orchestration templates that still pin "
"/usr/bin/tini as the entrypoint (Hostinger 'Hermes WebUI' "
"catalog as of v0.14.x)."
)
def test_tini_compat_comment_explains_why():
"""The symlink line is comment-anchored to #34192 so a future reader
knows why it exists. Removing the comment makes it look like dead
code worth deleting."""
df = _dockerfile_text()
assert "#34192" in df, (
"The Dockerfile tini compat shim must keep its #34192 anchor "
"comment so future maintainers know why the symlink is there."
)
def test_entrypoint_still_init_not_tini():
"""Sanity check: the actual ENTRYPOINT is still /init (s6-overlay).
The shim is for legacy external wrappers, not for the image's own
runtime — that path must continue to use the canonical /init."""
df = _dockerfile_text()
assert 'ENTRYPOINT [ "/init"' in df, (
"Dockerfile ENTRYPOINT must remain /init (s6-overlay). The "
"tini shim is only for external wrappers that haven't been "
"updated yet."
)

17
tests/test_docker_webui_install_surface.py → tests/test_setup_temporary_outputs.py
View file

@ -1,5 +1,6 @@
"""Guards for the multi-container Hermes WebUI install surface."""
"""Test that setup.py uses temporary output directories when the source
tree is read-only (as it is inside the Docker WebUI install surface).
"""
from __future__ import annotations
from pathlib import Path
@ -20,18 +21,6 @@ def _is_under(path: str, root: Path) -> bool:
return True
def test_docker_context_includes_license_file() -> None:
"""PEP 639 license-files metadata must resolve inside the Docker image."""
dockerignore = (REPO_ROOT / ".dockerignore").read_text(encoding="utf-8")
active_lines = [
line.strip()
for line in dockerignore.splitlines()
if line.strip() and not line.lstrip().startswith("#")
]
assert "LICENSE" not in active_lines
def test_setup_uses_temporary_outputs_when_source_tree_is_read_only(
monkeypatch,
) -> None:

152
tests/tools/test_stage2_hook_gateway_bootstrap_state.py
View file

@ -1,152 +0,0 @@
"""Contract test: the s6-overlay stage2 hook seeds gateway_state.json from
HERMES_GATEWAY_BOOTSTRAP_STATE on first boot, so a freshly-provisioned
container can come up with the gateway already running.
Background. On a blank volume there is no gateway_state.json, so the boot
reconciler (cont-init.d/02-reconcile-profiles ->
container_boot.reconcile_profile_gateways) registers the gateway-default s6
slot but leaves it DOWN — it only auto-starts when the last recorded state was
"running". A container provisioned on a fresh volume therefore comes up with
the gateway down until something starts it.
An orchestrator that wants the gateway running from first boot sets
HERMES_GATEWAY_BOOTSTRAP_STATE=running; stage2-hook.sh (installed as
/etc/cont-init.d/01-hermes-setup, which runs lexicographically BEFORE
02-reconcile-profiles) seeds the state file so the reconciler sees
prior_state=running and brings the slot up on the very first boot.
This mirrors the existing HERMES_AUTH_JSON_BOOTSTRAP env-seed pattern: it seeds
the SAME gateway_state.json the reconciler already consults, guarded by
``[ ! -f ]`` so persisted runtime state always wins on subsequent boots (a
deliberately-stopped gateway must stay stopped across restarts).
"""
from __future__ import annotations
import json
import re
import shutil
import subprocess
import tempfile
from pathlib import Path
import pytest
REPO_ROOT = Path(__file__).resolve().parents[2]
STAGE2_HOOK = REPO_ROOT / "docker" / "stage2-hook.sh"
@pytest.fixture(scope="module")
def stage2_text() -> str:
if not STAGE2_HOOK.exists():
pytest.skip("docker/stage2-hook.sh not present in this checkout")
return STAGE2_HOOK.read_text()
def _seed_block(text: str) -> str:
"""Extract the ``if [ ! -f "$HERMES_HOME/gateway_state.json" ] && … fi``
block that seeds the gateway state file from the bootstrap env var."""
m = re.search(
r'(if \[ ! -f "\$HERMES_HOME/gateway_state\.json" \] && \\\n'
r"(?:.*\n)*?fi)",
text,
)
assert m, (
"stage2-hook.sh must contain the gateway_state.json bootstrap-seed block "
"guarded on HERMES_GATEWAY_BOOTSTRAP_STATE"
)
return m.group(1)
def test_seed_block_present_and_guarded(stage2_text: str) -> None:
block = _seed_block(stage2_text)
# Must be a first-boot-only seed (the [ ! -f ] guard) keyed on the env var.
assert '[ ! -f "$HERMES_HOME/gateway_state.json" ]' in block, (
"seed must be guarded by [ ! -f ] so persisted state wins on restart"
)
assert "HERMES_GATEWAY_BOOTSTRAP_STATE" in block
assert "gateway_state" in block
def _run_seed(
text: str, *, env_value: str | None, preexisting: str | None
) -> str | None:
"""Run the extracted seed block in a sandbox $HERMES_HOME.
``env_value`` is the HERMES_GATEWAY_BOOTSTRAP_STATE value (None = unset).
``preexisting`` is the contents of a gateway_state.json placed before the
block runs (None = no file). Returns the file's contents afterwards, or
None if it doesn't exist. ``chown``/``chmod`` are stubbed so the block
runs without real root.
"""
bash = shutil.which("bash")
if bash is None:
pytest.skip("bash not available")
block = _seed_block(text)
with tempfile.TemporaryDirectory() as d:
dpath = Path(d)
home = dpath / "home"
home.mkdir()
state_file = home / "gateway_state.json"
if preexisting is not None:
state_file.write_text(preexisting)
env_line = (
f'export HERMES_GATEWAY_BOOTSTRAP_STATE="{env_value}"\n'
if env_value is not None
else "unset HERMES_GATEWAY_BOOTSTRAP_STATE\n"
)
script = (
"set -e\n"
f'HERMES_HOME="{home}"\n'
# Stub privilege ops — the sandbox isn't root.
"chown() { :; }\n"
"chmod() { :; }\n"
+ env_line
+ block
)
script_path = dpath / "harness.sh"
script_path.write_text(script)
proc = subprocess.run(
[bash, str(script_path)], capture_output=True, text=True
)
assert proc.returncode == 0, proc.stderr
if not state_file.exists():
return None
return state_file.read_text()
def test_seeds_running_state_on_blank_volume(stage2_text: str) -> None:
"""env=running + no pre-existing file -> writes a valid running state."""
out = _run_seed(stage2_text, env_value="running", preexisting=None)
assert out is not None, "seed must create gateway_state.json"
assert json.loads(out).get("gateway_state") == "running"
def test_does_not_clobber_existing_state(stage2_text: str) -> None:
"""The [ ! -f ] guard: an existing state file is never overwritten, even
when the bootstrap env var says running. A deliberately-stopped gateway
must stay stopped across restarts."""
existing = json.dumps({"gateway_state": "stopped", "pid": 123})
out = _run_seed(stage2_text, env_value="running", preexisting=existing)
assert out == existing, "seed must not clobber a persisted state file"
def test_no_seed_when_env_unset(stage2_text: str) -> None:
"""No env var -> no file written (preserves the default down-on-first-boot
behaviour for orchestrators that don't opt in)."""
out = _run_seed(stage2_text, env_value=None, preexisting=None)
assert out is None, "seed must not run when HERMES_GATEWAY_BOOTSTRAP_STATE is unset"
def test_non_running_value_ignored(stage2_text: str) -> None:
"""Only a literal "running" is honoured; any other value is ignored so a
typo can't write a bogus state. (The reconciler's _AUTOSTART_STATES is
exactly {"running"}.)"""
for bogus in ("stopped", "Running", "1", "true", "starting"):
out = _run_seed(stage2_text, env_value=bogus, preexisting=None)
assert out is None, (
f"only 'running' should seed a state file, not {bogus!r}"
)

48
tests/tools/test_stage2_hook_immutable_install.py
View file

@ -1,48 +0,0 @@
"""Contract tests for the Docker stage2 immutable install-tree policy.
Hosted/container Hermes keeps user-writable state under HERMES_HOME
(/opt/data). The installed source, venv, TUI bundle, and node_modules under
/opt/hermes must remain root-owned/non-writable by the runtime hermes user so
an agent session cannot self-modify the installation and brick the gateway.
"""
from __future__ import annotations
from pathlib import Path
import pytest
REPO_ROOT = Path(__file__).resolve().parents[2]
STAGE2_HOOK = REPO_ROOT / "docker" / "stage2-hook.sh"
@pytest.fixture(scope="module")
def stage2_text() -> str:
if not STAGE2_HOOK.exists():
pytest.skip("docker/stage2-hook.sh not present in this checkout")
return STAGE2_HOOK.read_text()
def test_stage2_does_not_chown_install_tree_to_hermes(stage2_text: str) -> None:
assert "Fixing ownership of build trees under $INSTALL_DIR" not in stage2_text
assert 'chown -R hermes:hermes \\\n "$INSTALL_DIR/.venv"' not in stage2_text
assert "venv_owner=$(stat -c %u \"$INSTALL_DIR/.venv\"" not in stage2_text
assert "chown of build trees failed" not in stage2_text
for install_tree in (
'"$INSTALL_DIR/.venv" \\',
'"$INSTALL_DIR/ui-tui" \\',
'"$INSTALL_DIR/gateway" \\',
'"$INSTALL_DIR/node_modules" \\',
):
assert install_tree not in stage2_text, (
f"stage2 must not chown {install_tree} back to hermes; "
"the Dockerfile keeps /opt/hermes immutable and writable state "
"belongs under HERMES_HOME"
)
def test_stage2_documents_immutable_install_contract(stage2_text: str) -> None:
assert "Immutable install tree" in stage2_text
assert "PYTHONDONTWRITEBYTECODE" in stage2_text
assert "HERMES_DISABLE_LAZY_INSTALLS=1" in stage2_text
assert "/opt/hermes" in stage2_text

61
tests/tools/test_stage2_hook_install_method_stamp.py
View file

@ -1,61 +0,0 @@
"""Contract test: the s6-overlay stage2 hook must NOT stamp the install method
into the shared $HERMES_HOME, and must heal a stale 'docker' stamp left there
by older images.
Background (shared-$HERMES_HOME bug)
------------------------------------
$HERMES_HOME (/opt/data) is a DATA volume that users commonly bind-mount from
the host (``~/.hermes:/opt/data``) and sometimes share with a host-side
Desktop/CLI install. Older images wrote ``printf 'docker' > $HERMES_HOME/.install_method``
at boot, which clobbered the host install's own marker — so the host's in-app
updater read 'docker' and refused to run ``hermes update`` ("doesn't apply
inside the Docker container").
The fix scopes the stamp to the install tree (baked at
``/opt/hermes/.install_method`` in the Dockerfile, read first by
``detect_install_method``). stage2 must therefore:
* NOT write the 'docker' stamp into $HERMES_HOME any more, and
* proactively remove a stale 'docker' stamp from $HERMES_HOME so homes
already poisoned by an older image self-heal on the next boot.
"""
from __future__ import annotations
import re
from pathlib import Path
import pytest
REPO_ROOT = Path(__file__).resolve().parents[2]
STAGE2_HOOK = REPO_ROOT / "docker" / "stage2-hook.sh"
@pytest.fixture(scope="module")
def stage2_text() -> str:
if not STAGE2_HOOK.exists():
pytest.skip("docker/stage2-hook.sh not present in this checkout")
return STAGE2_HOOK.read_text()
def test_stage2_does_not_write_install_method_into_home(stage2_text: str) -> None:
# No write/tee of the home-scoped install-method stamp anywhere.
assert not re.search(
r"(tee|>)\s*\"?\$HERMES_HOME/\.install_method", stage2_text
), (
"stage2 must not stamp $HERMES_HOME/.install_method — that data dir "
"may be shared with a host install whose marker would be clobbered"
)
def test_stage2_heals_stale_docker_home_stamp(stage2_text: str) -> None:
# It must remove a stale 'docker' stamp from $HERMES_HOME so already
# poisoned shared homes recover.
assert 'rm -f "$HERMES_HOME/.install_method"' in stage2_text, (
"stage2 must remove a stale 'docker' stamp from $HERMES_HOME to heal "
"homes poisoned by older images"
)
# The removal must be guarded on the value being 'docker' so we never
# delete a legitimately-different stamp a user/host install put there.
assert re.search(r'\[\s*"\$stamped"\s*=\s*"docker"\s*\]', stage2_text), (
"the stale-stamp removal must be guarded on the value == 'docker'"
)

60
tests/tools/test_stage2_hook_log_dir_seed.py
View file

@ -1,60 +0,0 @@
"""Contract test: the s6-overlay stage2 hook seeds $HERMES_HOME/logs/gateways
as the hermes user.
Regression guard for #45258: the per-profile gateway log service
(`gateway-<profile>/log/run`) creates `logs/gateways/` via `mkdir -p` but only
chowns the leaf `logs/gateways/<profile>`. If the first log service to boot
runs in root context, the `gateways/` parent is created root-owned and stays
that way; every profile registered later runs its log service as the dropped
hermes user and s6-log crash-loops on `mkdir: Permission denied`.
Seeding `logs/gateways` in stage2 (cont-init runs before any service starts)
guarantees the parent already exists hermes-owned by the time the first
log/run executes its `mkdir -p`.
"""
from __future__ import annotations
import re
from pathlib import Path
import pytest
REPO_ROOT = Path(__file__).resolve().parents[2]
STAGE2_HOOK = REPO_ROOT / "docker" / "stage2-hook.sh"
@pytest.fixture(scope="module")
def stage2_text() -> str:
if not STAGE2_HOOK.exists():
pytest.skip("docker/stage2-hook.sh not present in this checkout")
return STAGE2_HOOK.read_text()
def _seed_mkdir_block(text: str) -> str:
"""Extract the `as_hermes mkdir -p \\ ...` seed block."""
m = re.search(r"as_hermes mkdir -p \\\n(?:[^\n]*\\\n)*[^\n]*\n", text)
assert m, "stage2-hook.sh must contain the as_hermes mkdir -p seed block"
return m.group(0)
def test_logs_gateways_is_seeded(stage2_text: str) -> None:
block = _seed_mkdir_block(stage2_text)
assert '"$HERMES_HOME/logs/gateways"' in block, (
"logs/gateways must be seeded hermes-owned in stage2 so profiles "
"added after first boot can create their log dirs (#45258)"
)
# The parent must also be seeded so mkdir -p inside the block never
# creates logs/ implicitly with surprising ownership.
assert '"$HERMES_HOME/logs"' in block
def test_logs_subtree_is_healed_when_chown_needed(stage2_text: str) -> None:
"""The needs_chown repair loop must cover the logs subtree recursively —
that is what makes the seed entry above sufficient (no separate
logs/gateways loop entry needed)."""
m = re.search(r"for sub in ([^;]*); do", stage2_text)
assert m, "stage2-hook.sh must contain the needs_chown subdir repair loop"
assert "logs" in m.group(1).split(), (
"the needs_chown loop must recursively chown logs/ — it covers "
"logs/gateways, so the seed list does not need a loop twin"
)

110
tests/tools/test_stage2_hook_puid_pgid.py
View file

@ -1,110 +0,0 @@
"""Contract test: the s6-overlay stage2 hook accepts PUID/PGID as aliases for
HERMES_UID/HERMES_GID.
Regression guard for #15290. NAS platforms (UGOS, Synology, unRAID) bind-mount
/opt/data from a host directory owned by the user's own UID and expect the
LinuxServer.io PUID/PGID convention. Without the alias those vars are silently
ignored, the s6-setuidgid drop lands on UID 10000, and the runtime cannot read
the volume. HERMES_UID/HERMES_GID must still take precedence when both are
set.
The s6-overlay rework moved bootstrap from docker/entrypoint.sh (now a shim)
to docker/stage2-hook.sh, which is installed as /etc/cont-init.d/01-hermes-setup
by the Dockerfile. This test targets the post-rework location.
"""
from __future__ import annotations
import os
import shutil
import subprocess
from pathlib import Path
import pytest
REPO_ROOT = Path(__file__).resolve().parents[2]
STAGE2_HOOK = REPO_ROOT / "docker" / "stage2-hook.sh"
@pytest.fixture(scope="module")
def stage2_text() -> str:
if not STAGE2_HOOK.exists():
pytest.skip("docker/stage2-hook.sh not present in this checkout")
return STAGE2_HOOK.read_text()
def _alias_lines(text: str) -> list[str]:
"""The stage2 hook lines that resolve HERMES_UID/HERMES_GID from aliases."""
return [
line.strip()
for line in text.splitlines()
if line.strip().startswith(("HERMES_UID=", "HERMES_GID="))
]
def test_stage2_hook_resolves_puid_pgid_aliases(stage2_text: str) -> None:
alias_lines = _alias_lines(stage2_text)
assert any("PUID" in line for line in alias_lines), (
"docker/stage2-hook.sh must resolve HERMES_UID from a PUID alias; see #15290"
)
assert any("PGID" in line for line in alias_lines), (
"docker/stage2-hook.sh must resolve HERMES_GID from a PGID alias; see #15290"
)
def _resolve(stage2_text: str, env: dict[str, str]) -> str:
"""Run the stage2 hook's alias-resolution lines in isolation and report the
resolved ``HERMES_UID:HERMES_GID`` pair."""
bash = shutil.which("bash")
if bash is None:
pytest.skip("bash not available")
script = "\n".join(_alias_lines(stage2_text))
script += '\necho "${HERMES_UID:-}:${HERMES_GID:-}"\n'
proc = subprocess.run(
[bash, "-ec", script],
env={"PATH": os.environ.get("PATH", "")} | env,
capture_output=True,
text=True,
)
assert proc.returncode == 0, proc.stderr
return proc.stdout.strip()
def test_puid_pgid_populate_hermes_uid_gid(stage2_text: str) -> None:
assert _resolve(stage2_text, {"PUID": "1000", "PGID": "10"}) == "1000:10"
def test_hermes_uid_gid_take_precedence_over_aliases(stage2_text: str) -> None:
resolved = _resolve(
stage2_text,
{"HERMES_UID": "2000", "HERMES_GID": "2001", "PUID": "1000", "PGID": "10"},
)
assert resolved == "2000:2001"
def test_no_uid_vars_leaves_values_empty(stage2_text: str) -> None:
# An empty resolution means the stage2 hook keeps the default hermes user.
assert _resolve(stage2_text, {}) == ":"
def test_stage2_hook_creates_s6_envdir_before_writing_browser_path(stage2_text: str) -> None:
"""Regression guard for browser-path export on runtimes where the
s6 container_environment directory is absent when the cont-init hook runs.
"""
mkdir_line = "mkdir -p /run/s6/container_environment"
write_line = (
"printf '%s' \"$browser_bin\" > "
"/run/s6/container_environment/AGENT_BROWSER_EXECUTABLE_PATH"
)
assert mkdir_line in stage2_text
assert write_line in stage2_text
assert stage2_text.index(mkdir_line) < stage2_text.index(write_line)
def test_stage2_hook_runs_config_migration_as_hermes(stage2_text: str) -> None:
assert "scripts/docker_config_migrate.py" in stage2_text
assert 's6-setuidgid hermes "$INSTALL_DIR/.venv/bin/python"' in stage2_text
def test_stage2_hook_documents_config_migration_opt_out(stage2_text: str) -> None:
assert "HERMES_SKIP_CONFIG_MIGRATION" in stage2_text

138
tests/tools/test_stage2_hook_toplevel_chown.py
View file

@ -1,138 +0,0 @@
"""Contract test: the s6-overlay stage2 hook resets ownership of hermes-owned
top-level state files in $HERMES_HOME — but only those, never arbitrary
host-owned files.
Regression guard for the gateway restart loop reported in #35098: files such
as gateway.lock / state.db / auth.json live directly under $HERMES_HOME (not in
a subdir), so the targeted subdir chown misses them. When created or rewritten
by `docker exec <container> hermes …` (root unless `-u` is passed) they land
root-owned and the unprivileged hermes runtime then hits PermissionError on next
startup.
The fix uses an explicit allowlist rather than a blanket `find -user root`
sweep, preserving the targeted-ownership contract from #19788 / PR #19795: a
bind-mounted $HERMES_HOME may contain host-owned files Hermes does not manage,
and those must never be chowned.
The s6-overlay rework moved bootstrap from docker/entrypoint.sh (now a shim) to
docker/stage2-hook.sh, installed as /etc/cont-init.d/01-hermes-setup. This test
targets that location.
"""
from __future__ import annotations
import os
import re
import shutil
import subprocess
from pathlib import Path
import pytest
REPO_ROOT = Path(__file__).resolve().parents[2]
STAGE2_HOOK = REPO_ROOT / "docker" / "stage2-hook.sh"
@pytest.fixture(scope="module")
def stage2_text() -> str:
if not STAGE2_HOOK.exists():
pytest.skip("docker/stage2-hook.sh not present in this checkout")
return STAGE2_HOOK.read_text()
def _toplevel_chown_loop(text: str) -> str:
"""Extract the `for f in … chown hermes:hermes "$HERMES_HOME/$f" … done`
block that repairs top-level state-file ownership."""
m = re.search(
r"(for f in \\\n(?:.*\\\n)*?.*; do\n(?:.*\n)*?done)",
text,
)
assert m, "stage2-hook.sh must contain the top-level-file chown for-loop (#35098)"
block = m.group(1)
assert 'chown hermes:hermes "$HERMES_HOME/$f"' in block, (
"the top-level-file loop must chown each allowlisted file to hermes"
)
return block
def test_toplevel_chown_loop_present(stage2_text: str) -> None:
block = _toplevel_chown_loop(stage2_text)
# The reported-broken files must be covered.
for required in ("auth.json", "state.db", "gateway.lock", "gateway_state.json"):
assert required in block, (
f"top-level chown allowlist must include {required!r} (#35098)"
)
def test_no_blanket_find_user_root_sweep(stage2_text: str) -> None:
"""The fix must NOT reintroduce a blanket `find … -user root` chown of
$HERMES_HOME contents — that would clobber host-owned files in a bind mount
(#19788 / PR #19795)."""
assert not re.search(r"find\s+\"?\$\{?HERMES_HOME\}?\"?[^\n]*-user\s+root", stage2_text), (
"stage2-hook.sh must not blanket-chown root-owned files under "
"$HERMES_HOME via `find -user root`; use the targeted allowlist instead "
"so host-owned bind-mounted files are preserved (#19788, #19795)."
)
def _run_loop(text: str, present_files: list[str]) -> list[str]:
"""Run the extracted chown loop in a sandbox $HERMES_HOME, with `chown`
stubbed to record which paths it was asked to touch. Returns the basenames
the loop attempted to chown."""
bash = shutil.which("bash")
if bash is None:
pytest.skip("bash not available")
block = _toplevel_chown_loop(text)
import tempfile
with tempfile.TemporaryDirectory() as d:
dpath = Path(d)
home = dpath / "home"
home.mkdir()
for f in present_files:
(home / f).touch()
# A non-allowlisted, "host-owned" file that must never be chowned.
(home / "host_secret.json").touch()
# Stub chown to record the basename of its last argument (the path),
# so we observe exactly which files the allowlist loop selected
# without needing real root privileges.
script = (
"set -e\n"
f'HERMES_HOME="{home}"\n'
f'chown() {{ for a in "$@"; do :; done; echo "${{a##*/}}" >> "{dpath}/chown.log"; }}\n'
+ block
)
script_path = dpath / "harness.sh"
script_path.write_text(script)
proc = subprocess.run([bash, str(script_path)], capture_output=True, text=True)
assert proc.returncode == 0, proc.stderr
log = dpath / "chown.log"
if not log.exists():
return []
return [ln for ln in log.read_text().splitlines() if ln]
def test_loop_chowns_present_allowlisted_files(stage2_text: str) -> None:
touched = _run_loop(stage2_text, ["auth.json", "state.db", "gateway.lock"])
assert "auth.json" in touched
assert "state.db" in touched
assert "gateway.lock" in touched
def test_loop_skips_nonallowlisted_host_file(stage2_text: str) -> None:
"""A file NOT on the allowlist (e.g. a host-owned file in a bind mount) must
never be chowned, even if present."""
touched = _run_loop(stage2_text, ["auth.json"])
assert "host_secret.json" not in touched, (
"the allowlist loop must not touch non-allowlisted files (#19788)"
)
def test_loop_skips_absent_files(stage2_text: str) -> None:
"""Allowlisted files that don't exist are skipped (no spurious chown)."""
touched = _run_loop(stage2_text, ["auth.json"])
# state.db wasn't created, so it must not appear.
assert "state.db" not in touched

86
tests/tools/test_stage2_hook_unraid_uid.py
View file

@ -1,86 +0,0 @@
"""Regression tests for Docker stage2 UID/GID handling on NAS hosts.
Unraid commonly runs appdata as nobody:users (99:100). The stage2 hook must
accept those non-root numeric IDs and keep legacy/new pairing stores writable
after targeted ownership reconciliation.
"""
from __future__ import annotations
import os
import re
import shutil
import subprocess
from pathlib import Path
import pytest
REPO_ROOT = Path(__file__).resolve().parents[2]
STAGE2_HOOK = REPO_ROOT / "docker" / "stage2-hook.sh"
@pytest.fixture(scope="module")
def stage2_text() -> str:
if not STAGE2_HOOK.exists():
pytest.skip("docker/stage2-hook.sh not present in this checkout")
return STAGE2_HOOK.read_text()
def _uid_gid_validator(text: str) -> str:
marker = "# --- UID/GID remap ---"
before_marker = text.split(marker, 1)[0]
start = before_marker.index("validate_uid_gid()")
return before_marker[start:]
def _validate_uid_gid(text: str, value: str) -> bool:
bash = shutil.which("bash")
if bash is None:
pytest.skip("bash not available")
script = _uid_gid_validator(text) + '\nvalidate_uid_gid "$CANDIDATE"\n'
proc = subprocess.run(
[bash, "-c", script],
env={"PATH": os.environ.get("PATH", ""), "CANDIDATE": value},
capture_output=True,
text=True,
)
return proc.returncode == 0
@pytest.mark.parametrize("value", ["1", "99", "100", "1000", "65534"])
def test_uid_gid_validator_accepts_non_root_nas_ids(stage2_text: str, value: str) -> None:
assert _validate_uid_gid(stage2_text, value), (
f"stage2 hook must accept NAS UID/GID {value}; Unraid uses 99:100 (#38070)"
)
@pytest.mark.parametrize("value", ["", "0", "abc", "99x", "65535"])
def test_uid_gid_validator_rejects_root_invalid_and_out_of_range(
stage2_text: str,
value: str,
) -> None:
assert not _validate_uid_gid(stage2_text, value)
def _targeted_chown_subdirs(text: str) -> list[str]:
m = re.search(
r"for sub in (?P<items>.*?); do\n\s*if \[ -e \"\$HERMES_HOME/\$sub\" \]",
text,
re.DOTALL,
)
assert m, "stage2-hook.sh must contain the targeted subdir chown loop"
return m.group("items").split()
def test_targeted_chown_covers_legacy_and_new_pairing_dirs(stage2_text: str) -> None:
subdirs = _targeted_chown_subdirs(stage2_text)
assert "pairing" in subdirs
assert "platforms/pairing" in subdirs
def test_seeded_directory_list_covers_legacy_and_new_pairing_dirs(stage2_text: str) -> None:
seed_block = stage2_text.split("as_hermes mkdir -p \\", 1)[1].split(
"# --- Install-method stamp",
1,
)[0]
assert '"$HERMES_HOME/pairing"' in seed_block
assert '"$HERMES_HOME/platforms/pairing"' in seed_block

119
tests/tools/test_stage2_hook_user_flag_guard.py
View file

@ -1,119 +0,0 @@
"""Contract test: the s6-overlay stage2 hook and main-wrapper reject an
unsupported `docker run --user <arbitrary-uid>:<gid>` start with actionable
guidance, while still allowing:
- root start (id -u == 0)
- `--user <hermes-uid>` (the supported non-root start, #34648 / #34837)
Background: in the tini era `docker run --user $(id -u):$(id -g)` was used to
make container-written files match the host user. Under s6-overlay this can't
work — the bootstrap (UID remap, volume/build-tree chown, config seeding) needs
root, and the baked image dirs are owned by the hermes build UID, so an
arbitrary pinned UID can't write them (EACCES on a bind mount, hard crash on a
named volume). The supported path is root start + HERMES_UID/HERMES_GID (or the
PUID/PGID aliases), which remaps the hermes user and chowns the volume.
The guard fires only when the current UID is neither root NOR the hermes UID,
so the #34648 `--user 10000:10000` case (pinning to the hermes UID itself) is
unaffected.
Extraction + stubbed-shell-run mirrors
tests/tools/test_stage2_hook_toplevel_chown.py.
"""
from __future__ import annotations
import re
import shutil
import subprocess
import tempfile
from pathlib import Path
import pytest
REPO_ROOT = Path(__file__).resolve().parents[2]
STAGE2_HOOK = REPO_ROOT / "docker" / "stage2-hook.sh"
MAIN_WRAPPER = REPO_ROOT / "docker" / "main-wrapper.sh"
def _read(p: Path) -> str:
if not p.exists():
pytest.skip(f"{p} not present in this checkout")
return p.read_text()
def _guard_block(text: str) -> str:
"""Extract the `cur_uid=...; if [ ... ]; then ... exit 1; fi` guard."""
m = re.search(
r"(cur_uid=\"\$\(id -u\)\"\nif \[ \"\$cur_uid\" != 0 \](?:.*\n)*?fi)",
text,
)
assert m, "expected the --user guard block (cur_uid + non-root/non-hermes check)"
return m.group(1)
@pytest.mark.parametrize("path", [STAGE2_HOOK, MAIN_WRAPPER])
def test_guard_present_and_mentions_remediation(path: Path) -> None:
text = _read(path)
block = _guard_block(text)
# Must check non-root AND non-hermes-uid (so --user 10000:10000 is allowed).
assert '"$cur_uid" != 0' in block
assert '"$cur_uid" != "$(id -u hermes)"' in block
assert "exit 1" in block
# Must point users at the supported env vars.
assert "HERMES_UID" in block and "HERMES_GID" in block
assert "PUID" in block and "PGID" in block
def _run_guard(text: str, *, cur_uid: int, hermes_uid: int = 10000) -> subprocess.CompletedProcess:
"""Run the extracted guard with `id` stubbed. Returns the completed process
(rc 1 + stderr message when rejected, rc 0 when allowed through)."""
bash = shutil.which("bash")
if bash is None:
pytest.skip("bash not available")
block = _guard_block(text)
with tempfile.TemporaryDirectory() as d:
script = (
"set -e\n"
# Stub `id`: `id -u` -> cur_uid; `id -u hermes` -> hermes_uid.
f'id() {{ if [ "$2" = hermes ]; then echo {hermes_uid}; else echo {cur_uid}; fi; }}\n'
+ block
+ "\necho GUARD_PASSED\n" # only reached when the guard allows through
)
sp = Path(d) / "h.sh"
sp.write_text(script)
return subprocess.run([bash, str(sp)], capture_output=True, text=True)
def test_arbitrary_user_uid_is_rejected() -> None:
"""An arbitrary host UID (1000), neither root nor hermes, is rejected."""
for text in (_read(STAGE2_HOOK), _read(MAIN_WRAPPER)):
proc = _run_guard(text, cur_uid=1000, hermes_uid=10000)
assert proc.returncode == 1, f"expected rejection, got rc={proc.returncode}"
assert "not supported" in proc.stderr
assert "GUARD_PASSED" not in proc.stdout
def test_root_start_passes() -> None:
"""Root start (uid 0) is never blocked."""
for text in (_read(STAGE2_HOOK), _read(MAIN_WRAPPER)):
proc = _run_guard(text, cur_uid=0, hermes_uid=10000)
assert proc.returncode == 0, proc.stderr
assert "GUARD_PASSED" in proc.stdout
def test_user_pinned_to_hermes_uid_passes() -> None:
"""`--user 10000:10000` (the hermes UID itself) is the supported non-root
start from #34648 / #34837 and must NOT be blocked."""
for text in (_read(STAGE2_HOOK), _read(MAIN_WRAPPER)):
proc = _run_guard(text, cur_uid=10000, hermes_uid=10000)
assert proc.returncode == 0, proc.stderr
assert "GUARD_PASSED" in proc.stdout
def test_user_pinned_to_remapped_hermes_uid_passes() -> None:
"""After a HERMES_UID remap the hermes UID is e.g. 4242; a container pinned
to that same UID must still pass (cur_uid == hermes_uid)."""
for text in (_read(STAGE2_HOOK), _read(MAIN_WRAPPER)):
proc = _run_guard(text, cur_uid=4242, hermes_uid=4242)
assert proc.returncode == 0, proc.stderr
assert "GUARD_PASSED" in proc.stdout