ccoding 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

ccode/config.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import copy
 import json
+import secrets
 import socket
 import uuid
 from pathlib import Path
@@ -32,11 +33,13 @@ DEFAULT_REMOTE: dict[str, Any] = {
     "local": {
         "host": "127.0.0.1",
         "port": 8765,
-        "token": "",
+        "appId": "",
+        "appKey": "",
     },
     "server": {
         "url": "",
-        "token": "",
+        "appId": "",
+        "appKey": "",
         "device_name": "",
         "device_id": "",
         "auto_connect": True,
@@ -103,6 +106,10 @@ def _new_device_id() -> str:
     return f"ccode-{uuid.uuid4().hex}"
 
 
+def _new_app_id() -> str:
+    return f"app_{secrets.token_urlsafe(9)}"
+
+
 def normalize_remote(remote: Any) -> dict[str, Any]:
     normalized = copy.deepcopy(DEFAULT_REMOTE)
     if not isinstance(remote, dict):
@@ -132,18 +139,31 @@ def normalize_remote(remote: Any) -> dict[str, Any]:
         port = remote.get("port")
     if isinstance(port, int):
         normalized["local"]["port"] = port
-    token = local.get("token") if isinstance(local, dict) else None
-    if not isinstance(token, str):
-        token = remote.get("token")
-    if isinstance(token, str):
-        normalized["local"]["token"] = token
+    local_app_id = local.get("appId") if isinstance(local, dict) else None
+    local_app_key = local.get("appKey") if isinstance(local, dict) else None
+    local_token = local.get("token") if isinstance(local, dict) else None
+    if not isinstance(local_token, str):
+        local_token = remote.get("token")
+    if isinstance(local_app_id, str):
+        normalized["local"]["appId"] = local_app_id
+    elif isinstance(local_token, str) and local_token:
+        normalized["local"]["appId"] = _new_app_id()
+    if isinstance(local_app_key, str):
+        normalized["local"]["appKey"] = local_app_key
+    elif isinstance(local_token, str):
+        normalized["local"]["appKey"] = local_token
 
     server = remote.get("server") if isinstance(remote.get("server"), dict) else {}
     if isinstance(server, dict):
-        for key in ("url", "token", "device_name", "device_id"):
+        server_token = server.get("token")
+        for key in ("url", "appId", "appKey", "device_name", "device_id"):
             value = server.get(key)
             if isinstance(value, str):
                 normalized["server"][key] = value
+        if not normalized["server"].get("appId") and isinstance(server_token, str) and server_token:
+            normalized["server"]["appId"] = _new_app_id()
+        if not normalized["server"].get("appKey") and isinstance(server_token, str):
+            normalized["server"]["appKey"] = server_token
         for key in ("auto_connect", "verify_tls"):
             value = server.get(key)
             if isinstance(value, bool):

ccode/remote.py

@@ -15,20 +15,20 @@ from .remote_common import (
     _new_session_id,
     _sanitize_session_name,
     _utc_now,
+    AuthResult,
     asset_text,
-    auth_token_matches,
     file_lock,
     missing_extra_message,
+    remote_local_app_id,
+    remote_local_app_key,
     remote_local_host_port,
-    remote_local_token,
     remote_local_url,
     remote_mode,
     remote_server_config,
     remote_server_url,
     rotate_log,
-    token_matches,
+    verify_auth_payload,
     web_asset_text,
-    websocket_auth_token,
 )
 
 REMOTE_SESSIONS_PATH = CONFIG_DIR / "remote_sessions.json"
@@ -321,29 +321,33 @@ def ensure_remote_hub(config: dict[str, Any]) -> str | None:
         return f"Failed to start remote hub. See {REMOTE_SERVER_LOG_PATH} for details."
 
 
-_TOKEN_CACHE: tuple[float | None, str] = (None, "")
+_AUTH_CACHE: tuple[float | None, str, str] = (None, "", "")
 
 
-def _current_remote_token() -> str:
-    global _TOKEN_CACHE
+def _current_remote_credentials() -> tuple[str, str]:
+    global _AUTH_CACHE
     try:
         mtime = CONFIG_PATH.stat().st_mtime
     except FileNotFoundError:
         mtime = None
-    cached_mtime, cached_token = _TOKEN_CACHE
+    cached_mtime, app_id, app_key = _AUTH_CACHE
     if cached_mtime == mtime:
-        return cached_token
-    token = remote_local_token(load_config()).strip()
-    _TOKEN_CACHE = (mtime, token)
-    return token
+        return app_id, app_key
+    config = load_config()
+    app_id = remote_local_app_id(config).strip()
+    app_key = remote_local_app_key(config).strip()
+    _AUTH_CACHE = (mtime, app_id, app_key)
+    return app_id, app_key
 
 
-def _valid_token(token: str | None) -> bool:
-    return token_matches(_current_remote_token(), token)
+def _valid_auth_payload(payload: dict[str, Any], scope: str) -> AuthResult:
+    app_id, app_key = _current_remote_credentials()
+    return verify_auth_payload(app_id, app_key, payload, scope)
 
 
-def _valid_auth_token(token: str | None, authorization: str | None = None) -> bool:
-    return auth_token_matches(_current_remote_token(), token, authorization)
+def _auth_response(result: AuthResult, response_class: Any) -> Any:
+    status_code = 401 if result.error in {"auth_required", "reauth_required"} else 403
+    return response_class({"error": result.error or "auth_failed", "message": result.message}, status_code=status_code)
 
 
 async def _attach_websocket_to_session(websocket: Any, session: dict[str, Any]) -> None:
@@ -422,16 +426,18 @@ def create_app() -> Any:
 
     @app.get("/health")
     async def health() -> dict[str, Any]:
-        return {"ok": True, "name": REMOTE_HUB_NAME, "multi_session": True}
+        return {"ok": True, "name": REMOTE_HUB_NAME, "multi_session": True, "remote_kind": "local"}
 
     @app.get("/api/sessions")
     async def sessions(
-        token: str | None = None,
-        authorization: str | None = Header(default=None),
+        x_ccode_app_id: str | None = Header(default=None),
+        x_ccode_timestamp: str | None = Header(default=None),
+        x_ccode_sign: str | None = Header(default=None),
     ) -> Response:
-        if not _valid_auth_token(token, authorization):
-            _log_event("api sessions unauthorized")
-            return JSONResponse({"error": "unauthorized"}, status_code=401)
+        auth_result = _valid_auth_payload({"appId": x_ccode_app_id, "timestamp": x_ccode_timestamp, "sign": x_ccode_sign}, "local.api")
+        if not auth_result.ok:
+            _log_event(f"api sessions unauthorized error={auth_result.error}")
+            return _auth_response(auth_result, JSONResponse)
         sessions = list_remote_sessions()
         _log_event(f"api sessions returned count={len(sessions)}")
         return JSONResponse({"sessions": sessions})
@@ -439,12 +445,14 @@ def create_app() -> Any:
     @app.get("/api/sessions/{session_id}")
     async def session_detail(
         session_id: str,
-        token: str | None = None,
-        authorization: str | None = Header(default=None),
+        x_ccode_app_id: str | None = Header(default=None),
+        x_ccode_timestamp: str | None = Header(default=None),
+        x_ccode_sign: str | None = Header(default=None),
     ) -> Response:
-        if not _valid_auth_token(token, authorization):
-            _log_event(f"api session detail unauthorized session_id={session_id}")
-            return JSONResponse({"error": "unauthorized"}, status_code=401)
+        auth_result = _valid_auth_payload({"appId": x_ccode_app_id, "timestamp": x_ccode_timestamp, "sign": x_ccode_sign}, "local.api")
+        if not auth_result.ok:
+            _log_event(f"api session detail unauthorized session_id={session_id} error={auth_result.error}")
+            return _auth_response(auth_result, JSONResponse)
         session = get_remote_session(session_id)
         if session is None or not _session_is_running(session):
             _log_event(f"api session detail not_found session_id={session_id}")
@@ -454,12 +462,14 @@ def create_app() -> Any:
 
     @app.get("/api/session")
     async def legacy_session(
-        token: str | None = None,
-        authorization: str | None = Header(default=None),
+        x_ccode_app_id: str | None = Header(default=None),
+        x_ccode_timestamp: str | None = Header(default=None),
+        x_ccode_sign: str | None = Header(default=None),
     ) -> Response:
-        if not _valid_auth_token(token, authorization):
-            _log_event("legacy api session unauthorized")
-            return JSONResponse({"error": "unauthorized"}, status_code=401)
+        auth_result = _valid_auth_payload({"appId": x_ccode_app_id, "timestamp": x_ccode_timestamp, "sign": x_ccode_sign}, "local.api")
+        if not auth_result.ok:
+            _log_event(f"legacy api session unauthorized error={auth_result.error}")
+            return _auth_response(auth_result, JSONResponse)
         sessions = list_remote_sessions()
         _log_event(f"legacy api session requested running_count={len(sessions)}")
         if len(sessions) == 1:
@@ -471,9 +481,10 @@ def create_app() -> Any:
     async def websocket_session(websocket: FastAPIWebSocket, session_id: str) -> None:
         await websocket.accept()
         _log_event(f"websocket accepted session_id={session_id}")
-        if not _valid_token(await websocket_auth_token(websocket)):
-            _log_event(f"websocket unauthorized session_id={session_id}")
-            await websocket.send_json({"type": "status", "message": "unauthorized: invalid token"})
+        auth_result = _valid_auth_payload(dict(websocket.query_params), "local.ws")
+        if not auth_result.ok:
+            _log_event(f"websocket unauthorized session_id={session_id} error={auth_result.error}")
+            await websocket.send_json({"type": "error", "error": auth_result.error, "message": auth_result.message})
             await websocket.close(code=1008)
             return
         session = get_remote_session(session_id)
@@ -488,9 +499,10 @@ def create_app() -> Any:
     async def legacy_websocket(websocket: FastAPIWebSocket) -> None:
         await websocket.accept()
         _log_event("legacy websocket accepted")
-        if not _valid_token(await websocket_auth_token(websocket)):
-            _log_event("legacy websocket unauthorized")
-            await websocket.send_json({"type": "status", "message": "unauthorized: invalid token"})
+        auth_result = _valid_auth_payload(dict(websocket.query_params), "local.ws")
+        if not auth_result.ok:
+            _log_event(f"legacy websocket unauthorized error={auth_result.error}")
+            await websocket.send_json({"type": "error", "error": auth_result.error, "message": auth_result.message})
             await websocket.close(code=1008)
             return
         sessions = list_remote_sessions()
@@ -530,11 +542,11 @@ def run_remote_hub_forever(config: dict[str, Any]) -> str | None:
 
 def run_remote_session(config: dict[str, Any], args: list[str]) -> str | None:
     mode = remote_mode(config)
-    if mode == "local" and not remote_local_token(config).strip():
-        return "Remote token is required. Set it in the config screen or press g on the TOKEN field to generate one."
+    if mode == "local" and (not remote_local_app_id(config).strip() or not remote_local_app_key(config).strip()):
+        return "Remote app ID and app key are required. Set them in the config screen or press g on the APP ID / APP KEY fields to generate them."
     server = remote_server_config(config)
-    if mode == "server" and (not remote_server_url(config) or not str(server.get("token") or "").strip()):
-        return "Remote server URL and client token are required in server mode."
+    if mode == "server" and (not remote_server_url(config) or not str(server.get("appId") or "").strip() or not str(server.get("appKey") or "").strip()):
+        return "Remote server URL, client app ID, and client app key are required in server mode."
     error = _check_runtime()
     if error is not None:
         return error
@@ -604,7 +616,7 @@ def run_remote_session(config: dict[str, Any], args: list[str]) -> str | None:
         print(f"  {session_name}\n")
         if host == "0.0.0.0":
             print("Security warning:")
-            print("  Listening on 0.0.0.0 exposes all remote sessions to your network. Protect the access URL and token.\n")
+            print("  Listening on 0.0.0.0 exposes all remote sessions to your network. Protect the access URL and app credentials.\n")
         print("This terminal will attach to this tmux session. The web hub stays running independently.")
         print("Detach with Ctrl+B then D. Browser users can choose this session from the session list.\n")
 

ccode/remote_cli.py

@@ -8,7 +8,7 @@ from pathlib import Path
 from typing import Any
 
 from .config import load_config, mask_secret
-from .remote_common import pid_from_path, remote_display_url, remote_local_host_port, remote_local_token, remote_mode, remote_server_config, remote_server_url
+from .remote_common import pid_from_path, remote_display_url, remote_local_app_id, remote_local_app_key, remote_local_host_port, remote_mode, remote_server_config, remote_server_url
 
 
 def _format_bytes(value: int) -> str:
@@ -90,12 +90,14 @@ def print_status(kind: str | None = None) -> int:
         server = remote_server_config(config)
         print(f"  device name: {server.get('device_name') or '<unset>'}")
         print(f"  device id: {server.get('device_id') or '<unset>'}")
-        print(f"  client token: {mask_secret(str(server.get('token') or ''))}")
+        print(f"  client app id: {server.get('appId') or '<unset>'}")
+        print(f"  client app key: {mask_secret(str(server.get('appKey') or ''))}")
     else:
         host, port = remote_local_host_port(config)
         print(f"  host: {host}")
         print(f"  port: {port}")
-        print(f"  token: {mask_secret(remote_local_token(config))}")
+        print(f"  app id: {remote_local_app_id(config) or '<unset>'}")
+        print(f"  app key: {mask_secret(remote_local_app_key(config))}")
     print()
 
     if effective == "client":

ccode/remote_client.py

@@ -10,7 +10,7 @@ import time
 from typing import Any
 
 from .config import CONFIG_DIR, load_config
-from .remote_common import file_lock, http_to_ws_url, missing_extra_message, pid_from_path, remote_server_config, remote_server_url, rotate_log
+from .remote_common import build_auth_payload, file_lock, http_to_ws_url, missing_extra_message, pid_from_path, remote_server_app_id, remote_server_app_key, remote_server_config, remote_server_url, rotate_log
 
 REMOTE_CLIENT_LOCK_PATH = CONFIG_DIR / "remote_client.lock"
 REMOTE_CLIENT_PID_PATH = CONFIG_DIR / "remote_client.pid"
@@ -179,9 +179,9 @@ async def open_attach_socket(attach_id: str, session_id: str, config: dict[str,
     except ImportError:
         _log_event(missing_extra_message("remote-client", "websockets"))
         return
-    server = remote_server_config(config)
+    auth_payload = build_auth_payload(remote_server_app_id(config), remote_server_app_key(config), "client.attach")
     async with websockets.connect(_attach_url(config, attach_id), **_connect_kwargs(config)) as ws:
-        await ws.send(json.dumps({"type": "auth", "token": server.get("token") or "", "attach_id": attach_id}))
+        await ws.send(json.dumps({"type": "auth", **auth_payload, "attach_id": attach_id}))
         await attach_local_session_to_websocket(ws, session_id)
 
 
@@ -217,10 +217,11 @@ async def connect_control_loop(config: dict[str, Any]) -> None:
     from .remote import scan_remote_sessions
 
     running, _dead = scan_remote_sessions(prune=True)
+    auth_payload = build_auth_payload(remote_server_app_id(config), remote_server_app_key(config), "client.control")
     async with websockets.connect(_control_url(config), **_connect_kwargs(config)) as ws:
         await ws.send(json.dumps({
             "type": "hello",
-            "token": server.get("token") or "",
+            **auth_payload,
             "device_id": server.get("device_id") or "",
             "device_name": server.get("device_name") or "",
             "version": "0.2.0",
@@ -246,9 +247,8 @@ async def _run_loop(config: dict[str, Any]) -> None:
 def run_remote_client_forever(config: dict[str, Any]) -> str | None:
     if not remote_server_url(config):
         return "Remote server URL is required."
-    server = remote_server_config(config)
-    if not str(server.get("token") or "").strip():
-        return "Remote server client token is required."
+    if not remote_server_app_id(config).strip() or not remote_server_app_key(config).strip():
+        return "Remote server client app ID and app key are required."
     if remote_server_url(config).startswith("http://"):
         _log_event("warning: remote server URL uses plain HTTP/WS")
     try:

ccode/remote_common.py

@@ -1,16 +1,19 @@
 from __future__ import annotations
 
-import asyncio
+import base64
 import contextlib
 import datetime as dt
 import fcntl
-import json
+import hashlib
+import hmac
 import os
 import re
 import secrets
+import time
+from dataclasses import dataclass
 from importlib import resources
 from typing import Any, Iterator
-from urllib.parse import quote, urlparse
+from urllib.parse import urlencode, urlparse
 
 from .config import CONFIG_DIR
 
@@ -42,17 +45,25 @@ def remote_local_host_port(config: dict[str, Any]) -> tuple[str, int]:
     return host, port
 
 
-def remote_local_token(config: dict[str, Any]) -> str:
-    return str(remote_local_config(config).get("token") or "")
+def remote_local_app_id(config: dict[str, Any]) -> str:
+    return str(remote_local_config(config).get("appId") or "")
+
+
+def remote_local_app_key(config: dict[str, Any]) -> str:
+    return str(remote_local_config(config).get("appKey") or "")
+
+
+def remote_server_app_id(config: dict[str, Any]) -> str:
+    return str(remote_server_config(config).get("appId") or "")
+
+
+def remote_server_app_key(config: dict[str, Any]) -> str:
+    return str(remote_server_config(config).get("appKey") or "")
 
 
 def remote_local_url(config: dict[str, Any], include_token: bool = False) -> str:
     host, port = remote_local_host_port(config)
-    url = f"http://{host}:{port}/"
-    token = remote_local_token(config)
-    if include_token and token:
-        return f"{url}?token={quote(token)}"
-    return url
+    return f"http://{host}:{port}/"
 
 
 def remote_server_url(config: dict[str, Any]) -> str:
@@ -98,35 +109,81 @@ def _utc_now() -> str:
     return dt.datetime.now(dt.timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
 
 
-def token_matches(expected: str, provided: str | None) -> bool:
-    value = (provided or "").strip()
-    expected = (expected or "").strip()
-    return bool(value) and bool(expected) and secrets.compare_digest(value, expected)
+AUTH_MAX_AGE_SECONDS = 24 * 60 * 60
+AUTH_FUTURE_SKEW_SECONDS = 5 * 60
 
 
-def bearer_token(authorization: str | None) -> str | None:
-    if not authorization:
-        return None
-    scheme, _, value = authorization.partition(" ")
-    if scheme.lower() != "bearer":
-        return None
-    return value.strip() or None
+@dataclass(frozen=True)
+class AuthResult:
+    ok: bool
+    error: str = ""
+    message: str = ""
+
+
+AUTH_OK = AuthResult(True)
+
+
+def new_app_id() -> str:
+    return f"app_{secrets.token_urlsafe(9)}"
 
 
-def auth_token_matches(expected: str, token: str | None = None, authorization: str | None = None) -> bool:
-    return token_matches(expected, token) or token_matches(expected, bearer_token(authorization))
+def new_app_key() -> str:
+    return secrets.token_urlsafe(32)
 
 
-async def websocket_auth_token(websocket: Any) -> str | None:
+def _auth_message(app_id: str, timestamp: str, scope: str) -> bytes:
+    return f"v1\nappId={app_id}\ntimestamp={timestamp}\nscope={scope}".encode()
+
+
+def make_auth_signature(app_key: str, app_id: str, timestamp: str, scope: str) -> str:
+    digest = hmac.new(app_key.encode(), _auth_message(app_id, timestamp, scope), hashlib.sha256).digest()
+    return base64.urlsafe_b64encode(digest).decode("ascii").rstrip("=")
+
+
+def build_auth_payload(app_id: str, app_key: str, scope: str, timestamp: int | None = None) -> dict[str, str]:
+    timestamp_value = str(int(time.time() if timestamp is None else timestamp))
+    return {
+        "appId": app_id,
+        "timestamp": timestamp_value,
+        "sign": make_auth_signature(app_key, app_id, timestamp_value, scope),
+    }
+
+
+def auth_headers(payload: dict[str, str]) -> dict[str, str]:
+    return {
+        "X-CCODE-App-Id": payload.get("appId", ""),
+        "X-CCODE-Timestamp": payload.get("timestamp", ""),
+        "X-CCODE-Sign": payload.get("sign", ""),
+    }
+
+
+def auth_query(payload: dict[str, str]) -> str:
+    return urlencode({"appId": payload.get("appId", ""), "timestamp": payload.get("timestamp", ""), "sign": payload.get("sign", "")})
+
+
+def verify_auth_payload(expected_app_id: str, expected_app_key: str, payload: dict[str, Any], scope: str) -> AuthResult:
+    app_id = str(payload.get("appId") or "").strip()
+    timestamp = str(payload.get("timestamp") or "").strip()
+    sign = str(payload.get("sign") or "").strip()
+    expected_app_id = (expected_app_id or "").strip()
+    expected_app_key = (expected_app_key or "").strip()
+    if not expected_app_id or not expected_app_key or not app_id or not timestamp or not sign:
+        return AuthResult(False, "auth_required", "Authentication required.")
+    if not hmac.compare_digest(expected_app_id, app_id):
+        return AuthResult(False, "auth_failed", "Authentication failed.")
     try:
-        raw = await asyncio.wait_for(websocket.receive_text(), timeout=10)
-        payload = json.loads(raw)
-    except (asyncio.TimeoutError, json.JSONDecodeError):
-        return None
-    if payload.get("type") != "auth":
-        return None
-    token = payload.get("token")
-    return token if isinstance(token, str) else None
+        timestamp_int = int(timestamp)
+    except ValueError:
+        return AuthResult(False, "auth_required", "Invalid authentication timestamp.")
+    age = int(time.time()) - timestamp_int
+    if age > AUTH_MAX_AGE_SECONDS:
+        return AuthResult(False, "reauth_required", "Authentication expired, please re-authenticate.")
+    if age < -AUTH_FUTURE_SKEW_SECONDS:
+        return AuthResult(False, "auth_failed", "Authentication timestamp is invalid.")
+    expected_sign = make_auth_signature(expected_app_key, app_id, timestamp, scope)
+    if not hmac.compare_digest(expected_sign, sign):
+        return AuthResult(False, "auth_failed", "Authentication failed.")
+    return AUTH_OK
 
 
 _ASSET_TEXT_CACHE: dict[str, str] = {}

ccode/remote_server.py

@@ -8,7 +8,7 @@ import time
 from dataclasses import dataclass, field
 from typing import Any
 
-from .remote_common import asset_text, auth_token_matches, missing_extra_message, token_matches, web_asset_text, websocket_auth_token
+from .remote_common import AuthResult, asset_text, missing_extra_message, verify_auth_payload, web_asset_text
 
 REMOTE_SERVER_NAME = "ccode-remote-server"
 ATTACH_TTL_SECONDS = 30
@@ -41,22 +41,33 @@ _PENDING_ATTACHES: dict[str, PendingAttach] = {}
 DEVICE_OFFLINE_TTL_SECONDS = 24 * 60 * 60
 
 
-def _admin_token() -> str:
-    return os.environ.get("CCODE_REMOTE_SERVER_ADMIN_TOKEN", "").strip()
+def _admin_app_id() -> str:
+    return os.environ.get("CCODE_REMOTE_SERVER_ADMIN_APP_ID", "").strip()
 
 
-def _client_token() -> str:
-    return os.environ.get("CCODE_REMOTE_SERVER_CLIENT_TOKEN", "").strip()
+def _admin_app_key() -> str:
+    return os.environ.get("CCODE_REMOTE_SERVER_ADMIN_APP_KEY", "").strip()
 
 
-def _valid_admin(token: str | None = None, authorization: str | None = None) -> bool:
-    expected = _admin_token()
-    return bool(expected) and auth_token_matches(expected, token, authorization)
+def _client_app_id() -> str:
+    return os.environ.get("CCODE_REMOTE_SERVER_CLIENT_APP_ID", "").strip()
 
 
-def _valid_client(token: str | None) -> bool:
-    expected = _client_token()
-    return bool(expected) and token_matches(expected, token)
+def _client_app_key() -> str:
+    return os.environ.get("CCODE_REMOTE_SERVER_CLIENT_APP_KEY", "").strip()
+
+
+def _valid_admin(payload: dict[str, Any], scope: str) -> AuthResult:
+    return verify_auth_payload(_admin_app_id(), _admin_app_key(), payload, scope)
+
+
+def _valid_client(payload: dict[str, Any], scope: str) -> AuthResult:
+    return verify_auth_payload(_client_app_id(), _client_app_key(), payload, scope)
+
+
+def _auth_response(result: AuthResult, response_class: Any) -> Any:
+    status_code = 401 if result.error in {"auth_required", "reauth_required"} else 403
+    return response_class({"error": result.error or "auth_failed", "message": result.message}, status_code=status_code)
 
 
 def _device_payload(device: DeviceConnection) -> dict[str, Any]:
@@ -168,25 +179,42 @@ def create_server_app() -> Any:
     @app.get("/health")
     async def health() -> dict[str, Any]:
         _prune_offline_devices()
-        return {"ok": True, "name": REMOTE_SERVER_NAME, "devices": len(_DEVICES)}
+        return {"ok": True, "name": REMOTE_SERVER_NAME, "devices": len(_DEVICES), "remote_kind": "server"}
 
     @app.get("/api/devices")
-    async def devices(token: str | None = None, authorization: str | None = Header(default=None)) -> Response:
-        if not _valid_admin(token, authorization):
-            return JSONResponse({"error": "unauthorized"}, status_code=401)
+    async def devices(
+        x_ccode_app_id: str | None = Header(default=None),
+        x_ccode_timestamp: str | None = Header(default=None),
+        x_ccode_sign: str | None = Header(default=None),
+    ) -> Response:
+        auth_result = _valid_admin({"appId": x_ccode_app_id, "timestamp": x_ccode_timestamp, "sign": x_ccode_sign}, "server.api")
+        if not auth_result.ok:
+            return _auth_response(auth_result, JSONResponse)
         _prune_offline_devices()
         return JSONResponse({"devices": [_device_payload(device) for device in _DEVICES.values()]})
 
     @app.get("/api/sessions")
-    async def sessions(token: str | None = None, authorization: str | None = Header(default=None)) -> Response:
-        if not _valid_admin(token, authorization):
-            return JSONResponse({"error": "unauthorized"}, status_code=401)
+    async def sessions(
+        x_ccode_app_id: str | None = Header(default=None),
+        x_ccode_timestamp: str | None = Header(default=None),
+        x_ccode_sign: str | None = Header(default=None),
+    ) -> Response:
+        auth_result = _valid_admin({"appId": x_ccode_app_id, "timestamp": x_ccode_timestamp, "sign": x_ccode_sign}, "server.api")
+        if not auth_result.ok:
+            return _auth_response(auth_result, JSONResponse)
         return JSONResponse({"sessions": _flatten_sessions()})
 
     @app.get("/api/devices/{device_id}/sessions/{session_id}")
-    async def session_detail(device_id: str, session_id: str, token: str | None = None, authorization: str | None = Header(default=None)) -> Response:
-        if not _valid_admin(token, authorization):
-            return JSONResponse({"error": "unauthorized"}, status_code=401)
+    async def session_detail(
+        device_id: str,
+        session_id: str,
+        x_ccode_app_id: str | None = Header(default=None),
+        x_ccode_timestamp: str | None = Header(default=None),
+        x_ccode_sign: str | None = Header(default=None),
+    ) -> Response:
+        auth_result = _valid_admin({"appId": x_ccode_app_id, "timestamp": x_ccode_timestamp, "sign": x_ccode_sign}, "server.api")
+        if not auth_result.ok:
+            return _auth_response(auth_result, JSONResponse)
         device, session = _get_device_session(device_id, session_id)
         if device is None or session is None:
             return JSONResponse({"error": "not_found"}, status_code=404)
@@ -201,7 +229,9 @@ def create_server_app() -> Any:
         except (asyncio.TimeoutError, json.JSONDecodeError):
             await websocket.close(code=1008)
             return
-        if hello.get("type") != "hello" or not _valid_client(hello.get("token") if isinstance(hello.get("token"), str) else None):
+        auth_result = _valid_client(hello, "client.control")
+        if hello.get("type") != "hello" or not auth_result.ok:
+            await websocket.send_json({"type": "error", "error": auth_result.error or "auth_failed", "message": auth_result.message})
             await websocket.close(code=1008)
             return
         device_id = str(hello.get("device_id") or secrets.token_urlsafe(16))
@@ -237,8 +267,15 @@ def create_server_app() -> Any:
         await websocket.accept()
         _prune_pending()
         pending = _PENDING_ATTACHES.get(attach_id)
-        token = await websocket_auth_token(websocket)
-        if pending is None or not _valid_client(token):
+        try:
+            raw = await asyncio.wait_for(websocket.receive_text(), timeout=10)
+            payload = json.loads(raw)
+        except (asyncio.TimeoutError, json.JSONDecodeError):
+            await websocket.close(code=1008)
+            return
+        auth_result = _valid_client(payload, "client.attach")
+        if pending is None or payload.get("type") != "auth" or not auth_result.ok:
+            await websocket.send_json({"type": "error", "error": auth_result.error or "auth_failed", "message": auth_result.message})
             await websocket.close(code=1008)
             return
         pending.client_ws = websocket
@@ -249,9 +286,9 @@ def create_server_app() -> Any:
     @app.websocket("/ws/devices/{device_id}/sessions/{session_id}")
     async def browser_attach(websocket: FastAPIWebSocket, device_id: str, session_id: str) -> None:
         await websocket.accept()
-        token = await websocket_auth_token(websocket)
-        if not _valid_admin(token):
-            await websocket.send_json({"type": "status", "message": "unauthorized: invalid token"})
+        auth_result = _valid_admin(dict(websocket.query_params), "server.ws")
+        if not auth_result.ok:
+            await websocket.send_json({"type": "error", "error": auth_result.error, "message": auth_result.message})
             await websocket.close(code=1008)
             return
         device, session = _get_device_session(device_id, session_id)