feat(api): FastAPI skeleton with two-role RLS auth foundation

Phase 0's API half: a working FastAPI app with register/login/me/logout,
backed by a Postgres schema where row-level security is real and
independently proven, not just declared.

The core design decision, and the reason this lands as one PR instead of
several: request-scoped queries run as `velodrome_app` (NOBYPASSRLS), but
looking up identity in the first place — login by email, a session by its
token hash — has to happen *before* app.user_id can be set, so those specific
lookups run as a second role, `velodrome_auth` (BYPASSRLS), used nowhere else
in the codebase. See velodrome/db.py's module docstring and apps/api/README.md
for the full rationale. This is genuinely one reviewable unit: the migration,
the models, and the auth service only make sense evaluated together, since
they're three views of the same invariant.

tests/test_auth.py::test_rls_blocks_cross_user_session_reads is the test
worth reading first — it doesn't trust the RLS policy SQL because it reads
correctly, it proves isolation by registering two users and confirming a
scoped read of `sessions` for user A returns exactly one row, never two.

Bugs found and fixed while actually running this against real Postgres
(everything below was verified against a live postgis/postgis:16-3.4
container and a built Docker image, not just read for correctness):

- CREATE ROLE's PASSWORD clause is DDL, not DML — it doesn't accept bind
  parameters (`PASSWORD $1` is a syntax error). Fixed with dollar-quoting.
- Postgres roles are cluster-wide, not per-database — a second database in
  the same cluster hit "role already exists" on a plain CREATE ROLE. Fixed
  with a DO block catching duplicate_object.
- A bare `Mapped[datetime]` on the ORM models infers a naive timestamp,
  silently disagreeing with the migration's correct `DateTime(timezone=True)`
  — asyncpg rejected the mismatch at insert time. Fixed once, at the
  declarative Base level via type_annotation_map, rather than per-column.
- The session cookie's `secure` flag was gated on `!= "development"`, so
  anything else — including local testing and a real deploy running
  temporarily without TLS in front — got a Secure cookie no HTTP client
  will ever send back, breaking every authenticated request after login
  with no visible error. Gated on `== "production"` instead.
- `alembic check` initially flagged every PostGIS/TIGER-installed table
  (dozens of them) as drift, because they're not in our metadata. A
  schema-based denylist doesn't work — reflected foreign tables come back
  with schema=None regardless of their real schema. Fixed with an
  allowlist keyed on target_metadata.tables instead, which is also more
  robust against future PostGIS versions adding more tables.
- The migration itself was missing `nullable=False` on three timestamp
  columns that the ORM model assumed were never null — a genuine
  model/migration drift that alembic check caught once the PostGIS noise
  above was filtered out. Fixed in 0001 directly, since it's never shipped.
- Two indexes the migration creates explicitly weren't declared on the
  ORM models, causing the same kind of drift. Added index=True to match.

Deliberately deferred, not forgotten: per-IP/per-account login rate
limiting (docs/PLAN.md mentions it; Phase 0's bar is a working skeleton,
and this needs its own design pass) and the procrastinate job runner /
worker container (nothing to run yet — arrives with the ingestion
pipeline).

ci.yml updated to match: the api and migrations jobs now provision the
same two runtime roles this code actually needs, replacing the single
placeholder DATABASE_URL from before any code existed.

Verified: ruff check, ruff format --check, and mypy --strict all clean.
12/12 pytest passing against a real Postgres. Full alembic upgrade ->
downgrade -1 -> upgrade cycle run twice (once standalone, once inside a
two-database cluster to specifically catch the role-collision bug).
alembic check clean. Docker image builds and serves real traffic —
register and an authenticated GET /me both exercised against the actual
built container, not just the test suite.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

apps/api/velodrome/db.py

@@ -0,0 +1,113 @@
+"""Two database engines, on purpose.
+
+`app` engine: connects as a role with RLS enforced (NOBYPASSRLS). Every request handler that has
+already established who the caller is uses this, wrapped in `scoped_session()` below, which sets
+`app.user_id` for the transaction so RLS policies can key off it.
+
+`auth` engine: connects as a role with BYPASSRLS. Used ONLY by velodrome.auth.service, and only
+for the narrow set of queries that must run *before* identity is known — looking a user up by
+email at login, a session up by its hashed token, an invite up by its hashed code — plus the
+inserts that create those rows in the first place. Nothing outside auth/service.py should import
+this engine; if you find yourself reaching for it elsewhere, the query almost certainly belongs
+in a repository method on the scoped session instead (see CLAUDE.md invariant #4).
+"""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from uuid import UUID
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.pool import NullPool
+
+from velodrome.config import get_settings
+
+
+def _make_engine(url: str) -> AsyncEngine:
+    settings = get_settings()
+    # NullPool in dev/test keeps behaviour predictable across the pytest-asyncio event loop;
+    # production tuning (pool_size etc.) is a deploy-time concern, not a Phase-0 one.
+    return create_async_engine(
+        url,
+        poolclass=NullPool if settings.environment == "test" else None,
+        echo=False,
+    )
+
+
+_app_engine: AsyncEngine | None = None
+_auth_engine: AsyncEngine | None = None
+
+
+def app_engine() -> AsyncEngine:
+    global _app_engine
+    if _app_engine is None:
+        _app_engine = _make_engine(str(get_settings().database_url_app))
+    return _app_engine
+
+
+def auth_engine() -> AsyncEngine:
+    global _auth_engine
+    if _auth_engine is None:
+        _auth_engine = _make_engine(str(get_settings().database_url_auth))
+    return _auth_engine
+
+
+_app_sessionmaker: async_sessionmaker[AsyncSession] | None = None
+_auth_sessionmaker: async_sessionmaker[AsyncSession] | None = None
+
+
+def _app_sessions() -> async_sessionmaker[AsyncSession]:
+    global _app_sessionmaker
+    if _app_sessionmaker is None:
+        _app_sessionmaker = async_sessionmaker(app_engine(), expire_on_commit=False)
+    return _app_sessionmaker
+
+
+def _auth_sessions() -> async_sessionmaker[AsyncSession]:
+    global _auth_sessionmaker
+    if _auth_sessionmaker is None:
+        _auth_sessionmaker = async_sessionmaker(auth_engine(), expire_on_commit=False)
+    return _auth_sessionmaker
+
+
+@asynccontextmanager
+async def auth_session() -> AsyncIterator[AsyncSession]:
+    """A BYPASSRLS session. See module docstring — auth/service.py only."""
+    async with _auth_sessions()() as session:
+        yield session
+
+
+@asynccontextmanager
+async def scoped_session(user_id: UUID) -> AsyncIterator[AsyncSession]:
+    """An RLS-scoped session for a known, authenticated user.
+
+    `SET LOCAL` binds to the current transaction, not the connection, so this is safe under
+    connection pooling — it can never leak `app.user_id` from one request into a pooled
+    connection reused by a different request.
+    """
+    async with _app_sessions()() as session:
+        async with session.begin():
+            await session.execute(
+                # bound parameter, not string interpolation — user_id is a UUID we generated
+                # or validated ourselves, but there is no reason to ever risk it.
+                text("SELECT set_config('app.user_id', :uid, true)"),
+                {"uid": str(user_id)},
+            )
+            yield session
+
+
+@asynccontextmanager
+async def unscoped_session() -> AsyncIterator[AsyncSession]:
+    """An `app`-role session with no `app.user_id` set.
+
+    RLS policies default-deny when `current_setting('app.user_id', true)` is NULL, so this sees
+    zero rows of any user-owned table — useful for health checks and anything that only touches
+    non-RLS tables. Prefer `scoped_session` whenever a user is known.
+    """
+    async with _app_sessions()() as session:
+        yield session