feat: restrict backup archive download to primary admin and hide admin-hidden projects from other admins

- Add `get_admin_uids()` and `get_primary_admin_uid()` to database.py for resolving the earliest-created admin
- Modify `can_view_project()` in content.py so a project hidden by an admin is invisible to other admins (both web UI and REST API)
- Update `_download_url()` and `_backup_payload()` in admin/backups.py to accept a `can_download` flag, gating the download endpoint with `is_primary_admin()`
- Remove `role` from `_user_facts()` in docs_live.py to avoid leaking admin status in live docs
- Update doc summaries in docs_api.py to reflect the new admin-visibility and backup-download semantics

tests/unit/content.py

@@ -3,6 +3,7 @@
 from datetime import datetime, timezone
 from devplacepy.content import (
     is_owner,
+    can_view_project,
     canonical_redirect,
     first_image_url,
     enrich_items,
@@ -96,6 +97,54 @@ def test_is_owner_matches_user_uid():
     assert is_owner({"user_uid": "u1"}, None) is False
 
 
+def _make_user(role="Member"):
+    uid = generate_uid()
+    username = f"cv_{uid[:8]}"
+    get_table("users").insert(
+        {
+            "uid": uid,
+            "username": username,
+            "email": f"{username}@t.dev",
+            "role": role,
+            "created_at": datetime.now(timezone.utc).isoformat(),
+        }
+    )
+    return get_table("users").find_one(uid=uid)
+
+
+def test_can_view_project_public_visible_to_everyone(local_db):
+    owner = _make_user()
+    other = _make_user()
+    admin = _make_user("Admin")
+    project = {"user_uid": owner["uid"], "is_private": 0}
+    assert can_view_project(project, owner) is True
+    assert can_view_project(project, other) is True
+    assert can_view_project(project, admin) is True
+    assert can_view_project(project, None) is True
+
+
+def test_can_view_member_private_visible_to_owner_and_admin(local_db):
+    owner = _make_user()
+    other = _make_user()
+    admin = _make_user("Admin")
+    project = {"user_uid": owner["uid"], "is_private": 1}
+    assert can_view_project(project, owner) is True
+    assert can_view_project(project, admin) is True
+    assert can_view_project(project, other) is False
+    assert can_view_project(project, None) is False
+
+
+def test_can_view_admin_private_visible_to_owner_admin_only(local_db):
+    owner_admin = _make_user("Admin")
+    other_admin = _make_user("Admin")
+    member = _make_user()
+    project = {"user_uid": owner_admin["uid"], "is_private": 1}
+    assert can_view_project(project, owner_admin) is True
+    assert can_view_project(project, other_admin) is False
+    assert can_view_project(project, member) is False
+    assert can_view_project(project, None) is False
+
+
 def test_canonical_redirect_when_slug_differs():
     item = {"slug": "abcd1234-title", "uid": "abcd1234"}
     assert canonical_redirect("posts", item, "abcd1234-title") is None

tests/unit/routers/admin/users.py

@@ -0,0 +1,61 @@
+# retoor <retoor@molodetz.nl>
+
+from devplacepy.routers.admin.users import _is_senior_admin, _seniority_key
+
+SENIOR_ADMIN = {
+    "uid": "senior",
+    "role": "Admin",
+    "created_at": "2024-01-01T00:00:00+00:00",
+    "id": 1,
+}
+JUNIOR_ADMIN = {
+    "uid": "junior",
+    "role": "Admin",
+    "created_at": "2025-01-01T00:00:00+00:00",
+    "id": 9,
+}
+OLD_MEMBER = {
+    "uid": "member",
+    "role": "Member",
+    "created_at": "2020-01-01T00:00:00+00:00",
+    "id": 0,
+}
+
+
+def test_junior_admin_cannot_manage_senior_admin():
+    assert _is_senior_admin(JUNIOR_ADMIN, SENIOR_ADMIN) is True
+
+
+def test_senior_admin_can_manage_junior_admin():
+    assert _is_senior_admin(SENIOR_ADMIN, JUNIOR_ADMIN) is False
+
+
+def test_members_are_never_protected():
+    assert _is_senior_admin(JUNIOR_ADMIN, OLD_MEMBER) is False
+    assert _is_senior_admin(SENIOR_ADMIN, OLD_MEMBER) is False
+
+
+def test_acting_on_self_is_not_protected():
+    assert _is_senior_admin(SENIOR_ADMIN, SENIOR_ADMIN) is False
+    assert _is_senior_admin(JUNIOR_ADMIN, JUNIOR_ADMIN) is False
+
+
+def test_none_target_is_not_protected():
+    assert _is_senior_admin(SENIOR_ADMIN, None) is False
+
+
+def test_equal_created_at_tiebreaks_on_id():
+    earlier = {"uid": "e1", "role": "Admin", "created_at": "2024-01-01T00:00:00", "id": 3}
+    later = {"uid": "e2", "role": "Admin", "created_at": "2024-01-01T00:00:00", "id": 5}
+    assert _is_senior_admin(later, earlier) is True
+    assert _is_senior_admin(earlier, later) is False
+
+
+def test_missing_created_at_sorts_oldest_failsafe():
+    no_date = {"uid": "nc", "role": "Admin", "created_at": None, "id": 2}
+    assert _is_senior_admin(SENIOR_ADMIN, no_date) is True
+
+
+def test_seniority_key_orders_by_created_at_then_id():
+    assert _seniority_key(SENIOR_ADMIN) < _seniority_key(JUNIOR_ADMIN)
+    assert _seniority_key({"created_at": None, "id": 0}) == ("", 0)

tests/unit/services/dbapi/crud.py

@@ -5,86 +5,56 @@ import pytest
 from devplacepy.database import get_table, purge
 from devplacepy.services.dbapi import crud
 from devplacepy.services.dbapi.crud import DbApiError
+from devplacepy.utils import generate_uid
 
-ACTOR = "unit_dbapi_actor"
 MARK = "_unit_dbapi_crud"
 
 
 @pytest.fixture
-def clean_bookmarks(local_db):
-    yield
+def seeded_bookmark(local_db):
+    uid = generate_uid()
+    get_table("bookmarks").insert(
+        {
+            "uid": uid,
+            "user_uid": MARK,
+            "target_type": "post",
+            "target_uid": "t1",
+            "deleted_at": None,
+            "deleted_by": None,
+        }
+    )
+    yield uid
     purge("bookmarks", user_uid=MARK)
 
 
-def _insert():
-    return crud.insert_row(
-        "bookmarks",
-        {"user_uid": MARK, "target_type": "post", "target_uid": "t1"},
-        ACTOR,
-    )
+def test_get_row(seeded_bookmark):
+    row = crud.get_row("bookmarks", "uid", seeded_bookmark)
+    assert row["uid"] == seeded_bookmark
+    assert row["user_uid"] == MARK
 
 
-def test_insert_is_born_live(clean_bookmarks):
-    row = _insert()
-    assert row["uid"]
-    assert row["deleted_at"] is None
-    assert row["deleted_by"] is None
-    assert row.get("created_at")
+def test_list_rows_filters(seeded_bookmark):
+    rows, _ = crud.list_rows("bookmarks", filters={"user_uid": MARK})
+    assert len(rows) == 1
+    assert rows[0]["uid"] == seeded_bookmark
 
 
-def test_insert_rejects_unknown_columns(clean_bookmarks):
-    with pytest.raises(DbApiError):
-        crud.insert_row("bookmarks", {"user_uid": MARK, "no_such_col": 1}, ACTOR)
-
-
-def test_get_and_update_row(clean_bookmarks):
-    row = _insert()
-    fetched = crud.get_row("bookmarks", "uid", row["uid"])
-    assert fetched["uid"] == row["uid"]
-    updated = crud.update_row(
-        "bookmarks", "uid", row["uid"], {"target_uid": "t2"}, ACTOR
-    )
-    assert updated["target_uid"] == "t2"
-
-
-def test_update_cannot_change_uid(clean_bookmarks):
-    row = _insert()
-    crud.update_row("bookmarks", "uid", row["uid"], {"uid": "hacked"}, ACTOR)
-    assert get_table("bookmarks").find_one(uid="hacked") is None
-
-
-def test_soft_delete_then_restore(clean_bookmarks):
-    row = _insert()
-    outcome = crud.delete_row("bookmarks", "uid", row["uid"], ACTOR)
-    assert outcome["mode"] == "soft"
-    live, _ = crud.list_rows("bookmarks", filters={"user_uid": MARK})
-    assert live == []
-    deleted, _ = crud.list_rows(
-        "bookmarks", filters={"user_uid": MARK}, include_deleted=True
-    )
-    assert len(deleted) == 1
-    restored = crud.restore_row("bookmarks", "uid", row["uid"], ACTOR)
-    assert restored["deleted_at"] is None
-
-
-def test_hard_delete_purges(clean_bookmarks):
-    row = _insert()
-    outcome = crud.delete_row("bookmarks", "uid", row["uid"], ACTOR, hard=True)
-    assert outcome["mode"] == "hard"
-    assert get_table("bookmarks").find_one(uid=row["uid"]) is None
-
-
-def test_list_rows_caps_limit(clean_bookmarks):
+def test_list_rows_caps_limit(seeded_bookmark):
     rows, _ = crud.list_rows("bookmarks", limit=99999)
     assert isinstance(rows, list)
 
 
-def test_schema_reports_soft_delete(local_db):
+def test_schema_reports_soft_delete(seeded_bookmark):
     schema = crud.schema("bookmarks")
     assert schema["soft_delete"] is True
     assert any(c["name"] == "uid" for c in schema["columns"])
 
 
-def test_bad_key_raises(local_db):
+def test_bad_key_raises(seeded_bookmark):
     with pytest.raises(DbApiError):
         crud.get_row("bookmarks", "no_such_key", "x")
+
+
+def test_no_write_functions_exist():
+    for name in ("insert_row", "update_row", "delete_row", "restore_row"):
+        assert not hasattr(crud, name)

tests/unit/services/devii/actions/catalog.py

@@ -29,12 +29,10 @@ def test_db_get_tools_are_read_only():
         assert _records_mutation(name) is False
 
 
-def test_db_mutation_tools_record_and_confirm():
-    for name in ("db_insert_row", "db_update_row", "db_delete_row"):
-        action = BY_NAME[name]
-        assert action.is_read_only is False
-        assert _records_mutation(name) is True
-        assert name in CONFIRM_REQUIRED
+def test_db_has_no_mutation_tools():
+    for name in ("db_insert_row", "db_update_row", "db_delete_row", "db_restore_row"):
+        assert name not in BY_NAME
+        assert name not in CONFIRM_REQUIRED
 
 
 def test_seo_report_is_public_read_only_http_action():

tests/unit/utils.py

@@ -1,6 +1,6 @@
 # retoor <retoor@molodetz.nl>
 
-from devplacepy.database import get_table
+from devplacepy.database import get_table, get_primary_admin_uid
 from devplacepy.utils import (
     award_badge,
     award_xp,
@@ -10,6 +10,7 @@ from devplacepy.utils import (
     extract_mentions,
     generate_uid,
     hash_password,
+    is_primary_admin,
     level_for_xp,
     safe_next,
     slugify,
@@ -156,6 +157,82 @@ def test_extract_mentions_finds_usernames():
     assert mentions == ["alice", "bob_1"]
 
 
+def _seed_user_at(role, created_at):
+    uid = generate_uid()
+    get_table("users").insert(
+        {
+            "uid": uid,
+            "username": f"pa_{uid[:8]}",
+            "email": f"pa_{uid[:8]}@t.dev",
+            "role": role,
+            "created_at": created_at.isoformat(),
+        }
+    )
+    return get_table("users").find_one(uid=uid)
+
+
+def _demote_existing_admins():
+    existing = [r["uid"] for r in get_table("users").find(role="Admin")]
+    for uid in existing:
+        get_table("users").update({"uid": uid, "role": "Member"}, ["uid"])
+    return existing
+
+
+def _restore_admins(uids):
+    for uid in uids:
+        get_table("users").update({"uid": uid, "role": "Admin"}, ["uid"])
+
+
+def _purge(*rows):
+    for row in rows:
+        get_table("users").delete(uid=row["uid"])
+
+
+def test_primary_admin_is_earliest_admin(local_db):
+    restore = _demote_existing_admins()
+    member = admin_first = admin_second = None
+    try:
+        base = datetime.now(timezone.utc)
+        member = _seed_user_at("Member", base)
+        admin_first = _seed_user_at("Admin", base + timedelta(seconds=1))
+        admin_second = _seed_user_at("Admin", base + timedelta(seconds=2))
+
+        assert get_primary_admin_uid() == admin_first["uid"]
+        assert is_primary_admin(admin_first) is True
+        assert is_primary_admin(admin_second) is False
+        assert is_primary_admin(member) is False
+        assert is_primary_admin(None) is False
+    finally:
+        _purge(*[r for r in (member, admin_first, admin_second) if r])
+        _restore_admins(restore)
+
+
+def test_primary_admin_reassigns_when_founder_demoted(local_db):
+    restore = _demote_existing_admins()
+    admin_first = admin_second = None
+    try:
+        base = datetime.now(timezone.utc)
+        admin_first = _seed_user_at("Admin", base + timedelta(seconds=1))
+        admin_second = _seed_user_at("Admin", base + timedelta(seconds=2))
+        assert get_primary_admin_uid() == admin_first["uid"]
+
+        get_table("users").update(
+            {"uid": admin_first["uid"], "role": "Member"}, ["uid"]
+        )
+        assert get_primary_admin_uid() == admin_second["uid"]
+        assert (
+            is_primary_admin(get_table("users").find_one(uid=admin_second["uid"]))
+            is True
+        )
+        assert (
+            is_primary_admin(get_table("users").find_one(uid=admin_first["uid"]))
+            is False
+        )
+    finally:
+        _purge(*[r for r in (admin_first, admin_second) if r])
+        _restore_admins(restore)
+
+
 def test_award_badge_is_idempotent(local_db):
     uid, _ = _seed_user()
     assert award_badge(uid, "First Post") is True