waidrop-cli 1.0.0__py3-none-any.whl

waidrop_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Query encrypted WAiDrop archives."""
+
+__version__ = "1.0.0"

waidrop_cli/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

waidrop_cli/archive.py

@@ -0,0 +1,103 @@
+"""Archive format detection and encrypted object access."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from .crypto import (
+    chat_hash,
+    decrypt_media,
+    decrypt_text,
+    derive_keys,
+    derive_media_key,
+    media_hash,
+)
+from .errors import RemoteError, UsageError
+
+if TYPE_CHECKING:
+    from .config import DropboxConfig
+
+ENCRYPTED = "encrypted"
+SUPPORTED_FORMAT = 4
+FORMAT_OBJECT = "_format.json"
+
+
+class ArchiveCodec:
+    """Read encrypted archive objects."""
+
+    def __init__(self, archive_key: str = "", version: int = SUPPORTED_FORMAT):
+        self.version = version
+        if not archive_key:
+            raise UsageError(
+                "archive is encrypted; encryption key required "
+                "(--key, WAIDROP_KEY, or `waidrop config`)"
+            )
+        try:
+            self._hash_key, self._enc_key = derive_keys(archive_key)
+            self._media_key = derive_media_key(archive_key)
+        except ValueError as exc:
+            raise UsageError(str(exc)) from exc
+
+    @property
+    def part_suffix(self) -> str:
+        return ".enc"
+
+    @property
+    def chat_suffix(self) -> str:
+        return ".enc"
+
+    @property
+    def media_suffix(self) -> str:
+        return ".enc"
+
+    def decode_text(self, payload: bytes | bytearray) -> str:
+        return decrypt_text(self._enc_key, bytes(payload))
+
+    def decode_media(self, relative_path: str, payload: bytes | bytearray) -> bytes:
+        return decrypt_media(self._media_key, relative_path, bytes(payload))
+
+    def chat_hash(self, chat_id: str) -> str:
+        return chat_hash(self._hash_key, chat_id)
+
+    def media_hash(self, msg_id: str) -> str:
+        return media_hash(self._hash_key, msg_id)
+
+
+def parse_format_marker(payload: bytes) -> tuple[int, str]:
+    try:
+        document = json.loads(payload.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise RemoteError(f"archive format marker is invalid: {exc}") from exc
+    if not isinstance(document, dict):
+        raise RemoteError("archive format marker is invalid: expected a JSON object")
+    layout = document.get("layout")
+    if layout != "waidrop":
+        raise RemoteError(f"unsupported archive layout: {layout!r}")
+
+    version = document.get("format")
+    if not isinstance(version, int) or isinstance(version, bool) or version < 1:
+        raise RemoteError("archive format marker is invalid: missing format version")
+    if version != SUPPORTED_FORMAT:
+        raise RemoteError(f"unsupported archive format {version}; update waidrop-cli")
+
+    mode = document.get("mode")
+    if mode == "plaintext":
+        raise RemoteError(
+            "plaintext archives are no longer supported; re-export with encryption enabled"
+        )
+    if mode != ENCRYPTED:
+        raise RemoteError(f"unsupported archive mode: {mode!r}")
+    return version, mode
+
+
+def read_format(client, cfg: DropboxConfig) -> tuple[int, str]:
+    payload = client.download(f"{cfg.account_root}/{FORMAT_OBJECT}")
+    if payload is None:
+        raise RemoteError("archive format marker is missing")
+    return parse_format_marker(payload)
+
+
+def resolve_archive(client, cfg: DropboxConfig) -> ArchiveCodec:
+    version, _mode = read_format(client, cfg)
+    return ArchiveCodec(archive_key=cfg.archive_key, version=version)

waidrop_cli/auth.py

@@ -0,0 +1,321 @@
+"""Dropbox OAuth (PKCE, offline access) and local credential storage.
+
+The CLI is a public client: it ships only the app key (client id), never a
+client secret. Each user authorizes once; we store a long-lived refresh token
+and mint short-lived access tokens on demand. The archive lives in the Dropbox
+App Folder, which is namespaced per app, so the CLI must use the same app key
+as the extension to see the same folder.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import secrets
+import stat
+import tempfile
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .errors import RemoteError, UsageError
+
+AUTHORIZE_URL = "https://www.dropbox.com/oauth2/authorize"
+DEFAULT_TOKEN_URL = "https://api.dropboxapi.com/oauth2/token"
+DEFAULT_REVOKE_URL = "https://api.dropboxapi.com/2/auth/token/revoke"
+DEFAULT_API_BASE = "https://api.dropboxapi.com/2"
+DEFAULT_CONTENT_BASE = "https://content.dropboxapi.com/2"
+
+# Read-only scopes for the CLI. The extension additionally requests
+# files.content.write so it can upload the archive.
+CLI_SCOPES = ("account_info.read", "files.metadata.read", "files.content.read")
+REQUIRED_SCOPES = ("files.metadata.read", "files.content.read")
+
+# Set at release; must match the extension's DEFAULT_DROPBOX_APP_KEY. The app
+# key is a public client id and is safe to ship. Never ship a client secret.
+DEFAULT_APP_KEY = "ydtsl7okrf4xuee"
+
+EXPIRY_SKEW_SECONDS = 60
+CREDENTIALS_VERSION = 1
+
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def generate_pkce() -> tuple[str, str]:
+    """Return (code_verifier, code_challenge) using S256."""
+    verifier = secrets.token_urlsafe(48)
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    return verifier, _b64url(digest)
+
+
+def build_authorize_url(
+    app_key: str,
+    *,
+    code_challenge: str,
+    redirect_uri: str | None = None,
+    state: str | None = None,
+    scopes: tuple[str, ...] = CLI_SCOPES,
+) -> str:
+    params = {
+        "client_id": app_key,
+        "response_type": "code",
+        "token_access_type": "offline",
+        "code_challenge": code_challenge,
+        "code_challenge_method": "S256",
+        "scope": " ".join(scopes),
+    }
+    if redirect_uri:
+        params["redirect_uri"] = redirect_uri
+    if state:
+        params["state"] = state
+    return f"{AUTHORIZE_URL}?{urllib.parse.urlencode(params)}"
+
+
+def _read_error_body(exc: urllib.error.HTTPError) -> str:
+    cached = getattr(exc, "_cached_body", None)
+    if cached is not None:
+        return cached
+    try:
+        detail = exc.read().decode("utf-8", errors="replace")[:300]
+    except Exception:
+        detail = ""
+    exc._cached_body = detail
+    return detail
+
+
+def _token_error(detail: str, context: str) -> RemoteError:
+    try:
+        document = json.loads(detail)
+    except (json.JSONDecodeError, TypeError):
+        return RemoteError(f"Dropbox token request failed: {detail or 'unknown error'}")
+    code = document.get("error")
+    description = document.get("error_description") or ""
+    if code == "invalid_grant":
+        if context == "refresh token":
+            return RemoteError(
+                "Dropbox refresh token was revoked or expired; run `waidrop auth` again"
+            )
+        return RemoteError(
+            "the authorization code expired or was already used; run `waidrop auth` again"
+        )
+    if code in ("invalid_scope", "missing_scope"):
+        return RemoteError(
+            f"Dropbox scope error ({code}): {description or 'enable the required scopes in the App Console'}"
+        )
+    if code == "unauthorized_client":
+        return RemoteError(
+            "Dropbox rejected the app key; check WAIDROP_DROPBOX_APP_KEY / --dropbox-app-key"
+        )
+    message = f"Dropbox token request failed: {code or 'unknown'}"
+    if description:
+        message += f" ({description})"
+    return RemoteError(message)
+
+
+def _token_request(token_url: str, payload: dict, timeout: float, context: str) -> dict:
+    request = urllib.request.Request(
+        token_url,
+        data=urllib.parse.urlencode(payload).encode("utf-8"),
+        method="POST",
+        headers={"content-type": "application/x-www-form-urlencoded"},
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            return json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        raise _token_error(_read_error_body(exc), context) from exc
+    except urllib.error.URLError as exc:
+        raise RemoteError(f"cannot reach Dropbox: {exc.reason}") from exc
+
+
+def exchange_code(
+    *,
+    app_key: str,
+    code: str,
+    code_verifier: str,
+    token_url: str = DEFAULT_TOKEN_URL,
+    redirect_uri: str | None = None,
+    client_secret: str | None = None,
+    timeout: float = 60.0,
+) -> dict:
+    payload = {
+        "grant_type": "authorization_code",
+        "code": code,
+        "client_id": app_key,
+        "code_verifier": code_verifier,
+    }
+    if redirect_uri:
+        payload["redirect_uri"] = redirect_uri
+    if client_secret:
+        payload["client_secret"] = client_secret
+    return _token_request(token_url, payload, timeout, context="authorization code")
+
+
+def refresh_access_token(
+    *,
+    app_key: str,
+    refresh_token: str,
+    token_url: str = DEFAULT_TOKEN_URL,
+    client_secret: str | None = None,
+    timeout: float = 60.0,
+) -> dict:
+    payload = {
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token,
+        "client_id": app_key,
+    }
+    if client_secret:
+        payload["client_secret"] = client_secret
+    return _token_request(token_url, payload, timeout, context="refresh token")
+
+
+def _split_scope(value) -> list[str]:
+    if not value:
+        return []
+    if isinstance(value, (list, tuple)):
+        return [str(item) for item in value]
+    return str(value).split()
+
+
+def parse_token_document(document: dict) -> dict:
+    access_token = document.get("access_token")
+    if not access_token:
+        raise RemoteError("Dropbox token response contained no access token")
+    expires_in = document.get("expires_in")
+    return {
+        "access_token": access_token,
+        "refresh_token": document.get("refresh_token"),
+        "expires_at": time.time() + float(expires_in) if expires_in else None,
+        "scope": _split_scope(document.get("scope")),
+        "account_id": document.get("account_id"),
+    }
+
+
+def missing_scopes(granted, required: tuple[str, ...] = REQUIRED_SCOPES) -> list[str]:
+    granted_set = set(granted or [])
+    return [scope for scope in required if scope not in granted_set]
+
+
+@dataclass
+class Credentials:
+    app_key: str
+    refresh_token: str
+    access_token: str | None = None
+    expires_at: float | None = None
+    scope: list[str] = field(default_factory=list)
+    account_id: str | None = None
+    account_name: str | None = None
+    email: str | None = None
+    obtained_at: str | None = None
+
+    def to_dict(self) -> dict:
+        return {
+            "version": CREDENTIALS_VERSION,
+            "app_key": self.app_key,
+            "refresh_token": self.refresh_token,
+            "access_token": self.access_token,
+            "expires_at": self.expires_at,
+            "scope": list(self.scope),
+            "account_id": self.account_id,
+            "account_name": self.account_name,
+            "email": self.email,
+            "obtained_at": self.obtained_at,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Credentials:
+        return cls(
+            app_key=str(data["app_key"]),
+            refresh_token=str(data.get("refresh_token") or ""),
+            access_token=data.get("access_token"),
+            expires_at=float(data["expires_at"]) if data.get("expires_at") is not None else None,
+            scope=_split_scope(data.get("scope")),
+            account_id=data.get("account_id"),
+            account_name=data.get("account_name"),
+            email=data.get("email"),
+            obtained_at=data.get("obtained_at"),
+        )
+
+
+def default_credentials_path() -> Path:
+    if os.name == "nt":
+        base = Path(os.environ.get("APPDATA") or Path.home())
+        return base / "waidrop" / "credentials.json"
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".config"
+    return base / "waidrop" / "credentials.json"
+
+
+def resolve_credentials_path(args) -> Path:
+    explicit = getattr(args, "credentials_file", None) or os.environ.get("WAIDROP_CREDENTIALS")
+    if explicit:
+        return Path(str(explicit)).expanduser()
+    return default_credentials_path()
+
+
+def load_credentials(path) -> Credentials | None:
+    if os.name != "nt":
+        try:
+            mode = stat.S_IMODE(os.stat(path).st_mode)
+        except FileNotFoundError:
+            return None
+        except OSError:
+            return None
+        if mode & 0o077:
+            raise UsageError(
+                f"credentials file {path} must not be readable or writable by "
+                f"group/others; run `chmod 600 {path}`"
+            )
+    try:
+        with open(path, encoding="utf-8") as handle:
+            data = json.load(handle)
+    except (FileNotFoundError, OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(data, dict) or data.get("version") != CREDENTIALS_VERSION:
+        return None
+    try:
+        return Credentials.from_dict(data)
+    except (KeyError, TypeError, ValueError):
+        return None
+
+
+def save_credentials(path, creds: Credentials) -> None:
+    path = Path(path)
+    parent = path.parent
+    existed = parent.exists()
+    parent.mkdir(parents=True, exist_ok=True)
+    if not existed or parent == default_credentials_path().parent:
+        try:
+            os.chmod(parent, 0o700)
+        except OSError:
+            pass
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=".credentials-", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(creds.to_dict(), handle, indent=2)
+            handle.write("\n")
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def delete_credentials(path) -> bool:
+    try:
+        Path(path).unlink()
+        return True
+    except FileNotFoundError:
+        return False
+    except OSError:
+        return False

waidrop_cli/auth_flow.py

@@ -0,0 +1,182 @@
+"""Interactive Dropbox authorization flows: paste-code and loopback.
+
+The paste flow is the default: it needs no redirect URI registration and works
+over SSH and on headless hosts (the user opens the URL anywhere and pastes the
+code back). The loopback flow is optional and gives a smoother desktop
+experience; its redirect URI must be registered in the App Console.
+"""
+
+from __future__ import annotations
+
+import hmac
+import secrets
+import sys
+import threading
+import webbrowser
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlparse
+
+from .auth import (
+    CLI_SCOPES,
+    build_authorize_url,
+    exchange_code,
+    generate_pkce,
+    parse_token_document,
+)
+from .errors import RemoteError, UsageError
+
+LOOPBACK_PORT = 53682
+LOOPBACK_PATH = "/callback"
+
+
+def _open_browser(url: str, open_browser: bool) -> None:
+    if not open_browser:
+        return
+    try:
+        webbrowser.open(url)
+    except Exception:
+        pass
+
+
+def run_paste_flow(
+    *,
+    app_key: str,
+    token_url: str,
+    client_secret: str | None = None,
+    open_browser: bool = True,
+    code: str | None = None,
+    input_fn=input,
+    print_fn=print,
+    timeout: float = 60.0,
+) -> dict:
+    verifier, challenge = generate_pkce()
+    url = build_authorize_url(app_key, code_challenge=challenge, scopes=CLI_SCOPES)
+
+    print_fn("Connect WAiDrop to Dropbox:")
+    print_fn("  1. Open this URL in a browser:")
+    print_fn(f"     {url}")
+    print_fn('  2. Click "Allow", then copy the authorization code Dropbox shows.')
+
+    if code is None and not sys.stdin.isatty():
+        raise UsageError(
+            "cannot prompt for the authorization code in a non-interactive session; "
+            "pass --code <CODE> or use --loopback"
+        )
+    _open_browser(url, open_browser)
+
+    if code is None:
+        code = input_fn("  Paste the authorization code: ").strip()
+    if not code:
+        raise UsageError("no authorization code provided")
+
+    document = exchange_code(
+        app_key=app_key,
+        code=code,
+        code_verifier=verifier,
+        token_url=token_url,
+        client_secret=client_secret,
+        timeout=timeout,
+    )
+    return parse_token_document(document)
+
+
+def _result_page(ok: bool) -> str:
+    if ok:
+        body = "WAiDrop connected to Dropbox. You can close this tab and return to the terminal."
+    else:
+        body = "WAiDrop could not complete the connection. Check the terminal for details."
+    return f"<!doctype html><html><head><meta charset=utf-8></head><body><h1>WAiDrop</h1><p>{body}</p></body></html>"
+
+
+def run_loopback_flow(
+    *,
+    app_key: str,
+    token_url: str,
+    port: int = LOOPBACK_PORT,
+    client_secret: str | None = None,
+    open_browser: bool = True,
+    timeout: float = 300.0,
+    print_fn=print,
+) -> dict:
+    verifier, challenge = generate_pkce()
+    state = secrets.token_urlsafe(24)
+    redirect_uri = f"http://127.0.0.1:{port}{LOOPBACK_PATH}"
+    url = build_authorize_url(
+        app_key, code_challenge=challenge, redirect_uri=redirect_uri, state=state, scopes=CLI_SCOPES
+    )
+
+    result: dict = {"code": None, "error": None, "state_ok": False}
+    done = threading.Event()
+
+    class Handler(BaseHTTPRequestHandler):
+        def log_message(self, *args):  # silence request logging
+            return
+
+        def do_GET(self):
+            parsed = urlparse(self.path)
+            if parsed.path != LOOPBACK_PATH:
+                self.send_response(404)
+                self.end_headers()
+                return
+            query = parse_qs(parsed.query)
+            got_state = (query.get("state") or [""])[0]
+            state_ok = hmac.compare_digest(got_state, state)
+            result["state_ok"] = state_ok
+            if not state_ok:
+                self.send_response(400)
+                self.send_header("content-type", "text/html; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(_result_page(False).encode("utf-8"))
+                return
+            if "code" in query:
+                result["code"] = query["code"][0]
+            elif "error" in query:
+                description = (query.get("error_description") or [""])[0]
+                result["error"] = f"{query['error'][0]} {description}".strip()
+            else:
+                result["error"] = "missing authorization code"
+            self.send_response(200)
+            self.send_header("content-type", "text/html; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(_result_page(result["code"] is not None).encode("utf-8"))
+            done.set()
+
+    try:
+        server = ThreadingHTTPServer(("127.0.0.1", port), Handler)
+    except OSError as exc:
+        raise UsageError(
+            f"cannot bind the loopback callback on 127.0.0.1:{port} ({exc}); "
+            "pick another --port or use the paste flow"
+        ) from exc
+
+    server_thread = threading.Thread(target=server.serve_forever, daemon=True)
+    server_thread.start()
+    try:
+        print_fn(
+            f"Waiting for Dropbox authorization at {redirect_uri} (timeout {int(timeout)}s)..."
+        )
+        _open_browser(url, open_browser)
+        if not done.wait(timeout):
+            raise UsageError(
+                "timed out waiting for Dropbox authorization; run again or use the paste flow"
+            )
+    finally:
+        server.shutdown()
+        server.server_close()
+        server_thread.join(timeout=2)
+
+    if not result["state_ok"]:
+        raise RemoteError("authorization state mismatch (possible CSRF); run `waidrop auth` again")
+    if result["error"]:
+        raise UsageError(f"Dropbox authorization failed: {result['error']}")
+
+    document = exchange_code(
+        app_key=app_key,
+        code=result["code"],
+        code_verifier=verifier,
+        token_url=token_url,
+        redirect_uri=redirect_uri,
+        client_secret=client_secret,
+        timeout=60.0,
+    )
+    return parse_token_document(document)