ltcai 11.0.1 → 11.2.0

package/lattice_brain/portability.py

@@ -38,7 +38,14 @@ from .archive import (
     EncryptedBrainArchive,
     _derive_key,
 )
+from .gates import FeatureGate
 from .quiet import quiet
+from .sealed_box import (
+    SEALED_BOX_ALGORITHM,
+    load_recipient_identity,
+    public_key_fingerprint,
+    seal,
+)
 from .storage import (
     DockerPostgresWizard,
     PostgresEngine,
@@ -64,6 +71,9 @@ SUBGRAPH_ARCHIVE_FORMAT = "latticebrain.subgraph"
 #: Brain is a network act, and local-first means those are never on by default.
 BRAIN_NETWORK_ENV = "LATTICEAI_BRAIN_NETWORK"
 _TRUTHY = frozenset({"1", "true", "yes", "on"})
+#: How a bundle can be encrypted. ``passphrase`` needs a secret agreed out of
+#: band; ``recipient_public_key`` needs nothing secret to travel at all.
+ENCRYPTION_MODES = ("passphrase", "recipient_public_key")
 #: A received bundle becomes review items, never a merge. The cap keeps one
 #: peer from flooding the inbox; what it dropped is reported, not hidden.
 SUBGRAPH_PROPOSAL_CAP = 200
@@ -82,6 +92,17 @@ BRAIN_NETWORK_DISABLED_DETAIL = (
 )
 
 
+#: The share gate, resolved when it is asked. The environment variable is still
+#: the default answer — an untouched install behaves exactly as it did — but a
+#: settings surface can now bind a resolver and move it without a restart.
+BRAIN_NETWORK_GATE = FeatureGate(
+    BRAIN_NETWORK_ENV,
+    default=False,
+    name="brain_network",
+    detail=BRAIN_NETWORK_DISABLED_DETAIL,
+)
+
+
 class BrainNetworkDisabled(PermissionError):
     """Raised when a share surface is used while the opt-in flag is off."""
 
@@ -91,7 +112,7 @@ class BrainNetworkDisabled(PermissionError):
 
 def brain_network_enabled() -> bool:
     """True only when the operator explicitly opted in (default: off)."""
-    return os.getenv(BRAIN_NETWORK_ENV, "").strip().lower() in _TRUTHY
+    return BRAIN_NETWORK_GATE.enabled()
 
 
 def require_brain_network() -> None:
@@ -365,6 +386,41 @@ class KGPortabilityService:
         # importable locally (origin='unsigned-legacy') — signatures are
         # mandatory only on the Brain Network peer path.
         self._identity = device_identity
+        # The receiving X25519 key is created lazily: a Brain that never asks
+        # anyone to seal anything to it should not be minting key material on
+        # every startup (v11.2.0).
+        self._recipient: Any = None
+        self._recipient_loaded = False
+
+    # ── recipient key (v11.2.0 sealed-box receipt) ───────────────────────────
+    def _recipient_identity(self) -> Any:
+        """This Brain's X25519 receiving key, created on first use.
+
+        ``None`` when the data directory cannot hold one — reported as a state
+        by :meth:`recipient_key`, never raised into a status read.
+        """
+        if not self._recipient_loaded:
+            self._recipient = load_recipient_identity(self._data_dir)
+            self._recipient_loaded = True
+        return self._recipient
+
+    def recipient_key(self) -> Dict[str, Any]:
+        """The public half to hand a sender, so they can seal a bundle to us.
+
+        Publishing this is safe by construction: a public key encrypts, it does
+        not decrypt, and it says nothing about what this Brain contains.
+        """
+        require_brain_network()
+        identity = self._recipient_identity()
+        if identity is None:
+            return {
+                "available": False,
+                "detail": (
+                    "a receiving key could not be created in the data directory; "
+                    "sealed bundles cannot be opened on this machine"
+                ),
+            }
+        return {"available": True, **identity.describe()}
 
     def available(self) -> bool:
         return self._enable and self._kg is not None
@@ -469,11 +525,14 @@ class KGPortabilityService:
             "signing": self._identity is not None,
             "device": self._share_device(),
             "proposal_cap": SUBGRAPH_PROPOSAL_CAP,
-            # Stated rather than implied: the bundle is signed by this device
-            # and encrypted with a shared passphrase. Encrypting *to a
-            # recipient's public key* is not implemented in this release.
-            "encryption": "passphrase",
-            "recipient_public_key_encryption": False,
+            # Stated rather than implied: a bundle is always signed by this
+            # device, and encrypted either with a shared passphrase or — since
+            # 11.2.0 — to the recipient's own public key, so nothing secret has
+            # to travel ahead of it.
+            "encryption": list(ENCRYPTION_MODES),
+            "recipient_public_key_encryption": True,
+            "sealed_box_algorithm": SEALED_BOX_ALGORITHM,
+            "gate": BRAIN_NETWORK_GATE.describe(),
             "detail": None if enabled else BRAIN_NETWORK_DISABLED_DETAIL,
         }
 
@@ -607,17 +666,28 @@ class KGPortabilityService:
         self,
         dest_path=None,
         *,
-        passphrase: str,
+        passphrase: Optional[str] = None,
+        recipient_public_key: Optional[str] = None,
         **selection: Any,
     ) -> Dict[str, Any]:
         """Write the signed subgraph as an encrypted ``.latticebrain`` file.
 
-        Same passphrase mechanism as the whole-Brain archive (PBKDF2-SHA256 →
-        AES-256-GCM), a different ``format`` so the two can never be confused.
-        The header and signature stay outside the ciphertext on purpose: a
-        recipient can see *who* sent a bundle, and how big it is, before typing
-        a passphrase into it.
+        Exactly one recipient mechanism, named explicitly:
+
+        * ``passphrase`` — the 11.1.0 mechanism, identical to the whole-Brain
+          archive (PBKDF2-SHA256 → AES-256-GCM). Simple, and it means a secret
+          has to reach the receiver through some other channel first.
+        * ``recipient_public_key`` — an X25519 sealed box (11.2.0). The
+          receiver publishes a public key; nothing secret travels at all.
+
+        Supplying both is refused rather than silently preferring one: which
+        key opens a bundle is not a detail to guess at. A different ``format``
+        from the whole-Brain archive keeps the two from ever being confused,
+        and the header and signature stay *outside* the ciphertext on purpose —
+        a recipient can see who sent a bundle, and how big it is, before
+        deciding to open it.
         """
+        mode = self._encryption_mode(passphrase, recipient_public_key)
         artifact = self.export_subgraph(**selection)
         self._exports_dir.mkdir(parents=True, exist_ok=True)
         dest = Path(dest_path) if dest_path else self._exports_dir / f"subgraph-{_stamp()}.latticebrain"
@@ -625,36 +695,77 @@ class KGPortabilityService:
             dest = dest.with_suffix(".latticebrain")
         body = {key: value for key, value in artifact.items() if key not in {"header", "signature"}}
         plaintext = json.dumps(body, ensure_ascii=False, sort_keys=True).encode("utf-8")
-        salt = os.urandom(16)
-        nonce = os.urandom(12)
-        ciphertext = AESGCM(_derive_key(passphrase, salt)).encrypt(nonce, plaintext, None)
-        envelope = {
+        envelope: Dict[str, Any] = {
             "format": SUBGRAPH_ARCHIVE_FORMAT,
             "format_version": SUBGRAPH_FORMAT_VERSION,
             "created_at": utc_now_iso(),
-            "kdf": {
-                "name": "PBKDF2HMAC-SHA256",
-                "iterations": KDF_ITERATIONS,
-                "salt": base64.b64encode(salt).decode("ascii"),
-            },
-            "cipher": {"name": "AES-256-GCM", "nonce": base64.b64encode(nonce).decode("ascii")},
+            "encryption": mode,
             "header": artifact["header"],
             "signature": artifact["signature"],
-            "payload": base64.b64encode(ciphertext).decode("ascii"),
         }
+        recipient: Optional[str] = None
+        if mode == "recipient_public_key":
+            sealed = seal(plaintext, recipient_public_key=str(recipient_public_key))
+            recipient = str(sealed["recipient_fingerprint"])
+            envelope["sealed_box"] = sealed
+        else:
+            salt = os.urandom(16)
+            nonce = os.urandom(12)
+            ciphertext = AESGCM(_derive_key(str(passphrase), salt)).encrypt(nonce, plaintext, None)
+            envelope["kdf"] = {
+                "name": "PBKDF2HMAC-SHA256",
+                "iterations": KDF_ITERATIONS,
+                "salt": base64.b64encode(salt).decode("ascii"),
+            }
+            envelope["cipher"] = {
+                "name": "AES-256-GCM",
+                "nonce": base64.b64encode(nonce).decode("ascii"),
+            }
+            envelope["payload"] = base64.b64encode(ciphertext).decode("ascii")
         dest.parent.mkdir(parents=True, exist_ok=True)
         dest.write_text(json.dumps(envelope, ensure_ascii=False, indent=2), encoding="utf-8")
         return {
             "path": str(dest),
             "bytes": dest.stat().st_size,
             "encrypted": True,
+            "encryption": mode,
+            "recipient_fingerprint": recipient,
             "format": SUBGRAPH_ARCHIVE_FORMAT,
             "header": artifact["header"],
             "counts": artifact["header"]["counts"],
         }
 
-    def read_subgraph_archive(self, path, *, passphrase: str) -> Dict[str, Any]:
-        """Decrypt an encrypted subgraph bundle back into a signed artifact."""
+    @staticmethod
+    def _encryption_mode(
+        passphrase: Optional[str], recipient_public_key: Optional[str]
+    ) -> str:
+        """``passphrase`` | ``recipient_public_key`` — exactly one, validated."""
+        has_passphrase = bool(str(passphrase or "").strip())
+        wanted_key = str(recipient_public_key or "").strip()
+        if has_passphrase and wanted_key:
+            raise ValueError(
+                "Choose one: a passphrase, or a recipient public key. "
+                "A bundle sealed both ways would hide which key really opens it."
+            )
+        if wanted_key:
+            public_key_fingerprint(wanted_key)  # validates; raises on garbage
+            return "recipient_public_key"
+        if has_passphrase:
+            return "passphrase"
+        raise ValueError(
+            "A subgraph bundle must be encrypted: supply a passphrase or the "
+            "recipient's public key."
+        )
+
+    def read_subgraph_archive(
+        self, path, *, passphrase: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Decrypt an encrypted subgraph bundle back into a signed artifact.
+
+        The envelope says how it was sealed, so the reader never has to guess:
+        a passphrase bundle needs the passphrase, a sealed-box bundle needs
+        this Brain's own receiving key and no passphrase at all.
+        """
         require_brain_network()
         source = Path(path)
         if not source.exists():
@@ -665,6 +776,36 @@ class KGPortabilityService:
             raise ValueError("Subgraph bundle is not valid JSON.") from exc
         if envelope.get("format") != SUBGRAPH_ARCHIVE_FORMAT:
             raise ValueError("Not a .latticebrain subgraph bundle.")
+        if envelope.get("encryption") == "recipient_public_key":
+            plaintext = self._unseal_bundle(envelope)
+        else:
+            plaintext = self._decrypt_with_passphrase(envelope, passphrase)
+        body = json.loads(plaintext.decode("utf-8"))
+        return {
+            "header": envelope.get("header") or {},
+            **body,
+            "signature": envelope.get("signature") or {},
+        }
+
+    def _unseal_bundle(self, envelope: Dict[str, Any]) -> bytes:
+        """Open a sealed box with this Brain's receiving key, or say why not."""
+        identity = self._recipient_identity()
+        if identity is None:
+            raise ValueError(
+                "This bundle is sealed to a public key, but no receiving key "
+                "could be loaded on this machine."
+            )
+        block = envelope.get("sealed_box")
+        if not isinstance(block, dict):
+            raise ValueError("Subgraph bundle is missing encryption metadata.")
+        return bytes(identity.unseal(block))
+
+    @staticmethod
+    def _decrypt_with_passphrase(
+        envelope: Dict[str, Any], passphrase: Optional[str]
+    ) -> bytes:
+        if not str(passphrase or "").strip():
+            raise ValueError("This bundle is passphrase-encrypted; a passphrase is required.")
         try:
             salt = base64.b64decode(envelope["kdf"]["salt"])
             nonce = base64.b64decode(envelope["cipher"]["nonce"])
@@ -672,17 +813,13 @@ class KGPortabilityService:
         except (KeyError, TypeError, ValueError) as exc:
             raise ValueError("Subgraph bundle is missing encryption metadata.") from exc
         try:
-            plaintext = AESGCM(_derive_key(passphrase, salt)).decrypt(nonce, ciphertext, None)
+            return bytes(
+                AESGCM(_derive_key(str(passphrase), salt)).decrypt(nonce, ciphertext, None)
+            )
         except InvalidTag as exc:
             raise ValueError(
                 "Subgraph decryption failed; the passphrase or the bundle is invalid."
             ) from exc
-        body = json.loads(plaintext.decode("utf-8"))
-        return {
-            "header": envelope.get("header") or {},
-            **body,
-            "signature": envelope.get("signature") or {},
-        }
 
     def verify_subgraph(self, artifact: Dict[str, Any]) -> Dict[str, Any]:
         """Signature + payload-digest verdict for a received bundle.

package/lattice_brain/runtime/multi_agent.py

@@ -49,7 +49,7 @@ from typing import Any, Callable, Dict, List, Optional
 from ..utils import now_iso as _now
 from .contracts import multi_agent_contract
 
-MULTI_AGENT_VERSION = "11.0.1"
+MULTI_AGENT_VERSION = "11.2.0"
 
 AGENT_ROLES = ("researcher", "planner", "executor", "reviewer", "release")
 CORE_PIPELINE = ("planner", "executor", "reviewer")

package/lattice_brain/sealed_box.py

@@ -0,0 +1,244 @@
+"""Sealing a bundle to a recipient's public key (v11.2.0).
+
+Through 11.1.0 a shared subgraph was encrypted with a passphrase, which means
+the sender and the receiver must first agree on a secret over some *other*
+channel — and whatever that channel is, the passphrase is now in it. This
+module removes that step: the receiver publishes an X25519 public key, the
+sender seals a bundle to it, and only the holder of the matching private key
+can open it. Nothing secret ever travels.
+
+The construction is the standard sealed box, assembled from primitives
+``cryptography`` already ships (it is a core dependency; nothing new is added):
+
+1. the sender generates a **single-use ephemeral X25519 keypair**;
+2. ``ephemeral_private × recipient_public`` yields a shared secret only the two
+   of them can compute;
+3. **HKDF-SHA256** stretches that secret into a 256-bit key, with both public
+   keys mixed into ``info`` so a key derived for one recipient can never be
+   reused for another;
+4. **AES-256-GCM** encrypts the payload under it.
+
+Forward secrecy comes free: the ephemeral private key is discarded the moment
+the box is sealed, so a later compromise of the recipient's long-term key still
+does not decrypt an already-sent bundle — nothing else in the envelope can
+reconstruct the shared secret.
+
+The sender's Ed25519 signature over the bundle header is **untouched** by all
+of this. Signing says who wrote it; sealing says who may read it. Collapsing
+the two into one keypair is the usual way to end up with neither.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric.x25519 import (
+    X25519PrivateKey,
+    X25519PublicKey,
+)
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+#: Named in the envelope so a future construction can be told apart from this
+#: one instead of being silently mis-decrypted.
+SEALED_BOX_ALGORITHM = "x25519-hkdf-sha256-aes256gcm"
+#: Domain separation for the KDF — this key schedule is for subgraph bundles
+#: and nothing else.
+HKDF_INFO_PREFIX = b"latticeai.subgraph.sealed-box.v1"
+KEY_BYTES = 32
+NONCE_BYTES = 12
+SALT_BYTES = 16
+#: Filename of the recipient key under the data directory (0600, like the
+#: device identity's key file).
+RECIPIENT_KEY_FILENAME = "subgraph_recipient.key"
+
+
+def _b64(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).decode("ascii").rstrip("=")
+
+
+def _unb64(text: str) -> bytes:
+    padded = str(text) + "=" * (-len(str(text)) % 4)
+    return base64.urlsafe_b64decode(padded.encode("ascii"))
+
+
+def _raw_public(key: X25519PublicKey) -> bytes:
+    return key.public_bytes(
+        serialization.Encoding.Raw, serialization.PublicFormat.Raw
+    )
+
+
+def public_key_fingerprint(public_key_b64: str) -> str:
+    """Human-comparable fingerprint of an X25519 public key.
+
+    Raises ``ValueError`` when the input is not a usable key — callers use this
+    as the validation gate before sealing anything to a pasted string.
+    """
+    try:
+        raw = _unb64(public_key_b64)
+        X25519PublicKey.from_public_bytes(raw)
+    except Exception as exc:  # noqa: BLE001 — any parse failure is one answer
+        raise ValueError(f"not a valid X25519 public key: {exc}") from exc
+    digest = hashlib.sha256(raw).hexdigest()
+    return ":".join(digest[i : i + 4] for i in range(0, 16, 4))
+
+
+def _derive(shared: bytes, salt: bytes, ephemeral: bytes, recipient: bytes) -> bytes:
+    return HKDF(
+        algorithm=hashes.SHA256(),
+        length=KEY_BYTES,
+        salt=salt,
+        info=HKDF_INFO_PREFIX + b"|" + ephemeral + b"|" + recipient,
+    ).derive(shared)
+
+
+def seal(plaintext: bytes, *, recipient_public_key: str) -> Dict[str, Any]:
+    """Encrypt ``plaintext`` so only the recipient's private key can open it.
+
+    Returns the JSON-safe crypto block that goes in the bundle envelope. The
+    recipient's own public key is echoed back into it so a receiver holding
+    several keys can tell at a glance whether this box was meant for them —
+    without trying to decrypt it, and without the sender having to be asked.
+    """
+    try:
+        recipient_raw = _unb64(recipient_public_key)
+        peer = X25519PublicKey.from_public_bytes(recipient_raw)
+    except Exception as exc:  # noqa: BLE001 — a bad key is a caller error, said plainly
+        raise ValueError(f"not a valid X25519 public key: {exc}") from exc
+    ephemeral = X25519PrivateKey.generate()
+    ephemeral_raw = _raw_public(ephemeral.public_key())
+    salt = os.urandom(SALT_BYTES)
+    nonce = os.urandom(NONCE_BYTES)
+    key = _derive(ephemeral.exchange(peer), salt, ephemeral_raw, recipient_raw)
+    ciphertext = AESGCM(key).encrypt(nonce, plaintext, None)
+    return {
+        "algorithm": SEALED_BOX_ALGORITHM,
+        "ephemeral_public_key": _b64(ephemeral_raw),
+        "recipient_public_key": _b64(recipient_raw),
+        "recipient_fingerprint": public_key_fingerprint(recipient_public_key),
+        "salt": _b64(salt),
+        "nonce": _b64(nonce),
+        "ciphertext": _b64(ciphertext),
+    }
+
+
+def unseal(block: Dict[str, Any], private_key: X25519PrivateKey) -> bytes:
+    """Open a sealed box with the recipient's private key.
+
+    Fail-closed and specific: an unknown algorithm, a missing field, a box
+    addressed to a different key, and a failed tag check each say which one
+    happened rather than collapsing into "decryption failed".
+    """
+    algorithm = str((block or {}).get("algorithm") or "")
+    if algorithm != SEALED_BOX_ALGORITHM:
+        raise ValueError(
+            f"unsupported sealed-box algorithm: {algorithm or 'missing'}"
+        )
+    try:
+        ephemeral_raw = _unb64(block["ephemeral_public_key"])
+        salt = _unb64(block["salt"])
+        nonce = _unb64(block["nonce"])
+        ciphertext = _unb64(block["ciphertext"])
+        peer = X25519PublicKey.from_public_bytes(ephemeral_raw)
+    except Exception as exc:  # noqa: BLE001 — a malformed envelope is one answer
+        raise ValueError(f"sealed bundle is missing encryption metadata: {exc}") from exc
+    recipient_raw = _raw_public(private_key.public_key())
+    addressed = str(block.get("recipient_public_key") or "")
+    if addressed and _unb64(addressed) != recipient_raw:
+        raise ValueError(
+            "this bundle was sealed to a different recipient key "
+            f"({block.get('recipient_fingerprint') or 'unknown fingerprint'})."
+        )
+    key = _derive(private_key.exchange(peer), salt, ephemeral_raw, recipient_raw)
+    try:
+        return bytes(AESGCM(key).decrypt(nonce, ciphertext, None))
+    except InvalidTag as exc:
+        raise ValueError(
+            "Sealed bundle decryption failed; the recipient key or the bundle is invalid."
+        ) from exc
+
+
+class RecipientIdentity:
+    """This Brain's X25519 receiving keypair — loads or creates, file-backed.
+
+    Deliberately *not* the device's Ed25519 identity. That key signs, and a
+    signing key that also decrypts is a key whose compromise costs twice. The
+    private half lives in a 0600 file under the data directory and never leaves
+    the machine; :meth:`describe` reports exactly that rather than implying a
+    keychain this class does not use.
+    """
+
+    def __init__(self, data_dir: Any) -> None:
+        self._data_dir = Path(data_dir)
+        self._key_file = self._data_dir / RECIPIENT_KEY_FILENAME
+        self._private = self._load_or_create()
+
+    def _load_or_create(self) -> X25519PrivateKey:
+        if self._key_file.exists():
+            return X25519PrivateKey.from_private_bytes(
+                _unb64(self._key_file.read_text(encoding="utf-8").strip())
+            )
+        key = X25519PrivateKey.generate()
+        raw = key.private_bytes(
+            serialization.Encoding.Raw,
+            serialization.PrivateFormat.Raw,
+            serialization.NoEncryption(),
+        )
+        self._data_dir.mkdir(parents=True, exist_ok=True)
+        self._key_file.write_text(_b64(raw), encoding="utf-8")
+        os.chmod(self._key_file, 0o600)
+        return key
+
+    @property
+    def public_key_b64(self) -> str:
+        return _b64(_raw_public(self._private.public_key()))
+
+    @property
+    def fingerprint(self) -> str:
+        return public_key_fingerprint(self.public_key_b64)
+
+    def describe(self) -> Dict[str, Any]:
+        return {
+            "public_key": self.public_key_b64,
+            "fingerprint": self.fingerprint,
+            "algorithm": SEALED_BOX_ALGORITHM,
+            "storage": "file",
+            "path": str(self._key_file),
+        }
+
+    def seal_to_self(self, plaintext: bytes) -> Dict[str, Any]:
+        """Seal to this Brain's own key — the honest way to test a round trip."""
+        return seal(plaintext, recipient_public_key=self.public_key_b64)
+
+    def unseal(self, block: Dict[str, Any]) -> bytes:
+        return unseal(block, self._private)
+
+
+def load_recipient_identity(data_dir: Any) -> Optional[RecipientIdentity]:
+    """Best-effort recipient key, or ``None`` when the directory is unusable.
+
+    Sharing is opt-in and a missing key is a *state*, not a crash: the status
+    surface reports "no receiving key" rather than failing a status read.
+    """
+    try:
+        return RecipientIdentity(data_dir)
+    except (OSError, ValueError):  # noqa: BLE001 — unwritable dir / corrupt key file
+        return None
+
+
+__all__ = [
+    "HKDF_INFO_PREFIX",
+    "RECIPIENT_KEY_FILENAME",
+    "SEALED_BOX_ALGORITHM",
+    "RecipientIdentity",
+    "load_recipient_identity",
+    "public_key_fingerprint",
+    "seal",
+    "unseal",
+]