feat(crates): add crate-ID validation

Add app/crates/ids.py: validate_crate_id / is_valid_crate_id and an InvalidCrateId exception. IDs are constrained to a safe charset (start alphanumeric, [A-Za-z0-9._-], max 128, no '/' or '..'). Fixes the ".zip in crate ID" fragility. IDs are no longer parsed.
Closes #174

Author: alexhambley

app/crates/__init__.py

@@ -0,0 +1 @@
+"""Crate identification, layout, and resolution within object storage."""

app/crates/ids.py

@@ -0,0 +1,37 @@
+"""Strict validation for crate identifiers.
+
+A crate ID is treated as a single-segment label. Constraining it to a safe charset
+means it can be composed into object keys and local paths without risk of collisions
+or traversal, and removes the need to parse meaning (such as a ``.zip`` suffix) back
+out of it.
+"""
+
+import re
+
+# Start with an alphanumeric (so no leading dot/dash), then up to 127 more of a
+# restricted set. No slashes, whitespace, or non-ASCII; max length 128.
+_CRATE_ID_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+
+
+class InvalidCrateId(ValueError):
+    """Raised when a crate ID does not meet the required format."""
+
+
+def is_valid_crate_id(crate_id: object) -> bool:
+    """Return whether ``crate_id`` is a well-formed crate identifier."""
+    if not isinstance(crate_id, str):
+        return False
+    if ".." in crate_id:
+        return False
+    return _CRATE_ID_PATTERN.match(crate_id) is not None
+
+
+def validate_crate_id(crate_id: object) -> str:
+    """Return ``crate_id`` unchanged if valid, else raise :class:`InvalidCrateId`."""
+    if not is_valid_crate_id(crate_id):
+        raise InvalidCrateId(
+            f"Invalid crate ID: {crate_id!r}. Crate IDs must start with a letter "
+            "or digit and contain only letters, digits, '.', '_' or '-' "
+            "(max 128 characters, no '/' or '..')."
+        )
+    return crate_id

tests/test_crate_ids.py

@@ -0,0 +1,54 @@
+"""Tests for strict crate-ID validation."""
+
+import pytest
+
+from app.crates.ids import validate_crate_id, is_valid_crate_id, InvalidCrateId
+
+
+@pytest.mark.parametrize(
+    "crate_id",
+    [
+        "a",
+        "crate-123",
+        "my_crate.v2",
+        "ABC.def-123_456",
+        "release.zip",          # ".zip" in the ID is harmless now: IDs are opaque
+        "x" * 128,              # max length
+    ],
+)
+def test_valid_ids_are_accepted(crate_id):
+    assert validate_crate_id(crate_id) == crate_id
+    assert is_valid_crate_id(crate_id) is True
+
+
+@pytest.mark.parametrize(
+    "crate_id",
+    [
+        "",                     # empty
+        ".hidden",              # leading dot
+        "-leading-dash",        # must start alphanumeric
+        "a/b",                  # path separator
+        "../etc/passwd",        # traversal
+        "a..b",                 # parent-dir sequence
+        "with space",           # whitespace
+        "tab\tchar",            # control char
+        "x" * 129,              # too long
+        "unicodé",              # non-ASCII
+    ],
+)
+def test_invalid_ids_are_rejected(crate_id):
+    assert is_valid_crate_id(crate_id) is False
+    with pytest.raises(InvalidCrateId):
+        validate_crate_id(crate_id)
+
+
+def test_non_string_is_rejected():
+    assert is_valid_crate_id(None) is False
+    with pytest.raises(InvalidCrateId):
+        validate_crate_id(None)
+
+
+def test_error_message_names_the_offending_id():
+    with pytest.raises(InvalidCrateId) as exc_info:
+        validate_crate_id("a/b")
+    assert "a/b" in str(exc_info.value)