memorysync-cli 1.0.2__py3-none-any.whl

memorysync_cli/credentials.py

@@ -0,0 +1,259 @@
+"""Where the API key lives.
+
+Three tiers, in order: the environment, then the OS keychain, then an encrypted
+file readable only by the owner. Same order as the Node CLI, and reached through
+the same OS tools, so a key stored by one CLI is found by the other.
+
+Stated plainly, because it affects what a customer should expect:
+
+  macOS    `security`      real keychain
+  Linux    `secret-tool`   real keyring, when libsecret is installed
+  Windows  encrypted file  tier 3
+
+Windows has no scriptable Credential Manager path that does not require a
+dependency, so it lands on tier 3. That is a genuine difference rather than a
+hedge, and it is the same on the Node CLI.
+
+Tier 3 is not security theatre and is not claimed to be. The file is 0600 and the
+contents are obfuscated with a key derived from the machine and user, which stops
+a casual `cat` or a backup scraper. Anyone who can already run code as this user
+can read it. The keychain is better, which is why it is tried first.
+"""
+
+from __future__ import annotations
+
+import base64
+import getpass
+import hashlib
+import os
+import platform
+import shutil
+import subprocess
+from pathlib import Path
+
+from .config import config_dir
+
+SERVICE = "memorysync-cli"
+ENV_VAR = "MEMORYSYNC_API_KEY"
+
+
+def _account(profile: str) -> str:
+    return f"{SERVICE}:{profile}"
+
+
+def _keyfile() -> Path:
+    return config_dir() / "credentials"
+
+
+def _obfuscation_key() -> bytes:
+    """A key derived from the machine and the user.
+
+    Not a password: there is nobody to prompt. It ties the file to this account so
+    that copying it to another machine yields nothing useful, which is the actual
+    threat for a CLI credential file.
+    """
+    try:
+        user = getpass.getuser()
+    except Exception:  # noqa: BLE001 - no controlling terminal, or no passwd entry
+        user = os.environ.get("USERNAME") or os.environ.get("USER") or "unknown"
+    seed = f"{platform.node()}|{user}|{SERVICE}".encode("utf-8")
+    return hashlib.sha256(seed).digest()
+
+
+def _xor(data: bytes, key: bytes) -> bytes:
+    return bytes(byte ^ key[index % len(key)] for index, byte in enumerate(data))
+
+
+# ---------------------------------------------------------------------------
+# Tier 2: the OS keychain
+# ---------------------------------------------------------------------------
+
+
+def _keychain_tool() -> str | None:
+    if platform.system() == "Darwin" and shutil.which("security"):
+        return "security"
+    if platform.system() == "Linux" and shutil.which("secret-tool"):
+        return "secret-tool"
+    return None
+
+
+def _keychain_get(profile: str) -> str | None:
+    tool = _keychain_tool()
+    if tool is None:
+        return None
+    try:
+        if tool == "security":
+            result = subprocess.run(
+                ["security", "find-generic-password", "-a", _account(profile), "-s", SERVICE, "-w"],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+        else:
+            result = subprocess.run(
+                ["secret-tool", "lookup", "service", SERVICE, "account", _account(profile)],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+    except (OSError, subprocess.SubprocessError):
+        return None
+
+    value = (result.stdout or "").strip()
+    return value if result.returncode == 0 and value else None
+
+
+def _keychain_set(profile: str, key: str) -> bool:
+    tool = _keychain_tool()
+    if tool is None:
+        return False
+    try:
+        if tool == "security":
+            result = subprocess.run(
+                [
+                    "security",
+                    "add-generic-password",
+                    "-a",
+                    _account(profile),
+                    "-s",
+                    SERVICE,
+                    "-w",
+                    key,
+                    # Replace an existing entry instead of failing, so `init
+                    # --force` behaves the same on the second run.
+                    "-U",
+                ],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+        else:
+            result = subprocess.run(
+                ["secret-tool", "store", "--label", SERVICE, "service", SERVICE, "account", _account(profile)],
+                input=key,
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+        return result.returncode == 0
+    except (OSError, subprocess.SubprocessError):
+        return False
+
+
+def _keychain_delete(profile: str) -> bool:
+    tool = _keychain_tool()
+    if tool is None:
+        return False
+    try:
+        if tool == "security":
+            result = subprocess.run(
+                ["security", "delete-generic-password", "-a", _account(profile), "-s", SERVICE],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+        else:
+            result = subprocess.run(
+                ["secret-tool", "clear", "service", SERVICE, "account", _account(profile)],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+        return result.returncode == 0
+    except (OSError, subprocess.SubprocessError):
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Tier 3: an owner-only file
+# ---------------------------------------------------------------------------
+
+
+def _file_read(profile: str) -> str | None:
+    path = _keyfile()
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except (FileNotFoundError, OSError):
+        return None
+
+    for line in raw.splitlines():
+        name, _, blob = line.partition("=")
+        if name != profile or not blob:
+            continue
+        try:
+            return _xor(base64.b64decode(blob), _obfuscation_key()).decode("utf-8")
+        except Exception:  # noqa: BLE001 - a corrupt line is a miss, not a crash
+            return None
+    return None
+
+
+def _file_write(profile: str, key: str | None) -> None:
+    path = _keyfile()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    entries: dict[str, str] = {}
+    try:
+        for line in path.read_text(encoding="utf-8").splitlines():
+            name, _, blob = line.partition("=")
+            if name and blob:
+                entries[name] = blob
+    except (FileNotFoundError, OSError):
+        pass
+
+    if key is None:
+        entries.pop(profile, None)
+    else:
+        entries[profile] = base64.b64encode(_xor(key.encode("utf-8"), _obfuscation_key())).decode("ascii")
+
+    # Written 0600 before any content lands, so there is no window where the file
+    # exists with default permissions.
+    descriptor = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+        for name, blob in entries.items():
+            handle.write(f"{name}={blob}\n")
+
+
+# ---------------------------------------------------------------------------
+# Public surface
+# ---------------------------------------------------------------------------
+
+
+def read_key(profile: str = "default") -> str | None:
+    """The key for a profile, from the highest-priority source that has one.
+
+    The environment wins so CI can inject a key without touching a keychain or
+    writing a file to a container image.
+    """
+    from_env = os.environ.get(ENV_VAR)
+    if from_env:
+        return from_env.strip()
+    return _keychain_get(profile) or _file_read(profile)
+
+
+def write_key(key: str, profile: str = "default") -> str:
+    """Store a key and report which tier accepted it.
+
+    The tier is returned rather than logged so `init` can tell the user plainly
+    where their key went, instead of implying a keychain that was never reached.
+    """
+    if _keychain_set(profile, key):
+        return "keychain"
+    _file_write(profile, key)
+    return "file"
+
+
+def delete_key(profile: str = "default") -> None:
+    _keychain_delete(profile)
+    _file_write(profile, None)
+
+
+def describe_storage() -> str:
+    """Human description of where a key would be stored, for `doctor`."""
+    tool = _keychain_tool()
+    if tool == "security":
+        return "macOS keychain (security)"
+    if tool == "secret-tool":
+        return "Linux keyring (secret-tool)"
+    if platform.system() == "Windows":
+        return f"encrypted file, owner-only ({_keyfile()})"
+    return f"encrypted file, owner-only ({_keyfile()}) - no keychain tool found"

memorysync_cli/errors.py

@@ -0,0 +1,110 @@
+"""Failure taxonomy and exit codes.
+
+The exit codes are a contract. A CI job or an agent loop branches on them, so they
+have to match the Node CLI exactly.
+
+They are not retyped here. The numbers come from ``registry.json``, generated from
+the Node CLI's ``EXIT``, because a first draft of this module did retype them and
+got three of them wrong: QUOTA 5, NETWORK 6, NOT_FOUND 4 against the real 4, 5, 6.
+Nothing would have looked broken - every failure still exits non-zero - while a
+script branching on 4 for "over quota" would quietly take that branch on a network
+error instead. Numbers are the easiest thing to transcribe wrongly and the hardest
+to spot, so they are derived.
+
+The quota code earns its own value. The API degrades silently at a plan limit,
+returning an empty result rather than an error, because a language model must not
+narrate billing state to an end user. A distinct exit code is therefore the only
+local signal that nothing was stored, so a script does not read a silent skip as
+an empty database.
+"""
+
+from __future__ import annotations
+
+from .registry import exit_codes
+
+_CODES = exit_codes()
+
+
+class Exit:
+    """Process exit codes, mirroring ``EXIT`` in the Node CLI.
+
+    Read from the generated registry rather than declared, so the two CLIs cannot
+    disagree about what 4 means.
+    """
+
+    OK: int = _CODES["OK"]
+    FAILURE: int = _CODES["FAILURE"]
+    USAGE: int = _CODES["USAGE"]
+    AUTH: int = _CODES["AUTH"]
+    QUOTA: int = _CODES["QUOTA"]
+    NETWORK: int = _CODES["NETWORK"]
+    NOT_FOUND: int = _CODES["NOT_FOUND"]
+    INTERRUPTED: int = _CODES["INTERRUPTED"]
+
+
+class CliError(Exception):
+    """An error carrying an exit code, a stable identifier and a next step.
+
+    ``hint`` stays separate from ``message`` so agent mode can emit them as
+    distinct JSON fields instead of one blob a model has to split apart.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        exit_code: int = Exit.FAILURE,
+        code: str = "error",
+        hint: str | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.exit_code = exit_code
+        self.code = code
+        self.hint = hint
+        self.request_id = request_id
+
+    def to_dict(self) -> dict[str, object]:
+        payload: dict[str, object] = {"error": self.message, "code": self.code}
+        if self.hint:
+            payload["hint"] = self.hint
+        if self.request_id:
+            payload["request_id"] = self.request_id
+        return payload
+
+
+def usage_error(message: str, hint: str | None = None) -> CliError:
+    """The command line was wrong. Never retryable."""
+    return CliError(message, exit_code=Exit.USAGE, code="usage_error", hint=hint)
+
+
+def auth_error(message: str, hint: str | None = None) -> CliError:
+    return CliError(
+        message,
+        exit_code=Exit.AUTH,
+        code="auth_error",
+        hint=hint or "Run `memorysync init` to store a key, or set MEMORYSYNC_API_KEY.",
+    )
+
+
+def quota_error(message: str, hint: str | None = None) -> CliError:
+    return CliError(
+        message,
+        exit_code=Exit.QUOTA,
+        code="quota_exceeded",
+        hint=hint or "Run `memorysync quota` to see usage and when the cycle resets.",
+    )
+
+
+def network_error(message: str, hint: str | None = None) -> CliError:
+    return CliError(
+        message,
+        exit_code=Exit.NETWORK,
+        code="network_error",
+        hint=hint or "Run `memorysync doctor` to check connectivity.",
+    )
+
+
+def not_found_error(message: str, hint: str | None = None) -> CliError:
+    return CliError(message, exit_code=Exit.NOT_FOUND, code="not_found", hint=hint)

memorysync_cli/http.py

@@ -0,0 +1,257 @@
+"""The API client.
+
+Built on ``urllib.request`` so the package keeps zero dependencies. Mem0's Python
+CLI pulls in httpx; every dependency is code we would be putting on a customer's
+machine that they cannot audit on our behalf, which matters more for a closed
+source tool because nobody else is reading our lockfile.
+
+The job here is turning HTTP outcomes into the failure taxonomy in ``errors.py``,
+so a caller can branch on cause. Two cases deserve their own handling:
+
+  * 401/403 become AUTH, with a hint pointing at ``init`` rather than the raw body.
+  * A silent quota skip is not an HTTP error at all. Over a plan limit the API
+    answers 200 with an empty result, deliberately, so a model never repeats
+    billing state to an end user. The client therefore reads usage separately and
+    the commands decide what to say; see ``looks_like_silent_skip``.
+
+Mirrors ``sdk/cli/src/http.mjs``, including which status maps to which exit code.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+from ._version import __version__
+from .errors import (
+    CliError,
+    Exit,
+    auth_error,
+    network_error,
+    not_found_error,
+    quota_error,
+)
+
+# Header the API requires from key-authenticated callers to scope memory.
+END_USER_HEADER = "X-End-User-ID"
+
+
+class ApiClient:
+    """A thin, synchronous client over the MemorySync API."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        user: str | None = None,
+        project: str | None = None,
+        timeout: int = 60000,
+        verbose: bool = False,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.user = user
+        self.project = project
+        self.timeout = timeout
+        self.verbose = verbose
+
+    def headers(self, extra: dict[str, str] | None = None) -> dict[str, str]:
+        headers = {
+            "X-API-Key": self.api_key,
+            "Accept": "application/json",
+            # From the package version, never a literal. The Node CLI shipped
+            # 1.0.1 announcing itself as 1.0.0 because this was hardcoded.
+            "User-Agent": f"memorysync-cli-py/{__version__}",
+        }
+        # The API rejects key-authenticated memory calls without this, because
+        # memory is always scoped to (tenant, project, user) and storing
+        # everything under the key owner is not allowed. Commands validate it up
+        # front so the failure is a usage error, not a 400 from the server.
+        if self.user:
+            headers[END_USER_HEADER] = self.user
+        if self.project:
+            headers["X-Project-ID"] = self.project
+        if extra:
+            headers.update(extra)
+        return headers
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        query: dict[str, Any] | None = None,
+        timeout: int | None = None,
+    ) -> Any:
+        url = self.base_url + path
+        if query:
+            pairs = {
+                key: str(value)
+                for key, value in query.items()
+                if value is not None and value != ""
+            }
+            if pairs:
+                url = f"{url}?{urllib.parse.urlencode(pairs)}"
+
+        payload = None
+        headers = self.headers()
+        if body is not None:
+            payload = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        limit_ms = timeout or self.timeout
+        started = time.monotonic()
+        request = urllib.request.Request(url, data=payload, headers=headers, method=method)
+
+        try:
+            with urllib.request.urlopen(request, timeout=limit_ms / 1000) as response:
+                text = response.read().decode("utf-8", errors="replace")
+                status = response.status
+        except urllib.error.HTTPError as error:
+            text = error.read().decode("utf-8", errors="replace")
+            status = error.code
+        except TimeoutError:
+            raise network_error(
+                f"Request to {path} timed out after {limit_ms}ms.",
+                "Raise it with --timeout, or check your connection with `memorysync doctor`.",
+            ) from None
+        except urllib.error.URLError as error:
+            reason = getattr(error, "reason", error)
+            if isinstance(reason, TimeoutError):
+                raise network_error(
+                    f"Request to {path} timed out after {limit_ms}ms.",
+                    "Raise it with --timeout, or check your connection with `memorysync doctor`.",
+                ) from None
+            raise network_error(f"Could not reach {self.base_url}: {reason}") from None
+
+        if self.verbose:
+            elapsed = int((time.monotonic() - started) * 1000)
+            print(f"{method} {path} -> {status} in {elapsed}ms", file=sys.stderr)
+
+        parsed: Any = None
+        if text:
+            try:
+                parsed = json.loads(text)
+            except ValueError:
+                parsed = {"raw": text}
+
+        if 200 <= status < 300:
+            return parsed
+
+        raise self._to_error(status, parsed)
+
+    def _to_error(self, status: int, payload: Any) -> CliError:
+        """Map a failed response to the taxonomy.
+
+        The status alone is not enough for 429: a plan limit and a rate limit both
+        arrive as 429 but mean different things to a script. Only the first is
+        about the plan, and only the first is pointless to retry.
+        """
+        detail = payload.get("detail") if isinstance(payload, dict) else None
+        inner = detail if isinstance(detail, dict) else None
+        message = (
+            (inner or {}).get("message")
+            or (detail if isinstance(detail, str) else None)
+            or (payload.get("message") if isinstance(payload, dict) else None)
+            or f"Request failed with status {status}."
+        )
+        code = (inner or {}).get("code")
+
+        if status in (401, 403):
+            return auth_error(message)
+        if status == 404:
+            return not_found_error(message)
+        if status == 429:
+            is_plan_limit = code == "limit_exceeded" or bool(
+                re.search(r"monthly limit", message, re.IGNORECASE)
+            )
+            if is_plan_limit:
+                return quota_error(message)
+            return CliError(
+                message,
+                exit_code=Exit.NETWORK,
+                code="rate_limited",
+                hint="Too many requests. Wait and retry.",
+            )
+        if status >= 500:
+            return CliError(
+                message,
+                exit_code=Exit.NETWORK,
+                code="server_error",
+                hint="The API failed. Retry, and check status if it persists.",
+            )
+        return CliError(message, exit_code=Exit.FAILURE, code=code or "api_error")
+
+    # -----------------------------------------------------------------------
+    # Named endpoints, so commands never carry raw paths
+    # -----------------------------------------------------------------------
+
+    def add_memory(self, body: dict) -> Any:
+        return self.request("POST", "/memory/add", body=body)
+
+    def query_memory(self, body: dict) -> Any:
+        return self.request("POST", "/memory/query", body=body)
+
+    def list_memories(self, tenant_id: str, user_id: str, limit: int | None = None) -> Any:
+        tenant = urllib.parse.quote(str(tenant_id), safe="")
+        user = urllib.parse.quote(str(user_id), safe="")
+        return self.request(
+            "GET",
+            f"/v1/memory/{tenant}/{user}/list",
+            query={"limit": limit} if limit else None,
+        )
+
+    def memory_status(self, numeric_id: str) -> Any:
+        return self.request("GET", f"/v1/memory/status/{urllib.parse.quote(str(numeric_id), safe='')}")
+
+    def forget(self, body: dict) -> Any:
+        return self.request("DELETE", "/memory/forget", body=body)
+
+    # There is deliberately no purge helper here.
+    #
+    # DELETE /memory/user/purge sits under /memory/ and reads as if it clears one
+    # end user's memories. It does neither: it ignores the end-user header and
+    # erases the account behind the credential, cascading to the password hash,
+    # every API key, memberships, auth providers and MFA. The Node CLI exposed it
+    # as purgeUser() and `delete --all` called it, which deleted a live account
+    # during a cleanup step.
+    #
+    # The CLI has no feature that needs account erasure, so the method is absent
+    # rather than merely unused - an available helper with a memory-shaped name is
+    # what caused the incident. Clearing a scope goes through forget() above.
+
+    def projects(self) -> Any:
+        return self.request("GET", "/org/projects")
+
+    def usage_summary(self) -> Any:
+        return self.request("GET", "/org/billing/usage-summary")
+
+    def current_plan(self) -> Any:
+        return self.request("GET", "/org/billing/current-plan")
+
+
+def looks_like_silent_skip(payload: Any) -> bool:
+    """Whether a 200 response is really a quota refusal.
+
+    The API degrades silently at a plan limit: `add` returns success having stored
+    nothing and `search` returns an empty list, on purpose, so an assistant never
+    narrates billing state to an end user. That design makes a refusal
+    indistinguishable from a genuinely empty result unless usage is read
+    separately, which is why the commands check rather than the client guessing.
+    """
+    if not isinstance(payload, dict):
+        return False
+    if payload.get("status") == "skipped":
+        return True
+    memory_ids = payload.get("memory_ids")
+    if isinstance(memory_ids, list) and not memory_ids and "candidates_extracted" in payload:
+        return True
+    return False