bike-app/apps/api/alembic/versions/0001_baseline.py

"""Baseline: identity tables, two runtime DB roles, RLS policies.

This migration creates the schema AND the two application-facing Postgres roles it depends on
(velodrome_app, velodrome_auth) — see db.py and auth/service.py module docstrings for the full
rationale. It runs as a privileged/owner connection (VELODROME_DATABASE_URL_MIGRATE), which is
why it's able to CREATE ROLE and GRANT at all; neither of the two roles it creates could do this
to itself.

Revision ID: 0001
Revises:
Create Date: 2026-09-21
"""

import os
from collections.abc import Sequence

import sqlalchemy as sa
from sqlalchemy.dialects import postgresql as pg

from alembic import op

revision: str = "0001"
down_revision: str | None = None
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None


def _require_password(env_var: str) -> str:
    value = os.environ.get(env_var)
    if not value:
        raise RuntimeError(
            f"{env_var} must be set before running this migration — see deploy/.env.example. "
            "There is no default: these are the passwords for real runtime database roles."
        )
    return value


def _dollar_quoted(password: str) -> str:
    """Safely embed a password literal in DDL.

    CREATE ROLE's PASSWORD clause is DDL, not DML — it does NOT accept bind parameters over the
    wire (Postgres rejects `PASSWORD $1` with a syntax error; ask how we know). Dollar-quoting
    sidesteps manual escaping entirely rather than hand-rolling quote-doubling, which is easy to
    get subtly wrong for a password an operator chose.
    """
    tag = "$velodrome_pw$"
    if tag in password:
        raise RuntimeError(
            f"password must not contain the literal sequence {tag!r} — pick a different one"
        )
    return f"{tag}{password}{tag}"


def upgrade() -> None:
    app_password = _require_password("VELODROME_DB_APP_PASSWORD")
    auth_password = _require_password("VELODROME_DB_AUTH_PASSWORD")

    # --- Runtime roles -------------------------------------------------------------------
    # velodrome_app:  NOBYPASSRLS — every request-scoped query after identity is established.
    # velodrome_auth: BYPASSRLS   — ONLY auth/service.py's pre-identity lookups. See db.py.
    # Roles are cluster-wide in Postgres, not per-database — if this migration ever runs
    # against a second database sharing the same cluster (exactly what a local dev + test setup
    # commonly looks like), a plain CREATE ROLE fails with "role already exists" even though
    # THIS database has never seen the migration before. Postgres has no CREATE ROLE IF NOT
    # EXISTS, so the standard idiom is catching duplicate_object in a DO block. ALTER ROLE
    # afterwards keeps the password in sync with the current env var either way, rather than
    # silently keeping whatever password the role happened to be created with previously.
    op.execute(
        f"""
        DO $$
        BEGIN
            CREATE ROLE velodrome_app LOGIN PASSWORD {_dollar_quoted(app_password)}
                NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS;
        EXCEPTION WHEN duplicate_object THEN
            ALTER ROLE velodrome_app WITH LOGIN PASSWORD {_dollar_quoted(app_password)}
                NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS;
        END
        $$;
        """
    )
    op.execute(
        f"""
        DO $$
        BEGIN
            CREATE ROLE velodrome_auth LOGIN PASSWORD {_dollar_quoted(auth_password)}
                NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION BYPASSRLS;
        EXCEPTION WHEN duplicate_object THEN
            ALTER ROLE velodrome_auth WITH LOGIN PASSWORD {_dollar_quoted(auth_password)}
                NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION BYPASSRLS;
        END
        $$;
        """
    )

    # --- Tables ----------------------------------------------------------------------------
    op.create_table(
        "users",
        sa.Column("id", pg.UUID(as_uuid=True), primary_key=True),
        sa.Column("email", sa.String(320), nullable=False, unique=True),
        sa.Column("display_name", sa.String(200), nullable=False),
        sa.Column("password_hash", sa.Text(), nullable=False),
        sa.Column("role", sa.String(20), nullable=False, server_default="member"),
        sa.Column("timezone", sa.String(64), nullable=False, server_default="UTC"),
        sa.Column("unit_system", sa.String(10), nullable=False, server_default="imperial"),
        sa.Column("is_active", sa.Boolean(), nullable=False, server_default=sa.true()),
        sa.Column(
            "created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()
        ),
    )

    op.create_table(
        "invites",
        sa.Column("id", pg.UUID(as_uuid=True), primary_key=True),
        sa.Column("code_hash", sa.LargeBinary(32), nullable=False, unique=True),
        sa.Column(
            "created_by",
            pg.UUID(as_uuid=True),
            sa.ForeignKey("users.id"),
            nullable=False,
        ),
        sa.Column("email", sa.String(320), nullable=True),
        sa.Column("role", sa.String(20), nullable=False, server_default="member"),
        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
        sa.Column("max_uses", sa.Integer(), nullable=False, server_default="1"),
        sa.Column("used_count", sa.Integer(), nullable=False, server_default="0"),
        sa.Column("revoked_at", sa.DateTime(timezone=True), nullable=True),
    )

    op.create_table(
        "sessions",
        sa.Column("id", pg.UUID(as_uuid=True), primary_key=True),
        sa.Column(
            "user_id",
            pg.UUID(as_uuid=True),
            sa.ForeignKey("users.id", ondelete="CASCADE"),
            nullable=False,
        ),
        sa.Column("token_hash", sa.LargeBinary(32), nullable=False, unique=True),
        sa.Column("client", sa.String(20), nullable=False, server_default="web"),
        sa.Column("user_agent", sa.Text(), nullable=True),
        sa.Column("ip", pg.INET(), nullable=True),
        sa.Column(
            "created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()
        ),
        sa.Column(
            "last_seen_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()
        ),
        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
        sa.Column("revoked_at", sa.DateTime(timezone=True), nullable=True),
    )
    op.create_index("ix_sessions_user_id", "sessions", ["user_id"])

    op.create_table(
        "api_tokens",
        sa.Column("id", pg.UUID(as_uuid=True), primary_key=True),
        sa.Column(
            "user_id",
            pg.UUID(as_uuid=True),
            sa.ForeignKey("users.id", ondelete="CASCADE"),
            nullable=False,
        ),
        sa.Column("name", sa.String(200), nullable=False),
        sa.Column("token_hash", sa.LargeBinary(32), nullable=False, unique=True),
        sa.Column(
            "scopes",
            pg.ARRAY(sa.String()),
            nullable=False,
            server_default="{}",
        ),
        sa.Column("last_used_at", sa.DateTime(timezone=True), nullable=True),
        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=True),
        sa.Column("revoked_at", sa.DateTime(timezone=True), nullable=True),
    )
    op.create_index("ix_api_tokens_user_id", "api_tokens", ["user_id"])

    # --- Grants ------------------------------------------------------------------------------
    # velodrome_auth needs full read/write on these four tables — it's the only thing that ever
    # creates a user, a session, or redeems an invite. velodrome_app needs the same grants
    # because RLS policies (below) restrict WHICH ROWS it sees, not whether the underlying
    # privilege exists — GRANT and POLICY are two independent layers, both required.
    # Deliberately NOT granting TRUNCATE: it's a whole-table operation that RLS cannot filter
    # (Postgres RLS policies do not apply to TRUNCATE at all), so granting it to velodrome_app
    # would let any bug in ordinary request-handling code wipe an entire table in one statement,
    # defeating the isolation these policies exist to provide. Neither runtime role needs it —
    # tests use DELETE for fixture cleanup instead (see tests/conftest.py).
    for table in ("users", "invites", "sessions", "api_tokens"):
        op.execute(f"GRANT SELECT, INSERT, UPDATE, DELETE ON {table} TO velodrome_app")
        op.execute(f"GRANT SELECT, INSERT, UPDATE, DELETE ON {table} TO velodrome_auth")

    # --- Row-level security ------------------------------------------------------------------
    # Policies below apply to velodrome_app only — velodrome_auth has BYPASSRLS and ignores them
    # entirely, by design (see module docstring). current_setting('app.user_id', true) returns
    # NULL when unset, which makes every policy below deny-by-default for an unscoped connection.

    op.execute("ALTER TABLE users ENABLE ROW LEVEL SECURITY")
    op.execute(
        "CREATE POLICY own_row ON users FOR ALL "
        "USING (id = current_setting('app.user_id', true)::uuid) "
        "WITH CHECK (id = current_setting('app.user_id', true)::uuid)"
    )

    op.execute("ALTER TABLE sessions ENABLE ROW LEVEL SECURITY")
    op.execute(
        "CREATE POLICY own_rows ON sessions FOR ALL "
        "USING (user_id = current_setting('app.user_id', true)::uuid) "
        "WITH CHECK (user_id = current_setting('app.user_id', true)::uuid)"
    )

    op.execute("ALTER TABLE api_tokens ENABLE ROW LEVEL SECURITY")
    op.execute(
        "CREATE POLICY own_rows ON api_tokens FOR ALL "
        "USING (user_id = current_setting('app.user_id', true)::uuid) "
        "WITH CHECK (user_id = current_setting('app.user_id', true)::uuid)"
    )

    op.execute("ALTER TABLE invites ENABLE ROW LEVEL SECURITY")
    op.execute(
        "CREATE POLICY own_rows ON invites FOR ALL "
        "USING (created_by = current_setting('app.user_id', true)::uuid) "
        "WITH CHECK (created_by = current_setting('app.user_id', true)::uuid)"
    )


def downgrade() -> None:
    for table in ("invites", "api_tokens", "sessions", "users"):
        op.execute(f"DROP POLICY IF EXISTS own_rows ON {table}")
        op.execute(f"DROP POLICY IF EXISTS own_row ON {table}")

    # Children before parents (FK order).
    op.drop_table("api_tokens")
    op.drop_table("sessions")
    op.drop_table("invites")
    op.drop_table("users")

    # Dropping the tables drops the GRANTs that referenced them; the roles themselves remain
    # until explicitly dropped here.
    op.execute("DROP ROLE IF EXISTS velodrome_app")
    op.execute("DROP ROLE IF EXISTS velodrome_auth")