booking-agent-cli 0.1.0__py3-none-any.whl

booking_agent/calendar/oauth_listener.py

@@ -0,0 +1,287 @@
+"""Out-of-process Google OAuth callback listener.
+
+``start`` binds the callback port in the calling process, hands the listening
+socket to a detached child, records the child, and returns. The calling command
+therefore exits right away, and a harness that kills it cannot take the listener
+down with it or leave the port bound: the child stops on its own at its deadline.
+
+``status`` and ``cleanup`` read and clear the record, so a later command can
+report the result or release a listener that is no longer wanted.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import signal
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from booking_agent.secure_file import ensure_private_dir, write_private_text
+
+STATUS_PENDING = "pending"
+STATUS_CONNECTED = "connected"
+STATUS_TIMEOUT = "timeout"
+STATUS_FAILED = "failed"
+STATUS_NONE = "none"
+
+# A child is only signalled while it can still be ours: past this grace the pid may
+# belong to an unrelated process, and the child has already exited on its own.
+_KILL_GRACE_SECONDS = 30
+_BIND_HOST = "0.0.0.0"
+
+
+class CallbackPortBusy(RuntimeError):
+    """The OAuth redirect port is held by another process."""
+
+    def __init__(self, port: int):
+        super().__init__(f"Port {port} is already in use, so the sign-in callback cannot start.")
+        self.port = port
+
+
+def _state_dir() -> Path:
+    from booking_agent.settings import booking_agent_home
+
+    return booking_agent_home() / ".calendar-oauth"
+
+
+def _record_path() -> Path:
+    return _state_dir() / "listener.json"
+
+
+def _result_path() -> Path:
+    return _state_dir() / "result.json"
+
+
+def _read_json(path: Path) -> Optional[Dict[str, Any]]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _remove(path: Path) -> None:
+    try:
+        path.unlink()
+    except FileNotFoundError:
+        pass
+    except OSError:
+        pass
+
+
+def pid_alive(pid: int) -> bool:
+    if pid <= 0:
+        return False
+    if os.name == "nt":
+        out = subprocess.run(
+            ["tasklist", "/FI", f"PID eq {pid}", "/NH"],
+            capture_output=True, text=True, check=False,
+        ).stdout
+        return str(pid) in out
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def _terminate(pid: int) -> None:
+    if os.name == "nt":
+        subprocess.run(["taskkill", "/PID", str(pid), "/F"], capture_output=True, check=False)
+        return
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except OSError:
+        return
+    for _ in range(20):
+        if not pid_alive(pid):
+            return
+        time.sleep(0.1)
+    try:
+        os.kill(pid, signal.SIGKILL)
+    except OSError:
+        pass
+
+
+def _record_owns_live_child(record: Dict[str, Any]) -> bool:
+    pid = int(record.get("pid") or 0)
+    deadline = float(record.get("deadline") or 0)
+    return time.time() < deadline + _KILL_GRACE_SECONDS and pid_alive(pid)
+
+
+def cleanup() -> bool:
+    """Stop a recorded listener and forget it. True when a running child was stopped."""
+    record = _read_json(_record_path())
+    stopped = False
+    if record and _record_owns_live_child(record):
+        _terminate(int(record["pid"]))
+        stopped = True
+    _remove(_record_path())
+    _remove(_result_path())
+    return stopped
+
+
+def _bind(port: int) -> socket.socket:
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    if os.name != "nt":
+        # Only lets a port in TIME_WAIT be reused; a live listener still refuses the bind.
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    try:
+        sock.bind((_BIND_HOST, port))
+        sock.listen(16)
+    except OSError as exc:
+        sock.close()
+        raise CallbackPortBusy(port) from exc
+    return sock
+
+
+def start(
+    *,
+    port: int,
+    state: str,
+    pkce: Dict[str, str],
+    mode: str,
+    timeout: int,
+) -> Dict[str, Any]:
+    """Start the callback child for one sign-in attempt and return its record."""
+    cleanup()
+    ensure_private_dir(_state_dir())
+    sock = _bind(port)
+    deadline = time.time() + timeout
+    payload = {
+        "state": state,
+        "pkce": pkce,
+        "deadline": deadline,
+        "port": port,
+        "result_path": str(_result_path()),
+    }
+    kwargs: Dict[str, Any] = {
+        "stdin": subprocess.PIPE,
+        "stdout": subprocess.DEVNULL,
+        "stderr": subprocess.DEVNULL,
+        "env": dict(os.environ),
+    }
+    if os.name == "nt":
+        kwargs["creationflags"] = getattr(subprocess, "DETACHED_PROCESS", 0) | getattr(
+            subprocess, "CREATE_NEW_PROCESS_GROUP", 0,
+        )
+        sock.close()
+    else:
+        sock.set_inheritable(True)
+        payload["fd"] = sock.fileno()
+        kwargs["pass_fds"] = (sock.fileno(),)
+        kwargs["start_new_session"] = True
+    try:
+        child = subprocess.Popen(
+            [sys.executable, "-m", "booking_agent.calendar.oauth_listener"], **kwargs,
+        )
+        assert child.stdin is not None
+        child.stdin.write(json.dumps(payload).encode("utf-8"))
+        child.stdin.close()
+    finally:
+        if os.name != "nt":
+            sock.close()
+    record = {
+        "pid": child.pid,
+        "port": port,
+        "mode": mode,
+        "state": state,
+        "deadline": deadline,
+        "started_at": time.time(),
+    }
+    write_private_text(_record_path(), json.dumps(record))
+    return record
+
+
+def status() -> Dict[str, Any]:
+    """Current sign-in attempt: ``pending``, ``connected``, ``timeout``, ``failed``, or ``none``."""
+    record = _read_json(_record_path())
+    if not record:
+        return {"status": STATUS_NONE}
+    out = {"status": STATUS_PENDING, "mode": record.get("mode"), "deadline": record.get("deadline")}
+    result = _read_json(_result_path())
+    if result and result.get("state") == record.get("state"):
+        out["status"] = result.get("status") or STATUS_FAILED
+        if result.get("error"):
+            out["error"] = result["error"]
+        return out
+    if time.time() >= float(record.get("deadline") or 0):
+        out["status"] = STATUS_TIMEOUT
+        return out
+    if not pid_alive(int(record.get("pid") or 0)):
+        out["status"] = STATUS_FAILED
+        out["error"] = "The sign-in listener stopped before Google Calendar was connected."
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Child process
+# ---------------------------------------------------------------------------
+
+
+def _write_result(path: str, state: str, status_value: str, error: Optional[str] = None) -> None:
+    body: Dict[str, Any] = {"state": state, "status": status_value}
+    if error:
+        body["error"] = error
+    write_private_text(Path(path), json.dumps(body))
+
+
+async def _serve(payload: Dict[str, Any]) -> None:
+    import uvicorn
+
+    from booking_agent.calendar import google
+
+    state = payload["state"]
+    google._PKCE_STORE[state] = dict(payload["pkce"])
+    if "fd" in payload:
+        config = uvicorn.Config(google._build_callback_app(), fd=int(payload["fd"]), log_level="warning")
+    else:
+        config = uvicorn.Config(
+            google._build_callback_app(), host=_BIND_HOST, port=int(payload["port"]), log_level="warning",
+        )
+    server = uvicorn.Server(config)
+    result_path = payload["result_path"]
+    deadline = float(payload["deadline"])
+
+    async def _watch() -> None:
+        while not server.should_exit:
+            if state in google._TOKEN_STORE:
+                _write_result(result_path, state, STATUS_CONNECTED)
+                # Let the success page reach the browser before the listener stops.
+                await asyncio.sleep(1.5)
+                server.should_exit = True
+                return
+            if google._OAUTH_FAILURES.get(state):
+                _write_result(result_path, state, STATUS_FAILED, google._OAUTH_FAILURES[state])
+                await asyncio.sleep(1.5)
+                server.should_exit = True
+                return
+            if time.time() >= deadline:
+                _write_result(result_path, state, STATUS_TIMEOUT)
+                server.should_exit = True
+                return
+            await asyncio.sleep(0.5)
+
+    watcher = asyncio.create_task(_watch())
+    try:
+        await server.serve()
+    except (OSError, SystemExit) as exc:
+        _write_result(result_path, state, STATUS_FAILED, f"The sign-in listener could not start ({type(exc).__name__}).")
+    finally:
+        watcher.cancel()
+
+
+def main() -> None:
+    payload = json.loads(sys.stdin.read() or "{}")
+    asyncio.run(_serve(payload))
+
+
+if __name__ == "__main__":
+    main()

booking_agent/calendar/scope.py

@@ -0,0 +1,97 @@
+"""Google Calendar OAuth scope helpers for the Booking Agent CLI."""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Tuple
+
+import httpx
+
+from booking_agent.http_deadlines import coerce_timeout
+
+SCOPE_FREEBUSY = "https://www.googleapis.com/auth/calendar.freebusy"
+SCOPE_EVENTS = "https://www.googleapis.com/auth/calendar.events"
+SCOPE_FULL = "https://www.googleapis.com/auth/calendar"
+
+CALENDAR_MODE_NONE = "none"
+CALENDAR_MODE_FREEBUSY = "freebusy"
+CALENDAR_MODE_EVENTS = "events"
+
+TOKENINFO_URL = "https://www.googleapis.com/oauth2/v3/tokeninfo"
+
+TOKENINFO_ERROR_INVALID = "invalid_token"
+TOKENINFO_ERROR_HTTP = "tokeninfo_http_error"
+TOKENINFO_ERROR_UNAVAILABLE = "tokeninfo_unavailable"
+
+_WRITE_SCOPE_EXACT = {SCOPE_EVENTS, SCOPE_FULL}
+
+
+def oauth_scope_param(mode: str) -> str:
+    """Space-delimited scope string for Google OAuth consent."""
+    if mode == CALENDAR_MODE_EVENTS:
+        return f"{SCOPE_FREEBUSY} {SCOPE_EVENTS}"
+    return SCOPE_FREEBUSY
+
+
+def scope_string(tokeninfo: Dict[str, Any]) -> str:
+    return str(tokeninfo.get("scope") or "")
+
+
+def supports_freebusy(scope: str) -> bool:
+    if not scope:
+        return False
+    parts = scope.split()
+    if SCOPE_FULL in parts or SCOPE_FREEBUSY in parts:
+        return True
+    if supports_events(scope):
+        return True
+    return "calendar.readonly" in scope or "calendar.freebusy" in scope
+
+
+def supports_events(scope: str) -> bool:
+    if not scope:
+        return False
+    parts = scope.split()
+    if any(p in _WRITE_SCOPE_EXACT for p in parts):
+        return True
+    return SCOPE_FULL in parts
+
+
+def scope_satisfies_mode(scope: str, mode: str) -> bool:
+    if mode == CALENDAR_MODE_EVENTS:
+        return supports_freebusy(scope) and supports_events(scope)
+    if mode == CALENDAR_MODE_FREEBUSY:
+        return supports_freebusy(scope)
+    return False
+
+
+def fetch_tokeninfo(access_token: str) -> Dict[str, Any]:
+    with httpx.Client(timeout=coerce_timeout(15.0)) as client:
+        resp = client.get(TOKENINFO_URL, params={"access_token": access_token})
+        resp.raise_for_status()
+        return resp.json()
+
+
+def tokeninfo_error(exc: Exception) -> Dict[str, Any]:
+    """Classify a tokeninfo failure without echoing the request URL or token."""
+    if isinstance(exc, httpx.HTTPStatusError):
+        status = exc.response.status_code
+        code = TOKENINFO_ERROR_INVALID if status in (400, 401) else TOKENINFO_ERROR_HTTP
+        return {"error": code, "http_status": status}
+    return {"error": TOKENINFO_ERROR_UNAVAILABLE}
+
+
+def inspect_access_token(access_token: str) -> Tuple[Optional[str], Dict[str, Any]]:
+    """Return (scope_string, tokeninfo) or (None, sanitized_error_dict) on failure."""
+    try:
+        info = fetch_tokeninfo(access_token)
+    except (httpx.HTTPError, ValueError) as e:
+        return None, tokeninfo_error(e)
+    if not isinstance(info, dict):
+        return None, {"error": TOKENINFO_ERROR_UNAVAILABLE}
+    return scope_string(info), info
+
+
+def connection_capabilities(scope: str) -> Dict[str, bool]:
+    return {
+        "supports_freebusy": supports_freebusy(scope),
+        "supports_events": supports_events(scope),
+    }

booking_agent/circuit_breaker.py

@@ -0,0 +1,116 @@
+"""Per-host circuit breaker so a failing merchant or registry is not hammered."""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Optional, Union
+
+import httpx
+
+from . import settings
+from booking_agent.observability import emit_event
+
+
+class CircuitOpenError(RuntimeError):
+    """Raised when the circuit for a host is open and the cooldown has not elapsed."""
+
+    def __init__(self, host: str, retry_after: float) -> None:
+        super().__init__(
+            f"circuit open for {host}; retry after {retry_after:.0f}s"
+        )
+        self.host = host
+        self.retry_after = retry_after
+
+
+def _host_key(url: Union[str, httpx.URL]) -> str:
+    parsed = httpx.URL(url) if isinstance(url, str) else url
+    host = parsed.host or ""
+    return host.lower()
+
+
+@dataclass
+class _Bucket:
+    failures: int = 0
+    opened_at: Optional[float] = None
+    half_open_emitted: bool = False
+
+
+class HostCircuitBreaker:
+    """Counts consecutive failures per host and sheds load once the threshold trips.
+
+    A success closes the circuit. After ``cooldown_seconds`` an open circuit
+    becomes half-open: the next call is allowed through; another failure reopens
+    it immediately.
+    """
+
+    def __init__(
+        self,
+        *,
+        failure_threshold: int = 5,
+        cooldown_seconds: float = 30.0,
+        disabled: bool = False,
+    ) -> None:
+        self.failure_threshold = max(1, failure_threshold)
+        self.cooldown_seconds = max(0.0, cooldown_seconds)
+        self.disabled = disabled
+        self._buckets: dict[str, _Bucket] = {}
+
+    @classmethod
+    def from_env(cls) -> "HostCircuitBreaker":
+        return cls(
+            failure_threshold=settings.get_int("BOOKING_AGENT_CIRCUIT_FAILURE_THRESHOLD"),
+            cooldown_seconds=settings.get_float("BOOKING_AGENT_CIRCUIT_COOLDOWN_SECONDS"),
+            disabled=settings.get_bool("BOOKING_AGENT_CIRCUIT_DISABLED"),
+        )
+
+    def guard(self, url: Union[str, httpx.URL]) -> None:
+        if self.disabled:
+            return
+        host = _host_key(url)
+        bucket = self._buckets.get(host)
+        if bucket is None or bucket.opened_at is None:
+            return
+        elapsed = time.monotonic() - bucket.opened_at
+        if elapsed >= self.cooldown_seconds:
+            if not bucket.half_open_emitted:
+                bucket.half_open_emitted = True
+                emit_event("circuit_half_open", host=host)
+            return
+        raise CircuitOpenError(host, retry_after=self.cooldown_seconds - elapsed)
+
+    def record_failure(self, url: Union[str, httpx.URL]) -> None:
+        if self.disabled:
+            return
+        host = _host_key(url)
+        bucket = self._buckets.setdefault(host, _Bucket())
+        bucket.failures += 1
+        if bucket.failures >= self.failure_threshold:
+            if bucket.opened_at is None:
+                bucket.opened_at = time.monotonic()
+                bucket.half_open_emitted = False
+                emit_event("circuit_open", host=host)
+            elif bucket.half_open_emitted:
+                bucket.opened_at = time.monotonic()
+                bucket.half_open_emitted = False
+                emit_event("circuit_open", host=host)
+
+    def record_success(self, url: Union[str, httpx.URL]) -> None:
+        if self.disabled:
+            return
+        host = _host_key(url)
+        self._buckets[host] = _Bucket()
+
+
+_default: Optional[HostCircuitBreaker] = None
+
+
+def default_breaker() -> HostCircuitBreaker:
+    global _default
+    if _default is None:
+        _default = HostCircuitBreaker.from_env()
+    return _default
+
+
+def reset_default_breaker() -> None:
+    global _default
+    _default = None

booking_agent/config.py

@@ -0,0 +1,51 @@
+"""booking-agent configuration (USP env subset).
+
+Reads settings (process environment, then the shipped defaults) and exposes them
+as a small Config object.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from . import settings
+from .platform_profile import platform_profile_url
+
+
+@dataclass
+class Config:
+    """Resolved USP configuration."""
+
+    usp_agent_profile_url: str = ""
+    usp_platform_name: Optional[str] = None
+    usp_platform_contact: Optional[str] = None
+    usp_registry_url: Optional[str] = None
+    # Enforcement posture for the USP Section 10.1.6 privileged-operation floor:
+    # required | preferred.  None means "use the default".
+    usp_auth_scoped_credential: Optional[str] = None
+
+    google_calendar_client_id: str = ""
+    google_calendar_client_secret: str = ""
+    google_calendar_redirect_port: int = 8098
+
+
+def _optional_strip(value: Optional[str]) -> Optional[str]:
+    if value is None:
+        return None
+    stripped = value.strip()
+    return stripped or None
+
+
+def load_config() -> Config:
+    """Build a Config from the process environment and the shipped defaults."""
+    get = settings.get
+    return Config(
+        usp_agent_profile_url=platform_profile_url(),
+        usp_platform_name=get("USP_PLATFORM_NAME"),
+        usp_platform_contact=get("USP_PLATFORM_CONTACT"),
+        usp_registry_url=get("USP_REGISTRY_URL"),
+        usp_auth_scoped_credential=_optional_strip(get("BOOKING_AGENT_USP_AUTH_SCOPED_CREDENTIAL")),
+        google_calendar_client_id=get("GOOGLE_CALENDAR_CLIENT_ID") or "",
+        google_calendar_client_secret=get("GOOGLE_CALENDAR_CLIENT_SECRET") or "",
+        google_calendar_redirect_port=settings.get_int("GOOGLE_CALENDAR_REDIRECT_PORT"),
+    )

booking_agent/defaults.env

@@ -0,0 +1,50 @@
+# Shipped defaults for booking-agent. Do not edit this copy.
+# Override a value in the process environment or ~/.booking-agent/.env.
+# `booking-agent config show` prints each effective value and its source.
+# A `# NAME=` line has no default.
+
+# --- Platform identity ---------------------------------------------------------
+# Fetched by businesses from the USP-Agent and UCP-Agent headers.
+USP_AGENT_PROFILE_URL=https://profile.booking-agent.dev/platform-profile.json
+USP_REGISTRY_URL=https://www.wixapis.com/_api/usp-registry/registry/search_services
+USP_PLATFORM_NAME=USP Agent
+USP_PLATFORM_CONTACT=support@booking-agent.dev
+
+# --- Install -------------------------------------------------------------------
+# Sessions, tokens, and traces. Holds the user .env, so override it only in the
+# process environment.
+BOOKING_AGENT_SESSION_DIR=~/.booking-agent
+BOOKING_AGENT_MAX_SESSIONS=30
+LINK_CLI_BIN=link-cli
+
+# --- Authorization -------------------------------------------------------------
+# Booking-scoped credential floor: required or preferred.
+BOOKING_AGENT_USP_AUTH_SCOPED_CREDENTIAL=required
+
+# --- HTTP (seconds unless named otherwise) -------------------------------------
+BOOKING_AGENT_HTTP_TIMEOUT=15
+BOOKING_AGENT_HTTP_CONNECT_TIMEOUT=5
+BOOKING_AGENT_HTTP_MAX_RETRIES=4
+BOOKING_AGENT_HTTP_BACKOFF_BASE=1.0
+BOOKING_AGENT_HTTP_BACKOFF_MAX=300.0
+BOOKING_AGENT_CIRCUIT_FAILURE_THRESHOLD=5
+BOOKING_AGENT_CIRCUIT_COOLDOWN_SECONDS=30
+BOOKING_AGENT_CIRCUIT_DISABLED=0
+# Minimum gap between requests to one business host.
+BOOKING_AGENT_MERCHANT_REQUEST_DELAY_MS=200
+BOOKING_AGENT_MERCHANT_HOST_CONCURRENCY=3
+BOOKING_AGENT_DISCOVERY_CONCURRENCY=8
+BOOKING_AGENT_PROFILE_CACHE_TTL_SECONDS=900
+# 1 writes a redacted request log to <session dir>/http_trace.log.
+BOOKING_AGENT_HTTP_TRACE=0
+
+# --- Address -------------------------------------------------------------------
+BOOKING_AGENT_GEOCODER_URL=https://nominatim.openstreetmap.org/search
+
+# --- Google Calendar -----------------------------------------------------------
+# The operator's OAuth app, needed only for a local calendar sign-in.
+# GOOGLE_CALENDAR_CLIENT_ID=
+# GOOGLE_CALENDAR_CLIENT_SECRET=
+GOOGLE_CALENDAR_REDIRECT_PORT=8098
+# A folder under the session dir, or an absolute path.
+GOOGLE_CALENDAR_TOKEN_CACHE_DIR=.google-calendar-tokens