agentremote-common 1.0.0__py3-none-any.whl

agentremote_common/__init__.py

@@ -0,0 +1,21 @@
+"""Shared AgentRemote demo protocol, MQTT client and security helpers."""
+
+from .mqtt_client import AgentRemoteMqttClient
+from .protocol.message import MqttConfig, WSMessage, WSMessageType
+from .protocol.topics import (
+    PLUGIN_OUTBOUND_TOPICS,
+    gateway_topic,
+    parse_plugin_topic,
+    plugin_topic,
+)
+
+__all__ = [
+    "MqttConfig",
+    "WSMessage",
+    "WSMessageType",
+    "AgentRemoteMqttClient",
+    "PLUGIN_OUTBOUND_TOPICS",
+    "parse_plugin_topic",
+    "plugin_topic",
+    "gateway_topic",
+]

agentremote_common/config.py

@@ -0,0 +1,341 @@
+"""Role-based AgentRemote configuration helpers.
+
+Resolution order is always: explicit CLI args, environment variables,
+role-specific TOML config, local development defaults.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import tomllib
+from typing import Any, Mapping
+
+
+TRUE_VALUES = {"1", "true", "yes", "on"}
+FALSE_VALUES = {"0", "false", "no", "off"}
+
+ROLE_ENV_VARS = {
+    "cli": "AGENTREMOTE_CLI_CONFIG",
+    "server": "AGENTREMOTE_MIDDLEWARE_CONFIG",
+    "client": "AGENTREMOTE_RUNTIME_CONFIG",
+}
+
+ROLE_CONFIG_FILES = {
+    "cli": "agentremote.cli.toml",
+    "server": "agentremote.server.toml",
+    "client": "agentremote.client.toml",
+}
+
+
+@dataclass(frozen=True)
+class CliDefaults:
+    middleware_url: str = "http://127.0.0.1:9100"
+    tenant: str = "acme_shanghai"
+    node: str = "sh_win_01"
+    agent: str = "agent_ai_01"
+    handle: str = ""
+
+
+@dataclass(frozen=True)
+class MiddlewareDefaults:
+    http_host: str = "127.0.0.1"
+    http_port: int = 9100
+    mqtt_broker: str = "127.0.0.1"
+    mqtt_port: int = 1883
+    auth_broker_url: str = ""
+    require_auth: bool = False
+    dev_skip_license: bool = False
+
+
+@dataclass(frozen=True)
+class RuntimeDefaults:
+    node: str = "sh_win_01"
+    tenant: str = "acme_shanghai"
+    mqtt_broker: str = "127.0.0.1"
+    mqtt_port: int = 1883
+    plugins_dir: str = "client/plugins"
+    watch_plugins: bool = False
+    plugin_watch_interval: float = 2.0
+
+
+def load_cli_defaults(config_path: str = "") -> CliDefaults:
+    config = load_role_config("cli", config_path)
+    return CliDefaults(
+        middleware_url=_pick_str(
+            config,
+            "cli",
+            "middleware_url",
+            "http://127.0.0.1:9100",
+            "AGENTREMOTE_MIDDLEWARE_URL",
+            "MIDDLEWARE_HTTP",
+        ),
+        tenant=_pick_str(config, "cli", "tenant", "acme_shanghai", "AGENTREMOTE_TENANT", "TENANT_ID"),
+        node=_pick_str(config, "cli", "node", "sh_win_01", "AGENTREMOTE_NODE", "NODE_ID"),
+        agent=_pick_str(config, "cli", "agent", "agent_ai_01", "AGENTREMOTE_AGENT", "AGENT_ID"),
+        handle=_pick_str(config, "cli", "handle", "", "AGENTREMOTE_HANDLE"),
+    )
+
+
+def load_middleware_defaults(config_path: str = "") -> MiddlewareDefaults:
+    config = load_role_config("server", config_path)
+    return MiddlewareDefaults(
+        http_host=_pick_str(
+            config,
+            "middleware",
+            "http_host",
+            "127.0.0.1",
+            "AGENTREMOTE_HTTP_HOST",
+            "AGENTREMOTE_MIDDLEWARE_HTTP_HOST",
+        ),
+        http_port=_pick_int(
+            config,
+            "middleware",
+            "http_port",
+            9100,
+            "AGENTREMOTE_HTTP_PORT",
+            "AGENTREMOTE_MIDDLEWARE_HTTP_PORT",
+        ),
+        mqtt_broker=_pick_str(
+            config,
+            "mqtt",
+            "broker_host",
+            "127.0.0.1",
+            "AGENTREMOTE_MQTT_BROKER",
+            "AGENTREMOTE_MQTT_HOST",
+            "AGENTREMOTE_MIDDLEWARE_MQTT_BROKER",
+        ),
+        mqtt_port=_pick_int(
+            config,
+            "mqtt",
+            "broker_port",
+            1883,
+            "AGENTREMOTE_MQTT_PORT",
+            "AGENTREMOTE_MIDDLEWARE_MQTT_PORT",
+        ),
+        auth_broker_url=_pick_str(
+            config,
+            "middleware",
+            "auth_broker_url",
+            "",
+            "AGENTREMOTE_AUTH_BROKER_URL",
+            "AUTH_BROKER_URL",
+        ),
+        require_auth=_pick_bool(config, "middleware", "require_auth", False, "AGENTREMOTE_REQUIRE_AUTH"),
+        dev_skip_license=_pick_bool(
+            config,
+            "middleware",
+            "dev_skip_license",
+            False,
+            "AGENTREMOTE_DEV_SKIP_LICENSE",
+        ),
+    )
+
+
+def load_runtime_defaults(config_path: str = "") -> RuntimeDefaults:
+    config = load_role_config("client", config_path)
+    return RuntimeDefaults(
+        node=_pick_str(config, "runtime", "node", "sh_win_01", "AGENTREMOTE_NODE", "NODE_ID"),
+        tenant=_pick_str(config, "runtime", "tenant", "acme_shanghai", "AGENTREMOTE_TENANT", "TENANT_ID"),
+        mqtt_broker=_pick_str(
+            config,
+            "mqtt",
+            "broker_host",
+            "127.0.0.1",
+            "AGENTREMOTE_MQTT_BROKER",
+            "AGENTREMOTE_MQTT_HOST",
+            "AGENTREMOTE_RUNTIME_MQTT_BROKER",
+        ),
+        mqtt_port=_pick_int(
+            config,
+            "mqtt",
+            "broker_port",
+            1883,
+            "AGENTREMOTE_MQTT_PORT",
+            "AGENTREMOTE_RUNTIME_MQTT_PORT",
+        ),
+        plugins_dir=_pick_str(
+            config,
+            "runtime",
+            "plugins_dir",
+            "client/plugins",
+            "AGENTREMOTE_PLUGINS_DIR",
+            "AGENTREMOTE_RUNTIME_PLUGINS_DIR",
+        ),
+        watch_plugins=_pick_bool(
+            config,
+            "runtime",
+            "watch_plugins",
+            False,
+            "AGENTREMOTE_WATCH_PLUGINS",
+            "AGENTREMOTE_RUNTIME_WATCH_PLUGINS",
+        ),
+        plugin_watch_interval=_pick_float(
+            config,
+            "runtime",
+            "plugin_watch_interval",
+            2.0,
+            "AGENTREMOTE_PLUGIN_WATCH_INTERVAL",
+            "AGENTREMOTE_RUNTIME_PLUGIN_WATCH_INTERVAL",
+        ),
+    )
+
+
+def load_role_config(role: str, explicit_path: str = "") -> dict[str, Any]:
+    path = resolve_config_path(role, explicit_path)
+    if path is None:
+        return {}
+    with path.open("rb") as f:
+        data = tomllib.load(f)
+    if not isinstance(data, dict):
+        return {}
+    return data
+
+
+def resolve_config_path(role: str, explicit_path: str = "") -> Path | None:
+    if role not in ROLE_CONFIG_FILES:
+        raise ValueError(f"Unknown AgentRemote config role: {role}")
+
+    explicit = explicit_path.strip()
+    if explicit:
+        return _existing_path(explicit, "explicit")
+
+    role_env = os.environ.get(ROLE_ENV_VARS[role], "").strip()
+    if role_env:
+        return _existing_path(role_env, ROLE_ENV_VARS[role])
+
+    shared_env = os.environ.get("AGENTREMOTE_CONFIG", "").strip()
+    if shared_env:
+        return _existing_path(shared_env, "AGENTREMOTE_CONFIG")
+
+    for candidate in _default_config_candidates(role):
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _default_config_candidates(role: str) -> list[Path]:
+    filename = ROLE_CONFIG_FILES[role]
+    root = Path(__file__).resolve().parents[2]
+    cwd = Path.cwd()
+
+    role_dirs = {
+        "cli": ("remotecli", "config"),
+        "server": ("platform", "middleware", "config"),
+        "client": ("client", "config"),
+    }
+    role_dir = role_dirs[role]
+    candidates = [
+        cwd.joinpath(*role_dir, filename),
+        root.joinpath(*role_dir, filename),
+    ]
+
+    result: list[Path] = []
+    for candidate in candidates:
+        if candidate not in result:
+            result.append(candidate)
+    return result
+
+
+def _existing_path(value: str, source: str) -> Path:
+    path = Path(value).expanduser()
+    if not path.exists():
+        raise FileNotFoundError(f"{source} config path not found: {path}")
+    return path
+
+
+def _env_value(*names: str) -> str | None:
+    for name in names:
+        value = os.environ.get(name)
+        if value is not None and value.strip() != "":
+            return value.strip()
+    return None
+
+
+def _section(config: Mapping[str, Any], name: str) -> Mapping[str, Any]:
+    value = config.get(name, {})
+    if isinstance(value, Mapping):
+        return value
+    return {}
+
+
+def _config_value(config: Mapping[str, Any], section: str, key: str) -> Any:
+    return _section(config, section).get(key)
+
+
+def _pick_str(
+    config: Mapping[str, Any],
+    section: str,
+    key: str,
+    default: str,
+    *env_names: str,
+) -> str:
+    env = _env_value(*env_names)
+    if env is not None:
+        return env
+    value = _config_value(config, section, key)
+    if value is None:
+        return default
+    return str(value)
+
+
+def _pick_int(
+    config: Mapping[str, Any],
+    section: str,
+    key: str,
+    default: int,
+    *env_names: str,
+) -> int:
+    env = _env_value(*env_names)
+    if env is not None:
+        return int(env)
+    value = _config_value(config, section, key)
+    if value is None:
+        return default
+    return int(value)
+
+
+def _pick_float(
+    config: Mapping[str, Any],
+    section: str,
+    key: str,
+    default: float,
+    *env_names: str,
+) -> float:
+    env = _env_value(*env_names)
+    if env is not None:
+        return float(env)
+    value = _config_value(config, section, key)
+    if value is None:
+        return default
+    return float(value)
+
+
+def _pick_bool(
+    config: Mapping[str, Any],
+    section: str,
+    key: str,
+    default: bool,
+    *env_names: str,
+) -> bool:
+    env = _env_value(*env_names)
+    if env is not None:
+        return _to_bool(env)
+    value = _config_value(config, section, key)
+    if value is None:
+        return default
+    return _to_bool(value)
+
+
+def _to_bool(value: Any) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int):
+        return bool(value)
+    lowered = str(value).strip().lower()
+    if lowered in TRUE_VALUES:
+        return True
+    if lowered in FALSE_VALUES:
+        return False
+    raise ValueError(f"Invalid boolean config value: {value!r}")

agentremote_common/crypto/__init__.py

@@ -0,0 +1,69 @@
+"""
+AgentRemote Crypto Layer — ECDSA + JWT + AES + SHA256
+
+Provides all cryptographic primitives for the demo security chain:
+  - keys:      ECDSA P-256 key generation, signing, verification
+  - certs:     X.509 self-signed device certificates
+  - jwt:       JWT (ES256) authentication tokens
+  - license:   AES-256-GCM license encryption/decryption
+  - integrity: SHA256 file/content hashing
+"""
+
+from .keys import (
+    generate_keypair,
+    sign_data,
+    verify_signature,
+    load_private_key,
+    load_public_key,
+    private_to_pem,
+    public_to_pem,
+)
+from .certificates import (
+    generate_device_cert,
+    load_device_cert,
+    verify_device_cert,
+)
+from .jwt_auth import (
+    create_auth_token,
+    verify_auth_token,
+)
+from .license import (
+    encrypt_license,
+    decrypt_license,
+    generate_license_key,
+    load_license_key,
+)
+from .integrity import (
+    hash_file,
+    hash_content,
+    hash_skill_directory,
+    verify_skill_integrity,
+)
+
+__all__ = [
+    # keys
+    "generate_keypair",
+    "sign_data",
+    "verify_signature",
+    "load_private_key",
+    "load_public_key",
+    "private_to_pem",
+    "public_to_pem",
+    # certs
+    "generate_device_cert",
+    "load_device_cert",
+    "verify_device_cert",
+    # jwt
+    "create_auth_token",
+    "verify_auth_token",
+    # license
+    "encrypt_license",
+    "decrypt_license",
+    "generate_license_key",
+    "load_license_key",
+    # integrity
+    "hash_file",
+    "hash_content",
+    "hash_skill_directory",
+    "verify_skill_integrity",
+]

agentremote_common/crypto/certificates.py

@@ -0,0 +1,171 @@
+"""
+X.509 设备证书管理
+
+Demo 用自签名 CA 签发的设备证书。
+- CA 根证书 (ca_public.pem) → Middleware 内置，验证设备证书
+- 设备证书 (device_cert.pem + device_private.pem) → Plugin 持有
+"""
+
+from __future__ import annotations
+
+import datetime
+from pathlib import Path
+from typing import Tuple
+
+from cryptography import x509
+from cryptography.x509.oid import NameOID
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+
+from .keys import generate_keypair, private_to_pem, public_to_pem
+
+
+def generate_ca() -> Tuple[ec.EllipticCurvePrivateKey, x509.Certificate]:
+    """
+    生成自签名 CA 根证书。
+
+    Returns:
+        (ca_private_key, ca_certificate)
+    """
+    ca_private, ca_public = generate_keypair()
+
+    subject = issuer = x509.Name([
+        x509.NameAttribute(NameOID.COMMON_NAME, "AgentRemote Demo CA"),
+        x509.NameAttribute(NameOID.ORGANIZATION_NAME, "AgentRemote Demo"),
+        x509.NameAttribute(NameOID.COUNTRY_NAME, "CN"),
+    ])
+
+    ca_cert = (
+        x509.CertificateBuilder()
+        .subject_name(subject)
+        .issuer_name(issuer)
+        .public_key(ca_public)
+        .serial_number(x509.random_serial_number())
+        .not_valid_before(datetime.datetime.utcnow() - datetime.timedelta(days=1))
+        .not_valid_after(datetime.datetime.utcnow() + datetime.timedelta(days=3650))  # 10 年 Demo CA
+        .add_extension(x509.BasicConstraints(ca=True, path_length=0), critical=True)
+        .add_extension(x509.KeyUsage(
+            key_cert_sign=True,
+            crl_sign=True,
+            digital_signature=False,
+            content_commitment=False,
+            key_encipherment=False,
+            data_encipherment=False,
+            key_agreement=False,
+            encipher_only=False,
+            decipher_only=False,
+        ), critical=True)
+        .add_extension(x509.SubjectKeyIdentifier.from_public_key(ca_public), critical=False)
+        .sign(ca_private, hashes.SHA256())
+    )
+
+    return ca_private, ca_cert
+
+
+def generate_device_cert(
+    ca_private: ec.EllipticCurvePrivateKey,
+    ca_cert: x509.Certificate,
+    device_id: str = "sh_win_01",
+    tenant_id: str = "acme_shanghai",
+) -> Tuple[ec.EllipticCurvePrivateKey, x509.Certificate]:
+    """
+    由 CA 签发设备证书。
+
+    Args:
+        ca_private: CA 私钥
+        ca_cert: CA 证书
+        device_id: 设备标识
+        tenant_id: 租户标识
+
+    Returns:
+        (device_private_key, device_certificate)
+    """
+    device_private, device_public = generate_keypair()
+    ca_public = ca_cert.public_key()
+
+    subject = x509.Name([
+        x509.NameAttribute(NameOID.COMMON_NAME, f"plugin-{device_id}"),
+        x509.NameAttribute(NameOID.ORGANIZATION_NAME, tenant_id),
+        x509.NameAttribute(NameOID.ORGANIZATIONAL_UNIT_NAME, f"node:{device_id}"),
+        x509.NameAttribute(NameOID.COUNTRY_NAME, "CN"),
+    ])
+
+    device_cert = (
+        x509.CertificateBuilder()
+        .subject_name(subject)
+        .issuer_name(ca_cert.subject)
+        .public_key(device_public)
+        .serial_number(x509.random_serial_number())
+        .not_valid_before(datetime.datetime.utcnow() - datetime.timedelta(days=1))
+        .not_valid_after(datetime.datetime.utcnow() + datetime.timedelta(days=365))  # 1 年设备证书
+        .add_extension(x509.BasicConstraints(ca=False, path_length=None), critical=True)
+        .add_extension(x509.KeyUsage(
+            digital_signature=True,
+            content_commitment=False,
+            key_encipherment=False,
+            data_encipherment=False,
+            key_agreement=False,
+            key_cert_sign=False,
+            crl_sign=False,
+            encipher_only=False,
+            decipher_only=False,
+        ), critical=True)
+        .add_extension(x509.SubjectKeyIdentifier.from_public_key(device_public), critical=False)
+        .add_extension(x509.AuthorityKeyIdentifier.from_issuer_public_key(ca_public), critical=False)
+        .sign(ca_private, hashes.SHA256())
+    )
+
+    return device_private, device_cert
+
+
+def load_device_cert(cert_path: str | Path) -> x509.Certificate:
+    """从 PEM 文件加载设备证书"""
+    data = Path(cert_path).read_bytes()
+    return x509.load_pem_x509_certificate(data)
+
+
+def load_ca_public_key(ca_cert_path: str | Path) -> ec.EllipticCurvePublicKey:
+    """从 CA 证书中提取公钥（用于验证设备证书签名）"""
+    ca_cert = load_device_cert(ca_cert_path)
+    pk = ca_cert.public_key()
+    if not isinstance(pk, ec.EllipticCurvePublicKey):
+        raise TypeError("CA public key is not EC")
+    return pk
+
+
+def extract_device_public_key(device_cert: x509.Certificate) -> ec.EllipticCurvePublicKey:
+    """从设备证书中提取公钥"""
+    pk = device_cert.public_key()
+    if not isinstance(pk, ec.EllipticCurvePublicKey):
+        raise TypeError("Device public key is not EC")
+    return pk
+
+
+def verify_device_cert(
+    device_cert: x509.Certificate,
+    ca_public_key: ec.EllipticCurvePublicKey,
+) -> bool:
+    """
+    验证设备证书是否由受信 CA 签发。
+
+    同时检查:
+      - 证书签名（CA 公钥验证）
+      - 有效期
+    """
+    try:
+        # 验证签名 — CA 用 SHA256 签名设备证书
+        ca_public_key.verify(
+            device_cert.signature,
+            device_cert.tbs_certificate_bytes,
+            ec.ECDSA(hashes.SHA256()),
+        )
+        return True
+    except Exception as e:
+        import sys
+        print(f"  [DEBUG] Cert verification error: {e}", file=sys.stderr)
+        return False
+
+
+def cert_to_pem(cert: x509.Certificate) -> bytes:
+    """证书 → PEM 字节"""
+    return cert.public_bytes(serialization.Encoding.PEM)