tlgr-cli 2.0.1__py3-none-any.whl

tlgr/daemon/main.py

@@ -0,0 +1,161 @@
+"""The daemon entry point, in the order §6.1 requires.
+
+The order is the design. `umask` before anything creates a file; the singleton
+lock before any work, so two simultaneous starts cannot both proceed; the
+permission audit before a session file is opened; the socket bound and
+answering `ready: false` before the first account connect, so a CLI waiting to
+start us learns we exist in milliseconds rather than in however long a
+connect takes.
+
+A second daemon exits **0**, not 1. Under launchd with
+`KeepAlive.SuccessfulExit=false`, exiting non-zero means "restart me", so v1's
+`sys.exit(1)` on "already running" produced an infinite respawn loop (COR-39).
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import contextlib
+import logging
+import os
+import signal
+import sys
+from pathlib import Path
+
+from tlgr.core.config import load_app_config
+from tlgr.core.errors import ConfigurationError
+from tlgr.core.paths import TlgrPaths, require_safe_permissions
+from tlgr.core.process import daemonize, setup_logging, write_pid
+from tlgr.daemon.app import Daemon
+from tlgr.daemon.singleton import FileLock, LockBusy
+
+log = logging.getLogger("tlgr.daemon")
+
+__all__ = ["main", "run"]
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(prog="tlgr-daemon", description="the tlgr daemon")
+    parser.add_argument("--base", default="", help="tlgr home directory (default ~/.tlgr)")
+    parser.add_argument("--foreground", action="store_true", help="do not fork; log to stderr too")
+    parser.add_argument("--log-level", default="", help="debug | info | warning | error")
+    return parser.parse_args(argv)
+
+
+async def run(daemon: Daemon) -> None:
+    """Install signal handlers and run until told to stop."""
+    loop = asyncio.get_running_loop()
+    # A task with no reference can be garbage-collected mid-flight, which is
+    # COR-41: a SIGHUP reload that vanished halfway through.
+    pending: set[asyncio.Task[None]] = set()
+
+    def request_stop() -> None:
+        log.info("shutdown requested")
+        daemon.request_shutdown()
+
+    def request_reload() -> None:
+        log.info("reload requested (SIGHUP)")
+        task = loop.create_task(_reload(daemon))
+        pending.add(task)
+        task.add_done_callback(pending.discard)
+
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        with contextlib.suppress(NotImplementedError):
+            loop.add_signal_handler(sig, request_stop)
+    with contextlib.suppress(NotImplementedError, AttributeError):
+        loop.add_signal_handler(signal.SIGHUP, request_reload)
+
+    await daemon.run()
+
+
+async def _reload(daemon: Daemon) -> None:
+    from tlgr.daemon.app import _reload as reload_config
+
+    try:
+        await reload_config(daemon, ["config", "jobs", "policy"])
+    except Exception as exc:  # pragma: no cover - a bad config must not kill us
+        log.error("reload failed, keeping the running configuration: %s", exc)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(argv)
+
+    # SEC-01: before anything creates a file. A daemon started from a shell
+    # with a permissive umask would otherwise write a world-readable session,
+    # log and socket, and fixing the modes afterwards leaves a window.
+    os.umask(0o077)
+
+    base = Path(args.base).expanduser() if args.base else None
+
+    # `TlgrPaths` refuses a home marked `.production`, and that refusal has to
+    # be an exit code rather than a traceback: two daemons on one home share
+    # session files, and Telegram treats a second client on the same auth key
+    # as a compromised session and revokes it. A development build started
+    # against somebody's live home does not degrade it, it breaks it.
+    try:
+        paths = TlgrPaths(base)
+    except ConfigurationError as exc:
+        print(f"tlgr daemon: {exc}", file=sys.stderr)
+        return 10
+
+    paths.ensure_base()
+
+    try:
+        config = load_app_config(paths.base)
+    except ConfigurationError as exc:
+        print(f"tlgr daemon: {exc}", file=sys.stderr)
+        return 10
+
+    lock = FileLock(paths.lock)
+    try:
+        lock.acquire()
+    except LockBusy as exc:
+        # Exit 0: this is the expected outcome of racing a start, and a
+        # non-zero exit tells launchd to respawn us forever (COR-39).
+        print(f"tlgr daemon: already running{f' (pid {exc.pid})' if exc.pid else ''}")
+        return 0
+
+    level = args.log_level or config.daemon.log_level
+    if not args.foreground:
+        daemonize(paths.base)
+        # The pid written before the fork belongs to a process that no longer
+        # exists; the lock survives the fork, its recorded pid must too.
+        lock.write_pid()
+    setup_logging(paths.base, level, foreground=args.foreground)
+    write_pid(paths.base)
+
+    try:
+        require_safe_permissions(paths.base)
+    except ConfigurationError as exc:
+        log.error("%s", exc)
+        print(f"tlgr daemon: {exc}", file=sys.stderr)
+        lock.release()
+        return 10
+
+    managed_by = _managed_by()
+    daemon = Daemon(paths.base, config=config, managed_by=managed_by)
+    log.info(
+        "daemon starting",
+        extra={"pid": os.getpid(), "version": __import__("tlgr").__version__},
+    )
+    try:
+        asyncio.run(run(daemon))
+    except KeyboardInterrupt:  # pragma: no cover - interactive only
+        pass
+    finally:
+        lock.release()
+    return 0
+
+
+def _managed_by() -> str:
+    """Whether a supervisor started us, which changes the idle policy (§6.12)."""
+    if os.environ.get("INVOCATION_ID"):
+        return "systemd"
+    if os.environ.get("XPC_SERVICE_NAME", "").startswith("dev.tlgr"):
+        return "launchd"
+    return ""
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

tlgr/daemon/peercred.py

@@ -0,0 +1,75 @@
+"""Who is on the other end of the socket (SEC-01).
+
+The socket is 0600, which is the real control. This is defence in depth over
+it, for two reasons: a umask can be changed by anything in the process tree
+that started the daemon, and a refusal here produces an auditable log line
+naming the peer's pid, which "connection refused by file permissions" does
+not.
+
+The two platforms disagree about how to ask:
+
+* **Linux** — `getsockopt(SOL_SOCKET, SO_PEERCRED)` returns `struct ucred`,
+  three native ints: pid, uid, gid.
+* **macOS/BSD** — `getsockopt(SOL_LOCAL, LOCAL_PEERCRED)` returns
+  `struct xucred`: version (u32), uid (u32), ngroups (short), groups[16].
+  There is no pid in it. `SOL_LOCAL` is 0 and `LOCAL_PEERCRED` is 1; the
+  layout was verified on Darwin 25.6.
+
+Where neither works, `peer_of()` returns `None` and the caller falls back to
+the shared token (§8.2) — which is why `require_token` exists as a config key
+rather than a hard-coded platform test.
+"""
+
+from __future__ import annotations
+
+import hmac
+import os
+import socket
+import struct
+import sys
+from dataclasses import dataclass
+
+__all__ = ["Peer", "peer_of", "token_matches"]
+
+_SO_PEERCRED = getattr(socket, "SO_PEERCRED", 17)
+_SOL_LOCAL = 0
+_LOCAL_PEERCRED = 1
+
+
+@dataclass(frozen=True)
+class Peer:
+    uid: int
+    pid: int | None = None
+    gid: int | None = None
+
+
+def peer_of(sock: socket.socket | None) -> Peer | None:
+    """The credentials of the process on the other end, or None if unknown."""
+    if sock is None:
+        return None
+    try:
+        if sys.platform.startswith("linux"):
+            raw = sock.getsockopt(socket.SOL_SOCKET, _SO_PEERCRED, struct.calcsize("3i"))
+            pid, uid, gid = struct.unpack("3i", raw)
+            return Peer(uid=uid, pid=pid, gid=gid)
+        if sys.platform == "darwin" or "bsd" in sys.platform:
+            raw = sock.getsockopt(_SOL_LOCAL, _LOCAL_PEERCRED, 4 + 4 + 2 + 4 * 16)
+            # cr_version, cr_uid — the rest of xucred is groups we do not need.
+            _version, uid = struct.unpack_from("=II", raw, 0)
+            return Peer(uid=uid)
+    except (OSError, struct.error):
+        return None
+    return None
+
+
+def token_matches(supplied: str | None, expected: str | None) -> bool:
+    """Constant-time comparison; both sides absent is *not* a match."""
+    if not expected:
+        return False
+    if not supplied:
+        return False
+    return hmac.compare_digest(supplied.strip(), expected.strip())
+
+
+def current_uid() -> int:
+    return os.getuid()

tlgr/daemon/policy.py

@@ -0,0 +1,113 @@
+"""The operation allowlist, enforced where it cannot be bypassed (SEC-04).
+
+Three properties, each of which v1 lacked:
+
+* **matched by canonical id.** `--enable-commands message.send` also permits
+  the `send` alias and the legacy `message send` path, because every name is
+  canonicalised through the registry before it is compared. v1 matched the
+  literal command path, so an allowlist written against one spelling let the
+  other through — or, more often, blocked a command the operator thought they
+  had allowed.
+* **enforced in the daemon.** The CLI checks too, for a fast, local error, but
+  the CLI flag is under the agent's control. The daemon's copy is the one with
+  teeth, and it comes from `config.toml` or a token-bound policy file.
+* **`deny` beats `allow`,** and behaviour classes (`*:mutating`,
+  `*:destructive`, `*:read`) can be denied wholesale, so "this agent may read
+  anything and change nothing" is one entry instead of five hundred.
+
+This is a usability guard, not a sandbox: anything that can open the socket can
+also read the session file. §8.3 says so, and `SECURITY.md` repeats it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from tlgr.core.errors import PermissionError_
+
+if TYPE_CHECKING:  # pragma: no cover
+    from tlgr.ops._spec import OperationSpec
+
+__all__ = ["Policy", "PolicyDecision"]
+
+#: Behaviour classes usable in place of an id.
+_CLASSES = {"read", "mutating", "destructive", "stream", "local"}
+
+
+@dataclass(frozen=True)
+class PolicyDecision:
+    allowed: bool
+    reason: str = ""
+
+
+@dataclass
+class Policy:
+    """An allow/deny pair over canonical operation ids."""
+
+    allow: list[str] = field(default_factory=lambda: ["*"])
+    deny: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_config(cls, allow: list[str] | None, deny: list[str] | None) -> Policy:
+        return cls(allow=list(allow or ["*"]), deny=list(deny or []))
+
+    @classmethod
+    def parse(cls, spec: str) -> Policy:
+        """Parse a `--enable-commands`-style string into an allowlist."""
+        entries = [e.strip() for e in spec.replace(" ", ",").split(",") if e.strip()]
+        return cls(allow=entries or ["*"])
+
+    # -- matching ----------------------------------------------------------
+
+    def _canonical(self, name: str) -> str:
+        from tlgr.registry import ALIASES
+
+        key = name.strip().lower().replace(" ", ".")
+        return ALIASES.get(key, key)
+
+    def _classes_of(self, spec: OperationSpec | None) -> set[str]:
+        if spec is None:
+            return set()
+        classes = {"stream"} if spec.stream else set()
+        if spec.destructive:
+            classes |= {"mutating", "destructive"}
+        elif spec.mutating:
+            classes.add("mutating")
+        else:
+            classes.add("read")
+        if spec.surface.value == "local":
+            classes.add("local")
+        return classes
+
+    def _matches(self, entry: str, op_id: str, classes: set[str]) -> bool:
+        entry = entry.strip().lower()
+        if not entry:
+            return False
+        if entry in ("*", "all"):
+            return True
+        if entry.startswith("*:"):
+            return entry[2:] in classes and entry[2:] in _CLASSES
+        if entry.endswith(".*"):
+            return op_id.startswith(entry[:-1])
+        resolved = self._canonical(entry)
+        return resolved == op_id or op_id.startswith(f"{resolved}.")
+
+    def check(self, op_id: str, spec: OperationSpec | None = None) -> PolicyDecision:
+        """Is *op_id* permitted? `deny` wins over `allow`, always."""
+        canonical = self._canonical(op_id)
+        classes = self._classes_of(spec)
+        for entry in self.deny:
+            if self._matches(entry, canonical, classes):
+                return PolicyDecision(False, f"denied by policy entry {entry!r}")
+        for entry in self.allow:
+            if self._matches(entry, canonical, classes):
+                return PolicyDecision(True)
+        return PolicyDecision(False, "not in the policy allowlist")
+
+    def enforce(self, op_id: str, spec: OperationSpec | None = None) -> None:
+        decision = self.check(op_id, spec)
+        if not decision.allowed:
+            raise PermissionError_(
+                f"operation {op_id!r} is not enabled: {decision.reason}",
+            )