dosync 0.4.1__py3-none-any.whl

dosync/auth.py

@@ -0,0 +1,194 @@
+"""
+DoSync — Authentication
+=======================
+API key simple para proteger el hub.
+
+- Las keys se generan con secrets.token_urlsafe(32)
+- Solo almacenamos el SHA-256 del token, nunca el token en texto plano
+- El primer arranque genera una key automáticamente y la muestra en consola
+- Las keys adicionales se crean via API o CLI
+
+Flujo:
+    1. Hub arranca → si no hay keys, genera una y la muestra UNA SOLA VEZ
+    2. Cliente incluye: Authorization: Bearer <token>
+    3. Hub hashea el token y busca en la DB
+    4. Si no coincide → 401 Unauthorized
+
+Uso en FastAPI (las dependencias viven en dosync.auth_fastapi):
+    from dosync.auth_fastapi import require_auth
+
+    @app.get("/v1/devices")
+    async def list_devices(auth=Depends(require_auth)):
+        ...
+"""
+
+from __future__ import annotations
+import hashlib
+import logging
+import os
+import secrets
+from typing import Optional
+
+log = logging.getLogger("dosync.auth")
+
+# NOTE: This module is the framework-agnostic core of DoSync auth.
+# It deliberately does NOT import FastAPI (or any web framework). The
+# FastAPI request dependencies (require_auth / optional_auth) live in
+# dosync/auth_fastapi.py, which is only loaded by the server. Keeping the
+# core free of framework imports means hash_token, AuthManager, and
+# DeviceAuthManager can be imported and tested in isolation — and a prior
+# bug (require_auth failing to import when FastAPI was absent) cannot recur.
+# Do not add `from fastapi import ...` here.
+
+
+# ── Hashing ───────────────────────────────────────────────────────────────────
+
+def hash_token(token: str) -> str:
+    """SHA-256 del token. Nunca almacenamos el token en texto plano."""
+    return hashlib.sha256(token.encode()).hexdigest()
+
+
+# ── Auth manager ──────────────────────────────────────────────────────────────
+
+class AuthManager:
+    """
+    Gestiona API keys para el hub DoSync.
+    Se integra con DoSyncDB para persistencia.
+    """
+
+    def __init__(self, db, enabled: bool = True):
+        """
+        Args:
+            db:      instancia de DoSyncDB
+            enabled: si False, todas las requests pasan sin verificación.
+                     Útil para desarrollo local.
+        """
+        self.db      = db
+        self.enabled = enabled
+
+    def generate_key(self, label: str = "default") -> str:
+        """
+        Genera una nueva API key, la hashea y la guarda en la DB.
+        Retorna el token en texto plano — solo se muestra UNA VEZ.
+        """
+        token    = secrets.token_urlsafe(32)
+        key_hash = hash_token(token)
+        self.db.save_api_key(key_hash, label)
+        log.info("New API key generated: label='%s'", label)
+        return token
+
+    def verify(self, token: str) -> bool:
+        """Verifica un token. Retorna True si es válido."""
+        if not self.enabled:
+            return True
+        key_hash = hash_token(token)
+        return self.db.verify_api_key(key_hash)
+
+    def ensure_default_key(self) -> Optional[str]:
+        """
+        Si no hay ninguna key, genera una y la retorna para mostrarla.
+        Si ya hay keys, retorna None (no genera otra).
+        Llamar al iniciar el hub.
+
+        Si DOSYNC_DEMO_TOKEN está definido en el entorno, usa ese valor
+        como token inicial en lugar de generar uno aleatorio. Útil para
+        despliegues Docker donde el token debe ser conocido de antemano.
+        """
+        if not self.enabled:
+            return None
+        if not self.db.has_any_key():
+            demo_token = os.environ.get("DOSYNC_DEMO_TOKEN")
+            if demo_token:
+                key_hash = hash_token(demo_token)
+                self.db.save_api_key(key_hash, "demo")
+                log.info("Demo token registered from DOSYNC_DEMO_TOKEN env var")
+                return demo_token
+            token = self.generate_key("default")
+            return token
+        return None
+
+    def list_keys(self) -> list[dict]:
+        return self.db.list_api_keys()
+
+    def delete_key(self, key_hash: str) -> bool:
+        return self.db.delete_api_key(key_hash)
+
+
+# ── FastAPI dependency ────────────────────────────────────────────────────────
+
+# Referencia global al auth manager — se setea al iniciar el servidor
+_auth_manager: Optional[AuthManager] = None
+
+def set_auth_manager(manager: AuthManager) -> None:
+    global _auth_manager
+    _auth_manager = manager
+
+def get_auth_manager() -> AuthManager:
+    return _auth_manager
+
+
+# ── Device token manager ──────────────────────────────────────────────────────
+
+class DeviceAuthManager:
+    """
+    Gestiona tokens de autenticación por dispositivo.
+
+    Flujo:
+        1. Operador pre-registra un dispositivo → obtiene device_token
+        2. Dispositivo incluye device_token al registrar su manifest
+        3. Hub valida el token → solo permite el device_id autorizado
+
+    Backward compatible: si device_token no se incluye en el manifest,
+    el registro procede sin validación (modo legacy).
+    Configurable via DOSYNC_DEVICE_AUTH=strict para requerir token siempre.
+    """
+
+    def __init__(self, db):
+        self.db = db
+        self.strict = os.environ.get("DOSYNC_DEVICE_AUTH", "permissive") == "strict"
+
+    def provision(self, device_id: str, label: str = "") -> str:
+        """
+        Pre-registra un device_id y genera su token de acceso.
+        Retorna el token en texto plano — mostrar UNA SOLA VEZ al operador.
+        """
+        token = secrets.token_urlsafe(32)
+        token_hash = hash_token(token)
+        self.db.save_device_token(device_id, token_hash, label or device_id)
+        log.info("Device token provisioned: device_id='%s'", device_id)
+        return token
+
+    def verify(self, device_id: str, token: str) -> tuple[bool, str]:
+        """
+        Verifica que el token corresponde al device_id declarado.
+        Retorna (valid: bool, reason: str).
+        """
+        token_hash = hash_token(token)
+        if self.db.verify_device_token(device_id, token_hash):
+            return True, "ok"
+        if self.db.device_is_provisioned(device_id):
+            return False, f"Invalid token for device_id '{device_id}'"
+        if self.strict:
+            return False, f"Device '{device_id}' not provisioned — strict mode enabled"
+        return True, "unprovisioned — permissive mode"
+
+    def is_provisioned(self, device_id: str) -> bool:
+        return self.db.device_is_provisioned(device_id)
+
+    def revoke(self, device_id: str) -> bool:
+        return self.db.delete_device_token(device_id)
+
+    def list_provisioned(self) -> list[dict]:
+        return self.db.list_device_tokens()
+
+
+# Referencia global al device auth manager
+_device_auth_manager: Optional[AuthManager] = None
+
+def set_device_auth_manager(manager: "DeviceAuthManager") -> None:
+    global _device_auth_manager
+    _device_auth_manager = manager
+
+def get_device_auth_manager() -> Optional["DeviceAuthManager"]:
+    return _device_auth_manager
+

dosync/auth_fastapi.py

@@ -0,0 +1,87 @@
+"""
+DoSync — FastAPI Auth Dependencies
+==================================
+FastAPI request dependencies that enforce the hub's API-key authentication.
+
+This module is the web-framework glue layer. It is the ONLY auth module that
+imports FastAPI, and it imports it unconditionally — because this module is
+only ever loaded by the server, which requires FastAPI by definition.
+
+The framework-agnostic core (hash_token, AuthManager, DeviceAuthManager) lives
+in dosync/auth.py and must never import a web framework. This separation keeps
+the core testable in isolation and prevents the class of bug where a
+module-level FastAPI symbol fails to resolve when FastAPI is absent.
+
+Usage:
+    from dosync.auth_fastapi import require_auth
+
+    @app.get("/v1/devices")
+    async def list_devices(auth=Depends(require_auth)):
+        ...
+"""
+
+from __future__ import annotations
+from typing import Optional
+
+from fastapi import HTTPException, Security
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from dosync.auth import get_auth_manager
+
+# Bearer scheme — auto_error=False so we can return our own 401 payloads.
+_bearer = HTTPBearer(auto_error=False)
+
+
+async def require_auth(
+    credentials: Optional[HTTPAuthorizationCredentials] = Security(_bearer),
+) -> str:
+    """
+    FastAPI dependency that verifies the API key.
+
+    Usage:
+        @app.get("/v1/devices")
+        async def list_devices(auth=Depends(require_auth)):
+            ...
+
+    If auth is disabled (development), it lets everything through.
+    """
+    manager = get_auth_manager()
+
+    # Auth disabled
+    if manager is None or not manager.enabled:
+        return "dev"
+
+    # No token
+    if not credentials:
+        raise HTTPException(
+            status_code=401,
+            detail="Missing Authorization header. Use: Authorization: Bearer <token>",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    # Invalid token
+    if not manager.verify(credentials.credentials):
+        raise HTTPException(
+            status_code=401,
+            detail="Invalid or expired API key.",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    return credentials.credentials
+
+
+async def optional_auth(
+    credentials: Optional[HTTPAuthorizationCredentials] = Security(_bearer),
+) -> Optional[str]:
+    """
+    Like require_auth but does not fail when no token is present.
+    Useful for endpoints that are public but show more info when authenticated.
+    """
+    manager = get_auth_manager()
+    if manager is None or not manager.enabled:
+        return "dev"
+    if not credentials:
+        return None
+    if manager.verify(credentials.credentials):
+        return credentials.credentials
+    return None

dosync/cert_signing.py

@@ -0,0 +1,117 @@
+"""
+DoSync — Certification report signing & verification.
+=====================================================
+
+Signs a certification report with Ed25519 so a third party can confirm the report
+was not ALTERED after it was issued. Uses the pure-Python Ed25519 (zero deps).
+
+WHAT THE SIGNATURE PROVES — AND DOESN'T
+---------------------------------------
+A valid signature proves the report content is byte-for-byte what the holder of
+the signing key produced: no third party edited "failed" into "passed" or changed
+the host. It does NOT prove the tests reflect production, nor that the operator
+didn't tune the hub for the test run — the operator holds the key and controls the
+environment. The signature defends against tampering by others, not against
+self-declaration. The report's own `attestation` block states this in plain words.
+
+KEY MANAGEMENT
+--------------
+The signing key is a 32-byte seed stored at the path given by DOSYNC_CERT_KEY
+(default: ~/.dosync/cert_signing_key). If absent, `sign_report` can generate one.
+The PUBLIC key is embedded in every signed report so a verifier needs nothing but
+the report itself (and this code, or any Ed25519 library).
+
+The key identifies the ISSUER, not an authority. Anyone can generate a key and
+sign their own reports — which is exactly right for self-certification. Trust in a
+key is a social fact (you know whose key it is), established outside this protocol.
+"""
+
+from __future__ import annotations
+import json
+import os
+import hashlib
+from pathlib import Path
+
+from .ed25519_pure import publickey, signature, checkvalid
+
+
+def _key_path() -> Path:
+    return Path(os.environ.get("DOSYNC_CERT_KEY", str(Path.home() / ".dosync" / "cert_signing_key")))
+
+
+def load_or_create_key() -> bytes:
+    """Return the 32-byte signing seed, creating one if it does not exist."""
+    path = _key_path()
+    if path.exists():
+        seed = path.read_bytes()
+        if len(seed) != 32:
+            raise ValueError(f"signing key at {path} is not 32 bytes")
+        return seed
+    seed = os.urandom(32)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(seed)
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+    return seed
+
+
+def _canonical(report_dict: dict) -> bytes:
+    """Canonical byte representation of the report for signing/verifying.
+
+    The `signature` block itself is excluded — you cannot sign a document that
+    contains its own signature. Everything else is serialized deterministically
+    (sorted keys, no whitespace) so signer and verifier hash identical bytes.
+    """
+    payload = {k: v for k, v in report_dict.items() if k != "signature"}
+    return json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+
+
+def sign_report(report_dict: dict, seed: bytes | None = None) -> dict:
+    """Return a copy of the report with a `signature` block attached.
+
+    The block carries the algorithm, the public key (hex), and the signature
+    (hex), so the report is self-contained for verification.
+    """
+    if seed is None:
+        seed = load_or_create_key()
+    pk = publickey(seed)
+    msg = _canonical(report_dict)
+    sig = signature(msg, seed, pk)
+    signed = dict(report_dict)
+    signed["signature"] = {
+        "algorithm": "ed25519",
+        "public_key": pk.hex(),
+        "signature": sig.hex(),
+        "signed_fields": "all fields except 'signature'",
+        "note": (
+            "Proves this report was not altered after issuance by the holder of "
+            "the public key. Does not prove production parity or independent review "
+            "— see the 'attestation' block."
+        ),
+    }
+    return signed
+
+
+def verify_report(report_dict: dict) -> tuple[bool, str]:
+    """Verify a signed report. Returns (ok, message).
+
+    Recomputes the canonical bytes over everything except the signature block and
+    checks the Ed25519 signature against the embedded public key.
+    """
+    sig_block = report_dict.get("signature")
+    if not sig_block:
+        return False, "report is not signed (no 'signature' block)"
+    if sig_block.get("algorithm") != "ed25519":
+        return False, f"unsupported algorithm: {sig_block.get('algorithm')}"
+    try:
+        pk = bytes.fromhex(sig_block["public_key"])
+        sig = bytes.fromhex(sig_block["signature"])
+    except (KeyError, ValueError) as e:
+        return False, f"malformed signature block: {e}"
+
+    msg = _canonical(report_dict)
+    if checkvalid(sig, msg, pk):
+        return True, f"signature valid — issued by key {pk.hex()[:16]}…"
+    return False, "signature INVALID — report was altered or key mismatch"