nxd 0.1.0__py3-none-any.whl

nxd/__init__.py

@@ -0,0 +1,65 @@
+"""
+NXD — encrypted agent operating system.
+
+Three guarantees:
+  1. The agent works fully
+  2. The agent sees nothing
+  3. The operator holds the keys
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from nxd.audit import export as audit_export
+from nxd.audit import log as audit_log
+from nxd.audit import verify as audit_verify
+from nxd.bind import BindingError, bind, open
+from nxd.blur import blur, blur_dataset, blur_guide, blur_report
+from nxd.channel import Channel, ChannelClosedError, channel
+from nxd.checkpoint import checkpoint
+from nxd.fhe import aggregate, match, score
+from nxd.handoff import Handoff
+from nxd.redact import deredact, redact
+from nxd.search import SearchIndex, build_index, retrieve, search
+from nxd.seal import seal, seal_text, unseal, unseal_text
+from nxd.shield import send_to_model, shield, unshield
+from nxd.sign import sign, sign_record, verify_record, verify_signature
+from nxd.split import InsufficientSharesError, distribute, reconstruct_strict, split
+from nxd.tokenize import detokenize, tokenize, tokenize_record
+from nxd.vault import Vault
+from nxd.verify import LockedError, register, unlock, verify
+
+Mode = Literal["auto", "fast", "secure"]
+
+__all__ = [
+    "score", "match", "aggregate", "receive",
+    "Vault", "Handoff",
+    "shield", "unshield", "send_to_model",
+    "build_index", "search", "retrieve", "SearchIndex",
+    "register", "verify", "unlock", "LockedError",
+    "tokenize", "detokenize", "tokenize_record",
+    "redact", "deredact",
+    "seal", "unseal", "seal_text", "unseal_text",
+    "channel", "Channel", "ChannelClosedError",
+    "checkpoint",
+    "sign", "verify_signature", "sign_record", "verify_record",
+    "blur", "blur_dataset", "blur_report", "blur_guide",
+    "split", "reconstruct_strict", "distribute", "InsufficientSharesError",
+    "bind", "open", "BindingError",
+    "audit_log", "audit_verify", "audit_export",
+    "Mode",
+]
+
+
+def receive(model: Any, token: str, handoff: Handoff, mode: Mode = "auto") -> list[int]:
+    """Agent B scores encrypted handoff context."""
+    context = handoff.unpack(token)
+    clients = context if isinstance(context, list) else [context]
+    return score(model, clients, mode=mode)
+
+
+class audit:
+    log = staticmethod(audit_log)
+    verify = staticmethod(audit_verify)
+    export = staticmethod(audit_export)

nxd/_crypto.py

@@ -0,0 +1,46 @@
+"""Shared cryptography utilities for NXD."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+
+from cryptography.fernet import Fernet
+
+DEFAULT_DATA_DIR = Path.home() / ".nxd"
+MASTER_KEY_FILE = "master.key"
+
+
+def data_dir() -> Path:
+    import os
+    path = Path(os.environ.get("NXD_DATA_DIR", DEFAULT_DATA_DIR))
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def master_key_path() -> Path:
+    return data_dir() / MASTER_KEY_FILE
+
+
+def load_fernet(key_path: Path | None = None) -> Fernet:
+    path = key_path or master_key_path()
+    if path.exists():
+        key = path.read_bytes()
+    else:
+        key = Fernet.generate_key()
+        path.write_bytes(key)
+        os.chmod(path, 0o600)
+    return Fernet(key)
+
+
+def load_hmac_key() -> bytes:
+    return hashlib.sha256(master_key_path().read_bytes()).digest()
+
+
+def encrypt_bytes(data: bytes, fernet: Fernet | None = None) -> bytes:
+    return (fernet or load_fernet()).encrypt(data)
+
+
+def decrypt_bytes(token: bytes, fernet: Fernet | None = None) -> bytes:
+    return (fernet or load_fernet()).decrypt(token)

nxd/audit.py

@@ -0,0 +1,86 @@
+"""Tamper-proof audit chain for all NXD operations."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+from nxd._crypto import data_dir
+
+AUDIT_FILE = "audit_chain.jsonl"
+
+
+class AuditChain:
+    def __init__(self, path: Path | None = None):
+        self.path = path or (data_dir() / AUDIT_FILE)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        if not self.path.exists():
+            self.path.write_text("")
+
+    def _last_hash(self) -> str:
+        lines = [l for l in self.path.read_text().splitlines() if l.strip()]
+        if not lines:
+            return "genesis"
+        return json.loads(lines[-1])["hash"]
+
+    def log(self, operation: str, **meta: Any) -> dict:
+        prev = self._last_hash()
+        entry = {
+            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "operation": operation,
+            "meta": meta,
+            "prev_hash": prev,
+        }
+        payload = json.dumps(entry, sort_keys=True)
+        entry["hash"] = hashlib.sha256((prev + payload).encode()).hexdigest()
+        with self.path.open("a") as f:
+            f.write(json.dumps(entry) + "\n")
+        return entry
+
+    def entries(self) -> list[dict]:
+        return [json.loads(l) for l in self.path.read_text().splitlines() if l.strip()]
+
+    def verify(self) -> tuple[bool, int | None]:
+        lines = self.entries()
+        prev = "genesis"
+        for i, entry in enumerate(lines):
+            stored = entry.pop("hash")
+            payload = json.dumps(entry, sort_keys=True)
+            expected = hashlib.sha256((prev + payload).encode()).hexdigest()
+            if stored != expected:
+                entry["hash"] = stored
+                return False, i
+            prev = stored
+            entry["hash"] = stored
+        return True, None
+
+    def export(self, out_path: str | Path) -> Path:
+        out = Path(out_path)
+        report = {"chain_valid": self.verify()[0], "entries": self.entries()}
+        out.write_text(json.dumps(report, indent=2))
+        return out
+
+
+_audit = AuditChain()
+
+
+def log(operation: str, **meta: Any) -> dict:
+    return _audit.log(operation, **meta)
+
+
+def verify() -> tuple[bool, int | None]:
+    return _audit.verify()
+
+
+def export(out_path: str | Path) -> Path:
+    return _audit.export(out_path)
+
+
+def reset_for_tests(path: Path) -> None:
+    global _audit
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("")
+    _audit = AuditChain(path)

nxd/bind.py

@@ -0,0 +1,50 @@
+"""Data binding — encrypt locked to specific recipient and purpose."""
+
+from __future__ import annotations
+
+import base64
+import json
+
+from cryptography.fernet import Fernet
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+from nxd._crypto import master_key_path
+
+
+class BindingError(Exception):
+    pass
+
+
+def _derive_key(recipient: str, purpose: str = "") -> Fernet:
+    seed = master_key_path().read_bytes()
+    derived = HKDF(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=b"nxd-bind",
+        info=f"{recipient}:{purpose}".encode(),
+    ).derive(seed)
+    key = base64.urlsafe_b64encode(derived)
+    return Fernet(key)
+
+
+def bind(data: str, recipient: str, purpose: str = "") -> str:
+    from nxd import audit
+    payload = json.dumps({"data": data, "recipient": recipient, "purpose": purpose})
+    token = _derive_key(recipient, purpose).encrypt(payload.encode()).decode()
+    audit.log("bind", recipient=recipient, purpose=purpose)
+    return token
+
+
+def open(locked: str, caller: str, purpose: str = "") -> str:
+    from nxd import audit
+    try:
+        payload = json.loads(_derive_key(caller, purpose).decrypt(locked.encode()).decode())
+    except Exception as e:
+        raise BindingError(f"Access denied for {caller}") from e
+    if payload["recipient"] != caller:
+        raise BindingError(f"Bound to {payload['recipient']}, not {caller}")
+    if purpose and payload.get("purpose") and payload["purpose"] != purpose:
+        raise BindingError(f"Bound to purpose '{payload['purpose']}', not '{purpose}'")
+    audit.log("open", caller=caller, purpose=purpose)
+    return payload["data"]

nxd/blur.py

@@ -0,0 +1,41 @@
+"""Differential privacy — blur aggregates for safe sharing."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def blur(value: float, sensitivity: float = 1.0, epsilon: float = 1.0) -> float:
+    from nxd import audit
+    scale = sensitivity / epsilon
+    noise = np.random.laplace(0, scale)
+    result = float(value + noise)
+    audit.log("blur", epsilon=epsilon)
+    return result
+
+
+def blur_dataset(values: list[float], sensitivity: float = 1.0, epsilon: float = 1.0) -> list[float]:
+    from nxd import audit
+    result = [blur(v, sensitivity, epsilon) for v in values]
+    audit.log("blur_dataset", count=len(values))
+    return result
+
+
+def blur_report(records: list[dict], fields: list[str], epsilon: float = 1.0) -> dict:
+    from nxd import audit
+    report = {}
+    for field in fields:
+        vals = [float(r[field]) for r in records if field in r]
+        if vals:
+            noisy = blur_dataset(vals, sensitivity=max(vals) * 0.1, epsilon=epsilon)
+            report[field] = {"mean": float(np.mean(noisy)), "std": float(np.std(noisy))}
+    audit.log("blur_report", fields=fields)
+    return report
+
+
+def blur_guide() -> str:
+    return (
+        "epsilon=0.1: very strong privacy, less accuracy\n"
+        "epsilon=1.0: balanced\n"
+        "epsilon=10.0: weak privacy, high accuracy"
+    )

nxd/channel.py

@@ -0,0 +1,63 @@
+"""Encrypted channels — E2E messaging between agents."""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+
+from cryptography.fernet import Fernet
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+from nxd._crypto import master_key_path
+
+
+class ChannelClosedError(Exception):
+    pass
+
+
+def _session_fernet(sender: str, receiver: str) -> Fernet:
+    seed = master_key_path().read_bytes()
+    derived = HKDF(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=b"nxd-channel",
+        info=f"{sender}:{receiver}".encode(),
+    ).derive(seed)
+    key = base64.urlsafe_b64encode(derived)
+    return Fernet(key)
+
+
+class Channel:
+    def __init__(self, sender: str, receiver: str):
+        self.sender = sender
+        self.receiver = receiver
+        self._closed = False
+        self._fernet = _session_fernet(sender, receiver)
+
+    def send(self, message: str) -> str:
+        from nxd import audit
+        if self._closed:
+            raise ChannelClosedError("Channel is closed")
+        packet = json.dumps({"ts": time.time(), "msg": message}).encode()
+        token = self._fernet.encrypt(packet).decode()
+        audit.log("channel_send", sender=self.sender, receiver=self.receiver)
+        return token
+
+    def receive(self, packet: str) -> str:
+        from nxd import audit
+        if self._closed:
+            raise ChannelClosedError("Channel is closed")
+        payload = json.loads(self._fernet.decrypt(packet.encode()).decode())
+        audit.log("channel_receive", receiver=self.receiver)
+        return payload["msg"]
+
+    def close(self) -> None:
+        from nxd import audit
+        self._closed = True
+        audit.log("channel_close", sender=self.sender, receiver=self.receiver)
+
+
+def channel(sender: str, receiver: str) -> Channel:
+    return Channel(sender, receiver)

nxd/checkpoint.py

@@ -0,0 +1,75 @@
+"""Agent state persistence — encrypted checkpoints."""
+
+from __future__ import annotations
+
+import gzip
+import json
+import time
+from pathlib import Path
+
+from nxd._crypto import data_dir, load_fernet
+
+
+class CheckpointStore:
+    def __init__(self, path: Path | None = None):
+        self.dir = path or (data_dir() / "checkpoints")
+        self.dir.mkdir(parents=True, exist_ok=True)
+
+    def _file(self, agent_id: str) -> Path:
+        return self.dir / f"{agent_id}.nxd"
+
+    def save(self, agent_id: str, state: dict) -> Path:
+        from nxd import audit
+        f = load_fernet()
+        meta = {"agent_id": agent_id, "timestamp": time.time(), "keys": list(state.keys())}
+        payload = gzip.compress(json.dumps({"meta": meta, "state": state}).encode())
+        out = self._file(agent_id)
+        out.write_bytes(f.encrypt(payload))
+        audit.log("checkpoint_save", agent_id=agent_id)
+        return out
+
+    def load(self, agent_id: str) -> dict:
+        from nxd import audit
+        out = self._file(agent_id)
+        if not out.exists():
+            raise FileNotFoundError(f"No checkpoint for {agent_id}")
+        f = load_fernet()
+        payload = gzip.decompress(f.decrypt(out.read_bytes()))
+        data = json.loads(payload.decode())
+        audit.log("checkpoint_load", agent_id=agent_id)
+        return data["state"]
+
+    def list_checkpoints(self) -> list[str]:
+        entries = []
+        for p in self.dir.glob("*.nxd"):
+            try:
+                f = load_fernet()
+                payload = gzip.decompress(f.decrypt(p.read_bytes()))
+                meta = json.loads(payload.decode())["meta"]
+                ts = time.strftime("%Y-%m-%d %H:%M", time.localtime(meta["timestamp"]))
+                entries.append(f"{meta['agent_id']} | {ts} | {len(meta['keys'])} keys")
+            except Exception:
+                entries.append(p.stem)
+        return entries
+
+    def purge(self, agent_id: str) -> None:
+        from nxd import audit
+        out = self._file(agent_id)
+        if out.exists():
+            out.unlink()
+        audit.log("checkpoint_purge", agent_id=agent_id)
+
+
+_store = CheckpointStore()
+
+
+class checkpoint:
+    save = staticmethod(lambda agent_id, state: _store.save(agent_id, state))
+    load = staticmethod(lambda agent_id: _store.load(agent_id))
+    list = staticmethod(lambda: _store.list_checkpoints())
+    purge = staticmethod(lambda agent_id: _store.purge(agent_id))
+
+
+def reset_for_tests(path: Path) -> None:
+    global _store
+    _store = CheckpointStore(path)

nxd/fhe.py

@@ -0,0 +1,106 @@
+"""FHE compute primitives — score, match, aggregate."""
+
+from __future__ import annotations
+
+import multiprocessing as mp
+import os
+from typing import Any, Literal
+
+import numpy as np
+import pandas as pd
+
+Mode = Literal["auto", "fast", "secure"]
+PARALLEL_THRESHOLD = 64
+MIN_COMPILE_ROWS = 64
+
+_compiled_models: set[int] = set()
+_worker_model: Any = None
+_worker_fhe: str = "execute"
+
+
+def _to_float64(data: Any) -> np.ndarray:
+    if isinstance(data, pd.DataFrame):
+        arr = data.values
+    elif isinstance(data, np.ndarray):
+        arr = data
+    elif isinstance(data, dict):
+        arr = np.array(list(data.values()), dtype=np.float64)
+    elif isinstance(data, list):
+        if not data:
+            return np.empty((0, 0), dtype=np.float64)
+        if isinstance(data[0], dict):
+            arr = pd.DataFrame(data).values
+        else:
+            arr = np.array(data, dtype=np.float64)
+    else:
+        arr = np.asarray(data, dtype=np.float64)
+    return np.asarray(arr, dtype=np.float64)
+
+
+def _compile_set(X: np.ndarray) -> np.ndarray:
+    if len(X) >= MIN_COMPILE_ROWS:
+        return X
+    repeats = (MIN_COMPILE_ROWS // max(len(X), 1)) + 1
+    return np.tile(X, (repeats, 1))[:MIN_COMPILE_ROWS]
+
+
+def _resolve_fhe(mode: Mode) -> str:
+    return "simulate" if mode == "fast" else "execute"
+
+
+def _ensure_compiled(model: Any, X: np.ndarray) -> None:
+    key = id(model)
+    if key not in _compiled_models:
+        model.compile(_compile_set(X))
+        _compiled_models.add(key)
+
+
+def _worker_predict(X_batch: np.ndarray) -> np.ndarray:
+    return _worker_model.predict(X_batch, fhe=_worker_fhe)
+
+
+def _predict(model: Any, X: np.ndarray, mode: Mode) -> np.ndarray:
+    _ensure_compiled(model, X)
+    fhe = _resolve_fhe(mode)
+    use_parallel = mode == "auto" and fhe == "execute" and len(X) >= PARALLEL_THRESHOLD
+    if use_parallel:
+        global _worker_model, _worker_fhe
+        _worker_model = model
+        _worker_fhe = fhe
+        n_workers = min(os.cpu_count() or 8, len(X))
+        batches = [b for b in np.array_split(X, n_workers) if len(b) > 0]
+        ctx = mp.get_context("fork")
+        with ctx.Pool(len(batches)) as pool:
+            parts = pool.map(_worker_predict, batches)
+        return np.concatenate(parts)
+    return model.predict(X, fhe=fhe)
+
+
+def score(model: Any, clients: Any, mode: Mode = "auto") -> list[int]:
+    from nxd import audit
+    X = _to_float64(clients)
+    if X.ndim == 1:
+        X = X.reshape(1, -1)
+    result = [int(v) for v in _predict(model, X, mode)]
+    audit.log("score", count=len(result), mode=mode)
+    return result
+
+
+def match(model: Any, record_a: Any, record_b: Any) -> bool:
+    from nxd import audit
+    a = _to_float64(record_a).ravel()
+    b = _to_float64(record_b).ravel()
+    X = np.concatenate([a, b]).reshape(1, -1)
+    result = bool(int(_predict(model, X, mode="secure")[0]) == 1)
+    audit.log("match", result=result)
+    return result
+
+
+def aggregate(model: Any, records: Any) -> float:
+    from nxd import audit
+    X = _to_float64(records)
+    if X.ndim == 1:
+        X = X.reshape(-1, 1)
+    result = float(np.mean(_predict(model, X, mode="auto")))
+    audit.log("aggregate", count=len(X))
+    return result

nxd/handoff.py

@@ -0,0 +1,30 @@
+"""Encrypted context handoff between agents."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from cryptography.fernet import Fernet
+
+
+class Handoff:
+    def __init__(self, key: bytes | None = None):
+        self._key = key or Fernet.generate_key()
+        self._fernet = Fernet(self._key)
+
+    @property
+    def key(self) -> bytes:
+        return self._key
+
+    def pack(self, context: Any) -> str:
+        from nxd import audit
+        token = self._fernet.encrypt(json.dumps(context).encode()).decode()
+        audit.log("handoff_pack")
+        return token
+
+    def unpack(self, token: str) -> Any:
+        from nxd import audit
+        data = json.loads(self._fernet.decrypt(token.encode()).decode())
+        audit.log("handoff_unpack")
+        return data

nxd/redact.py

@@ -0,0 +1,42 @@
+"""PII redaction — mask sensitive text before AI models."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_PATTERNS = [
+    (r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b", "EMAIL"),
+    (r"\b\d{3}-\d{2}-\d{4}\b", "SSN"),
+    (r"\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b", "CARD"),
+    (r"\bsk_live_[A-Za-z0-9]+\b", "APIKEY"),
+    (r"\bBearer\s+[A-Za-z0-9._-]+\b", "BEARER"),
+    (r"\b\d{2}/\d{2}/\d{4}\b", "DATE"),
+    (r"\b\d{3}[-.]?\d{3}[-.]?\d{4}\b", "PHONE"),
+    (r"\b[A-Z][a-z]+ [A-Z][a-z]+\b", "NAME"),
+]
+
+
+def redact(text: str) -> tuple[str, dict[str, str]]:
+    from nxd import audit
+    mapping: dict[str, str] = {}
+    result = text
+    counters: dict[str, int] = {}
+    for pattern, label in _PATTERNS:
+        for match in re.finditer(pattern, result):
+            val = match.group()
+            counters[label] = counters.get(label, 0) + 1
+            placeholder = f"[{label}_{counters[label]}]"
+            mapping[placeholder] = val
+            result = result.replace(val, placeholder, 1)
+    audit.log("redact", placeholders=len(mapping))
+    return result, mapping
+
+
+def deredact(text: str, mapping: dict[str, str]) -> str:
+    from nxd import audit
+    result = text
+    for placeholder, value in mapping.items():
+        result = result.replace(placeholder, value)
+    audit.log("deredact", restored=len(mapping))
+    return result

nxd/seal.py

@@ -0,0 +1,49 @@
+"""Document sealing — encrypt files for storage and transit."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+from nxd._crypto import load_fernet
+
+
+def seal(path: str | Path, operator_id: str = "operator") -> Path:
+    from nxd import audit
+    src = Path(path)
+    f = load_fernet()
+    header = {"filename": src.name, "timestamp": time.time(), "operator": operator_id}
+    payload = json.dumps(header).encode() + b"\n---\n" + src.read_bytes()
+    out = src.with_suffix(src.suffix + ".nxd")
+    out.write_bytes(f.encrypt(payload))
+    audit.log("seal", file=src.name)
+    return out
+
+
+def unseal(path: str | Path, out_dir: str | Path | None = None) -> Path:
+    from nxd import audit
+    src = Path(path)
+    f = load_fernet()
+    payload = f.decrypt(src.read_bytes())
+    header_raw, data = payload.split(b"\n---\n", 1)
+    header = json.loads(header_raw.decode())
+    dest_dir = Path(out_dir) if out_dir else src.parent
+    out = dest_dir / header["filename"]
+    out.write_bytes(data)
+    audit.log("unseal", file=header["filename"])
+    return out
+
+
+def seal_text(text: str) -> str:
+    from nxd import audit
+    token = load_fernet().encrypt(text.encode()).decode()
+    audit.log("seal_text", length=len(text))
+    return token
+
+
+def unseal_text(token: str) -> str:
+    from nxd import audit
+    text = load_fernet().decrypt(token.encode()).decode()
+    audit.log("unseal_text", length=len(text))
+    return text