workspaceguard-cli 0.1.1__py3-none-any.whl

workspaceguard/__init__.py

@@ -0,0 +1,78 @@
+"""
+Programmatic / agent-native entry point.
+
+    from workspaceguard import create_workspace_guard, MockAdapter
+
+    guard = await create_workspace_guard(data_dir="./data", backend=MockAdapter())
+    await guard.add_workspace("alex", "alex@example.com")
+    await guard.set_cap("alex", 1000)
+    report = await guard.usage_report()
+
+Same core isolation/metering logic as the `workspaceguard` CLI;
+workspaceguard/cli.py is a thin argument-parsing wrapper over this class.
+
+This is the Python port of the workspaceguard-cli npm package
+(https://www.npmjs.com/package/workspaceguard-cli, not yet published as of
+this port -- see README for current npm status). See
+https://github.com/RudrenduPaul/workspaceguard for the canonical
+documentation and the original TypeScript source.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from .adapters.mock import MockAdapter
+from .config import DuplicateIdentityError, InvalidWorkspaceIdError
+from .isolation_guard import IsolationGuard, WorkspaceUsageReport
+from .types import (
+    BackendAdapter,
+    BackendCircuitOpenError,
+    BackendUnreachableError,
+    IdentityNotFoundError,
+    VaultDecryptionError,
+    WorkspaceNotFoundError,
+)
+from .usage import QuotaExceededError, WorkspaceUsage
+
+__version__ = "0.1.1"
+
+
+async def create_workspace_guard(
+    data_dir: str,
+    backend: BackendAdapter,
+    circuit_open_cooldown_ms: Optional[int] = None,
+) -> IsolationGuard:
+    """
+    The library entry point -- the "agent-native" surface. An orchestrator
+    process can call this directly instead of shelling out to the CLI. No
+    default backend -- a caller must be explicit about which adapter it
+    wants (the real Odysseus adapter ships once the feasibility spike
+    confirms clean HTTP interception; MockAdapter is exported for tests and
+    local experimentation).
+    """
+    guard = IsolationGuard(
+        data_dir=data_dir,
+        backend=backend,
+        circuit_open_cooldown_ms=circuit_open_cooldown_ms,
+    )
+    await guard.init()
+    return guard
+
+
+__all__ = [
+    "create_workspace_guard",
+    "IsolationGuard",
+    "WorkspaceUsageReport",
+    "BackendAdapter",
+    "MockAdapter",
+    "IdentityNotFoundError",
+    "VaultDecryptionError",
+    "BackendUnreachableError",
+    "BackendCircuitOpenError",
+    "WorkspaceNotFoundError",
+    "DuplicateIdentityError",
+    "InvalidWorkspaceIdError",
+    "QuotaExceededError",
+    "WorkspaceUsage",
+    "__version__",
+]

workspaceguard/adapters/__init__.py

@@ -0,0 +1,3 @@
+from .mock import MockAdapter
+
+__all__ = ["MockAdapter"]

workspaceguard/adapters/mock.py

@@ -0,0 +1,39 @@
+"""
+In-memory mock backend, used for the scaffold-stage isolation tests only.
+Ported from src/adapters/mock.ts. The real Odysseus adapter is blocked on a
+feasibility spike: does Odysseus's HTTP API expose clean interception
+points, or does it read/write some of this directly from disk/DB in a way
+an HTTP-level proxy can't see? See docs/integrations/backends.md.
+"""
+from __future__ import annotations
+
+from typing import Dict, List
+
+from ..types import BackendAdapter
+
+
+class MockAdapter(BackendAdapter):
+    name = "mock"
+
+    def __init__(self) -> None:
+        self._messages_by_workspace: Dict[str, List[str]] = {}
+        self._failures_remaining = 0
+
+    async def health_check(self) -> bool:
+        return True
+
+    async def forward_chat(self, workspace_id: str, message: str) -> str:
+        if self._failures_remaining > 0:
+            self._failures_remaining -= 1
+            raise RuntimeError("simulated backend failure")
+        existing = self._messages_by_workspace.setdefault(workspace_id, [])
+        existing.append(message)
+        return f"echo: {message}"
+
+    def _fail_next_calls(self, n: int) -> None:
+        """Test-only: makes the next N forward_chat calls fail, to exercise the circuit breaker."""
+        self._failures_remaining = n
+
+    def _messages_for(self, workspace_id: str) -> List[str]:
+        """Test-only inspection point -- never exposed through the public adapter interface."""
+        return self._messages_by_workspace.get(workspace_id, [])

workspaceguard/circuit_breaker.py

@@ -0,0 +1,65 @@
+"""
+Fail closed, never pass-through-unisolated -- the worst failure mode here is
+a silent cross-workspace leak, so an unreachable backend must block, not
+bypass, isolation. Ported from src/core/circuit-breaker.ts.
+
+Opens after 3 consecutive failures. Once the cooldown has passed since
+opening, the next call is let through as a half-open probe; success closes
+the circuit, failure keeps it open and restarts the cooldown -- a real
+circuit breaker with a path back to closed, not a one-way trip switch.
+"""
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Awaitable, Callable, TypeVar
+
+from .log import CircuitStateChangeEvent, Logger
+from .types import BackendCircuitOpenError, BackendUnreachableError
+
+T = TypeVar("T")
+
+FAILURE_THRESHOLD = 3
+CONNECT_TIMEOUT_MS = 3000
+DEFAULT_OPEN_COOLDOWN_MS = 10_000
+
+
+class CircuitBreaker:
+    def __init__(self, backend_name: str, logger: Logger, open_cooldown_ms: int = DEFAULT_OPEN_COOLDOWN_MS) -> None:
+        self._backend_name = backend_name
+        self._logger = logger
+        self._open_cooldown_ms = open_cooldown_ms
+        self._consecutive_failures = 0
+        self._open = False
+        self._opened_at = 0.0
+
+    def _probe_allowed(self) -> bool:
+        return self._open and (time.monotonic() * 1000 - self._opened_at) >= self._open_cooldown_ms
+
+    async def call(self, fn: Callable[[], Awaitable[T]]) -> T:
+        if self._open and not self._probe_allowed():
+            raise BackendCircuitOpenError(self._backend_name)
+        try:
+            result = await asyncio.wait_for(fn(), timeout=CONNECT_TIMEOUT_MS / 1000)
+            self._consecutive_failures = 0
+            self.on_health_check_success()
+            return result
+        except Exception:
+            self._consecutive_failures += 1
+            if self._consecutive_failures >= FAILURE_THRESHOLD:
+                self._open_circuit()
+            raise BackendUnreachableError(self._backend_name)
+
+    def _open_circuit(self) -> None:
+        was_open = self._open
+        self._open = True
+        self._opened_at = time.monotonic() * 1000
+        if not was_open:
+            self._logger.log(CircuitStateChangeEvent(backend=self._backend_name, state="open"))
+
+    def on_health_check_success(self) -> None:
+        """A health check success (or a successful half-open probe) closes the circuit again."""
+        if self._open:
+            self._open = False
+            self._consecutive_failures = 0
+            self._logger.log(CircuitStateChangeEvent(backend=self._backend_name, state="closed"))

workspaceguard/cli.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""
+Console entry point: `workspaceguard <command> [args] [--json]`, installed
+via the `workspaceguard` console-script defined in python/pyproject.toml --
+the same command name as the (not-yet-published) npm package's `bin` entry.
+
+Ported from src/cli/index.ts. Commands, flags, human-readable text, and
+--json output shapes are kept identical to the TypeScript CLI so the two
+distributions are drop-in equivalents for anything that shells out to
+either one.
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+from dataclasses import asdict
+from typing import Any, List, Optional, Tuple
+
+from . import create_workspace_guard
+from .adapters.mock import MockAdapter
+
+STARTUP_WARNING = (
+    "WARNING: workspaceguard must never be directly reachable from the network.\n"
+    "It trusts an upstream identity header (e.g. Cf-Access-Authenticated-User-Email)\n"
+    "set by your reverse proxy. If this port is exposed without that proxy in front\n"
+    "of it, anyone can impersonate any workspace. Firewall this port; only your\n"
+    "trusted proxy should be able to reach it."
+)
+
+USAGE = "usage: workspaceguard <init|add-workspace|status|rotate-key|usage|set-cap|scan> [--json]"
+
+
+def _extract_json_flag(args: List[str]) -> Tuple[bool, List[str]]:
+    """Strips a boolean flag out of an argv slice, agent-native mode toggle for every command."""
+    rest = [a for a in args if a != "--json"]
+    return len(rest) != len(args), rest
+
+
+def _print_result(json_mode: bool, data: Any, human_lines: List[str]) -> None:
+    if json_mode:
+        import json as _json
+
+        print(_json.dumps(data))
+        return
+    for line in human_lines:
+        print(line)
+
+
+def _usage_report_to_dict(report: Any) -> dict:
+    d = asdict(report)
+    return {
+        "workspaceId": d["workspace_id"],
+        "identity": d["identity"],
+        "monthlyMessageCap": d["monthly_message_cap"],
+        "percentUsed": d["percent_used"],
+        "period": d["period"],
+        "messageCount": d["message_count"],
+        "estimatedBytes": d["estimated_bytes"],
+    }
+
+
+async def _run(argv: List[str]) -> int:
+    command = argv[1] if len(argv) > 1 else None
+    raw_args = argv[2:]
+    json_mode, args = _extract_json_flag(raw_args)
+    data_dir = os.environ.get("WORKSPACEGUARD_DATA_DIR") or os.getcwd()
+
+    if command == "init":
+        if not json_mode:
+            print(STARTUP_WARNING)
+        guard = await create_workspace_guard(data_dir=data_dir, backend=MockAdapter())
+        workspaces = await guard.status()
+        _print_result(json_mode, {"ok": True, "dataDir": data_dir, "workspaces": workspaces}, [
+            f"workspaceguard initialized in {data_dir}"
+        ])
+        return 0
+
+    if command == "add-workspace":
+        workspace_id: Optional[str] = args[0] if len(args) > 0 else None
+        identity: Optional[str] = args[2] if len(args) > 2 else None  # add-workspace <id> --identity <value>
+        if not workspace_id or not identity:
+            _print_result(
+                json_mode,
+                {"ok": False, "error": "usage: workspaceguard add-workspace <id> --identity <value>"},
+                ["usage: workspaceguard add-workspace <id> --identity <value>"],
+            )
+            return 1
+        guard = await create_workspace_guard(data_dir=data_dir, backend=MockAdapter())
+        await guard.add_workspace(workspace_id, identity)
+        _print_result(json_mode, {"ok": True, "workspaceId": workspace_id, "identity": identity}, [
+            f"workspace {workspace_id} added"
+        ])
+        return 0
+
+    if command == "status":
+        guard = await create_workspace_guard(data_dir=data_dir, backend=MockAdapter())
+        workspaces = await guard.status()
+        if workspaces:
+            lines = [f"-> {w['workspaceId']} [isolated] identity: {w['identity']}" for w in workspaces]
+            lines.append("No cross-workspace leaks detected.")
+        else:
+            lines = ["no workspaces configured"]
+        _print_result(json_mode, {"ok": True, "workspaces": workspaces}, lines)
+        return 0
+
+    if command == "rotate-key":
+        workspace_id = args[0] if len(args) > 0 else None
+        if not workspace_id:
+            _print_result(json_mode, {"ok": False, "error": "usage: workspaceguard rotate-key <id>"}, [
+                "usage: workspaceguard rotate-key <id>"
+            ])
+            return 1
+        guard = await create_workspace_guard(data_dir=data_dir, backend=MockAdapter())
+        await guard.rotate_key(workspace_id)
+        _print_result(json_mode, {"ok": True, "workspaceId": workspace_id}, [f"workspace {workspace_id} key rotated"])
+        return 0
+
+    if command == "usage":
+        guard = await create_workspace_guard(data_dir=data_dir, backend=MockAdapter())
+        report = await guard.usage_report()
+        report_dicts = [_usage_report_to_dict(r) for r in report]
+        if report:
+            lines = []
+            for r in report:
+                cap = str(r.monthly_message_cap) if r.monthly_message_cap is not None else "unlimited"
+                pct = f" ({r.percent_used}%)" if r.percent_used is not None else ""
+                lines.append(
+                    f"-> {r.workspace_id} [{r.identity}]: {r.message_count} messages this period, cap {cap}{pct}"
+                )
+        else:
+            lines = ["no workspaces configured"]
+        _print_result(json_mode, {"ok": True, "usage": report_dicts}, lines)
+        return 0
+
+    if command == "set-cap":
+        workspace_id = args[0] if len(args) > 0 else None
+        cap_arg = args[1] if len(args) > 1 else None
+        if not workspace_id or not cap_arg:
+            _print_result(
+                json_mode,
+                {"ok": False, "error": "usage: workspaceguard set-cap <workspaceId> <count|none>"},
+                ["usage: workspaceguard set-cap <workspaceId> <count|none>"],
+            )
+            return 1
+        cap: Optional[int]
+        if cap_arg == "none":
+            cap = None
+        else:
+            try:
+                cap = int(cap_arg)
+                if cap < 0:
+                    raise ValueError
+            except ValueError:
+                _print_result(json_mode, {"ok": False, "error": f"invalid cap value: {cap_arg}"}, [
+                    f'invalid cap value: {cap_arg} (must be a non-negative integer or "none")'
+                ])
+                return 1
+        guard = await create_workspace_guard(data_dir=data_dir, backend=MockAdapter())
+        await guard.set_cap(workspace_id, cap)
+        _print_result(json_mode, {"ok": True, "workspaceId": workspace_id, "cap": cap}, [
+            f"workspace {workspace_id} cap cleared (unlimited)"
+            if cap is None
+            else f"workspace {workspace_id} cap set to {cap} messages/month"
+        ])
+        return 0
+
+    if command == "scan":
+        _print_result(json_mode, {"ok": True, "findings": []}, [
+            "isolation config scan: no misconfigurations detected (scaffold stub)"
+        ])
+        return 0
+
+    _print_result(json_mode, {"ok": False, "error": USAGE}, [USAGE])
+    return 1
+
+
+def main() -> None:
+    try:
+        code = asyncio.run(_run(sys.argv))
+    except Exception as err:  # noqa: BLE001 -- top-level crash guard, mirrors src/cli/index.ts's catch-all
+        print(str(err), file=sys.stderr)
+        sys.exit(1)
+    sys.exit(code)
+
+
+if __name__ == "__main__":
+    main()

workspaceguard/config.py

@@ -0,0 +1,156 @@
+"""
+Load/save `workspaceguard.config.yaml` and the pure config-mutation helpers
+(add a workspace, set a cap, resolve an identity to a workspace id). Ported
+from src/core/config.ts. YAML keys are camelCase (backend, identityHeader,
+workspaces: [{workspaceId, identity, monthlyMessageCap}]) to stay
+file-compatible with the npm package's own config file.
+"""
+from __future__ import annotations
+
+import os
+import re
+from typing import Optional
+
+import yaml
+
+from .types import WorkspaceEntry, WorkspaceGuardConfig, WorkspaceNotFoundError
+
+DEFAULT_IDENTITY_HEADER = "cf-access-authenticated-user-email"
+
+# workspace_id is used to build filesystem paths (vault, namespace, chat
+# history dirs) -- an allowlist plus a reserved-name denylist closes a
+# path-traversal vector (e.g. "../../etc") before it ever reaches those
+# call sites.
+_WORKSPACE_ID_PATTERN = re.compile(r"^[a-zA-Z0-9_-]+$")
+_RESERVED_WORKSPACE_IDS = {"__proto__", "constructor", "prototype", ".", ".."}
+
+
+class InvalidWorkspaceIdError(Exception):
+    def __init__(self, workspace_id: str) -> None:
+        super().__init__(
+            f'workspace id "{workspace_id}" is invalid: must match {_WORKSPACE_ID_PATTERN.pattern} '
+            "and must not be a reserved name"
+        )
+        self.workspace_id = workspace_id
+
+
+def _assert_valid_workspace_id(workspace_id: str) -> None:
+    if not _WORKSPACE_ID_PATTERN.match(workspace_id) or workspace_id in _RESERVED_WORKSPACE_IDS:
+        raise InvalidWorkspaceIdError(workspace_id)
+
+
+def _normalize_identity(identity: str) -> str:
+    """
+    Identities are compared case/whitespace-insensitively so that
+    "Alex@Example.com " and "alex@example.com" resolve to the same
+    workspace -- without this, the duplicate-identity guard below could be
+    evaded by registering a near-duplicate, producing two workspaces (and
+    two independent quotas) for what is really one real-world identity.
+    The original casing is still stored, only comparisons are normalized.
+    """
+    return identity.strip().lower()
+
+
+def _default_config() -> WorkspaceGuardConfig:
+    return WorkspaceGuardConfig(backend="odysseus", identity_header=DEFAULT_IDENTITY_HEADER, workspaces=[])
+
+
+def load_config(config_path: str) -> WorkspaceGuardConfig:
+    try:
+        with open(config_path, "r", encoding="utf-8") as fh:
+            raw = fh.read()
+        parsed = yaml.safe_load(raw) or {}
+        workspaces = [
+            WorkspaceEntry(
+                workspace_id=w["workspaceId"],
+                identity=w["identity"],
+                monthly_message_cap=w.get("monthlyMessageCap"),
+            )
+            for w in parsed.get("workspaces", [])
+        ]
+        return WorkspaceGuardConfig(
+            backend=parsed.get("backend") or "odysseus",
+            identity_header=parsed.get("identityHeader") or DEFAULT_IDENTITY_HEADER,
+            workspaces=workspaces,
+        )
+    except Exception:
+        return _default_config()
+
+
+def save_config(config_path: str, config: WorkspaceGuardConfig) -> None:
+    os.makedirs(os.path.dirname(config_path), exist_ok=True)
+    payload = {
+        "backend": config.backend,
+        "identityHeader": config.identity_header,
+        "workspaces": [
+            {
+                "workspaceId": w.workspace_id,
+                "identity": w.identity,
+                **({"monthlyMessageCap": w.monthly_message_cap} if w.monthly_message_cap is not None else {}),
+            }
+            for w in config.workspaces
+        ],
+    }
+    with open(config_path, "w", encoding="utf-8") as fh:
+        yaml.safe_dump(payload, fh, sort_keys=False)
+
+
+class DuplicateIdentityError(Exception):
+    def __init__(self, identity: str, existing_workspace_id: str) -> None:
+        super().__init__(f'identity "{identity}" is already assigned to workspace "{existing_workspace_id}"')
+        self.identity = identity
+        self.existing_workspace_id = existing_workspace_id
+
+
+def upsert_workspace(config: WorkspaceGuardConfig, workspace_id: str, identity: str) -> WorkspaceGuardConfig:
+    """
+    add-workspace on an existing id is idempotent -- returns the existing
+    config unchanged, never overwrites. Rejects loudly if the identity is
+    already claimed by a DIFFERENT workspace id: without this check, two
+    workspace ids could silently share one identity, and resolve_workspace_id
+    would deterministically route to whichever was added first, merging two
+    workspaces from the routing layer's perspective without either operator
+    being told.
+    """
+    for w in config.workspaces:
+        if w.workspace_id == workspace_id:
+            return config
+    _assert_valid_workspace_id(workspace_id)
+    normalized = _normalize_identity(identity)
+    for w in config.workspaces:
+        if _normalize_identity(w.identity) == normalized:
+            raise DuplicateIdentityError(identity, w.workspace_id)
+    return WorkspaceGuardConfig(
+        backend=config.backend,
+        identity_header=config.identity_header,
+        workspaces=[*config.workspaces, WorkspaceEntry(workspace_id=workspace_id, identity=identity)],
+    )
+
+
+def set_workspace_cap(
+    config: WorkspaceGuardConfig, workspace_id: str, cap: Optional[int]
+) -> WorkspaceGuardConfig:
+    """
+    Sets (or clears, with cap=None) a workspace's monthly message cap.
+    Rejects loudly on an unknown workspace id rather than silently
+    no-op'ing, matching upsert_workspace's fail-loud-on-ambiguity precedent.
+    """
+    index = next((i for i, w in enumerate(config.workspaces) if w.workspace_id == workspace_id), None)
+    if index is None:
+        raise WorkspaceNotFoundError(workspace_id)
+    workspaces = list(config.workspaces)
+    existing = workspaces[index]
+    workspaces[index] = WorkspaceEntry(
+        workspace_id=existing.workspace_id, identity=existing.identity, monthly_message_cap=cap
+    )
+    return WorkspaceGuardConfig(backend=config.backend, identity_header=config.identity_header, workspaces=workspaces)
+
+
+def resolve_workspace_id(config: WorkspaceGuardConfig, identity_header_value: Optional[str]) -> Optional[str]:
+    if not identity_header_value:
+        return None
+    normalized = _normalize_identity(identity_header_value)
+    for w in config.workspaces:
+        if _normalize_identity(w.identity) == normalized:
+            return w.workspace_id
+    return None