@ao_zorin/zocket 1.0.0

package/zocket/mcp_server.py

@@ -0,0 +1,249 @@
+from typing import Literal
+
+from mcp.server.fastmcp import FastMCP
+
+from .audit import AuditLogger
+from .config_store import ConfigStore
+from .paths import config_path
+from .runner import ExecPolicyError, run_with_env_limited
+from .vault import ProjectNotFoundError, SecretNotFoundError, ValidationError, VaultService
+
+MCPMode = Literal["metadata", "admin"]
+
+MCP_INSTRUCTIONS = (
+    "Zocket MCP provides project metadata and a safe command runner. "
+    "Secret values are never returned. To use secrets, call run_with_project_env "
+    "and pass command arguments with $VAR or ${VAR} placeholders. "
+    "Those placeholders are substituted from the project environment before execution. "
+    "Do not try to print or exfiltrate secrets."
+)
+
+
+def _public_project_metadata(rows: list[dict]) -> list[dict]:
+    return [
+        {
+            "project": row.get("project"),
+            "folder_path": row.get("folder_path"),
+            "secret_count": row.get("secret_count"),
+            "updated_at": row.get("updated_at"),
+        }
+        for row in rows
+    ]
+
+
+def _public_key_metadata(rows: list[dict]) -> list[dict]:
+    return [
+        {
+            "key": row.get("key"),
+            "has_value": row.get("has_value"),
+            "updated_at": row.get("updated_at"),
+        }
+        for row in rows
+    ]
+
+
+def create_server(
+    vault: VaultService,
+    mode: MCPMode = "metadata",
+    audit: AuditLogger | None = None,
+    host: str = "127.0.0.1",
+    port: int = 18002,
+) -> FastMCP:
+    mcp = FastMCP(name="zocket", host=host, port=port, instructions=MCP_INSTRUCTIONS)
+
+    def _exec_policy() -> tuple[list[str], bool, int, bool, bool]:
+        cfg = ConfigStore(config_path()).load()
+        allowlist = cfg.get("exec_allowlist") or []
+        return_output = bool(cfg.get("exec_return_output", False))
+        allow_full_output = bool(cfg.get("exec_allow_full_output", False))
+        substitute_env = bool(cfg.get("exec_substitute_env", True))
+        try:
+            max_output = int(cfg.get("exec_max_output_chars", 0))
+        except (TypeError, ValueError):
+            max_output = 0
+        if not return_output:
+            max_output = 0
+        return allowlist, return_output, max_output, allow_full_output, substitute_env
+
+    @mcp.tool(
+        description=(
+            "List all known projects from local zocket vault. "
+            "Secret values are never returned."
+        )
+    )
+    def list_projects() -> list:
+        if audit:
+            audit.log("mcp.list_projects", "ok", "mcp")
+        return _public_project_metadata(vault.list_projects())
+
+    @mcp.tool(
+        description=(
+            "List secret keys for a project without returning secret values."
+        )
+    )
+    def list_project_keys(project: str) -> list:
+        if audit:
+            audit.log("mcp.list_project_keys", "ok", "mcp", {"project": project})
+        return _public_key_metadata(
+            vault.list_project_secrets(project, include_values=False)
+        )
+
+    @mcp.tool(
+        description=(
+            "Find a project by local filesystem path. "
+            "Returns best match by longest folder prefix."
+        )
+    )
+    def find_project_by_path(path: str) -> dict:
+        match = vault.find_project_by_path(path)
+        if audit:
+            audit.log(
+                "mcp.find_project_by_path",
+                "ok",
+                "mcp",
+                {"path": path, "matched": bool(match)},
+            )
+        if not match:
+            return {"status": "not_found"}
+        return {
+            "status": "ok",
+            "project": match.get("project"),
+            "folder_path": match.get("folder_path"),
+            "secret_count": match.get("secret_count"),
+            "updated_at": match.get("updated_at"),
+        }
+
+    if mode == "admin":
+        @mcp.tool(
+            description=(
+                "Create or update a secret for project. "
+                "Use env-like key names, e.g. SSH_HOST / SSH_PASSWORD."
+            )
+        )
+        def upsert_secret(
+            project: str, key: str, value: str, description: str = ""
+        ) -> dict:
+            vault.upsert_secret(project=project, key=key, value=value, description=description)
+            if audit:
+                audit.log("mcp.upsert_secret", "ok", "mcp", {"project": project, "key": key})
+            return {"status": "ok", "message": f"Saved {key} in project {project}"}
+
+        @mcp.tool(description="Delete a secret key from project.")
+        def delete_secret(project: str, key: str) -> dict:
+            vault.delete_secret(project=project, key=key)
+            if audit:
+                audit.log("mcp.delete_secret", "ok", "mcp", {"project": project, "key": key})
+            return {"status": "ok", "message": f"Deleted {key} from project {project}"}
+
+        @mcp.tool(description="Delete project and all its secrets.")
+        def delete_project(project: str) -> dict:
+            vault.delete_project(project=project)
+            if audit:
+                audit.log("mcp.delete_project", "ok", "mcp", {"project": project})
+            return {"status": "ok", "message": f"Deleted project {project}"}
+
+        @mcp.tool(
+            description=(
+                "Run local command with project secrets injected into process ENV. "
+                "Secret values are not returned and output is redacted."
+            )
+        )
+        def run_with_project_env(project: str, command: list, full_output: bool = False) -> dict:
+            if not isinstance(command, list) or not command:
+                return {"status": "error", "error": "Command must be a non-empty list."}
+            env = vault.get_project_env(project)
+            allowlist, return_output, max_output, allow_full_output, substitute_env = _exec_policy()
+            if full_output and not allow_full_output:
+                return {"status": "denied", "error": "Full output is not allowed."}
+            output_limit = None if full_output else (max_output if return_output else 0)
+            try:
+                result = run_with_env_limited(
+                    command=command,
+                    project_env=env,
+                    allowlist=allowlist,
+                    max_output_chars=output_limit,
+                    substitute_env=substitute_env,
+                )
+            except ExecPolicyError as exc:
+                if audit:
+                    audit.log(
+                        "mcp.run_with_project_env",
+                        "denied",
+                        "mcp",
+                        {"project": project, "reason": str(exc)},
+                    )
+                return {"status": "denied", "error": str(exc)}
+            if audit:
+                audit.log(
+                    "mcp.run_with_project_env",
+                    "ok",
+                    "mcp",
+                    {"project": project, "exit_code": result.exit_code},
+                )
+            payload = {"status": "ok", "exit_code": result.exit_code}
+            if full_output or return_output:
+                payload["stdout"] = result.stdout
+                payload["stderr"] = result.stderr
+            return payload
+
+        @mcp.tool(
+            description=(
+                "Describe execution policy for run_with_project_env, including "
+                "allowed commands, output limits, and whether ${VAR} substitution is enabled."
+            )
+        )
+        def get_exec_policy() -> dict:
+            allowlist, return_output, max_output, allow_full_output, substitute_env = _exec_policy()
+            return {
+                "status": "ok",
+                "allowlist": allowlist,
+                "return_output": return_output,
+                "max_output_chars": max_output,
+                "allow_full_output": allow_full_output,
+                "substitute_env": substitute_env,
+            }
+
+        @mcp.tool(
+            description=(
+                "Create an empty project. This is optional, because upsert_secret "
+                "creates project automatically."
+            )
+        )
+        def create_project(
+            project: str, description: str = "", folder_path: str = ""
+        ) -> dict:
+            vault.create_project(
+                project=project,
+                description=description,
+                folder_path=folder_path,
+            )
+            if audit:
+                audit.log("mcp.create_project", "ok", "mcp", {"project": project})
+            return {"status": "ok", "message": f"Project created: {project}"}
+
+    @mcp.tool(
+        description=(
+            "Health check for zocket MCP server. Use this to verify server is alive."
+        )
+    )
+    def ping() -> dict:
+        if audit:
+            audit.log("mcp.ping", "ok", "mcp", {"mode": mode})
+        return {"status": "ok", "name": "zocket", "mode": mode}
+
+    return mcp
+
+
+def run_server(
+    vault: VaultService,
+    transport: Literal["stdio", "sse", "streamable-http"] = "stdio",
+    mode: MCPMode = "metadata",
+    audit: AuditLogger | None = None,
+    host: str = "127.0.0.1",
+    port: int = 18002,
+) -> None:
+    server = create_server(vault, mode=mode, audit=audit, host=host, port=port)
+    try:
+        server.run(transport=transport)
+    except (ValidationError, ProjectNotFoundError, SecretNotFoundError) as exc:
+        raise RuntimeError(str(exc)) from exc

package/zocket/paths.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def zocket_home() -> Path:
+    default = Path.home() / ".zocket"
+    return Path(os.environ.get("ZOCKET_HOME", str(default))).expanduser()
+
+
+def vault_path() -> Path:
+    default = zocket_home() / "vault.enc"
+    return Path(os.environ.get("ZOCKET_VAULT_PATH", str(default))).expanduser()
+
+
+def key_path() -> Path:
+    default = zocket_home() / "master.key"
+    return Path(os.environ.get("ZOCKET_KEY_PATH", str(default))).expanduser()
+
+
+def lock_path() -> Path:
+    default = zocket_home() / "vault.lock"
+    return Path(os.environ.get("ZOCKET_LOCK_PATH", str(default))).expanduser()
+
+
+def config_path() -> Path:
+    default = zocket_home() / "config.json"
+    return Path(os.environ.get("ZOCKET_CONFIG_PATH", str(default))).expanduser()
+
+
+def audit_log_path() -> Path:
+    default = zocket_home() / "audit.log"
+    return Path(os.environ.get("ZOCKET_AUDIT_LOG_PATH", str(default))).expanduser()
+
+
+def backups_dir() -> Path:
+    default = zocket_home() / "backups"
+    return Path(os.environ.get("ZOCKET_BACKUPS_DIR", str(default))).expanduser()
+
+
+def ensure_dirs() -> None:
+    home = zocket_home()
+    home.mkdir(parents=True, exist_ok=True)
+    vault_path().parent.mkdir(parents=True, exist_ok=True)
+    key_path().parent.mkdir(parents=True, exist_ok=True)
+    lock_path().parent.mkdir(parents=True, exist_ok=True)
+    config_path().parent.mkdir(parents=True, exist_ok=True)
+    audit_log_path().parent.mkdir(parents=True, exist_ok=True)
+    backups_dir().mkdir(parents=True, exist_ok=True)

package/zocket/runner.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from dataclasses import dataclass
+from typing import Sequence
+
+
+def redact_text(text: str, secrets: Sequence[str]) -> str:
+    redacted = text
+    # Replace longest secrets first to avoid partial leaking.
+    for secret in sorted(set(secrets), key=len, reverse=True):
+        if secret:
+            redacted = redacted.replace(secret, "***REDACTED***")
+    return redacted
+
+
+@dataclass
+class RunResult:
+    exit_code: int
+    stdout: str
+    stderr: str
+
+
+class ExecPolicyError(RuntimeError):
+    pass
+
+
+_ENV_PATTERN = re.compile(r"\$(\w+)|\$\{([^}]+)\}")
+
+
+def _substitute_env_vars(args: Sequence[str], env: dict[str, str]) -> list[str]:
+    resolved: list[str] = []
+    for arg in args:
+        def _replace(match: re.Match[str]) -> str:
+            key = match.group(1) or match.group(2) or ""
+            return env.get(key, match.group(0))
+        resolved.append(_ENV_PATTERN.sub(_replace, arg))
+    return resolved
+
+
+def _enforce_allowlist(command: Sequence[str], allowlist: Sequence[str]) -> None:
+    if not command:
+        raise ExecPolicyError("Command is required.")
+    base = os.path.basename(command[0])
+    if base == "sudo":
+        raise ExecPolicyError("sudo is not allowed.")
+    if allowlist and base not in set(allowlist):
+        raise ExecPolicyError(f"Command '{base}' is not allowed by policy.")
+
+
+def run_with_env(command: Sequence[str], project_env: dict[str, str]) -> RunResult:
+    if not command:
+        raise ValueError("Command is required.")
+
+    env = os.environ.copy()
+    env.update(project_env)
+    completed = subprocess.run(
+        list(command),
+        env=env,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    secrets = list(project_env.values())
+    return RunResult(
+        exit_code=completed.returncode,
+        stdout=redact_text(completed.stdout, secrets),
+        stderr=redact_text(completed.stderr, secrets),
+    )
+
+
+def run_with_env_limited(
+    *,
+    command: Sequence[str],
+    project_env: dict[str, str],
+    allowlist: Sequence[str] | None = None,
+    max_output_chars: int | None = 0,
+    substitute_env: bool = True,
+) -> RunResult:
+    if not command:
+        raise ValueError("Command is required.")
+    allowlist = list(allowlist or [])
+    _enforce_allowlist(command, allowlist)
+    env = os.environ.copy()
+    env.update(project_env)
+    resolved = _substitute_env_vars(command, project_env) if substitute_env else list(command)
+    completed = subprocess.run(
+        list(resolved),
+        env=env,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    secrets = list(project_env.values())
+    stdout = redact_text(completed.stdout, secrets)
+    stderr = redact_text(completed.stderr, secrets)
+    if max_output_chars is None:
+        return RunResult(exit_code=completed.returncode, stdout=stdout, stderr=stderr)
+    limit = max(int(max_output_chars), 0)
+    if limit == 0:
+        return RunResult(exit_code=completed.returncode, stdout="", stderr="")
+    return RunResult(
+        exit_code=completed.returncode,
+        stdout=stdout[:limit],
+        stderr=stderr[:limit],
+    )