ui-foundation-backend 4.25.0__tar.gz

ui_foundation_backend-4.25.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: ui-foundation-backend
+Version: 4.25.0
+Summary: The auth and security layer shared by FastAPI + SQLModel backends built on ui-foundation: sessions, sign-in limits, TOTP, error reporting, deploy checks, AI chats' OAuth.
+License-Expression: MIT
+Project-URL: Repository, https://github.com/Tristan2828/ui-foundation
+Project-URL: Changelog, https://github.com/Tristan2828/ui-foundation/blob/main/CHANGELOG.md
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi==0.141.1
+Requires-Dist: sqlmodel==0.0.42
+Requires-Dist: pydantic==2.13.5
+Requires-Dist: python-dotenv==1.2.3
+Requires-Dist: email-validator==2.3.0
+Provides-Extra: dev
+Requires-Dist: mypy==2.3.1; extra == "dev"
+Requires-Dist: pytest==9.1.1; extra == "dev"
+Requires-Dist: pytest-asyncio==1.4.0; extra == "dev"
+Requires-Dist: httpx==0.28.1; extra == "dev"
+Requires-Dist: aiosqlite==0.22.1; extra == "dev"
+
+# ui-foundation-backend
+
+The auth and security layer shared by the FastAPI + SQLModel backends of
+apps built on [ui-foundation](https://github.com/Tristan2828/ui-foundation):
+the half of every app's backend that apps never change on purpose. Import
+package `foundation_backend`. Released with `@tristan2828/ui-foundation`,
+under the same version number, from the same commit.
+
+## What's in it
+
+| Module | What it is |
+|---|---|
+| `config` | The settings it reads from the environment (database, cookies and sessions, sign-in limits, TOTP, error reporting, AI chats' OAuth, the seeded account) and `database_connect_args()` |
+| `db` | The async engine and the `get_session` dependency |
+| `models` | `User`, `Session`, `LoginFailure`, `RecoveryCode`, `PendingLogin`, `OAuthClient`, `OAuthCode`, `OAuthGrant` (table names `users`, `sessions`, …) |
+| `schemas` | `CamelModel`, `Page`, the sign-in and error-envelope schemas |
+| `security`, `totp`, `login_limits`, `rate_window` | Password and token hashing, the TOTP step, failed sign-in limits, an in-memory rate window |
+| `errors`, `error_reporting`, `openapi_responses` | Error bodies pinned to the contract, `report_error`, the shared `responses=` fragments |
+| `deploy_checks`, `spa` | What `APP_ENV=production` refuses to start with; the SPA mount with its client-route fallback |
+| `routers.auth` | `router` (login, the TOTP step, logout, me) and `register_router` (`POST /auth/register`), with `get_current_user` |
+| `routers.environment`, `routers.client_errors`, `routers.oauth` | `GET /environment`, `POST /client-errors`, AI chats' OAuth sign-in (off unless `MCP_ENABLED`) |
+| `scripts.set_password`, `scripts.enable_totp`, `scripts.disable_totp` | Run as `python -m foundation_backend.scripts.<name> <email>` from the app's `backend/` |
+| `testing.signed_in` | `session_cookie`, to sign a test client in for real |
+| `migrations/` | Reference copies of the Alembic revisions that create these tables; never run from here ([`migrations/README.md`](src/foundation_backend/migrations/README.md)) |
+
+An app keeps everything else: its entities, models, routers and
+migrations, and, in the template, MCP's tools, scheduled jobs and Web
+Push.
+
+## How an app uses it
+
+`backend/pyproject.toml` pins it to the release the app is on, the same
+version as its `@tristan2828/ui-foundation`:
+
+```toml
+dependencies = [
+  "ui-foundation-backend==4.25.0",
+  ...
+]
+```
+
+The app's own modules re-export it, so `from app.models import User`
+keeps working (the template's `app/config.py`, `db.py`, `models.py`,
+`schemas.py`, `openapi_responses.py`, `security.py`, `errors.py`, `spa.py`
+do this), and its `main.py` includes the routers it offers:
+
+```python
+from foundation_backend.routers import auth, client_errors, environment, oauth
+
+app.include_router(auth.router, prefix="/api")
+app.include_router(auth.register_router, prefix="/api")  # only if people make their own accounts
+app.include_router(client_errors.router, prefix="/api")
+app.include_router(environment.router, prefix="/api")
+app.include_router(oauth.router)  # only with AI chats (MCP)
+```
+
+**`register_router` is separate on purpose.** An app where accounts are
+made by whoever runs it leaves it out, with `/auth/register` out of its
+`openapi.yaml` (the path is `x-optional`) and `LoginRoute
+registerPath={null}`. Including `router` alone serves sign-in with no way
+to make an account through the API.
+
+A setting the package reads is changed at runtime (a test's
+`monkeypatch`) on `foundation_backend.config` or on the module that
+imported it, never on the app's re-export, which is a copy.
+
+Upgrading: bump the pin with the npm package, run the migrations the
+[changelog](https://github.com/Tristan2828/ui-foundation/blob/main/CHANGELOG.md)
+names for that release, then `npm run verify:backend`
+([`docs/consuming.md`](https://github.com/Tristan2828/ui-foundation/blob/main/docs/consuming.md)).
+
+## In this repo
+
+`template/backend/` depends on `ui-foundation-backend` unpinned. Install
+both editable **in one pip call**, so the dependency resolves to this
+folder and never to PyPI:
+
+```bash
+cd template/backend
+python -m venv .venv
+.venv/Scripts/python -m pip install -e ../../packages/backend-foundation -e ".[dev]"   # .venv/bin/python elsewhere
+```
+
+`template/backend/scripts/dev.sh` and the cloud session hook do this.
+Installing `template/backend` on its own would pull the published version
+(or fail before the first release), and its tests would run against code
+that isn't this commit's.
+
+`npm run verify:backend` (repo root) runs this package's gate,
+`scripts/verify.sh` (mypy strict, then pytest over SQLite against
+`tests/minimal_app.py`, an app made of the package alone), then the
+template's. On its own: `cd packages/backend-foundation && pytest`.
+
+## Releasing
+
+`.github/workflows/release.yml` builds it (`build-py`, with the release's
+version written into `pyproject.toml`) and publishes it to PyPI by trusted
+publishing (`publish-py`), beside the npm package, before tagging. The
+committed version in `pyproject.toml` is a floor, like
+`packages/ui-foundation/package.json`'s; keep the two the same.

ui_foundation_backend-4.25.0/README.md

@@ -0,0 +1,100 @@
+# ui-foundation-backend
+
+The auth and security layer shared by the FastAPI + SQLModel backends of
+apps built on [ui-foundation](https://github.com/Tristan2828/ui-foundation):
+the half of every app's backend that apps never change on purpose. Import
+package `foundation_backend`. Released with `@tristan2828/ui-foundation`,
+under the same version number, from the same commit.
+
+## What's in it
+
+| Module | What it is |
+|---|---|
+| `config` | The settings it reads from the environment (database, cookies and sessions, sign-in limits, TOTP, error reporting, AI chats' OAuth, the seeded account) and `database_connect_args()` |
+| `db` | The async engine and the `get_session` dependency |
+| `models` | `User`, `Session`, `LoginFailure`, `RecoveryCode`, `PendingLogin`, `OAuthClient`, `OAuthCode`, `OAuthGrant` (table names `users`, `sessions`, …) |
+| `schemas` | `CamelModel`, `Page`, the sign-in and error-envelope schemas |
+| `security`, `totp`, `login_limits`, `rate_window` | Password and token hashing, the TOTP step, failed sign-in limits, an in-memory rate window |
+| `errors`, `error_reporting`, `openapi_responses` | Error bodies pinned to the contract, `report_error`, the shared `responses=` fragments |
+| `deploy_checks`, `spa` | What `APP_ENV=production` refuses to start with; the SPA mount with its client-route fallback |
+| `routers.auth` | `router` (login, the TOTP step, logout, me) and `register_router` (`POST /auth/register`), with `get_current_user` |
+| `routers.environment`, `routers.client_errors`, `routers.oauth` | `GET /environment`, `POST /client-errors`, AI chats' OAuth sign-in (off unless `MCP_ENABLED`) |
+| `scripts.set_password`, `scripts.enable_totp`, `scripts.disable_totp` | Run as `python -m foundation_backend.scripts.<name> <email>` from the app's `backend/` |
+| `testing.signed_in` | `session_cookie`, to sign a test client in for real |
+| `migrations/` | Reference copies of the Alembic revisions that create these tables; never run from here ([`migrations/README.md`](src/foundation_backend/migrations/README.md)) |
+
+An app keeps everything else: its entities, models, routers and
+migrations, and, in the template, MCP's tools, scheduled jobs and Web
+Push.
+
+## How an app uses it
+
+`backend/pyproject.toml` pins it to the release the app is on, the same
+version as its `@tristan2828/ui-foundation`:
+
+```toml
+dependencies = [
+  "ui-foundation-backend==4.25.0",
+  ...
+]
+```
+
+The app's own modules re-export it, so `from app.models import User`
+keeps working (the template's `app/config.py`, `db.py`, `models.py`,
+`schemas.py`, `openapi_responses.py`, `security.py`, `errors.py`, `spa.py`
+do this), and its `main.py` includes the routers it offers:
+
+```python
+from foundation_backend.routers import auth, client_errors, environment, oauth
+
+app.include_router(auth.router, prefix="/api")
+app.include_router(auth.register_router, prefix="/api")  # only if people make their own accounts
+app.include_router(client_errors.router, prefix="/api")
+app.include_router(environment.router, prefix="/api")
+app.include_router(oauth.router)  # only with AI chats (MCP)
+```
+
+**`register_router` is separate on purpose.** An app where accounts are
+made by whoever runs it leaves it out, with `/auth/register` out of its
+`openapi.yaml` (the path is `x-optional`) and `LoginRoute
+registerPath={null}`. Including `router` alone serves sign-in with no way
+to make an account through the API.
+
+A setting the package reads is changed at runtime (a test's
+`monkeypatch`) on `foundation_backend.config` or on the module that
+imported it, never on the app's re-export, which is a copy.
+
+Upgrading: bump the pin with the npm package, run the migrations the
+[changelog](https://github.com/Tristan2828/ui-foundation/blob/main/CHANGELOG.md)
+names for that release, then `npm run verify:backend`
+([`docs/consuming.md`](https://github.com/Tristan2828/ui-foundation/blob/main/docs/consuming.md)).
+
+## In this repo
+
+`template/backend/` depends on `ui-foundation-backend` unpinned. Install
+both editable **in one pip call**, so the dependency resolves to this
+folder and never to PyPI:
+
+```bash
+cd template/backend
+python -m venv .venv
+.venv/Scripts/python -m pip install -e ../../packages/backend-foundation -e ".[dev]"   # .venv/bin/python elsewhere
+```
+
+`template/backend/scripts/dev.sh` and the cloud session hook do this.
+Installing `template/backend` on its own would pull the published version
+(or fail before the first release), and its tests would run against code
+that isn't this commit's.
+
+`npm run verify:backend` (repo root) runs this package's gate,
+`scripts/verify.sh` (mypy strict, then pytest over SQLite against
+`tests/minimal_app.py`, an app made of the package alone), then the
+template's. On its own: `cd packages/backend-foundation && pytest`.
+
+## Releasing
+
+`.github/workflows/release.yml` builds it (`build-py`, with the release's
+version written into `pyproject.toml`) and publishes it to PyPI by trusted
+publishing (`publish-py`), beside the npm package, before tagging. The
+committed version in `pyproject.toml` is a floor, like
+`packages/ui-foundation/package.json`'s; keep the two the same.

ui_foundation_backend-4.25.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "ui-foundation-backend"
+# The release workflow writes the release's version here, the same as
+# @tristan2828/ui-foundation's (packages/ui-foundation/package.json).
+version = "4.25.0"
+description = "The auth and security layer shared by FastAPI + SQLModel backends built on ui-foundation: sessions, sign-in limits, TOTP, error reporting, deploy checks, AI chats' OAuth."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+# Exactly the template backend's versions (template/backend/pyproject.toml),
+# so an app that pins the same ones resolves to one set.
+dependencies = [
+  "fastapi==0.141.1",
+  "sqlmodel==0.0.42",
+  "pydantic==2.13.5",
+  "python-dotenv==1.2.3",
+  "email-validator==2.3.0",
+]
+
+[project.urls]
+Repository = "https://github.com/Tristan2828/ui-foundation"
+Changelog = "https://github.com/Tristan2828/ui-foundation/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+  "mypy==2.3.1",
+  "pytest==9.1.1",
+  "pytest-asyncio==1.4.0",
+  "httpx==0.28.1",
+  "aiosqlite==0.22.1",
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+plugins = ["pydantic.mypy"]
+# Reference copies for an app to take, not modules of this package
+# (src/foundation_backend/migrations/README.md).
+exclude = ["src/foundation_backend/migrations/"]
+
+[[tool.mypy.overrides]]
+module = "alembic.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+foundation_backend = ["py.typed", "migrations/*.py", "migrations/README.md"]

ui_foundation_backend-4.25.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ui_foundation_backend-4.25.0/src/foundation_backend/__init__.py

@@ -0,0 +1,13 @@
+"""The auth and security layer every app built on ui-foundation shares
+(the PyPI package `ui-foundation-backend`). README.md says what is in it
+and how an app uses it.
+"""
+
+# The release version, the same as @tristan2828/ui-foundation's. The release
+# workflow writes it into pyproject.toml; this reads it back.
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("ui-foundation-backend")
+except PackageNotFoundError:  # imported from a source tree, not installed
+    __version__ = "0.0.0"

ui_foundation_backend-4.25.0/src/foundation_backend/config.py

@@ -0,0 +1,118 @@
+"""The settings the foundation's backend reads, each from the environment
+once, at import. An app's own `config.py` star-imports this module and
+adds its own settings after it; it calls `load_dotenv()` first, from its
+own file, so its `backend/.env` is read wherever the process starts.
+
+Here `.env` is looked for from the working directory up (`backend/` when
+the app runs, its scripts run, or `python -m foundation_backend.scripts.*`
+runs), since this file is installed in site-packages, not in the app.
+Values already in the environment win over the file's.
+"""
+
+import os
+import ssl
+
+from dotenv import find_dotenv, load_dotenv
+
+load_dotenv(find_dotenv(usecwd=True))
+
+DATABASE_URL: str = os.environ.get(
+    "DATABASE_URL",
+    "postgresql+asyncpg://ui_foundation:ui_foundation@localhost:5432/ui_foundation",
+)
+
+# Cloud Postgres support (docs/cloud-postgres.md).
+# asyncpg's own SSL flag — postgresql+asyncpg:// doesn't parse libpq's
+# sslmode= query param, so this can't be folded into DATABASE_URL itself.
+DATABASE_SSL: bool = os.environ.get("DATABASE_SSL", "false").lower() == "true"
+
+# Some managed providers (confirmed on Supabase) serve their Postgres TLS
+# cert from a private CA that isn't in the OS trust store, unlike their own
+# HTTPS endpoints — connecting with just DATABASE_SSL=true then fails
+# certificate verification. Point this at a local PEM file (that CA's root
+# cert) to verify against it explicitly instead of the system trust store.
+DATABASE_SSL_CA_FILE: str | None = os.environ.get("DATABASE_SSL_CA_FILE") or None
+
+
+def database_connect_args() -> dict[str, object]:
+    """asyncpg connect_args for DATABASE_URL — shared by db.py and an
+    app's migrations/env.py, which each construct their own engine."""
+    if not DATABASE_SSL:
+        return {}
+    if DATABASE_SSL_CA_FILE:
+        return {"ssl": ssl.create_default_context(cafile=DATABASE_SSL_CA_FILE)}
+    return {"ssl": True}
+
+# "production" turns on deploy_checks.py at startup: the app refuses to
+# start with an insecure cookie or a still-default seeded account. Anything
+# else (the default) is development, with no startup checks.
+APP_ENV: str = os.environ.get("APP_ENV", "development")
+
+# Which data this backend serves when it isn't production's: "dev" for a
+# dev branch of the hosted database, "local" for the docker-compose one.
+# Served unauthenticated at GET /api/environment, and the app names it in
+# a banner on every screen (DataEnvironmentBanner: "Dev data: changes here
+# don't reach production"). Unset, the default, means production data and
+# no banner; APP_ENV=production refuses to start with it set.
+DATA_LABEL: str | None = os.environ.get("DATA_LABEL", "").strip() or None
+
+# Session cookie. Local dev is plain
+# HTTP, so the Secure flag defaults off; a real deployment sets it.
+COOKIE_SECURE: bool = os.environ.get("COOKIE_SECURE", "false").lower() == "true"
+SESSION_TTL_DAYS: int = int(os.environ.get("SESSION_TTL_DAYS", "7"))
+
+# Failed sign-in limits (login_limits.py, docs/deploy.md). Over either,
+# POST /auth/login answers 429 before the password is checked. Per IP needs
+# uvicorn's --proxy-headers behind a proxy it trusts, or every request
+# appears to come from the proxy and this becomes one global limit.
+LOGIN_MAX_FAILURES_PER_IP: int = int(os.environ.get("LOGIN_MAX_FAILURES_PER_IP", "10"))
+LOGIN_IP_WINDOW_SECONDS: int = int(os.environ.get("LOGIN_IP_WINDOW_SECONDS", str(15 * 60)))
+LOGIN_MAX_FAILURES_PER_ACCOUNT: int = int(os.environ.get("LOGIN_MAX_FAILURES_PER_ACCOUNT", "20"))
+LOGIN_ACCOUNT_WINDOW_SECONDS: int = int(os.environ.get("LOGIN_ACCOUNT_WINDOW_SECONDS", str(60 * 60)))
+# A header a CDN or tunnel always overwrites with the client's address
+# (CF-Connecting-IP, True-Client-IP, Fly-Client-IP), read for the per-IP key
+# instead of X-Forwarded-For, which such proxies append to. Unset: ignored.
+# Safe only if every request reaches the app through that proxy.
+CLIENT_IP_HEADER: str | None = os.environ.get("CLIENT_IP_HEADER", "").strip() or None
+
+# The TOTP second step (totp.py): how long a sign-in waits for its code
+# after the password, and how many wrong codes it gets before it ends.
+PENDING_LOGIN_TTL_SECONDS: int = int(os.environ.get("PENDING_LOGIN_TTL_SECONDS", str(5 * 60)))
+PENDING_LOGIN_MAX_TRIES: int = int(os.environ.get("PENDING_LOGIN_MAX_TRIES", "5"))
+# The name an authenticator app lists the account under.
+TOTP_ISSUER: str = os.environ.get("TOTP_ISSUER", "UI Foundation")
+
+# Error reporting (error_reporting.py, docs/deploy.md "Error reporting").
+# A Sentry-compatible DSN (Sentry, or a self-hosted GlitchTip):
+# https://<key>@<host>/<project id>. Unset, the default, errors are only logged.
+ERROR_REPORTING_DSN: str | None = os.environ.get("ERROR_REPORTING_DSN", "").strip() or None
+# The build a report names: the commit, set by the deploy (unset is fine).
+RELEASE: str | None = os.environ.get("RELEASE", "").strip() or None
+# How many reports one session may send per minute from the browser, after
+# duplicates (the same error) are dropped to one a minute.
+CLIENT_ERRORS_PER_MINUTE: int = int(os.environ.get("CLIENT_ERRORS_PER_MINUTE", "10"))
+
+# AI chats reading and writing the app's records through MCP (an app's routers/mcp.py,
+# routers/oauth.py, docs/deploy.md "AI chats (MCP)"). Off by default: with
+# it off, /mcp, /oauth/* and the /.well-known/oauth-* documents answer 404.
+MCP_ENABLED: bool = os.environ.get("MCP_ENABLED", "false").lower() == "true"
+# The app's public https origin, e.g. https://app.example.com: the OAuth
+# issuer, and the base of every address the sign-in documents hand out.
+# Required when MCP_ENABLED and APP_ENV=production (a proxy hides the real
+# one from the app); in development the request's own is used.
+MCP_PUBLIC_URL: str | None = os.environ.get("MCP_PUBLIC_URL", "").strip().rstrip("/") or None
+MCP_ACCESS_TOKEN_TTL_SECONDS: int = int(os.environ.get("MCP_ACCESS_TOKEN_TTL_SECONDS", str(60 * 60)))
+MCP_REFRESH_TOKEN_TTL_DAYS: int = int(os.environ.get("MCP_REFRESH_TOKEN_TTL_DAYS", "30"))
+# How many AI chats may be registered at once, and how many requests one
+# connection may make a minute (counted in each worker's memory).
+MCP_MAX_CLIENTS: int = int(os.environ.get("MCP_MAX_CLIENTS", "50"))
+MCP_REQUESTS_PER_MINUTE: int = int(os.environ.get("MCP_REQUESTS_PER_MINUTE", "120"))
+
+# Seeded dev user (migration 0002). Not a
+# production credential; a real deployment sets its own before going live.
+# The defaults are published in the README, which is why production refuses
+# to start while any account still accepts DEFAULT_SEED_PASSWORD.
+DEFAULT_SEED_EMAIL = "dev@example.com"
+DEFAULT_SEED_PASSWORD = "dev-password-123"
+SEED_USER_EMAIL: str = os.environ.get("SEED_USER_EMAIL", DEFAULT_SEED_EMAIL)
+SEED_USER_PASSWORD: str = os.environ.get("SEED_USER_PASSWORD", DEFAULT_SEED_PASSWORD)

ui_foundation_backend-4.25.0/src/foundation_backend/db.py

@@ -0,0 +1,17 @@
+"""Async engine + session dependency. No repository layer on purpose —
+routers call the session directly.
+"""
+
+from collections.abc import AsyncGenerator
+
+from sqlmodel.ext.asyncio.session import AsyncSession
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from foundation_backend.config import DATABASE_URL, database_connect_args
+
+engine = create_async_engine(DATABASE_URL, echo=False, connect_args=database_connect_args())
+
+
+async def get_session() -> AsyncGenerator[AsyncSession, None]:
+    async with AsyncSession(engine) as session:
+        yield session

ui_foundation_backend-4.25.0/src/foundation_backend/deploy_checks.py

@@ -0,0 +1,105 @@
+"""Startup safety checks for APP_ENV=production (see docs/deploy.md).
+
+Development needs none of this and runs no startup query at all. A real
+deployment is refused outright rather than warned about: a warning in a log
+nobody reads is how a published default password ends up on the internet.
+"""
+
+import json
+from pathlib import Path
+
+from fastapi.concurrency import run_in_threadpool
+from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from foundation_backend.config import DEFAULT_SEED_EMAIL, DEFAULT_SEED_PASSWORD, SEED_USER_EMAIL
+from foundation_backend.models import User
+from foundation_backend.security import verify_password
+
+
+async def production_problems(
+    session: AsyncSession,
+    *,
+    cookie_secure: bool,
+    data_label: str | None = None,
+    mcp_enabled: bool = False,
+    mcp_public_url: str | None = None,
+    static_dir: str | None = None,
+) -> list[str]:
+    """Everything that makes this deployment unsafe to serve; empty if none.
+
+    `static_dir` is the built frontend (STATIC_DIR); None skips its check.
+    """
+    problems: list[str] = []
+
+    if static_dir is not None:
+        problem = frontend_build_problem(Path(static_dir))
+        if problem is not None:
+            problems.append(problem)
+
+    # A label says the data isn't production's, and the app shows it on
+    # every screen. Production serves production data, so a label here is
+    # a dev backend/.env deployed by mistake.
+    if data_label is not None:
+        problems.append(
+            f"DATA_LABEL is set ({data_label!r}); production data has no label, and every "
+            "screen would say it isn't production's. Unset it."
+        )
+
+    # Chats are sent to the issuer's address to sign in, and the OAuth
+    # documents name it; behind a proxy the app can't know it, and the
+    # protocol requires https.
+    if mcp_enabled and (mcp_public_url is None or not mcp_public_url.startswith("https://")):
+        problems.append(
+            "MCP_ENABLED is true but MCP_PUBLIC_URL is not an https:// address; AI chats can't "
+            "sign in without the app's public address (e.g. https://app.example.com)."
+        )
+
+    if not cookie_secure:
+        problems.append(
+            "COOKIE_SECURE is not true; the session cookie would be sent over plain HTTP."
+        )
+
+    # Migration 0002 seeds whatever SEED_USER_* held when it ran, so check
+    # the stored hash, not the environment: both the configured seed email
+    # and the published default one, in case the env changed after seeding.
+    for email in sorted({DEFAULT_SEED_EMAIL, SEED_USER_EMAIL}):
+        result = await session.exec(select(User).where(User.email == email))
+        user = result.first()
+        if user is not None and await run_in_threadpool(
+            verify_password, DEFAULT_SEED_PASSWORD, user.password_hash
+        ):
+            problems.append(
+                f"User {email} still accepts the published default password. Change it "
+                "with `python -m foundation_backend.scripts.set_password` before serving this deployment."
+            )
+
+    return problems
+
+
+BUILD_COMMAND = "Build it with `npm run build:real`, never a plain `npm run build`"
+
+
+def frontend_build_problem(static_dir: Path) -> str | None:
+    """Why the frontend at `static_dir` mustn't be served, or None.
+
+    The build writes build-info.json (the foundation's Vite plugin) saying
+    which API the bundle calls. A mock bundle runs MSW in the browser: the
+    app would show fake data to real users and save nothing, with nothing
+    saying so. A missing file means a build that predates the plugin, or
+    no build at all, so it can't be told apart and is refused too.
+    """
+    info_file = static_dir / "build-info.json"
+    try:
+        info = json.loads(info_file.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return f"The frontend has no {info_file}, so it can't be told from a mock build. {BUILD_COMMAND}."
+    except (OSError, ValueError):
+        return f"{info_file} can't be read as JSON. {BUILD_COMMAND}."
+    api = info.get("api") if isinstance(info, dict) else None
+    if api != "real":
+        return (
+            f"The frontend in {static_dir} was built with mocks (api: {api!r} in build-info.json); "
+            f"it would serve fake data. {BUILD_COMMAND}."
+        )
+    return None