pairling 0.0.1 → 0.1.0

package/payload/mac/companiond/request_proof.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Request-bound HMAC proof verification for mutating Pairling endpoints."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from dataclasses import dataclass
+from typing import Any
+
+
+INSTALL_ID_HEADER = "Pairling-Install-ID"
+REQUEST_ID_HEADER = "Pairling-Request-ID"
+TIMESTAMP_HEADER = "Pairling-Timestamp"
+BODY_SHA256_HEADER = "Pairling-Body-SHA256"
+PROOF_HEADER = "Pairling-Proof"
+SKEW_MS = 10 * 60 * 1000
+
+
+@dataclass(frozen=True)
+class ProofVerificationResult:
+    ok: bool
+    status: int = 200
+    code: str = "ok"
+    message: str = "ok"
+
+
+class ReplayCache:
+    def __init__(self, *, retention_seconds: int = 600, max_entries: int = 4096):
+        self.retention_seconds = retention_seconds
+        self.max_entries = max_entries
+        self._seen: dict[tuple[str, str], float] = {}
+
+    def check_and_store(self, *, device_id: str, request_id: str, now: float | None = None) -> bool:
+        current = time.time() if now is None else now
+        cutoff = current - self.retention_seconds
+        if len(self._seen) > self.max_entries:
+            self._seen = {
+                key: ts for key, ts in self._seen.items()
+                if ts >= cutoff
+            }
+        key = (device_id, request_id)
+        if key in self._seen and self._seen[key] >= cutoff:
+            return False
+        self._seen[key] = current
+        return True
+
+
+def body_sha256_hex(body: bytes) -> str:
+    return hashlib.sha256(body).hexdigest()
+
+
+def canonical_request(
+    *,
+    method: str,
+    path_and_query: str,
+    timestamp_ms: str,
+    request_id: str,
+    body_sha256: str,
+    install_id: str,
+    device_id: str,
+) -> str:
+    return "\n".join([
+        method.upper(),
+        path_and_query,
+        timestamp_ms,
+        request_id,
+        body_sha256,
+        install_id,
+        device_id,
+    ])
+
+
+def proof_hex(*, secret: str, canonical: str) -> str:
+    return hmac.new(
+        secret.encode("utf-8"),
+        canonical.encode("utf-8"),
+        hashlib.sha256,
+    ).hexdigest()
+
+
+def verify_request_proof(
+    *,
+    headers: Any,
+    method: str,
+    path_and_query: str,
+    body: bytes,
+    auth_result: Any,
+    local_install_id: str,
+    replay_cache: ReplayCache,
+    now_ms: int | None = None,
+) -> ProofVerificationResult:
+    proof_secret = str(getattr(auth_result, "proof_secret", "") or "").strip()
+    if not proof_secret:
+        return ProofVerificationResult(False, 403, "missing_proof_secret", "Pair this Mac again to enable request proof.")
+
+    install_id = _header(headers, INSTALL_ID_HEADER)
+    request_id = _header(headers, REQUEST_ID_HEADER)
+    timestamp_ms = _header(headers, TIMESTAMP_HEADER)
+    body_hash = _header(headers, BODY_SHA256_HEADER)
+    proof = _header(headers, PROOF_HEADER)
+
+    if not install_id or not request_id or not timestamp_ms or not body_hash or not proof:
+        return ProofVerificationResult(False, 401, "missing_proof", "Request proof headers are required.")
+    if install_id != local_install_id:
+        return ProofVerificationResult(False, 403, "install_id_mismatch", "Request proof was for a different Mac.")
+    try:
+        parsed_ts = int(timestamp_ms)
+    except ValueError:
+        return ProofVerificationResult(False, 401, "bad_timestamp", "Request proof timestamp is invalid.")
+    current_ms = int(time.time() * 1000) if now_ms is None else now_ms
+    if abs(current_ms - parsed_ts) > SKEW_MS:
+        return ProofVerificationResult(False, 401, "stale_timestamp", "Request proof timestamp is stale.")
+
+    expected_body_hash = body_sha256_hex(body)
+    if not hmac.compare_digest(body_hash.lower(), expected_body_hash):
+        return ProofVerificationResult(False, 401, "body_hash_mismatch", "Request body hash does not match.")
+
+    device_id = str(getattr(auth_result, "device_id", "") or "")
+    canonical = canonical_request(
+        method=method,
+        path_and_query=path_and_query,
+        timestamp_ms=timestamp_ms,
+        request_id=request_id,
+        body_sha256=expected_body_hash,
+        install_id=install_id,
+        device_id=device_id,
+    )
+    expected_proof = proof_hex(secret=proof_secret, canonical=canonical)
+    if not hmac.compare_digest(proof.lower(), expected_proof):
+        return ProofVerificationResult(False, 401, "bad_proof", "Request proof did not verify.")
+    if not replay_cache.check_and_store(device_id=device_id, request_id=request_id, now=current_ms / 1000):
+        return ProofVerificationResult(False, 409, "replayed_request", "Request proof was already used.")
+    return ProofVerificationResult(True)
+
+
+def _header(headers: Any, name: str) -> str:
+    try:
+        return str(headers.get(name, "") or "").strip()
+    except AttributeError:
+        return str((headers or {}).get(name, "") or "").strip()

package/payload/mac/companiond/runtime_contract.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""Shared constants for the Pairling Mac runtime."""
+
+from __future__ import annotations
+
+import os
+
+SCHEMA_VERSION = 1
+POWER_STATE_SCHEMA_VERSION = 1
+RUNTIME_NAME = "pairling-mac-runtime"
+CONTRACT_VERSION = "pairling-runtime-v1"
+PAIRLING_CONTRACT_VERSION = CONTRACT_VERSION
+COMPAT_MODE = "pairling-v1"
+PORT = int(os.environ.get("PAIRLING_RUNTIME_PORT", "7773"))
+LEGACY_PORT = 7723
+DAEMON_LABEL = "dev.pairling.companiond"
+GUARDIAN_LABEL = "dev.pairling.power-guardian"
+LEGACY_DAEMON_LABEL = "com.mghome.notify-webhook"
+LEGACY_GUARDIAN_LABEL = "com.mghome.companion-power-guardian"
+LEGACY_TOKEN_RELATIVE_PATH = ".claude/scripts/.notify-token"
+POWER_STATE_PATH = "/var/run/pairling-power-state.json"
+TAILSCALE_VARIANT = "standalone"
+AUTH_MODE = "scoped-device-bearer"
+PAIR_SERVICE_TYPE = "_pairling-pair._tcp"
+RUNTIME_BONJOUR_ADVERTISED = False
+
+DEFAULT_DEVICE_SCOPES = frozenset({
+    "health:read",
+    "manifest:read",
+    "sessions:read",
+    "transcript:read",
+    "session:send",
+    "session:spawn",
+    "session:signal",
+    "worker:read",
+    "worker:control",
+    "llm:route",
+    "pairling-tools:run",
+    "files:upload",
+    "files:read",
+    "files:write",
+    "files:delete",
+    "pair:admin",
+    "phone-tools:reverse",
+})
+
+SUPPORTED_CONTRACTS = {CONTRACT_VERSION}

package/payload/mac/companiond/runtime_manifest.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""Runtime manifest loading and verification for the Mac companion daemon."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from runtime_contract import (
+    AUTH_MODE,
+    COMPAT_MODE,
+    CONTRACT_VERSION,
+    DAEMON_LABEL,
+    PAIR_SERVICE_TYPE,
+    PORT,
+    RUNTIME_BONJOUR_ADVERTISED,
+    RUNTIME_NAME,
+    TAILSCALE_VARIANT,
+)
+from runtime_paths import release_root_for
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def utc_now_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def load_manifest_for(script_path: str | Path) -> tuple[dict[str, Any] | None, Path | None, str | None]:
+    root = release_root_for(script_path)
+    if root is None:
+        return None, None, "manifest not found for script path"
+    path = root / "manifest.json"
+    try:
+        data = json.loads(path.read_text())
+    except Exception as exc:
+        return None, path, f"{type(exc).__name__}: {exc}"
+    if not isinstance(data, dict):
+        return None, path, "manifest root is not an object"
+    return data, path, None
+
+
+def _manifest_file_hash(manifest: dict[str, Any], relative_path: str) -> str | None:
+    for item in manifest.get("files") or []:
+        if isinstance(item, dict) and item.get("path") == relative_path:
+            value = item.get("sha256")
+            return value if isinstance(value, str) else None
+    return None
+
+
+def build_runtime_info(
+    script_path: str | Path,
+    *,
+    relative_path: str = "companiond/pairlingd.py",
+    launchd_label: str = DAEMON_LABEL,
+) -> dict[str, Any]:
+    script = Path(script_path).resolve()
+    manifest, manifest_path, manifest_error = load_manifest_for(script)
+    runtime_version = os.environ.get("COMPANION_RUNTIME_VERSION", "legacy")
+    source_revision = os.environ.get("COMPANION_SOURCE_REVISION", "unknown")
+    source_branch = os.environ.get("COMPANION_SOURCE_BRANCH", "unknown")
+    source_dirty = None
+    installed_at = os.environ.get("COMPANION_INSTALLED_AT")
+    install_root = str(script.parent.parent) if script.parent.name in {"companiond", "guardian"} else str(script.parent)
+    source_hash = None
+    verified = False
+    verification_error = manifest_error
+
+    try:
+        source_hash = sha256_file(script)
+    except Exception as exc:
+        verification_error = f"{type(exc).__name__}: {exc}"
+
+    if manifest:
+        runtime_version = str(manifest.get("runtime_version") or runtime_version)
+        source_revision = str(manifest.get("source_revision") or source_revision)
+        source_branch = str(manifest.get("source_branch") or source_branch)
+        if "source_dirty" in manifest:
+            source_dirty = bool(manifest.get("source_dirty"))
+        installed_at = str(manifest.get("installed_at") or installed_at or "")
+        install_root = str(manifest.get("install_root") or install_root)
+        expected_hash = _manifest_file_hash(manifest, relative_path)
+        if expected_hash and source_hash:
+            verified = expected_hash == source_hash
+            if not verified:
+                verification_error = f"hash mismatch for {relative_path}"
+        else:
+            verification_error = f"manifest missing hash for {relative_path}"
+
+    return {
+        "name": RUNTIME_NAME,
+        "runtime_version": runtime_version,
+        "contract_version": CONTRACT_VERSION,
+        "source_revision": source_revision,
+        "source_branch": source_branch,
+        "source_dirty": source_dirty,
+        "installed_at": installed_at or None,
+        "install_root": install_root,
+        "compat_mode": COMPAT_MODE,
+        "launchd_label": launchd_label,
+        "port": PORT,
+        "tailscale_variant": TAILSCALE_VARIANT,
+        "verified": verified,
+        "source_hash": source_hash,
+        "manifest_path": str(manifest_path) if manifest_path else None,
+        "manifest_error": verification_error,
+    }
+
+
+def public_runtime_info(info: dict[str, Any]) -> dict[str, Any]:
+    """Return the unauthenticated-safe subset of runtime metadata."""
+    return {
+        "name": info.get("name") or RUNTIME_NAME,
+        "runtime_version": info.get("runtime_version"),
+        "contract_version": info.get("contract_version") or CONTRACT_VERSION,
+        "compat_mode": info.get("compat_mode") or COMPAT_MODE,
+        "launchd_label": info.get("launchd_label") or DAEMON_LABEL,
+        "port": info.get("port") or PORT,
+        "tailscale_variant": info.get("tailscale_variant") or TAILSCALE_VARIANT,
+        "verified": bool(info.get("verified")),
+    }
+
+
+def build_manifest_payload(
+    runtime_info: dict[str, Any],
+    *,
+    authenticated: bool,
+    device_id: str | None = None,
+    scopes: list[str] | None = None,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "ok": True,
+        "schema_version": 1,
+        "contract_version": CONTRACT_VERSION,
+        "runtime": public_runtime_info(runtime_info),
+        "auth": {
+            "mode": AUTH_MODE,
+            "required": True,
+            "legacy_global_token": False,
+            "authenticated": authenticated,
+        },
+        "network": {
+            "runtime_port": PORT,
+            "pair_service_type": PAIR_SERVICE_TYPE,
+            "runtime_bonjour_advertised": RUNTIME_BONJOUR_ADVERTISED,
+            "route_diagnostics": {
+                "bonjour": {
+                    "service_type": PAIR_SERVICE_TYPE,
+                    "runtime_port": PORT,
+                    "txt_version": "2",
+                },
+                "tailnet": {
+                    "variant": TAILSCALE_VARIANT,
+                },
+            },
+        },
+        "endpoints": {
+            "public": ["/health", "/manifest", "/pair/start", "/pair/claim"],
+            "authenticated": [
+                "/manifest",
+                "/sessions",
+                "/sessions-stream",
+                "/session-live-events",
+                "/transcript",
+                "/transcript-stream",
+                "/send-text",
+                "/inject-now",
+                "/worker-kill",
+                "/pairling-tools/run",
+                "/phone-tools/availability",
+                "/phone-tools/next",
+                "/phone-tools/result",
+                "/sentinel/status",
+                "/sentinel/preferences",
+                "/sentinel/snooze",
+                "/sentinel/evaluate-now",
+                "/sentinel/events",
+                "/pair/revoke",
+                "/pair/rotate-token",
+            ],
+        },
+    }
+    if authenticated:
+        payload["runtime"] = runtime_info
+        payload["auth"]["device_id"] = device_id
+        payload["auth"]["scopes"] = sorted(scopes or [])
+    return payload

package/payload/mac/companiond/runtime_paths.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Path resolver for the Pairling runtime."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from runtime_contract import LEGACY_TOKEN_RELATIVE_PATH, POWER_STATE_PATH
+
+
+def home() -> Path:
+    return Path.home()
+
+
+def app_support_root() -> Path:
+    return Path(
+        os.environ.get(
+            "PAIRLING_APP_SUPPORT_ROOT",
+            os.environ.get(
+                "COMPANION_APP_SUPPORT_ROOT",
+                str(home() / "Library" / "Application Support" / "Pairling"),
+            ),
+        )
+    )
+
+
+def logs_root() -> Path:
+    return Path(
+        os.environ.get(
+            "PAIRLING_LOGS_ROOT",
+            os.environ.get(
+                "COMPANION_LOGS_ROOT",
+                str(home() / "Library" / "Logs" / "Pairling"),
+            ),
+        )
+    )
+
+
+def runtime_root() -> Path:
+    return app_support_root() / "runtime"
+
+
+def current_release() -> Path:
+    return runtime_root() / "current"
+
+
+def state_root() -> Path:
+    return app_support_root() / "state"
+
+
+def install_history_path() -> Path:
+    return state_root() / "install-history.jsonl"
+
+
+def install_id_path() -> Path:
+    return state_root() / "install-id"
+
+
+def devices_db_path() -> Path:
+    return app_support_root() / "devices.sqlite"
+
+
+def audit_log_path() -> Path:
+    return logs_root() / "audit.jsonl"
+
+
+def token_path() -> Path:
+    return Path(os.environ.get("NOTIFY_TOKEN_FILE", str(home() / LEGACY_TOKEN_RELATIVE_PATH)))
+
+
+def guardian_state_path() -> Path:
+    return Path(os.environ.get("COMPANION_POWER_STATE_PATH", POWER_STATE_PATH))
+
+
+def legacy_scripts_root() -> Path:
+    return home() / ".claude" / "scripts"
+
+
+def release_root_for(script_path: str | Path) -> Path | None:
+    path = Path(script_path).resolve()
+    parent = path.parent
+    if parent.name in {"companiond", "guardian"}:
+        root = parent.parent
+        if (root / "manifest.json").is_file():
+            return root
+    return None