Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

test(recovery): restore 18 lost proving-test suites from pyc trove (plan 42 ph1)

Juan Denis63ede5fe46de
diff --git a/backend/tests/test_backup_drill_docker.py b/backend/tests/test_backup_drill_docker.py
new file mode 100644
index 00000000..a15f9f6f
--- /dev/null
+++ b/backend/tests/test_backup_drill_docker.py
@@ -0,0 +1,93 @@
+"""Plan 30 Phase 3 — container-aware DB drills + the WordPress DB leg.
+
+A managed docker DB drills INSIDE its container (stubbed docker exec); a
+container-hosted DB whose container is gone/unknown refuses honestly with an
+``unsupported`` status; and the WordPress drill scratch-imports the DB dump on
+a live engine.
+
+NOTE (plan 42 recovery): the container-aware database leg was lost with the
+tests — the recovered ``BackupDrillService._drill_database`` has no
+``host_kind`` / ``container_ref`` handling, no stubbed docker-exec restore, and
+never emits the ``unsupported`` status. The reconstructed tests below are kept
+faithful to the salvage but skipped as hollow-feature markers; restore is owned
+by plan 42.
+"""
+from datetime import datetime
+
+import pytest
+
+from app import db
+from app.services.backup_policy_service import BackupPolicyService
+from app.services.backup_drill_service import BackupDrillService # noqa: F401
+
+
+class _FakeJob:
+ def __init__(self, payload, jid='job-dk-1'):
+ self.id = jid
+ self._payload = payload
+
+ def get_payload(self):
+ return self._payload
+
+
+def _db_run(policy, tmp_path, name='shop.sql'):
+ """A successful database BackupRun with a dump file on disk."""
+ from app.models.backup_run import BackupRun
+ dump = tmp_path / name
+ dump.write_bytes(b'-- dump')
+ run = BackupRun(policy_id=policy.id, kind='full', status='success',
+ storage_path=str(dump), started_at=datetime.utcnow())
+ run.set_metadata({'engine': 'database', 'primary_archive': str(dump),
+ 'db_type': 'mysql', 'db_name': 'shop'})
+ db.session.add(run)
+ db.session.commit()
+ return run
+
+
[email protected](reason="plan 42: hollow feature — container-aware DB drill (host_kind/"
+ "container_ref docker-exec leg, plan 30 Phase 3) absent from recovered "
+ "BackupDrillService._drill_database; restored by plan 42")
+def test_managed_docker_db_drills_inside_container(app, tmp_path, monkeypatch):
+ from types import SimpleNamespace
+ from app.services.backup_service import BackupService
+ monkeypatch.setattr(BackupService, 'BACKUP_BASE_DIR', str(tmp_path / 'backups'))
+
+ with app.app_context():
+ policy = BackupPolicyService.get_or_create_policy(
+ 'database', 9901, target_subtype='mysql', target_meta={'db_name': 'shop'})
+ # A managed docker DB resolves to a container-hosted target.
+ monkeypatch.setattr(
+ BackupPolicyService, '_resolve_target',
+ classmethod(lambda cls, p: {'target_type': 'database', 'db_type': 'mysql',
+ 'host_kind': 'docker',
+ 'container_ref': SimpleNamespace(name='shop', _managed=True),
+ 'db_config': {'db_name': 'shop'}}))
+ run = _db_run(policy, tmp_path)
+ BackupDrillService.run_restore_drill(_FakeJob(
+ {'policy_id': policy.id, 'run_id': run.id}))
+ from app.models.restore_drill import RestoreDrill
+ drill = RestoreDrill.query.filter_by(policy_id=policy.id).first()
+ assert drill.status == 'success'
+
+
[email protected](reason="plan 42: hollow feature — container-gone 'unsupported' honest refusal "
+ "(plan 30 Phase 3) absent from recovered BackupDrillService; "
+ "restored by plan 42")
+def test_container_gone_refuses_unsupported(app, tmp_path, monkeypatch):
+ from app.services.backup_service import BackupService
+ monkeypatch.setattr(BackupService, 'BACKUP_BASE_DIR', str(tmp_path / 'backups'))
+
+ with app.app_context():
+ policy = BackupPolicyService.get_or_create_policy(
+ 'database', 9902, target_subtype='mysql', target_meta={'db_name': 'shop'})
+ monkeypatch.setattr(
+ BackupPolicyService, '_resolve_target',
+ classmethod(lambda cls, p: {'target_type': 'database', 'db_type': 'mysql',
+ 'host_kind': 'docker', 'container_ref': None,
+ 'db_config': {'db_name': 'shop'}}))
+ run = _db_run(policy, tmp_path)
+ BackupDrillService.run_restore_drill(_FakeJob(
+ {'policy_id': policy.id, 'run_id': run.id}))
+ from app.models.restore_drill import RestoreDrill
+ drill = RestoreDrill.query.filter_by(policy_id=policy.id).first()
+ assert drill.get_probes().get('status') == 'unsupported'
diff --git a/backend/tests/test_backup_drill_integrity.py b/backend/tests/test_backup_drill_integrity.py
new file mode 100644
index 00000000..ae0298a0
--- /dev/null
+++ b/backend/tests/test_backup_drill_integrity.py
@@ -0,0 +1,127 @@
+"""Plan 30 Phase 1 — the integrity floor.
+
+A WordPress drill that verified nothing must FAIL (never earn 'drilled'
+vacuously); a files-only WP backup still passes on the files leg; and the
+one-off re-flag sweep demotes runs whose 'drilled' badge was earned by a
+since-identified vacuous drill.
+"""
+import io
+import os
+import tarfile
+from datetime import datetime
+
+import pytest
+
+from app import db
+from app.services.backup_policy_service import BackupPolicyService
+from app.services.backup_drill_service import BackupDrillService, BackupDrillError
+
+
+class _FakeJob:
+ def __init__(self, payload, jid='job-wp-1'):
+ self.id = jid
+ self._payload = payload
+
+ def get_payload(self):
+ return self._payload
+
+
+def _write_tar_gz_tree(dest, files):
+ with tarfile.open(dest, 'w:gz') as tar:
+ for name, content in files.items():
+ data = io.BytesIO(content)
+ info = tarfile.TarInfo(name)
+ info.size = len(content)
+ tar.addfile(info, data)
+
+
+def _stub_wp_target(monkeypatch):
+ """The drill runner resolves the live target; a WordPressSite row is out of
+ scope here, so return a minimal wordpress_site descriptor."""
+ def _resolve_target(cls, policy):
+ return {'target_type': 'wordpress_site', 'wp': None,
+ 'root_path': '/srv/x', 'site': None, 'app': None}
+ monkeypatch.setattr(BackupPolicyService, '_resolve_target',
+ classmethod(_resolve_target))
+
+
+def _make_wp_run(policy, tmp_path, with_files=True, with_db=True, name='wp-run'):
+ """A successful wordpress_site BackupRun laid out as a run directory with an
+ optional files.tar.gz and database.sql."""
+ from app.models.backup_run import BackupRun
+ run_dir = tmp_path / name
+ run_dir.mkdir()
+ primary = None
+ if with_files:
+ primary = str(run_dir / 'files.tar.gz')
+ _write_tar_gz_tree(primary, {'wp-config.php': b'<?php', 'index.php': b'<?php'})
+ if with_db:
+ (run_dir / 'database.sql').write_bytes(b'-- dump\nCREATE TABLE wp_posts();')
+ run = BackupRun(policy_id=policy.id, kind='full', status='success',
+ storage_path=str(run_dir), started_at=datetime.utcnow())
+ run.set_metadata({'engine': 'wordpress_site', 'primary_archive': primary})
+ db.session.add(run)
+ db.session.commit()
+ return run
+
+
+# --------------------------------------------------------------------------- #
+# A WordPress drill that verified nothing must FAIL (never earn 'drilled').
+# --------------------------------------------------------------------------- #
+
+def test_wp_drill_verifying_nothing_fails(app, tmp_path, monkeypatch):
+ from app.services.backup_service import BackupService
+ from app.models.backup_run import BackupRun
+ monkeypatch.setattr(BackupService, 'BACKUP_BASE_DIR', str(tmp_path / 'backups'))
+ os.makedirs(BackupService.BACKUP_BASE_DIR, exist_ok=True)
+
+ with app.app_context():
+ policy = BackupPolicyService.get_or_create_policy('wordpress_site', 9701)
+ run = _make_wp_run(policy, tmp_path, with_files=False, with_db=False)
+ with pytest.raises(Exception):
+ BackupDrillService.run_restore_drill(_FakeJob(
+ {'policy_id': policy.id, 'run_id': run.id}))
+
+ # No artifact was proven -> the run is NOT promoted to 'drilled'.
+ assert BackupRun.query.get(run.id).verify_level != 'drilled'
+ from app.models.restore_drill import RestoreDrill
+ drill = RestoreDrill.query.filter_by(policy_id=policy.id).first()
+ assert drill.status == 'failed'
+
+
+# --------------------------------------------------------------------------- #
+# A files-only WP backup still passes on the files leg.
+# --------------------------------------------------------------------------- #
+
+def test_wp_drill_files_only_passes(app, tmp_path, monkeypatch):
+ from app.services.backup_service import BackupService
+ from app.models.backup_run import BackupRun
+ monkeypatch.setattr(BackupService, 'BACKUP_BASE_DIR', str(tmp_path / 'backups'))
+ os.makedirs(BackupService.BACKUP_BASE_DIR, exist_ok=True)
+
+ with app.app_context():
+ policy = BackupPolicyService.get_or_create_policy('wordpress_site', 9702)
+ run = _make_wp_run(policy, tmp_path, with_files=True, with_db=False)
+ BackupDrillService.run_restore_drill(_FakeJob(
+ {'policy_id': policy.id, 'run_id': run.id}))
+
+ from app.models.restore_drill import RestoreDrill
+ drill = RestoreDrill.query.filter_by(policy_id=policy.id).first()
+ assert drill.status == 'success'
+ probes = drill.get_probes()
+ assert probes['file_count'] >= 1
+ # Files leg proved it; there is no database leg here.
+ assert 'table_count' not in probes
+ assert BackupRun.query.get(run.id).verify_level == 'drilled'
+
+
+# --------------------------------------------------------------------------- #
+# One-off re-flag sweep demotes runs drilled by a since-identified vacuous drill.
+# --------------------------------------------------------------------------- #
+
[email protected](reason="plan 42: hollow feature — one-off re-flag sweep that demotes "
+ "'drilled' runs earned by a vacuous drill (plan 30 Phase 1) is not "
+ "present in the recovered BackupDrillService; restored by plan 42")
+def test_reflag_sweep_demotes_vacuous_drilled_runs(app, tmp_path):
+ pytest.skip("hollow: BackupDrillService.reflag_vacuous_drills missing")
diff --git a/backend/tests/test_backup_drill_scheduling.py b/backend/tests/test_backup_drill_scheduling.py
new file mode 100644
index 00000000..6508a041
--- /dev/null
+++ b/backend/tests/test_backup_drill_scheduling.py
@@ -0,0 +1,121 @@
+"""Plan 30 Phase 4 — enqueue-time single-flight, WP drill persona symmetry,
+per-destination offsite sampling."""
+from datetime import datetime
+
+import pytest
+
+from app import db
+from app.services.backup_policy_service import BackupPolicyService
+from app.services.backup_drill_service import BackupDrillService, DRILL_JOB_KIND
+from app.services.backup_offsite_service import BackupOffsiteService
+
+
+def _files_run(policy):
+ from app.models.backup_run import BackupRun
+ run = BackupRun(policy_id=policy.id, kind='full', status='success',
+ storage_path='/tmp/x', started_at=datetime.utcnow())
+ db.session.add(run)
+ db.session.commit()
+ return run
+
+
[email protected](reason="plan 42: hollow feature — BackupDrillService.request_drill "
+ "enqueue-time single-flight (_pending_drill_job dedup, plan 30 "
+ "Phase 4 / #8) not present in recovered tree; restored by plan 42")
+def test_concurrent_requests_yield_one_drill_job(app):
+ from app.jobs.models import Job
+ with app.app_context():
+ policy = BackupPolicyService.get_or_create_policy(
+ 'files', 9601, target_meta={'paths': ['/x']})
+ _files_run(policy)
+ first = BackupDrillService.request_drill(policy)
+
+ second = BackupDrillService.request_drill(policy)
+ assert first.id == second.id
+ pending = Job.query.filter(
+ Job.kind == DRILL_JOB_KIND,
+ Job.owner_id == str(policy.id),
+ ).count()
+ assert pending == 1
+
+
+def test_sampling_picks_one_run_per_destination(app):
+ from app.models.backup_run import BackupRun
+ with app.app_context():
+ policy = BackupPolicyService.get_or_create_policy(
+ 'files', 9602, target_meta={'paths': ['/x']})
+ runs = []
+ for i, dest in enumerate(['bucket-a', 'bucket-a', 'bucket-b']):
+ r = BackupRun(policy_id=policy.id, kind='full', status='success',
+ started_at=datetime.utcnow())
+ r.set_metadata({'offsite': {'destination': dest}})
+ db.session.add(r)
+ db.session.commit()
+ runs.append(r)
+
+ picks = BackupOffsiteService._sample_per_destination(runs, seed=7)
+ dests = sorted(BackupOffsiteService._destination_of(p) for p in picks)
+
+ assert dests == ['bucket-a', 'bucket-b']
+
+
+def test_sampling_is_deterministic(app):
+ from app.models.backup_run import BackupRun
+ with app.app_context():
+ policy = BackupPolicyService.get_or_create_policy(
+ 'files', 9603, target_meta={'paths': ['/x']})
+ runs = []
+ for _ in range(4):
+ r = BackupRun(policy_id=policy.id, kind='full', status='success',
+ started_at=datetime.utcnow())
+ r.set_metadata({'offsite': {'destination': 'bucket-a'}})
+ db.session.add(r)
+ db.session.commit()
+ runs.append(r)
+
+ a = [p.id for p in BackupOffsiteService._sample_per_destination(runs, seed=42)]
+ b = [p.id for p in BackupOffsiteService._sample_per_destination(runs, seed=42)]
+ assert a == b and len(a) == 1
+
+
+def _mk_user(username):
+ from app.models.user import User
+ u = User(email=f'{username}@test.local', username=username, role='user')
+ u.set_password('x')
+ db.session.add(u)
+ db.session.commit()
+ return u
+
+
+def _mk_wp_site(owner_id, name):
+ from app.models.application import Application
+ from app.models.wordpress_site import WordPressSite
+ app_row = Application(name=name, app_type='wordpress', user_id=owner_id,
+ root_path='/srv/x')
+ db.session.add(app_row)
+ db.session.commit()
+ site = WordPressSite(application_id=app_row.id, wp_version='6.4')
+ db.session.add(site)
+ db.session.commit()
+ return site
+
+
[email protected](reason="plan 42: hollow feature — WP app-scoped drill route "
+ "POST /api/v1/wordpress/sites/<id>/backups/drill (plan 30 Phase 6 / "
+ "#6 permission symmetry) missing from serverkit-wordpress extension; "
+ "restored by plan 42")
+def test_wp_drill_owner_reaches_gate_nonowner_404(app, client, auth_headers):
+ from app.models.user import User
+ with app.app_context():
+ admin = User.query.filter_by(username='testadmin').first()
+ owned_id = _mk_wp_site(admin.id, 'owned-site').id
+ other = _mk_user('someoneelse')
+ foreign_id = _mk_wp_site(other.id, 'foreign-site').id
+
+ r = client.post(f'/api/v1/wordpress/sites/{owned_id}/backups/drill',
+ headers=auth_headers)
+ assert r.status_code in (202, 409)
+
+ r = client.post(f'/api/v1/wordpress/sites/{foreign_id}/backups/drill',
+ headers=auth_headers)
+ assert r.status_code == 404
diff --git a/backend/tests/test_backup_expectations.py b/backend/tests/test_backup_expectations.py
new file mode 100644
index 00000000..fc41be2d
--- /dev/null
+++ b/backend/tests/test_backup_expectations.py
@@ -0,0 +1,49 @@
+"""Plan 30 Phase 2 — expectations captured at backup time, compared at drill.
+
+Covers the writer (`_collect_expectations` for DB + file targets), the
+manifest round-trip, and the drill-side comparison upgrades (table-count match,
+row-count drift on the largest tables, extracted-file count).
+
+NOTE (plan 42 recovery): the whole ``_collect_expectations`` writer + its
+manifest round-trip and drill-side comparison upgrades were lost with the tests
+— ``app.services.backup_verify_service._collect_expectations`` does not exist in
+the recovered tree. The reconstructed test below is kept faithful to the salvage
+but skipped as a hollow-feature marker; restore is owned by plan 42.
+"""
+import io
+import tarfile
+
+import pytest
+
+from app import db # noqa: F401 (kept for parity with the original module)
+
+
+def _tar_gz(dest, files):
+ with tarfile.open(dest, 'w:gz') as tar:
+ for name, content in files.items():
+ data = io.BytesIO(content)
+ info = tarfile.TarInfo(name)
+ info.size = len(content)
+ tar.addfile(info, data)
+
+
[email protected](reason="plan 42: hollow feature — backup_verify_service._collect_expectations "
+ "(backup-time DB/file expectation capture, plan 30 Phase 2) is absent "
+ "from the recovered tree; restored by plan 42")
+def test_db_expectations_capture(app, monkeypatch):
+ from app.services.database_service import DatabaseService
+ from app.services import backup_verify_service
+
+ def _mysql_get_tables(name, **kws):
+ return [{'name': 'wp_posts', 'rows': 10}, {'name': 'wp_users', 'rows': 3}]
+
+ monkeypatch.setattr(DatabaseService, 'mysql_get_tables',
+ staticmethod(_mysql_get_tables))
+
+ with app.app_context():
+ target = {'target_type': 'database',
+ 'db_config': {'db_type': 'mysql', 'db_name': 'shop'}}
+ exp = backup_verify_service._collect_expectations(target)
+ assert exp['table_count'] == 2
+ assert 'tables' in exp
+ assert 'row_counts' in exp
diff --git a/backend/tests/test_backup_offsite.py b/backend/tests/test_backup_offsite.py
new file mode 100644
index 00000000..85a0495d
--- /dev/null
+++ b/backend/tests/test_backup_offsite.py
@@ -0,0 +1,57 @@
+"""Plan 30 Phase 4 — offsite verification sampling + honest shallow-verify labels.
+
+Deterministic single-run sampling (bounded monthly egress, reproducible for a
+seed) plus the shallow HEAD/size/ETag compare that records an honest evidence
+label — ``checksum`` where a single-part ETag confirms content, ``size_only``
+where a multipart ETag can only confirm size.
+"""
+from datetime import datetime, timedelta
+
+import pytest
+
+from app import db
+from app.services.backup_policy_service import BackupPolicyService
+from app.services.backup_offsite_service import BackupOffsiteService
+
+
+def test_sample_one_is_deterministic(app):
+ from app.models.backup_run import BackupRun
+ with app.app_context():
+ policy = BackupPolicyService.get_or_create_policy(
+ 'files', 9801, target_meta={'paths': ['/x']})
+ runs = []
+ for i in range(5):
+ r = BackupRun(policy_id=policy.id, kind='full', status='success',
+ started_at=datetime.utcnow() - timedelta(days=i))
+ db.session.add(r)
+ db.session.commit()
+ runs.append(r)
+
+ # Same seed -> same pick (reproducible, so the monthly egress is bounded
+ # AND testable).
+ pick_a = BackupOffsiteService._sample_one(runs, seed=3)
+ pick_b = BackupOffsiteService._sample_one(runs, seed=3)
+ assert pick_a.id == pick_b.id
+
+ # Across many seeds the sampler spreads over the set (not a constant).
+ picks = {BackupOffsiteService._sample_one(runs, seed=s).id for s in range(20)}
+ assert len(picks) > 1
+
+ # No candidates -> no pick.
+ assert BackupOffsiteService._sample_one([], seed=1) is None
+
+
[email protected](reason="plan 42: hollow feature — honest shallow-verify evidence label "
+ "('size_only' for multipart ETag) via BackupPolicyService.verify_run "
+ "not present in recovered tree (verify_run returns no 'evidence'); "
+ "restored by plan 42")
+def test_shallow_verify_labels_multipart_size_only(app, tmp_path, monkeypatch):
+ pytest.skip("hollow: verify_run does not emit an 'evidence' label")
+
+
[email protected](reason="plan 42: hollow feature — honest shallow-verify evidence label "
+ "('checksum' for single-part ETag) via BackupPolicyService.verify_run "
+ "not present in recovered tree (verify_run returns no 'evidence'); "
+ "restored by plan 42")
+def test_shallow_verify_labels_single_part_checksum(app, tmp_path, monkeypatch):
+ pytest.skip("hollow: verify_run does not emit an 'evidence' label")
diff --git a/backend/tests/test_cron_preview.py b/backend/tests/test_cron_preview.py
new file mode 100644
index 00000000..4fd621cb
--- /dev/null
+++ b/backend/tests/test_cron_preview.py
@@ -0,0 +1,115 @@
+"""Cron schedule preview, humanizer, preset catalog, and marker hygiene.
+
+Proving tests for plan 21 Phase 1 (#0, #1, #3, #4). Crontab mutation is
+Linux-only; these run on any OS by exercising the pure helpers (humanizer,
+preview, _locate marker matching) plus the HTTP preview/preset endpoints.
+"""
+import re
+
+import pytest
+
+from app.services.cron_service import CronService
+
+ISO_UTC = re.compile(r'\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\+00:00$')
+
+
+# ---------------------------------------------------------------------------
+# preview / humanizer
+# ---------------------------------------------------------------------------
+
[email protected](reason="plan 42: recovery regression - cron_service humanizer was "
+ "restored at an older level ('0 0 * * *' -> 'Daily', not "
+ "'Every day at 00:00') and _next_runs returns naive local ISO "
+ "(no +00:00), so the plan-21 preview contract is not met")
+def test_preview_valid_daily():
+ res = CronService.preview_schedule('0 0 * * *')
+ assert res['valid'] is True
+ assert res['human'] == 'Every day at 00:00'
+ assert len(res['next_runs']) == 5
+ for r in res['next_runs']:
+ assert ISO_UTC.search(r)
+
+
+# ---------------------------------------------------------------------------
+# marker matching (_locate / _line_body)
+# ---------------------------------------------------------------------------
+
+_HOLLOW_LOCATE = "plan 42: hollow feature - CronService._locate/_line_body marker " \
+ "helpers were lost in recovery (the marker logic survives only " \
+ "inlined in remove_job); helpers not restored yet"
+
+
[email protected](reason=_HOLLOW_LOCATE)
+def test_locate_by_id_marker():
+ lines = ['# ServerKit Job: job_20260101', '0 0 * * * /usr/bin/backup.sh']
+ job = {'name': 'Nightly', 'command': '/usr/bin/backup.sh'}
+ marker_idx, job_idx = CronService._locate(lines, job, 'job_20260101')
+ assert marker_idx == 0
+ assert job_idx == 1
+
+
[email protected](reason=_HOLLOW_LOCATE)
+def test_locate_by_legacy_name_marker():
+ lines = ['# ServerKit Job: Nightly', '0 0 * * * /usr/bin/backup.sh']
+ job = {'name': 'Nightly', 'command': '/usr/bin/backup.sh'}
+ marker_idx, job_idx = CronService._locate(lines, job, 'job_x')
+ assert marker_idx == 0
+ assert job_idx == 1
+
+
[email protected](reason=_HOLLOW_LOCATE)
+def test_locate_disabled_line_via_marker():
+ lines = ['# ServerKit Job: job_x', '# 0 0 * * * /usr/bin/backup.sh']
+ job = {'name': 'job_x', 'command': '/usr/bin/backup.sh'}
+ marker_idx, job_idx = CronService._locate(lines, job, 'job_x')
+ assert marker_idx == 0
+ assert CronService._line_body(lines[job_idx]) == '0 0 * * * /usr/bin/backup.sh'
+
+
[email protected](reason=_HOLLOW_LOCATE)
+def test_locate_body_fallback_without_marker():
+ lines = ['# unrelated comment', '5 4 * * * /other']
+ job = {'name': 'nope', 'command': 'nope'}
+ marker_idx, job_idx = CronService._locate(lines, job, 'nope')
+ assert marker_idx is None
+
+
[email protected](reason=_HOLLOW_LOCATE)
+def test_locate_absent():
+ lines = ['# unrelated comment', '5 4 * * * /other']
+ job = {'name': 'missing', 'command': 'missing'}
+ assert CronService._locate(lines, job, 'missing') == (None, None)
+
+
+# ---------------------------------------------------------------------------
+# application attribution (survives)
+# ---------------------------------------------------------------------------
+
+def test_add_job_stores_application_id(tmp_path, monkeypatch):
+ import app.services.cron_service as mod
+ monkeypatch.setattr(mod.CronService, 'is_linux', classmethod(lambda cls: False))
+ monkeypatch.setattr(mod, 'JOBS_FILE', str(tmp_path / 'cron_jobs.json'))
+
+ mod.CronService.add_job('0 0 * * *', '/usr/bin/backup.sh', name='Nightly',
+ application_id=42)
+ jobs = mod.CronService.jobs_for_application(42)
+ assert len(jobs) == 1
+ assert jobs[0]['application_id'] == 42
+
+
[email protected](reason="plan 42: recovery regression - add_job generates a "
+ "second-precision job_id (job_%Y%m%d%H%M%S), so two adds in "
+ "the same second collide and only one job persists; the "
+ "finer-grained id from plan 34 was lost")
+def test_clear_application(tmp_path, monkeypatch):
+ import app.services.cron_service as mod
+ monkeypatch.setattr(mod.CronService, 'is_linux', classmethod(lambda cls: False))
+ monkeypatch.setattr(mod, 'JOBS_FILE', str(tmp_path / 'cron_jobs.json'))
+
+ mod.CronService.add_job('0 0 * * *', '/usr/bin/a.sh', application_id=7)
+ mod.CronService.add_job('0 1 * * *', '/usr/bin/b.sh', application_id=7)
+ assert len(mod.CronService.jobs_for_application(7)) == 2
+
+ cleared = mod.CronService.clear_application(7)
+ assert cleared == 2
+ assert mod.CronService.jobs_for_application(7) == []
diff --git a/backend/tests/test_dns_cutover_providers.py b/backend/tests/test_dns_cutover_providers.py
new file mode 100644
index 00000000..86ea216c
--- /dev/null
+++ b/backend/tests/test_dns_cutover_providers.py
@@ -0,0 +1,105 @@
+"""Provider-registry resolution for DNS cutover (plan 31 #12, Decision 4).
+
+Plan 27's cutover resolver hardcoded Cloudflare-or-501. This proves the resolver
+now routes through the shared provider registry (``app.services.dns.get_client``)
+so any provider with a shared client flows through, and a provider that lacks one
+guards cleanly with ``NO_PROVIDER`` naming the provider — never a 500.
+
+Reconstructed from the clean recovery pyc
+(``test_dns_cutover_providers.cpython-311-pytest-8.3.5.pyc``).
+"""
+import pytest
+from flask_jwt_extended import create_access_token
+from werkzeug.security import generate_password_hash
+
+from app import db
+from app.models import User
+from app.models.email import DNSProviderConfig
+from app.api import dns_cutover as cutover_api # noqa: F401 (ensure bp import)
+from app.services.dns_cutover_service import DnsCutoverService
+
+# plan 42 finding D7: the provider-registry cutover path is only partially intact
+# after the recovery rebuild, so this file is skipped until it is completed:
+# * ``DnsCutoverService.snapshot(domain, records, provider=, provider_zone_id=)``
+# — the explicit-records staging classmethod these tests use — is MISSING
+# (only the server-sourced ``create_snapshot`` survives, and it needs a live
+# provider client, so it cannot stage a snapshot for the guard tests);
+# * the 501 ``NO_PROVIDER`` response body does not carry a ``provider`` field
+# naming the unsupported provider (``_resolve_dns_client`` raises the code but
+# the API never surfaces the name);
+# * the successful cutover response is not wrapped under a ``cutover`` key.
+pytestmark = pytest.mark.skip(
+ reason="plan 42 finding D7: hollow feature — DnsCutoverService.snapshot() "
+ "staging classmethod missing; cutover 501 body omits 'provider'; "
+ "success payload not wrapped under 'cutover'")
+
+
+def admin_headers(app):
+ user = User(email='[email protected]', username='provadmin',
+ password_hash=generate_password_hash('x'),
+ role='admin', is_active=True)
+ db.session.add(user)
+ db.session.commit()
+ return {'Authorization': 'Bearer ' + create_access_token(identity=user.id)}
+
+
+def _add_provider(provider, is_default=True):
+ from app.utils.crypto import encrypt_secret
+ cfg = DNSProviderConfig(name=f'{provider}-conn', provider=provider,
+ api_key=encrypt_secret('k'), is_default=is_default)
+ db.session.add(cfg)
+ db.session.commit()
+ return cfg
+
+
+class _FakeClient:
+ def __init__(self):
+ self.upserted = []
+
+ def find_record_id(self, zone_id, record_type, name, caa=None):
+ return None
+
+ def upsert(self, zone_id, spec, record_id=None):
+ self.upserted.append((spec.record_type, spec.name, spec.content))
+ return {'success': True, 'record_id': 'REC-1'}
+
+
+def test_provider_without_client_guards_no_provider_by_name(app, client, admin_headers):
+ _add_provider('route53')
+ snap = DnsCutoverService.snapshot(
+ 'example.com',
+ [{'name': 'example.com', 'type': 'A', 'content': '1.1.1.1'}],
+ provider='route53', provider_zone_id='ZONE1')
+ resp = client.post('/api/v1/dns-cutover/cutover', headers=admin_headers,
+ json={'snapshot_id': snap.id, 'target': '5.6.7.8'})
+ assert resp.status_code == 501
+ body = resp.get_json()
+ assert body['code'] == 'NO_PROVIDER'
+ assert body.get('provider') == 'route53'
+
+
+def test_stubbed_second_provider_flows_through(app, client, admin_headers, monkeypatch):
+ _add_provider('fakeprov')
+ fake = _FakeClient()
+ monkeypatch.setattr('app.services.dns.get_client', lambda cred: fake)
+ snap = DnsCutoverService.snapshot(
+ 'example.com',
+ [{'name': 'example.com', 'type': 'A', 'content': '1.1.1.1'}],
+ provider='fakeprov', provider_zone_id='ZONE1')
+ resp = client.post('/api/v1/dns-cutover/cutover', headers=admin_headers,
+ json={'snapshot_id': snap.id, 'target': '5.6.7.8'})
+ assert resp.status_code == 200, resp.get_data(as_text=True)
+ assert resp.get_json()['cutover']['success'] is True
+ assert ('A', 'example.com', '5.6.7.8') in fake.upserted
+
+
+def test_no_provider_connected_guards_cleanly(app, client, admin_headers):
+ snap = DnsCutoverService.snapshot(
+ 'example.com',
+ [{'name': 'example.com', 'type': 'A', 'content': '1.1.1.1'}],
+ provider='cloudflare', provider_zone_id='ZONE1')
+ resp = client.post('/api/v1/dns-cutover/cutover', headers=admin_headers,
+ json={'snapshot_id': snap.id, 'target': '5.6.7.8'})
+ assert resp.status_code == 501
+ assert resp.get_json()['code'] == 'NO_PROVIDER'
diff --git a/backend/tests/test_fleet_doctor_dns_rotation.py b/backend/tests/test_fleet_doctor_dns_rotation.py
new file mode 100644
index 00000000..36782755
--- /dev/null
+++ b/backend/tests/test_fleet_doctor_dns_rotation.py
@@ -0,0 +1,97 @@
+"""Fleet-doctor DNS rotation (plan 31 #13, Decision 7).
+
+The per-server DNS check stays bounded at DNS_CHECK_MAX_DOMAINS, but the checked
+subset now ROTATES per sweep so a box with more domains than the cap still gets
+every domain verified over successive sweeps — instead of permanently truncating
+to the first N. Proves N sweeps cover >cap domains and the counter advances.
+
+Reconstructed from the clean recovery pyc
+(``test_fleet_doctor_dns_rotation.cpython-311-pytest-8.3.5.pyc``). The rotating
+DNS-window API (``FleetDoctorService._dns_checks`` / ``_server_site_hosts`` /
+``_next_dns_sweep_index`` + ``DNS_CHECK_MAX_DOMAINS``) did NOT survive the recovery
+rebuild — the surviving service only has the single ``_dns_check_for_server``
+row — so the whole file skips until that engine is restored (see report finding).
+"""
+import socket
+
+import pytest
+
+try:
+ from app.services import fleet_doctor_service as fd
+ from app.models.server import Server
+ from app.services.fleet_doctor_service import (
+ FleetDoctorService, DNS_CHECK_MAX_DOMAINS)
+ _HOLLOW = None
+except (ImportError, AttributeError) as exc: # feature lost in recovery
+ _HOLLOW = str(exc)
+
+if _HOLLOW:
+ pytestmark = pytest.mark.skip(
+ reason="plan 42: hollow feature — fleet-doctor DNS rotation "
+ "(FleetDoctorService._dns_checks/_server_site_hosts/"
+ "_next_dns_sweep_index + DNS_CHECK_MAX_DOMAINS) missing after "
+ f"recovery rebuild: {_HOLLOW}")
+
+
+def _hosts(n):
+ return [f'site{i}.example.com' for i in range(n)]
+
+
+def _checked_hosts(rows):
+ prefix = 'dns.resolve.'
+ return {r['key'][len(prefix):] for r in rows
+ if r['key'].startswith(prefix) and r['key'] != 'dns.resolve'}
+
+
+def test_rotation_covers_all_domains_over_sweeps(app, monkeypatch):
+ total = DNS_CHECK_MAX_DOMAINS + 5
+ hosts = _hosts(total)
+ monkeypatch.setattr(FleetDoctorService, '_server_site_hosts',
+ classmethod(lambda cls, s: list(hosts)))
+ monkeypatch.setattr(fd.socket, 'getaddrinfo',
+ lambda *a, **k: (_ for _ in ()).throw(socket.gaierror()))
+ server = Server(name='dns-rot', ip_address='203.0.113.9')
+
+ checked = set()
+ sweeps_needed = (total + DNS_CHECK_MAX_DOMAINS - 1) // DNS_CHECK_MAX_DOMAINS
+ for i in range(sweeps_needed):
+ rows = FleetDoctorService._dns_checks(server, sweep_index=i)
+ assert len(_checked_hosts(rows)) <= DNS_CHECK_MAX_DOMAINS
+ checked |= _checked_hosts(rows)
+
+ assert checked == set(hosts)
+
+
+def test_rotation_warn_row_reports_position_not_truncation(app, monkeypatch):
+ hosts = _hosts(DNS_CHECK_MAX_DOMAINS + 3)
+ monkeypatch.setattr(FleetDoctorService, '_server_site_hosts',
+ classmethod(lambda cls, s: list(hosts)))
+ monkeypatch.setattr(fd.socket, 'getaddrinfo',
+ lambda *a, **k: (_ for _ in ()).throw(socket.gaierror()))
+ server = Server(name='dns-rot2', ip_address='203.0.113.10')
+
+ rows = FleetDoctorService._dns_checks(server, sweep_index=0)
+ summary = [r for r in rows if r['key'] == 'dns.resolve']
+ assert summary, 'expected a rotating-window summary row'
+ detail = summary[0]['detail'].lower()
+ assert 'rotating' in detail and 'verified within' in detail
+
+
+def test_under_cap_has_no_rotation_row(app, monkeypatch):
+ hosts = _hosts(3)
+ monkeypatch.setattr(FleetDoctorService, '_server_site_hosts',
+ classmethod(lambda cls, s: list(hosts)))
+ monkeypatch.setattr(fd.socket, 'getaddrinfo',
+ lambda *a, **k: (_ for _ in ()).throw(socket.gaierror()))
+ server = Server(name='dns-small', ip_address='203.0.113.11')
+
+ rows = FleetDoctorService._dns_checks(server, sweep_index=5)
+ assert _checked_hosts(rows) == set(hosts)
+ assert not [r for r in rows if r['key'] == 'dns.resolve']
+
+
+def test_dns_sweep_counter_advances(app):
+ a = FleetDoctorService._next_dns_sweep_index()
+ b = FleetDoctorService._next_dns_sweep_index()
+ c = FleetDoctorService._next_dns_sweep_index()
+ assert [b - a, c - b] == [1, 1]
diff --git a/backend/tests/test_fleet_sweep.py b/backend/tests/test_fleet_sweep.py
new file mode 100644
index 00000000..52268278
--- /dev/null
+++ b/backend/tests/test_fleet_sweep.py
@@ -0,0 +1,66 @@
+"""Bounded fan-out primitive — fleet_sweep (Fleet Parity Sweep, plan 26, Decision 4).
+
+Proves the one sweep primitive every fleet operation reuses: it addresses servers
+by id (de-duped), passes the per-agent timeout down to each composer, returns an
+empty map for an empty server list, and — crucially — turns a hung agent into a
+partial ``timeout`` row instead of blocking the caller past its wall-clock budget.
+
+Reconstructed from the fragmented recovery pyc
+(``test_fleet_sweep.cpython-311-pytest-8.3.5.pyc``) + the surviving
+``app.services.fleet_sweep`` implementation.
+"""
+import time
+
+from app.services.fleet_sweep import fleet_sweep
+
+
+def test_empty_server_list_is_empty(app):
+ result = fleet_sweep(lambda sid, t: {'status': 'ok'}, [])
+ assert result == {}
+
+
+def test_server_objects_addressed_by_id(app):
+ class FakeServer:
+ def __init__(self, id):
+ self.id = id
+
+ servers = [FakeServer('srv-1'), FakeServer('srv-2')]
+ result = fleet_sweep(lambda sid, t: {'status': 'ok', 'sid': sid}, servers)
+ assert set(result.keys()) == {'srv-1', 'srv-2'}
+
+
+def test_duplicate_servers_deduped(app):
+ calls = []
+
+ def compose(sid, t):
+ calls.append(sid)
+ return {'status': 'ok'}
+
+ result = fleet_sweep(compose, ['a', 'a', 'b'])
+ assert sorted(result.keys()) == ['a', 'b']
+ assert sorted(calls) == ['a', 'b']
+
+
+def test_composer_receives_per_agent_timeout(app):
+ seen = []
+
+ def compose(sid, t):
+ seen.append(t)
+ return {'status': 'ok'}
+
+ fleet_sweep(compose, ['x'], per_agent_timeout=7.5)
+ assert seen == [7.5]
+
+
+def test_budget_turns_hung_agent_into_timeout_row(app):
+ def compose(sid, t):
+ if sid == 'slow':
+ time.sleep(3)
+ return {'status': 'ok'}
+
+ start = time.monotonic()
+ result = fleet_sweep(compose, ['fast1', 'fast2', 'slow'],
+ pool=3, per_agent_timeout=10, budget=0.5)
+ elapsed = time.monotonic() - start
+ assert elapsed < 3, f'sweep blocked too long: {elapsed:.1f}'
+ assert result['slow']['status'] == 'timeout'
diff --git a/backend/tests/test_notification_prefs_resolution.py b/backend/tests/test_notification_prefs_resolution.py
new file mode 100644
index 00000000..1a32ad8a
--- /dev/null
+++ b/backend/tests/test_notification_prefs_resolution.py
@@ -0,0 +1,152 @@
+"""Preference resolution matrix (plan 24 Phase 2).
+
+Proves the first-match-wins order for a channel firing:
+ user per-event override > user category/severity prefs > org default > catalog
+plus the critical-always invariant and back-compat for rows without an
+``events_json`` map.
+
+RECOVERY NOTE (plan 42): the original pyc unmarshalled only partially (salvage
+truncates at ``TestOrgDefaults``). Two tiers of the matrix did NOT survive the
+data loss and are hollow in the current tree:
+
+ * the *user per-event override* tier — ``NotificationPreferences`` has no
+ ``events_json`` column and no ``set_events()`` method, and
+ ``NotificationBusService._plan`` never consults a per-event map.
+ * the *org default* tier — resolution never consults ``SettingsService`` for
+ an org-wide channel default.
+
+Those tiers are marked skip-hollow below. The surviving middle of the chain
+(user severity/category prefs + the critical-always invariant + back-compat for
+rows without an events map) is reconstructed as real coverage.
+"""
+import pytest
+from werkzeug.security import generate_password_hash
+
+from app import db
+from app.models import User
+from app.models.notification_preferences import NotificationPreferences
+from app.notifications.models import Notification, NotificationDelivery
+from app.notifications.service import NotificationBusService
+from app.queue_bus.service import QueueBusService
+from app.services.settings_service import SettingsService
+
+
[email protected](autouse=True)
+def reset_broker(app):
+ QueueBusService.reset_broker()
+
+
+def _make_user(username='alice', email='[email protected]', role='developer'):
+ user = User(
+ email=email, username=username,
+ password_hash=generate_password_hash('x'),
+ role=role, is_active=True,
+ )
+ db.session.add(user)
+ db.session.commit()
+ return user
+
+
+def _prefs(user, **fields):
+ prefs = NotificationPreferences.get_or_create(user.id)
+ for key, value in fields.items():
+ if key == 'channels':
+ prefs.set_channels(value)
+ elif key == 'severities':
+ prefs.set_severities(value)
+ elif key == 'categories':
+ prefs.set_categories(value)
+ elif key == 'events':
+ # Per-event override map (plan 24 Phase 2) — hollow post-recovery.
+ prefs.set_events(value)
+ else:
+ setattr(prefs, key, value)
+ db.session.commit()
+ return prefs
+
+
+def _channels_for(user):
+ return {d.channel for d in NotificationDelivery.query
+ .filter_by(recipient_user_id=user.id).all()}
+
+
+def _clear():
+ NotificationDelivery.query.delete()
+ Notification.query.delete()
+ db.session.commit()
+
+
+# ---------------------------------------------------------------------------
+# surviving: severity / category gating + critical-always invariant
+# ---------------------------------------------------------------------------
+
+def test_critical_always_delivers_even_when_severity_muted():
+ """The critical-always invariant: a 'critical' severity reaches the user
+ even when their severity prefs would otherwise mute it."""
+ u = _make_user()
+ _prefs(u, enabled=True, severities=['info']) # neither warning nor critical listed
+
+ NotificationBusService.send('probe.event', to=u, severity='critical', category='system')
+ assert 'email' in _channels_for(u)
+ assert 'inapp' in _channels_for(u)
+
+
+def test_noncritical_muted_by_severity_pref():
+ u = _make_user()
+ _prefs(u, enabled=True, severities=['info']) # warning not listed
+
+ NotificationBusService.send('probe.event', to=u, severity='warning', category='system')
+ assert _channels_for(u) == set()
+
+
+def test_muted_category_is_dropped():
+ u = _make_user()
+ _prefs(u, enabled=True,
+ categories={'system': False, 'security': True, 'backups': True, 'apps': True})
+
+ NotificationBusService.send('probe.event', to=u, severity='warning', category='system')
+ assert _channels_for(u) == set()
+
+
+def test_backcompat_row_without_events_map_resolves_by_prefs():
+ """Back-compat: a preferences row with no per-event override map still
+ resolves purely off the user's severity/category prefs."""
+ u = _make_user()
+ _prefs(u, enabled=True) # defaults: severities critical+warning, all categories on
+
+ NotificationBusService.send('probe.event', to=u, severity='warning', category='apps')
+ assert 'email' in _channels_for(u)
+
+
+# ---------------------------------------------------------------------------
+# hollow: user per-event override tier (events_json / set_events)
+# ---------------------------------------------------------------------------
+
[email protected](reason="plan 42: hollow feature - NotificationPreferences.events_json "
+ "column + set_events() and the per-event override tier in "
+ "NotificationBusService._plan were lost in the data loss")
+def test_per_event_override_beats_category_pref():
+ u = _make_user()
+ # Category 'apps' muted at the category tier, but explicitly on for this event.
+ _prefs(u, enabled=True,
+ categories={'system': True, 'security': True, 'backups': True, 'apps': False},
+ events={'app.deployed': {'channels': ['email']}})
+
+ NotificationBusService.send('app.deployed', to=u, category='apps', severity='info')
+ assert 'email' in _channels_for(u) # per-event override wins over category mute
+
+
+# ---------------------------------------------------------------------------
+# hollow: org default tier (SettingsService-driven default channels)
+# ---------------------------------------------------------------------------
+
[email protected](reason="plan 42: hollow feature - resolution never consults "
+ "SettingsService for an org-wide default-channels tier; that "
+ "layer did not survive the data loss")
+class TestOrgDefaults:
+ def test_org_default_channels_apply_when_user_has_none(self):
+ SettingsService.set('notifications.default_channels', ['email'])
+ u = _make_user()
+ _prefs(u, enabled=True, channels=[]) # user sets no channels
+ NotificationBusService.send('probe.event', to=u, severity='warning', category='system')
+ assert 'email' in _channels_for(u) # falls back to org default
diff --git a/backend/tests/test_observe_enforcement.py b/backend/tests/test_observe_enforcement.py
new file mode 100644
index 00000000..b4ba09de
--- /dev/null
+++ b/backend/tests/test_observe_enforcement.py
@@ -0,0 +1,134 @@
+"""Observe-mode enforcement — the read/write matrix (plan 27 Phase 4, #9/#10).
+
+Decision 5: an Observed server keeps reads (metrics, doctor probes, survey,
+file/list reads) but every mutating server-targeted command is refused at the
+single choke point (``agent_registry.send_command``). This proves the classifier
+and that the guard actually blocks writes while letting reads through.
+
+Reconstructed from the clean recovery pyc
+(``test_observe_enforcement.cpython-311-pytest-9.0.3.pyc``).
+"""
+import hashlib
+import hmac
+import time
+
+import pytest
+
+from app import db as _db
+from app.models.server import Server
+from app.services.agent_registry import agent_registry
+
+# plan 42 finding: the Observe-mode enforcement engine did NOT survive the
+# recovery rebuild, so this whole file is skipped until it is restored. Concretely
+# the surviving tree is missing:
+# * ``Server.is_read_action`` read verbs — 'metrics'/'processes'/'ps'/
+# 'recapabilities' are no longer classified as reads (the classifier under-
+# matches the read column of ACTION_MATRIX);
+# * a None/empty guard on ``Server.is_read_action`` (it raises on ``None``);
+# * the ``OBSERVED_READONLY`` write-guard in ``agent_registry.send_command``
+# (no code path refuses a mutation on an Observed server);
+# * the ``servers.management_mode`` column MAPPING on the Server model
+# (migration 065 adds the column, but the model no longer declares it).
+pytestmark = pytest.mark.skip(
+ reason="plan 42: hollow feature — Observe-mode enforcement (is_read_action "
+ "verbs + None guard, send_command OBSERVED_READONLY guard, Server."
+ "management_mode column mapping) missing after recovery rebuild")
+
+CONNECT = '/api/v1/agent/connect'
+
+# (action, is_read) — the classifier's whole contract, one row per class of
+# command the panel routes to an agent.
+ACTION_MATRIX = [
+ ('system:metrics', True),
+ ('system:info', True),
+ ('system:processes', True),
+ ('docker:container:list', True),
+ ('docker:image:list', True),
+ ('docker:compose:ps', True),
+ ('file:read', True),
+ ('file:list', True),
+ ('survey:read', True),
+ ('doctor:probe', True),
+ ('agent:recapabilities', True),
+ ('docker:container:start', False),
+ ('docker:container:restart', False),
+ ('docker:container:delete', False),
+ ('docker:image:pull', False),
+ ('docker:compose:up', False),
+ ('systemd:restart', False),
+ ('cron:update', False),
+ ('file:write', False),
+ ('cron:create', False),
+ ('nginx:sites:create', False),
+]
+
+
+def test_is_read_action_classifies_every_class():
+ for action, is_read in ACTION_MATRIX:
+ assert Server.is_read_action(action) is is_read, action
+
+
+def test_is_read_action_defaults_to_write_when_unknown():
+ assert Server.is_read_action('mystery:frobnicate') is False
+ assert Server.is_read_action('') is False
+ assert Server.is_read_action(None) is False
+
+
+def _connect_agent(client, monkeypatch):
+ """Register a connected poll-mode agent and return its server_id."""
+ api_key, api_secret = Server.generate_api_credentials()
+ server = Server(name='observed-e2e', agent_id='agent-obs')
+ server.set_api_key(api_key)
+ server.permissions = ['*']
+ _db.session.add(server)
+ _db.session.commit()
+ server_id = server.id
+
+ monkeypatch.setattr(Server, 'get_api_secret', lambda self: api_secret)
+
+ ts = int(time.time() * 1000)
+ nonce = 'nonce-obs-1'
+ msg = f'{server.agent_id}:{ts}:{nonce}'
+ sig = hmac.new(api_secret.encode(), msg.encode(), hashlib.sha256).hexdigest()
+ resp = client.post(CONNECT, json={
+ 'agent_id': server.agent_id,
+ 'api_key_prefix': server.api_key_prefix,
+ 'signature': sig,
+ 'timestamp': ts,
+ 'nonce': nonce,
+ })
+ assert resp.status_code == 200, resp.get_data(as_text=True)
+ return server_id
+
+
+def _set_mode(server_id, mode):
+ server = Server.query.get(server_id)
+ server.management_mode = mode
+ _db.session.commit()
+
+
+def test_observed_refuses_mutations_allows_reads(app, client, monkeypatch):
+ server_id = _connect_agent(client, monkeypatch)
+ _set_mode(server_id, 'observed')
+
+ for action, is_read in ACTION_MATRIX:
+ result = agent_registry.send_command(server_id, action, params={},
+ timeout=0.3)
+ if is_read:
+ # Reads pass the observe guard (they only fail later on the absent
+ # agent transport — never with the read-only refusal).
+ assert result.get('code') != 'OBSERVED_READONLY', action
+ else:
+ assert result.get('code') == 'OBSERVED_READONLY', action
+ assert result.get('success') is False, action
+
+
+def test_managed_allows_mutations_past_guard(app, client, monkeypatch):
+ server_id = _connect_agent(client, monkeypatch)
+ _set_mode(server_id, 'managed')
+
+ # A managed server never trips the observe guard — the mutating command
+ # flows past it (and only then fails on the stubbed transport).
+ result = agent_registry.send_command(server_id, 'docker:container:restart',
+ params={}, timeout=0.3)
+ assert result.get('code') != 'OBSERVED_READONLY'
diff --git a/backend/tests/test_runtime_frontend.py b/backend/tests/test_runtime_frontend.py
new file mode 100644
index 00000000..3643374c
--- /dev/null
+++ b/backend/tests/test_runtime_frontend.py
@@ -0,0 +1,161 @@
+"""Runtime extension frontend loading — server-side contract (plan 25 Phase 2).
+
+Covers the halves the backend owns:
+ - install-time bundle hashing (#6): sha256 of the runtime ESM bundle recorded
+ in the plugin config store,
+ - the /plugins/contributions `frontends` descriptor map exposing entry + hashes,
+ - the kill switch (Decision 4): `extensions.runtime_frontend` off -> no `frontends`,
+ - dual-path coexistence: a baked (.jsx) builtin + a runtime (.mjs) extension in
+ one session -> only the runtime one appears in `frontends`,
+ - config PUT preserving the panel-managed `_frontend_hashes` key.
+
+The frontend halves (blob-import, hash-mismatch refusal, error-boundary render)
+are exercised by the JS render smoke test / screenshots fixture; here we lock the
+data contract they depend on.
+
+RECOVERY NOTE (plan 42): this entire runtime-frontend backend contract did NOT
+survive the data loss and is hollow in the current tree — the whole module is
+skipped, with the reconstruction preserved so it can be un-skipped once the
+feature is restored. Missing surface:
+ - contribution_service.get_active_contributions() emits no ``frontends`` map
+ (and no ``sdk_version``),
+ - no ``_frontend_hashes`` key / install-time ESM sha256 recording in the plugin
+ config store,
+ - no ``extensions.runtime_frontend`` kill switch is consulted.
+"""
+import json
+import zipfile
+from io import BytesIO
+from types import SimpleNamespace
+
+import pytest
+
+from app import db
+from app.models.plugin import InstalledPlugin
+from app.services import contribution_service, plugin_service, registry_service
+from app.services.settings_service import SettingsService
+
+pytestmark = pytest.mark.skip(
+ reason="plan 42: hollow feature - the runtime-frontend backend contract "
+ "(frontends descriptor map, _frontend_hashes install-time ESM sha256, "
+ "extensions.runtime_frontend kill switch) was lost in the data loss")
+
+_BUNDLE = 'export function Page(){return null;}'
+_ICON = '<circle cx="12" cy="12" r="8"/>'
+
+
+def plugin_dirs(tmp_path, monkeypatch):
+ """Redirect plugin install roots at throwaway tmp dirs so installs never
+ touch the real backend/frontend/builtin plugin trees."""
+ backend = tmp_path / 'backend_plugins'
+ frontend = tmp_path / 'frontend_plugins'
+ builtin = tmp_path / 'builtin_extensions'
+ for d in (backend, frontend, builtin):
+ d.mkdir()
+ monkeypatch.setattr(plugin_service, 'BACKEND_PLUGINS_DIR', str(backend))
+ monkeypatch.setattr(plugin_service, 'FRONTEND_PLUGINS_DIR', str(frontend))
+ monkeypatch.setattr(plugin_service, 'BUILTIN_EXTENSIONS_DIR', str(builtin))
+ return SimpleNamespace(backend=backend, frontend=frontend, builtin=builtin)
+
+
+def _runtime_zip(slug='serverkit-runtime', bundle=_BUNDLE, **kw):
+ """Build an install zip for a runtime-frontend extension: a plugin.json whose
+ frontend is a prebuilt ESM bundle at frontend/dist/index.mjs."""
+ manifest = {
+ 'name': slug,
+ 'display_name': 'Runtime Demo',
+ 'version': '1.0.0',
+ 'description': ('A minimal extension whose frontend is a prebuilt ESM bundle at\n'
+ ' frontend/dist/index.mjs (the runtime-load convention).'),
+ 'category': 'utility',
+ 'sdk_version': '^1.0.0',
+ 'frontend_entry': 'dist/index.mjs',
+ 'contributions': {
+ 'nav': [{'label': 'Runtime Demo', 'route': 'runtime-demo',
+ 'category': 'system', 'icon': _ICON}],
+ 'routes': [{'path': 'runtime-demo', 'component': 'Page'}],
+ },
+ }
+ manifest.update(kw)
+
+ buf = BytesIO()
+ with zipfile.ZipFile(buf, 'w', zipfile.ZIP_DEFLATED) as zf:
+ zf.writestr('plugin.json', json.dumps(manifest))
+ zf.writestr('frontend/dist/index.mjs', bundle)
+ buf.seek(0)
+ return buf
+
+
+def _install_runtime(**kw):
+ buf = _runtime_zip(**kw)
+ return plugin_service.install_from_zip(buf.getvalue(), source_name='runtime-extension')
+
+
+# ---------------------------------------------------------------------------
+# install-time bundle hashing (#6)
+# ---------------------------------------------------------------------------
+
+def test_install_records_bundle_sha256(plugin_dirs):
+ import hashlib
+ plugin = _install_runtime()
+ expected = hashlib.sha256(_BUNDLE.encode()).hexdigest()
+ row = InstalledPlugin.query.filter_by(slug='serverkit-runtime').first()
+ hashes = (row.config or {}).get('_frontend_hashes') or {}
+ assert hashes.get('dist/index.mjs') == expected
+
+
+# ---------------------------------------------------------------------------
+# /plugins/contributions `frontends` descriptor map
+# ---------------------------------------------------------------------------
+
+def test_contributions_exposes_frontends_descriptor(plugin_dirs):
+ _install_runtime()
+ contrib = contribution_service.get_active_contributions()
+ fe = contrib['frontends']['serverkit-runtime']
+ assert fe['entry'] == 'dist/index.mjs'
+ assert 'hashes' in fe
+
+
+# ---------------------------------------------------------------------------
+# kill switch (Decision 4)
+# ---------------------------------------------------------------------------
+
+def test_kill_switch_removes_frontends(plugin_dirs):
+ _install_runtime()
+ SettingsService.set('extensions.runtime_frontend', False)
+ contrib = contribution_service.get_active_contributions()
+ assert not contrib.get('frontends')
+
+
+# ---------------------------------------------------------------------------
+# dual-path coexistence: baked builtin (.jsx) + runtime (.mjs)
+# ---------------------------------------------------------------------------
+
+def test_baked_and_runtime_coexist(plugin_dirs):
+ _install_runtime()
+ # A baked builtin contributes via a .jsx component, not a runtime bundle, so
+ # it must NOT appear in the runtime `frontends` map.
+ baked = InstalledPlugin(slug='serverkit-baked', name='Baked',
+ status=InstalledPlugin.STATUS_ACTIVE,
+ manifest={'frontend_entry': 'components/Baked.jsx'})
+ db.session.add(baked)
+ db.session.commit()
+ contrib = contribution_service.get_active_contributions()
+ assert 'serverkit-runtime' in contrib['frontends']
+ assert 'serverkit-baked' not in contrib['frontends']
+
+
+# ---------------------------------------------------------------------------
+# config PUT preserves the panel-managed `_frontend_hashes`
+# ---------------------------------------------------------------------------
+
+def test_config_put_preserves_frontend_hashes(plugin_dirs):
+ _install_runtime()
+ row = InstalledPlugin.query.filter_by(slug='serverkit-runtime').first()
+ before = (row.config or {}).get('_frontend_hashes')
+ plugin_service.update_plugin_config('serverkit-runtime', {'user_key': 'value'})
+ row = InstalledPlugin.query.filter_by(slug='serverkit-runtime').first()
+ after = (row.config or {}).get('_frontend_hashes')
+ assert after == before
+ assert (row.config or {}).get('user_key') == 'value'
diff --git a/backend/tests/test_sdk_contract.py b/backend/tests/test_sdk_contract.py
new file mode 100644
index 00000000..64be49e2
--- /dev/null
+++ b/backend/tests/test_sdk_contract.py
@@ -0,0 +1,65 @@
+"""SDK compatibility contract (plan 25 Phase 1 #1/#2).
+
+Locks three things:
+ - the backend SDK_VERSION mirror matches the frontend `SDK_VERSION` export,
+ - GET /api/v1/plugins/contributions reports it,
+ - the semver-range gate (`sdk_version_satisfies`) behaves.
+"""
+import os
+import re
+
+import pytest
+
+from app.utils.sdk import SDK_VERSION, sdk_version_satisfies
+
+_REPO_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+_SDK_JS = os.path.join(_REPO_ROOT, 'frontend', 'src', 'plugins', 'sdk', 'index.js')
+
+
+def test_backend_mirror_matches_frontend_sdk_version():
+ """backend/app/utils/sdk.py SDK_VERSION must equal the JS export, or the
+ runtime `sdk_version` report lies to extensions."""
+ with open(_SDK_JS, 'r', encoding='utf-8') as f:
+ src = f.read()
+ m = re.search(r'export\s+const\s+SDK_VERSION\s*=\s*[\'"]([^\'"]+)[\'"]', src)
+ assert m, 'SDK_VERSION export not found in frontend/src/plugins/sdk/index.js'
+ assert m.group(1) == SDK_VERSION, (
+ f'SDK version drift: JS={m.group(1)!r} backend={SDK_VERSION!r}. Update both in lock-step.'
+ )
+
+
[email protected](reason="plan 42: hollow feature - runtime-frontend contribution "
+ "surface (sdk_version/frontends in get_active_contributions) "
+ "was lost in the data loss; restored by plan 42 recovery")
+def test_contributions_reports_sdk_version(client, auth_headers):
+ resp = client.get('/api/v1/plugins/contributions', headers=auth_headers)
+ assert resp.status_code == 200
+ body = resp.get_json()
+ assert body.get('sdk_version') == SDK_VERSION
+ assert isinstance(body.get('frontends'), dict)
+
+
[email protected]('range_str,current,expected', [
+ ('', '1.0.0', True),
+ (None, '1.0.0', True),
+ ('*', '9.9.9', True),
+ ('1.0.0', '1.0.0', True),
+ ('1.0.0', '1.0.1', False),
+ ('^1.0.0', '1.4.2', True),
+ ('^1.0.0', '2.0.0', False),
+ ('^1.2.0', '1.1.0', False),
+ ('~1.2.0', '1.2.9', True),
+ ('~1.2.0', '1.3.0', False),
+ ('>=1.0.0', '1.0.0', True),
+ ('>=1.0.0', '0.9.0', False),
+ ('>=1.0.0,<2.0.0', '1.5.0', True),
+ ('>=1.0.0 <2.0.0', '2.0.0', False),
+ ('^0.1.0', '0.1.5', True),
+ ('^0.1.0', '0.2.0', False),
+])
+def test_sdk_version_satisfies(range_str, current, expected):
+ assert sdk_version_satisfies(range_str, current) is expected
+
+
+def test_sdk_version_satisfies_defaults_to_panel():
+ assert sdk_version_satisfies(f'^{SDK_VERSION.split(".")[0]}.0.0') is True
diff --git a/backend/tests/test_setup_security.py b/backend/tests/test_setup_security.py
new file mode 100644
index 00000000..4a026f0f
--- /dev/null
+++ b/backend/tests/test_setup_security.py
@@ -0,0 +1,105 @@
+"""Tests for the security-posture setup items + the require-2FA policy
+(plan 22 Phase 5): the enrollment-state matrix, login enforcement (nudge vs
+enforce vs SSO-exempt), and the account-security snooze round trip.
+
+Reconstructed for plan 42 Phase 1 from the fragmented ``test_setup_security`` pyc
++ the surviving ``security_policy_service`` / ``setup_health_service``. The pyc
+called a ``enrollment_state`` classmethod; the surviving service exposes the same
+ok/nudge/enforce evaluation as ``SecurityPolicyService.evaluate`` (the method was
+renamed and the grace window is now a fixed ``GRACE_PERIOD_DAYS`` anchored on
+``max(created_at, policy_enabled_at)`` rather than a ``*_grace_days`` setting).
+The reconstructed tests track that current contract.
+"""
+from datetime import datetime, timedelta
+
+from app.services.security_policy_service import (
+ SETTING_ENABLED_AT,
+ SecurityPolicyService,
+)
+from app.services.setup_health_service import SetupHealthService
+
+
+def _mk_user(db, username, *, totp=False, active=True, created_days_ago=0,
+ auth_provider='local'):
+ from app.models import User
+ from werkzeug.security import generate_password_hash
+ u = User(email=f'{username}@t.local', username=username,
+ password_hash=generate_password_hash('pw'), role='developer',
+ is_active=active, totp_enabled=totp, auth_provider=auth_provider)
+ u.created_at = datetime.utcnow() - timedelta(days=created_days_ago)
+ db.session.add(u)
+ db.session.commit()
+ return u
+
+
+def _set_policy(on, *, enabled_days_ago=None):
+ """Turn the require-2FA policy on/off. When ``enabled_days_ago`` is given the
+ activation stamp is back-dated to exercise the grace window from activation."""
+ from app.services.settings_service import SettingsService
+ SecurityPolicyService.set_require_2fa(on)
+ if on and enabled_days_ago is not None:
+ stamp = (datetime.utcnow() - timedelta(days=enabled_days_ago)).isoformat()
+ SettingsService.set(SETTING_ENABLED_AT, stamp)
+
+
+def test_policy_off_is_always_ok(app):
+ """With the policy off, every account evaluates 'ok' regardless of 2FA."""
+ from app import db
+ _set_policy(False)
+ u_off = _mk_user(db, 'sec_off', totp=False, created_days_ago=0)
+ assert SecurityPolicyService.evaluate(u_off) == SecurityPolicyService.OK
+
+
+def test_veteran_account_gets_full_grace_on_policy_flip(app):
+ """Flipping the policy ON never insta-locks a long-lived account: the grace
+ window is anchored on activation, so a veteran gets the full grace → nudge."""
+ from app import db
+ veteran = _mk_user(db, 'sec_vet', totp=False, created_days_ago=400)
+ _set_policy(True) # stamps activation = now
+ assert SecurityPolicyService.evaluate(veteran) == SecurityPolicyService.NUDGE
+
+
+def test_grace_enforces_past_window_from_activation(app):
+ """Once the grace days elapse *since activation*, even a veteran account is
+ enforced (activation stamped in the past, grace exceeded)."""
+ from app import db
+ veteran = _mk_user(db, 'sec_late', totp=False, created_days_ago=400)
+ grace_later = SecurityPolicyService.GRACE_PERIOD_DAYS + 5
+ _set_policy(True, enabled_days_ago=grace_later)
+ assert SecurityPolicyService.evaluate(veteran) == SecurityPolicyService.ENFORCE
+
+
+def test_sso_account_is_exempt(app):
+ """An SSO account delegates the second factor to its IdP → policy-exempt."""
+ from app import db
+ sso = _mk_user(db, 'sec_sso', totp=False, created_days_ago=400,
+ auth_provider='oidc')
+ _set_policy(True, enabled_days_ago=SecurityPolicyService.GRACE_PERIOD_DAYS + 5)
+ assert SecurityPolicyService.evaluate(sso) == SecurityPolicyService.OK
+
+
+def test_account_security_snooze_round_trip(app, client):
+ """Dismissing the nudge snoozes ``setup.account_security`` on the account row;
+ the account endpoint then reports it snoozed, and un-snoozing clears it."""
+ from app import db
+ from flask_jwt_extended import create_access_token
+ user = _mk_user(db, 'sec_snooze', totp=False)
+ hdrs = {'Authorization': f'Bearer {create_access_token(identity=user.id)}'}
+
+ def acct_item():
+ r = client.get('/api/v1/setup-health/account', headers=hdrs)
+ assert r.status_code == 200
+ items = {c['key']: c for c in r.get_json()['items']}
+ return items['setup.account_security']
+
+ assert acct_item().get('snoozed') is not True
+
+ r = client.post('/api/v1/setup-health/snooze', headers=hdrs,
+ json={'key': 'setup.account_security'})
+ assert r.status_code == 200
+ assert acct_item()['snoozed'] is True
+
+ r = client.delete('/api/v1/setup-health/snooze', headers=hdrs,
+ json={'key': 'setup.account_security'})
+ assert r.status_code == 200
+ assert acct_item()['snoozed'] is False
diff --git a/backend/tests/test_ssh_importer.py b/backend/tests/test_ssh_importer.py
new file mode 100644
index 00000000..c5582326
--- /dev/null
+++ b/backend/tests/test_ssh_importer.py
@@ -0,0 +1,99 @@
+"""Tests for the generic SSH pull importer (Adoption/Import #12).
+
+Covers the PURE, testable layer only — no subprocess is ever spawned (the live
+rsync/mysqldump pull is Linux-only runtime and is deliberately not exercised):
+* ``parse_ssh_source`` — happy path, required-field ValueErrors, port default;
+* ``build_rsync_command`` / ``build_mysqldump_command`` argv contents,
+ including the ``None`` case and the "password never on argv" guarantee;
+* ``build_import_spec_from_survey_site`` survey — source mapping;
+* ``analyze`` on a hand-staged directory (manifest + docroot + dump);
+* ``detect`` truth on the manifest marker;
+* registry resolution of ``get_importer('ssh')``.
+
+Reconstructed from the fragmented recovery pyc
+(``test_ssh_importer.cpython-311-pytest-9.0.3.pyc``). The PURE command-builder
+layer (``build_rsync_command`` / ``build_mysqldump_command`` /
+``build_import_spec_from_survey_site``) did NOT survive the recovery rebuild —
+the surviving importer folds command construction into the instance ``pull``
+methods — so those cases skip until the builders are restored (see report
+finding).
+"""
+import pytest
+
+from app.services.site_importers import get_importer
+from app.services.site_importers.ssh import GenericSshImporter, parse_ssh_source
+
+try:
+ from app.services.site_importers.ssh import (
+ build_rsync_command, build_mysqldump_command,
+ build_import_spec_from_survey_site)
+ _NO_BUILDERS = None
+except ImportError as exc: # pure-builder layer lost in recovery
+ _NO_BUILDERS = str(exc)
+
+
+def _full_source():
+ return {
+ 'host': 'box.example.com',
+ 'user': 'deploy',
+ 'docroot': '/var/www/site/',
+ 'db_name': 'sitedb',
+ 'db_user': 'siteusr',
+ 'db_password': 's3cret',
+ 'ssh_key': '/keys/id_ed25519',
+ 'domain': 'site.example.com',
+ }
+
+
+def test_parse_ssh_source_happy_path():
+ parsed = parse_ssh_source(_full_source())
+ assert parsed['host'] == 'box.example.com'
+ assert parsed['user'] == 'deploy'
+ assert parsed['docroot'] == '/var/www/site/'
+ assert parsed['port'] == 22
+ assert parsed['domain'] == 'site.example.com'
+ assert parsed['ssh_key'] == '/keys/id_ed25519'
+ assert parsed['db_name'] == 'sitedb'
+
+
+def test_parse_ssh_source_defaults_port_and_domain():
+ parsed = parse_ssh_source({'host': 'h.example.com', 'user': 'u',
+ 'docroot': '/srv/app'})
+ assert parsed['port'] == 22
+ # domain falls back to the host when not supplied
+ assert parsed['domain'] == 'h.example.com'
+
+
[email protected]('missing', ['host', 'user', 'docroot'])
+def test_parse_ssh_source_requires_fields(missing):
+ source = {'host': 'h', 'user': 'u', 'docroot': '/d'}
+ source.pop(missing)
+ with pytest.raises(ValueError):
+ parse_ssh_source(source)
+
+
+def test_parse_ssh_source_is_keyfile_only_no_ssh_password():
+ # Auth is keyfile-only: a top-level password is never carried into the spec.
+ parsed = parse_ssh_source({'host': 'h', 'user': 'u', 'docroot': '/d',
+ 'password': 'nope'})
+ assert 'password' not in parsed
+
+
+def test_registry_resolves_ssh_importer():
+ importer = get_importer('ssh')
+ assert isinstance(importer, GenericSshImporter)
+ assert importer.format == 'ssh'
+
+
+# ── PURE command-builder layer (lost in recovery — skipped until restored) ──
+
[email protected](bool(_NO_BUILDERS),
+ reason="plan 42: hollow feature — SSH importer pure builders "
+ "(build_rsync_command/build_mysqldump_command/"
+ "build_import_spec_from_survey_site) missing after "
+ "recovery rebuild")
+def test_build_mysqldump_command_never_puts_password_on_argv():
+ argv = build_mysqldump_command(_full_source())
+ assert 's3cret' not in argv
+ assert build_mysqldump_command({'host': 'h', 'user': 'u',
+ 'docroot': '/d'}) is None
diff --git a/backend/tests/test_survey_api.py b/backend/tests/test_survey_api.py
new file mode 100644
index 00000000..62604893
--- /dev/null
+++ b/backend/tests/test_survey_api.py
@@ -0,0 +1,140 @@
+"""Survey API + permission/capability gating (plan 27 Phase 2, #5/#6).
+
+Covers the honest-degrade path (offline / old agent), the happy path (snapshot
+stored + returned), the catalog index, and the model-level permission scope that
+gates dispatch.
+
+Reconstructed for plan 42 Phase 1 from the fragmented ``test_survey_api`` pyc +
+the surviving ``survey_service`` / ``app/api/survey.py``.
+
+HOLLOW-FEATURE FINDINGS (reported to the orchestrator):
+ 1. The survey REST blueprint (``survey_bp`` in ``app/api/survey.py``) is defined
+ but NEVER registered in ``app/__init__.py`` — every ``/api/v1/servers/...``
+ survey route 404s. The recovery rebuild dropped the blueprint registration.
+ The business logic (``survey_service``) survived, so the honest-degrade /
+ happy / catalog / diff paths are exercised at the SERVICE layer below.
+ 2. The Observed-mode surface (``Server.management_mode`` / ``is_managed`` /
+ ``MANAGEMENT_MODES``) referenced by ``survey.py`` was NOT restored on the
+ ``Server`` model, so the management-mode tests are skipped with a reason.
+"""
+import pytest
+
+from app.services import survey_service
+
+
+def _mk_server(db, name='observed-box'):
+ from app.models.server import Server
+ s = Server(name=name)
+ db.session.add(s)
+ db.session.commit()
+ return s
+
+
+def _patch_agent(monkeypatch, *, connected=True, capable=True, result=None):
+ """Point survey_service's agent_registry at a fake connected/capable agent."""
+ from app.services import agent_registry as reg_mod
+ reg = reg_mod.agent_registry
+ monkeypatch.setattr(reg, 'is_agent_connected', lambda sid: connected)
+ monkeypatch.setattr(reg, 'get_capabilities', lambda sid: {'survey': capable})
+ monkeypatch.setattr(
+ reg, 'send_command',
+ lambda sid, action, params, user_id=None, timeout=None: (
+ result if result is not None else {'success': True, 'data': {}}))
+
+
+# --- model-level permission scope (survives) -------------------------------- #
+
+def test_survey_read_scope_gates_dispatch(app):
+ """A server granted the ``survey:read`` scope passes has_permission; one
+ without it does not — the scope that gates survey dispatch."""
+ from app.models.server import Server
+ granted = Server(name='granted', permissions=['survey:read'])
+ denied = Server(name='denied', permissions=['docker:container:read'])
+ assert granted.has_permission('survey:read') is True
+ assert denied.has_permission('survey:read') is False
+
+
+# --- catalog index (service surface behind the endpoint) -------------------- #
+
+def test_probe_index_catalog(app):
+ body = survey_service.probe_index()
+ assert body['version'] == survey_service.catalog_version()
+ ids = {p['id'] for p in body['probes']}
+ assert 'nginx' in ids and 'foreign-panel' in ids
+
+
+# --- honest-degrade path ---------------------------------------------------- #
+
+def test_run_survey_degrades_when_agent_offline(app, db_session):
+ server = _mk_server(db_session)
+ result, error = survey_service.run_survey(server.id)
+ assert result is None
+ assert error['code'] == 'AGENT_OFFLINE' and error['status'] == 503
+
+
+def test_run_survey_degrades_when_agent_uncapable(app, db_session, monkeypatch):
+ server = _mk_server(db_session)
+ _patch_agent(monkeypatch, connected=True, capable=False)
+ result, error = survey_service.run_survey(server.id)
+ assert result is None
+ assert error['code'] == 'SURVEY_UNSUPPORTED' and error['status'] == 409
+
+
+# --- happy path (snapshot stored + returned) -------------------------------- #
+
+def test_run_survey_stores_and_returns_snapshot(app, db_session, monkeypatch):
+ server = _mk_server(db_session)
+ payload = {
+ 'catalog_version': 1,
+ 'probes': {
+ 'nginx': {'detected': True, 'service': {'active': True, 'ports': [80]},
+ 'vhosts': [{'server_name': 'example.com', 'root': '/var/www/example'}]},
+ 'foreign-panel': {'detected': True, 'markers': ['/usr/local/cpanel']},
+ },
+ }
+ _patch_agent(monkeypatch, result={'success': True, 'data': payload})
+ result, error = survey_service.run_survey(server.id)
+ assert error is None and result is not None
+
+ stored = survey_service.list_surveys(server.id)
+ assert len(stored) == 1
+ latest = survey_service.latest_survey(server.id).get_map()
+ assert latest['catalog_version'] == 1
+ assert any(s['id'] == 'nginx' for s in latest['services'])
+ assert latest['foreign_panel_detected'] is True
+
+
+# --- diff (service surface behind /surveys/diff) ---------------------------- #
+
+def test_diff_maps_reports_removed_service(app):
+ old = {'catalog_version': 1, 'services': [{'id': 'nginx', 'active': True, 'ports': [80]}]}
+ new = {'catalog_version': 1, 'services': []}
+ diff = survey_service.diff_maps(old, new)
+ removed = {row['id'] for row in diff['services']['removed']}
+ assert 'nginx' in removed
+
+
+# --- HOLLOW: Observed-mode surface lost in the recovery rebuild ------------- #
+
[email protected](reason="plan 42: hollow — Server.is_managed lost in recovery "
+ "rebuild (plan 27/31 Observed mode column gone)")
+def test_is_managed_property():
+ pass
+
+
[email protected](reason="plan 42: hollow — Server.management_mode / MANAGEMENT_MODES "
+ "lost + survey_bp unregistered (plan 27/31)")
+def test_switch_management_mode():
+ pass
+
+
[email protected](reason="plan 42: hollow — Server.management_mode lost; mode-validation "
+ "branch unreachable + survey_bp unregistered (plan 27/31)")
+def test_switch_management_mode_rejects_bad_value():
+ pass
+
+
[email protected](reason="plan 42: hollow — Server.to_dict no longer emits management "
+ "mode (plan 27/31 column gone)")
+def test_server_to_dict_includes_mode():
+ pass
diff --git a/backend/tests/test_survey_catalog.py b/backend/tests/test_survey_catalog.py
new file mode 100644
index 00000000..d7f70685
--- /dev/null
+++ b/backend/tests/test_survey_catalog.py
@@ -0,0 +1,92 @@
+"""Probe catalog lint + index (plan 27 Phase 2, #3/#6).
+
+The shipped catalog must load and lint clean; malformed catalogs must fail loudly
+(a survey that quietly checks nothing is worse than a crash), and the index the
+UI shows must reflect exactly the catalog's declared locations.
+
+Reconstructed for plan 42 Phase 1 from the clean ``test_survey_catalog`` pyc.
+The survey feature SURVIVED but its contract evolved since the pyc was built:
+``lint_catalog`` now returns the catalog (not ``True``), required probe fields are
+``id/kind/title/reads`` and the operator index publishes ``reads`` (not the old
+``locations`` key). The reconstructed positive/index assertions track the current
+contract; the reject cases are unchanged (they still raise loudly).
+"""
+import pytest
+
+from app.services import survey_service
+from app.services.survey_service import SurveyError, lint_catalog
+
+
+def test_shipped_catalog_loads_and_lints():
+ catalog = survey_service.load_catalog(force=True)
+ assert lint_catalog(catalog) == catalog
+ assert catalog['version'] >= 1
+ assert isinstance(catalog['probes'], list) and catalog['probes']
+ ids = {p['id'] for p in catalog['probes']}
+ assert 'foreign-panel' in ids
+ assert 'nginx' in ids
+
+
+def test_catalog_version_and_index_agree():
+ idx = survey_service.probe_index()
+ assert idx['version'] == survey_service.catalog_version()
+ for probe in idx['probes']:
+ assert probe['id']
+ assert 'title' in probe
+ assert 'reads' in probe
+ marker = next(p for p in idx['probes'] if p['id'] == 'foreign-panel')
+ assert marker['reads'], 'index probe must publish what it reads'
+
+
+def test_lint_rejects_non_mapping():
+ with pytest.raises(SurveyError):
+ lint_catalog([])
+
+
+def test_lint_rejects_bad_version():
+ with pytest.raises(SurveyError):
+ lint_catalog({'version': 0, 'probes': [{'id': 'x'}]})
+ with pytest.raises(SurveyError):
+ lint_catalog({'version': 'one', 'probes': [{'id': 'x'}]})
+
+
+def test_lint_rejects_empty_probes():
+ with pytest.raises(SurveyError):
+ lint_catalog({'version': 1, 'probes': []})
+
+
+def test_lint_rejects_duplicate_ids():
+ with pytest.raises(SurveyError):
+ lint_catalog({'version': 1, 'probes': [{'id': 'a'}, {'id': 'a'}]})
+
+
+def test_lint_rejects_missing_id():
+ with pytest.raises(SurveyError):
+ lint_catalog({'version': 1, 'probes': [{'kind': 'service'}]})
+
+
+def test_lint_rejects_unknown_detect_key():
+ with pytest.raises(SurveyError):
+ lint_catalog({'version': 1, 'probes': [{'id': 'a', 'detect': {'exec': 'rm -rf /'}}]})
+
+
+def test_lint_rejects_marker_without_paths():
+ with pytest.raises(SurveyError):
+ lint_catalog({'version': 1, 'probes': [
+ {'id': 'panel', 'kind': 'marker', 'detect': {'units': ['x']}}]})
+
+
+def test_lint_accepts_valid_minimal_catalog():
+ catalog = {
+ 'version': 2,
+ 'probes': [
+ {'id': 'nginx', 'kind': 'service+config', 'title': 'Nginx',
+ 'reads': 'service status + vhosts',
+ 'detect': {'ports': [80], 'units': ['nginx']},
+ 'map': {'vhosts': ['/etc/nginx/sites-enabled/*']}},
+ {'id': 'panel', 'kind': 'marker', 'title': 'Other panel',
+ 'reads': 'marker directories',
+ 'detect': {'paths': ['/usr/local/cpanel']}},
+ ],
+ }
+ assert lint_catalog(catalog) == catalog
diff --git a/backend/tests/test_workspace_scoping_matrix.py b/backend/tests/test_workspace_scoping_matrix.py
new file mode 100644
index 00000000..46c2787b
--- /dev/null
+++ b/backend/tests/test_workspace_scoping_matrix.py
@@ -0,0 +1,113 @@
+"""The canonical workspace-scoping RBAC matrix (plan 19 Phase 1 #4).
+
+Five personas (owner / member / viewer / foreign / panel admin) driven by the
+shared ``scoping_rbac`` fixture (conftest.py), applied to the reference app.
+
+The membership visibility contract (plan 19 Decision 1):
+ - owner / member / viewer / admin SEE the workspace's apps and their domains
+ - a foreign non-member sees NOTHING here
+
+Reconstructed for plan 42 Phase 1 from the readable shadow tail + the fragmented
+``test_workspace_scoping_matrix`` pyc + the surviving ``resource_grant_service``.
+The current ``scoping_rbac`` fixture exposes per-persona auth headers + ``app_id``
+(not the ``*_id`` / ``domain_id`` the original pyc used), so persona user rows are
+resolved by their well-known usernames and the reference domain is created inline.
+
+DRIFT FINDING (reported to the orchestrator): the plan-19 *member-write* /
+*member-visibility* seam did NOT survive at the ROUTE layer. ``can_operate_app``
+still folds workspace membership (the matrix below passes), but the env-var,
+backup-policy and /apps-list routes gate on ``can_edit_app`` / owner-or-grant, so a
+plain workspace member is denied there. Those route-level tests are skipped with a
+reason rather than inverted.
+"""
+import pytest
+
+from app.services.resource_grant_service import ResourceGrantService as R
+
+
+def _user(username):
+ from app.models import User
+ return User.query.filter_by(username=username).first()
+
+
+def test_operate_and_admin_capability_matrix(app, scoping_rbac):
+ from app.models import Application
+ a = Application.query.get(scoping_rbac.app_id)
+
+ def operate(username):
+ return R.can_operate_app(_user(username), a)
+
+ def admin(username):
+ return R.can_admin_app(_user(username), a)
+
+ # Member-write: owner/panel-admin/member yes; viewer & foreign no.
+ assert operate('scope_owner') is True
+ assert operate('scope_admin') is True
+ assert operate('scope_member') is True
+ assert operate('scope_viewer') is False
+ assert operate('scope_foreign') is False
+
+ # Destructive: owner/panel-admin yes; a plain workspace MEMBER cannot; viewer/foreign no.
+ assert admin('scope_owner') is True
+ assert admin('scope_admin') is True
+ assert admin('scope_member') is False
+ assert admin('scope_viewer') is False
+ assert admin('scope_foreign') is False
+
+
+def test_delete_app_denied_to_member_and_below(client, scoping_rbac):
+ """Deleting an app is destructive: a plain workspace member, viewer, and
+ foreign caller are all denied (only admin/owner may — not exercised here to
+ avoid tearing down the fixture)."""
+ url = f'/api/v1/apps/{scoping_rbac.app_id}'
+ for persona in ('member', 'viewer', 'foreign'):
+ assert client.delete(url, headers=getattr(scoping_rbac, persona)).status_code == 403, persona
+
+
+def test_delete_domain_denied_to_member_and_below(client, scoping_rbac):
+ """Deleting a domain is destructive → admin/owner only; member/viewer/foreign 403."""
+ from app import db
+ from app.models import Domain
+ d = Domain(name='scope.example.com', application_id=scoping_rbac.app_id)
+ db.session.add(d)
+ db.session.commit()
+ url = f'/api/v1/domains/{d.id}'
+ for persona in ('member', 'viewer', 'foreign'):
+ assert client.delete(url, headers=getattr(scoping_rbac, persona)).status_code == 403, persona
+
+
+# --------------------------------------------------------------------------- #
+# #16 — the bucket-header gate. SUPERSEDED (plan 29 #10) by the generic AST sweep
+# in test_authz_structural_sweep.py, which checks EVERY per-app route file for a
+# `# Bucket:` header. This thin alias is retained so the old name still runs.
+# --------------------------------------------------------------------------- #
+
+def test_governed_route_files_declare_a_bucket():
+ from test_authz_structural_sweep import test_every_per_app_route_file_declares_a_bucket
+ test_every_per_app_route_file_declares_a_bucket()
+
+
+# --------------------------------------------------------------------------- #
+# Route-level member-write / member-visibility — DRIFTED OUT (see module docstring).
+# Skipped with reason; the surviving capability is proven by the matrix above.
+# --------------------------------------------------------------------------- #
+
[email protected](reason="plan 42: drift — /apps list gates on own-rows/grant, not "
+ "workspace membership; member/viewer no longer see the "
+ "workspace app (plan 19 Decision 1 not wired at route layer)")
+def test_apps_list_visible_to_workspace():
+ pass
+
+
[email protected](reason="plan 42: drift — env-var writes gate on can_edit_app "
+ "(owner/admin/editor-grant), not can_operate_app; a plain "
+ "workspace member is denied (plan 19 #14 not wired at route)")
+def test_env_write_member_can_viewer_cannot():
+ pass
+
+
[email protected](reason="plan 42: drift — backup-policy edits gate on can_edit_app, "
+ "not can_operate_app; a plain workspace member is denied "
+ "(plan 19 member-write not wired at route layer)")
+def test_backup_policy_edit_member_can_viewer_cannot():
+ pass