karma-mcp-server 0.1.0__py3-none-any.whl

karma_mcp_server/__init__.py

@@ -0,0 +1,7 @@
+"""Karma 通用 Agent MCP Server —— 薄接入层。
+
+只做「翻译 + 转发 + 校验」；身份、授权、风控、状态机、结算判定全部在后端。
+本包永不持有私钥、助记词或钱包凭证。
+"""
+
+__version__ = "0.1.0"

karma_mcp_server/__main__.py

@@ -0,0 +1,82 @@
+"""入口：stdio（默认）或 Streamable HTTP（默认关闭，需显式开启 + 鉴权令牌）。
+
+安全第一：
+* 启动前拒绝「私钥被注入本进程」这种配置（红线 R1）。
+* 远程 HTTP 没有配置鉴权令牌时**拒绝启动**，不会裸奔。
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from karma_mcp_server.config import load_config
+from karma_mcp_server.credentials import check_forbidden_env
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="karma-mcp-server")
+    parser.add_argument(
+        "--transport",
+        choices=("stdio", "streamable-http"),
+        default="stdio",
+        help="stdio（本地 Agent，默认）或 streamable-http（远程，需 KARMA_MCP_ENABLE_HTTP=1）",
+    )
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8765)
+    args = parser.parse_args(argv)
+
+    forbidden = check_forbidden_env()
+    if forbidden:
+        print(
+            "refusing to start: this MCP process must not hold private key material. "
+            "remove these env vars: " + ", ".join(forbidden),
+            file=sys.stderr,
+        )
+        return 2
+
+    config = load_config()
+
+    token_verifier = None
+    auth_settings = None
+    if args.transport == "streamable-http":
+        if not config.enable_http:
+            print(
+                "refusing to start: remote HTTP transport is disabled "
+                "(set KARMA_MCP_ENABLE_HTTP=1 once remote auth is configured).",
+                file=sys.stderr,
+            )
+            return 3
+        from karma_mcp_server.http_auth import (
+            StaticTokenVerifier,
+            build_auth_settings,
+            configured_token,
+        )
+
+        token = configured_token()
+        if not token:
+            print(
+                "refusing to start: remote HTTP requires KARMA_MCP_HTTP_TOKEN "
+                "(no anonymous remote access).",
+                file=sys.stderr,
+            )
+            return 4
+        token_verifier = StaticTokenVerifier(token)
+        auth_settings = build_auth_settings(default_host=args.host, default_port=args.port)
+
+    from karma_mcp_server.server import build_server
+
+    mcp = build_server(config, token_verifier=token_verifier, auth_settings=auth_settings)
+
+    if args.transport == "streamable-http":
+        mcp.settings.host = args.host
+        mcp.settings.port = args.port
+        mcp.run(transport="streamable-http")
+        return 0
+
+    mcp.run(transport="stdio")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

karma_mcp_server/agent_signing.py

@@ -0,0 +1,185 @@
+"""Agent 侧 Runtime Key 请求签名。
+
+与 ``services/runtime_wallet.build_agent_request_message``（服务端）**逐字对齐**。
+两边由测试钉死，格式不得漂移。
+
+私钥只在本进程内存里使用，永不外露、永不进日志。
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+_NEWLINE = chr(10)
+
+
+def runtime_key_id(token: str) -> str:
+    """从 ``KRM_RT_<key_id>_<secret>`` 取出 key_id（签名消息需要它）。"""
+    raw = (token or "").strip()
+    if not raw.startswith("KRM_RT_"):
+        return ""
+    head, _, _ = raw[len("KRM_RT_") :].partition("_")
+    return head
+
+
+def agent_key_from_seed(seed: str) -> Any:
+    """base64(32 raw bytes) 或 64 位 hex → Ed25519PrivateKey。"""
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+    text = (seed or "").strip()
+    if not text:
+        raise ValueError("agent private key is empty")
+    if len(text) == 64 and all(c in "0123456789abcdefABCDEF" for c in text):
+        raw = bytes.fromhex(text)
+    else:
+        raw = base64.b64decode(text, validate=True)
+    if len(raw) != 32:
+        raise ValueError("agent private key must be 32 raw bytes (base64 or hex seed)")
+    return Ed25519PrivateKey.from_private_bytes(raw)
+
+
+def agent_public_key_b64(key: Any) -> str:
+    from cryptography.hazmat.primitives import serialization
+
+    raw = key.public_key().public_bytes(serialization.Encoding.Raw, serialization.PublicFormat.Raw)
+    return base64.b64encode(raw).decode()
+
+
+def canonical_public_key_b64(public_key: str) -> str:
+    """收敛成 canonical base64(raw 32 bytes)；不是 32 字节裸公钥就返回空串。
+
+    fingerprint 必须先把 base64 / hex 两种写法收敛成同一个值，否则同一把钥匙
+    在两处会显示成两串不同的 hex，主人核对就失去意义。
+    """
+    text = (public_key or "").strip()
+    if not text:
+        return ""
+    compact = "".join(text.split())
+    if compact[:2].lower() == "0x":
+        compact = compact[2:]
+    try:
+        if len(compact) == 64 and all(c in "0123456789abcdefABCDEF" for c in compact):
+            raw = bytes.fromhex(compact)
+        else:
+            raw = base64.b64decode(compact, validate=True)
+    except Exception:  # noqa: BLE001 - 形状不对就当没有指纹
+        return ""
+    if len(raw) != 32:
+        return ""
+    return base64.b64encode(raw).decode()
+
+
+def agent_public_key_fingerprint(public_key_b64: str, *, length: int = 16) -> str:
+    """与后端 ``runtime_key_service.agent_binding_fingerprint`` 同口径（sha256 前 16 位）。
+
+    口径：先收敛成 canonical base64(raw 32 bytes)，再对**那串 base64 文本**取
+    sha256。配对卡片、key 列表、agent 自报三处必须是同一串 hex —— 差一个编码
+    方式，主人核对的就是两串对不上的数。
+    """
+    canonical = canonical_public_key_b64(public_key_b64)
+    if not canonical:
+        return ""
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()[:length]
+
+
+def build_agent_request_message(
+    *, key_id: str, method: str, path: str, timestamp: str, nonce: str, body_sha256: str
+) -> str:
+    """服务端重算的那段文字。**不要**改动行序。"""
+    return _NEWLINE.join(
+        [
+            "Karma Runtime Request",
+            "key_id:" + key_id,
+            "method:" + method.upper(),
+            "path:" + path,
+            "timestamp:" + timestamp,
+            "nonce:" + nonce,
+            "body_sha256:" + body_sha256,
+        ]
+    )
+
+
+def sign_runtime_request(
+    *, key: Any, key_id: str, method: str, path: str, body: bytes
+) -> dict[str, str]:
+    """已绑公钥的 key 每个请求必须带上的三个头。"""
+    timestamp = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+    nonce = uuid.uuid4().hex
+    message = build_agent_request_message(
+        key_id=key_id,
+        method=method,
+        path=path,
+        timestamp=timestamp,
+        nonce=nonce,
+        body_sha256=hashlib.sha256(body or b"").hexdigest(),
+    )
+    signature = base64.b64encode(key.sign(message.encode("utf-8"))).decode()
+    return {
+        "X-Karma-Agent-Signature": signature,
+        "X-Karma-Runtime-Timestamp": timestamp,
+        "X-Karma-Runtime-Nonce": nonce,
+    }
+
+
+def build_agent_pairing_request_message(
+    *, agent_name: str, public_key: str, nonce: str, timestamp: str
+) -> str:
+    """与 ``services/runtime_wallet.build_agent_pairing_request_message`` 逐字对齐。"""
+    return _NEWLINE.join(
+        [
+            "Karma Agent Pairing Request",
+            "agent_name:" + agent_name,
+            "public_key:" + public_key,
+            "nonce:" + nonce,
+            "timestamp:" + timestamp,
+        ]
+    )
+
+
+def sign_pairing_request(*, key: Any, agent_name: str, public_key: str) -> dict[str, str]:
+    """申请接入要带的三件套：签名 + nonce + 时间戳。
+
+    公钥从此不再是「申报」：服务端用这段签名证明申请方真的持有那把私钥。
+    """
+    timestamp = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+    nonce = uuid.uuid4().hex
+    message = build_agent_pairing_request_message(
+        agent_name=agent_name, public_key=public_key, nonce=nonce, timestamp=timestamp
+    )
+    return {
+        "signature": base64.b64encode(key.sign(message.encode("utf-8"))).decode(),
+        "nonce": nonce,
+        "timestamp": timestamp,
+    }
+
+
+def ensure_local_agent_key() -> Any | None:
+    """本机 agent 私钥：有就用，没有就现生成一把并落盘（0600）。
+
+    这把私钥是「光有钥匙字符串花不了钱」的全部依据，它必须只存在于 agent 本机 ——
+    Karma 服务端从头到尾看不到它，只收到公钥，用来把 Runtime Key 钉在这次的 agent 身上。
+    """
+    from karma_mcp_server.credentials import credential
+
+    seed = credential("KARMA_AGENT_PRIVATE_KEY")
+    if seed:
+        try:
+            return agent_key_from_seed(seed)
+        except Exception:  # noqa: BLE001, S110 - 种子坏了就当没有，重新生成会把旧的覆盖掉
+            pass
+    try:
+        from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+        from karma_mcp_server.credential_store import upsert_credential
+
+        key = Ed25519PrivateKey.generate()
+        upsert_credential(
+            "KARMA_AGENT_PRIVATE_KEY", base64.b64encode(key.private_bytes_raw()).decode()
+        )
+        return key
+    except Exception:  # noqa: BLE001 - 落不了盘就当没有，退回「领取时再绑」那条老路
+        return None

karma_mcp_server/backend_client.py

@@ -0,0 +1,228 @@
+"""L4 后端客户端 —— 唯一允许出网的地方。
+
+职责：注入 ``X-Karma-Runtime-Key`` + 逐请求 Agent 签名；传 ``client_nonce`` /
+``Idempotency-Key``；把 HTTP 结果归类成 ``KarmaToolError``。
+
+**不做**：不代签钱包交易、不持有私钥、不做额度/风控/状态机判定。
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+
+from karma_mcp_server.agent_signing import (
+    agent_key_from_seed,
+    agent_public_key_b64,
+    agent_public_key_fingerprint,
+    runtime_key_id,
+    sign_runtime_request,
+)
+from karma_mcp_server.config import McpConfig
+from karma_mcp_server.credentials import credential
+from karma_mcp_server.errors import ErrorClass, KarmaToolError, classify_http_status
+from karma_mcp_server.redact import fingerprint
+
+_SIGNATURE_REQUIRED_MARKER = "X-Karma-Agent-Signature"
+
+
+def _encode(body: Any) -> bytes:
+    if body is None:
+        return b""
+    return json.dumps(body, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+class KarmaBackend:
+    """对 Karma 后端的薄封装。一个实例 = 一个进程的凭据视图。"""
+
+    def __init__(
+        self,
+        config: McpConfig,
+        *,
+        runtime_key: str | None = None,
+        api_key: str | None = None,
+        agent_private_key_seed: str | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+        credential_fn=credential,
+    ) -> None:
+        self._config = config
+        self._credential = credential_fn
+        self._transport = transport
+        self._explicit_runtime_key = runtime_key
+        self._explicit_api_key = api_key
+        self._explicit_seed = agent_private_key_seed
+        self._signing_mode: bool | None = None
+
+    # ---- 凭据（只读） --------------------------------------------------
+    def runtime_key(self) -> str:
+        if self._explicit_runtime_key is not None:
+            return self._explicit_runtime_key.strip()
+        return self._credential("KARMA_RUNTIME_KEY")
+
+    def has_runtime_key(self) -> bool:
+        return bool(self.runtime_key())
+
+    def api_key(self) -> str:
+        """公共 API（``/v1/*``）用的 key。配对前为空是正常的。"""
+        if self._explicit_api_key is not None:
+            return self._explicit_api_key.strip()
+        return self._credential("KARMA_API_KEY")
+
+    def key_fingerprint(self) -> str:
+        return fingerprint(self.runtime_key())
+
+    def agent_key_fingerprint(self) -> str:
+        """本机 agent 公钥的 16 位 hex 指纹；没有钥匙就返回空串。
+
+        铸 Runtime Key 时把「这把钱钥匙给哪把 agent 公钥」钉进主人的钱包签名
+        消息（``agent_public_key_fingerprint`` 行）。读不到本机钥匙就不填 —— 回到
+        「签名不约束绑定公钥」的老行为，绝不因此多放行任何权限。
+        """
+        key = self._agent_key()
+        if key is None:
+            return ""
+        return agent_public_key_fingerprint(agent_public_key_b64(key))
+
+    def _agent_key(self):
+        seed = (
+            self._explicit_seed
+            if self._explicit_seed is not None
+            else self._credential("KARMA_AGENT_PRIVATE_KEY")
+        )
+        if not seed:
+            return None
+        try:
+            return agent_key_from_seed(seed)
+        except Exception:  # noqa: BLE001 - 种子坏了就当没有，走「不签名」这条老路
+            return None
+
+    # ---- 出网 ----------------------------------------------------------
+    def _headers(
+        self, *, method: str, path: str, body: bytes, runtime: bool = True
+    ) -> dict[str, str]:
+        h = {"Content-Type": "application/json", "Accept": "application/json"}
+        ak = self.api_key()
+        if ak and not runtime:
+            h["X-Karma-Api-Key"] = ak
+        rk = self.runtime_key()
+        # 只有要钱、要额度的 /runtime/* 才必须带钥匙；引导期的公开接口
+        # （pairing request / claim 等 runtime=False）在还没拿到钥匙时也得能发出去，
+        # 否则一台全新的机器永远开不了第一次配对，自助接入的第一步就死在这里。
+        # 带了钥匙依旧照发：怎么验是服务端的事，客户端不替它放行。
+        if not rk and runtime:
+            raise KarmaToolError(
+                ErrorClass.UNAUTHORIZED,
+                "no Runtime Key configured for this MCP server",
+            )
+        if rk:
+            h["X-Karma-Runtime-Key"] = rk
+        key = self._agent_key()
+        if key is not None and self._signing_mode is True:
+            h.update(
+                sign_runtime_request(
+                    key=key, key_id=runtime_key_id(rk), method=method, path=path, body=body
+                )
+            )
+        return h
+
+    @staticmethod
+    def _detail(resp: httpx.Response) -> str:
+        try:
+            payload = resp.json()
+        except Exception:  # noqa: BLE001
+            return (resp.text or "")[:300]
+        if isinstance(payload, dict) and payload.get("detail"):
+            return str(payload["detail"])[:300]
+        return (resp.text or "")[:300]
+
+    def _client(self) -> httpx.AsyncClient:
+        return httpx.AsyncClient(
+            timeout=httpx.Timeout(self._config.write_timeout_seconds),
+            transport=self._transport,
+        )
+
+    async def _probe_signing_mode(self, client: httpx.AsyncClient) -> bool:
+        """探一次这把钥匙要不要签名（读路径，不落调用记录）。"""
+        if not self.has_runtime_key():
+            self._signing_mode = False
+            return False
+        if self._agent_key() is None:
+            self._signing_mode = False
+            return False
+        url = self._config.runtime_base_url + "/runtime/permissions"
+        headers = {"Content-Type": "application/json", "X-Karma-Runtime-Key": self.runtime_key()}
+        try:
+            resp = await client.get(url, headers=headers)
+        except httpx.HTTPError:
+            self._signing_mode = False
+            return False
+        self._signing_mode = bool(
+            resp.status_code == 401 and _SIGNATURE_REQUIRED_MARKER in self._detail(resp)
+        )
+        return self._signing_mode
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        runtime: bool = True,
+        extra_headers: dict[str, str] | None = None,
+    ) -> Any:
+        payload = _encode(body)
+        url = self._config.runtime_base_url + path
+        async with self._client() as client:
+            if runtime and self._signing_mode is None:
+                await self._probe_signing_mode(client)
+            headers = self._headers(method=method, path=path, body=payload, runtime=runtime)
+            if extra_headers:
+                headers = {**headers, **extra_headers}
+            try:
+                resp = await client.request(method, url, headers=headers, content=payload or None)
+            except httpx.TimeoutException as exc:
+                raise KarmaToolError(ErrorClass.TRANSPORT, f"request to {path} timed out") from exc
+            except httpx.HTTPError as exc:
+                raise KarmaToolError(
+                    ErrorClass.TRANSPORT, f"cannot reach Karma backend at {path}"
+                ) from exc
+
+            # 主人刚在操作台输完配对码：这一刻服务端开始要求签名，补签重发一次。
+            if (
+                resp.status_code == 401
+                and self._agent_key() is not None
+                and self._signing_mode is not True
+                and _SIGNATURE_REQUIRED_MARKER in self._detail(resp)
+            ):
+                self._signing_mode = True
+                headers = self._headers(method=method, path=path, body=payload, runtime=runtime)
+                if extra_headers:
+                    headers = {**headers, **extra_headers}
+                resp = await client.request(method, url, headers=headers, content=payload or None)
+
+            if resp.is_error:
+                detail = self._detail(resp)
+                raise KarmaToolError(
+                    classify_http_status(resp.status_code, detail),
+                    detail or f"backend returned {resp.status_code}",
+                    http_status=resp.status_code,
+                )
+            if not resp.content:
+                return {}
+            return resp.json()
+
+    # ---- 便捷方法 ------------------------------------------------------
+    async def runtime_get(self, path: str) -> Any:
+        return await self.request("GET", path, runtime=True)
+
+    async def runtime_post(
+        self, path: str, body: Any, *, extra_headers: dict[str, str] | None = None
+    ) -> Any:
+        return await self.request(
+            "POST", path, body=body, runtime=True, extra_headers=extra_headers
+        )
+
+    async def api_get(self, path: str) -> Any:
+        return await self.request("GET", path, runtime=False)

karma_mcp_server/config.py

@@ -0,0 +1,52 @@
+"""MCP Server 配置。
+
+**只读** ``KARMA_RUNTIME_KEY`` 等凭据；Tier-2/Tier-3（动钱）默认**关闭**（fail-closed）。
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from karma_mcp_server.credentials import credential
+
+DEFAULT_RUNTIME_URL = "http://localhost:8000"
+
+
+def _truthy(value: str | None) -> bool:
+    return (value or "").strip().lower() in ("1", "true", "yes", "on")
+
+
+@dataclass(frozen=True)
+class McpConfig:
+    runtime_base_url: str = DEFAULT_RUNTIME_URL
+    read_timeout_seconds: float = 30.0
+    write_timeout_seconds: float = 120.0
+    #: Tier-2（交易/交付）与 Tier-3（结算/争议）默认关闭。
+    enable_tier2: bool = False
+    enable_tier3: bool = False
+    #: 远程 Streamable HTTP 默认关闭 —— 远程鉴权方案未定前不得开放。
+    enable_http: bool = False
+
+    def allowed_tiers(self) -> frozenset[int]:
+        tiers = {0, 1}
+        if self.enable_tier2:
+            tiers.add(2)
+        if self.enable_tier3:
+            tiers.add(3)
+        return frozenset(tiers)
+
+
+def load_config(
+    env: dict[str, str] | None = None, *, file_values: dict[str, str] | None = None
+) -> McpConfig:
+    source = os.environ if env is None else env
+    base = (
+        credential("KARMA_RUNTIME_URL", env=source, file_values=file_values) or DEFAULT_RUNTIME_URL
+    )
+    return McpConfig(
+        runtime_base_url=base.rstrip("/"),
+        enable_tier2=_truthy(source.get("KARMA_MCP_ENABLE_TIER2")),
+        enable_tier3=_truthy(source.get("KARMA_MCP_ENABLE_TIER3")),
+        enable_http=_truthy(source.get("KARMA_MCP_ENABLE_HTTP")),
+    )

karma_mcp_server/credential_store.py

@@ -0,0 +1,71 @@
+"""凭据**写入**（配对流程专用）。
+
+与 ``credentials.py``（只读）分开：读的路径要尽可能简单、无副作用；写的路径只有
+``karma_connect_claim`` 会走，并且必须 0600 + 原子落盘。
+
+凭据文件**永不回显** —— 返回给调用方的只有指纹。
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from karma_mcp_server.credentials import agent_env_path
+
+
+def state_dir() -> Path:
+    """配对状态目录（含 pairing_code，属于秘密）。"""
+    override = os.environ.get("KARMA_MCP_STATE_DIR", "").strip()
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".karma" / "pairings"
+
+
+def _write_secret(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(text, encoding="utf-8")
+    try:
+        os.chmod(tmp, 0o600)
+    except OSError:
+        pass
+    os.replace(tmp, path)
+
+
+def upsert_credential(name: str, value: str) -> Path:
+    """把一对键值并进凭据文件（0600），同名行就地替换。"""
+    path = agent_env_path()
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        lines = []
+    prefix = name + "="
+    out: list[str] = []
+    replaced = False
+    for line in lines:
+        if line.strip().startswith(prefix):
+            if not replaced:
+                out.append(prefix + value)
+                replaced = True
+            continue
+        out.append(line)
+    if not replaced:
+        out.append(prefix + value)
+    _write_secret(path, "\n".join(out).rstrip("\n") + "\n")
+    return path
+
+
+def write_env_file(text: str) -> Path:
+    """整份重写凭据文件（领取凭据时用）。"""
+    path = agent_env_path()
+    _write_secret(path, text)
+    return path
+
+
+def write_pairing_state(user_code: str, payload_json: str) -> Path:
+    """配对状态（含 pairing_code）落到本机 0600 文件，聊天里不出现。"""
+    safe = "".join(ch for ch in (user_code or "pairing") if ch.isalnum() or ch in "-_") or "pairing"
+    path = state_dir() / (safe.upper() + ".json")
+    _write_secret(path, payload_json)
+    return path