codebase-memory-mcp 0.11.0__tar.gz → 0.12.1__tar.gz

{codebase_memory_mcp-0.11.0 → codebase_memory_mcp-0.12.1}/.gitignore

@@ -51,6 +51,9 @@ graph-ui/dist/
 # Generated by scripts/embed-frontend.sh into the source tree (the linker needs
 # it beside the other UI sources). Removed by scripts/clean.sh; never committed.
 src/ui/embedded_assets.c
+# Raw coverage profiles. A coverage-instrumented binary (make test-runner-cov,
+# cbm-cov) run without LLVM_PROFILE_FILE drops default.profraw in its cwd.
+*.profraw
 
 # Generated reports
 BENCHMARK_REPORT.md

{codebase_memory_mcp-0.11.0 → codebase_memory_mcp-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebase-memory-mcp
-Version: 0.11.0
+Version: 0.12.1
 Summary: Fast code intelligence for AI coding agents — installs a verified native runtime set
 Project-URL: Homepage, https://github.com/DeusData/codebase-memory-mcp
 Project-URL: Repository, https://github.com/DeusData/codebase-memory-mcp
@@ -38,6 +38,8 @@ pipx install codebase-memory-mcp
 
 There is one composition per platform: the graph UI ships in every build, so no variant selection is needed.
 
+For testing, `CBM_DOWNLOAD_URL` overrides the download base URL (default `https://github.com/DeusData/codebase-memory-mcp/releases/download/v<version>`): the archive and `checksums.txt` are fetched from `<CBM_DOWNLOAD_URL>/<file>`. It must be `https://`, or plain `http://` to exactly `localhost`, `127.0.0.1`, or `[::1]` (optional port; no proxy, no redirects).
+
 ## Usage
 
 ```bash

{codebase_memory_mcp-0.11.0 → codebase_memory_mcp-0.12.1}/README.md

@@ -16,6 +16,8 @@ pipx install codebase-memory-mcp
 
 There is one composition per platform: the graph UI ships in every build, so no variant selection is needed.
 
+For testing, `CBM_DOWNLOAD_URL` overrides the download base URL (default `https://github.com/DeusData/codebase-memory-mcp/releases/download/v<version>`): the archive and `checksums.txt` are fetched from `<CBM_DOWNLOAD_URL>/<file>`. It must be `https://`, or plain `http://` to exactly `localhost`, `127.0.0.1`, or `[::1]` (optional port; no proxy, no redirects).
+
 ## Usage
 
 ```bash

{codebase_memory_mcp-0.11.0 → codebase_memory_mcp-0.12.1}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codebase-memory-mcp"
-version = "0.11.0"
+version = "0.12.1"
 description = "Fast code intelligence for AI coding agents — installs a verified native runtime set"
 readme = "README.md"
 license = { text = "MIT" }

{codebase_memory_mcp-0.11.0 → codebase_memory_mcp-0.12.1}/requirements-publish.txt

@@ -354,6 +354,6 @@ secretstorage==3.5.0 \
 twine==7.0.0 \
     --hash=sha256:85cdb29c518efef867360ae4acd4b0dfd61c8654a22fca08e6f8539f05022177 \
     --hash=sha256:b854164df26db268af05f49aa5c0344b10e27a494343ff05b1e0bad3b135f5a7
-urllib3==2.7.0 \
-    --hash=sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c \
-    --hash=sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897
+urllib3==2.8.0 \
+    --hash=sha256:0cf3cae568d36aa9576b28dfb35f11328f1cb974ca7647d9475ebb86c75ac6e3 \
+    --hash=sha256:63bf2ead4c879426ebf22ef2a781eeb4aa3b4ae798a0435506f8687fd5bb9b63

{codebase_memory_mcp-0.11.0 → codebase_memory_mcp-0.12.1}/src/codebase_memory_mcp/_cli.py

@@ -38,10 +38,19 @@ _WINDOWS_ARCHIVE_NAMES = (
 # file://, ftp://, and custom schemes — a redirect or tainted URL source
 # could otherwise turn a download into an arbitrary-local-file read.
 _ALLOWED_SCHEMES = frozenset({"https"})
+# install.sh's loopback pattern: plain HTTP only to an exact loopback
+# authority, for local smoke tests (CBM_DOWNLOAD_URL).
+_LOOPBACK_HTTP_URL = re.compile(
+    r"http://(localhost|127\.0\.0\.1|\[::1\])(:[0-9]+)?([/?#].*)?"
+)
+_LOOPBACK_HOSTNAMES = frozenset({"localhost", "127.0.0.1", "::1"})
 _MAX_REDIRECTS = 5
 _NETWORK_TIMEOUT_SECONDS = 120
 _CANDIDATE_TIMEOUT_SECONDS = 15
-_MAX_CHECKSUM_MANIFEST_BYTES = 1024 * 1024
+# Entry-count guard for the archive namespace check. Keep in sync with the
+# Go wrapper (pkg/go/cmd/codebase-memory-mcp/main.go) and the npm wrapper.
+_MAX_ARCHIVE_MEMBERS = 64
+_ARCHIVE_COPY_CHUNK_BYTES = 64 * 1024
 _REDIRECT_CODES = frozenset({301, 302, 303, 307, 308})
 _RUNTIME_LOCK_NAME = ".codebase-memory-mcp-runtime.lock"
 _RUNTIME_LOCK_WAIT_SECONDS = 45
@@ -62,13 +71,50 @@ _runtime_lock_claim_observer = None
 
 
 class _NoRedirectHandler(urllib.request.HTTPRedirectHandler):
-    """Expose redirects to _download_https for explicit per-hop validation."""
+    """Expose redirects to _download_file for explicit per-hop validation."""
 
     def redirect_request(self, req, fp, code, msg, headers, newurl):
         return None
 
 
 _HTTPS_OPENER = urllib.request.build_opener(_NoRedirectHandler())
+# A loopback fetch never goes through a proxy.
+_LOOPBACK_OPENER = urllib.request.build_opener(
+    urllib.request.ProxyHandler({}), _NoRedirectHandler()
+)
+
+
+def _download_base(version: str, environ=None):
+    """Return (base, loopback) for release downloads.
+
+    CBM_DOWNLOAD_URL replaces the release download base (for testing), with
+    install.sh's policy: HTTPS, or plain HTTP to an exact loopback authority.
+    """
+    env = os.environ if environ is None else environ
+    override = env.get("CBM_DOWNLOAD_URL")
+    if not override:
+        return f"https://github.com/{REPO}/releases/download/v{version}", False
+    if override.startswith("https://"):
+        return override, False
+    if _LOOPBACK_HTTP_URL.fullmatch(override):
+        return override, True
+    sys.exit(
+        f"codebase-memory-mcp: refusing non-HTTPS download URL "
+        f"(CBM_DOWNLOAD_URL): {override}"
+    )
+
+
+def _validate_loopback_url(url: str) -> None:
+    """Reject anything but plain HTTP to an exact loopback authority."""
+    parsed = urllib.parse.urlparse(url)
+    if (
+        not _LOOPBACK_HTTP_URL.fullmatch(url)
+        or parsed.scheme != "http"
+        or parsed.hostname not in _LOOPBACK_HOSTNAMES
+        or parsed.username is not None
+        or parsed.password is not None
+    ):
+        sys.exit(f"codebase-memory-mcp: refusing non-loopback HTTP URL: {url}")
 
 
 def _validate_url_scheme(url: str) -> None:
@@ -86,23 +132,33 @@ def _validate_url_scheme(url: str) -> None:
         )
 
 
-def _download_https(url: str, dest: str, max_bytes: int = 0) -> None:
-    """Download through a bounded HTTPS-only opener into dest."""
+def _validate_download_url(url: str, loopback: bool) -> None:
+    if loopback:
+        _validate_loopback_url(url)
+    else:
+        _validate_url_scheme(url)
+
+
+def _download_file(url: str, dest: str, loopback: bool = False) -> None:
+    """Download into dest: HTTPS with checked redirects, or one loopback hop."""
+    opener = _LOOPBACK_OPENER if loopback else _HTTPS_OPENER
     current_url = url
     for redirect_count in range(_MAX_REDIRECTS + 1):
-        _validate_url_scheme(current_url)
+        _validate_download_url(current_url, loopback)
         request = urllib.request.Request(
             current_url, headers={"User-Agent": "codebase-memory-mcp-installer"}
         )
         try:
-            response = _HTTPS_OPENER.open(
-                request, timeout=_NETWORK_TIMEOUT_SECONDS
-            )
+            response = opener.open(request, timeout=_NETWORK_TIMEOUT_SECONDS)
         except urllib.error.HTTPError as exc:
             if exc.code not in _REDIRECT_CODES:
                 raise
             location = exc.headers.get("Location")
             exc.close()
+            if loopback:
+                raise RuntimeError(
+                    f"refusing redirect from loopback download: {current_url}"
+                )
             if not location:
                 raise RuntimeError(f"redirect has no Location: {current_url}")
             if redirect_count == _MAX_REDIRECTS:
@@ -112,28 +168,35 @@ def _download_https(url: str, dest: str, max_bytes: int = 0) -> None:
             continue
 
         with response:
-            _validate_url_scheme(response.geturl())
+            _validate_download_url(response.geturl(), loopback)
             deadline = time.monotonic() + _NETWORK_TIMEOUT_SECONDS
-            total = 0
-            with open(dest, "wb") as out:
-                while True:
-                    if time.monotonic() >= deadline:
-                        raise TimeoutError(
-                            f"download hop timed out: {current_url}"
-                        )
-                    chunk = response.read(65536)
-                    if not chunk:
-                        return
-                    total += len(chunk)
-                    if max_bytes and total > max_bytes:
-                        raise RuntimeError(
-                            f"download exceeds the {max_bytes}-byte safety limit"
-                        )
-                    out.write(chunk)
+            try:
+                with open(dest, "wb") as out:
+                    while True:
+                        if time.monotonic() >= deadline:
+                            raise TimeoutError(
+                                f"download hop timed out: {current_url}"
+                            )
+                        chunk = response.read(65536)
+                        if not chunk:
+                            return
+                        out.write(chunk)
+            except BaseException:
+                # Never leave a partial download behind for a later step to
+                # mistake for the complete asset.
+                _remove_quietly(dest)
+                raise
 
     raise RuntimeError("too many redirects")
 
 
+def _remove_quietly(path) -> None:
+    try:
+        os.unlink(path)
+    except OSError:
+        pass
+
+
 def _verify_candidate(path: Path) -> None:
     """Require a staged native candidate to execute successfully."""
     try:
@@ -196,17 +259,74 @@ def _validate_archive_names(names, archive_names, casefold: bool = False):
         )
 
 
+def _require_regular_archive(archive_path: str) -> None:
+    if not stat.S_ISREG(os.stat(archive_path).st_mode):
+        sys.exit("codebase-memory-mcp: release archive is not a regular file")
+
+
+def _require_member_count_within_limit(count: int, max_members: int) -> None:
+    if count > max_members:
+        sys.exit(
+            f"codebase-memory-mcp: archive exceeds the {max_members}-member "
+            f"safety limit"
+        )
+
+
+def _require_declared_size(name: str, size: int) -> None:
+    if size < 0:
+        sys.exit(
+            f"codebase-memory-mcp: archive member has a negative declared "
+            f"size: {name!r}"
+        )
+
+
+def _copy_archive_member(source, output, name: str, declared_size: int) -> int:
+    """Copy a member, then require the declared size; return the bytes copied.
+
+    The caller removes the target on failure.
+    """
+    copied = 0
+    while True:
+        chunk = source.read(_ARCHIVE_COPY_CHUNK_BYTES)
+        if not chunk:
+            break
+        copied += len(chunk)
+        output.write(chunk)
+    if copied != declared_size:
+        sys.exit(
+            f"codebase-memory-mcp: archive member {name!r} actual size {copied} "
+            f"does not match declared size {declared_size}"
+        )
+    return copied
+
+
+def _write_archive_member(source, target: str, name: str, declared_size: int) -> int:
+    try:
+        with open(target, "xb") as output:
+            return _copy_archive_member(source, output, name, declared_size)
+    except BaseException:
+        _remove_quietly(target)
+        raise
+
+
 def _safe_extract_tar(
-    tf, dest: str, archive_names=(), extract_names=(), ui: bool = False
+    tf,
+    dest: str,
+    archive_names=(),
+    extract_names=(),
+    ui: bool = False,
+    max_members: int = _MAX_ARCHIVE_MEMBERS,
 ):
     """Validate a tar namespace, then extract only its authenticated runtime set."""
     members = tf.getmembers()
+    _require_member_count_within_limit(len(members), max_members)
     for member in members:
         if not member.isfile():
             sys.exit(
                 f"codebase-memory-mcp: refusing unsafe tar entry "
                 f"(not a regular root file: {member.name!r})"
             )
+        _require_declared_size(member.name, member.size)
     _validate_archive_names([member.name for member in members], archive_names)
     runtime_names = list(extract_names)
     by_name = {member.name: member for member in members}
@@ -216,13 +336,18 @@ def _safe_extract_tar(
         if source is None:
             sys.exit(f"codebase-memory-mcp: could not read archive member: {name}")
         target = os.path.join(dest_abs, name)
-        with source, open(target, "xb") as output:
-            shutil.copyfileobj(source, output)
+        with source:
+            _write_archive_member(source, target, name, by_name[name].size)
     return tuple(runtime_names)
 
 
 def _safe_extract_zip(
-    zf, dest: str, archive_names=(), extract_names=(), ui: bool = False
+    zf,
+    dest: str,
+    archive_names=(),
+    extract_names=(),
+    ui: bool = False,
+    max_members: int = _MAX_ARCHIVE_MEMBERS,
 ):
     """Extract a zipfile after validating its Windows-style namespace.
 
@@ -232,7 +357,10 @@ def _safe_extract_zip(
     """
     dest_abs = os.path.abspath(dest)
     names = []
-    for info in zf.infolist():
+    infos = zf.infolist()
+    _require_member_count_within_limit(len(infos), max_members)
+    for info in infos:
+        _require_declared_size(info.filename, info.file_size)
         raw_name = info.filename
         name = raw_name.replace("\\", "/")
         segments_name = name[:-1] if name.endswith("/") else name
@@ -268,20 +396,22 @@ def _safe_extract_zip(
     runtime_names = list(extract_names)
     for name in runtime_names:
         target = os.path.join(dest_abs, name)
-        with zf.open(name) as source, open(target, "xb") as output:
-            shutil.copyfileobj(source, output)
+        with zf.open(name) as source:
+            _write_archive_member(source, target, name, zf.getinfo(name).file_size)
     return tuple(runtime_names)
 
 
-def _verify_checksum(archive_path: str, archive_name: str, version: str) -> None:
-    """Verify SHA256 checksum against checksums.txt from the release."""
-    url = f"https://github.com/{REPO}/releases/download/v{version}/checksums.txt"
+def _verify_checksum(
+    archive_path: str, archive_name: str, base: str, loopback: bool = False
+) -> None:
+    """Verify SHA256 checksum against checksums.txt from the same base."""
+    url = f"{base}/checksums.txt"
     tmp_path = None
     try:
-        _validate_url_scheme(url)
+        _validate_download_url(url, loopback)
         with tempfile.NamedTemporaryFile(suffix=".txt", delete=False) as tmp:
             tmp_path = tmp.name
-        _download_https(url, tmp_path, _MAX_CHECKSUM_MANIFEST_BYTES)
+        _download_file(url, tmp_path, loopback)
         expected = None
         with open(tmp_path, encoding="utf-8") as f:
             for line in f:
@@ -338,7 +468,7 @@ def _version() -> str:
         from importlib.metadata import version
         return version("codebase-memory-mcp")
     except Exception:
-        return "0.10.8"
+        return "0.12.0"
 
 
 def _os_name() -> str:
@@ -1165,8 +1295,9 @@ def _download(version: str) -> Path:
     # have no such variant. Keep in sync with install.sh / install.js / cli.c.
     portable = "-portable" if os_name == "linux" else ""
     archive = f"codebase-memory-mcp-{os_name}-{arch}{portable}.{ext}"
-    url = f"https://github.com/{REPO}/releases/download/v{version}/{archive}"
-    _validate_url_scheme(url)
+    base, loopback = _download_base(version)
+    url = f"{base}/{archive}"
+    _validate_download_url(url, loopback)
 
     dest = _bin_path(version)
     dest.parent.mkdir(parents=True, exist_ok=True)
@@ -1179,7 +1310,7 @@ def _download(version: str) -> Path:
     with tempfile.TemporaryDirectory() as tmp:
         tmp_archive = os.path.join(tmp, f"cbm.{ext}")
         try:
-            _download_https(url, tmp_archive)
+            _download_file(url, tmp_archive, loopback)
         except (OSError, RuntimeError, urllib.error.URLError) as e:
             sys.exit(
                 f"codebase-memory-mcp: download failed ({e})\n"
@@ -1187,7 +1318,8 @@ def _download(version: str) -> Path:
                 f"See https://github.com/{REPO}/releases for available versions."
             )
 
-        _verify_checksum(tmp_archive, archive, version)
+        _verify_checksum(tmp_archive, archive, base, loopback)
+        _require_regular_archive(tmp_archive)
 
         bin_name = (
             _WINDOWS_BINARY_NAME if os_name == "windows" else "codebase-memory-mcp"

{codebase_memory_mcp-0.11.0 → codebase_memory_mcp-0.12.1}/tests/test_cli.py

@@ -1,5 +1,8 @@
+import contextlib
 import errno
 import hashlib
+import http.server
+import io
 import json
 import os
 import stat
@@ -835,3 +838,361 @@ _cli._publish_runtime_set(
                     False,
                 )
 
+
+class _FakeHttpsResponse:
+    """Minimal stand-in for the opener's response: headers, geturl, read."""
+
+    def __init__(self, body: bytes, headers=None, fail_after_first_chunk=False):
+        self._body = body
+        self._offset = 0
+        self._fail_after_first_chunk = fail_after_first_chunk
+        self.headers = dict(headers or {})
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc_info):
+        return False
+
+    def geturl(self):
+        return "https://example.invalid/release.tar.gz"
+
+    def read(self, size=-1):
+        if self._fail_after_first_chunk and self._offset:
+            raise OSError("connection reset")
+        if size is None or size < 0:
+            size = len(self._body) - self._offset
+        chunk = self._body[self._offset : self._offset + size]
+        self._offset += len(chunk)
+        return chunk
+
+
+class _ZeroSource:
+    """Reader that yields `size` zero bytes without holding them."""
+
+    def __init__(self, size: int):
+        self._remaining = size
+
+    def read(self, size=-1):
+        if size is None or size < 0:
+            size = self._remaining
+        count = min(size, self._remaining)
+        self._remaining -= count
+        return bytes(count)
+
+
+class _CountingSink:
+    def __init__(self):
+        self.written = 0
+
+    def write(self, chunk):
+        self.written += len(chunk)
+        return len(chunk)
+
+
+# The size cap the 0.12.0 wrappers enforced, which refused every release.
+_FORMER_MEMBER_CAP_BYTES = 256 * 1024 * 1024
+
+
+def _write_tar_gz(archive, entries):
+    with tarfile.open(archive, "w:gz") as tf:
+        for name, data in entries:
+            info = tarfile.TarInfo(name)
+            info.size = len(data)
+            tf.addfile(info, io.BytesIO(data))
+
+
+def _write_zip(archive, entries):
+    with zipfile.ZipFile(archive, "w") as zf:
+        for name, data in entries:
+            zf.writestr(name, data)
+
+
+def _release_entries(names):
+    return [(name, f"payload of {name}".encode()) for name in names]
+
+
+class ArchiveExtractionTests(unittest.TestCase):
+    URL = "https://example.invalid/release.tar.gz"
+
+    def _download(self, response, destination):
+        with mock.patch.object(_cli._HTTPS_OPENER, "open", return_value=response):
+            _cli._download_file(self.URL, destination)
+
+    def test_download_stores_a_body_whose_declared_length_exceeds_the_former_cap(
+        self,
+    ):
+        with tempfile.TemporaryDirectory() as root:
+            destination = os.path.join(root, "release.tar.gz")
+            response = _FakeHttpsResponse(
+                b"payload", {"Content-Length": str(_FORMER_MEMBER_CAP_BYTES + 1)}
+            )
+            self._download(response, destination)
+            with open(destination, "rb") as stored:
+                self.assertEqual(stored.read(), b"payload")
+
+    def test_download_removes_the_partial_file_when_the_body_fails(self):
+        with tempfile.TemporaryDirectory() as root:
+            destination = os.path.join(root, "release.tar.gz")
+            response = _FakeHttpsResponse(b"x" * 200000, fail_after_first_chunk=True)
+            with self.assertRaises(OSError):
+                self._download(response, destination)
+            self.assertFalse(os.path.exists(destination))
+
+    def test_unix_tar_rejects_more_members_than_the_limit(self):
+        with tempfile.TemporaryDirectory() as root:
+            archive = Path(root) / "members.tar.gz"
+            _write_tar_gz(archive, [("one", b"a"), ("two", b"b"), ("three", b"c")])
+            destination = Path(root) / "extract"
+            destination.mkdir()
+            with tarfile.open(archive) as tf, self.assertRaises(SystemExit) as raised:
+                _cli._safe_extract_tar(
+                    tf,
+                    str(destination),
+                    ("one", "two", "three"),
+                    ("one",),
+                    max_members=2,
+                )
+            self.assertIn("2-member safety limit", str(raised.exception))
+            self.assertFalse((destination / "one").exists())
+
+    def test_unix_tar_extracts_only_the_executable(self):
+        with tempfile.TemporaryDirectory() as root:
+            archive = Path(root) / "release.tar.gz"
+            _write_tar_gz(archive, _release_entries(_cli._UNIX_ARCHIVE_NAMES))
+            destination = Path(root) / "extract"
+            destination.mkdir()
+            with tarfile.open(archive) as tf:
+                extracted = _cli._safe_extract_tar(
+                    tf,
+                    str(destination),
+                    _cli._UNIX_ARCHIVE_NAMES,
+                    ("codebase-memory-mcp",),
+                )
+            self.assertEqual(extracted, ("codebase-memory-mcp",))
+            self.assertEqual(
+                (destination / "codebase-memory-mcp").read_bytes(),
+                b"payload of codebase-memory-mcp",
+            )
+            self.assertEqual(os.listdir(destination), ["codebase-memory-mcp"])
+
+    def test_archive_copy_accepts_a_member_larger_than_the_former_cap(self):
+        size = _FORMER_MEMBER_CAP_BYTES + 1024 * 1024
+        sink = _CountingSink()
+        copied = _cli._copy_archive_member(
+            _ZeroSource(size), sink, "codebase-memory-mcp", size
+        )
+        self.assertEqual(copied, size)
+        self.assertEqual(sink.written, size)
+
+    def test_archive_copy_rejects_a_member_that_yields_more_than_it_declares(self):
+        with self.assertRaises(SystemExit) as raised:
+            _cli._copy_archive_member(io.BytesIO(b"x" * 100), io.BytesIO(), "member", 10)
+        self.assertIn(
+            "'member' actual size 100 does not match declared size 10",
+            str(raised.exception),
+        )
+
+    def test_archive_member_write_removes_the_partial_file_on_failure(self):
+        with tempfile.TemporaryDirectory() as root:
+            target = os.path.join(root, "codebase-memory-mcp")
+            with self.assertRaises(SystemExit):
+                _cli._write_archive_member(
+                    io.BytesIO(b"x" * 100), target, "codebase-memory-mcp", 10
+                )
+            self.assertFalse(os.path.exists(target))
+
+    def test_windows_zip_rejects_more_members_than_the_limit(self):
+        with tempfile.TemporaryDirectory() as root:
+            archive = Path(root) / "members.zip"
+            _write_zip(archive, [("one", b"a"), ("two", b"b"), ("three", b"c")])
+            destination = Path(root) / "extract"
+            destination.mkdir()
+            with zipfile.ZipFile(archive) as zf, self.assertRaises(SystemExit) as raised:
+                _cli._safe_extract_zip(
+                    zf,
+                    str(destination),
+                    ("one", "two", "three"),
+                    ("one",),
+                    max_members=2,
+                )
+            self.assertIn("2-member safety limit", str(raised.exception))
+
+    def test_windows_zip_extracts_only_the_executable(self):
+        with tempfile.TemporaryDirectory() as root:
+            archive = Path(root) / "release.zip"
+            _write_zip(archive, _release_entries(_cli._WINDOWS_ARCHIVE_NAMES))
+            destination = Path(root) / "extract"
+            destination.mkdir()
+            with zipfile.ZipFile(archive) as zf:
+                extracted = _cli._safe_extract_zip(
+                    zf,
+                    str(destination),
+                    _cli._WINDOWS_ARCHIVE_NAMES,
+                    (_cli._WINDOWS_BINARY_NAME,),
+                )
+            self.assertEqual(extracted, (_cli._WINDOWS_BINARY_NAME,))
+            self.assertEqual(
+                (destination / _cli._WINDOWS_BINARY_NAME).read_bytes(),
+                b"payload of codebase-memory-mcp.exe",
+            )
+            self.assertEqual(os.listdir(destination), [_cli._WINDOWS_BINARY_NAME])
+
+
+@contextlib.contextmanager
+def _loopback_server(routes):
+    """Serve `routes` ({path: bytes}) on 127.0.0.1; any other path redirects."""
+
+    class Handler(http.server.BaseHTTPRequestHandler):
+        def do_GET(self):
+            body = routes.get(self.path)
+            if body is None:
+                self.send_response(302)
+                self.send_header("Location", "https://example.invalid/elsewhere")
+                self.send_header("Content-Length", "0")
+                self.end_headers()
+                return
+            self.send_response(200)
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def log_message(self, *args):
+            pass
+
+    server = http.server.ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        yield f"http://127.0.0.1:{server.server_address[1]}"
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join()
+
+
+class DownloadBaseTests(unittest.TestCase):
+    GITHUB_BASE = "https://github.com/DeusData/codebase-memory-mcp/releases/download/v1.2.3"
+
+    def test_unset_or_empty_uses_the_github_release_base(self):
+        self.assertEqual(_cli._download_base("1.2.3", {}), (self.GITHUB_BASE, False))
+        self.assertEqual(
+            _cli._download_base("1.2.3", {"CBM_DOWNLOAD_URL": ""}),
+            (self.GITHUB_BASE, False),
+        )
+
+    def test_https_override_is_accepted(self):
+        for base in (
+            "https://mirror.example/releases/v1",
+            "https://127.0.0.1:8443/fixture",
+        ):
+            with self.subTest(base=base):
+                self.assertEqual(
+                    _cli._download_base("1.2.3", {"CBM_DOWNLOAD_URL": base}),
+                    (base, False),
+                )
+
+    def test_exact_loopback_http_override_is_accepted(self):
+        for base in (
+            "http://localhost",
+            "http://localhost:8080/fixture",
+            "http://127.0.0.1:41234/standard",
+            "http://[::1]:9/x?y#z",
+        ):
+            with self.subTest(base=base):
+                self.assertEqual(
+                    _cli._download_base("1.2.3", {"CBM_DOWNLOAD_URL": base}),
+                    (base, True),
+                )
+
+    def test_non_loopback_http_and_other_schemes_are_refused(self):
+        for base in (
+            "http://example.com/releases",
+            "http://127.0.0.1.example.com/",
+            "http://localhost.example.com:8080/",
+            "http://user@localhost/",
+            "http://127.0.0.2/",
+            "HTTP://localhost/",
+            "file:///tmp/releases",
+            "ftp://localhost/releases",
+            "github.com/DeusData/codebase-memory-mcp",
+        ):
+            with self.subTest(base=base), self.assertRaises(SystemExit) as raised:
+                _cli._download_base("1.2.3", {"CBM_DOWNLOAD_URL": base})
+            self.assertIn(
+                "refusing non-HTTPS download URL (CBM_DOWNLOAD_URL)",
+                str(raised.exception),
+            )
+
+    def test_https_download_refuses_plain_http(self):
+        with tempfile.TemporaryDirectory() as root:
+            with self.assertRaises(SystemExit):
+                _cli._download_file(
+                    "http://127.0.0.1/release.tar.gz", os.path.join(root, "a")
+                )
+
+    def test_loopback_download_refuses_a_non_loopback_url(self):
+        with tempfile.TemporaryDirectory() as root:
+            with self.assertRaises(SystemExit) as raised:
+                _cli._download_file(
+                    "http://example.invalid/release.tar.gz",
+                    os.path.join(root, "a"),
+                    loopback=True,
+                )
+            self.assertIn("refusing non-loopback HTTP URL", str(raised.exception))
+
+    def test_loopback_download_bypasses_proxies_and_refuses_redirects(self):
+        routes = {"/fixture/archive": b"loopback payload"}
+        # A configured proxy that is not listening: using it would fail.
+        proxy_env = {"http_proxy": "http://127.0.0.1:9", "HTTP_PROXY": "http://127.0.0.1:9"}
+        with _loopback_server(routes) as origin, tempfile.TemporaryDirectory() as root, \
+                mock.patch.dict(os.environ, proxy_env):
+            archive = os.path.join(root, "archive")
+            _cli._download_file(f"{origin}/fixture/archive", archive, loopback=True)
+            with open(archive, "rb") as stored:
+                self.assertEqual(stored.read(), b"loopback payload")
+
+            redirected = os.path.join(root, "redirected")
+            with self.assertRaises(RuntimeError) as raised:
+                _cli._download_file(
+                    f"{origin}/fixture/checksums.txt", redirected, loopback=True
+                )
+            self.assertIn("refusing redirect from loopback download", str(raised.exception))
+            self.assertFalse(os.path.exists(redirected))
+
+    def test_download_fetches_archive_and_checksums_from_the_override(self):
+        os_name = _cli._os_name()
+        arch = _cli._arch()
+        if os_name == "windows":
+            ext, names = "zip", _cli._WINDOWS_ARCHIVE_NAMES
+        else:
+            ext, names = "tar.gz", _cli._UNIX_ARCHIVE_NAMES
+        portable = "-portable" if os_name == "linux" else ""
+        archive_name = f"codebase-memory-mcp-{os_name}-{arch}{portable}.{ext}"
+        with tempfile.TemporaryDirectory() as root:
+            fixture = Path(root) / archive_name
+            if ext == "zip":
+                _write_zip(fixture, _release_entries(names))
+            else:
+                _write_tar_gz(fixture, _release_entries(names))
+            archive_bytes = fixture.read_bytes()
+            digest = hashlib.sha256(archive_bytes).hexdigest()
+            routes = {
+                f"/fixture/{archive_name}": archive_bytes,
+                "/fixture/checksums.txt": f"{digest}  {archive_name}\n".encode(),
+            }
+            cache = Path(root) / "cache"
+            with _loopback_server(routes) as origin, mock.patch.dict(
+                os.environ, {"CBM_DOWNLOAD_URL": f"{origin}/fixture"}
+            ), mock.patch.object(_cli, "_cache_dir", return_value=cache), \
+                    mock.patch.object(_cli, "_verify_candidate"), \
+                    contextlib.redirect_stderr(io.StringIO()):
+                installed = _cli._download("9.9.9")
+            binary_name = (
+                _cli._WINDOWS_BINARY_NAME
+                if os_name == "windows"
+                else "codebase-memory-mcp"
+            )
+            self.assertEqual(
+                installed.read_bytes(), f"payload of {binary_name}".encode()
+            )