keble-scraper-api 0.2.0__py3-none-any.whl

keble_scraper_api/application/auth.py

@@ -0,0 +1,324 @@
+"""Truth-backed Google sign-in, encrypted sessions, and static service keys."""
+
+from __future__ import annotations
+
+import asyncio
+import hmac
+from datetime import UTC, datetime, timedelta
+
+import httpx
+from cryptography.fernet import Fernet
+from keble_helpers.typings import PydanticModelConfig
+from pydantic import AliasChoices, BaseModel, Field, SecretStr
+
+from keble_scraper_contract import OperatorRole, OperatorSession
+
+from keble_scraper_api.errors import ScraperDomainError, ScraperErrorCode
+from keble_scraper_api.settings import RuntimeEnvironment, ScraperSettings
+
+
+class TruthUser(BaseModel):
+    """Validated Truth identity returned by the Google workspace exchange.
+
+    Side effects if changes:
+    - active-role/domain gates and encrypted browser sessions.
+    """
+
+    model_config = PydanticModelConfig.default(frozen=True, extra="ignore")
+
+    id: str | int
+    email: str
+    role: str
+    status: str
+
+
+class TruthExchange(BaseModel):
+    """Server-only Truth exchange result including the private bearer.
+
+    Side effects if changes:
+    - encrypted cookie contents; the bearer must never enter browser JSON.
+    """
+
+    model_config = PydanticModelConfig.default(frozen=True, extra="ignore")
+
+    access_token: str = Field(
+        min_length=16,
+        validation_alias=AliasChoices("accessToken", "access_token"),
+    )
+    expires_at: datetime | None = Field(
+        default=None,
+        validation_alias=AliasChoices("expiresAt", "expires_at"),
+    )
+    user: TruthUser
+
+
+class EncryptedSessionPayload(BaseModel):
+    """Backend-only encrypted cookie payload with non-exported Truth bearer.
+
+    Side effects if changes:
+    - session rotation and browser authentication continuity.
+    """
+
+    model_config = PydanticModelConfig.default(frozen=True, extra="forbid")
+
+    session: OperatorSession
+    truth_bearer: SecretStr | None = None
+
+
+class SessionCipher:
+    """Encrypt and validate HttpOnly session payloads.
+
+    Steps:
+    1. own one stable or development-only ephemeral Fernet key;
+    2. encrypt private Truth-backed session payloads;
+    3. decrypt and validate them before authorization.
+
+    Side effects if changes:
+    - all console authentication and stored Truth bearer secrecy.
+    """
+
+    def __init__(self, *, key: SecretStr | None) -> None:
+        """Use a configured stable key or an ephemeral local-development key.
+
+        Steps:
+        1. unwrap configured write-only material when present;
+        2. otherwise generate an ephemeral development key;
+        3. construct the authenticated Fernet cipher exactly once.
+
+        Side effects if changes:
+        - sessions survive deployment restarts only with configured secret material.
+        """
+
+        material = (
+            key.get_secret_value().encode()
+            if key is not None
+            else Fernet.generate_key()
+        )
+        self._fernet = Fernet(material)
+
+    def encrypt(self, *, payload: EncryptedSessionPayload) -> str:
+        """Serialize and encrypt one session cookie value.
+
+        Steps:
+        1. serialize the strict private payload using wire aliases;
+        2. authenticate and encrypt its exact bytes;
+        3. return URL-safe cookie text without exposing the bearer.
+
+        Side effects if changes:
+        - browser cookie bytes and future decryption compatibility.
+        """
+
+        return self._fernet.encrypt(
+            payload.model_dump_json(by_alias=True).encode()
+        ).decode()
+
+    async def decrypt(self, *, token: str) -> EncryptedSessionPayload:
+        """Decrypt, validate, and reject expired session material.
+
+        Steps:
+        1. perform CPU-bound authenticated decryption off the event loop;
+        2. validate the private payload against its strict Pydantic schema;
+        3. reject a structurally valid but expired operator session.
+
+        Side effects if changes:
+        - every protected admin API authorization decision;
+        - invalid Fernet tokens propagate to the dedicated HTTP auth handler.
+        """
+
+        raw = await asyncio.to_thread(self._fernet.decrypt, token.encode())
+        payload = EncryptedSessionPayload.model_validate_json(raw)
+        if payload.session.expires_at <= datetime.now(UTC):
+            raise ScraperDomainError(
+                code=ScraperErrorCode.AUTH_INVALID,
+                message="operator session has expired",
+            )
+        return payload
+
+
+class OperatorAuthService:
+    """Exchange Google credentials through Truth and issue safe sessions.
+
+    Steps:
+    1. exchange Google credentials only through the configured Truth service;
+    2. enforce active Keble role/domain policy;
+    3. mint encrypted production or explicit local-development sessions.
+
+    Side effects if changes:
+    - production identity, role authorization, and development bypass.
+    """
+
+    def __init__(self, *, settings: ScraperSettings, cipher: SessionCipher) -> None:
+        """Bind environment policy and encrypted session ownership.
+
+        Side effects if changes:
+        - all auth routes and admin dependencies.
+        """
+
+        self._settings = settings
+        self._cipher = cipher
+
+    async def google_login(self, *, credential: str) -> tuple[OperatorSession, str]:
+        """Post one Google ID token to Truth and mint an HttpOnly session.
+
+        Steps:
+        1. never store or return the submitted Google credential;
+        2. accept only active Keble roles and `@keble.ai` identities;
+        3. encrypt the Truth bearer server-side inside the cookie payload.
+
+        Side effects if changes:
+        - external Truth auth call and browser session creation.
+        """
+
+        if self._settings.truth_base_url is None:
+            raise ScraperDomainError(
+                code=ScraperErrorCode.CONFIGURATION_INVALID,
+                message="Truth authentication is not configured",
+            )
+        endpoint = (
+            str(self._settings.truth_base_url).rstrip("/")
+            + self._settings.truth_auth_path
+        )
+        async with httpx.AsyncClient(
+            timeout=self._settings.truth_timeout_seconds,
+            trust_env=False,
+        ) as client:
+            raw = await client.post(endpoint, json={"id_token": credential})
+        if not raw.is_success:
+            raise ScraperDomainError(
+                code=ScraperErrorCode.AUTH_INVALID,
+                message="Google workspace identity exchange failed",
+            )
+        exchange = await asyncio.to_thread(
+            TruthExchange.model_validate_json,
+            raw.content,
+        )
+        if exchange.user.status != "ACTIVE" or exchange.user.role not in {
+            role.value for role in OperatorRole
+        }:
+            raise ScraperDomainError(
+                code=ScraperErrorCode.AUTH_FORBIDDEN,
+                message="Truth identity is not an active Keble operator",
+            )
+        email = exchange.user.email.strip().lower()
+        if not email.endswith("@keble.ai"):
+            raise ScraperDomainError(
+                code=ScraperErrorCode.AUTH_FORBIDDEN,
+                message="Google identity is outside the Keble workspace",
+            )
+        configured_expiry = datetime.now(UTC) + timedelta(
+            hours=self._settings.session_hours
+        )
+        expires_at = min(
+            configured_expiry,
+            exchange.expires_at or configured_expiry,
+        )
+        session = OperatorSession(
+            user_id=str(exchange.user.id),
+            email=email,
+            role=OperatorRole(exchange.user.role),
+            expires_at=expires_at,
+            is_local=False,
+        )
+        cookie = self._cipher.encrypt(
+            payload=EncryptedSessionPayload(
+                session=session,
+                truth_bearer=SecretStr(exchange.access_token),
+            )
+        )
+        return session, cookie
+
+    def dev_login(self) -> tuple[OperatorSession, str]:
+        """Mint a visibly local principal only under the explicit development gate.
+
+        Steps:
+        1. require both development environment and explicit bypass enablement;
+        2. build a bounded visibly local operator session;
+        3. encrypt it without a Truth bearer.
+
+        Side effects if changes:
+        - local bypass access; production settings validation must remain aligned.
+        """
+
+        if (
+            self._settings.environment is not RuntimeEnvironment.DEVELOPMENT
+            or not self._settings.dev_auth_enabled
+        ):
+            raise ScraperDomainError(
+                code=ScraperErrorCode.AUTH_FORBIDDEN,
+                message="development authentication bypass is disabled",
+            )
+        session = OperatorSession(
+            user_id="local-scraper-operator",
+            email=self._settings.dev_auth_email,
+            role=self._settings.dev_auth_role,
+            expires_at=datetime.now(UTC)
+            + timedelta(hours=self._settings.session_hours),
+            is_local=True,
+        )
+        cookie = self._cipher.encrypt(
+            payload=EncryptedSessionPayload(session=session, truth_bearer=None)
+        )
+        return session, cookie
+
+    async def session_from_cookie(self, *, token: str | None) -> OperatorSession:
+        """Resolve a safe current session or fail closed.
+
+        Side effects if changes:
+        - every console read/mutation authorization dependency.
+        """
+
+        if token is None:
+            raise ScraperDomainError(
+                code=ScraperErrorCode.AUTH_INVALID,
+                message="operator session is required",
+            )
+        return (await self._cipher.decrypt(token=token)).session
+
+
+class StaticServiceKeyAuthorizer:
+    """Constant-time current/next service key rotation boundary.
+
+    Steps:
+    1. retain independent current and optional next keys;
+    2. compare supplied credentials in constant time;
+    3. reject absence and mismatch with one finite auth code.
+
+    Side effects if changes:
+    - Shopify submission/read access to scraper APIs.
+    """
+
+    def __init__(self, *, current: SecretStr, next_key: SecretStr | None) -> None:
+        """Bind one audience's rotation pair.
+
+        Side effects if changes:
+        - independent service credential rollout.
+        """
+
+        self._current = current
+        self._next = next_key
+
+    def authorize(self, *, supplied: str | None) -> None:
+        """Accept the current or next key and reject every absent/mismatched value.
+
+        Steps:
+        1. normalize an absent header to a non-matching value;
+        2. compare current and optional next keys independently;
+        3. reject unless at least one rotation key matches.
+
+        Side effects if changes:
+        - service API authentication.
+        """
+
+        candidate = supplied or ""
+        current_matches = hmac.compare_digest(
+            candidate,
+            self._current.get_secret_value(),
+        )
+        next_matches = self._next is not None and hmac.compare_digest(
+            candidate, self._next.get_secret_value()
+        )
+        if not current_matches and not next_matches:
+            raise ScraperDomainError(
+                code=ScraperErrorCode.AUTH_INVALID,
+                message="service credential is invalid",
+            )