noirebox 0.3.0__py3-none-any.whl

noirebox/__init__.py

@@ -0,0 +1 @@
+

noirebox/anchors.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import base64
+import os
+import subprocess
+import tempfile
+
+import httpx
+
+from .chain import GENESIS, KeyPair
+from .store import EventStore
+
+GENESIS_HASH = GENESIS
+
+
+def tsa_configured() -> bool:
+    return bool(os.environ.get("NOIREBOX_TSA_URL"))
+
+
+def _tsa_url() -> str:
+    return os.environ["NOIREBOX_TSA_URL"].rstrip("/")
+
+
+def build_query(head_hash: str) -> bytes:
+    """Builds the timestamp request (TimeStampReq, DER) via OpenSSL.
+
+    The DIGEST (hex) is passed directly — the TSA never sees the data;
+    a 32-byte hash tells no one anything.
+    """
+    with tempfile.TemporaryDirectory() as tmp:
+        out = f"{tmp}/req.tsq"
+        proc = subprocess.run(
+            ["openssl", "ts", "-query", "-digest", head_hash, "-sha256", "-cert", "-out", out],
+            capture_output=True,
+        )
+        if proc.returncode != 0:
+            raise RuntimeError(f"openssl ts -query failed: {proc.stderr.decode()[:200]}")
+        with open(out, "rb") as f:
+            return f.read()
+
+
+def request_token(head_hash: str, tsa_url: str | None = None) -> bytes:
+    """Sends the request to the TSA, returns the TimeStampResp token (DER)."""
+    url = (tsa_url or _tsa_url()).rstrip("/")
+    response = httpx.post(
+        f"{url}/tsa",
+        content=build_query(head_hash),
+        headers={"Content-Type": "application/timestamp-query"},
+        timeout=10,
+    )
+    if response.status_code != 200:
+        raise RuntimeError(f"TSA responded {response.status_code}")
+    return response.content
+
+
+def fetch_tsa_cert(tsa_url: str | None = None) -> str:
+    """Fetches the TSA certificate (it travels INSIDE the anchor — the third
+    party needs it to verify the token; TOFU + pinning possible, ADR 006)."""
+    url = (tsa_url or _tsa_url()).rstrip("/")
+    response = httpx.get(f"{url}/cert", timeout=10)
+    response.raise_for_status()
+    return response.text
+
+
+def anchor_now(store: EventStore, key: KeyPair, tsa_url: str | None = None) -> dict:
+    """Seals the current chain head to the TSA: token + certificate logged
+    in an "anchor" event (the anchor is part of the chain)."""
+    events = store.all()
+    head_seq = len(events)
+    head_hash = events[-1]["event_hash"] if events else GENESIS_HASH
+
+    token = request_token(head_hash, tsa_url)
+    cert_pem = fetch_tsa_cert(tsa_url)
+
+    event = store.append(
+        "anchor",
+        {"head_seq": head_seq, "head_hash": head_hash,
+         "tsr": base64.b64encode(token).decode("ascii"),
+         "tsa_cert_pem": cert_pem},
+        key,
+    )
+    return {
+        "anchor_event_seq": event.seq,
+        "anchored_head_seq": head_seq,
+        "anchored_head_hash": head_hash,
+        "tsr_bytes": len(token),
+    }

noirebox/attestation.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from collections import Counter
+
+from .chain import GENESIS, KeyPair, canonical, ed25519_verify, verify_chain
+from .store import now_iso
+
+
+def build_attestation(store, key: KeyPair) -> dict:
+    """Builds the attestation of the current state: canonical digest + signature.
+
+    `store` is loosely typed (to avoid a circular import with store.py):
+    we only depend on its `.all()`.
+    """
+    events = store.all()
+    report = verify_chain(key.public_hex(), events)
+    by_type = dict(Counter(e["type"] for e in events))
+    core = {
+        "generated_at": now_iso(),
+        "algo": "sha256-chain+ed25519",
+        "public_key": key.public_hex(),
+        "head_seq": len(events),
+        "head_hash": events[-1]["event_hash"] if events else GENESIS,
+        "total_events": len(events),
+        "chain_valid": report["valid"],
+        "event_types": by_type,
+    }
+
+    return {**core, "signature": key.sign(canonical(core))}
+
+
+def verify_attestation(attestation: dict) -> bool:
+    """Verifies the signature of a submitted attestation.
+
+    The `signature` key is removed from the dict before recomputing the
+    digest: that is the "signed payload" scheme — everything is signed
+    EXCEPT the signature itself.
+    """
+    core = {k: v for k, v in attestation.items() if k != "signature"}
+    public_key = attestation.get("public_key", "")
+    signature = attestation.get("signature", "")
+    if not public_key or not signature:
+        return False
+    return ed25519_verify(public_key, signature, canonical(core))

noirebox/auth.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+import time
+
+import jwt
+from fastapi import HTTPException, Request
+
+
+
+
+
+
+
+DEFAULT_CLIENTS = {"demo": "demo-secret"}
+
+
+def load_clients() -> dict[str, str]:
+    """Reads NOIREBOX_CLIENTS ("id:secret,id2:secret2"), otherwise the demo client."""
+    raw = os.environ.get("NOIREBOX_CLIENTS", "")
+    clients: dict[str, str] = {}
+    for pair in raw.split(","):
+        if ":" in pair:
+            client_id, secret = pair.split(":", 1)
+            clients[client_id.strip()] = secret.strip()
+    return clients or dict(DEFAULT_CLIENTS)
+
+
+
+
+TOKEN_TTL_SECONDS = 3600
+
+
+def _jwt_secret() -> str:
+    """JWT signing secret: NOIREBOX_JWT_SECRET, otherwise derived from the
+    instance key (every deployment signs with something unique)."""
+    secret = os.environ.get("NOIREBOX_JWT_SECRET")
+    if secret:
+        return secret
+
+
+    from .chain import KeyPair
+
+    key = KeyPair.load_or_create(os.environ.get("NOIREBOX_DB", "data/noirebox.db") + ".key")
+    return hashlib.sha256(key.public_hex().encode()).hexdigest()
+
+
+def issue_token(client_id: str, client_secret: str, clients: dict[str, str] | None = None) -> str | None:
+    """Exchanges an id/secret pair for a 1 h JWT. None if credentials are invalid.
+
+    Constant-time comparison (`hmac.compare_digest`) — the SQL injection
+    lesson applied to timing: reveal nothing through request duration.
+    """
+    clients = clients if clients is not None else load_clients()
+    expected = clients.get(client_id)
+    if expected is None or not hmac.compare_digest(expected.encode(), client_secret.encode()):
+        return None
+    now = int(time.time())
+    payload = {"sub": client_id, "iat": now, "exp": now + TOKEN_TTL_SECONDS, "scope": "api"}
+    return jwt.encode(payload, _jwt_secret(), algorithm="HS256")
+
+
+def verify_token(token: str) -> str | None:
+    """Verifies signature + expiration. Returns the client_id, None if invalid."""
+    try:
+        payload = jwt.decode(token, _jwt_secret(), algorithms=["HS256"])
+    except jwt.InvalidTokenError:
+        return None
+    return payload.get("sub")
+
+
+
+
+class RateLimiter:
+    """Per-client counter over a sliding window.
+
+    Why in memory and not SQLite: rate limiting must cost ~0 ms and, above
+    all, never write to the append-only journal (the journal records the
+    business, not the traffic). Redis = the multi-process extension.
+    """
+
+    def __init__(self, max_requests: int = 60, window_seconds: int = 60):
+        self.max = max_requests
+        self.window = window_seconds
+        self._hits: dict[str, list[float]] = {}
+
+    def allow(self, client_id: str, now: float | None = None) -> tuple[bool, int]:
+        """Returns (allowed?, remaining quota). Purges expired hits along the way."""
+        now = now if now is not None else time.monotonic()
+        bucket = [t for t in self._hits.get(client_id, []) if now - t < self.window]
+        if len(bucket) >= self.max:
+            self._hits[client_id] = bucket
+            return False, 0
+        bucket.append(now)
+        self._hits[client_id] = bucket
+        return True, self.max - len(bucket)
+
+
+
+
+def build_auth_dependency(clients: dict[str, str] | None = None,
+                          limiter: RateLimiter | None = None,
+                          enabled: bool = True):
+    """Returns the FastAPI dependency `require_auth`.
+
+    Why a factory: tests inject their own clients/limits without touching
+    env vars — same pattern as `create_app(db_path)`.
+    Auth DISABLED by default locally (enabled=False when no client is
+    configured): the quickstart stays friction-free `./start.sh`; enabling
+    it means setting NOIREBOX_CLIENTS. Security must not break the demo,
+    and activation must be an explicit choice.
+    """
+    clients = clients if clients is not None else load_clients()
+    limiter = limiter or RateLimiter()
+
+    def require_auth(request: Request) -> str:
+        if not enabled:
+            return "anonymous"
+        header = request.headers.get("authorization", "")
+        if not header.startswith("Bearer "):
+            raise HTTPException(status_code=401, detail="Authorization: Bearer <token> required",
+                                headers={"WWW-Authenticate": "Bearer"})
+        client_id = verify_token(header.removeprefix("Bearer ").strip())
+        if client_id is None:
+            raise HTTPException(status_code=401, detail="invalid or expired token",
+                                headers={"WWW-Authenticate": "Bearer"})
+        allowed, remaining = limiter.allow(client_id)
+        if not allowed:
+            raise HTTPException(status_code=429, detail="rate limit exceeded (60 req/min)",
+                                headers={"Retry-After": "60"})
+        request.state.client_id = client_id
+        request.state.quota_remaining = remaining
+        return client_id
+
+    return require_auth

noirebox/chain.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import dataclass
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+from cryptography.hazmat.primitives.serialization import (
+    Encoding,
+    NoEncryption,
+    PrivateFormat,
+    PublicFormat,
+    load_pem_private_key,
+)
+
+
+
+GENESIS = "0" * 64
+
+
+def canonical(obj: object) -> bytes:
+    """Deterministic canonical serialization: identical bytes on every machine.
+
+    Why this is critical: the hash is computed over these bytes. If two
+    serializations of the same content produced two different representations
+    (key order, whitespace), third-party verification would fail with no
+    tampering at all. Hence: sorted keys (`sort_keys`), zero superfluous
+    whitespace, explicit UTF-8 (accented text must hash identically everywhere).
+    """
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def compute_event_hash(seq: int, ts: str, type_: str, payload: dict, prev_hash: str) -> str:
+    """Hex SHA-256 hash committing the entire content of the event."""
+    core = {"seq": seq, "ts": ts, "type": type_, "payload": payload, "prev_hash": prev_hash}
+    return hashlib.sha256(canonical(core)).hexdigest()
+
+
+class KeyPair:
+    """The instance's Ed25519 key pair.
+
+    Why Ed25519: modern elliptic-curve cryptography, 32-byte keys (versus
+    256+ bytes for RSA), very fast signing and verification, standardized.
+
+    The private key is persisted as PEM (standard text format) with chmod 600:
+    only the server process can read it. The public key, meanwhile, travels
+    in every export/attestation — it is all a third party needs.
+    """
+
+    def __init__(self, private_key: Ed25519PrivateKey):
+        self._priv = private_key
+        self._pub = private_key.public_key()
+
+    @classmethod
+    def generate(cls) -> KeyPair:
+        """Factory: generates a new key pair."""
+        return cls(Ed25519PrivateKey.generate())
+
+    @classmethod
+    def load_or_create(cls, path: str) -> KeyPair:
+        """Loads the PEM key if it exists, otherwise generates it and writes it chmod 600.
+
+        `os.open(..., 0o600)`: the file is created with its permissions set
+        right away (atomically), rather than created then chmod'ed — a key
+        file world-readable for even an instant would be a vulnerability.
+        """
+        if os.path.exists(path):
+            with open(path, "rb") as f:
+                priv = load_pem_private_key(f.read(), password=None)
+            if not isinstance(priv, Ed25519PrivateKey):
+                raise ValueError(f"{path} does not contain an Ed25519 key")
+            return cls(priv)
+        kp = cls.generate()
+        pem = kp._priv.private_bytes(Encoding.PEM, PrivateFormat.PKCS8, NoEncryption())
+        fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        with os.fdopen(fd, "wb") as f:
+            f.write(pem)
+        return kp
+
+    def public_hex(self) -> str:
+        """Public key in hexadecimal — the value embedded in the exports."""
+        return self._pub.public_bytes(Encoding.Raw, PublicFormat.Raw).hex()
+
+    def sign(self, data: bytes) -> str:
+        """Signs bytes, returns the signature in hexadecimal."""
+        return self._priv.sign(data).hex()
+
+    def verify(self, signature_hex: str, data: bytes) -> bool:
+        """Verifies with THIS instance's public key (self-verification)."""
+        try:
+            self._pub.verify(bytes.fromhex(signature_hex), data)
+            return True
+        except (InvalidSignature, ValueError):
+            return False
+
+    def verify_with_public_key(self, public_hex: str, signature_hex: str, data: bytes) -> bool:
+        """Verifies with an external public key — the third-party auditor case."""
+        return ed25519_verify(public_hex, signature_hex, data)
+
+
+@dataclass
+class Event:
+    """A journal event. `@dataclass` generates __init__/__eq__ automatically.
+
+    The 7 fields below are enough: no getter/setter to write.
+    """
+
+    seq: int
+    ts: str
+    type: str
+    payload: dict
+    prev_hash: str
+    event_hash: str
+    signature: str
+
+    def as_dict(self) -> dict:
+        """Explicit serialization to a dict (JSON-compatible)."""
+        return {
+            "seq": self.seq,
+            "ts": self.ts,
+            "type": self.type,
+            "payload": self.payload,
+            "prev_hash": self.prev_hash,
+            "event_hash": self.event_hash,
+            "signature": self.signature,
+        }
+
+
+def ed25519_verify(public_hex: str, signature_hex: str, data: bytes) -> bool:
+    """Verification with the public key alone.
+
+    Returns False instead of raising: a signature failure is an expected
+    BUSINESS outcome (tampering), not a programming error.
+    """
+    try:
+        pub = Ed25519PublicKey.from_public_bytes(bytes.fromhex(public_hex))
+        pub.verify(bytes.fromhex(signature_hex), data)
+        return True
+    except (InvalidSignature, ValueError):
+        return False
+
+
+def verify_event(public_hex: str, ev: dict) -> str | None:
+    """Verifies a single event. Convention: `None` = intact, otherwise the reason.
+
+    No exception is raised for a predictable business case — the auditor wants
+    a report, not a crash.
+    """
+    recomputed = compute_event_hash(ev["seq"], ev["ts"], ev["type"], ev["payload"], ev["prev_hash"])
+    if recomputed != ev["event_hash"]:
+        return "invalid hash (content was modified)"
+    if not ed25519_verify(public_hex, ev["signature"], bytes.fromhex(ev["event_hash"])):
+        return "invalid signature"
+    return None
+
+
+def verify_chain(public_hex: str, events: list[dict]) -> dict:
+    """Verifies the whole chain: order, links, hashes, signatures.
+
+    We stop at the first anomaly and locate it precisely (`first_error.seq`):
+    that is what the auditor wants to see — WHERE it breaks.
+    """
+    prev = GENESIS
+    for expected_seq, ev in enumerate(events, start=1):
+
+        if ev["seq"] != expected_seq:
+            return {"valid": False, "nb_events": len(events),
+                    "first_error": {"seq": ev["seq"], "reason": "broken sequence (reordering or deletion)"}}
+        if ev["prev_hash"] != prev:
+            return {"valid": False, "nb_events": len(events),
+                    "first_error": {"seq": ev["seq"], "reason": f"broken link: prev_hash ≠ hash of event {ev['seq'] - 1}"}}
+        reason = verify_event(public_hex, ev)
+        if reason is not None:
+            return {"valid": False, "nb_events": len(events),
+                    "first_error": {"seq": ev["seq"], "reason": reason}}
+        prev = ev["event_hash"]
+    return {"valid": True, "nb_events": len(events), "first_error": None}

noirebox/cli.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import argparse
+
+
+def _version() -> str:
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version("noirebox")
+    except PackageNotFoundError:
+        return "0.3.0+unknown"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="noirebox",
+        description="NoireBox — the flight data recorder for AI agents.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {_version()}")
+    sub = parser.add_subparsers(dest="command")
+    serve = sub.add_parser("serve", help="run the HTTP API (uvicorn)")
+    serve.add_argument("--host", default="127.0.0.1", help="bind address")
+    serve.add_argument("--port", type=int, default=8768, help="listening port")
+    args = parser.parse_args(argv)
+
+    if args.command == "serve":
+        import uvicorn
+
+        uvicorn.run("noirebox.main:app", host=args.host, port=args.port, log_level="info")
+        return 0
+
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    import sys
+
+    sys.exit(main())

noirebox/client.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import httpx
+
+
+class NoireBoxError(RuntimeError):
+    """Business error raised by the API (status 4xx/5xx)."""
+
+
+class NoireBoxClient:
+    def __init__(self, base_url: str = "http://127.0.0.1:8768",
+                 timeout: float = 5.0, transport: httpx.BaseTransport | None = None):
+
+
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"), timeout=timeout, transport=transport
+        )
+
+    def _request(self, method: str, path: str, json_body: dict | None = None) -> dict:
+        response = self._http.request(method, path, json=json_body)
+        if response.status_code >= 400:
+            raise NoireBoxError(f"{method} {path} → {response.status_code}: {response.text}")
+        return response.json()
+
+    def health(self) -> dict:
+        return self._request("GET", "/health")
+
+    def log_event(self, type_: str, payload: dict | None = None) -> dict:
+        return self._request("POST", "/api/v1/events",
+                             {"type": type_, "payload": payload or {}})
+
+    def scan(self, meeting_id: str, text: str, engine: str = "regex", lang: str = "fr") -> dict:
+        """Guardrail on a text. `engine`: "regex" or "ml"; `lang`: "fr"/"en" (ml engine)."""
+        return self._request("POST", "/api/v1/transcripts/scan",
+                             {"meeting_id": meeting_id, "text": text,
+                              "engine": engine, "lang": lang})
+
+    def verify(self) -> dict:
+        return self._request("GET", "/api/v1/verify")
+
+    def attestation(self) -> dict:
+        return self._request("GET", "/api/v1/attestation")
+
+    def export(self) -> dict:
+        return self._request("GET", "/api/v1/export")