karma-mcp-server 0.1.0__tar.gz

karma_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: karma-mcp-server
+Version: 0.1.0
+Summary: Karma universal Agent MCP server — thin access layer over the Karma backend
+License: AGPL-3.0-only
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp<2,>=1.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+
+# karma-mcp-server
+
+Karma 通用 Agent MCP Server —— **薄接入层**。把已有后端能力接到 MCP，不重写任何业务。
+
+- 设计：[`docs/mcp/karma-mcp-architecture.md`](../../docs/mcp/karma-mcp-architecture.md)
+- 工具契约：[`docs/mcp/karma-mcp-tools.md`](../../docs/mcp/karma-mcp-tools.md)
+- 安全：[`docs/mcp/karma-mcp-security.md`](../../docs/mcp/karma-mcp-security.md)
+
+## 安全红线
+
+- 本进程**只**注入 `KARMA_RUNTIME_KEY`；**禁止**私钥、助记词。启动时会检查并拒绝启动。
+- 远程 HTTP 传输默认关闭（需 `KARMA_MCP_ENABLE_HTTP=1` + `KARMA_MCP_HTTP_TOKEN`；缺一拒绝启动）。
+- Tier-2/3（动钱）默认不注册（`KARMA_MCP_ENABLE_TIER2/3=1` 才开）。
+
+## 环境变量
+
+| 变量 | 必填 | 说明 |
+|---|---|---|
+| `KARMA_RUNTIME_KEY` | 是（配对后） | `KRM_RT_…`；只读 |
+| `KARMA_RUNTIME_URL` | 否 | 默认 `http://localhost:8000` |
+| `KARMA_AGENT_PRIVATE_KEY` | 否 | Agent 签名私钥（base64/hex），留在本机 |
+| `KARMA_AGENT_ID` | 否 | 主人授权的 agent id |
+| `KARMA_AGENT_ENV_PATH` | 否 | 凭据文件路径覆盖（默认 `~/.karma/agent.env`） |
+| `KARMA_MCP_ENABLE_TIER2` | 否 | 开启交易/交付工具（默认关） |
+| `KARMA_MCP_ENABLE_TIER3` | 否 | 开启结算/争议工具（默认关） |
+| `KARMA_MCP_ENABLE_HTTP` | 否 | 开启 Streamable HTTP（默认关） |
+| `KARMA_MCP_HTTP_TOKEN` | 远程必填 | 远程 HTTP 的静态 bearer token；缺了拒绝启动 |
+| `KARMA_MCP_STATE_DIR` | 否 | 配对状态目录（含配对码），默认 `~/.karma/pairings` |
+| `KARMA_MCP_ISSUER_URL` / `KARMA_MCP_RESOURCE_URL` | 否 | 远程鉴权 issuer / resource，默认取 `host:port` |
+
+## 安装
+
+```bash
+# 在仓库根目录：
+pip install ./packages/karma-mcp-server
+
+# 没 clone 过仓库（公开仓库，一行装）：
+pip install "karma-mcp-server @ git+https://github.com/AtoB101/Karma@main#subdirectory=packages/karma-mcp-server"
+```
+
+PyPI 上**还没有**这个包（`pip install karma-mcp-server` 会 404）。装 / 接线 / 自检 /
+发包的完整口径：[`docs/mcp/karma-mcp-integration.md`](../../docs/mcp/karma-mcp-integration.md)。
+
+## 运行
+
+```bash
+pip install -e ".[dev]"
+karma-mcp-server                                    # stdio（本地 Agent，默认）
+
+KARMA_MCP_ENABLE_HTTP=1 KARMA_MCP_HTTP_TOKEN=... \
+  karma-mcp-server --transport streamable-http --host 0.0.0.0 --port 8765
+```
+
+远程启动有三道红线：进程里出现私钥 / 未设 `KARMA_MCP_ENABLE_HTTP=1` / 没配
+`KARMA_MCP_HTTP_TOKEN` —— 任一条不满足都**拒绝启动**。
+
+## 测试
+
+```bash
+python -m pytest -q -c pyproject.toml
+```
+
+## 当前状态（第二阶段 S2–S5 已落地）
+
+已实现并有测试（`packages/karma-mcp-server/tests`，56 例全绿）：
+
+- **S2 薄层**：配置 / 凭据（只读）/ Agent Ed25519 逐请求签名（与服务端逐字对齐）/
+  后端客户端（错误分类 + `client_nonce`）/ 凭据 0600 落盘 / stdio 入口。
+- **S3 配对与身份**：`karma_connect` → `karma_connect_status` → `karma_connect_claim`
+  （配对码只落本机文件，凭据只回指纹）；身份核验、授权状态、策略、交易 / 结算 / 信誉查询。
+- **S3 授权读写**：`karma_request_authorization`（预览，不写后端）→
+  `karma_submit_authorization`（主人钱包签名后铸造）→ `karma_update_authorization`
+  （铸新 + 撤旧）→ `karma_revoke_authorization`（一键停用）。
+- **S4 远程入口**：`--transport streamable-http` + 静态 bearer token（常量时间比较）。
+- **S5 交易工具**：Tier-2/3 已实现，**默认不注册**，按 Tier 白名单 fail-closed。
+
+| Tier | 默认 | 开启方式 | 内容 |
+|---|---|---|---|
+| T0 只读 | 开 | — | 连接 / 身份 / 授权状态 / 策略 / 交易 / 结算 / 信誉 / 凭证查询 |
+| T1 授权 | 开 | — | 授权预览 / 提交（需主人钱包签名）/ 更新 / 撤销 |
+| T2 交易 | 关 | `KARMA_MCP_ENABLE_TIER2=1` | 下单 / 收款码 / 确认裁决 / 证据 / 回执 / 进度 / 结算请求 |
+| T3 资金 | 关 | `KARMA_MCP_ENABLE_TIER3=1` | 凭证校验 / 争议 / 退款 |
+
+未做（S6 及以后）：跨平台适配器（Telegram / 微信等）、完整 OAuth 2.1 授权服务器接入。

karma_mcp_server-0.1.0/README.md

@@ -0,0 +1,84 @@
+# karma-mcp-server
+
+Karma 通用 Agent MCP Server —— **薄接入层**。把已有后端能力接到 MCP，不重写任何业务。
+
+- 设计：[`docs/mcp/karma-mcp-architecture.md`](../../docs/mcp/karma-mcp-architecture.md)
+- 工具契约：[`docs/mcp/karma-mcp-tools.md`](../../docs/mcp/karma-mcp-tools.md)
+- 安全：[`docs/mcp/karma-mcp-security.md`](../../docs/mcp/karma-mcp-security.md)
+
+## 安全红线
+
+- 本进程**只**注入 `KARMA_RUNTIME_KEY`；**禁止**私钥、助记词。启动时会检查并拒绝启动。
+- 远程 HTTP 传输默认关闭（需 `KARMA_MCP_ENABLE_HTTP=1` + `KARMA_MCP_HTTP_TOKEN`；缺一拒绝启动）。
+- Tier-2/3（动钱）默认不注册（`KARMA_MCP_ENABLE_TIER2/3=1` 才开）。
+
+## 环境变量
+
+| 变量 | 必填 | 说明 |
+|---|---|---|
+| `KARMA_RUNTIME_KEY` | 是（配对后） | `KRM_RT_…`；只读 |
+| `KARMA_RUNTIME_URL` | 否 | 默认 `http://localhost:8000` |
+| `KARMA_AGENT_PRIVATE_KEY` | 否 | Agent 签名私钥（base64/hex），留在本机 |
+| `KARMA_AGENT_ID` | 否 | 主人授权的 agent id |
+| `KARMA_AGENT_ENV_PATH` | 否 | 凭据文件路径覆盖（默认 `~/.karma/agent.env`） |
+| `KARMA_MCP_ENABLE_TIER2` | 否 | 开启交易/交付工具（默认关） |
+| `KARMA_MCP_ENABLE_TIER3` | 否 | 开启结算/争议工具（默认关） |
+| `KARMA_MCP_ENABLE_HTTP` | 否 | 开启 Streamable HTTP（默认关） |
+| `KARMA_MCP_HTTP_TOKEN` | 远程必填 | 远程 HTTP 的静态 bearer token；缺了拒绝启动 |
+| `KARMA_MCP_STATE_DIR` | 否 | 配对状态目录（含配对码），默认 `~/.karma/pairings` |
+| `KARMA_MCP_ISSUER_URL` / `KARMA_MCP_RESOURCE_URL` | 否 | 远程鉴权 issuer / resource，默认取 `host:port` |
+
+## 安装
+
+```bash
+# 在仓库根目录：
+pip install ./packages/karma-mcp-server
+
+# 没 clone 过仓库（公开仓库，一行装）：
+pip install "karma-mcp-server @ git+https://github.com/AtoB101/Karma@main#subdirectory=packages/karma-mcp-server"
+```
+
+PyPI 上**还没有**这个包（`pip install karma-mcp-server` 会 404）。装 / 接线 / 自检 /
+发包的完整口径：[`docs/mcp/karma-mcp-integration.md`](../../docs/mcp/karma-mcp-integration.md)。
+
+## 运行
+
+```bash
+pip install -e ".[dev]"
+karma-mcp-server                                    # stdio（本地 Agent，默认）
+
+KARMA_MCP_ENABLE_HTTP=1 KARMA_MCP_HTTP_TOKEN=... \
+  karma-mcp-server --transport streamable-http --host 0.0.0.0 --port 8765
+```
+
+远程启动有三道红线：进程里出现私钥 / 未设 `KARMA_MCP_ENABLE_HTTP=1` / 没配
+`KARMA_MCP_HTTP_TOKEN` —— 任一条不满足都**拒绝启动**。
+
+## 测试
+
+```bash
+python -m pytest -q -c pyproject.toml
+```
+
+## 当前状态（第二阶段 S2–S5 已落地）
+
+已实现并有测试（`packages/karma-mcp-server/tests`，56 例全绿）：
+
+- **S2 薄层**：配置 / 凭据（只读）/ Agent Ed25519 逐请求签名（与服务端逐字对齐）/
+  后端客户端（错误分类 + `client_nonce`）/ 凭据 0600 落盘 / stdio 入口。
+- **S3 配对与身份**：`karma_connect` → `karma_connect_status` → `karma_connect_claim`
+  （配对码只落本机文件，凭据只回指纹）；身份核验、授权状态、策略、交易 / 结算 / 信誉查询。
+- **S3 授权读写**：`karma_request_authorization`（预览，不写后端）→
+  `karma_submit_authorization`（主人钱包签名后铸造）→ `karma_update_authorization`
+  （铸新 + 撤旧）→ `karma_revoke_authorization`（一键停用）。
+- **S4 远程入口**：`--transport streamable-http` + 静态 bearer token（常量时间比较）。
+- **S5 交易工具**：Tier-2/3 已实现，**默认不注册**，按 Tier 白名单 fail-closed。
+
+| Tier | 默认 | 开启方式 | 内容 |
+|---|---|---|---|
+| T0 只读 | 开 | — | 连接 / 身份 / 授权状态 / 策略 / 交易 / 结算 / 信誉 / 凭证查询 |
+| T1 授权 | 开 | — | 授权预览 / 提交（需主人钱包签名）/ 更新 / 撤销 |
+| T2 交易 | 关 | `KARMA_MCP_ENABLE_TIER2=1` | 下单 / 收款码 / 确认裁决 / 证据 / 回执 / 进度 / 结算请求 |
+| T3 资金 | 关 | `KARMA_MCP_ENABLE_TIER3=1` | 凭证校验 / 争议 / 退款 |
+
+未做（S6 及以后）：跨平台适配器（Telegram / 微信等）、完整 OAuth 2.1 授权服务器接入。

karma_mcp_server-0.1.0/karma_mcp_server/__init__.py

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

karma_mcp_server-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-0.1.0/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-0.1.0/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)