diff --git a/README.md b/README.md index 5c641f2..da46e7a 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ uv run nix2cf buildfile \ `--platform` (`macos` or `linux`) and `--supervisor` (`launchd`, `systemd`, `runit` or `nixos`) are both required and have no default. It is written into the goal file's `device-trust.entries.supervisor`; a `--device-trust` document that already carries a different `supervisor` is -refused. The output is **schema_version 4** (tendcf's `goal-file.schema.json`); +refused. The output is **schema_version 5** (tendcf's `goal-file.schema.json`); CI fails when `GOAL_FILE_SCHEMA_VERSION` and tendcf's schema const differ. That prints the host's **goal file**: the canonical (RFC 8785, no trailing diff --git a/docs/DESIGN.md b/docs/DESIGN.md index bc08a9b..c5438b9 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -100,8 +100,9 @@ Each of these is marked `TODO(operator)` in `nix2cf/compile.py` at the spot. | `supervisor` | A required host input (`--supervisor launchd\|systemd\|runit\|nixos`) next to `platform`, **no default** (house rule; spec Q1/Q8). Written into `device-trust.entries.supervisor` as `{"host":{"name":X,"state":"present"}}`. A supplied `device-trust` document whose `supervisor` entry differs is refused; one that omits it is fine. | No inventory schema exists (spec Q8); the flag goes when it does. | | Platform ↔ supervisor | `macos` has `launchd`; `linux` has `systemd`, `runit` or `nixos`; any other pairing, and `android`, is refused. | Not in the spec. Android/Termux is deferred (linux-targets ruling 2026-10-29), so `android` is refused rather than mapped to runit. | | `nixos` host | Any selected service is refused ("host is nixos-supervised; its units are the Nix configuration's"). With none, the goal file carries `supervision: {"coverage": "deliberately-unmanaged"}` and no unit-writer registry; tendcf's projector reads it as `{"vars":{}}`. | Spec §6.2 item 3, Q3. | -| Older `schema_version` | Library only (`compile_host(..., schema_version=N)`): 3 renders without the `supervisor` entry; a `nixos` host is refused below 4; anything else is refused. The CLI always renders the current version, and an older file is not schema-validated (tendcf's schema is a const). | Spec §6.2 item 6. | -| Tombstones | Cannot be rendered: the Site Model has no way to say "absent". | Goal file supports them; the Site Model does not yet. | +| Older `schema_version` | Library only (`compile_host(..., schema_version=N)`): 3 renders without the `supervisor` entry; 4 renders, for inputs valid under the current Site Model contract, the same file as the current version bar the number. That is not a migration claim for arbitrary historical v4 output: v4 permitted `dpkg` unit-writer claims, which v5 rejects. A `nixos` host is refused below 4; anything else is refused. The CLI always renders the current version, and an older file is not schema-validated (tendcf's schema is a const). | Spec §6.2 item 6; schema-v5 spec §4 items 1 and 11. | +| Unit-writer keys (schema v5) | Only launchd prefixes are emitted (from `launchd-writers.yml`, `^[a-z][a-z0-9]*(\.[A-Za-z0-9][A-Za-z0-9_-]*)+\.\*$`, the v4 language launchd and runit keep). No exact/template key, no `unit-package`, no `tendcf-install`. Schema-validated v5 output carries no `dpkg` writer (retired in v5: the writers schema and the goal-file schema both refuse it); the renderer copies declared writers unchanged, so an old Site Model with one still renders at v4 (unvalidated) and is refused at v5. A systemd host gets no `supervision` domain (its renderer is not built), so the "systemd prefix must be cfengine" rule has nothing to apply to. | Schema-v5 spec §2.1, §7 item 12: the Site Model has no systemd writer registry. | +| Tombstones | Cannot be rendered: the Site Model has no way to say "absent". So the v5 rules that a tombstone sit under a same-domain `cfengine` claim and that no unit be present in one domain and absent in another cannot fire on nix2cf output. | Goal file supports them; the Site Model does not yet. | ## Conflict check (stage 2) diff --git a/nix2cf/compile.py b/nix2cf/compile.py index b547e7a..801dfe4 100644 --- a/nix2cf/compile.py +++ b/nix2cf/compile.py @@ -39,18 +39,26 @@ # Must equal the `const` of `tendcf/schema/goal-file.schema.json` # `schema_version`; CI fails when it does not (.github/workflows/check.yml). -GOAL_FILE_SCHEMA_VERSION = 4 +GOAL_FILE_SCHEMA_VERSION = 5 # `supervisor` entered the device-trust domain at v4 (schema-v4 spec §2.1). # The `nixos` host exists only from v4 on (spec §6.2 item 6): the one v3 # spelling, a `nixos` unit-writer, described nothing. SUPERVISOR_SCHEMA_VERSION = 4 -# Older versions this compiler can still state. The launchd shape did not -# change between v1 and v4; only v3 and v4 are claimed, because v3 is the one -# the spec names ("Non-nixos hosts may render at 3 by dropping the entry"). +# Older versions this compiler can still state: 3 and 4. For inputs valid +# under the current Site Model contract, rendering at v4 and v5 differs only +# in `schema_version` (v5 changed the unit-writer key language, which is a +# superset of every launchd prefix nix2cf emits, retired the `dpkg` writer and +# added `tendcf-install` and `unit-package`), and v3 differs by lacking the +# `supervisor` entry. This does not establish migration compatibility for +# arbitrary historical v4 output: v4 permitted `dpkg` unit-writer claims, +# which v5 rejects. Older-version output is never schema-validated. The spec +# names no downgrade path at v5 and no device holds a baseline (spec §4 item +# 1); 3 and 4 stay as the shapes a not-yet-migrated device could still hold. # The current version is derived, so a bump of GOAL_FILE_SCHEMA_VERSION cannot -# leave the renderer refusing its own version. The literal 3 is NOT derived: -# re-justify it (is v3 still a shape a device may hold?) at every bump. -SUPPORTED_SCHEMA_VERSIONS = (3, GOAL_FILE_SCHEMA_VERSION) +# leave the renderer refusing its own version. The literals 3 and 4 are NOT +# derived: re-justify them (is that still a shape a device may hold?) at every +# bump. +SUPPORTED_SCHEMA_VERSIONS = (3, 4, GOAL_FILE_SCHEMA_VERSION) # The one state domain the reference projector reads # (`tendcf/bin/projector.py:PROJECTING_DOMAIN`). The Site Model's own domain diff --git a/tests/golden/example-site_mac.goal-file.json b/tests/golden/example-site_mac.goal-file.json index 2ba357e..e5423a8 100644 --- a/tests/golden/example-site_mac.goal-file.json +++ b/tests/golden/example-site_mac.goal-file.json @@ -1 +1 @@ -{"domains":{"device-trust":{"coverage":"comprehensive","entries":{"advisor-key":{"ed25519:b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2":{"state":"present"}},"agent":{"tendcf-agent":{"sha256":"sha256:d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4","state":"present","version":"ops-v1.0.0"}},"policy-tree":{"tree":{"sha256":"sha256:c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3","state":"present"}},"supervisor":{"host":{"name":"launchd","state":"present"}},"trust-policy":{"consent":{"local_yes_required":true,"state":"present","tier":"consented"}}}},"supervision":{"coverage":"comprehensive","entries":{"interlock":{"tailscale-authenticated-before-lockdown":{"blocks":"enclosing-bundle","bundle":"fleet-vpn","defines_class":"tailscale_authenticated","pre_action":{"command":["tailscale","status","--json"],"expect_exit":0,"timeout_seconds":15},"report":true,"state":"present"}},"service":{"com.djbclark.caddy":{"bundle":"edge-http","command":["/opt/homebrew/bin/caddy","run","--config","/etc/caddy/Caddyfile"],"run_as":"djbclark","state":"present","unit":{"launchd":{"keep_alive":true,"run_at_load":true}},"working_dir":"/"},"com.djbclark.litellm":{"bundle":"edge-http","command":["/opt/homebrew/bin/litellm","--config","/etc/litellm/config.yaml"],"env":{"LITELLM_MASTER_KEY":"LITELLM_MASTER_KEY","OPENAI_API_KEY":"OPENAI_API_KEY"},"run_as":"djbclark","state":"present","unit":{"launchd":{"keep_alive":false,"run_at_load":false}},"working_dir":"/"},"org.tendcf.tailscaled":{"bundle":"fleet-vpn","command":["/usr/local/bin/tailscaled"],"run_as":"root","state":"present","unit":{"launchd":{"keep_alive":false,"run_at_load":false}},"working_dir":"/"}},"unit-writer":{"com.apple.*":{"state":"present","writer":"apple"},"com.djbclark.*":{"state":"present","writer":"cfengine"},"dev.mise.*":{"state":"present","writer":"mise"},"org.nixos.*":{"state":"present","writer":"nix-darwin"},"org.tendcf.*":{"state":"present","writer":"cfengine"}}}}},"host":"ed25519:a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1","schema_version":4} \ No newline at end of file +{"domains":{"device-trust":{"coverage":"comprehensive","entries":{"advisor-key":{"ed25519:b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2":{"state":"present"}},"agent":{"tendcf-agent":{"sha256":"sha256:d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4","state":"present","version":"ops-v1.0.0"}},"policy-tree":{"tree":{"sha256":"sha256:c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3","state":"present"}},"supervisor":{"host":{"name":"launchd","state":"present"}},"trust-policy":{"consent":{"local_yes_required":true,"state":"present","tier":"consented"}}}},"supervision":{"coverage":"comprehensive","entries":{"interlock":{"tailscale-authenticated-before-lockdown":{"blocks":"enclosing-bundle","bundle":"fleet-vpn","defines_class":"tailscale_authenticated","pre_action":{"command":["tailscale","status","--json"],"expect_exit":0,"timeout_seconds":15},"report":true,"state":"present"}},"service":{"com.djbclark.caddy":{"bundle":"edge-http","command":["/opt/homebrew/bin/caddy","run","--config","/etc/caddy/Caddyfile"],"run_as":"djbclark","state":"present","unit":{"launchd":{"keep_alive":true,"run_at_load":true}},"working_dir":"/"},"com.djbclark.litellm":{"bundle":"edge-http","command":["/opt/homebrew/bin/litellm","--config","/etc/litellm/config.yaml"],"env":{"LITELLM_MASTER_KEY":"LITELLM_MASTER_KEY","OPENAI_API_KEY":"OPENAI_API_KEY"},"run_as":"djbclark","state":"present","unit":{"launchd":{"keep_alive":false,"run_at_load":false}},"working_dir":"/"},"org.tendcf.tailscaled":{"bundle":"fleet-vpn","command":["/usr/local/bin/tailscaled"],"run_as":"root","state":"present","unit":{"launchd":{"keep_alive":false,"run_at_load":false}},"working_dir":"/"}},"unit-writer":{"com.apple.*":{"state":"present","writer":"apple"},"com.djbclark.*":{"state":"present","writer":"cfengine"},"dev.mise.*":{"state":"present","writer":"mise"},"org.nixos.*":{"state":"present","writer":"nix-darwin"},"org.tendcf.*":{"state":"present","writer":"cfengine"}}}}},"host":"ed25519:a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1","schema_version":5} \ No newline at end of file diff --git a/tests/golden/nixos-get.goal-file.json b/tests/golden/nixos-get.goal-file.json index 48453ed..0862897 100644 --- a/tests/golden/nixos-get.goal-file.json +++ b/tests/golden/nixos-get.goal-file.json @@ -1 +1 @@ -{"domains":{"device-trust":{"coverage":"comprehensive","entries":{"advisor-key":{"ed25519:b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2":{"state":"present"}},"agent":{"tendcf-agent":{"sha256":"sha256:d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4","state":"present","version":"ops-v1.0.0"}},"policy-tree":{"tree":{"sha256":"sha256:c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3","state":"present"}},"supervisor":{"host":{"name":"nixos","state":"present"}},"trust-policy":{"consent":{"local_yes_required":true,"state":"present","tier":"consented"}}}},"supervision":{"coverage":"deliberately-unmanaged"}},"host":"ed25519:a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1","schema_version":4} \ No newline at end of file +{"domains":{"device-trust":{"coverage":"comprehensive","entries":{"advisor-key":{"ed25519:b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2":{"state":"present"}},"agent":{"tendcf-agent":{"sha256":"sha256:d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4","state":"present","version":"ops-v1.0.0"}},"policy-tree":{"tree":{"sha256":"sha256:c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3","state":"present"}},"supervisor":{"host":{"name":"nixos","state":"present"}},"trust-policy":{"consent":{"local_yes_required":true,"state":"present","tier":"consented"}}}},"supervision":{"coverage":"deliberately-unmanaged"}},"host":"ed25519:a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1","schema_version":5} \ No newline at end of file diff --git a/tests/golden/tendcf-examples_mac.goal-file.json b/tests/golden/tendcf-examples_mac.goal-file.json index 53c41e4..c5fe73d 100644 --- a/tests/golden/tendcf-examples_mac.goal-file.json +++ b/tests/golden/tendcf-examples_mac.goal-file.json @@ -1 +1 @@ -{"domains":{"device-trust":{"coverage":"comprehensive","entries":{"advisor-key":{"ed25519:b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2":{"state":"present"}},"agent":{"tendcf-agent":{"sha256":"sha256:d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4","state":"present","version":"ops-v1.0.0"}},"policy-tree":{"tree":{"sha256":"sha256:c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3","state":"present"}},"supervisor":{"host":{"name":"launchd","state":"present"}},"trust-policy":{"consent":{"local_yes_required":true,"state":"present","tier":"consented"}}}},"supervision":{"coverage":"comprehensive","entries":{"service":{"com.djbclark.caddy":{"bundle":"edge-http","command":["/opt/homebrew/bin/caddy","run","--config","/etc/caddy/Caddyfile"],"run_as":"djbclark","state":"present","unit":{"launchd":{"keep_alive":true,"run_at_load":true}},"working_dir":"/"},"com.djbclark.litellm":{"bundle":"edge-http","command":["/opt/homebrew/bin/litellm","--config","/etc/litellm/config.yaml"],"env":{"LITELLM_MASTER_KEY":"LITELLM_MASTER_KEY","OPENAI_API_KEY":"OPENAI_API_KEY"},"run_as":"djbclark","state":"present","unit":{"launchd":{"keep_alive":false,"run_at_load":false}},"working_dir":"/"}},"unit-writer":{"com.apple.*":{"state":"present","writer":"apple"},"com.djbclark.*":{"state":"present","writer":"cfengine"},"dev.mise.*":{"state":"present","writer":"mise"},"org.nixos.*":{"state":"present","writer":"nix-darwin"},"org.tendcf.*":{"state":"present","writer":"cfengine"}}}}},"host":"ed25519:a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1","schema_version":4} \ No newline at end of file +{"domains":{"device-trust":{"coverage":"comprehensive","entries":{"advisor-key":{"ed25519:b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2":{"state":"present"}},"agent":{"tendcf-agent":{"sha256":"sha256:d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4","state":"present","version":"ops-v1.0.0"}},"policy-tree":{"tree":{"sha256":"sha256:c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3","state":"present"}},"supervisor":{"host":{"name":"launchd","state":"present"}},"trust-policy":{"consent":{"local_yes_required":true,"state":"present","tier":"consented"}}}},"supervision":{"coverage":"comprehensive","entries":{"service":{"com.djbclark.caddy":{"bundle":"edge-http","command":["/opt/homebrew/bin/caddy","run","--config","/etc/caddy/Caddyfile"],"run_as":"djbclark","state":"present","unit":{"launchd":{"keep_alive":true,"run_at_load":true}},"working_dir":"/"},"com.djbclark.litellm":{"bundle":"edge-http","command":["/opt/homebrew/bin/litellm","--config","/etc/litellm/config.yaml"],"env":{"LITELLM_MASTER_KEY":"LITELLM_MASTER_KEY","OPENAI_API_KEY":"OPENAI_API_KEY"},"run_as":"djbclark","state":"present","unit":{"launchd":{"keep_alive":false,"run_at_load":false}},"working_dir":"/"}},"unit-writer":{"com.apple.*":{"state":"present","writer":"apple"},"com.djbclark.*":{"state":"present","writer":"cfengine"},"dev.mise.*":{"state":"present","writer":"mise"},"org.nixos.*":{"state":"present","writer":"nix-darwin"},"org.tendcf.*":{"state":"present","writer":"cfengine"}}}}},"host":"ed25519:a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1","schema_version":5} \ No newline at end of file diff --git a/tests/test_compile.py b/tests/test_compile.py index 7b02a90..a3ae8f7 100644 --- a/tests/test_compile.py +++ b/tests/test_compile.py @@ -120,7 +120,7 @@ def test_site_model_inputs_validate(schemas: Schemas) -> None: def test_example_site_mac_golden(schemas: Schemas) -> None: result = compile_host(_model(SITE), _host(SITE), schemas) doc = result.goal_file - assert doc["schema_version"] == 4 + assert doc["schema_version"] == GOAL_FILE_SCHEMA_VERSION == 5 assert doc["host"] == HOST_KEY assert doc["domains"]["device-trust"]["entries"]["supervisor"] == {"host": {"name": "launchd", "state": "present"}} sup = doc["domains"]["supervision"] @@ -302,7 +302,7 @@ def test_nixos_host_without_services_is_deliberately_unmanaged(tendcf: Path, sch # no-op on a file with no entries): drift in either repo shows up here. assert result.canonical == (tendcf / "deploy" / "linux" / "passthrough" / "goal-file.json").read_bytes() doc = result.goal_file - assert doc["schema_version"] == 4 + assert doc["schema_version"] == GOAL_FILE_SCHEMA_VERSION == 5 assert doc["domains"]["supervision"] == {"coverage": "deliberately-unmanaged"} assert doc["domains"]["device-trust"]["entries"]["supervisor"] == {"host": {"name": "nixos", "state": "present"}} assert set(doc["domains"]) == {"device-trust", "supervision"} # no unit-writer registry travels @@ -358,6 +358,49 @@ def test_schema_v3_with_schema_is_noted_not_validated(schemas: Schemas) -> None: assert any("NOT validated" in d for d in result.diagnostics) +def _host_shapes() -> dict[str, HostSpec]: + """Every host shape nix2cf renders: a launchd host with services, a nixos + host, and service-free systemd and runit hosts (their unit renderers are not + built, so a selected service is refused; none selected renders the supervisor + entry alone).""" + return { + "launchd": _host(SITE), + "nixos": _nixos_host(), + "systemd": _host(SITE, name="get", platform="linux", supervisor="systemd", trust=_trust(SITE, None)), + "runit": _host(SITE, name="get", platform="linux", supervisor="runit", trust=_trust(SITE, None)), + } + + +@pytest.mark.parametrize("shape", ["launchd", "nixos", "systemd", "runit"]) +def test_schema_v4_and_v5_differ_only_in_the_version_for_current_inputs(schemas: Schemas, shape: str) -> None: + """For inputs valid under the current Site Model contract, the v4 file is the + current file with the old version number, for every host shape. The v5 file is + validated against tendcf's schemas (the v4 file cannot be: the schema is a + const). Not a claim about arbitrary historical v4 output: see + test_dpkg_writer_renders_at_v4_but_is_refused_at_v5.""" + host = _host_shapes()[shape] + old = compile_host(_model(SITE), host, None, schema_version=4).goal_file + new = compile_host(_model(SITE), host, schemas).goal_file # validates against the v5 schema + assert old["schema_version"] == 4 and new["schema_version"] == 5 + assert new["domains"]["device-trust"]["entries"]["supervisor"]["host"]["name"] == host.supervisor + assert {**old, "schema_version": 5} == new + assert schemas.errors("goal-file.schema.json", new) == [] + + +def test_dpkg_writer_renders_at_v4_but_is_refused_at_v5(schemas: Schemas) -> None: + """`dpkg` left the unit-writer enum in v5 (a package claim is its only spelling). + v4 permitted it, so an unused `dpkg` writer in an old Site Model still renders + at v4 (unvalidated, as every older version is) and is refused at v5.""" + model = _model(SITE) + writer = next(w for w in model.launchd_writers.data["writers"] if w["prefix"] == "dev.mise.*") + writer["writer"] = "dpkg" + assert validate_site_model(model, schemas) != [] # launchd-writers.schema.json dropped it too + old = compile_host(model, _host(SITE), None, schema_version=4).goal_file + assert old["domains"]["supervision"]["entries"]["unit-writer"]["dev.mise.*"]["writer"] == "dpkg" + with pytest.raises(CompileError, match="dpkg"): + compile_host(model, _host(SITE), schemas) + + def test_render_goal_file_alone_refuses_nixos_below_v4() -> None: from nix2cf.compile import render_goal_file @@ -388,7 +431,7 @@ def test_cli_platform_is_required_and_android_not_offered(tendcf: Path) -> None: def test_unsupported_schema_version_refused() -> None: with pytest.raises(CompileError, match="not one this compiler renders"): - compile_host(_model(SITE), _host(SITE), None, schema_version=5) + compile_host(_model(SITE), _host(SITE), None, schema_version=GOAL_FILE_SCHEMA_VERSION + 1) # --- conflict check -------------------------------------------------------------