pairling 0.2.0 → 0.2.2

package/payload/mac/companiond/pairling_pairing.py

@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+import base64
 import json
 import os
 import secrets
@@ -30,12 +31,113 @@ except Exception:
     RelayClaimError = None
     RelayClaimVerifier = None
 
+try:
+    from app_attest_lan import direct_attest_required as _direct_attest_required
+    from app_attest_lan import verify_attestation as _verify_direct_attestation
+except Exception:
+    def _direct_attest_required() -> bool:
+        return False
+    _verify_direct_attestation = None
+
+try:
+    import pairling_psk as _psk
+except Exception:
+    _psk = None
+
+
+def _psk_required() -> bool:
+    # PSK-authenticated ECDH is the only MITM-safe pairing path, so it is REQUIRED by
+    # default. Only an explicit opt-out ("0"/"false"/"no"/"off") permits the legacy
+    # plaintext /pair/claim — used by contract tests that exercise the legacy branch on
+    # purpose, and as a break-glass if the crypto module is ever unavailable.
+    return os.environ.get("PAIRLING_PSK_REQUIRED", "on").strip().lower() not in {"0", "false", "no", "off"}
+
+
+# Boot-time hard-dependency assertion. With PSK required by default, the cryptography
+# module (imported by pairling_psk) is a hard runtime dependency: if it failed to import,
+# fail LOUD here at daemon startup instead of silently returning 503 from every
+# /pair/psk-claim while legacy is closed — which would brick pairing entirely. Set
+# PAIRLING_PSK_REQUIRED=0 to fall back to legacy plaintext pairing when crypto is absent.
+if _psk is None and _psk_required():
+    raise RuntimeError(
+        "Pairling pairing requires the 'cryptography' package (pairling_psk failed to "
+        "import) because PAIRLING_PSK_REQUIRED is on by default. Install cryptography, or "
+        "set PAIRLING_PSK_REQUIRED=0 to permit the legacy plaintext claim."
+    )
+
 
 DEFAULT_PAIR_TTL_SECONDS = 180
 MIN_PAIR_TTL_SECONDS = 60
 MAX_PAIR_TTL_SECONDS = 300
 
 
+def _nonce_required() -> bool:
+    return os.environ.get("PAIRLING_NONCE_REQUIRED", "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def verify_p256_signature(point_b64: str, message: bytes, signature_der: bytes) -> bool:
+    """Verify an ECDSA-P256-SHA256 signature from the iOS Secure Enclave.
+
+    point_b64 is the base64 X9.63 public key (04 || X || Y) returned by
+    SecKeyCopyExternalRepresentation; signature_der is the DER (X9.62) ECDSA
+    signature from SecKeyCreateSignature(.ecdsaSignatureMessageX962SHA256).
+    Constant-time / exception-safe: any malformed input returns False.
+    """
+    try:
+        from cryptography.exceptions import InvalidSignature
+        from cryptography.hazmat.primitives import hashes
+        from cryptography.hazmat.primitives.asymmetric import ec
+    except Exception:
+        return False
+    if not point_b64 or not signature_der:
+        return False
+    try:
+        point = base64.b64decode(point_b64)
+        public_key = ec.EllipticCurvePublicKey.from_encoded_point(ec.SECP256R1(), point)
+        public_key.verify(signature_der, message, ec.ECDSA(hashes.SHA256()))
+        return True
+    except (InvalidSignature, ValueError, TypeError):
+        return False
+
+
+class ReauthStore:
+    """WS4: short-lived per-device challenges for zero-interaction re-pair.
+
+    A challenge is issued for ANY device_id (even unknown) so the endpoint is
+    not a device-existence oracle. Verification fails uniformly when the device
+    is unknown, revoked, has no SE key, or the signature does not check out.
+    """
+
+    def __init__(self, registry: DeviceRegistry, *, ttl_seconds: int = 120):
+        self.registry = registry
+        self.ttl_seconds = ttl_seconds
+        self._lock = threading.Lock()
+        self._challenges: dict[str, tuple[str, float]] = {}
+
+    def issue_challenge(self, device_id: str) -> str:
+        challenge = secrets.token_hex(32)
+        with self._lock:
+            self._challenges[device_id] = (challenge, time.time() + self.ttl_seconds)
+        return challenge
+
+    def verify_and_consume(self, device_id: str, challenge: str, signature_der: bytes) -> bool:
+        # Single-use: pop regardless of outcome so a captured challenge cannot
+        # be replayed even if the first signature was wrong.
+        with self._lock:
+            entry = self._challenges.pop(device_id, None)
+        if entry is None:
+            return False
+        stored_challenge, expires_at = entry
+        if time.time() > expires_at:
+            return False
+        if not secrets.compare_digest(stored_challenge, challenge or ""):
+            return False
+        point_b64 = self.registry.get_se_pubkey(device_id)
+        if not point_b64:
+            return False
+        return verify_p256_signature(point_b64, challenge.encode("ascii"), signature_der)
+
+
 @dataclass(frozen=True)
 class PairStart:
     pair_id: str
@@ -44,6 +146,9 @@ class PairStart:
     install_id: str
     service_type: str
     txt: dict[str, str]
+    pairing_nonce: str = ""
+    attest_challenge: str = ""
+    mac_ake_pub: str = ""
 
 
 @dataclass(frozen=True)
@@ -78,6 +183,10 @@ class PairingStore:
         self.runtime_port = runtime_port
         self.install_id = install_id or self._load_install_id_from_config()
         self._claim_lock = threading.Lock()
+        # P0-B: per-pair_id wrong-guess counter, pre-checked before secret
+        # comparison so a racing attacker cannot brute the secret/nonce.
+        # In-process only; the pair_id TTL is the outer bound on staleness.
+        self._claim_attempts: dict[str, int] = {}
 
     def _computer_name(self) -> str:
         try:
@@ -153,10 +262,33 @@ class PairingStore:
         ttl = max(MIN_PAIR_TTL_SECONDS, min(int(ttl_seconds), MAX_PAIR_TTL_SECONDS))
         pair_id = "pair_" + secrets.token_hex(8)
         secret = secrets.token_urlsafe(24)
+        # P0-A: the nonce now lives in the on-disk record (it used to be
+        # generated only into the Bonjour TXT, so claim_pair() could never
+        # verify it). Both the Bonjour TXT and the QR claim payload carry it,
+        # so either path can present it back.
+        pairing_nonce = secrets.token_urlsafe(9)
+        # WS2: per-invitation App Attest challenge. The iOS app binds its
+        # attestation to canonical(pair_id, attest_challenge); the Mac verifies
+        # against this stored value, so a MITM cannot swap it (Blocker #6).
+        attest_challenge = secrets.token_hex(32)
+        # WS3: per-invitation Mac ephemeral ECDH key. A_pub goes in the OOB
+        # payload (QR/paste); the private half is stored in this mode-600 record
+        # so the claim can run a PSK-authenticated ECDH and the secret is never
+        # transmitted. Absent when the crypto module is unavailable (legacy only).
+        mac_ake_pub = ""
+        mac_ake_priv_b64 = ""
+        if _psk is not None:
+            _ake_priv, _ake_pub = _psk.mac_keygen()
+            mac_ake_pub = base64.urlsafe_b64encode(_ake_pub).rstrip(b"=").decode("ascii")
+            mac_ake_priv_b64 = base64.b64encode(_psk.dump_private(_ake_priv)).decode("ascii")
         expires_at = time.time() + ttl
         record = {
             "pair_id": pair_id,
             "secret": secret,
+            "pairing_nonce": pairing_nonce,
+            "attest_challenge": attest_challenge,
+            "mac_ake_pub": mac_ake_pub,
+            "mac_ake_priv": mac_ake_priv_b64,
             "created_at": time.time(),
             "expires_at": expires_at,
             "claimed_at": None,
@@ -185,10 +317,13 @@ class PairingStore:
             "mac_name": self._computer_name(),
             "mac_model": self._mac_model(),
             "runtime_version": self._runtime_version(),
-            "pairing_nonce": secrets.token_urlsafe(9),
+            "pairing_nonce": pairing_nonce,
             "route_hint": os.environ.get("PAIRLING_ROUTE_HINT", "lan,bonjour,tailnet")[:64],
         }
-        return PairStart(pair_id, secret, expires_at, self.install_id, PAIR_SERVICE_TYPE, txt)
+        return PairStart(
+            pair_id, secret, expires_at, self.install_id, PAIR_SERVICE_TYPE, txt,
+            pairing_nonce, attest_challenge, mac_ake_pub,
+        )
 
     def _load_record(self, pair_id: str) -> tuple[dict, Path]:
         path = self._record_path(pair_id)
@@ -211,87 +346,249 @@ class PairingStore:
         host_chain: Iterable[str],
         scopes: Iterable[str] | None = None,
         cert_pin: str | None = None,
+        pairing_nonce: str = "",
+        se_public_key_der: str = "",
+        attest_object: dict | None = None,
+        attest_key_id: str = "",
+        attest_environment: str = "",
         attested_claim_ticket: str | None = None,
         relay_device_id: str | None = None,
         relay_required: bool = False,
         relay_claim_verifier=None,
     ) -> PairClaim:
         with self._claim_lock:
-            record, path = self._load_record(pair_id)
-            now = time.time()
-            if record.get("claimed_at") is not None:
-                raise PairingError("pair_already_claimed", 409, "pair record already claimed")
-            if now > float(record.get("expires_at") or 0):
-                self._delete_record(path)
-                raise PairingError("pair_expired", 410, "pair record expired")
+            record, path, now = self._precheck_claim(pair_id)
+            # WS3: once PSK pairing is mandatory, reject legacy plaintext-secret
+            # claims outright — the secret must never cross the wire. New clients
+            # use /pair/psk-claim instead.
+            if _psk_required():
+                raise PairingError("psk_required", 403, "psk-authenticated pairing required")
             if not secrets.compare_digest(str(record.get("secret") or ""), secret or ""):
                 raise PairingError("invalid_secret", 403, "invalid pair secret")
-            relay_status = "none"
-            verified_relay_device_id = relay_device_id
-            relay_pair_secret = None
-            relay_pair_secret_ref = None
-            if relay_required or attested_claim_ticket:
-                if not attested_claim_ticket:
-                    raise PairingError("attested_claim_required", 403, "relay claim ticket required")
-                if relay_claim_verifier is None:
-                    raise PairingError("attested_claim_invalid", 403, "relay claim verifier unavailable")
-                try:
-                    verification = relay_claim_verifier.verify(
-                        attested_claim_ticket,
-                        pair_id=pair_id,
-                        relay_device_id=relay_device_id,
-                        device_name=device_name,
-                    )
-                except Exception as exc:
-                    code = getattr(exc, "code", "attested_claim_invalid")
-                    message = getattr(exc, "message", str(exc))
-                    raise PairingError(code, 403, message)
-                verified_relay_device_id = verification.relay_device_id
-                relay_status = verification.attestation_status
-                relay_pair_secret = getattr(verification, "relay_pair_secret", None)
-                relay_pair_secret_ref = getattr(verification, "relay_pair_secret_ref", None)
-            normalized_hosts = tuple(h for h in host_chain if isinstance(h, str) and h)
-            if not normalized_hosts:
-                raise PairingError("missing_host_chain", 500, "host chain is empty")
-            marker = self._create_claim_marker(pair_id)
+            # P0-A: nonce gate (default off via PAIRLING_NONCE_REQUIRED). Both
+            # the QR claim payload and the Bonjour TXT carry pairing_nonce, so
+            # legitimate claims on either path present it; an attacker who only
+            # hit /pair/start blind (never saw the TXT/QR) cannot.
+            if _nonce_required():
+                if not secrets.compare_digest(str(record.get("pairing_nonce") or ""), pairing_nonce or ""):
+                    raise PairingError("invalid_pairing_nonce", 403, "invalid pairing nonce")
+            return self._finalize_claim(
+                pair_id=pair_id, record=record, path=path, now=now,
+                device_name=device_name, host_chain=host_chain, scopes=scopes,
+                cert_pin=cert_pin, se_public_key_der=se_public_key_der,
+                attest_object=attest_object, attest_key_id=attest_key_id,
+                attest_environment=attest_environment,
+                attested_claim_ticket=attested_claim_ticket,
+                relay_device_id=relay_device_id, relay_required=relay_required,
+                relay_claim_verifier=relay_claim_verifier,
+            )
+
+    def _precheck_claim(self, pair_id: str) -> tuple[dict, Path, float]:
+        """Shared front-matter for both claim paths (caller holds _claim_lock):
+        load the record, reject already-claimed/expired, and pre-increment the
+        per-pair_id attempt counter so wrong guesses lock out after 5 (P0-B)."""
+        record, path = self._load_record(pair_id)
+        now = time.time()
+        if record.get("claimed_at") is not None:
+            raise PairingError("pair_already_claimed", 409, "pair record already claimed")
+        if now > float(record.get("expires_at") or 0):
+            self._delete_record(path)
+            self._claim_attempts.pop(pair_id, None)
+            raise PairingError("pair_expired", 410, "pair record expired")
+        attempts = self._claim_attempts.get(pair_id, 0) + 1
+        self._claim_attempts[pair_id] = attempts
+        if attempts > 5:
+            raise PairingError("pair_locked", 429, "too many claim attempts")
+        return record, path, now
+
+    def _finalize_claim(
+        self,
+        *,
+        pair_id: str,
+        record: dict,
+        path: Path,
+        now: float,
+        device_name: str,
+        host_chain: Iterable[str],
+        scopes: Iterable[str] | None,
+        cert_pin: str | None,
+        se_public_key_der: str,
+        attest_object: dict | None,
+        attest_key_id: str,
+        attest_environment: str,
+        attested_claim_ticket: str | None,
+        relay_device_id: str | None,
+        relay_required: bool,
+        relay_claim_verifier,
+    ) -> PairClaim:
+        """Post-authentication finalize, shared by legacy and PSK claims. The
+        caller holds _claim_lock and has already proven secret-knowledge (legacy
+        compare or PSK key-confirmation): App Attest, relay ticket, device
+        creation, SE pubkey registration, record teardown."""
+        # WS2: direct-LAN App Attest. When required (or opportunistically
+        # supplied), the claimant must present a valid Apple attestation bound to
+        # this invitation. Fails closed if the validator is unavailable while on.
+        if _direct_attest_required() or attest_object:
+            if not attest_object:
+                raise PairingError("direct_attest_required", 403, "app attest required")
+            if _verify_direct_attestation is None:
+                raise PairingError("direct_attest_unavailable", 503, "app attest validator unavailable")
             try:
-                device = self.registry.create_device(
-                    device_name=device_name or "Pairling iPhone",
-                    install_id=str(record.get("install_id") or self.install_id),
-                    scopes=scopes or DEFAULT_DEVICE_SCOPES,
+                _verify_direct_attestation(
+                    attestation=attest_object,
+                    pair_id=pair_id,
+                    attest_challenge=str(record.get("attest_challenge") or ""),
+                    key_id=attest_key_id,
+                    environment=attest_environment,
+                )
+            except PairingError:
+                raise
+            except Exception:
+                raise PairingError("direct_attest_invalid", 403, "app attest validation failed")
+        relay_status = "none"
+        verified_relay_device_id = relay_device_id
+        relay_pair_secret = None
+        relay_pair_secret_ref = None
+        if relay_required or attested_claim_ticket:
+            if not attested_claim_ticket:
+                raise PairingError("attested_claim_required", 403, "relay claim ticket required")
+            if relay_claim_verifier is None:
+                raise PairingError("attested_claim_invalid", 403, "relay claim verifier unavailable")
+            try:
+                verification = relay_claim_verifier.verify(
+                    attested_claim_ticket,
+                    pair_id=pair_id,
+                    relay_device_id=relay_device_id,
+                    device_name=device_name,
+                )
+            except Exception as exc:
+                code = getattr(exc, "code", "attested_claim_invalid")
+                message = getattr(exc, "message", str(exc))
+                raise PairingError(code, 403, message)
+            verified_relay_device_id = verification.relay_device_id
+            relay_status = verification.attestation_status
+            relay_pair_secret = getattr(verification, "relay_pair_secret", None)
+            relay_pair_secret_ref = getattr(verification, "relay_pair_secret_ref", None)
+        normalized_hosts = tuple(h for h in host_chain if isinstance(h, str) and h)
+        if not normalized_hosts:
+            raise PairingError("missing_host_chain", 500, "host chain is empty")
+        marker = self._create_claim_marker(pair_id)
+        try:
+            device = self.registry.create_device(
+                device_name=device_name or "Pairling iPhone",
+                install_id=str(record.get("install_id") or self.install_id),
+                scopes=scopes or DEFAULT_DEVICE_SCOPES,
+                relay_device_id=verified_relay_device_id,
+                attestation_status=relay_status,
+                device_display_name=device_name or "Pairling iPhone",
+                relay_pair_secret_ref=relay_pair_secret_ref,
+            )
+            if relay_pair_secret and verified_relay_device_id:
+                self._store_relay_pair_secret(
+                    device_id=device.device_id,
                     relay_device_id=verified_relay_device_id,
-                    attestation_status=relay_status,
-                    device_display_name=device_name or "Pairling iPhone",
-                    relay_pair_secret_ref=relay_pair_secret_ref,
+                    mac_install_id=str(record.get("install_id") or self.install_id),
+                    relay_pair_secret=str(relay_pair_secret),
+                    relay_pair_secret_ref=str(relay_pair_secret_ref or ""),
                 )
-                if relay_pair_secret and verified_relay_device_id:
-                    self._store_relay_pair_secret(
-                        device_id=device.device_id,
-                        relay_device_id=verified_relay_device_id,
-                        mac_install_id=str(record.get("install_id") or self.install_id),
-                        relay_pair_secret=str(relay_pair_secret),
-                        relay_pair_secret_ref=str(relay_pair_secret_ref or ""),
-                    )
-                record["claimed_at"] = now
-                record["device_id"] = device.device_id
-                path.write_text(json.dumps(record, indent=2, sort_keys=True) + "\n")
-                try:
-                    os.chmod(path, 0o600)
-                except OSError:
-                    pass
-                self._delete_record(path)
-                self._delete_record(marker)
-                return PairClaim(
-                    device,
-                    normalized_hosts,
-                    int(record.get("runtime_port") or self.runtime_port),
-                    cert_pin,
-                    verified_relay_device_id,
-                    relay_status,
+            # WS4: register the device's Secure-Enclave public key so future
+            # connections can re-pair with a Face ID signature (no QR/PIN).
+            if se_public_key_der:
+                self.registry.register_se_pubkey(device.device_id, se_public_key_der)
+            record["claimed_at"] = now
+            record["device_id"] = device.device_id
+            path.write_text(json.dumps(record, indent=2, sort_keys=True) + "\n")
+            try:
+                os.chmod(path, 0o600)
+            except OSError:
+                pass
+            self._delete_record(path)
+            self._delete_record(marker)
+            self._claim_attempts.pop(pair_id, None)
+            return PairClaim(
+                device,
+                normalized_hosts,
+                int(record.get("runtime_port") or self.runtime_port),
+                cert_pin,
+                verified_relay_device_id,
+                relay_status,
+            )
+        except Exception:
+            self._delete_record(marker)
+            raise
+
+    def psk_claim_pair(
+        self,
+        *,
+        pair_id: str,
+        b_pub_b64: str,
+        confirm_b64: str,
+        device_name: str,
+        host_chain: Iterable[str],
+        scopes: Iterable[str] | None = None,
+        cert_pin: str | None = None,
+        se_public_key_der: str = "",
+        attest_object: dict | None = None,
+        attest_key_id: str = "",
+        attest_environment: str = "",
+        attested_claim_ticket: str | None = None,
+        relay_device_id: str | None = None,
+        relay_required: bool = False,
+        relay_claim_verifier=None,
+    ) -> tuple[PairClaim, bytes, bytes, bytes]:
+        """WS3 PSK-authenticated ECDH claim. The secret is NEVER received; the
+        caller proves knowledge of it by completing the authenticated key
+        exchange (phone confirm tag under K_confirm). Returns
+        (PairClaim, K_token, aad, mac_confirm) so the handler can seal the bearer
+        token under K_token and echo the Mac key-confirmation."""
+        if _psk is None:
+            raise PairingError("psk_unavailable", 503, "psk crypto unavailable")
+        try:
+            b_pub = base64.b64decode(b_pub_b64, validate=True)
+            confirm = base64.b64decode(confirm_b64, validate=True)
+        except Exception:
+            raise PairingError("psk_bad_key", 400, "invalid psk material")
+        with self._claim_lock:
+            record, path, now = self._precheck_claim(pair_id)
+            secret = str(record.get("secret") or "")
+            mac_priv_b64 = str(record.get("mac_ake_priv") or "")
+            mac_pub_b64url = str(record.get("mac_ake_pub") or "")
+            if not mac_priv_b64 or not mac_pub_b64url:
+                raise PairingError("psk_unavailable", 409, "invitation has no psk key")
+            try:
+                a_priv = _psk.load_private(base64.b64decode(mac_priv_b64))
+                a_pub = base64.urlsafe_b64decode(mac_pub_b64url + "=" * (-len(mac_pub_b64url) % 4))
+                z = _psk.shared_secret(a_priv, b_pub)
+                k_confirm, k_token = _psk.derive_keys(
+                    pair_id=pair_id, a_pub=a_pub, b_pub=b_pub, z=z, secret=secret
                 )
-            except Exception:
-                self._delete_record(marker)
+            except PairingError:
                 raise
+            except Exception:
+                raise PairingError("psk_bad_key", 400, "invalid psk material")
+            expected = _psk.confirm_tag(k_confirm, _psk.CONFIRM_PHONE, pair_id, a_pub, b_pub)
+            if not secrets.compare_digest(expected, confirm):
+                raise PairingError("psk_confirm_invalid", 403, "psk confirmation invalid")
+            claim = self._finalize_claim(
+                pair_id=pair_id, record=record, path=path, now=now,
+                device_name=device_name, host_chain=host_chain, scopes=scopes,
+                cert_pin=cert_pin, se_public_key_der=se_public_key_der,
+                attest_object=attest_object, attest_key_id=attest_key_id,
+                attest_environment=attest_environment,
+                attested_claim_ticket=attested_claim_ticket,
+                relay_device_id=relay_device_id, relay_required=relay_required,
+                relay_claim_verifier=relay_claim_verifier,
+            )
+            aad = _psk.transcript(pair_id, a_pub, b_pub)
+            mac_confirm = _psk.confirm_tag(k_confirm, _psk.CONFIRM_MAC, pair_id, a_pub, b_pub)
+            return claim, k_token, aad, mac_confirm
+
+    def seal_psk_token(self, k_token: bytes, token: str, aad: bytes) -> tuple[bytes, bytes]:
+        """AES-256-GCM the bearer token under K_token so only the phone (which
+        derived the same key) can read it. Returns (nonce, ciphertext‖tag)."""
+        if _psk is None:
+            raise PairingError("psk_unavailable", 503, "psk crypto unavailable")
+        return _psk.seal_token(k_token, token, aad=aad)
 
     def _delete_record(self, path: Path) -> None:
         try:
@@ -357,6 +654,13 @@ class PairingAdvertiser:
         self._timer: threading.Timer | None = None
 
     def start(self, started: PairStart, *, port: int) -> dict:
+        # When PSK pairing is required (the default), the Bonjour-advertised
+        # phone-initiated path can no longer complete a claim — legacy /pair/claim
+        # returns 403 — so publishing the service is dead surface and a needless
+        # LAN signal. Self-disable here rather than editing the pairlingd.py call
+        # site. PAIRLING_PSK_REQUIRED=0 (the legacy break-glass) re-enables it.
+        if _psk_required():
+            return {"ok": False, "reason": "psk_required"}
         if os.environ.get("PAIRLING_DISABLE_BONJOUR") in {"1", "true", "TRUE"}:
             return {"ok": False, "reason": "disabled"}
         if not Path(self.dns_sd_path).exists():

package/payload/mac/companiond/pairling_psk.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""WS3: PSK-authenticated ECDH for pairing — the byte-exact reference.
+
+The 192-bit pairing secret is a pre-shared key delivered out-of-band (QR / paste);
+it is NEVER transmitted. The claim becomes an authenticated P-256 ECDH whose key
+schedule mixes in the secret, so only a holder of the secret can derive the keys.
+
+Native primitives only (cryptography: ECDH + HKDF + HMAC + AES-GCM). The Swift
+side (PairingPSK.swift) mirrors every byte of this; SPEC-ws3-psk-authenticated-ecdh.md
+and the shared vectors in test_psk_vectors.py / PairingPSKTests.swift pin the agreement.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from cryptography.hazmat.primitives.hashes import SHA256
+from cryptography.hazmat.primitives.serialization import (
+    Encoding,
+    NoEncryption,
+    PrivateFormat,
+    PublicFormat,
+    load_der_private_key,
+)
+
+# Frozen protocol constants — must match PairingPSK.swift exactly.
+PSK_INFO_PREFIX = b"pairling.psk.v1"
+PSK_SALT = hashlib.sha256(b"pairling.psk.salt.v1").digest()
+CONFIRM_PHONE = b"pairling.psk.confirm.phone.v1"
+CONFIRM_MAC = b"pairling.psk.confirm.mac.v1"
+_CURVE = ec.SECP256R1()
+
+
+def mac_keygen() -> tuple[ec.EllipticCurvePrivateKey, bytes]:
+    """Per-invitation Mac ephemeral key. Returns (private, A_pub X9.63 65 bytes)."""
+    priv = ec.generate_private_key(_CURVE)
+    return priv, public_x963(priv)
+
+
+def private_from_scalar(scalar: int) -> ec.EllipticCurvePrivateKey:
+    """Deterministic key for test vectors."""
+    return ec.derive_private_key(scalar, _CURVE)
+
+
+def public_x963(priv: ec.EllipticCurvePrivateKey) -> bytes:
+    return priv.public_key().public_bytes(Encoding.X962, PublicFormat.UncompressedPoint)
+
+
+def public_from_x963(data: bytes) -> ec.EllipticCurvePublicKey:
+    return ec.EllipticCurvePublicKey.from_encoded_point(_CURVE, data)
+
+
+def dump_private(priv: ec.EllipticCurvePrivateKey) -> bytes:
+    """PKCS8 DER, for storing the per-invitation key in the (mode-600) pair record."""
+    return priv.private_bytes(Encoding.DER, PrivateFormat.PKCS8, NoEncryption())
+
+
+def load_private(der: bytes) -> ec.EllipticCurvePrivateKey:
+    return load_der_private_key(der, password=None)
+
+
+def shared_secret(priv: ec.EllipticCurvePrivateKey, peer_pub_x963: bytes) -> bytes:
+    """SEC1 X-coordinate (32 bytes) — the standard ECDH output both libraries return."""
+    peer = public_from_x963(peer_pub_x963)
+    return priv.exchange(ec.ECDH(), peer)
+
+
+def transcript(pair_id: str, a_pub_x963: bytes, b_pub_x963: bytes) -> bytes:
+    return PSK_INFO_PREFIX + pair_id.encode("utf-8") + a_pub_x963 + b_pub_x963
+
+
+def derive_keys(*, pair_id: str, a_pub: bytes, b_pub: bytes, z: bytes, secret: str) -> tuple[bytes, bytes]:
+    """Returns (K_confirm, K_token), each 32 bytes."""
+    info = transcript(pair_id, a_pub, b_pub)
+    okm = HKDF(algorithm=SHA256(), length=64, salt=PSK_SALT, info=info).derive(z + secret.encode("utf-8"))
+    return okm[:32], okm[32:]
+
+
+def confirm_tag(k_confirm: bytes, domain: bytes, pair_id: str, a_pub: bytes, b_pub: bytes) -> bytes:
+    return hmac.new(k_confirm, domain + transcript(pair_id, a_pub, b_pub), hashlib.sha256).digest()
+
+
+def verify_confirm(k_confirm: bytes, domain: bytes, pair_id: str, a_pub: bytes, b_pub: bytes, tag: bytes) -> bool:
+    return hmac.compare_digest(confirm_tag(k_confirm, domain, pair_id, a_pub, b_pub), tag or b"")
+
+
+def seal_token(k_token: bytes, token: str, *, aad: bytes) -> tuple[bytes, bytes]:
+    """AES-256-GCM. Returns (nonce(12), ciphertext+tag). Random nonce → not deterministic."""
+    import os
+    nonce = os.urandom(12)
+    ct = AESGCM(k_token).encrypt(nonce, token.encode("utf-8"), aad)
+    return nonce, ct
+
+
+def open_token(k_token: bytes, nonce: bytes, ciphertext: bytes, *, aad: bytes) -> str:
+    return AESGCM(k_token).decrypt(nonce, ciphertext, aad).decode("utf-8")

package/payload/mac/companiond/pairling_tools.py

@@ -584,7 +584,7 @@ def _truncate_output(value: str, max_chars: int) -> str:
 def _mac_prompt(tool: str, input_payload: dict[str, Any]) -> tuple[str, str]:
     if tool == "vibe_check":
         return (
-            "You are checking whether a draft sounds like Mergim's usual voice. Return one of: yes, partial, no. Then give one concrete edit. Be concise. Do not rewrite the whole draft unless asked.",
+            "You are checking whether a draft sounds like the user's usual voice. Return one of: yes, partial, no. Then give one concrete edit. Be concise. Do not rewrite the whole draft unless asked.",
             "Draft:\n" + str(input_payload.get("draft") or ""),
         )
     if tool == "second_opinion":
@@ -618,7 +618,7 @@ def _deterministic_vibe_check(draft: str, *, reason: str) -> str:
         "further to",
     ]
     if any(phrase in lowered for phrase in formal_phrases):
-        issues.append("a little more formal than Mergim's usual direct style")
+        issues.append("a little more formal than the user's usual direct style")
         edit = "open with the ask directly and drop the polite padding."
     if len(text) > 700:
         issues.append("too long for a quick operational message")