simple-module-ai 0.0.6__py3-none-any.whl

sm_ai/deps.py

@@ -0,0 +1,21 @@
+"""FastAPI dependencies for the AI module."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import Depends, Request
+from simple_module_db.deps import get_db
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from sm_ai.service import AiService
+
+
+async def get_ai_service(
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+) -> AiService:
+    return AiService(request.app, db)
+
+
+AiServiceDep = Annotated[AiService, Depends(get_ai_service)]

sm_ai/endpoints/api.py

@@ -0,0 +1,85 @@
+"""REST API for AI settings. Everything requires ai.manage."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+
+from fastapi import APIRouter, Depends
+from simple_module_hosting.permissions import RequiresPermission
+
+from sm_ai import constants, services
+from sm_ai.contracts.schemas import (
+    AiSettingsOut,
+    AiSettingsUpdate,
+    AiTestRequest,
+    AiTestResult,
+)
+from sm_ai.deps import AiServiceDep
+from sm_ai.service import AiService
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+_MANAGE = Depends(RequiresPermission(constants.PERM_MANAGE))
+
+
+@router.get("/settings", response_model=AiSettingsOut, dependencies=[_MANAGE])
+async def get_settings() -> AiSettingsOut:
+    # No AiServiceDep: current() only reads the module-global holder, and the
+    # dependency would open a DB session the read never touches.
+    return AiService.current()
+
+
+@router.put("/settings", response_model=AiSettingsOut, dependencies=[_MANAGE])
+async def update_settings(data: AiSettingsUpdate, service: AiServiceDep) -> AiSettingsOut:
+    changes = AiService.build_changes(data)
+    if not changes:
+        return service.current()
+    return await service.apply(changes)
+
+
+@router.post("/test", response_model=AiTestResult, dependencies=[_MANAGE])
+async def test_connection(data: AiTestRequest) -> AiTestResult:
+    """One tiny real call through the configured slot.
+
+    The only place this module itself calls a provider. Every failure —
+    missing config, unreadable key, bad URL, auth error, timeout — comes back
+    as ``ok: false`` with the message; a wrong URL is a result, not a 500.
+    """
+    from pydantic_ai import Agent
+
+    from sm_ai import resolve
+
+    started = time.monotonic()
+    label = ""
+    try:
+        # One snapshot for both the label and the probe — a concurrent save
+        # must not make the reported model describe a different configuration
+        # than the one actually exercised.
+        settings = services.current_settings()
+        async with asyncio.timeout(constants.TEST_TIMEOUT_SECONDS):
+            if data.slot == constants.SLOT_CHAT:
+                label = settings.chat_model
+                agent = Agent(resolve.build_chat_model(settings))
+                await agent.run(constants.TEST_PROMPT)
+            else:
+                label = settings.embedding_model
+                await resolve.build_embedder(settings).embed_query(constants.TEST_PROMPT)
+    except TimeoutError:
+        return AiTestResult(
+            ok=False,
+            model=label,
+            error=f"Timed out after {constants.TEST_TIMEOUT_SECONDS}s.",
+        )
+    except Exception as exc:  # a failed probe is a result, not a bug
+        # ... but log it server-side with the traceback: without this an
+        # actual code defect (e.g. a pydantic-ai API change) is
+        # indistinguishable from a config problem in the inline error string.
+        logger.warning("AI %s test probe failed", data.slot, exc_info=exc)
+        return AiTestResult(ok=False, model=label, error=str(exc) or type(exc).__name__)
+    return AiTestResult(
+        ok=True, model=label, latency_ms=int((time.monotonic() - started) * 1000)
+    )

sm_ai/endpoints/views.py

@@ -0,0 +1,28 @@
+"""Inertia view endpoints for the AI module."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+from inertia import InertiaResponse
+from simple_module_hosting.inertia_deps import InertiaDep
+from simple_module_hosting.permissions import RequiresPermission
+
+from sm_ai import constants
+
+router = APIRouter()
+
+
+@router.get(
+    "/",
+    response_model=None,
+    dependencies=[Depends(RequiresPermission(constants.PERM_MANAGE))],
+)
+async def settings_page(inertia: InertiaDep) -> InertiaResponse:
+    # Settings are fetched client-side from /api/ai/settings so a save can
+    # refresh without a full Inertia round trip.
+    #
+    # The page name comes from the constant, matching news and this repo's
+    # check_hardcoded_strings. The framework's own modules inline the literal
+    # instead, for the SM003/SM004 static-AST pairing — the two conventions
+    # disagree, and an in-repo module follows the in-repo linter.
+    return await inertia.render(constants._PAGE_SETTINGS)

sm_ai/module.py

@@ -0,0 +1,100 @@
+"""AI base module — connection configuration and the resolve service layer.
+
+Provides no AI features of its own. Other modules depend on it for
+``sm_ai.contracts`` (resolve_model / resolve_embedder) and its settings page;
+consumers own agents, prompts and behaviour. There are no tables and no
+migrations: configuration lives in the shared settings store.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import weakref
+
+from fastapi import APIRouter, Depends, FastAPI
+from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
+from simple_module_core.module import ModuleBase, ModuleMeta
+from simple_module_core.permissions import PermissionRegistry
+
+from sm_ai import constants
+
+_VERSION = importlib.metadata.version("simple_module_ai")
+
+
+class AiModule(ModuleBase):
+    meta = ModuleMeta(
+        name=constants.MODULE_NAME,
+        route_prefix=constants.ROUTE_PREFIX_API,
+        view_prefix=constants.VIEW_PREFIX,
+        depends_on=[constants._MODULE_SETTINGS],
+        version=_VERSION,
+        # The framework API version (1.0.0) is decoupled from the framework
+        # package version (0.0.x) — this range is correct as written.
+        requires_framework=">=1.0,<2.0",
+    )
+
+    def register_settings(self, app: FastAPI) -> None:
+        from settings.registration import register_module_settings
+
+        from sm_ai import crypto, services
+        from sm_ai.settings import AiSettings
+
+        # The factory installs the instance in the module-global holder AND
+        # returns it for app.state.sm_ai — one shared object, so hydration and
+        # hot reload (which assign .settings on it) are visible to contracts.
+        register_module_settings(
+            app,
+            constants.PACKAGE,
+            AiSettings,
+            lambda s: services.install(services.AiServices(settings=s)),
+        )
+
+        # Hosts may inject ``secret_key`` programmatically
+        # (``create_app(settings=...)``) rather than via env/.env; crypto must
+        # encrypt under the secret the running app actually holds or stored
+        # keys become unreadable. app.state.sm is assigned after this phase,
+        # so resolve lazily — through a weakref, because the provider is a
+        # process-global and a strong closure would keep a discarded app's
+        # whole object graph alive (app-factory test suites build many).
+        app_ref = weakref.ref(app)
+
+        def _live_secret() -> str:
+            live_app = app_ref()
+            if live_app is None:
+                return ""
+            sm = getattr(live_app.state, "sm", None)
+            return getattr(getattr(sm, "settings", None), "secret_key", "") or ""
+
+        crypto.set_secret_provider(_live_secret)
+
+    def register_permissions(self, registry: PermissionRegistry) -> None:
+        registry.add_group(constants.MODULE_NAME, [constants.PERM_MANAGE])
+
+    def register_menu_items(self, registry: MenuRegistry) -> None:
+        registry.add(
+            MenuItem(
+                label="AI",
+                url=constants.MENU_URL,
+                icon=constants.MENU_ICON,
+                order=constants.MENU_ORDER,
+                section=MenuSection.SIDEBAR,
+                group=constants.MENU_GROUP,
+                roles=["admin"],
+            )
+        )
+
+    def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
+        from sm_ai.endpoints.api import router as api
+        from sm_ai.endpoints.views import router as views
+        from sm_ai.security import mint_csrf_token, verify_csrf
+
+        # The write surface can redirect chat_base_url and thereby point the
+        # stored provider key at an attacker's server — CSRF is enforced on
+        # the API (unsafe methods) and the token minted on the admin view.
+        api_router.include_router(api, dependencies=[Depends(verify_csrf)])
+        view_router.include_router(views, dependencies=[Depends(mint_csrf_token)])
+
+    def register_middleware(self, app: FastAPI) -> None:
+        from sm_ai.security import CsrfCookieMiddleware
+
+        app.add_middleware(CsrfCookieMiddleware)

sm_ai/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@simple-module-py/ai",
+  "version": "0.0.6",
+  "private": true,
+  "description": "Frontend assets for the AI module",
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@inertiajs/react": "^2.0.0",
+    "@simple-module-py/ui": "*",
+    "sonner": "^2.0.0"
+  },
+  "devDependencies": {
+    "@simple-module-py/tsconfig": "*"
+  },
+  "dependencies": {}
+}

sm_ai/pages/Settings.tsx

@@ -0,0 +1,157 @@
+import { Head } from '@inertiajs/react';
+import { PageShell } from '@simple-module-py/ui/components/PageShell';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { AuthenticatedLayout } from '@simple-module-py/ui/layouts/AuthenticatedLayout';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { toast } from 'sonner';
+
+import { SlotCard } from '../components/SlotCard';
+import {
+  type AiSettingsOut,
+  loadSettings,
+  type SlotValues,
+  saveSettings,
+  type TestResult,
+  testSlot,
+} from '../utils/api';
+
+const emptySlot = (): SlotValues => ({
+  provider: '',
+  model: '',
+  base_url: '',
+  api_key: '',
+  clear_key: false,
+});
+
+function fromSettings(s: AiSettingsOut): { chat: SlotValues; embedding: SlotValues } {
+  return {
+    chat: {
+      provider: s.chat_provider,
+      model: s.chat_model,
+      base_url: s.chat_base_url,
+      api_key: '',
+      clear_key: false,
+    },
+    embedding: {
+      provider: s.embedding_provider,
+      model: s.embedding_model,
+      base_url: s.embedding_base_url,
+      api_key: '',
+      clear_key: false,
+      dim: s.embedding_dim,
+    },
+  };
+}
+
+export default function Settings() {
+  const [loaded, setLoaded] = useState<AiSettingsOut | null>(null);
+  const [chat, setChat] = useState<SlotValues>(emptySlot());
+  const [embedding, setEmbedding] = useState<SlotValues>(emptySlot());
+  const [busy, setBusy] = useState(false);
+  const [chatTest, setChatTest] = useState<TestResult | null>(null);
+  const [embeddingTest, setEmbeddingTest] = useState<TestResult | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  // One hydration path for both the initial load and the post-save read-back,
+  // so the editable state cannot drift from `loaded` in just one of them.
+  const hydrate = useCallback((s: AiSettingsOut) => {
+    setLoaded(s);
+    const slots = fromSettings(s);
+    setChat(slots.chat);
+    setEmbedding(slots.embedding);
+  }, []);
+
+  useEffect(() => {
+    loadSettings()
+      .then(hydrate)
+      .catch((err) => setError((err as Error).message));
+  }, [hydrate]);
+
+  async function run(work: () => Promise<void>, errorMsg: string) {
+    setBusy(true);
+    try {
+      await work();
+    } catch (err) {
+      toast.error(`${errorMsg}: ${(err as Error).message}`);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const save = () =>
+    run(async () => {
+      hydrate(await saveSettings(chat, embedding));
+      // Results describe the previous configuration — drop them.
+      setChatTest(null);
+      setEmbeddingTest(null);
+      toast.success('AI settings saved');
+    }, 'Save failed');
+
+  // The probe runs against *saved* settings; testing with unsaved edits
+  // would report on the old configuration and mislead either way.
+  // Field-by-field, not JSON.stringify: serialized equality is key-order and
+  // missing-vs-undefined sensitive (chat slots carry no `dim`), so equal
+  // states could compare unequal and disable Test with no visible reason.
+  const isDirty = (slot: SlotValues, saved: SlotValues) =>
+    slot.provider !== saved.provider ||
+    slot.model !== saved.model ||
+    slot.base_url !== saved.base_url ||
+    slot.api_key !== '' ||
+    slot.clear_key ||
+    (slot.dim ?? 0) !== (saved.dim ?? 0);
+  const savedSlots = useMemo(() => (loaded ? fromSettings(loaded) : null), [loaded]);
+
+  const test = (slot: 'chat' | 'embedding') =>
+    run(async () => {
+      const result = await testSlot(slot);
+      (slot === 'chat' ? setChatTest : setEmbeddingTest)(result);
+    }, 'Test failed');
+
+  return (
+    <AuthenticatedLayout>
+      <Head title="AI Settings" />
+      <PageShell
+        title="AI"
+        description="Connection settings for the chat and embedding providers every module shares."
+      >
+        {error && <p className="text-sm text-destructive">{error}</p>}
+        {!loaded && !error && <p className="text-sm text-muted-foreground">Loading…</p>}
+        {loaded && savedSlots && (
+          <div className="space-y-6">
+            <SlotCard
+              title="Chat"
+              description="The model modules use for text generation."
+              idPrefix="ai-chat"
+              providers={loaded.chat_providers}
+              optionalSlot={false}
+              values={chat}
+              hasStoredKey={loaded.has_chat_api_key}
+              dirty={isDirty(chat, savedSlots.chat)}
+              busy={busy}
+              testResult={chatTest}
+              onChange={setChat}
+              onTest={() => test('chat')}
+            />
+            <SlotCard
+              title="Embeddings"
+              description="Optional second endpoint for vector embeddings."
+              idPrefix="ai-embedding"
+              providers={loaded.embedding_providers}
+              optionalSlot={true}
+              values={embedding}
+              hasStoredKey={loaded.has_embedding_api_key}
+              dirty={isDirty(embedding, savedSlots.embedding)}
+              busy={busy}
+              testResult={embeddingTest}
+              onChange={setEmbedding}
+              onTest={() => test('embedding')}
+            />
+            <Button type="button" disabled={busy} onClick={save}>
+              Save
+            </Button>
+          </div>
+        )}
+      </PageShell>
+    </AuthenticatedLayout>
+  );
+}

sm_ai/resolve.py

@@ -0,0 +1,131 @@
+"""Build Pydantic AI model / embedder objects from AiSettings.
+
+Pure construction — no network I/O. Provider and auth failures surface in the
+consumer's ``agent.run()`` where they belong. Objects are built per call:
+construction is cheap, pydantic-ai's shared HTTP client keeps pooling, and a
+settings save applies on the very next call.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sm_ai import constants, crypto
+from sm_ai.contracts.errors import AiNotConfiguredError
+
+if TYPE_CHECKING:
+    from pydantic_ai import Embedder
+    from pydantic_ai.models import Model
+
+    from sm_ai.settings import AiSettings
+
+def _slot_inputs(
+    settings: AiSettings,
+    slot: str,
+    allowed: tuple[str, ...],
+    model_override: str | None = None,
+) -> tuple[str, str, str, str]:
+    """Validate one slot's settings; returns (provider_id, model, key, base_url).
+
+    The single validation path for both slots — provider membership, model
+    presence, key decryption, and the openai_compatible base_url requirement
+    (with the placeholder-key substitution) live here once.
+    """
+    provider_id = getattr(settings, f"{slot}_provider").strip().lower()
+    if not provider_id and slot == constants.SLOT_EMBEDDING:
+        raise AiNotConfiguredError(
+            "embedding_provider", "The embedding slot is not configured."
+        )
+    if provider_id not in allowed:
+        hint = (
+            "Anthropic does not offer an embeddings API."
+            if slot == constants.SLOT_EMBEDDING
+            and provider_id == constants.PROVIDER_ANTHROPIC
+            else f"Unknown provider {provider_id!r}; expected one of "
+            f"{', '.join(allowed)}."
+        )
+        raise AiNotConfiguredError(f"{slot}_provider", hint)
+    model = (model_override or getattr(settings, f"{slot}_model")).strip()
+    if not model:
+        raise AiNotConfiguredError(f"{slot}_model")
+
+    key = crypto.decrypt_value(getattr(settings, f"{slot}_api_key"), f"{slot}_api_key")
+    base_url = getattr(settings, f"{slot}_base_url").strip()
+
+    if provider_id == constants.PROVIDER_OPENAI_COMPATIBLE:
+        if not base_url:
+            raise AiNotConfiguredError(
+                f"{slot}_base_url",
+                "The openai_compatible provider needs the server's /v1 URL.",
+            )
+        # vLLM and friends ignore the key but the protocol wants a value.
+        key = key or constants.PLACEHOLDER_API_KEY
+    elif not key:
+        raise AiNotConfiguredError(f"{slot}_api_key")
+    return provider_id, model, key, base_url
+
+
+def build_chat_model(settings: AiSettings, model_name: str | None = None) -> Model:
+    """A ready chat model for the configured provider.
+
+    ``model_name`` overrides the configured name for same-endpoint
+    multi-model setups (e.g. a vision and a text model on one vLLM server).
+    """
+    provider_id, name, key, base_url = _slot_inputs(
+        settings, constants.SLOT_CHAT, constants.CHAT_PROVIDERS, model_name
+    )
+
+    if provider_id in (constants.PROVIDER_OPENAI, constants.PROVIDER_OPENAI_COMPATIBLE):
+        return _openai_chat(name, base_url, key)
+
+    if provider_id == constants.PROVIDER_ANTHROPIC:
+        from pydantic_ai.models.anthropic import AnthropicModel
+        from pydantic_ai.providers.anthropic import AnthropicProvider
+
+        kwargs = {"base_url": base_url} if base_url else {}
+        return AnthropicModel(name, provider=AnthropicProvider(api_key=key, **kwargs))
+
+    # google — GoogleProvider wires base_url into the genai client's
+    # http_options, so a gateway override routes exactly like the other
+    # providers' plain kwarg.
+    from pydantic_ai.models.google import GoogleModel
+    from pydantic_ai.providers.google import GoogleProvider
+
+    kwargs = {"base_url": base_url} if base_url else {}
+    return GoogleModel(name, provider=GoogleProvider(api_key=key, **kwargs))
+
+
+def _openai_chat(name: str, base_url: str, key: str) -> Model:
+    from pydantic_ai.models.openai import OpenAIChatModel
+    from pydantic_ai.providers.openai import OpenAIProvider
+
+    kwargs = {"base_url": base_url} if base_url else {}
+    return OpenAIChatModel(name, provider=OpenAIProvider(api_key=key, **kwargs))
+
+
+def build_embedder(settings: AiSettings) -> Embedder:
+    """A ready ``Embedder`` for the configured embedding slot."""
+    from pydantic_ai import Embedder
+
+    provider_id, name, key, base_url = _slot_inputs(
+        settings, constants.SLOT_EMBEDDING, constants.EMBEDDING_PROVIDERS
+    )
+
+    if provider_id in (constants.PROVIDER_OPENAI, constants.PROVIDER_OPENAI_COMPATIBLE):
+        return Embedder(_openai_embedding(name, base_url, key))
+
+    from pydantic_ai.embeddings.google import GoogleEmbeddingModel
+    from pydantic_ai.providers.google import GoogleProvider
+
+    kwargs = {"base_url": base_url} if base_url else {}
+    return Embedder(
+        GoogleEmbeddingModel(name, provider=GoogleProvider(api_key=key, **kwargs))
+    )
+
+
+def _openai_embedding(name: str, base_url: str, key: str):
+    from pydantic_ai.embeddings.openai import OpenAIEmbeddingModel
+    from pydantic_ai.providers.openai import OpenAIProvider
+
+    kwargs = {"base_url": base_url} if base_url else {}
+    return OpenAIEmbeddingModel(name, provider=OpenAIProvider(api_key=key, **kwargs))

sm_ai/security.py

@@ -0,0 +1,133 @@
+"""CSRF protection for the AI settings endpoints.
+
+This module stores provider API keys, and its write surface can redirect
+``chat_base_url`` — a forged cross-site PUT could point the stored key at an
+attacker's server. The admin API therefore enforces ``X-CSRF-Token`` the same
+way pagebuilder's does: a per-session token minted on the admin view, mirrored
+to a JS-readable cookie for the fetch client, and verified in constant time on
+every unsafe method.
+
+Adapted from ``pagebuilder.security`` rather than imported — a base module
+must not depend on a sibling optional module at runtime. Kept always-on and
+without the Inertia shared-prop channel: the settings page talks to the API
+via fetch, so the cookie is the only client channel it needs. Enforcement is
+skipped when no session is mounted (bare-FastAPI test harnesses) because
+without a session there is nothing to bind the token to.
+"""
+
+from __future__ import annotations
+
+import logging
+import secrets
+
+from fastapi import HTTPException, Request
+from starlette.datastructures import MutableHeaders
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from sm_ai import constants
+
+logger = logging.getLogger(__name__)
+
+_CSRF_SESSION_KEY = "sm_ai_csrf_token"
+_warned_no_session = False
+_UNSAFE_METHODS = frozenset({"POST", "PUT", "PATCH", "DELETE"})
+
+
+def mint_csrf_token(request: Request) -> None:
+    """View-router dependency: ensure the session carries a CSRF token.
+
+    ``CsrfCookieMiddleware`` mirrors it to the JS-readable cookie on the
+    response. No-op without a session — there is no anchor to bind to.
+    """
+    session = request.scope.get("session")
+    if session is None:
+        return
+    if not session.get(_CSRF_SESSION_KEY):
+        session[_CSRF_SESSION_KEY] = secrets.token_urlsafe(32)
+
+
+async def verify_csrf(request: Request) -> None:
+    """API-router dependency: enforce ``X-CSRF-Token`` on unsafe methods."""
+    if request.method not in _UNSAFE_METHODS:
+        return
+    session = request.scope.get("session")
+    if session is None:
+        # Fail-open by design (no session, nothing to bind a token to — see
+        # module docstring), but never silently: a host that mounts these
+        # routers without SessionMiddleware should know writes are unguarded.
+        global _warned_no_session
+        if not _warned_no_session:
+            _warned_no_session = True
+            logger.warning(
+                "CSRF enforcement skipped: no session middleware is mounted, "
+                "so the AI settings write API is unprotected against "
+                "cross-site requests."
+            )
+        return
+    expected = session.get(_CSRF_SESSION_KEY)
+    received = request.headers.get(constants.CSRF_HEADER)
+    if (
+        not expected
+        or not received
+        # Bytes, not str: compare_digest raises TypeError on non-ASCII str
+        # (headers decode as latin-1), which would turn a bad token into a
+        # 500 instead of this 403.
+        or not secrets.compare_digest(
+            str(expected).encode(), received.encode("latin-1")
+        )
+    ):
+        raise HTTPException(status_code=403, detail="Invalid or missing CSRF token")
+
+
+class CsrfCookieMiddleware:
+    """Mirror the session's CSRF token to a JS-readable cookie.
+
+    A middleware (not the mint dep) because FastAPI doesn't merge a
+    dependency's cookie writes into a ``Response`` returned by the handler.
+    Requests outside the module's prefixes skip the wrapper, and no
+    ``Set-Cookie`` is emitted when the request already carried the current
+    token.
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+        self._prefixes = (constants.ROUTE_PREFIX_API, constants.VIEW_PREFIX)
+        self._cookie_attr = f"{constants.CSRF_COOKIE}="
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        path = scope.get("path", "")
+        # Segment boundary, not bare startswith - "/ai" must not claim a
+        # future "/ai-other" route's responses.
+        if scope["type"] != "http" or not any(
+            path == p or path.startswith(p + "/") for p in self._prefixes
+        ):
+            await self.app(scope, receive, send)
+            return
+
+        async def send_wrapper(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                session = scope.get("session")
+                token = (
+                    session.get(_CSRF_SESSION_KEY) if isinstance(session, dict) else None
+                )
+                if token and _request_cookie_value(scope, self._cookie_attr) != token:
+                    headers = MutableHeaders(scope=message)
+                    cookie = f"{constants.CSRF_COOKIE}={token}; Path=/; SameSite=Strict"
+                    if scope.get("scheme") == "https":
+                        # Not unconditional: dev runs plain HTTP on loopback.
+                        cookie += "; Secure"
+                    headers.append("set-cookie", cookie)
+            await send(message)
+
+        await self.app(scope, receive, send_wrapper)
+
+
+def _request_cookie_value(scope: Scope, attr: str) -> str | None:
+    """Read one cookie value without re-parsing the whole header per request."""
+    for name, value in scope.get("headers", ()):
+        if name == b"cookie":
+            for piece in value.decode("latin-1").split(";"):
+                trimmed = piece.lstrip()
+                if trimmed.startswith(attr):
+                    return trimmed[len(attr) :]
+    return None