sharefetch 1.0.0__py3-none-any.whl

sharefetch/config.py

@@ -0,0 +1,374 @@
+"""Constants, bounds, the ``Settings`` dataclass and the boundary validators.
+
+Every constant and every bound the package uses lives here, so the command-line
+front end and the graphical front end validate an option identically and cannot
+diverge. The module is pure: it opens no socket and reads no clock.
+"""
+
+import logging
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import ValidationError
+
+logger = logging.getLogger(__name__)
+
+GRAPH_ROOT = "https://graph.microsoft.com/v1.0"
+GRAPH_HOST = "graph.microsoft.com"
+AUTHORITY_TEMPLATE = "https://login.microsoftonline.com/{tenant}"
+DEFAULT_TENANT = "organizations"
+DEFAULT_CLIENT_ID = "d3590ed6-52b3-4102-aeff-aad2292ab01c"
+
+# msal raises ValueError if offline_access, openid or profile appears here and
+# adds all three itself. See application.py:854 and :867.
+# Measured against a live tenant on 2026-09-22: the Office first-party client
+# is preauthorized for Files.Read.All and not for Sites.Read.All, so naming
+# the second fails with AADSTS65002 before tenant consent is even consulted.
+# Site lookup by path answers under the preconsented set this client already
+# holds, so the scope was never needed. An application registered in the
+# tenant may grant more; pass it with --client-id.
+MSAL_SCOPES: tuple[str, ...] = ("Files.Read.All",)
+
+ITEM_SELECT = "id,name,size,file,folder,eTag,cTag,package,parentReference"
+PAGE_SIZE = 200
+SITE_PROBE_MAX_SEGMENTS = 4
+
+DEFAULT_CONNECTIONS = 1
+CONNECTIONS_BOUNDS = (1, 2)
+
+DEFAULT_DELAY_SECONDS = 0.5
+DELAY_BOUNDS = (0.0, 60.0)
+
+DEFAULT_CHUNK_KIB = 256
+CHUNK_KIB_BOUNDS = (64, 4096)
+
+LIMIT_RATE_MIN_KBPS = 1
+
+CONNECT_TIMEOUT_SECONDS = 30
+READ_TIMEOUT_SECONDS = 60
+REQUEST_TIMEOUT = (CONNECT_TIMEOUT_SECONDS, READ_TIMEOUT_SECONDS)
+
+MAX_ATTEMPTS_PER_FILE = 5
+BACKOFF_BASE_SECONDS = 1.0
+BACKOFF_CAP_SECONDS = 60.0
+RETRY_AFTER_CLAMP = (0.0, 300.0)
+
+STATE_FLUSH_INTERVAL_SECONDS = 2.0
+FREE_SPACE_MARGIN = 0.05
+DEVICE_FLOW_POLL_TICK_SECONDS = 1.0
+GUI_DRAIN_INTERVAL_MS = 100
+GUI_LOG_MAX_LINES = 2000
+GUI_STOP_JOIN_SECONDS = 30.0
+
+STATE_FILENAME = ".sharefetch-state.json"
+STATE_SCHEMA_VERSION = 1
+MANIFEST_FILENAME = "manifest.csv"
+PART_SUFFIX = ".part"
+# Appended to a final name to form the temporary a write is built in before
+# ``os.replace`` renames it onto that name. The state file and the manifest are
+# both written this way, so the suffix is defined once here and imported by
+# both.
+TMP_SUFFIX = ".tmp"
+TOKEN_CACHE_DIRNAME = "sharefetch"
+TOKEN_CACHE_FILENAME = "token_cache.bin"
+DPAPI_ENTROPY = "sharefetch-token-cache-v1"
+
+MIN_DEPTH = 0
+
+
+# Shared status and reason vocabulary. The
+# state file, the manifest and every event carry these strings, so they are
+# defined once here and never spelled out at a call site. A reason is recorded
+# as a field, never recovered by matching the text of an exception message.
+STATUS_PENDING = "pending"
+STATUS_PARTIAL = "partial"
+STATUS_COMPLETE = "complete"
+STATUS_FAILED = "failed"
+STATUS_SKIPPED = "skipped"
+ITEM_STATUSES = frozenset(
+    {
+        STATUS_PENDING,
+        STATUS_PARTIAL,
+        STATUS_COMPLETE,
+        STATUS_FAILED,
+        STATUS_SKIPPED,
+    }
+)
+
+VERIFICATION_PASSED = "passed"
+# Check 5 warns and never fails, so a file can pass while carrying a warning.
+# The state file and the manifest both record this status, so it is shared
+# here rather than defined in verify.py, which state.py must not import.
+VERIFICATION_PASSED_WITH_WARNINGS = "passed_with_warnings"
+VERIFICATION_FAILED = "failed"
+VERIFICATION_STATUSES = frozenset(
+    {VERIFICATION_PASSED, VERIFICATION_PASSED_WITH_WARNINGS, VERIFICATION_FAILED}
+)
+
+CHECK_SIZE = "size"
+CHECK_CONTENT_HASH = "content_hash"
+CHECK_NOT_SUBSTITUTED = "not_substituted"
+CHECK_CONTAINER_INTEGRITY = "container_integrity"
+CHECK_EXTENSION_CONSISTENCY = "extension_consistency"
+VERIFICATION_CHECKS = (
+    CHECK_SIZE,
+    CHECK_CONTENT_HASH,
+    CHECK_NOT_SUBSTITUTED,
+    CHECK_CONTAINER_INTEGRITY,
+    CHECK_EXTENSION_CONSISTENCY,
+)
+
+REASON_SIZE_MISMATCH = "size_mismatch"
+REASON_HASH_MISMATCH = "hash_mismatch"
+REASON_HTML_RESPONSE = "html_response"
+REASON_CONTAINER_CORRUPT = "container_corrupt"
+REASON_PATH_TOO_LONG = "path_too_long"
+FAILURE_REASONS = frozenset(
+    {
+        REASON_SIZE_MISMATCH,
+        REASON_HASH_MISMATCH,
+        REASON_HTML_RESPONSE,
+        REASON_CONTAINER_CORRUPT,
+        REASON_PATH_TOO_LONG,
+    }
+)
+
+# Check 5 warns and never fails, so its reason is not a member of
+# FAILURE_REASONS.
+REASON_EXTENSION_MISMATCH = "extension_mismatch"
+
+
+@dataclass(frozen=True)
+class MagicRule:
+    prefix: bytes
+    family: str
+    integrity: str  # "zip" | "ole" | "pdf" | "gzip" | "jpeg" | "header"
+
+
+MAGIC_SIGNATURES: tuple[MagicRule, ...] = (
+    MagicRule(b"\x89PNG\r\n\x1a\n", "png", "header"),
+    MagicRule(b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1", "ole", "ole"),
+    MagicRule(b"\xfd7zXZ\x00", "xz", "header"),
+    MagicRule(b"7z\xbc\xaf\x27\x1c", "7z", "header"),
+    MagicRule(b"Rar!\x1a\x07", "rar", "header"),
+    MagicRule(b"PK\x03\x04", "zip", "zip"),
+    MagicRule(b"PK\x05\x06", "zip", "zip"),
+    MagicRule(b"PK\x07\x08", "zip", "zip"),
+    MagicRule(b"%PDF", "pdf", "pdf"),
+    MagicRule(b"GIF8", "gif", "header"),
+    MagicRule(b"II*\x00", "tiff", "header"),
+    MagicRule(b"MM\x00*", "tiff", "header"),
+    MagicRule(b"\x7fELF", "elf", "header"),
+    MagicRule(b"\xff\xd8\xff", "jpeg", "jpeg"),
+    MagicRule(b"BZh", "bzip2", "header"),
+    MagicRule(b"\x1f\x8b", "gzip", "gzip"),
+    MagicRule(b"BM", "bmp", "header"),
+    MagicRule(b"MZ", "pe", "header"),
+    MagicRule(b"#!", "script", "header"),
+)
+
+# Advisory only. Check 5 warns on disagreement and never fails a file.
+EXTENSION_FAMILIES: dict[str, str] = {
+    ".docx": "zip",
+    ".xlsx": "zip",
+    ".xlsm": "zip",
+    ".pptx": "zip",
+    ".odt": "zip",
+    ".ods": "zip",
+    ".odp": "zip",
+    ".zip": "zip",
+    ".jar": "zip",
+    ".doc": "ole",
+    ".xls": "ole",
+    ".ppt": "ole",
+    ".mpp": "ole",
+    ".msg": "ole",
+    ".pdf": "pdf",
+    ".gz": "gzip",
+    ".bz2": "bzip2",
+    ".xz": "xz",
+    ".7z": "7z",
+    ".rar": "rar",
+    ".png": "png",
+    ".jpg": "jpeg",
+    ".jpeg": "jpeg",
+    ".gif": "gif",
+    ".tif": "tiff",
+    ".tiff": "tiff",
+    ".bmp": "bmp",
+    ".exe": "pe",
+    ".dll": "pe",
+}
+
+HTML_MARKERS = (b"<!doctype html", b"<html", b"<head")
+HTML_SNIFF_BYTES = 1024
+HTML_MIME_TYPES = frozenset({"text/html", "application/xhtml+xml"})
+# Searched for the PDF %%EOF marker and for the JPEG FF D9 end-of-image marker,
+# so the name carries no format.
+TRAILER_WINDOW = 2048
+
+DISCARDED_QUERY_PARAMS = frozenset(
+    {
+        "viewid",
+        "ovuser",
+        "teamscid",
+        "or",
+        "ct",
+        "clickparams",
+        "e",
+        "csf",
+        "web",
+        "cid",
+        "rootfolder",
+        "folderctid",
+        "view",
+    }
+)
+SHARE_PATH_PREFIXES = ("/:f:/", "/:u:/", "/:w:/", "/:x:/", "/:p:/", "/:b:/", "/:o:/")
+MAX_DECODE_ITERATIONS = 5
+
+WINDOWS_FORBIDDEN_CHARS = '<>:"|?*'
+WINDOWS_RESERVED_NAMES = frozenset(
+    {"CON", "PRN", "AUX", "NUL"}
+    | {f"COM{i}" for i in range(1, 10)}
+    | {f"LPT{i}" for i in range(1, 10)}
+)
+MAX_PATH_SEGMENT = 255
+
+# --tenant is validated as a GUID or a domain and --client-id as a GUID, and
+# every boundary validation lives in this module.
+TENANT_ALIASES = frozenset({"organizations", "common", "consumers"})
+GUID_PATTERN = re.compile(r"\A[0-9a-fA-F]{8}(-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}\Z")
+DOMAIN_PATTERN = re.compile(
+    r"\A[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)+\Z"
+)
+
+
+@dataclass(frozen=True)
+class Settings:
+    url: str
+    dest: Path
+    connections: int = DEFAULT_CONNECTIONS
+    delay: float = DEFAULT_DELAY_SECONDS
+    limit_rate_kbps: int | None = None
+    chunk_kib: int = DEFAULT_CHUNK_KIB
+    max_depth: int | None = None
+    include: tuple[str, ...] = ()
+    exclude: tuple[str, ...] = ()
+    restart: bool = False
+    dry_run: bool = False
+    verify_only: bool = False
+    reauth: bool = False
+    tenant: str = DEFAULT_TENANT
+    client_id: str = DEFAULT_CLIENT_ID
+    ignore_free_space: bool = False
+    log_file: Path | None = None
+    verbose: bool = False
+
+    @property
+    def chunk_bytes(self) -> int:
+        return self.chunk_kib * 1024
+
+
+def check_bounds(name: str, value: float, bounds: tuple[float, float]) -> None:
+    low, high = bounds
+    if not low <= value <= high:
+        raise ValidationError(f"{name} must be between {low} and {high}, received {value}")
+
+
+def check_connections(value: int) -> int:
+    low, high = CONNECTIONS_BOUNDS
+    if value < low or value > high:
+        raise ValidationError(f"connections must be {low} or {high}, received {value}")
+    return value
+
+
+def check_delay(value: float) -> float:
+    check_bounds("delay", value, DELAY_BOUNDS)
+    return value
+
+
+def check_chunk_kib(value: int) -> int:
+    check_bounds("chunk size in KiB", value, CHUNK_KIB_BOUNDS)
+    return value
+
+
+def check_limit_rate(value: int | None) -> int | None:
+    """A rate ceiling is optional. ``None`` leaves the ceiling off."""
+    if value is None:
+        return None
+    if value < LIMIT_RATE_MIN_KBPS:
+        raise ValidationError(
+            f"rate limit must be an integer of at least {LIMIT_RATE_MIN_KBPS} KB/s, "
+            f"received {value}"
+        )
+    return value
+
+
+def check_max_depth(value: int | None) -> int | None:
+    """A depth limit is optional. ``None`` leaves the walk unbounded."""
+    if value is None:
+        return None
+    if value < MIN_DEPTH:
+        raise ValidationError(
+            f"max depth must be an integer of at least {MIN_DEPTH}, received {value}"
+        )
+    return value
+
+
+def check_dest(value: str | Path) -> Path:
+    """Return the destination as an absolute path, rejecting an unusable parent.
+
+    The destination directory itself need not exist, because the run creates it.
+    Its parent must exist and be writable, which is the earliest point at which
+    an unusable destination can be reported.
+    """
+    if value is None or not str(value).strip():
+        raise ValidationError("destination must be a directory path, received an empty value")
+    dest = Path(value).expanduser().resolve()
+    if dest.exists() and not dest.is_dir():
+        raise ValidationError(f"destination must be a directory, received {dest}, which is a file")
+    parent = dest.parent
+    if not parent.is_dir():
+        raise ValidationError(
+            f"destination parent directory must exist, received {dest}, "
+            f"whose parent {parent} does not exist"
+        )
+    if not os.access(parent, os.W_OK):
+        raise ValidationError(
+            f"destination parent directory must be writable, received {dest}, "
+            f"whose parent {parent} is not writable"
+        )
+    return dest
+
+
+def check_tenant(value: str) -> str:
+    """Accept a GUID, a domain, or one of the msal tenant aliases."""
+    candidate = (value or "").strip()
+    if not candidate:
+        raise ValidationError(
+            "tenant must be a GUID, a domain or one of "
+            f"{sorted(TENANT_ALIASES)}, received an empty value"
+        )
+    if candidate.lower() in TENANT_ALIASES:
+        return candidate.lower()
+    if GUID_PATTERN.match(candidate) or DOMAIN_PATTERN.match(candidate):
+        return candidate
+    raise ValidationError(
+        f"tenant must be a GUID, a domain or one of {sorted(TENANT_ALIASES)}, "
+        f"received {candidate!r}"
+    )
+
+
+def check_client_id(value: str) -> str:
+    """Accept a GUID in the canonical 8-4-4-4-12 form."""
+    candidate = (value or "").strip()
+    if not GUID_PATTERN.match(candidate):
+        raise ValidationError(
+            "client id must be a GUID in the form "
+            "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, "
+            f"received {candidate!r}"
+        )
+    return candidate