io-magiclinks 0.1.0__tar.gz

io_magiclinks-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.3
+Name: io-magiclinks
+Version: 0.1.0
+Summary: Upload browser experiments and retrieve their data with MagicLinks
+Requires-Dist: httpx>=0.28,<1
+Requires-Dist: pydantic>=2,<3
+Requires-Dist: rich>=13.9,<15
+Requires-Dist: typer>=0.27.2,<1
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/intelligence-observatory/magiclinks

io_magiclinks-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["uv_build>=0.8.12,<0.9"]
+build-backend = "uv_build"
+
+[project]
+name = "io-magiclinks"
+version = "0.1.0"
+description = "Upload browser experiments and retrieve their data with MagicLinks"
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.28,<1",
+    "pydantic>=2,<3",
+    "rich>=13.9,<15",
+    "typer>=0.27.2,<1",
+]
+
+[project.scripts]
+io-magiclinks = "magiclinks.cli:main"
+
+[tool.uv.build-backend]
+module-name = "magiclinks"
+source-exclude = ["/README.md"]
+
+[project.urls]
+Repository = "https://github.com/intelligence-observatory/magiclinks"

io_magiclinks-0.1.0/src/magiclinks/__init__.py

@@ -0,0 +1,11 @@
+"""Public MagicLinks client and shared HTTP contracts."""
+
+from .client import MagicLinksClient
+from .errors import AuthenticationError, MagicLinksAPIError, MagicLinkCreationUncertainError
+
+__all__ = [
+    "AuthenticationError",
+    "MagicLinkCreationUncertainError",
+    "MagicLinksAPIError",
+    "MagicLinksClient",
+]

io_magiclinks-0.1.0/src/magiclinks/_transfers.py

@@ -0,0 +1,47 @@
+"""Relay concurrent transfer progress and completion on the calling thread."""
+
+from collections.abc import Callable, Generator, Iterator, Mapping
+from concurrent.futures import Future, ThreadPoolExecutor
+from contextlib import contextmanager
+from functools import partial
+from queue import Queue
+
+
+# %% Ordered worker events
+@contextmanager
+def transfer_results[TKey, TItem, TResult](
+    items: Mapping[TKey, TItem],
+    operation: Callable[[TItem, Callable[[int], None] | None], TResult],
+    max_concurrency: int,
+    on_progress: Callable[[TKey, int], None] | None = None,
+) -> Generator[Iterator[tuple[TKey, Future[TResult]]], None, None]:
+    """Yield finished transfers after delivering their queued byte positions.
+
+    Workers report only byte counts. Callbacks and result/error handling remain
+    on the caller's thread, with completion ordered after each worker's progress.
+    """
+    events: Queue[tuple[TKey, int | Future[TResult]]] = Queue()
+
+    def execute(key: TKey, item: TItem) -> TResult:
+        """Attach item identity without passing credentials or policy to workers."""
+        return operation(item, (lambda count: events.put((key, count))) if on_progress is not None else None)
+
+    def completed(key: TKey, future: Future[TResult]) -> None:
+        """Wake the consumer when a worker has returned or raised."""
+        events.put((key, future))
+
+    def results() -> Iterator[tuple[TKey, Future[TResult]]]:
+        """Consume byte positions before exposing the corresponding completion."""
+        remaining = len(items)
+        while remaining:
+            key, event = events.get()
+            if isinstance(event, Future):
+                remaining -= 1
+                yield key, event
+            elif on_progress is not None:
+                on_progress(key, event)
+
+    with ThreadPoolExecutor(max_workers=max_concurrency) as pool:
+        for key, item in items.items():
+            pool.submit(execute, key, item).add_done_callback(partial(completed, key))
+        yield results()

io_magiclinks-0.1.0/src/magiclinks/archive.py

@@ -0,0 +1,401 @@
+"""Persistent verified JSON downloads with the shared browser ZIP manifest."""
+
+import gzip
+import json
+import os
+import sys
+import time
+import zipfile
+import zlib
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from hashlib import sha256
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import TYPE_CHECKING, Callable, Generator, Literal
+from urllib.parse import quote
+from uuid import UUID
+
+import httpx
+from pydantic import AwareDatetime, BaseModel, Field, JsonValue
+
+from ._transfers import transfer_results
+from .errors import MagicLinksAPIError
+from .files import atomic_json
+from .progress import TransferProgress
+from .types.download_models import (
+    CreateDownloadSelectionRequest, DownloadManifest, DownloadManifestMagicLink,
+    DownloadManifestSubmission, ListOpenDownloadSelectionResponseItem,
+)
+
+if TYPE_CHECKING:
+    from .client import LinkSource, MagicLinksClient
+
+_CHUNK_SIZE = 1024 * 1024
+DEFAULT_MAX_SUBMISSION_BYTES = 256 * 1024**2
+_STATE_FILENAME = ".io-magiclinks.json"
+
+
+# %% Private pull state, excluded from exported research datasets
+class _CachedSubmission(BaseModel):
+    """Verified bytes and a complete metadata snapshot for one local submission."""
+
+    submission: DownloadManifestSubmission
+    payload_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    payload_size_bytes: int = Field(ge=0)
+    json_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    json_size_bytes: int = Field(ge=0)
+    metadata_retrieved_at: AwareDatetime
+
+
+class _ArchiveState(BaseModel):
+    """Operational cache state for efficient pulls from exactly one deployment."""
+
+    source_origin: str
+    submissions: dict[str, JsonValue] = Field(default_factory=dict)
+    selected_at: AwareDatetime | None = None
+    pulled_at: AwareDatetime | None = None
+    failures: dict[str, str] = Field(default_factory=dict)
+
+
+def _save_state(directory: Path, state: _ArchiveState) -> None:
+    """Checkpoint verified transfers without exposing internals in manifest.json."""
+    atomic_json(directory / _STATE_FILENAME, state.model_dump(mode="json"))
+
+
+# %% Local integrity and archive ownership
+def _utc_now() -> datetime:
+    """Use aware UTC instants for private transfer bookkeeping."""
+    return datetime.now(timezone.utc)
+
+
+def _private_directory(path: Path) -> None:
+    """Create an owner-only archive directory without following a symlink."""
+    if path.is_symlink():
+        raise ValueError("Archive directories must not be symlinks")
+    path.mkdir(mode=0o700, parents=True, exist_ok=True)
+
+
+@contextmanager
+def _archive_lock(directory: Path, origin: str) -> Generator[_ArchiveState, None, None]:
+    """Serialize pulls and prevent an archive from mixing deployment origins."""
+    _private_directory(directory)
+    lock_path = directory / ".lock"
+    if lock_path.is_symlink():
+        raise ValueError("Archive lock must not be a symlink")
+    descriptor = os.open(lock_path, os.O_CREAT | os.O_RDWR | getattr(os, "O_NOFOLLOW", 0), 0o600)
+    with os.fdopen(descriptor, "r+b") as lock:
+        if sys.platform == "win32":
+            import msvcrt
+            lock.seek(0)
+            lock.write(b"\0")
+            lock.flush()
+            try:
+                msvcrt.locking(lock.fileno(), msvcrt.LK_NBLCK, 1)
+            except OSError as error:
+                raise ValueError("Another download is using this archive") from error
+        else:
+            import fcntl
+            try:
+                fcntl.flock(lock.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError as error:
+                raise ValueError("Another download is using this archive") from error
+        state_path = directory / _STATE_FILENAME
+        if state_path.is_symlink():
+            raise ValueError("Archive metadata must not be a symlink")
+        if state_path.exists():
+            try:
+                state = _ArchiveState.model_validate_json(state_path.read_bytes())
+            except (OSError, ValueError) as error:
+                raise ValueError("Private archive state is unreadable; choose a new destination") from error
+            if state.source_origin != origin:
+                raise ValueError("This archive belongs to another deployment; choose a different destination")
+        else:
+            state = _ArchiveState(source_origin=origin)
+            _save_state(directory, state)
+        _private_directory(directory / "submissions")
+        yield state
+
+
+def _digest_file(path: Path) -> tuple[int, str]:
+    """Hash a regular local file in bounded chunks."""
+    if path.is_symlink() or not path.is_file():
+        raise ValueError("Submission is not a regular file")
+    digest = sha256()
+    size = 0
+    with path.open("rb") as source:
+        while chunk := source.read(_CHUNK_SIZE):
+            digest.update(chunk)
+            size += len(chunk)
+    return size, digest.hexdigest()
+
+
+def _submission(item: ListOpenDownloadSelectionResponseItem, runtime_context: dict[str, JsonValue]) -> DownloadManifestSubmission:
+    """Project selected metadata onto the scientific dataset without transfer fields."""
+    return DownloadManifestSubmission(
+        open_id=item.open_id, magiclink_id=item.magiclink_id,
+        participant_id=item.participant_id, participant_namespace=item.participant_namespace,
+        participant_namespace_id=item.participant_namespace_id,
+        timestamp_started=item.timestamp_started, timestamp_submitted=item.timestamp_submitted,
+        path=f"submissions/{item.open_id}.json", runtime_context=runtime_context,
+    )
+
+
+def _cached_file(directory: Path, state: _ArchiveState, item: ListOpenDownloadSelectionResponseItem) -> _CachedSubmission | None:
+    """Reuse decoded bytes only when both immutable identity and checksum match."""
+    try:
+        saved = _CachedSubmission.model_validate(state.submissions.get(str(item.open_id)))
+        if (saved.submission.open_id != item.open_id or saved.submission.magiclink_id != item.magiclink_id
+            or saved.payload_sha256 != item.payload_sha256 or saved.payload_size_bytes != item.payload_size_bytes):
+            return None
+        if _digest_file(directory / saved.submission.path) != (saved.json_size_bytes, saved.json_sha256):
+            return None
+    except (OSError, ValueError):
+        return None
+    # Refresh selection metadata while retaining the verified runtime snapshot.
+    return saved.model_copy(update={"submission": _submission(item, saved.submission.runtime_context)})
+
+
+def _reject_constant(value: str) -> None:
+    """Match JSON.parse by rejecting NaN and Infinity extensions."""
+    raise ValueError(f"Invalid JSON constant: {value}")
+
+
+# %% Independent credential-free transfers
+def _stream_verified(transfer: httpx.Client, url: str, expected_size: int, expected_sha256: str,
+    destination: Path, progress: Callable[[int], None] | None = None) -> None:
+    """Receive the original signed bytes, checking length and SHA-256."""
+    digest = sha256()
+    size = 0
+    with destination.open("wb") as output:
+        with transfer.stream("GET", url, headers={"Accept-Encoding": "identity"}) as response:
+            if response.status_code != 200:
+                raise MagicLinksAPIError(response.status_code, "Storage transfer failed")
+            for chunk in response.iter_raw():
+                output.write(chunk)
+                digest.update(chunk)
+                size += len(chunk)
+                if size > expected_size:
+                    raise ValueError("Stored payload exceeds the expected size")
+                if progress is not None:
+                    progress(size)
+        output.flush()
+        os.fsync(output.fileno())
+    if size != expected_size or digest.hexdigest() != expected_sha256:
+        raise ValueError("Stored bytes failed size or SHA-256 verification")
+
+
+def _download_one(client: "MagicLinksClient", transfer: httpx.Client, directory: Path,
+    item: ListOpenDownloadSelectionResponseItem, on_progress: Callable[[int], None] | None,
+    max_submission_bytes: int) -> _CachedSubmission:
+    """Download, verify, decode, validate, and atomically retain one submission."""
+    for attempt in range(3):
+        compressed_path: Path | None = None
+        decoded_path: Path | None = None
+        if on_progress is not None:
+            on_progress(0)
+        try:
+            detail = client.get_open(item.open_id)
+            if (detail.magiclink_id != item.magiclink_id or detail.status != "completed" or not detail.download_url
+                or detail.payload_sha256 != item.payload_sha256 or detail.payload_size_bytes != item.payload_size_bytes):
+                raise ValueError("Submission identity changed after selection; start a new download")
+            with NamedTemporaryFile(dir=directory, prefix=".payload.", delete=False) as compressed:
+                compressed_path = Path(compressed.name)
+            _stream_verified(transfer, detail.download_url, item.payload_size_bytes, item.payload_sha256,
+                compressed_path, on_progress)
+            digest = sha256()
+            size = 0
+            with NamedTemporaryFile(dir=directory / "submissions", prefix=f".{item.open_id}.", delete=False) as decoded:
+                decoded_path = Path(decoded.name)
+                try:
+                    with gzip.open(compressed_path, "rb") as source:
+                        while chunk := source.read(_CHUNK_SIZE):
+                            size += len(chunk)
+                            if size > max_submission_bytes:
+                                raise ValueError("Decoded submission exceeds max_submission_bytes; raise the limit only for trusted data")
+                            decoded.write(chunk)
+                            digest.update(chunk)
+                except (EOFError, zlib.error) as error:
+                    raise ValueError("Stored submission is not valid gzip-compressed JSON") from error
+                decoded.flush()
+                os.fsync(decoded.fileno())
+            # Validate UTF-8 JSON, then preserve the exact original bytes.
+            try:
+                with decoded_path.open("r", encoding="utf-8") as json_source:
+                    json.load(json_source, parse_constant=_reject_constant)
+            except RecursionError as error:
+                raise ValueError("Submission JSON exceeds the decoder nesting limit") from error
+            metadata = _CachedSubmission(
+                submission=_submission(item, detail.runtime_context),
+                payload_sha256=item.payload_sha256, payload_size_bytes=item.payload_size_bytes,
+                json_sha256=digest.hexdigest(), json_size_bytes=size,
+                metadata_retrieved_at=_utc_now(),
+            )
+            os.replace(decoded_path, directory / metadata.submission.path)
+            return metadata
+        except (httpx.RequestError, MagicLinksAPIError) as error:
+            if isinstance(error, MagicLinksAPIError) and error.status_code not in {403, 408, 429, 500, 502, 503, 504}:
+                raise
+            if attempt == 2:
+                raise
+            time.sleep(0.25 * 2**attempt)
+        finally:
+            if compressed_path is not None:
+                compressed_path.unlink(missing_ok=True)
+            if decoded_path is not None:
+                decoded_path.unlink(missing_ok=True)
+    raise RuntimeError("Submission transfer failed")
+
+
+def _zip(directory: Path, manifest: DownloadManifest, files: dict[UUID, _CachedSubmission]) -> None:
+    """Build a ZIP from disk and publish it only after every entry is complete."""
+    temporary: Path | None = None
+    try:
+        with NamedTemporaryFile(dir=directory, prefix=".submissions.", suffix=".zip", delete=False) as output:
+            temporary = Path(output.name)
+        with zipfile.ZipFile(temporary, "w", compression=zipfile.ZIP_DEFLATED, compresslevel=6, allowZip64=True) as archive:
+            for submission in manifest.submissions:
+                cached = files[submission.open_id]
+                path = directory / submission.path
+                if path.is_symlink():
+                    raise ValueError("A local submission changed while preparing the ZIP")
+                digest = sha256()
+                size = 0
+                with path.open("rb") as source, archive.open(submission.path, "w", force_zip64=True) as output:
+                    while chunk := source.read(_CHUNK_SIZE):
+                        output.write(chunk)
+                        digest.update(chunk)
+                        size += len(chunk)
+                if size != cached.json_size_bytes or digest.hexdigest() != cached.json_sha256:
+                    raise ValueError("A local submission changed while preparing the ZIP; repeat the download")
+            archive.writestr("manifest.json", manifest.model_dump_json(indent=2) + "\n")
+        with temporary.open("rb") as output:
+            os.fsync(output.fileno())
+        name = "submissions-partial.zip" if manifest.is_partial else "submissions.zip"
+        os.replace(temporary, directory / name)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+
+
+# %% Public pull workflow
+def download(client: "MagicLinksClient", source: "LinkSource", directory: Path, *, open_ids: list[UUID] | None = None,
+    submitted_after: datetime | None = None, submitted_before: datetime | None = None,
+    participant_namespace: Literal["anon", "prolific"] | None = None, max_concurrency: int = 6,
+    max_submission_bytes: int = DEFAULT_MAX_SUBMISSION_BYTES, partial: bool = False, on_progress: Callable[[TransferProgress], None] | None = None,
+    on_new_open: Callable[[UUID], None] | None = None) -> DownloadManifest:
+    """Rediscover exact membership and reuse verified persistent submission files."""
+    if not 1 <= max_concurrency <= 32:
+        raise ValueError("max_concurrency must be between 1 and 32")
+    if max_submission_bytes < 1:
+        raise ValueError("max_submission_bytes must be positive")
+    ids = [link.magiclink_id for link in client.resolve_magiclinks(source)]
+    request = CreateDownloadSelectionRequest(magiclink_ids=ids, open_ids=open_ids, submitted_after=submitted_after,
+        submitted_before=submitted_before, participant_namespace=participant_namespace)
+    selection = client.select_download(request)
+    with _archive_lock(directory, client.base_url) as state:
+        files: dict[UUID, _CachedSubmission] = {}
+        failures: dict[UUID, str] = {}
+        positions = {item.open_id: 0 for item in selection.items}
+        by_id = {item.open_id: item for item in selection.items}
+        total = sum(item.payload_size_bytes for item in selection.items)
+        completed_bytes = 0
+        reused_bytes = 0
+
+        def emit(open_id: UUID, count: int) -> None:
+            """Publish worker byte positions on this calling thread."""
+            nonlocal completed_bytes
+            completed_bytes += count - positions[open_id]
+            positions[open_id] = count
+            if on_progress is not None:
+                on_progress(TransferProgress(completed_bytes=completed_bytes, total_bytes=total,
+                    reused_bytes=reused_bytes, file_path=f"submissions/{open_id}.json",
+                    file_completed_bytes=count, file_total_bytes=by_id[open_id].payload_size_bytes, phase="downloading"))
+
+        pending: list[ListOpenDownloadSelectionResponseItem] = []
+        for item in selection.items:
+            saved = _cached_file(directory, state, item)
+            if saved is not None and saved.json_size_bytes > max_submission_bytes:
+                failures[item.open_id] = "Decoded submission exceeds max_submission_bytes; raise the limit only for trusted data"
+            elif saved is not None:
+                files[item.open_id] = saved
+                state.submissions[str(item.open_id)] = saved.model_dump(mode="json")
+                reused_bytes += item.payload_size_bytes
+                emit(item.open_id, item.payload_size_bytes)
+            else:
+                pending.append(item)
+                if str(item.open_id) not in state.submissions and on_new_open is not None:
+                    on_new_open(item.open_id)
+        state.selected_at = selection.selected_at
+        _save_state(directory, state)
+        checkpoint_at = time.monotonic()
+        with httpx.Client(timeout=client.timeout) as transfer:
+            def receive(item: ListOpenDownloadSelectionResponseItem, report: Callable[[int], None] | None) -> _CachedSubmission:
+                """Keep authenticated metadata separate from storage transfers."""
+                return _download_one(client, transfer, directory, item, report, max_submission_bytes)
+
+            with transfer_results({item.open_id: item for item in pending}, receive,
+                max_concurrency, emit if on_progress is not None else None) as results:
+                for open_id, future in results:
+                    try:
+                        downloaded = future.result()
+                    except (ValueError, OSError, httpx.RequestError, MagicLinksAPIError) as error:
+                        failures[open_id] = _failure_message(error)
+                    else:
+                        files[open_id] = downloaded
+                        state.submissions[str(open_id)] = downloaded.model_dump(mode="json")
+                        # One shared JSON cache stays cheap even for many tiny submissions.
+                        if time.monotonic() - checkpoint_at >= 1:
+                            _save_state(directory, state)
+                            checkpoint_at = time.monotonic()
+                        emit(open_id, by_id[open_id].payload_size_bytes)
+        state.failures = {str(open_id): message for open_id, message in failures.items()}
+        state.pulled_at = _utc_now()
+        _save_state(directory, state)
+        criteria = request.model_dump(mode="json", exclude_none=True)
+        filters = {key: criteria[key] for key in ("submitted_after", "submitted_before", "participant_namespace") if key in criteria}
+        manifest = DownloadManifest(
+            magiclinks=[DownloadManifestMagicLink(magiclink_id=link.magiclink_id, name=link.name, tags=link.tags) for link in selection.magiclinks],
+            submissions=[files[item.open_id].submission for item in selection.items if item.open_id in files],
+            filters=filters, missing_open_ids=[item.open_id for item in selection.items if item.open_id in failures],
+        )
+        if not failures or partial:
+            _zip(directory, manifest, files)
+            atomic_json(directory / "manifest.json", manifest.model_dump(mode="json"))
+        return manifest
+
+
+def _failure_message(error: Exception) -> str:
+    """Keep signed storage URLs out of private per-Open error messages."""
+    if isinstance(error, httpx.RequestError):
+        return "Transfer connection failed after bounded retries"
+    if isinstance(error, MagicLinksAPIError):
+        return f"API or storage returned HTTP {error.status_code}"
+    if isinstance(error, OSError):
+        return "Could not read or write the local submission"
+    return str(error)
+
+
+def download_file(client: "MagicLinksClient", reference: str | UUID, file_path: str, destination: Path) -> Path:
+    """Follow one authenticated file redirect using a credential-free transfer."""
+    link = client.get_magiclink(reference)
+    entry = next((file for file in link.files if file.path == file_path), None)
+    if entry is None:
+        raise ValueError("The requested path is not in this MagicLink's file manifest")
+    if destination.exists() or destination.is_symlink():
+        raise FileExistsError(destination)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    response = client._http.get(f"/api/magiclinks/{link.magiclink_id}/files/{quote(file_path, safe='/')}", follow_redirects=False)
+    if response.status_code != 307 or "location" not in response.headers:
+        raise MagicLinksAPIError(response.status_code, "File route did not return a download capability")
+    temporary: Path | None = None
+    try:
+        with NamedTemporaryFile(dir=destination.parent, prefix=f".{destination.name}.", delete=False) as output:
+            temporary = Path(output.name)
+        with httpx.Client(timeout=client.timeout) as transfer:
+            _stream_verified(transfer, response.headers["location"], entry.size_bytes, entry.sha256, temporary)
+        os.link(temporary, destination)
+        return destination
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)

io_magiclinks-0.1.0/src/magiclinks/auth.py

@@ -0,0 +1,117 @@
+"""Discover a deployment and privately stored API key without named profiles."""
+
+import getpass
+import json
+import os
+import stat
+import sys
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from .errors import AuthenticationError
+from .files import atomic_json
+
+DEFAULT_BASE_URL = "https://intelligence-observatory.org"
+
+
+# %% Deployment configuration
+def normalize_base_url(value: str) -> str:
+    """Require HTTPS, allowing plain HTTP only for local development."""
+    parsed = urlsplit(value.rstrip("/"))
+    try:
+        parsed.port
+    except ValueError as error:
+        raise ValueError("Deployment URL has an invalid port") from error
+    if (
+        not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.query
+        or parsed.fragment
+        or parsed.path not in {"", "/"}
+        or parsed.scheme not in {"http", "https"}
+        or (parsed.scheme == "http" and parsed.hostname not in {"localhost", "127.0.0.1", "::1"})
+    ):
+        raise ValueError("Use an HTTPS deployment origin, or HTTP on localhost for development")
+    return f"{parsed.scheme}://{parsed.netloc}"
+
+
+def configured_base_url(explicit: str | None = None) -> str:
+    """Choose an explicit origin, environment origin, or public deployment."""
+    return normalize_base_url(explicit or os.environ.get("IO_MAGICLINKS_BASE_URL") or DEFAULT_BASE_URL)
+
+
+def credential_path() -> Path:
+    """Locate the configuration outside experiment and project directories."""
+    root = Path(os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config")))
+    if not root.is_absolute():
+        raise AuthenticationError("XDG_CONFIG_HOME must be an absolute directory outside the project")
+    return root / "io-magiclinks" / "credentials.json"
+
+
+def require_external_credentials(directory: Path) -> None:
+    """Reject uploads that could include the client's managed credential file."""
+    root, credential = directory.resolve(), credential_path().resolve()
+    if credential.is_relative_to(root) or (
+        root.exists() and any(parent.exists() and parent.samefile(root) for parent in credential.parents)
+    ):
+        raise AuthenticationError("Keep the credential file outside the uploaded folder")
+
+
+# %% Private credential storage
+def _normalize_api_key(value: str) -> str:
+    """Validate header-safe key text without echoing a malformed credential."""
+    key = value.strip()
+    if not key or any(not 33 <= ord(character) <= 126 for character in key):
+        raise AuthenticationError("API key must contain printable ASCII without whitespace")
+    return key
+
+
+def _read_credentials() -> dict[str, str]:
+    """Read only a regular owner-only credential file, never following symlinks."""
+    path = credential_path()
+    if not path.exists():
+        return {}
+    descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
+    with os.fdopen(descriptor, "r", encoding="utf-8") as source:
+        info = os.fstat(source.fileno())
+        if not stat.S_ISREG(info.st_mode) or (os.name != "nt" and (info.st_mode & 0o077 or info.st_uid != os.getuid())):
+            raise AuthenticationError("Credential file must be owned by you and readable only by you (chmod 600)")
+        try:
+            data = json.load(source)
+        except (ValueError, OSError) as error:
+            raise AuthenticationError("Could not read the local credential file") from error
+    if not isinstance(data, dict) or not all(isinstance(k, str) and isinstance(v, str) for k, v in data.items()):
+        raise AuthenticationError("Local credential file has an invalid format")
+    return data
+
+
+def discover_api_key(base_url: str, explicit: str | None = None) -> str | None:
+    """Prefer a supplied key, then environment, then private local credentials."""
+    key = explicit if explicit is not None else os.environ.get("IO_MAGICLINKS_API_KEY")
+    if key is None:
+        key = _read_credentials().get(base_url)
+    return _normalize_api_key(key) if key is not None else None
+
+
+def save_api_key(base_url: str, api_key: str) -> None:
+    """Atomically persist an accepted API key outside the working directory."""
+    key = _normalize_api_key(api_key)
+    data = _read_credentials()
+    data[base_url] = key
+    path = credential_path()
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    atomic_json(path, data)
+
+
+def prompt_secret(label: str) -> str:
+    """Read a hidden credential only from a terminal."""
+    if not sys.stdin.isatty():
+        raise AuthenticationError(
+            "Credentials are missing in a noninteractive session. Set IO_MAGICLINKS_API_KEY "
+            "or run the command once in a terminal to paste your API key."
+        )
+    value = getpass.getpass(label, stream=sys.stderr).strip()
+    if not value:
+        raise AuthenticationError("No credential was provided")
+    return value