agentremote-common 1.0.0__py3-none-any.whl

agentremote_common/crypto/integrity.py

@@ -0,0 +1,129 @@
+"""
+SHA256 文件完整性校验
+
+用于:
+  - Skill 包文件完整性验证（安装/加载前校验）
+  - Robot 文件防篡改检测（运行时校验）
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+
+def hash_content(content: bytes | str) -> str:
+    """计算内容的 SHA256 hex digest"""
+    if isinstance(content, str):
+        content = content.encode("utf-8")
+    return hashlib.sha256(content).hexdigest()
+
+
+def hash_file(file_path: str | Path) -> str:
+    """计算文件的 SHA256 hex digest"""
+    return hash_content(Path(file_path).read_bytes())
+
+
+def hash_skill_directory(skill_dir: str | Path, exclude_self_yaml: bool = True) -> Dict[str, str]:
+    """
+    计算 Skill 目录下所有文件的 SHA256。
+
+    递归扫描，排除 __pycache__、.git、*.pyc。
+
+    Args:
+        skill_dir: Skill 目录路径
+        exclude_self_yaml: 是否排除 skill.yaml（签名场景需要排除自身）
+
+    Returns:
+        {relative_path: sha256_hex}
+    """
+    skill_dir = Path(skill_dir).resolve()
+    hashes: Dict[str, str] = {}
+
+    for fpath in sorted(skill_dir.rglob("*")):
+        if not fpath.is_file():
+            continue
+        # 跳过无关文件
+        parts = set(fpath.parts)
+        if "__pycache__" in parts or ".git" in parts:
+            continue
+        if fpath.suffix == ".pyc":
+            continue
+        # 跳过签名文件自身
+        if fpath.name.startswith("."):
+            continue
+        # 跳过 skill.yaml 自身（避免鸡生蛋问题：签名写入会改变哈希）
+        if exclude_self_yaml and fpath.name == "skill.yaml":
+            continue
+        # 跳过 Robot Framework 运行产物（每次执行都会变化）
+        if fpath.name in ("log.html", "output.xml", "report.html", "@AutomationLog.txt"):
+            continue
+
+        rel = str(fpath.relative_to(skill_dir)).replace("\\", "/")
+        hashes[rel] = hash_file(fpath)
+
+    return hashes
+
+
+def verify_skill_integrity(
+    skill_dir: str | Path,
+    expected_hashes: Dict[str, str],
+    strict: bool = True,
+) -> Tuple[bool, List[str]]:
+    """
+    验证 Skill 目录完整性。
+
+    Args:
+        skill_dir: Skill 目录路径
+        expected_hashes: {文件路径: sha256} 期望的哈希表
+        strict: True=拒绝未知文件（启动时校验）, False=只检查已知文件（执行时校验）
+
+    Returns:
+        (passed, [错误信息列表])
+    """
+    errors: List[str] = []
+    actual = hash_skill_directory(skill_dir)
+
+    # 检查期望文件是否存在且哈希一致
+    for rel_path, expected_hash in expected_hashes.items():
+        fpath = Path(skill_dir) / rel_path
+        if not fpath.exists():
+            errors.append(f"[MISSING] {rel_path}: 文件不存在或被删除")
+            continue
+
+        actual_hash = actual.get(rel_path, "")
+        if actual_hash != expected_hash:
+            errors.append(
+                f"[TAMPERED] {rel_path}: 哈希不匹配  "
+                f"期望 {expected_hash[:16]}...  实际 {actual_hash[:16]}..."
+            )
+
+    # 检查是否有多余文件（仅 strict 模式）
+    if strict:
+        for rel_path in actual:
+            if rel_path not in expected_hashes:
+                errors.append(f"[EXTRA] {rel_path}: 未在签名清单中的文件")
+
+    return len(errors) == 0, errors
+
+
+def compute_manifest_hash(skill_dir: str | Path, exclude_signature: bool = True) -> str:
+    """
+    计算 Skill 目录的内容哈希（用于签名）。
+
+    将所有文件按路径排序，拼接 SHA256 后再做一次 SHA256，
+    得到该目录的"内容指纹"。
+
+    Args:
+        skill_dir: Skill 目录
+        exclude_signature: 是否排除 _security 相关字段
+
+    Returns:
+        内容指纹的 hex digest
+    """
+    hashes = hash_skill_directory(skill_dir)
+    # 按路径排序拼接
+    combined = "".join(f"{k}:{v}" for k, v in sorted(hashes.items()))
+    return hash_content(combined)

agentremote_common/crypto/jwt_auth.py

@@ -0,0 +1,108 @@
+"""
+JWT 认证 — Plugin → Middleware 身份认证
+
+Plugin 用设备私钥签 JWT（ES256），Middleware 用设备公钥验证。
+
+JWT Payload:
+  {
+    "sub": "sh_win_01",          # 设备 ID
+    "tenant": "acme_shanghai",   # 租户
+    "iat": 1719323500,           # 签发时间
+    "exp": 1719327100,           # 过期时间（1h）
+    "jti": "random_nonce"        # 防重放
+  }
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any, Dict, Optional
+
+import jwt  # PyJWT
+from cryptography.hazmat.primitives.asymmetric import ec
+
+
+# Token 有效期（Demo: 1 小时）
+TOKEN_TTL_SEC = 3600
+
+# JWT 算法
+ALGORITHM = "ES256"
+
+
+def create_auth_token(
+    device_private_key: ec.EllipticCurvePrivateKey,
+    device_id: str,
+    tenant_id: str,
+    ttl_sec: int = TOKEN_TTL_SEC,
+    extra_claims: Optional[Dict[str, Any]] = None,
+) -> str:
+    """
+    创建设备认证 JWT。
+
+    Args:
+        device_private_key: 设备 ECDSA 私钥（P-256）
+        device_id: 设备标识 (对应 node_id)
+        tenant_id: 租户标识
+        ttl_sec: 有效期（秒）
+        extra_claims: 额外的 JWT claims
+
+    Returns:
+        JWT 字符串
+    """
+    now = int(time.time())
+    payload = {
+        "sub": device_id,
+        "tenant": tenant_id,
+        "iat": now,
+        "exp": now + ttl_sec,
+        "jti": uuid.uuid4().hex[:16],
+    }
+    if extra_claims:
+        payload.update(extra_claims)
+
+    return jwt.encode(payload, device_private_key, algorithm=ALGORITHM)
+
+
+def verify_auth_token(
+    token: str,
+    device_public_key: ec.EllipticCurvePublicKey,
+    expected_device_id: Optional[str] = None,
+    expected_tenant: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    验证设备认证 JWT。
+
+    Args:
+        token: JWT 字符串
+        device_public_key: 设备 ECDSA 公钥（P-256）
+        expected_device_id: 期望的设备 ID（可选，不传则跳过）
+        expected_tenant: 期望的租户（可选，不传则跳过）
+
+    Returns:
+        解码后的 JWT payload
+
+    Raises:
+        jwt.ExpiredSignatureError: Token 已过期
+        jwt.InvalidSignatureError: 签名无效
+        jwt.InvalidTokenError: Token 无效
+        ValueError: sub/tenant 不匹配
+    """
+    payload = jwt.decode(
+        token,
+        device_public_key,
+        algorithms=[ALGORITHM],
+        options={"require": ["sub", "tenant", "iat", "exp", "jti"]},
+    )
+
+    if expected_device_id and payload.get("sub") != expected_device_id:
+        raise ValueError(
+            f"JWT sub mismatch: expected '{expected_device_id}', got '{payload.get('sub')}'"
+        )
+
+    if expected_tenant and payload.get("tenant") != expected_tenant:
+        raise ValueError(
+            f"JWT tenant mismatch: expected '{expected_tenant}', got '{payload.get('tenant')}'"
+        )
+
+    return payload

agentremote_common/crypto/keys.py

@@ -0,0 +1,128 @@
+"""
+ECDSA P-256 密钥管理 — 生成密钥对、签名、验签
+
+用于:
+  - 开发者签名 Skill 包（私钥签名，Plugin 用公钥验证）
+  - 设备密钥（Plugin 用私钥签 JWT，Middleware 用公钥验证）
+"""
+
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+from typing import Tuple
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.asymmetric.utils import (
+    decode_dss_signature,
+    encode_dss_signature,
+)
+from cryptography.exceptions import InvalidSignature
+
+
+# ═══════════════════════════════════════════
+# 密钥生成
+# ═══════════════════════════════════════════
+
+def generate_keypair() -> Tuple[ec.EllipticCurvePrivateKey, ec.EllipticCurvePublicKey]:
+    """生成 ECDSA P-256 密钥对"""
+    private = ec.generate_private_key(ec.SECP256R1())
+    return private, private.public_key()
+
+
+# ═══════════════════════════════════════════
+# PEM 序列化
+# ═══════════════════════════════════════════
+
+def private_to_pem(private_key: ec.EllipticCurvePrivateKey, password: bytes | None = None) -> bytes:
+    """私钥 → PEM 字节"""
+    enc = serialization.BestAvailableEncryption(password) if password else serialization.NoEncryption()
+    return private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=enc,
+    )
+
+
+def public_to_pem(public_key: ec.EllipticCurvePublicKey) -> bytes:
+    """公钥 → PEM 字节"""
+    return public_key.public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+
+
+def load_private_key(pem_data: bytes, password: bytes | None = None) -> ec.EllipticCurvePrivateKey:
+    """从 PEM 字节加载私钥"""
+    key = serialization.load_pem_private_key(pem_data, password=password)
+    if not isinstance(key, ec.EllipticCurvePrivateKey):
+        raise TypeError(f"Expected EC private key, got {type(key)}")
+    return key
+
+
+def load_public_key(pem_data: bytes) -> ec.EllipticCurvePublicKey:
+    """从 PEM 字节加载公钥"""
+    key = serialization.load_pem_public_key(pem_data)
+    if not isinstance(key, ec.EllipticCurvePublicKey):
+        raise TypeError(f"Expected EC public key, got {type(key)}")
+    return key
+
+
+def load_private_key_file(path: str | Path) -> ec.EllipticCurvePrivateKey:
+    """从文件加载私钥"""
+    return load_private_key(Path(path).read_bytes())
+
+
+def load_public_key_file(path: str | Path) -> ec.EllipticCurvePublicKey:
+    """从文件加载公钥"""
+    return load_public_key(Path(path).read_bytes())
+
+
+# ═══════════════════════════════════════════
+# 签名 / 验签
+# ═══════════════════════════════════════════
+
+def sign_data(private_key: ec.EllipticCurvePrivateKey, data: bytes) -> str:
+    """
+    用 ECDSA P-256 + SHA256 签名数据。
+
+    Returns:
+        Base64 编码的签名（DER 格式）
+    """
+    der_sig = private_key.sign(data, ec.ECDSA(hashes.SHA256()))
+    return base64.b64encode(der_sig).decode("ascii")
+
+
+def verify_signature(public_key: ec.EllipticCurvePublicKey, data: bytes, signature_b64: str) -> bool:
+    """
+    验证 ECDSA P-256 + SHA256 签名。
+
+    Args:
+        public_key: 签名者的公钥
+        data: 原始数据
+        signature_b64: Base64 编码的签名（DER 格式）
+
+    Returns:
+        True 如果签名有效
+    """
+    try:
+        der_sig = base64.b64decode(signature_b64)
+        public_key.verify(der_sig, data, ec.ECDSA(hashes.SHA256()))
+        return True
+    except (InvalidSignature, Exception):
+        return False
+
+
+def sign_json(private_key: ec.EllipticCurvePrivateKey, data: dict) -> str:
+    """对 JSON 可序列化的 dict 签名（先排序 key 再序列化）"""
+    import json
+    canonical = json.dumps(data, sort_keys=True, ensure_ascii=False).encode("utf-8")
+    return sign_data(private_key, canonical)
+
+
+def verify_json(public_key: ec.EllipticCurvePublicKey, data: dict, signature_b64: str) -> bool:
+    """验证对 JSON dict 的签名"""
+    import json
+    canonical = json.dumps(data, sort_keys=True, ensure_ascii=False).encode("utf-8")
+    return verify_signature(public_key, canonical, signature_b64)

agentremote_common/crypto/license.py

@@ -0,0 +1,157 @@
+"""
+AES-256-GCM 许可证加密/解密 — capability-first.
+
+许可证文件包含:
+  {
+    "tenant_id": "acme_shanghai",
+    "capability_id": "desktop.cua",
+    "status": "active",
+    "max_tasks": 0,
+    "task_count": 0,
+    "issued_at": "2026-06-25T00:00:00",
+    "expires_at": "2026-12-25T00:00:00",
+    "node_ids": ["sh_win_01"]
+  }
+
+加密: AES-256-GCM, 随机 IV (12 bytes), 认证标签 (16 bytes)
+格式: base64(iv + ciphertext + tag)
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+
+# ═══════════════════════════════════════════
+# 数据模型
+# ═══════════════════════════════════════════
+
+@dataclass
+class LicenseData:
+    """许可证数据 — capability-first."""
+    tenant_id: str
+    capability_id: str                            # ★ 替代 skill_name
+    status: str = "active"
+    max_tasks: int = 0
+    task_count: int = 0
+    issued_at: str = ""
+    expires_at: str = ""
+    node_ids: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "tenant_id": self.tenant_id,
+            "capability_id": self.capability_id,
+            "status": self.status,
+            "max_tasks": self.max_tasks,
+            "task_count": self.task_count,
+            "issued_at": self.issued_at,
+            "expires_at": self.expires_at,
+            "node_ids": self.node_ids,
+            "version": 2,
+        }
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "LicenseData":
+        # Support both old (skill_name) and new (capability_id) format
+        cap_id = d.get("capability_id", d.get("skill_name", ""))
+        return cls(
+            tenant_id=d["tenant_id"],
+            capability_id=cap_id,
+            status=d.get("status", "active"),
+            max_tasks=d.get("max_tasks", 0),
+            task_count=d.get("task_count", 0),
+            issued_at=d.get("issued_at", ""),
+            expires_at=d.get("expires_at", ""),
+            node_ids=d.get("node_ids", []),
+        )
+
+    def is_expired(self) -> bool:
+        if not self.expires_at:
+            return False
+        try:
+            exp = datetime.fromisoformat(self.expires_at)
+            return datetime.utcnow() > exp
+        except ValueError:
+            return False
+
+    def is_valid_for_node(self, node_id: str) -> bool:
+        if not self.node_ids:
+            return True
+        return node_id in self.node_ids
+
+    def can_execute(self) -> bool:
+        if self.status == "expired":
+            return False
+        if self.is_expired():
+            return False
+        if self.status == "trial" and self.max_tasks > 0 and self.task_count >= self.max_tasks:
+            return False
+        return True
+
+
+# ═══════════════════════════════════════════
+# 密钥管理
+# ═══════════════════════════════════════════
+
+def generate_license_key() -> bytes:
+    return AESGCM.generate_key(bit_length=256)
+
+
+def load_license_key(path: str | Path) -> bytes:
+    return Path(path).read_bytes()
+
+
+def save_license_key(path: str | Path, key: bytes) -> None:
+    Path(path).write_bytes(key)
+    try:
+        os.chmod(path, 0o600)
+    except Exception:
+        pass
+
+
+# ═══════════════════════════════════════════
+# 加密 / 解密
+# ═══════════════════════════════════════════
+
+def encrypt_license(license_data: LicenseData, key: bytes) -> str:
+    aesgcm = AESGCM(key)
+    plaintext = json.dumps(license_data.to_dict(), ensure_ascii=False).encode("utf-8")
+    nonce = os.urandom(12)
+    ciphertext = aesgcm.encrypt(nonce, plaintext, None)
+    return base64.b64encode(nonce + ciphertext).decode("ascii")
+
+
+def decrypt_license(encrypted: str, key: bytes) -> LicenseData:
+    aesgcm = AESGCM(key)
+    raw = base64.b64decode(encrypted)
+    nonce = raw[:12]
+    ciphertext = raw[12:]
+    try:
+        plaintext = aesgcm.decrypt(nonce, ciphertext, None)
+    except Exception as e:
+        raise ValueError(f"License decryption failed: {e}") from e
+    data = json.loads(plaintext.decode("utf-8"))
+    return LicenseData.from_dict(data)
+
+
+# ═══════════════════════════════════════════
+# 文件操作
+# ═══════════════════════════════════════════
+
+def encrypt_license_file(license_data: LicenseData, key: bytes, output_path: str | Path) -> None:
+    encrypted = encrypt_license(license_data, key)
+    Path(output_path).write_text(encrypted, encoding="ascii")
+
+
+def decrypt_license_file(file_path: str | Path, key: bytes) -> LicenseData:
+    encrypted = Path(file_path).read_text(encoding="ascii").strip()
+    return decrypt_license(encrypted, key)

agentremote_common/models/__init__.py

@@ -0,0 +1,34 @@
+"""AgentRemote data models — re-exported by domain."""
+
+from .capability import CapabilityManifest, FlowManifest
+from .license import GatewayCheckResult, License, LicenseInfo, LicenseStatus
+from .node import BackendStatus, Node, NodeStatus, RuntimeBackend
+from .task import RunnerType, Task, TaskResult, TaskStatus
+
+# 向后兼容 — 协议模型原在 models.py，现从 protocol 子包重导出
+from ..protocol.message import MqttConfig, WSMessage, WSMessageType
+
+__all__ = [
+    # task
+    "RunnerType",
+    "TaskStatus",
+    "Task",
+    "TaskResult",
+    # capability
+    "CapabilityManifest",
+    "FlowManifest",
+    # node
+    "BackendStatus",
+    "NodeStatus",
+    "RuntimeBackend",
+    "Node",
+    # license
+    "LicenseStatus",
+    "LicenseInfo",
+    "License",
+    "GatewayCheckResult",
+    # protocol (backward compat — 原在 models.py)
+    "MqttConfig",
+    "WSMessage",
+    "WSMessageType",
+]

agentremote_common/models/capability.py

@@ -0,0 +1,32 @@
+"""
+AgentRemote — 能力注册数据模型.
+
+CapabilityManifest — 替代旧的 SkillManifest + Capability.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class CapabilityManifest(BaseModel):
+    """节点上报的能力清单（替代 SkillManifest）"""
+    id: str                                      # "desktop.cua" | "crm-transaction-filter"
+    runner: str                                  # "cua" | "rpa" — Middleware 用此字段路由
+    tools: List[str] = Field(default_factory=list)  # ["click","type_text","list_apps",...]
+    description: str = ""
+    version: str = "1.0.0"
+    metadata: Dict[str, Any] = Field(default_factory=dict)  # 预留扩展
+
+
+class FlowManifest(BaseModel):
+    """RPA 流程清单（替代旧 skill.yaml 中 runner=rpa 的部分）"""
+    id: str                                      # "crm-transaction-filter"
+    name: str = ""
+    runner: str = "rpa"
+    robot_file: str = ""                         # 相对路径, e.g. "crm_transaction_date_filter.robot"
+    tasks: List[Dict[str, str]] = Field(default_factory=list)  # [{id:"01", name:"..."}]
+    description: str = ""
+    version: str = "1.0.0"

agentremote_common/models/license.py

@@ -0,0 +1,50 @@
+"""
+AgentRemote — 许可证和三道校验数据模型.
+
+LicenseStatus, LicenseInfo, License, GatewayCheckResult.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class LicenseStatus(str, Enum):
+    TRIAL = "trial"
+    ACTIVE = "active"
+    EXPIRED = "expired"
+
+
+class LicenseInfo(BaseModel):
+    """解密后的许可证信息"""
+    tenant_id: str
+    capability_id: str                            # 授权的能力 ID
+    status: str = "active"                        # trial | active | expired
+    max_tasks: int = 0                            # 0 = unlimited
+    task_count: int = 0
+    issued_at: str = ""
+    expires_at: str = ""
+    node_ids: List[str] = Field(default_factory=list)
+    valid: bool = True                            # 许可证是否有效
+
+
+class License(BaseModel):
+    """许可证"""
+    tenant_id: str
+    capability_id: str                            # 授权的能力 ID
+    status: LicenseStatus = LicenseStatus.TRIAL
+    max_tasks: int = 10
+    task_count: int = 0
+    expires_at: Optional[datetime] = None
+
+
+class GatewayCheckResult(BaseModel):
+    """三道校验结果"""
+    passed: bool
+    check_name: str                                # "身份" | "能力" | "许可证"
+    detail: str = ""
+    rejected_reason: str = ""

agentremote_common/models/node.py

@@ -0,0 +1,47 @@
+"""
+AgentRemote — 节点和运行时后端数据模型.
+
+Node, RuntimeBackend, BackendStatus, NodeStatus.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class BackendStatus(str, Enum):
+    READY = "ready"
+    DEGRADED = "degraded"
+    UNAVAILABLE = "unavailable"
+    LIMITED = "limited"
+
+
+class NodeStatus(str, Enum):
+    IDLE = "IDLE"
+    BUSY = "BUSY"
+    SESSION = "SESSION"
+    FDE_DEBUG = "FDE_DEBUG"
+    OFFLINE = "OFFLINE"
+
+
+class RuntimeBackend(BaseModel):
+    """Plugin 本地的运行时后端（Playwright / Shell / CUA / Native）"""
+    backend_name: str                            # playwright | shell | cua | native
+    status: BackendStatus = BackendStatus.READY
+    version: Optional[str] = None
+    platform: Optional[str] = None
+    capabilities: List[str] = Field(default_factory=list)
+    limitations: List[str] = Field(default_factory=list)
+
+
+class Node(BaseModel):
+    """节点（一台客户电脑）"""
+    node_id: str                                 # "sh_win_01"
+    tenant_id: str                               # "acme_shanghai"
+    hostname: str = ""
+    os: str = ""
+    status: NodeStatus = NodeStatus.IDLE
+    plugin_version: str = "v0.3.0"