fix: add audited macOS beta emergency rollback (#10051)

## Summary

- add an explicit, admin-authenticated emergency rollback operation
restricted to the macOS beta pointer;
- require a registered, passed-T2, strictly earlier release plus exact
current release/generation CAS;
- write an immutable rollback audit record transactionally before
replacing only the beta pointer;
- retain normal roll-forward-only promotion and Stable/production
isolation.

## Verification

- `/Users/dazheng/workspace/omi/backend/.venv/bin/python -m pytest
tests/unit/test_desktop_update_channels.py
tests/unit/test_desktop_updates.py -q` — 109 passed.
- Independent security/correctness review confirmed beta-only scope,
target qualification, transactional CAS, immutable audit semantics, and
no Stable/prod mutation path.

Failure-Class: none


<!-- This is an auto-generated description by cubic. -->
<a
href="https://cubic.dev/pr/BasedHardware/omi/pull/10051?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->

Author: Git-on-my-level

backend/database/desktop_update_channels.py

@@ -4,13 +4,15 @@
 import re
 from typing import Any, cast
 from urllib.parse import urlparse
+from uuid import uuid4
 
 from google.cloud.firestore import transactional
 
 from database._client import get_firestore_client
 
 CHANNELS_COLLECTION = "desktop_update_channels"
 MANIFESTS_COLLECTION = "desktop_release_manifests"
+ROLLBACK_AUDITS_COLLECTION = "desktop_update_channel_rollback_audits"
 VALID_CHANNELS = frozenset({"stable", "beta"})
 VALID_PLATFORMS = frozenset({"macos", "windows", "linux"})
 SHA40_RE = re.compile(r"^[0-9a-f]{40}$", re.IGNORECASE)
@@ -182,6 +184,46 @@ def _build_channel_pointer(
     }
 
 
+def _build_beta_rollback_pointer(
+    current: dict[str, Any],
+    manifest: dict[str, Any],
+    *,
+    release_id: str,
+    expected_current_release_id: str,
+    expected_generation: int,
+    updated_at: datetime | None = None,
+) -> dict[str, Any]:
+    """Build the sole permitted non-monotonic pointer transition: macOS beta rollback."""
+    if manifest["platform"] != "macos":
+        raise ValueError("rollback target must be a macos release manifest")
+    qualification = cast(dict[str, Any], manifest["qualification"])
+    if qualification.get("passed") is not True or str(qualification.get("tier", "")).upper() != "T2":
+        raise ValueError("rollback target is missing passed T2 qualification evidence")
+
+    current_release_id = current.get("release_id")
+    if current_release_id != expected_current_release_id:
+        raise ValueError(
+            f"current release mismatch: expected {expected_current_release_id}, current {current_release_id or 'missing'}"
+        )
+    current_generation = _generation(current.get("generation", 0))
+    if expected_generation != current_generation:
+        raise ValueError(f"generation mismatch: expected {expected_generation}, current {current_generation}")
+
+    current_build = _generation(current.get("build_number"))
+    if release_id == current_release_id or manifest["build_number"] >= current_build:
+        raise ValueError("rollback target must be an earlier qualified beta release")
+
+    return {
+        "platform": "macos",
+        "channel": "beta",
+        "release_id": release_id,
+        "version": manifest["version"],
+        "build_number": manifest["build_number"],
+        "generation": current_generation + 1,
+        "updated_at": updated_at or datetime.now(timezone.utc),
+    }
+
+
 @transactional
 def _promote_channel_transaction(
     transaction: Any,
@@ -249,6 +291,92 @@ def promote_channel(
     )
 
 
+@transactional
+def _rollback_macos_beta_transaction(
+    transaction: Any,
+    pointer_ref: Any,
+    manifest_ref: Any,
+    audit_ref: Any,
+    *,
+    release_id: str,
+    expected_current_release_id: str,
+    expected_generation: int,
+    audit_id: str,
+    occurred_at: datetime,
+) -> dict[str, Any]:
+    manifest_snapshot = manifest_ref.get(transaction=transaction)
+    if not getattr(manifest_snapshot, "exists", False):
+        raise ValueError("rollback target release manifest does not exist")
+    raw_manifest: object = manifest_snapshot.to_dict()
+    manifest_data = cast(dict[str, Any], raw_manifest) if isinstance(raw_manifest, dict) else {}
+    manifest = normalize_release_manifest(manifest_data)
+
+    pointer_snapshot = pointer_ref.get(transaction=transaction)
+    if not getattr(pointer_snapshot, "exists", False):
+        raise ValueError("current macos beta pointer does not exist")
+    current_raw: object = pointer_snapshot.to_dict()
+    current = cast(dict[str, Any], current_raw) if isinstance(current_raw, dict) else {}
+    pointer = _build_beta_rollback_pointer(
+        current,
+        manifest,
+        release_id=release_id,
+        expected_current_release_id=expected_current_release_id,
+        expected_generation=expected_generation,
+        updated_at=occurred_at,
+    )
+    audit = {
+        "audit_id": audit_id,
+        "operation": "macos_beta_rollback",
+        "platform": "macos",
+        "channel": "beta",
+        "previous_release_id": expected_current_release_id,
+        "previous_generation": expected_generation,
+        "target_release_id": release_id,
+        "generation": pointer["generation"],
+        "occurred_at": occurred_at,
+    }
+    # create() provides an immutable, append-only audit record. All reads above
+    # occur before this first transactional write.
+    transaction.create(audit_ref, audit)
+    transaction.set(pointer_ref, pointer)
+    return {"pointer": pointer, "audit": audit}
+
+
+def rollback_macos_beta_channel(
+    release_id: str,
+    *,
+    expected_current_release_id: str,
+    expected_generation: int,
+    firestore_client: Any = None,
+) -> dict[str, Any]:
+    """Atomically roll macOS beta back to an earlier, qualified registered release only."""
+    release_id = release_id.strip()
+    expected_current_release_id = expected_current_release_id.strip()
+    if not release_id:
+        raise ValueError("release_id is required")
+    if not expected_current_release_id:
+        raise ValueError("expected_current_release_id is required")
+    if expected_generation < 0:
+        raise ValueError("expected_generation must be a non-negative integer")
+
+    client = firestore_client if firestore_client is not None else get_firestore_client()
+    pointer_ref = client.collection(CHANNELS_COLLECTION).document("macos-beta")
+    manifest_ref = client.collection(MANIFESTS_COLLECTION).document(release_id)
+    audit_id = uuid4().hex
+    audit_ref = client.collection(ROLLBACK_AUDITS_COLLECTION).document(audit_id)
+    return _rollback_macos_beta_transaction(
+        client.transaction(),
+        pointer_ref,
+        manifest_ref,
+        audit_ref,
+        release_id=release_id,
+        expected_current_release_id=expected_current_release_id,
+        expected_generation=expected_generation,
+        audit_id=audit_id,
+        occurred_at=datetime.now(timezone.utc),
+    )
+
+
 def get_channel_release(platform: str, channel: str, *, firestore_client: Any = None) -> dict[str, Any] | None:
     """Resolve one explicit channel pointer to its immutable manifest."""
     if platform not in VALID_PLATFORMS or channel not in VALID_CHANNELS:

backend/route_policy_manifest.yaml

@@ -116,6 +116,28 @@ routes:
       data_domain: desktop_updates
       deprecation:
         state: active
+  - route_type: http
+    method: POST
+    path: /v2/desktop/channels/rollback
+    policy:
+      review_status: reviewed
+      auth:
+        mechanisms:
+          - admin_key
+        placement: inline
+        scopes: []
+      byok: not_applicable
+      rate_limit:
+        policy_name: none
+        key_subject: none
+        enforcement: none
+        placement: none
+      timeout_class: default_method
+      surface: desktop_update
+      visibility: admin
+      data_domain: desktop_updates
+      deprecation:
+        state: active
   - route_type: http
     method: POST
     path: /v2/desktop/channels/promote

backend/routers/updates.py

@@ -4,15 +4,15 @@
 import os
 import random
 import re
-from typing import Any, Optional, List, Dict
+from typing import Any, Optional, List, Dict, Literal
 from xml.sax.saxutils import escape as xml_escape
 
 from fastapi import APIRouter, HTTPException, Header, Query
 from fastapi.responses import RedirectResponse, Response, HTMLResponse
 from pydantic import BaseModel, Field
 
 from database.desktop_previews import delist_preview, get_current_preview, get_preview_manifest, publish_preview
-from database.desktop_update_channels import promote_channel, register_release_manifest
+from database.desktop_update_channels import promote_channel, register_release_manifest, rollback_macos_beta_channel
 from database.desktop_update_policy import default_desktop_update_policy, get_desktop_update_policy
 from database.redis_db import delete_generic_cache
 from utils.desktop_update_resolver import live_cache_key, resolve_pointer_release
@@ -78,6 +78,16 @@ class DesktopChannelPromotionRequest(BaseModel):
     expected_generation: Optional[int] = Field(default=None, ge=0)
 
 
+class DesktopBetaRollbackRequest(BaseModel):
+    """Emergency-only rollback request; the literal fields prevent cross-channel reuse."""
+
+    platform: Literal["macos"]
+    channel: Literal["beta"]
+    release_id: str = Field(min_length=1)
+    expected_current_release_id: str = Field(min_length=1)
+    expected_generation: int = Field(ge=0)
+
+
 class DesktopPreviewPublishRequest(BaseModel):
     """Immutable metadata for a signed desktop preview artifact."""
 
@@ -886,3 +896,22 @@ async def promote_desktop_channel(request: DesktopChannelPromotionRequest, secre
         live_cache_key(request.platform, request.channel),
     )
     return {"success": True, "pointer": pointer}
+
+
+@router.post("/v2/desktop/channels/rollback")
+async def rollback_macos_beta_channel_endpoint(request: DesktopBetaRollbackRequest, secret_key: str = Header(...)):
+    """Emergency-only, compare-and-swap rollback for the macOS beta pointer."""
+    if secret_key != os.getenv('ADMIN_KEY'):
+        raise HTTPException(status_code=403, detail='You are not authorized to perform this action')
+    try:
+        result = await run_blocking(
+            db_executor,
+            rollback_macos_beta_channel,
+            request.release_id,
+            expected_current_release_id=request.expected_current_release_id,
+            expected_generation=request.expected_generation,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    await run_blocking(db_executor, delete_generic_cache, live_cache_key("macos", "beta"))
+    return {"success": True, **result}

backend/tests/unit/test_desktop_update_channels.py

@@ -4,6 +4,8 @@
 
 from database.desktop_update_channels import (
     _build_channel_pointer,
+    _build_beta_rollback_pointer,
+    _rollback_macos_beta_transaction,
     get_channel_release,
     normalize_release_manifest,
     register_release_manifest,
@@ -159,3 +161,124 @@ def test_rejects_unqualified_release(self):
                 release_id=manifest["release_id"],
                 expected_generation=None,
             )
+
+
+class TestMacosBetaRollbackRules:
+    def test_rolls_back_qualified_release_and_creates_immutable_audit(self):
+        current = {
+            "platform": "macos",
+            "channel": "beta",
+            "release_id": "v0.12.84+12084-macos",
+            "version": "0.12.84+12084",
+            "build_number": 12084,
+            "generation": 7,
+        }
+        target = normalize_release_manifest(
+            _manifest(release_id="v0.12.73+12073-macos", version="0.12.73+12073", build_number=12073)
+        )
+        pointer = _build_beta_rollback_pointer(
+            current,
+            target,
+            release_id=target["release_id"],
+            expected_current_release_id=current["release_id"],
+            expected_generation=7,
+        )
+
+        pointer_snapshot = MagicMock(exists=True)
+        pointer_snapshot.to_dict.return_value = current
+        manifest_snapshot = MagicMock(exists=True)
+        manifest_snapshot.to_dict.return_value = target
+        pointer_ref = MagicMock()
+        pointer_ref.get.return_value = pointer_snapshot
+        manifest_ref = MagicMock()
+        manifest_ref.get.return_value = manifest_snapshot
+        audit_ref = MagicMock()
+        transaction = MagicMock()
+
+        result = _rollback_macos_beta_transaction.to_wrap(
+            transaction,
+            pointer_ref,
+            manifest_ref,
+            audit_ref,
+            release_id=target["release_id"],
+            expected_current_release_id=current["release_id"],
+            expected_generation=7,
+            audit_id="audit-123",
+            occurred_at=pointer["updated_at"],
+        )
+
+        assert result["pointer"]["release_id"] == target["release_id"]
+        assert result["pointer"]["generation"] == 8
+        assert result["audit"] == {
+            "audit_id": "audit-123",
+            "operation": "macos_beta_rollback",
+            "platform": "macos",
+            "channel": "beta",
+            "previous_release_id": current["release_id"],
+            "previous_generation": 7,
+            "target_release_id": target["release_id"],
+            "generation": 8,
+            "occurred_at": pointer["updated_at"],
+        }
+        transaction.create.assert_called_once_with(audit_ref, result["audit"])
+        transaction.set.assert_called_once_with(pointer_ref, result["pointer"])
+
+    def test_rejects_stale_current_release_or_generation(self):
+        current = {"release_id": "v0.12.84+12084-macos", "build_number": 12084, "generation": 7}
+        target = normalize_release_manifest(
+            _manifest(release_id="v0.12.73+12073-macos", version="0.12.73+12073", build_number=12073)
+        )
+
+        with pytest.raises(ValueError, match="current release mismatch"):
+            _build_beta_rollback_pointer(
+                current,
+                target,
+                release_id=target["release_id"],
+                expected_current_release_id="v0.12.83+12083-macos",
+                expected_generation=7,
+            )
+        with pytest.raises(ValueError, match="generation mismatch"):
+            _build_beta_rollback_pointer(
+                current,
+                target,
+                release_id=target["release_id"],
+                expected_current_release_id=current["release_id"],
+                expected_generation=6,
+            )
+
+    def test_rejects_unqualified_or_non_macos_target(self):
+        current = {"release_id": "v0.12.84+12084-macos", "build_number": 12084, "generation": 7}
+        unqualified = normalize_release_manifest(
+            _manifest(
+                release_id="v0.12.73+12073-macos",
+                version="0.12.73+12073",
+                build_number=12073,
+                qualification={"tier": "T2", "passed": False},
+            )
+        )
+        with pytest.raises(ValueError, match="qualification"):
+            _build_beta_rollback_pointer(
+                current,
+                unqualified,
+                release_id=unqualified["release_id"],
+                expected_current_release_id=current["release_id"],
+                expected_generation=7,
+            )
+
+        windows = normalize_release_manifest(
+            _manifest(
+                release_id="v0.12.73+12073-windows",
+                platform="windows",
+                version="0.12.73+12073",
+                build_number=12073,
+                dmg_url=None,
+            )
+        )
+        with pytest.raises(ValueError, match="macos"):
+            _build_beta_rollback_pointer(
+                current,
+                windows,
+                release_id=windows["release_id"],
+                expected_current_release_id=current["release_id"],
+                expected_generation=7,
+            )