feat: scaffold security modules and TLS foundation

Data/Server/Modules/crypto/__init__.py

@@ -0,0 +1 @@
+

Data/Server/Modules/crypto/certificates.py

@@ -0,0 +1,133 @@
+"""
+Self-signed certificate management for Borealis.
+
+The production Flask server and the Vite dev server both consume the same
+certificate chain so agents and browsers can pin a single trust anchor during
+enrollment.
+"""
+
+from __future__ import annotations
+
+import os
+import ssl
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Tuple
+
+from cryptography import x509
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.x509.oid import NameOID
+
+_CERT_DIR = Path(__file__).resolve().parent.parent / "certs"
+_CERT_FILE = _CERT_DIR / "borealis-server-cert.pem"
+_KEY_FILE = _CERT_DIR / "borealis-server-key.pem"
+_BUNDLE_FILE = _CERT_DIR / "borealis-server-bundle.pem"
+
+# 100-year lifetime (effectively "never" for self-signed deployments).
+_CERT_VALIDITY = timedelta(days=365 * 100)
+
+
+def ensure_certificate(common_name: str = "Borealis Server") -> Tuple[Path, Path, Path]:
+    """
+    Ensure the self-signed certificate and key exist on disk.
+
+    Returns (cert_path, key_path, bundle_path).
+    """
+
+    _CERT_DIR.mkdir(parents=True, exist_ok=True)
+
+    regenerate = not (_CERT_FILE.exists() and _KEY_FILE.exists())
+    if not regenerate:
+        try:
+            with _CERT_FILE.open("rb") as fh:
+                cert = x509.load_pem_x509_certificate(fh.read())
+            if cert.not_valid_after.replace(tzinfo=timezone.utc) <= datetime.now(tz=timezone.utc):
+                regenerate = True
+        except Exception:
+            regenerate = True
+
+    if regenerate:
+        _generate_certificate(common_name)
+
+    if not _BUNDLE_FILE.exists():
+        _BUNDLE_FILE.write_bytes(_CERT_FILE.read_bytes())
+
+    return _CERT_FILE, _KEY_FILE, _BUNDLE_FILE
+
+
+def _generate_certificate(common_name: str) -> None:
+    private_key = ec.generate_private_key(ec.SECP384R1())
+    public_key = private_key.public_key()
+
+    now = datetime.now(tz=timezone.utc)
+    builder = (
+        x509.CertificateBuilder()
+        .subject_name(
+            x509.Name(
+                [
+                    x509.NameAttribute(NameOID.COMMON_NAME, common_name),
+                    x509.NameAttribute(NameOID.ORGANIZATION_NAME, "Borealis"),
+                ]
+            )
+        )
+        .issuer_name(
+            x509.Name(
+                [
+                    x509.NameAttribute(NameOID.COMMON_NAME, common_name),
+                ]
+            )
+        )
+        .public_key(public_key)
+        .serial_number(x509.random_serial_number())
+        .not_valid_before(now - timedelta(minutes=5))
+        .not_valid_after(now + _CERT_VALIDITY)
+        .add_extension(
+            x509.SubjectAlternativeName(
+                [
+                    x509.DNSName("localhost"),
+                    x509.DNSName("127.0.0.1"),
+                    x509.DNSName("::1"),
+                ]
+            ),
+            critical=False,
+        )
+        .add_extension(x509.BasicConstraints(ca=True, path_length=None), critical=True)
+    )
+
+    certificate = builder.sign(private_key=private_key, algorithm=hashes.SHA384())
+
+    _KEY_FILE.write_bytes(
+        private_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.TraditionalOpenSSL,
+            encryption_algorithm=serialization.NoEncryption(),
+        )
+    )
+    _CERT_FILE.write_bytes(certificate.public_bytes(serialization.Encoding.PEM))
+
+    # Propagate filesystem permissions to restrict accidental disclosure.
+    _tighten_permissions(_KEY_FILE)
+    _tighten_permissions(_CERT_FILE)
+
+
+def _tighten_permissions(path: Path) -> None:
+    try:
+        if os.name == "posix":
+            path.chmod(0o600)
+    except Exception:
+        pass
+
+
+def build_ssl_context() -> ssl.SSLContext:
+    cert_path, key_path, _bundle_path = ensure_certificate()
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+    context.minimum_version = ssl.TLSVersion.TLSv1_3
+    context.load_cert_chain(certfile=str(cert_path), keyfile=str(key_path))
+    return context
+
+
+def certificate_paths() -> Tuple[str, str, str]:
+    cert_path, key_path, bundle_path = ensure_certificate()
+    return str(cert_path), str(key_path), str(bundle_path)
+

Data/Server/Modules/crypto/keys.py

@@ -0,0 +1,71 @@
+"""
+Utility helpers for working with Ed25519 keys and fingerprints.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import re
+from typing import Tuple
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.serialization import load_der_public_key
+from cryptography.hazmat.primitives.asymmetric import ed25519
+
+
+def generate_ed25519_keypair() -> Tuple[ed25519.Ed25519PrivateKey, bytes]:
+    """
+    Generate a new Ed25519 keypair.
+
+    Returns the private key object and the public key encoded as SubjectPublicKeyInfo DER bytes.
+    """
+
+    private_key = ed25519.Ed25519PrivateKey.generate()
+    public_key = private_key.public_key().public_bytes(
+        encoding=serialization.Encoding.DER,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    return private_key, public_key
+
+
+def normalize_base64(data: str) -> str:
+    """
+    Collapse whitespace and normalise URL-safe encodings so we can reliably decode.
+    """
+
+    cleaned = re.sub(r"\\s+", "", data or "")
+    return cleaned.replace("-", "+").replace("_", "/")
+
+
+def spki_der_from_base64(spki_b64: str) -> bytes:
+    return base64.b64decode(normalize_base64(spki_b64), validate=True)
+
+
+def base64_from_spki_der(spki_der: bytes) -> str:
+    return base64.b64encode(spki_der).decode("ascii")
+
+
+def fingerprint_from_spki_der(spki_der: bytes) -> str:
+    digest = hashlib.sha256(spki_der).hexdigest()
+    return digest.lower()
+
+
+def fingerprint_from_base64_spki(spki_b64: str) -> str:
+    return fingerprint_from_spki_der(spki_der_from_base64(spki_b64))
+
+
+def private_key_to_pem(private_key: ed25519.Ed25519PrivateKey) -> bytes:
+    return private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+
+
+def public_key_to_pem(public_spki_der: bytes) -> bytes:
+    public_key = load_der_public_key(public_spki_der)
+    return public_key.public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )

Data/Server/Modules/crypto/signing.py

@@ -0,0 +1,70 @@
+"""
+Code-signing helpers for delivering scripts to agents.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Tuple
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ed25519
+
+from .keys import base64_from_spki_der
+
+_KEY_DIR = Path(__file__).resolve().parent.parent / "keys"
+_SIGNING_KEY_FILE = _KEY_DIR / "borealis-script-ed25519.key"
+_SIGNING_PUB_FILE = _KEY_DIR / "borealis-script-ed25519.pub"
+
+
+class ScriptSigner:
+    def __init__(self, private_key: ed25519.Ed25519PrivateKey):
+        self._private = private_key
+        self._public = private_key.public_key()
+
+    def sign(self, payload: bytes) -> bytes:
+        return self._private.sign(payload)
+
+    def public_spki_der(self) -> bytes:
+        return self._public.public_bytes(
+            encoding=serialization.Encoding.DER,
+            format=serialization.PublicFormat.SubjectPublicKeyInfo,
+        )
+
+    def public_base64_spki(self) -> str:
+        return base64_from_spki_der(self.public_spki_der())
+
+
+def load_signer() -> ScriptSigner:
+    private_key = _load_or_create()
+    return ScriptSigner(private_key)
+
+
+def _load_or_create() -> ed25519.Ed25519PrivateKey:
+    _KEY_DIR.mkdir(parents=True, exist_ok=True)
+    if _SIGNING_KEY_FILE.exists():
+        with _SIGNING_KEY_FILE.open("rb") as fh:
+            return serialization.load_pem_private_key(fh.read(), password=None)
+
+    private_key = ed25519.Ed25519PrivateKey.generate()
+    pem = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    with _SIGNING_KEY_FILE.open("wb") as fh:
+        fh.write(pem)
+    try:
+        if hasattr(_SIGNING_KEY_FILE, "chmod"):
+            _SIGNING_KEY_FILE.chmod(0o600)
+    except Exception:
+        pass
+
+    pub_der = private_key.public_key().public_bytes(
+        encoding=serialization.Encoding.DER,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    _SIGNING_PUB_FILE.write_bytes(pub_der)
+
+    return private_key
+