inter-agent-core 0.2.0__py3-none-any.whl

inter_agent/core/shared.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import os
+import secrets
+import socket
+from dataclasses import dataclass
+from pathlib import Path
+
+from inter_agent.core.auth import build_hello
+from inter_agent.core.config import (
+    BUILTIN_DEFAULT_HOST,
+    BUILTIN_DEFAULT_PORT,
+    ConfigError,
+    EndpointResolution,
+    resolve_data_dir_path,
+    resolve_endpoint_config,
+    resolve_explicit_secret_config,
+)
+
+DEFAULT_HOST = BUILTIN_DEFAULT_HOST
+DEFAULT_PORT = BUILTIN_DEFAULT_PORT
+DEFAULT_DIRECT_CAP = 2 * 1024 * 1024
+DEFAULT_BROADCAST_CAP = 512 * 1024
+DEFAULT_FRAME_CAP = 16 * 1024 * 1024
+DEFAULT_CONNECTION_CAP = 64
+DEFAULT_CUSTOM_TYPE_CAP = 128
+DEFAULT_CUSTOM_PAYLOAD_CAP = 1024 * 1024
+DEFAULT_CHANNEL_NAME_CAP = 40
+DEFAULT_SUBSCRIPTIONS_CAP = 32
+DEFAULT_CHANNELS_CAP = 256
+
+
+def env_int(name: str, default: int) -> int:
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    try:
+        return int(raw)
+    except ValueError:
+        return default
+
+
+@dataclass(frozen=True)
+class Limits:
+    frame_max: int = env_int("INTER_AGENT_FRAME_MAX", DEFAULT_FRAME_CAP)
+    direct_text_max: int = env_int("INTER_AGENT_DIRECT_MAX", DEFAULT_DIRECT_CAP)
+    broadcast_text_max: int = env_int("INTER_AGENT_BROADCAST_MAX", DEFAULT_BROADCAST_CAP)
+    connection_max: int = env_int("INTER_AGENT_CONNECTION_MAX", DEFAULT_CONNECTION_CAP)
+    custom_type_max: int = env_int("INTER_AGENT_CUSTOM_TYPE_MAX", DEFAULT_CUSTOM_TYPE_CAP)
+    custom_payload_max: int = env_int("INTER_AGENT_CUSTOM_PAYLOAD_MAX", DEFAULT_CUSTOM_PAYLOAD_CAP)
+    channel_name_max: int = env_int("INTER_AGENT_CHANNEL_NAME_MAX", DEFAULT_CHANNEL_NAME_CAP)
+    subscriptions_max: int = env_int("INTER_AGENT_SUBSCRIPTIONS_MAX", DEFAULT_SUBSCRIPTIONS_CAP)
+    channels_max: int = env_int("INTER_AGENT_CHANNELS_MAX", DEFAULT_CHANNELS_CAP)
+
+
+@dataclass(frozen=True)
+class SecretResolution:
+    """Resolved shared server secret without exposing it in status output."""
+
+    secret: str
+    source: str
+    config_path: Path | None = None
+    path: Path | None = None
+
+
+class ServerAlreadyRunningError(RuntimeError):
+    """Compatibility error for older callers; bind failure now detects duplicates."""
+
+
+def data_dir() -> Path:
+    path = resolve_data_dir_path()
+    path.mkdir(parents=True, exist_ok=True)
+    os.chmod(path, 0o700)
+    return path
+
+
+def token_path() -> Path:
+    return data_dir() / "token"
+
+
+def _atomic_write_text(path: Path, content: str, mode: int = 0o600) -> None:
+    temp_path = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    temp_path.write_text(content, encoding="utf-8")
+    os.chmod(temp_path, mode)
+    os.replace(temp_path, path)
+    os.chmod(path, mode)
+
+
+def load_or_create_token() -> str:
+    """Load or create the fallback local generated secret."""
+    path = token_path()
+    if path.exists():
+        os.chmod(path, 0o600)
+        token = path.read_text(encoding="utf-8").strip()
+        if token:
+            return token
+    token = secrets.token_urlsafe(32)
+    _atomic_write_text(path, token + "\n")
+    return token
+
+
+def resolve_shared_secret() -> SecretResolution:
+    """Resolve the shared server secret using env/config/token-file precedence."""
+    try:
+        explicit = resolve_explicit_secret_config()
+    except ConfigError as exc:
+        raise SystemExit(str(exc)) from exc
+    if explicit is not None:
+        return SecretResolution(
+            secret=explicit.secret,
+            source=explicit.source,
+            config_path=explicit.config_path,
+        )
+    return SecretResolution(secret=load_or_create_token(), source="token_file", path=token_path())
+
+
+def resolve_endpoint(
+    host: str | None = None,
+    port: int | None = None,
+    *,
+    allow_discovery: bool = False,
+    tls: bool | None = None,
+    tls_cert_path: str | None = None,
+    tls_key_path: str | None = None,
+) -> EndpointResolution:
+    """Resolve the configured endpoint.
+
+    ``allow_discovery`` is accepted for compatibility but no longer redirects
+    away from the configured endpoint.
+    """
+    del allow_discovery
+    try:
+        return resolve_endpoint_config(host, port, tls, tls_cert_path, tls_key_path)
+    except ConfigError as exc:
+        raise SystemExit(str(exc)) from exc
+
+
+def utc_now() -> str:
+    from datetime import UTC, datetime
+
+    return datetime.now(UTC).isoformat()
+
+
+def next_msg_id() -> str:
+    return secrets.token_hex(8)
+
+
+def control_hello(session_id: str, client_nonce: str | None = None) -> dict[str, object]:
+    return build_hello(
+        role="control",
+        session_id=session_id,
+        name="control",
+        capabilities={},
+        client_nonce=client_nonce,
+    )
+
+
+def validate_name(name: object) -> bool:
+    if not isinstance(name, str):
+        return False
+    import re
+
+    return bool(re.fullmatch(r"[a-z0-9][a-z0-9-]{0,39}", name))
+
+
+def validate_channel_name(channel: object, max_bytes: int) -> bool:
+    if not isinstance(channel, str):
+        return False
+    import re
+
+    if not re.fullmatch(r"[a-z0-9][a-z0-9-]{0,39}", channel):
+        return False
+    return len(channel.encode("utf-8")) <= max_bytes
+
+
+def is_localhost(host: str) -> bool:
+    if host == "127.0.0.1":
+        return True
+    try:
+        return socket.gethostbyname(host) == "127.0.0.1"
+    except Exception:
+        return False

inter_agent/core/shutdown.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import uuid
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+import websockets
+
+from inter_agent.core.auth import AuthError, AuthProtocolError, client_handshake
+from inter_agent.core.shared import control_hello, resolve_endpoint, resolve_shared_secret
+from inter_agent.core.transport import client_ssl_context, websocket_uri
+
+
+@dataclass(frozen=True)
+class ShutdownResult:
+    """Result returned after requesting server shutdown."""
+
+    response: str
+    response_payload: dict[str, object]
+
+
+def _text_frame(frame: str | bytes) -> str:
+    if isinstance(frame, bytes):
+        return frame.decode("utf-8")
+    return frame
+
+
+def _json_object(raw: str) -> dict[str, object]:
+    payload: object = json.loads(raw)
+    if not isinstance(payload, dict):
+        raise ValueError("server response must be a JSON object")
+    return {str(key): value for key, value in payload.items()}
+
+
+async def shutdown_server(
+    host: str,
+    port: int,
+    *,
+    tls: bool = False,
+    data_dir: Path | None = None,
+    tls_cert_path: Path | None = None,
+) -> ShutdownResult:
+    """Request authenticated shutdown through a control connection."""
+    secret = resolve_shared_secret().secret
+    ssl_context = client_ssl_context(tls, data_dir, tls_cert_path)
+    async with websockets.connect(websocket_uri(host, port, tls), ssl=ssl_context) as ws:
+        try:
+            _ = await client_handshake(ws, secret, control_hello(f"shutdown-{uuid.uuid4()}"))
+        except AuthError as exc:
+            raise SystemExit(str(exc)) from exc
+        except (AuthProtocolError, json.JSONDecodeError, UnicodeDecodeError) as exc:
+            raise SystemExit(f"server protocol mismatch: {exc}") from exc
+        await ws.send(json.dumps({"op": "shutdown"}))
+        response = _text_frame(await ws.recv())
+        return ShutdownResult(response=response, response_payload=_json_object(response))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="inter-agent-shutdown")
+    parser.add_argument("--host")
+    parser.add_argument("--port", type=int)
+    parser.add_argument("--tls", dest="tls", action="store_true", default=None)
+    parser.add_argument("--no-tls", dest="tls", action="store_false")
+    parser.add_argument("--tls-cert")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    endpoint = resolve_endpoint(
+        args.host, args.port, allow_discovery=True, tls=args.tls, tls_cert_path=args.tls_cert
+    )
+    result = asyncio.run(
+        shutdown_server(
+            endpoint.host,
+            endpoint.port,
+            tls=endpoint.tls,
+            data_dir=endpoint.data_dir,
+            tls_cert_path=endpoint.tls_cert_path,
+        )
+    )
+    print(result.response)
+    return 0 if result.response_payload.get("op") == "shutdown_ok" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

inter_agent/core/status.py

@@ -0,0 +1,291 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import uuid
+from collections.abc import Sequence
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Literal
+
+import websockets
+from websockets.exceptions import WebSocketException
+
+from inter_agent.core.auth import AuthError, AuthProtocolError, client_handshake
+from inter_agent.core.config import EndpointResolution
+from inter_agent.core.shared import control_hello, resolve_endpoint, resolve_shared_secret
+from inter_agent.core.tls import TlsConfigError
+from inter_agent.core.transport import client_ssl_context, websocket_uri
+
+StatusState = Literal[
+    "available",
+    "unavailable",
+    "auth_failed",
+    "protocol_mismatch",
+]
+
+
+@dataclass(frozen=True)
+class CoreCommandStatus:
+    """Static command capabilities exposed to host adapters."""
+
+    list_supported: bool
+
+
+@dataclass(frozen=True)
+class ServerStatus:
+    """Live server status for command adapters."""
+
+    state: StatusState
+    host: str
+    port: int
+    reachable: bool
+    message: str
+    configured_host: str | None = None
+    configured_port: int | None = None
+    scheme: str | None = None
+    tls: bool | None = None
+    tls_source: str | None = None
+    tls_cert_path: str | None = None
+    tls_cert_source: str | None = None
+    host_source: str | None = None
+    port_source: str | None = None
+    data_dir: str | None = None
+    data_dir_source: str | None = None
+    config_path: str | None = None
+    hints: tuple[str, ...] = ()
+
+
+def command_status() -> CoreCommandStatus:
+    """Return core command capabilities that do not require a live server."""
+    return CoreCommandStatus(list_supported=True)
+
+
+def _status(
+    state: StatusState,
+    host: str,
+    port: int,
+    *,
+    reachable: bool,
+    message: str,
+) -> ServerStatus:
+    return ServerStatus(
+        state=state,
+        host=host,
+        port=port,
+        reachable=reachable,
+        message=message,
+    )
+
+
+def _json_object(raw: str) -> dict[str, object]:
+    payload: object = json.loads(raw)
+    if not isinstance(payload, dict):
+        raise ValueError("server response must be a JSON object")
+    return {str(key): value for key, value in payload.items()}
+
+
+async def _probe_server(
+    host: str,
+    port: int,
+    secret: str,
+    *,
+    tls: bool = False,
+    data_dir: Path | None = None,
+    tls_cert_path: Path | None = None,
+) -> ServerStatus:
+    ssl_context = client_ssl_context(tls, data_dir, tls_cert_path)
+    async with websockets.connect(websocket_uri(host, port, tls), ssl=ssl_context) as ws:
+        response_raw = await client_handshake(ws, secret, control_hello(f"status-{uuid.uuid4()}"))
+
+    response = _json_object(response_raw)
+    op = response.get("op")
+    if op == "welcome":
+        return _status(
+            "available",
+            host,
+            port,
+            reachable=True,
+            message="server available",
+        )
+    if op == "error" and response.get("code") == "AUTH_FAILED":
+        return _status(
+            "auth_failed",
+            host,
+            port,
+            reachable=True,
+            message="server authentication failed",
+        )
+    return _status(
+        "protocol_mismatch",
+        host,
+        port,
+        reachable=True,
+        message="server returned an unexpected status response",
+    )
+
+
+async def check_server_status(
+    host: str,
+    port: int,
+    timeout: float = 0.5,
+    *,
+    tls: bool = False,
+    data_dir: Path | None = None,
+    tls_cert_path: Path | None = None,
+) -> ServerStatus:
+    """Probe the live WebSocket endpoint with the resolved shared secret."""
+    try:
+        secret = resolve_shared_secret().secret
+        return await asyncio.wait_for(
+            _probe_server(
+                host,
+                port,
+                secret,
+                tls=tls,
+                data_dir=data_dir,
+                tls_cert_path=tls_cert_path,
+            ),
+            timeout=timeout,
+        )
+    except AuthError:
+        return _status(
+            "auth_failed",
+            host,
+            port,
+            reachable=True,
+            message="server authentication failed",
+        )
+    except (json.JSONDecodeError, UnicodeDecodeError, ValueError, AuthProtocolError):
+        return _status(
+            "protocol_mismatch",
+            host,
+            port,
+            reachable=True,
+            message="server returned an invalid status response",
+        )
+    except TlsConfigError as exc:
+        return _status(
+            "unavailable",
+            host,
+            port,
+            reachable=False,
+            message=f"TLS configuration failed: {exc}",
+        )
+    except (OSError, TimeoutError, WebSocketException):
+        return _status(
+            "unavailable",
+            host,
+            port,
+            reachable=False,
+            message="server connection failed",
+        )
+
+
+def _hints(status: ServerStatus) -> tuple[str, ...]:
+    if status.state == "unavailable":
+        return ("start inter-agent-server or check INTER_AGENT_HOST and INTER_AGENT_PORT",)
+    return ()
+
+
+async def check_resolved_server_status(
+    resolution: EndpointResolution, timeout: float = 0.5
+) -> ServerStatus:
+    """Check status and attach endpoint/config diagnostics."""
+    status = await check_server_status(
+        resolution.host,
+        resolution.port,
+        timeout=timeout,
+        tls=resolution.tls,
+        data_dir=resolution.data_dir,
+        tls_cert_path=resolution.tls_cert_path,
+    )
+    status = replace(
+        status,
+        configured_host=resolution.configured_host,
+        configured_port=resolution.configured_port,
+        scheme=resolution.scheme,
+        tls=resolution.tls,
+        tls_source=resolution.tls_source,
+        tls_cert_path=(
+            str(resolution.tls_cert_path) if resolution.tls_cert_path is not None else None
+        ),
+        tls_cert_source=resolution.tls_cert_source,
+        host_source=resolution.host_source,
+        port_source=resolution.port_source,
+        data_dir=str(resolution.data_dir),
+        data_dir_source=resolution.data_dir_source,
+        config_path=str(resolution.config_path) if resolution.config_path is not None else None,
+    )
+    return replace(status, hints=_hints(status))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="inter-agent-status")
+    parser.add_argument("--host")
+    parser.add_argument("--port", type=int)
+    parser.add_argument("--tls", dest="tls", action="store_true", default=None)
+    parser.add_argument("--no-tls", dest="tls", action="store_false")
+    parser.add_argument("--tls-cert")
+    parser.add_argument("--json", action="store_true", help="emit JSON status output")
+    return parser
+
+
+def _status_payload(status: ServerStatus) -> dict[str, object]:
+    return {
+        "state": status.state,
+        "host": status.host,
+        "port": status.port,
+        "configured_host": status.configured_host,
+        "configured_port": status.configured_port,
+        "scheme": status.scheme,
+        "tls": status.tls,
+        "tls_source": status.tls_source,
+        "tls_cert_path": status.tls_cert_path,
+        "tls_cert_source": status.tls_cert_source,
+        "host_source": status.host_source,
+        "port_source": status.port_source,
+        "data_dir": status.data_dir,
+        "data_dir_source": status.data_dir_source,
+        "config_path": status.config_path,
+        "hints": list(status.hints),
+        "reachable": status.reachable,
+        "message": status.message,
+    }
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    endpoint = resolve_endpoint(
+        args.host, args.port, allow_discovery=True, tls=args.tls, tls_cert_path=args.tls_cert
+    )
+    status = asyncio.run(check_resolved_server_status(endpoint))
+    if args.json:
+        print(json.dumps(_status_payload(status)))
+    else:
+        print(f"state={status.state}")
+        print(f"host={status.host}")
+        print(f"port={status.port}")
+        print(f"scheme={status.scheme}")
+        print(f"tls={status.tls}")
+        print(f"tls_source={status.tls_source}")
+        print(f"tls_cert_path={status.tls_cert_path or ''}")
+        print(f"tls_cert_source={status.tls_cert_source or ''}")
+        print(f"reachable={status.reachable}")
+        print(f"configured_host={status.configured_host}")
+        print(f"configured_port={status.configured_port}")
+        print(f"host_source={status.host_source}")
+        print(f"port_source={status.port_source}")
+        print(f"data_dir={status.data_dir}")
+        print(f"data_dir_source={status.data_dir_source}")
+        print(f"config_path={status.config_path or ''}")
+        print(f"message={status.message}")
+        for hint in status.hints:
+            print(f"hint={hint}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

inter_agent/core/tls.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import ipaddress
+import os
+import ssl
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+from cryptography import x509
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+from cryptography.x509.oid import NameOID
+
+
+class TlsConfigError(RuntimeError):
+    """Raised when TLS configuration cannot be used."""
+
+
+DEFAULT_CERT_NAME = "tls-cert.pem"
+DEFAULT_KEY_NAME = "tls-key.pem"
+
+
+def default_cert_path(data_dir: Path) -> Path:
+    return data_dir / DEFAULT_CERT_NAME
+
+
+def default_key_path(data_dir: Path) -> Path:
+    return data_dir / DEFAULT_KEY_NAME
+
+
+def resolved_tls_paths(
+    data_dir: Path,
+    cert_path: Path | None = None,
+    key_path: Path | None = None,
+) -> tuple[Path, Path]:
+    if (cert_path is None) != (key_path is None):
+        raise TlsConfigError("TLS requires both certificate and key paths, or neither")
+    if cert_path is not None and key_path is not None:
+        return cert_path, key_path
+    return default_cert_path(data_dir), default_key_path(data_dir)
+
+
+def ensure_tls_material(
+    data_dir: Path,
+    host: str,
+    cert_path: Path | None = None,
+    key_path: Path | None = None,
+) -> tuple[Path, Path]:
+    cert, key = resolved_tls_paths(data_dir, cert_path, key_path)
+    if cert.exists() and key.exists():
+        os.chmod(cert, 0o600)
+        os.chmod(key, 0o600)
+        return cert, key
+    if cert_path is not None or key_path is not None:
+        raise TlsConfigError(f"configured TLS certificate or key does not exist: {cert}, {key}")
+    data_dir.mkdir(parents=True, exist_ok=True)
+    os.chmod(data_dir, 0o700)
+    _generate_self_signed_cert(cert, key, host)
+    return cert, key
+
+
+def build_server_ssl_context(
+    data_dir: Path,
+    host: str,
+    cert_path: Path | None = None,
+    key_path: Path | None = None,
+) -> ssl.SSLContext:
+    cert, key = ensure_tls_material(data_dir, host, cert_path, key_path)
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+    try:
+        context.load_cert_chain(certfile=cert, keyfile=key)
+    except OSError as exc:
+        raise TlsConfigError(f"could not load TLS certificate or key: {exc}") from exc
+    return context
+
+
+def build_client_ssl_context(
+    data_dir: Path,
+    cert_path: Path | None = None,
+) -> ssl.SSLContext:
+    cert = cert_path or default_cert_path(data_dir)
+    if not cert.exists():
+        raise TlsConfigError(
+            f"TLS certificate not found at {cert}; "
+            "start the server or configure INTER_AGENT_TLS_CERT"
+        )
+    context = ssl.create_default_context(cafile=str(cert))
+    context.check_hostname = False
+    return context
+
+
+def _subject_alt_names(host: str) -> list[x509.GeneralName]:
+    names: list[x509.GeneralName] = [
+        x509.DNSName("localhost"),
+        x509.IPAddress(ipaddress.ip_address("127.0.0.1")),
+        x509.IPAddress(ipaddress.ip_address("::1")),
+    ]
+    try:
+        names.append(x509.IPAddress(ipaddress.ip_address(host)))
+    except ValueError:
+        if host:
+            names.append(x509.DNSName(host))
+    return names
+
+
+def _generate_self_signed_cert(cert_path: Path, key_path: Path, host: str) -> None:
+    private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+    subject = issuer = x509.Name(
+        [
+            x509.NameAttribute(NameOID.COMMON_NAME, "inter-agent local TLS"),
+        ]
+    )
+    now = datetime.now(UTC)
+    certificate = (
+        x509.CertificateBuilder()
+        .subject_name(subject)
+        .issuer_name(issuer)
+        .public_key(private_key.public_key())
+        .serial_number(x509.random_serial_number())
+        .not_valid_before(now - timedelta(minutes=1))
+        .not_valid_after(now + timedelta(days=3650))
+        .add_extension(x509.SubjectAlternativeName(_subject_alt_names(host)), critical=False)
+        .sign(private_key, hashes.SHA256())
+    )
+
+    cert_temp = cert_path.with_name(f".{cert_path.name}.{os.getpid()}.tmp")
+    key_temp = key_path.with_name(f".{key_path.name}.{os.getpid()}.tmp")
+    cert_temp.write_bytes(certificate.public_bytes(serialization.Encoding.PEM))
+    key_temp.write_bytes(
+        private_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.NoEncryption(),
+        )
+    )
+    os.chmod(cert_temp, 0o600)
+    os.chmod(key_temp, 0o600)
+    os.replace(cert_temp, cert_path)
+    os.replace(key_temp, key_path)
+    os.chmod(cert_path, 0o600)
+    os.chmod(key_path, 0o600)