feat: quarantine new releases to prevent supply chain attacks

Add per-remote quarantine support: when quarantine_new=true and quarantine_days=N,
immutable artifacts published within the last N days are blocked with 404 until
the quarantine window expires.

- ConfigManager.get_quarantine_config() reads quarantine_new/quarantine_days
- RedisCache.store/get_artifact_published() persist Last-Modified per artifact
- proxy._check_quarantine() enforces the window; fails open when date is unknown
- proxy._fetch_last_modified() HEAD-requests upstream to discover publish date
- Docker proxy route wires quarantine checks on both cache-hit and cache-miss
- remotes.yaml: quarantine_new/quarantine_days added to pypi example (3-day window)
- README: documents quarantine configuration

tests/conftest.py

@@ -98,6 +98,24 @@ TEST_REMOTES = {
             "immutable_patterns": [r"\.tgz$"],
             "cache": {"immutable_ttl": 0, "mutable_ttl": 3600},
         },
+        "quarantine-test": {
+            "base_url": "https://releases.example.com",
+            "type": "remote",
+            "package": "generic",
+            "immutable_patterns": [r".*\.tar\.gz$"],
+            "quarantine_new": True,
+            "quarantine_days": 3,
+            "cache": {"immutable_ttl": 0, "mutable_ttl": 0},
+        },
+        "quarantine-disabled": {
+            "base_url": "https://releases.example.com",
+            "type": "remote",
+            "package": "generic",
+            "immutable_patterns": [r".*\.tar\.gz$"],
+            "quarantine_new": False,
+            "quarantine_days": 3,
+            "cache": {"immutable_ttl": 0, "mutable_ttl": 0},
+        },
     }
 }
 

tests/test_cache.py

@@ -283,3 +283,47 @@ class TestMutableMeta:
 
     def test_delete_no_op_when_unavailable(self, unavailable_cache):
         unavailable_cache.delete_mutable_meta("remote", "path")  # must not raise
+
+
+# ---------------------------------------------------------------------------
+# artifact published date (quarantine support)
+# ---------------------------------------------------------------------------
+
+
+class TestArtifactPublished:
+    def test_key_format_is_deterministic(self, bare_cache):
+        path = "some/path/package-1.0.tar.gz"
+        expected_hash = hashlib.sha256(path.encode()).hexdigest()[:16]
+        assert bare_cache.get_artifact_published_key("myremote", path) == f"pkg:published:myremote:{expected_hash}"
+
+    def test_key_hash_is_16_chars(self, bare_cache):
+        key = bare_cache.get_artifact_published_key("remote", "path/to/file.whl")
+        assert len(key.split(":")[-1]) == 16
+
+    def test_different_paths_produce_different_keys(self, bare_cache):
+        k1 = bare_cache.get_artifact_published_key("remote", "pkg-1.0.tar.gz")
+        k2 = bare_cache.get_artifact_published_key("remote", "pkg-2.0.tar.gz")
+        assert k1 != k2
+
+    def test_store_calls_set_with_correct_value(self, cache_with_redis, mock_redis_client):
+        lm = "Mon, 01 Jan 2024 00:00:00 GMT"
+        cache_with_redis.store_artifact_published("remote", "path/pkg.tar.gz", lm)
+        expected_key = cache_with_redis.get_artifact_published_key("remote", "path/pkg.tar.gz")
+        mock_redis_client.set.assert_called_once_with(expected_key, lm)
+
+    def test_get_returns_stored_value(self, cache_with_redis, mock_redis_client):
+        lm = "Tue, 15 Mar 2022 12:00:00 GMT"
+        mock_redis_client.get.return_value = lm
+        result = cache_with_redis.get_artifact_published("remote", "path/pkg.tar.gz")
+        assert result == lm
+
+    def test_get_returns_none_when_not_stored(self, cache_with_redis, mock_redis_client):
+        mock_redis_client.get.return_value = None
+        result = cache_with_redis.get_artifact_published("remote", "path/pkg.tar.gz")
+        assert result is None
+
+    def test_store_no_op_when_unavailable(self, unavailable_cache):
+        unavailable_cache.store_artifact_published("remote", "path", "Mon, 01 Jan 2024 00:00:00 GMT")
+
+    def test_get_returns_none_when_unavailable(self, unavailable_cache):
+        assert unavailable_cache.get_artifact_published("remote", "path") is None

tests/test_config.py

@@ -351,3 +351,70 @@ class TestConfigReload:
         cfg._check_reload()
 
         assert "repo-a" in cfg.config["remotes"]
+
+
+# ---------------------------------------------------------------------------
+# get_quarantine_config
+# ---------------------------------------------------------------------------
+
+
+class TestGetQuarantineConfig:
+    def test_returns_false_zero_when_not_configured(self, make_config):
+        cfg = make_config({"r": {"type": "remote", "package": "generic", "base_url": "https://x.com"}})
+        enabled, days = cfg.get_quarantine_config("r")
+        assert enabled is False
+        assert days == 0
+
+    def test_returns_false_zero_for_missing_remote(self, make_config):
+        cfg = make_config({})
+        enabled, days = cfg.get_quarantine_config("nonexistent")
+        assert enabled is False
+        assert days == 0
+
+    def test_enabled_true_and_days_returned(self, make_config):
+        cfg = make_config(
+            {
+                "r": {
+                    "type": "remote",
+                    "package": "generic",
+                    "base_url": "https://x.com",
+                    "quarantine_new": True,
+                    "quarantine_days": 7,
+                }
+            }
+        )
+        enabled, days = cfg.get_quarantine_config("r")
+        assert enabled is True
+        assert days == 7
+
+    def test_quarantine_new_false_returns_disabled(self, make_config):
+        cfg = make_config(
+            {
+                "r": {
+                    "type": "remote",
+                    "package": "generic",
+                    "base_url": "https://x.com",
+                    "quarantine_new": False,
+                    "quarantine_days": 7,
+                }
+            }
+        )
+        enabled, days = cfg.get_quarantine_config("r")
+        assert enabled is False
+        assert days == 7
+
+    def test_enabled_with_zero_days_returns_zero(self, make_config):
+        cfg = make_config(
+            {
+                "r": {
+                    "type": "remote",
+                    "package": "generic",
+                    "base_url": "https://x.com",
+                    "quarantine_new": True,
+                    "quarantine_days": 0,
+                }
+            }
+        )
+        enabled, days = cfg.get_quarantine_config("r")
+        assert enabled is True
+        assert days == 0

tests/test_routes.py

@@ -2,6 +2,7 @@
 
 import hashlib
 import json
+from datetime import UTC
 from unittest.mock import ANY, AsyncMock, MagicMock, patch
 
 import pytest
@@ -924,3 +925,153 @@ class TestHelmRemote:
 
         response = client.get("/api/v1/remote/helm-test/vault.zip")
         assert response.status_code == 403
+
+
+# ---------------------------------------------------------------------------
+# Quarantine  (quarantine-test remote: quarantine_new=True, quarantine_days=3)
+# ---------------------------------------------------------------------------
+
+
+class TestQuarantine:
+    def _recent_date(self, days_ago=1):
+        """Return an HTTP-format date string N days in the past (within quarantine window)."""
+        from datetime import datetime, timedelta
+        from email.utils import format_datetime
+
+        dt = datetime.now(UTC) - timedelta(days=days_ago)
+        return format_datetime(dt, usegmt=True)
+
+    def _old_date(self, days_ago=10):
+        """Return an HTTP-format date string N days in the past (outside quarantine window)."""
+        from datetime import datetime, timedelta
+        from email.utils import format_datetime
+
+        dt = datetime.now(UTC) - timedelta(days=days_ago)
+        return format_datetime(dt, usegmt=True)
+
+    def test_cache_miss_recent_artifact_quarantined(self, client, patched_deps):
+        """Cache miss: artifact published within quarantine window → 404."""
+        deps = patched_deps
+        deps["storage"].exists.return_value = False
+        deps["storage"].download_object.return_value = b"content"
+        deps["cache"].is_mutable_file.return_value = False
+
+        with patch(
+            "artifactapi.artifact.proxy.cache_single_artifact",
+            new_callable=AsyncMock,
+            return_value={"status": "cached", "last_modified": self._recent_date()},
+        ):
+            response = client.get("/api/v1/remote/quarantine-test/some/path/package-1.0.tar.gz")
+
+        assert response.status_code == 404
+        assert "quarantined" in response.json()["detail"].lower()
+
+    def test_cache_miss_old_artifact_allowed(self, client, patched_deps):
+        """Cache miss: artifact published outside quarantine window → 200."""
+        deps = patched_deps
+        deps["storage"].exists.return_value = False
+        deps["storage"].download_object.return_value = b"content"
+        deps["cache"].is_mutable_file.return_value = False
+
+        with patch(
+            "artifactapi.artifact.proxy.cache_single_artifact",
+            new_callable=AsyncMock,
+            return_value={"status": "cached", "last_modified": self._old_date()},
+        ):
+            response = client.get("/api/v1/remote/quarantine-test/some/path/package-1.0.tar.gz")
+
+        assert response.status_code == 200
+
+    def test_cache_miss_no_last_modified_fails_open(self, client, patched_deps):
+        """Cache miss: no Last-Modified header → fail open (200, not quarantined)."""
+        deps = patched_deps
+        deps["storage"].exists.return_value = False
+        deps["storage"].download_object.return_value = b"content"
+        deps["cache"].is_mutable_file.return_value = False
+
+        with patch(
+            "artifactapi.artifact.proxy.cache_single_artifact",
+            new_callable=AsyncMock,
+            return_value={"status": "cached", "last_modified": None},
+        ):
+            response = client.get("/api/v1/remote/quarantine-test/some/path/package-1.0.tar.gz")
+
+        assert response.status_code == 200
+
+    def test_cache_hit_recent_artifact_quarantined(self, client, patched_deps):
+        """Cache hit: stored publish date within quarantine window → 404."""
+        deps = patched_deps
+        deps["storage"].exists.return_value = True
+        deps["storage"].download_object.return_value = b"content"
+        deps["cache"].is_mutable_file.return_value = False
+        deps["cache"].get_artifact_published.return_value = self._recent_date()
+
+        response = client.get("/api/v1/remote/quarantine-test/some/path/package-1.0.tar.gz")
+
+        assert response.status_code == 404
+        assert "quarantined" in response.json()["detail"].lower()
+
+    def test_cache_hit_old_artifact_allowed(self, client, patched_deps):
+        """Cache hit: stored publish date outside quarantine window → 200."""
+        deps = patched_deps
+        deps["storage"].exists.return_value = True
+        deps["storage"].download_object.return_value = b"content"
+        deps["cache"].is_mutable_file.return_value = False
+        deps["cache"].get_artifact_published.return_value = self._old_date()
+
+        response = client.get("/api/v1/remote/quarantine-test/some/path/package-1.0.tar.gz")
+
+        assert response.status_code == 200
+
+    def test_cache_hit_no_stored_date_fetches_upstream(self, client, patched_deps):
+        """Cache hit: no stored date → HEAD upstream to get Last-Modified."""
+        deps = patched_deps
+        deps["storage"].exists.return_value = True
+        deps["storage"].download_object.return_value = b"content"
+        deps["cache"].is_mutable_file.return_value = False
+        deps["cache"].get_artifact_published.return_value = None
+
+        with patch(
+            "artifactapi.artifact.proxy._fetch_last_modified",
+            new_callable=AsyncMock,
+            return_value=self._old_date(),
+        ) as mock_fetch:
+            response = client.get("/api/v1/remote/quarantine-test/some/path/package-1.0.tar.gz")
+
+        mock_fetch.assert_called_once()
+        assert response.status_code == 200
+
+    def test_quarantine_disabled_allows_recent_artifact(self, client, patched_deps):
+        """quarantine_new=False: recent artifacts are not blocked."""
+        deps = patched_deps
+        deps["storage"].exists.return_value = False
+        deps["storage"].download_object.return_value = b"content"
+        deps["cache"].is_mutable_file.return_value = False
+
+        with patch(
+            "artifactapi.artifact.proxy.cache_single_artifact",
+            new_callable=AsyncMock,
+            return_value={"status": "cached", "last_modified": self._recent_date()},
+        ):
+            response = client.get("/api/v1/remote/quarantine-disabled/some/path/package-1.0.tar.gz")
+
+        assert response.status_code == 200
+
+    def test_quarantine_detail_includes_available_date(self, client, patched_deps):
+        """The 404 detail should include the date when the artifact becomes available."""
+        deps = patched_deps
+        deps["storage"].exists.return_value = False
+        deps["storage"].download_object.return_value = b"content"
+        deps["cache"].is_mutable_file.return_value = False
+
+        with patch(
+            "artifactapi.artifact.proxy.cache_single_artifact",
+            new_callable=AsyncMock,
+            return_value={"status": "cached", "last_modified": self._recent_date()},
+        ):
+            response = client.get("/api/v1/remote/quarantine-test/some/path/package-1.0.tar.gz")
+
+        assert response.status_code == 404
+        detail = response.json()["detail"]
+        assert "available after" in detail
+        assert "3-day" in detail